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);