Fastgraph 3D Tutorial

A Texture Example

As promised, here is another example. This one is more complicated than the one presented in Chapter 2, so I am not going to post all the source code here. You can download the source code here. This is a C++ program. See figure 4.1 for a screen shot.

There are two data files associated with this program. One of them is game.ini which is an ini file. It is a simple ascii text file that you can edit in any text editor. It looks like this:

[PLAYER]
X=20
Y=5
Z=-20
xAngle=0
yAngle=0
zAngle=0

[WALLCOUNT]
Walls=4

[Wall0000]
X1=-45
X2=45
Y1=45
Y2=45
Texture=2

[Wall0001]
X1=45
X2=45
Y1=-45
Y2=45
Texture=1

[Wall0002]
X1=45
X2=-45
Y1=-45
Y2=-45
Texture=2

[Wall0003]
X1=-45
X2=-45
Y1=-45
Y2=45
Texture=1

Defining Texture Maps

There are four Fastgraph functions you need to know about in order to define texture maps.

fg_tminit(max_textures)

This function initializes the texture map table. The table consists of an array of structures, each with a pointer to a bitmap, the width and height. The number of textures determines the size of the table. Note: the table does not allocate memory for the bitmap. You control that yourself.

int handle = fg_tmdefine(void *texture, int width, int height)

This is the function that adds a texture to the texture map table, and returns the index into that table. We call the index "handle". The first texture will have a handle of 0, the next one will have a handle of 1, etc. Note the bitmap itself is defined as a void pointer. That's because the number of bytes per pixel varies according to the color depth. This array may be a byte, word, or integer depending on whether your program is running in 256 colors, high color or true color. More on that below.

fg_tmselect(handle)

This function determines which texture map you are currently using. Each face may have a different texture, or many faces may use the same texture. Since all this function does is set an integer, it is very fast, so don't hesitate to call it many times in your program.

fg_tmfree(-1)

Call this at the end of your program to delete the texture map table. This function does not free the memory you allocated for the texture bitmaps. Be sure to do that at the end of your program too.

Applying the texture to the surface is simple. You use functions analogous to those you used to draw solid color polygons. First, though, you need to set the rendering mode. Call the fg_3Drenderstate() function like this:

   fg_3Drenderstate(FG_LINEAR_TM);

   fg_3Drenderstate(FG_PERSPECTIVE_TM);

   fg_3Drenderstate(FG_ZBUFFER|FG_ZCLIP|FG_PERSPECTIVE_TM);

Textures Don't Have To Be Square

We try to keep this stuff as simple as possible, but sometimes reality dictates another level of complexity. The reality of texture maps is, they sometimes have to be z clipped. And sometimes you want to break up texture maps into parts, for example if you have narrow adjacent walls and you want your texture map to span both of them. Therefore, you need to pass an array to fg_3Dtexturemap() and fg_3Dtexturemapobject() that contains the vertices of the texture map in clockwise order. For example, if you are using a square 64 x 64 bitmap as in Figure 4.2, the vertices array may look like this:

   static int tmVertices[4][2]= {{0,63},{0,0},{63,0},{63,63}};

Figure 4.2 Texture Map Vertices.

Figure 4.3 Diamond Shaped Texture Map

Applying The Texture

This is easy. To apply a texture to a polygon defined in world space, call this function:

   fg_3Dtexturemap(face[i],tmVertices,nVerts);

   fg_3Dtexturemapobject(face[i],tmVertices,nVerts);

More About Color Depth

As I mentioned before, texture map data is a simple bitmap. Bitmaps, as you know, are defined differently in different color depths. In a 256 color VGA mode, bitmaps are defined to be one byte per pixel. In a 16-bit video mode (high color), bitmaps are 2 bytes per pixel. In a 24-bit or 32-bit video mode (true color), bitmaps are 3 or 4 bytes per pixel. How does Fastgraph know the color depth of the texture bitmap? It relies upon the color depth of the virtual buffers. When you call fg_vbdepth() to establish the color depth of the virtual buffers, you are also establishing the color depth of the textures.

The color depth of the virtual buffers and the texture maps does not have to match the color depth of the display mode. You can define high-color virtual buffers even when your program is running in 256 colors. It will work fine. Fastgraph will do on-the-fly color reduction. This will slow down your program, and you may lose some visual appeal, but the program will work. Similarly, you can define 256 color virtual buffers in a program that is running in high color or true color. For fastest results, make the color depth of the virtual buffers match the color depth of the display. You can auto-detect this with fg_colors(). See the Fastgraph manual for more details.

To capture a bitmap from a virtual buffer to use as a texture, you can use fg_getimage() in a 256 color mode, or fg_getdcb() to get a direct color bitmap in a high color or true color mode.

Putting It All Together

Here is how I used the functions above to create the program shown in Figure 4.1. First, I declare my texture class like this:

class _Texture
{
public:
	class _Texture *next;
	class _Texture *prev;

	byte *TextureMap;       // the bitmap in a Fastgraph dcb format
	int ImageWidth;
	int ImageHeight;
	int ReferenceNumber;    // useful for loading and saving textures
	int Handle;             // used by fg_tmselect();

	_Texture(byte *Map, int width, int height);
	~_Texture();
};

The cubes in my program are made up of faces. I declare my face class like this:

class _Face
{
public:
	_Face(int Verts, double *data);
	int nVerts;
	double *vertData;
	class _Texture *Texture;
};

class _Item
{
private:

public:
	int nFaces;
	_Item(double x, double y, double z, int xF, int yF, int zF);
	~_Item();
	class _Face **Face; // pointers to faces (surfaces);
	double CenterX,CenterY,CenterZ;
	int xAngle,yAngle,zAngle;
	int xFactor,yFactor,zFactor;

	class _Item *prev; // for linked list
	class _Item *next;
};

So, the Item points to the Face and the Face points to the Texture. After everything has been read from the file and initialized, I display a textured face of a cube like this:

   fg_tmselect(Item->Face[i]->Texture->Handle);
   fg_3Dtexturemapobject(Item->Face[i]->vertData,tmVertices,4);