Graphics Magician: GMBitmap

The GMBitmap Object

The GMBitmap object contains an image, such as a Windows BMP file. You can also draw and print to a GMBitmap using the functions described in GMMachine, setting the GMMachine's Target to the desired GMBitmap. The FrontBuffer and BackBuffer of GMMachine are actually GMBitmaps.

You can "Draw" one GMBitmap onto another. The GMBitmap that you Draw is overlayed onto the Target background GMBitmap at any x,y coordinate you specify. You can also scale and mirror the GMBitmap that you Draw. Irregularly-shaped images can have a "transparent" color around their edges, so the background shows through.

Drawing one GMBitmap onto another background GMBitmap is the basis of animation. You can program all your animation just by drawing GMBitmaps and using the GMMachine's Flip function. Or you can use a GMSprite, which is basically a GMBitmap on steroids. A GMSprite can contain multiple GMBitmaps and cycle them for animated movement. The GMSprite also has many automatic animation features built into it.

GMBitmap Functions

Drawing Functions (same as in GMMachine)

Novelty Function

Stereograph

Sample Programs

Moving bitmap | Moving bitmap with background | Moving bitmap with moving background
earthandspace.zip (required bitmap files for the above samples)

Constructors

GMBitmap has two constructor formats. Both require parameters. There is no default constructor.

 GMBitmap(GMMachine &Machine, int width, int height);

 GMBitmap(GMMachine &Machine, const char *pFilename);

Both constructors must receive the name of the active GMMachine. Use "Machine", if your GMMachine instance is named "Machine" as recommended.

In the first constructor, send a width and a height. An empty bitmap of that size will be created.

In the second constructor you can send a filename for a BMP file, or the name of a BMP resource. The constructor will load the bitmap from the BMP file and set itself to the size of that bitmap.

Here's a sample, assuming "background.bmp" is a file in the same directory as our EXE file (use the Debug or Release directory in Visual C++).

 GMBitmap Background(Machine,"background.bmp");

bitmap.Draw(int X, int Y [, unsigned int FlipFlag])

This function draws this bitmap onto the current Target bitmap of your GMMachine. Usually this will be the FrontBuffer or BackBuffer. The (x,y) coordinates give the coordinate on the Target surface where the top-left corner of this bitmap should be placed.

The Draw function will clip images that go partially off the screen. That means that it will draw just the part of the image that remains on screen. The DrawFast function does not clip.

FlipFlag lets you draw the image normal (0=default), mirrored left/right (1), mirrored up/down (2), or both (3).

Areas of the bitmap (usually the outside edge of an irregular-shaped object) will be drawn transparent if you have used the Transparent() function.

bitmap.DrawFast(int x, int y)

This function is much faster and just draws your bitmap onto the current Target bitmap of your GMMachine. Usually this will be the FrontBuffer or BackBuffer. The (x,y) coordinates give the coordinates on the Target bitmap where the top-left corner of this bitmap should be placed. This function does not have the scaling, mirroring, or transparency features of Draw().

The DrawFast function does no clipping. If any part of your image goes off the screen area, none of the image is drawn. If you require clipping, you must use the Draw function.

bitmap.Transparent()
bitmap.Transparent(unsigned int RGBcolor)

This tells the GMMachine that this bitmap should be drawn as "transparent". Pixels of the transparent color will not replace the background when rendering this image with the Draw function. Since all bitmaps are rectangular, if your image isn't rectangular you should fill to the edge of your bitmap rectangle with a color you will designate as transparent. Drawing a transparent bitmap will show the background in place of these pixels.

If you leave the parameter list empty, this function automatically uses the top-left pixel as the transparent color. Alternately you can specify which color will be considered transparent.

Remember: transparency only works when rendering with the Draw function. DrawFast, DrawScaled, and DrawScrolled do not pay attention to transparency values.

bitmap.DrawScrolled()
bitmap.DrawTiled()

These two are actually the same function, with two different names that illustrate its uses.

You can use this function if this bitmap is larger than the Target, to show just a portion of this bitmap. DrawScrolled can "wrap" a bitmap around the edges of the screen. This function will be used in conjunction with Scroll or SetScrollValues, described next. By using Scroll each time through your drawing loop you can easily put your background in motion.

This function can also be used to tile a smaller image into a repeated pattern to fill the Target. The "wrapping" effect with small image simply causes it to repeat over and over in all directions. Optionally, you can use Scroll and SetScrollValues to offset the top-left tiled image so that its (0,0) coordinate isn't in the top left corner.

bitmap.Scroll(int DeltaX, int DeltaY[,BOOL WrapX, BOOL WrapY])

This changes the offset for the DrawScrolled function by the amounts in DeltaX and DeltaY. If you do not use the optional WrapX and WrapY parameters, they default to TRUE and the image will wrap around if you keep scrolling in the same direction. If you send FALSE for either WrapX or WrapY, the image will stop when it reaches the edge in either or both of the X-Y directions.

