Images

Overview

This guide provides an overview of images and some of their associated commands.

What formats are supported?

AppGameKit Studio supports loading of PNG, JPG and (on some platforms) BMP image formats. For transparent images only PNG is supported.

How do I load an image?

An image can be loaded by calling the LoadImage command:

LoadImage ( id, file )
id = LoadImage ( file )

void LoadImage ( UINT id, const char* sImageFilename );
UINT LoadImage ( const char* sImageFilename );

It's possible to load an image like this, where an ID number of 1 is specified and the image "myImage.png" is to be loaded:

LoadImage ( 1, "myImage.png" )

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

Alternatively it can be handled like this, where the variable image stores the ID number:

image = LoadImage ( "myImage.png" )

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

The difference being that in the first example the ID number is fixed as 1, and from that point onwards if you want to do something with that image you must use ID 1. The other example has the ID number stored in the variable image, meaning it's not necessary to know the ID number, you simply use the variable image when requiring the ID number in future. Please note that ID numbers are unique for a command set. Therefore it's feasible to have a sprite ID of 1 along with an image ID of 1.

Where do images need to be stored?

When using Tier 1 all of your data needs to be placed in a folder named media. This becomes your root folder. For example, if you place image.jpg within the media folder you do not need to specify the media folder when loading e.g.

image = LoadImage ( "image.jpg" )

When using a Tier 2 application the root directory is the same directory as your executable.

How do I delete an image?

Due to limited resources on devices it may be necessary to delete previously loaded images and free up available memory. To delete an image call the command DeleteImage:

DeleteImage ( id )

void DeleteImage ( UINT id );

This command only requires the ID number of the image you want to delete.

Here's an example of loading an image into ID slot 1 and then deleting it:

LoadImage ( 1, "myImage.png" )
DeleteImage ( 1 )

agk::LoadImage ( 1, "myImage.png" );
agk::DeleteImage ( 1 );

How can I check if an image exists?

The command GetImageExists can be used to determine whether an image with the specified ID number exists:

exists = GetImageExists ( id )

UINT GetImageExists ( UINT id );

As an example, this code loads an image into ID slot 1 and then checks whether it exists:

LoadImage ( 1, "myImage.png" )


if GetImageExists ( 1 ) = 1
    ' the image exists
endif

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


if ( agk::GetImageExists ( 1 ) == 1 )
{
    // the image exists
}

How can I find out the size of an image?

Commands have been provided to find out the width and height of an image:

width = GetImageWidth ( id )
height = GetImageHeight ( id )

UINT GetImageWidth ( UINT id );
UINT GetImageHeight ( UINT id );

This example loads an image into ID slot 1 and then retrieves its width and height:

LoadImage ( 1, "myImage.png" )
width = GetImageWidth ( 1 )
height = GetImageHeight ( 1 )

agk::LoadImage ( 1, "myImage.png" );
width = agk::GetImageWidth ( 1 );
height = agk::GetImageHeight ( 1 );