Texture Map Management

The fg_tminit() function initializes Fastgraph's texture map manager. Its only parameter defines the maximum number of textures that will be in use at the same time. For example, suppose you are writing a game that uses 20 textures in one level and then uses 30 different textures in another level. You could pass 30 to fg_tminit() if you free the first 20 textures when they are no longer needed, but if you don't free the textures, you would need to pass 50 to fg_tminit(). Note that fg_tminit() doesn't actually allocate texture map memory, but merely a table that holds the attributes for the specified number of texture maps.

Once you've initialized the texture map manager, you define textures with fg_tmdefine(). This function's first parameter is the name of the array that holds the texture bitmap, and its last two parameters specify the texture width and height in pixels (if using Direct3D, the texture width and height must be powers of two). For 256-color virtual buffers, the texture bitmap is a 256-color bitmap but stored top down rather than bottom up. For direct color virtual buffers, the texture bitmap is a direct color bitmap but is likewise stored top down, not bottom up. This means if you use fg_getimage()fg_getimage or fg_getdcb() to retrieve a texture bitmap, you must call fg_invert() or fg_invdcb() to translate the bitmap to the top down orientation before using it as a texture map. If successful, fg_tmdefine() returns a handle by which the texture map is referenced (a valid handle will be greater than or equal to zero). The possible fg_tmdefine() error return values are -1 (maximum number of textures exceeded) and -2 (cannot make texture available to Direct3D).

If you dynamically allocate memory for the texture bitmap, you can free or reuse the bitmap memory immediately after calling fg_tmdefine() if you are using Direct3D. If you are using DirectX without Direct3D, or if you are using Fastgraph's native libraries, you cannot free or reuse the bitmap memory until you free the texture handle with fg_tmfree().

The fg_tmselect() function makes the specified texture map the active texture map. All Fastgraph functions that draw texture-mapped polygons do so using the active texture map. The fg_tmselect() function's only parameter is a texture map handle returned by fg_tmdefine().

The following code snippet demonstrates how to set up a single 256-color texture map. In this example, we'll extract a 64x64 texture map from a PCX file named MOUSE.PCX.

C/C++:

BYTE Texture[64*64];
int hTM;
fg_tminit(1);
fg_showpcx("MOUSE.PCX",FG_AT_XY);
fg_move(115,80);
fg_getimage(Texture,64,64);
fg_invert(Texture,64,64);
hTM = fg_tmdefine(Texture,64,64);
fg_tmselect(hTM);

Delphi:

Texture : array [1..64*64] of byte;
hTM : integer;;
fg_tminit(1);
fg_showpcx('MOUSE.PCX'+chr(0),FG_AT_XY);
fg_move(115,80);
fg_getimage(Texture,64,64);
fg_invert(Texture,64,64);
hTM := fg_tmdefine(Texture,64,64);
fg_tmselect(hTM);

Visual Basic:

Option Base 0
Dim Texture(64 * 64) As Byte
Dim hTM As Long
Call fg_tminit(1)
Call fg_showpcx(App.Path & "\MOUSE.PCX", FG_AT_XY)
Call fg_move(115, 80)
Call fg_getimage(Texture(0), 64, 64)
Call fg_invert(Texture(0), 64, 64)
hTM = fg_tmdefine(Texture(0), 64, 64)
Call fg_tmselect(hTM)

We first call fg_tminit() to initialize Fastgraph's texture map manager with support for one texture map. We then display the PCX file and use fg_getimage() to retrieve a 256-color bitmap from that image. The bitmap, whose size is 64x64 pixels, is read into the Texture array. Next we use fg_invert() to translate the 64x64 bitmap from the bottom up format used with fg_getimage() to the top down format expected by the texture mapping functions. The fg_tmdefine() function then tells Fastgraph about the texture map and returns a handle, which we pass to fg_tmselect() to make that texture map the active texture map.

If we wanted to modify this example to work with direct color virtual buffers, we would use fg_getdcb() instead of fg_getimage() and fg_invdcb() instead of fg_invert():

C/C++ and Delphi:

fg_getdcb(Texture,64,64);
fg_invdcb(Texture,64,64);

Visual Basic:

Call fg_getdcb(Texture(0), 64, 64)
Call fg_invdcb(Texture(0), 64, 64)

We would also need to increase the size of the Texture array to hold two bytes per pixel if using a high color virtual buffer, or three bytes per pixel if using a true color virtual buffer.

The final texture map management function is fg_tmfree(), which releases the specified texture handle. If you are using Direct3D, fg_tmfree() also releases the DirectDraw surface associated with the texture handle. The fg_tmfree() function expects a single parameter which can be either a texture handle, or a negative value to release all texture handles (and their associated DirectDraw surfaces if using Direct3D). Using fg_tmfree() is required in Direct3D programs, but is optional in all other environments.