Let's make a start on our "Hello World" project. Create a new directory to hold the project files, and then create a file called Hello.mkb in this directory and enter the following into it:

#
# Main MKB file for Hello project
#

# Modules used by this project
subprojects
{
  iwgx
}
 
# The files that make up the project (source, data etc.)
files
{
  [SourceCode]
  (source)

  Main.cpp
}

# Settings to configure the deployment process 
deployments
{
  name="Hello"
  caption="Hello World"
}

The first section of Hello.mkb is the subprojects section, which lists all the additional code modules used by our application. In this instance, a code module is a library that can be added to our project either as a group of C or C++ source files or, alternatively, as pre-compiled, linkable object files accompanying header files. In the previous example, there is just one, iwgx, which is the Marmalade code module responsible for rendering graphics.

All the higher level modules within Marmalade are referenced in this manner, and you can also use this system to create your own modules to enable code re-use across projects. To create a subproject module we use an MKF file, which amounts to a little more than an MKB file with a different file extension! When we add an entry to the subprojects list, the Marmalade makefile builder script will search for a suitable MKF file that describes each subproject. We'll see detailed examples of how to do this later in the book.

The next section is labeled files, and this is where we list all the source code files for our project. It is possible to split your source files up into different directories. To make it easy, you simply put the directory name in brackets ((source) in our example) and then list all the source files in the directory below.

It is also possible to group the related files together into subsections, which we do using square brackets ([SourceCode] in our example). Any source files below this will be added to that section and will then appear in a separate folder in the Visual C++ Solution Explorer. There is no need for the directory and group names to match, and indeed you can have more than one directory in a group if you so wish.

Finally we have the deployments section, which is where various settings are made that control the process of deploying our application to different device types.

In our example we are making two settings. The name setting provides the filename of our final executable and is also used in file and directory names created for us by Marmalade, while caption sets the name that will appear under the application's icon when installed on a device.

Both the aforementioned settings are examples of general settings that apply across all device types, but there are also a great many other settings available, which are specific to particular platforms, such as iOS or Android. A full list of these can be found in the Marmalade Documentation help file that is installed as part of the Marmalade SDK, and we'll also be looking at this in Chapter 8, Supporting a Wide Range of Devices, of this book along with the additional sections of the MKB file that have not yet been shown for this example.

The use of whitespace in the MKB file is pretty much up to your own personal preference. Though most of the Marmalade examples tend to indent entries within blocks, tabs or spaces can also be used.

Comments can also be added using the hash (#) character. Everything after the hash character till the end of the current line is then considered a comment.

We may now use the MKB file for our project but we still can't do anything with it yet, as we've told Marmalade that there is a source file called Main.cpp, which doesn't exist yet. If we were to try and use the MKB file to build the project, we would get an error reported about this missing file, so let's create it.

You will recall that we said that our Main.cpp file would reside in a directory called source in the MKB file, so first create this new subdirectory in the project directory. Now, create a file called Main.cpp in the source directory and enter the following into it:

//---------------------------------------------------------
// Learning Mobile Game Development with Marmalade
// Chapter 1 - Hello
//---------------------------------------------------------
 
// Marmalade SDK includes
#include "IwGx.h"
#include "s3eConfig.h"
#include "s3eDevice.h"
 
//---------------------------------------------------------
// Main entry point
//---------------------------------------------------------
int main()
{
  // Initialise Marmalade modules
  IwGxInit();
 
  // Set a default message, then check the ICF file to see if
  // a proper message has been specified
  char lMessage[S3E_CONFIG_STRING_MAX] = "Hello!";
  s3eConfigGetString("APP", "Message", lMessage);

  // Set screen clear colour to black
  IwGxSetColClear(0, 0, 0, 255);

  // Draw text at double default size
  IwGxPrintSetScale(2);
 
  // Loop until we receive a quit message
  while (!s3eDeviceCheckQuitRequest())
  {
    // Allow device to process its internal events
    s3eDeviceYield(0);
 
    // Clear the screen
    IwGxClear();
 
    // Display our message on screen
    IwGxPrintString(10, 10, lMessage);
 
    // Flush IwGx draw buffers to screen
    IwGxFlush();
 
    // Swap screen double buffer
    IwGxSwapBuffers();
  }
 
  // Terminate Marmalade modules
  IwGxTerminate();

  return 0;
}

The code should be fairly simple to follow, but here is a quick breakdown.

First we reference the include files to allow us to use the parts of Marmalade that are necessary for our application, and then we create our main entry point function main. This is equivalent to the main() function in a standard C or C++ program, except that it takes no parameters as Marmalade does not accept command-line parameters. It's quite hard to specify command-line parameters on mobile devices, so there really isn't any need!

The first thing our application needs to do is initialize Marmalade's rendering module with a call to IwGxInit(), which will initialize the screen and set up standard behavior such as double buffering of the display.

Next we allocate a character buffer that will contain the message that we will be displaying on screen. We initialize it to a default message to make sure that there is something to be shown, but we then use a call to the s3eConfigGetString function to see if another message has been specified in the application's configuration file, which will be explained in more detail shortly.

The following call to IwGxSetColClear sets the desired screen background color to black, and then the call to IwGxPrintSetScale tells Marmalade to display text using its built-in font (which is quite small in size) at double its default resolution.

We now enter our main processing loop that will continue until the s3eDeviceCheckQuitRequest function returns a true value, which will happen if the user quits the application or if the device sends a quit request to the application for any reason.

The first line of our main loop is a call to s3eDeviceYield. This is a very important function that must be called at regular intervals during our application, to allow the device's OS to perform important tasks such as handling events—user inputs, incoming phone calls, and so on. Under most circumstances, a single call to this function in the main loop is sufficient.

The value passed to s3eDeviceYield is the maximum time (in milliseconds) that our application will yield to the OS for. Normally this value is set to zero, which yields long enough for the device to process the events, but will return control to our application as soon as all the events have been processed.

Next, we call IwGxClear to clear the screen and then use IwGxPrintString to display a message on the screen. IwGxFlush causes the Marmalade engine to then process all our drawing requests to yield a final screen image that we can then display to the world using IwGxSwapBuffers.

Finally, outside the main loop, we call IwGxTerminate to shut down Marmalade's rendering engine, and finally return zero to indicate that our application was completed without any errors.

One of the directories created by the MKB file will be named build_hello_vcxx, where the "xx" part is dependent on the version of Visual C++ you are using.

This directory is Marmalade's working directory and is where all the object files created during building are stored. It will also be the home to our deployment packages when it comes to making device builds.

A Visual C++ solution file created from the MKB file also lives in this directory, and while you can use these files to switch between projects, you should never add files or change project settings using the options in the Visual C++ IDE.

The MKB file will also generate a directory called data, and this is where Marmalade requires you to place any files that your application will need to load, such as images, 3D model data, sound files, and others. While you can create this directory and these files yourself, and it will not cause a problem, we might as well let the makefile builder do it for us!

If you take a look inside the data directory, you will see that the build process has also created two more files called app.icf and app.config.txt. These files are used to configure your application and are explained in the following sections.

[APP]
Message      The message we want to display on screen

[APP]
Message="Hello World"

[APP]
{OS=ANDROID}
Message="Hello Android!"
{}
 
{OS=BADA}
Message="Hello Bada!"
{}
 
{OS=IPHONE}
Message="Hello iOS!"
{}

{OS=QNX}
Message="Hello BlackBerry!"
{}
 
{OS=WINDOWS}
Message="Hello Windows!"
{}