Core commands and general program layout

Description

AppGameKit Studio has a set of core commands that deal with aspects such as finding out the width and height of a device, updating the screen, checking the orientation of a screen and finding out what device your application is running on. In this example we'll explore the usage of these commands and also look at a typical layout for an AppGameKit Studio program.

General layout

A typical AppGameKit Studio program will follow this process:

• load resources such as images and sound
• set up sprites to be displayed on screen
• move to the main loop
• within the main loop handle logic for the program and update the screen
• after the main loop save any program settings and clear resources

Here's the process laid out in code:

` load resources


` create sprites


` set up a simple loop
do
    ` handle logic  


    ` update the screen
loop


` save any settings such as state of the game


` clear resources

void app::Begin ( void )
{
    // load resources


    // create sprites
}


void app::Loop ( void )
{
    // handle logic


    // update the screen
}


void app:End ( void )
{
    // save any settings such as state of the game


    // clear resources
}

Core commands

As mentioned previously the core commands within AppGameKit Studio allow you to retrieve information about the device and handle things such as updating the screen. In the code that follows we'll explore a few of these commands in practice.

Our program will do the following:

• find out the width of the device
• find out the height of the device
• retrieve the orientation of the device
• get the name of the device
• update the screen

Width and height of a device

To retrieve the width and height of the device our program runs on we call the commands GetDeviceWidth and GetDeviceHeight. These commands return these values to us and have no parameters:

width = GetDeviceWidth ( )
height = GetDeviceHeight ( )

width = agk::GetDeviceWidth ( );
height = agk::GetDeviceHeight ( );

Orientation

On some platforms the orientation of the screen will be of no particular interest, such as with Microsoft Windows and Mac OS X. The reason for this is that we can expect the orientation to always be the same. On mobile devices this is not necessarily the case. Users may be holding the device in any one of 4 possible orientations e.g. portrait, portrait flipped, landscape and landscape flipped. Retrieving this is useful as it allows you to customise your game dependent on the current orientation. Finding the orientiation is achieved with a simple call to the command GetOrientation. This commands returns 1 for portrait, 2 for portrat flipped, 3 for landscape and 4 for landscape flipped. It has no parameters:

orientation = GetOrientation ( )

agk::orientation = GetOrientation ( );

Device name

There may be instances when it's necessary to determine what platform or device your program is running on. This is useful for cases when you may require some platform specific behaviour. To find out the platform your program is running on call the command GetDeviceName. This command returns a string that will contain one of the following:

• Windows
• iOS
• Mac
• Bada

The command can be called like this:

platform = GetDeviceName ( )

platform = agk::GetDeviceName ( );

Updating the screen

AppGameKit Studio will not display anything on screen until the command Sync is called. To ensure the screen is updated call this command within your main loop.

Full code listing

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

width = GetDeviceWidth ( )
height = GetDeviceHeight ( )


orientation = GetOrientation ( )


platform$ = GetDeviceName ( )


do
    print ( width )
    print ( height )
    print ( orientation )
    print ( platform$ )


    Sync ( )
loop

void app::Begin ( void )
{
    width = agk::GetDeviceWidth ( );
    height = agk::GetDeviceHeight ( );


    orientation = agk::GetOrientation ( );


    platform = agk::GetDeviceName ( );
}


void app::Loop ( void )
{
    agk::Print ( width );
    agk::Print ( height );
    agk::Print ( orientation );
    agk::Print ( platform );


    agk::Sync ( );
}

Conclusion

Several other commands are included with the core section. Please refer to the reference guide for more details.