Sprites using the percentage system

Description

In this example we're going to place a sprite on screen using the approach of the percentage based system.

Overview

The process involved is as follows:

• load an image
• create a sprite
• setting the size of a sprite
• main loop

Load an image

In this next step we're going to load an image. This is achieved by calling the command LoadImage. This command either accepts or returns an ID number, followed by a filename. Let's see this in practice:

image = LoadImage ( "blue.png" )

image = agk::LoadImage ( "blue.png" );

This line calls LoadImage passing in the filename "blue.png", it then returns an ID number which gets saved in the variable image. This ID number is now treated as a handle to our image and can be used later on when referring to it.

An alternative option is to specify the ID number manually e.g.

LoadImage ( 1, "blue.png" )

agk::LoadImage ( 1, "blue.png" );

Creating a sprite

Now that we have an image loaded into memory we're ready to create a sprite and attach this image to it. This is achieved by calling the command CreateSprite. This command either accepts or returns an ID number followed by an ID number of the image you wish to attach to the sprite:

sprite = CreateSprite ( image )

sprite = agk::CreateSprite ( image );

Here we call CreateSprite passing in an ID number for our image and returning an ID number for the sprite. We're effectively saying create a sprite, attach this image to it and give us back an ID number for this sprite. This ID number for the sprite can be stored for use later on when dealing with sprite properties, for example.

Setting the size of a sprite

When using the percentage based system it's necessary to specify the size of your sprite. The reason for this is that when you load an image and attach it to the sprite, the system does not know how big your sprite is going to be in relation to the screen. Therefore when using the percentage based system you always need to specify the size of your sprite. This is handled by the command SetSpriteSize. This command's parameters are an ID number, width of the sprite and height of the sprite. If you wanted to set our previously created sprite to take up 50% of the screens width and 50% of the screens height we would call this:

SetSpriteSize ( sprite, 50, 50 )

agk::SetSpriteSize ( sprite, 50, 50 );

Given that our image is not square (it has dimensions of 54 x 50) the result may not be totally as expected. Our sprite will look slightly squashed. The solution for this is quite simple - let AppGameKit Studio determine the correct proportions for us. This is achieved by specifying either the width or the height and then -1 for the unspecified parameter e.g.

SetSpriteSize ( sprite, 50, -1 )

agk::SetSpriteSize ( sprite, 50, -1 );

So here we're saying we want our sprite to take up 50% of the screen on the X axis and then letting AppGameKit Studio decide the size on the Y axis in order to ensure it’s displayed correctly.

Main Loop

Up to this point we have loaded an image and created a sprite that uses this image and set its size. We’re nearly ready to run our application and see the results. Prior to this we need to ensure one more thing - in our main loop we must call Sync to ensure the screen gets updated and its contents drawn. The function Sync takes no parameters and can be called in your main loop like this:

do
    sync ( )
loop

void app::Loop ( void )
{
    agk::Sync ( );
}

Full code listing

Everything is now in place. Here's the final code for our program:

image = LoadImage ( "blue.png" )


sprite = CreateSprite ( image )


SetSpriteSize ( sprite, 50, -1 )


do
    Sync ( )
loop

void app::Begin ( void )
{
    agk::image = LoadImage ( "blue.png" );


    agk::sprite = CreateSprite ( image );


    agk::SetSpriteSize ( sprite, 50, -1 );
}


void app::Loop ( void )
{
    agk::Sync ( );
}

Conclusion

We're now all set to run our application and see the results on screen.

Understanding how sprite sizes work is important for the percentage based system. It's advisable to take time loading in different images and experimenting with the width and height parameters. Doing this will help you to understand the relationship between the original image width and height and the results on screen.