bitmap.SetScrollValues(int OffsetX, int OffsetY)

This sets the scrolling offset to absolute values (with Scroll, you send relative values). OffsetX and OffsetY should be greater or equal to zero and less than the width or height, respectively.

long int bitmap.GetScrollX()
int bitmap.GetScrollY()

These functions return the current offset x and y scroll values. This should correspond to the (x,y) pixel of the bitmap that appears at (0,0) of the target when you use DrawScrolled.

bitmap.DrawScaled(int x, int y, float ScaleFactor)

This renders the bitmap at (x,y) on the Target and scales the image larger or smaller using ScaleFactor. Set ScaleFactor to 2 to draw the bitmap twice as large as normal. Set ScaleFactor to 0.5 to draw it at half size. ScaleFactor is a floating point value, so you can scale to any enlargement or reduction that you want.

DrawScaled does clip the image if it goes off the edges of the Target. DrawScaled does not use transparency.

bitmap.Clear(unsigned int RGBcolor)

This function clears the contents of the bitmap to the specified color. You will usually use the ClearScreen function of the GMMachine instead, because you'll usually be refering to your Machine's Target bitmap.

int bitmap.GetWidth()
int bitmap.GetHeight()

These functions return the width and height of this bitmap.

BOOL bitmap.Save(const char* filename)

This saves the bitmap image as a Windows BMP file. It returns TRUE if successful, and FALSE if there was a problem trying to save. The most common problem is an invalid filename. As with all Graphics Machine functions, if you omit a drive/directory on the filename, the BMP file is saved in the directory where your executable program resides.

Bitmap Drawing Functions

These functions are identical to their counterparts in the GMMachine object, except they require explicit use of the fill and color parameters. (GMMachine actually hands off its drawing function calls to these functions for the appropriate GMBitmap.) It will almost always be simpler to just use the GMMachine drawing functions and the GMMachine's DrawOn function if you want to draw on a bitmap other than the FrontBuffer or BackBuffer.

bitmap.SetPixel(int x, int y, unsigned int RGBcolor)

This sets the pixel at x,y to RGBcolor.

unsigned int bitmap.GetPixel(int x, int y)

Returns the RGBcolor of the pixel at x,y.

void Rectangle(int x1, int y1, int x2, int y2, unsigned int RGBcolor, int fill)

Draws a rectangle with corners at (x1,y1) and (x2,y2) in RGBcolor. The sides are horizontal and vertical. Set the fill parameter to 1 for filled, 0 for outlined.

void Line(int x1, int y1, int x2, int y2, unsigned int RGBcolor)

Draws a line from (x1,y1) to (x2,y2) in RGBcolor.

void Circle(int xc, int yc, int radius, unsigned int RGBcolor, int fill)

Draws a circle with center at (xc,yc), with radius and RGBcolor as given. Set the fill parameter to 1 for filled, 0 for outlined.

void Arc(int xc, int yc, int radius, int startangle, int endangle, unsigned int RGBcolor)

Draws an arc with center at (xc,yc), with the radius and RGBcolor as given, starting at startangle and ending at endangle. Both angles are given in degrees, with 0 degrees to the right, 90 degrees at the top, 180 degrees to the left, and 270 degrees at the bottom.

startangle should be less than endangle. For example, if you want the right half of a circle, set startangle to 90 and endangle to 270. If you want the left half of a circle, set startangle to -90 and endangle to 90 (or set startangle to 270 and endangle to 450).

void PieSlice(int xc, int yc, int radius, int startangle, int endangle, unsigned int RGBcolor, int fill)

Draws a pie slice (an arc with endpoints connected to the circle's center) with center at (xc,yc), with the radius and RGBcolor as given, starting at startangle and ending at endangle. Both angles are given in the same manner as in the Arc function.

void Ellipse(int xf1, int yf1, int xf2, int yf2, int radius, unsigned int RGBcolor, int fill)

Draws a filled ellipse with focal points (xf1,yf1) and (xf2,yf2), with radius and RGBcolor as given.

NOTE: the fill parameter does nothing for now. As is, this function only draws filled ellipses. The fill parameter is there as a placeholder when an "outlined" option becomes available in the future. Use 1 (filled) as the value for the fill parameter for future compatibility.

void TriFill(int x1, int y1, int x2, int y2, int x3, int y3, unsigned int RGBcolor)

A fast filled triangle with (x1,y1), (x2,y2), and (x3,y3) as the vertices. The triangle is filled with the color given. Written for speed, this function does not work when drawing to the FrontBuffer. It only works with offscreen drawing.

BOOL LoadBitmap(const char* filename)

Loads a bitmap from a file to this GMBitmap. Send a filename to this function, or a string name of a resource in a resource file. It returns a boolean value of TRUE or FALSE, depending on whether the function was successful.