From GPWiki

Textures

Textures are loaded from image files (BMP, DDS, DIB, JPG, PNG and TGA are supported file formats), and its dimensions must be a power of 2. Usually textures are background images and sprite sheets.

Sprites

Sprites are defined by a portion of a texture file. At least one texture must be defined before a sprite can be defined. hgeSprite is a helper class designed for rendering and manipulating sprites. You can render sprites resized (stretched), tinted another color, rotated, and many other member functions are available.

Defining textures and sprites in the resource manager

To define a texture, give it a name (which will be referred to later) and specify the file name using the filename parameter.

Enter the following in the resource.res file:

Texture background
{
 filename=bg.jpg
}

Make sure you have a file named bg.jpg in the same directory as the executable. You may download a sample image here: Media:HGE_bg.jpg

To define a sprite, give it a name and specify which texture using the texture parameter. An additional parameter is required, rect, that defines the portion of the texture that will be used for the sprite. The rect parameter takes the following format: top-left corner X-coordinate, top-left corner Y-coordinate, width, height For instance, a sprite that starts at the upper left corner in the texture (0, 0), and is 32 pixels square would have rect values of 0, 0, 32, 32. If we want to use the entire image (say, for a background), simply set the width and height to the dimensions of the image.

Enter the following in the resource.res file, below the Texture definition:

Sprite bgSprite
{
 texture=background
 rect=0, 0, 512, 512
}

This assumes the dimensions of the texture file bg.jpg is 512x512 pixels. Adjust the width and height accordingly if it is different. Remember that the texture size must be a power of 2, but the individual sprites do not have to meet this requirement.

Displaying a sprite

To use the hgeSprite class, first include the hgesprite.h header file and declare a pointer to an hgeSprite object.

#include <hgesprite.h>
 
hgeSprite* bgSprite;

We then have to initialize and then render the sprite. The next 2 steps will explain this process.

Step 1: initializing the sprite

In the WinMain function, after HGE is initialized, below the myRes = new hgeResourceManager("resource.res"); statement, add the following:

bgSprite = myRes->GetSprite("bgSprite");

What this does is initialize the background sprite (bgSprite), since bgSprite is the name of the sprite defined in the resource script file. Note that the variable name and the resource name don't have to be identical, but for simplicity reasons we are using the same names.

Step 2: rendering the sprite

In the frame function (FrameFunc), we add the Gfx_BeginScene() and Gfx_EndScene() functions to tell us when to start and stop rendering. The Gfx_Clear() function clears the screen with the specified color (0 is passed in for black).

The Render() function of the hgeSprite class determines where the sprite will be rendered, using X and Y screen coordinates. (0, 0) indicates the top left corner of the screen in this case.

The frame function should look as follows:

bool FrameFunc()
{
hge->Gfx_BeginScene();
hge->Gfx_Clear(0);  //clear the screen, filling it with black
bgSprite->Render(0, 0);  //render the background sprite
hge->Gfx_EndScene(); 
return false;
}

Before you run the program, make sure the FrameFunc returns false, instead of true. This is so the program doesn't shut down immediately after initialization. The user will have to close the window by pressing Alt-F4 or clicking the x in the upper-right.

If you run this program as is, the background image won't cover the entire screen. This is because the image dimensions are 512x512, but the screen size is 800x600 by default. You can solve this by stretching the background sprite.

Change the bgSprite->Render(0, 0); statement to the following:

bgSprite->RenderStretch(0, 0, 800, 600); //render the background sprite stretched 

The RenderStretch() function takes 4 parameters to indicate the location of the sprite: the X and Y screen coordinates of the top-left corner, followed by the X and Y screen coordinates of the bottom-right corner. The sprite is stretched accordingly if the source and destination sizes are different.

Now the background image will be stretched all over the entire screen.

Adding additional sprites

To add more sprites, such as a sprite for the player, it is common to use a sprite sheet. PNG is often used for sprite sheets, since it supports an alpha channel. Add spritesheet.png to the current directory.

You may download the sprite sheet used for this tutorial here: Media:HGE_sheet.png

We need to define another texture for the sprite sheet.

Add the following to the resource.res file:

Texture sheet
{
 filename=sheet.png
}
Sprite playerSprite
{
 texture=sheet
 rect=0, 0, 64, 64
}

