Chapter 3: Tutorials

In this chapter there are tutorials on the basic use of the various parts of AgateLib.

Audio

Audio tutorial goes here.

Drawing

Basic drawing primitive shapes goes here.

Fonts

Of course in any game you want to be able to write text to the display. Agate provides a painless way of loading fonts:

  1. FontSurface font = new FontSurface("Arial", 12);

The above line of code creates a font object using 12-point Arial.

Drawing text to the screen is simple, using the DrawText function

  1. font.DrawText(10, 20, "This is my text");

FontSurfaces also have the same Alpha, Color, ScaleWidth, and ScaleHeight properties that Surfaces and Sprites have.

Input

Mouse Input

Input from the mouse can be obtained in an easy manner, through the use of the static Mouse class. The following three methods get the position of the mouse cursor.

  1. Point mousePosition = Mouse.Position;
  2.  int X = Mouse.X;
  3.  int Y = Mouse.Y;

The above properties have set methods also, so the mouse position can be changed. You can check them every frame, or if you prefer you can attach to the Mouse.MouseMove event, as in the next example.

  1. Mouse.MouseMove += new InputEventHandler(myHandler);

The Mouse also has a MouseDown and a MouseUp event that you can attach to in order to deal with mouse clicks.

Keyboard Input

Input from the keyboard is obtained in a similar manner to mouse input, through the static Keyboard class. You can check the state of any key with the Keys member, as in the following example.

  1. if (Keyboard.Keys[KeyCode.Enter]) // User pressed enter
  2. if (Keyboard.Keys[KeyCode.F5])  // User pressed F5

You can also attach to the Keyboard.KeyDown and Keyboard.KeyUp events.

Resources

Tutorials on creating / loading / using resources go here.

Serialization

AgateLib contains two serializers.

Sprites

AgateLib has a sprite class which can be used to create animated sprites. In order to use sprites, you need to add the following using directive to the top of any file you wish to use sprites:

  1. using AgateLib.Sprites;

Loading images into a sprite

Managing animations where you have several frames of animation can be tedious. Luckily, AgateLib has a fairly robust Sprite class which will do all of it for you. There are several ways to load up a sprite and add frames to it. The simplest follows:

  1. Sprite mySprite = new Sprite("sprite.png", 32, 32);
  2. Sprite mySprite = new Sprite("sprite.png", new Size(32, 32));

The above two function calls are equivalent. You specify a file, and the sprite automatically cuts out frames of the size passed (32x32 in the above example). It will automatically ignore frames which are blank.

If you have frames of animation in more than one file, you can add them after creating a sprite in this manner:

  1. mySprite.AddFrames("sprite2.png"); // loads frames from another file
  2. mySprite.AddFrames(mySurface);     // loads frames from a surface

Drawing with a sprite

Sprites have all the same drawing functions that Surfaces do. They also have a number of the same properties.

Animating sprites

Surfaces

Loading images

Loading an image to display on the screen is easy. Simply create a surface object and tell it what file to load.

  1. Surface mySurface = new Surface("myfile.png");

Png files are recommended, because they are small and they support per-pixel transparency, at 256 different levels for each pixel. Png transparencies are supported by AgateLib.

Drawing with surfaces

Surfaces have many properties that affect how they are drawn. The simplest way to draw on the screen is
to call one of the surface's Draw methods. The line of code below will draw the surface at the point x = 20 and y = 30.

  1. mySurface.Draw(20, 30);

By default, the above line tells Agate to draw with the point (20, 30) as the upper-left point of the surface. However, this can be changed easily. If you wanted to issue the above command and have (20, 30) be for example, the center of the surface, then you would need to first set the surface's DisplayAlignment property.

  1. mySurface.DisplayAlignment = Origin.Center;

Scaling Surfaces

This is very convenient if you have surfaces which you want to stretch as part of an animation. The above line will cause draw points to be interpreted as the center of the image, taking into account scaling. Speaking of scaling, it is very simple to scale a surface. The following code lists several methods to scale a surface.

  1. mySurface.SetScale(2.0, 1.0);  // stretchs it twice as wide in the horizontal direction
  2. mySurface.ScaleWidth = 2.0;    // sets it to stretch twice as wide in the horizontal direction
  3.                                 // with no change in how the vertical scaling is done.
  4. mySurface.ScaleHeight = 1.5;   // sets vertical scaling to 50% more than normal.
  5.  
  6. mySurface.DisplayWidth = 100;  // calculates the scale properties so that the width is 100 pixels.

Color and Transparency

You can make a surface partially or completely transparent by using its alpha property. An alpha value of 1.0 is fully opaque, 0.0 is fully transparent.

  1. mySurface.Alpha = 0.5;
  2. mySurface.Draw(20, 30);

Surfaces can also be colored, with their Color property. Following are several examples showing how to set the color of a surface.

  1. mySurface.Color = Color.Red;
  2.  mySurface.Color = Color.FromArgb(100, 20, 20); // this is 100 red, 20 green, and 20 blue
  3.  mySurface.Color = Color.FromArgb(128, 100, 20, 20); // the first value is the alpha value, then r, g, b.

Notice that the Color structure has an alpha channel. Setting the Color property of a surface will overwrite its Alpha value. Surface colors are multiplicitive in effect, so the effect is much greater on images which are lighter in color than images which are darker in color.

Rotations

Surfaces can also be rotated. Rotations can be specified in either radians or degrees, and positive numbers indicate rotating in the counter-clockwise (CCW) direction.

  1. mySurface.RotationAngle = Math.Pi / 4; // rotates the surface by π/4 radians (45 degrees) CCW.
  2. mySurface.RotationAngleDegrees = 90;  // rotates the surface by 90 degrees CCW.
  3. mySurface.RotationAngleDegrees = -45; // rotates the surface by 45 degrees CW.
  4. mySurface.RotationAngleDegrees += 1;  // increases the surface's rotation by 1 degree.  This syntax is useful for animations.

Just like you can change the display alignment of a surface, you can also change its center of rotation. By default it is in the center of the surface.

  1. mySurface.RotationCenter = Origin.TopLeft;  // rotate about top left point
  2. mySurface.RotationCenter = Origin.CenterLeft; // rotate about point halfway down the left edge.

An arbitrary rotation center cannot be specified in this way. If you want to make a rotation around an arbitrary point, there is a Draw overload which takes a rotation center point. The following line of code draws the surface at the point (20, 30) rotated around the point (40, 50).

  1. mySurface.Draw(20.0f, 30.0f, 40.0f, 50.0f);