This defines the "player" sprite (a green circle in this case). The rect values 0, 0, 64, 64 indicate that the sprite starts at 0, 0 (upper left corner) in the spritesheet texture and is 64 x 64 pixels in size.

At the top of the program, beneath the bgSprite declaration, add:

hgeSprite* playerSprite;

In WinMain, below the bgSprite initialization, add:

playerSprite = myRes->GetSprite("playerSprite");

In the FrameFunc, below the bgSprite rendering, add:

playerSprite->Render(200, 200);  //render the player sprite 

In addition to the background sprite, there will now a green circle drawn at the coordinates (200, 200).

Animations

Animations are a series of sprites displayed in succession. Additional information is needed for animations: the number of frames and how fast the animation is played (its frames per second). hgeAnimation is an HGE helper class for animated sprites. It is derived from the hgeSprite class, so you can use all hgeSprite methods with hgeAnimation. Defining an animation in the resource manager is similar to defining a sprite, except that 3 additional parameters are used.

• frames: The number of frames the animation has. The frames are expected to be placed in the texture consecutively left-to-right, top-to-bottom. If there is no space for the next frame to the right of the current one, the next frame is expected to be found one row lower, starting at x-coordinate 0. The rect parameter specifies the starting point and size of the first frame. All frames must be the same size.
• fps: The speed of the animation in frames per second.

• mode: The playback mode of the animation. Use any of the constants (1 per group) explained below. Separate constants by commas. If you do not use a constant in any of the groups described below, the default value is used.

Group 1. direction: choose one of the following

FORWARD - plays the animation in sequential order

REVERSE - plays the animation in reverse order

The default value is FORWARD.

Group 2. looping: choose one of the following

LOOP - the animation starts over at frame 1 after it is done playing

NOLOOP - the animation is played just once

The default value is LOOP.

Group 3. ping pong: choose one of the following

PINGPONG - use a "ping pong" cycle. Example for a 3-frame animation: 1, 2, 3, 2, 1, 2, 3, 2, 1, ....

NOPINGPONG - do not use "ping pong"

The default value is NOPINGPONG.

This sample animation, a star with numbers inside, is already located on the sprite sheet we defined earlier.

Add the following to the resource.res file:

Animation star
{
 texture=sheet
 rect=0, 64, 64, 64
 frames=3
 fps=1.0
 mode=FORWARD,LOOP
}

This defines an animation consisting of 3 frames which will be played at 1 frame per second. It will be played continuously in forward order. The starting point of the first frame is at (0, 64) in the sprite sheet (beneath the player sprite defined earlier). The second and third frames are placed to the right of the first frame: at (32, 64) and (64, 64) respectively.

To use the hgeAnimation class, first include the hgeanimation.h header file and declare a pointer to an hgeAnimation object.

#include <hgeanim.h>
 
hgeAnimation* star;

Animations do not play automatically, you must call the Play() member function in order to start playing the animation.

In WinMain, beneath the playerSprite initialization, add:

star = myRes->GetAnimation("star");
star->Play();  //start playback of animation 

Notice that we use GetAnimation instead of GetSprite here. This retrieves the animation from the resource script file.

In order for animations to play properly, you must call the Update() function of the animation inside the frame function. The time elapsed since the last call to FrameFunc is passed in. Retrieve this value (dt) with the Timer_GetDelta() function.

At the beginning of FrameFunc, add:

float dt=hge->Timer_GetDelta();  //get the time since the last call to FrameFunc
star->Update(dt);  //update the animation 

Rendering an animation is done the same way as rendering a sprite. In FrameFunc, below the playerSprite rendering, add:

star->Render(400, 300);  //render the animation of a star 

The frame function should now look as follows:

bool FrameFunc()
{
 float dt=hge->Timer_GetDelta();  //get the time since the last call to FrameFunc
 star->Update(dt);  //update the animation
 
 hge->Gfx_BeginScene();
 hge->Gfx_Clear(0);  //clear the screen, filling it with black
 bgSprite->RenderStretch(0, 0, 800, 600);  //render the background sprite stretched
 playerSprite->Render(200, 200);  //render the player sprite
 star->Render(400, 300);  //render the animation of a star
 
 hge->Gfx_EndScene(); 
 
 return false;
}

Run the program and you should see a star with a number inside of it increasing from 1 to 3.

You can download the source file and resource script file for this tutorial here: Tutorial 3 source, Resource script

Next Section: Fonts