Getting Started With Marmalade SDK

If you want to create cross-platform solutions quickly, in particular 2D or simple 3D games, I think you should pay your attention to Marmalade SDK.

Marmalade SDK is a cross-platform solution that allows us to write the source code for a game or an application once in C++ and then deploy it to a number of different platforms, including iOS, Android, BlackBerry, Windows Phone, etc.

What you need for this? You will need Microsoft Visual Studio 2008/2010/2012, if you are using windows platform, or the latest Xcode for Mac users, and a licensed copy of the Marmalade SDK.

After purchasing a licence and downloading the SDK (you can do it here, you should install the SDK on your Mac or PC. Then just run Marmalade Hub, in this application you can create project, see the examples or documentation, setup project configurations, deploy the builds, etc.

For creating project the SDK provides a lot of project templates:

And also you can include or exclude frameworks for your project.

After creating the project, MKB file will be created. MKB file is main file of every Marmalade SDK project, it’s a plain text file that describes all project settings. MKB files are used to specify project configuration and deployment configuration. This file is used to generate project files for Visual C++ or Xcode (In the documentation you can found a lot information about MKB format, how to include sub projects, libraries, assets, etc). And after that, when you will have Xcode project files, which will be generated from MKB file from console or Marmalade Hub, you can run Xcode and start working.

Before you begin, you should understand the Marmalade’s architecture. This SDK achieves its cross-platform due to two component parts. It’s a loader and S3E binary system. All the code that you write for your app is compiled and linked into a module(known as an S3E binary) which is executed by a loader program. The S3E binary can therefore be thought of as similar to a Windows dynamic link library (DLL) and indeed on the Windows platform it is actually implemented as such.

The loader is a pre-compiled native binary that acts as an abstraction layer and which provides a consistent programming interface across each supported platform. It takes care of any platform specific requirements including initialisation and termination and handling of events such as user inputs or incoming calls. The loaderwill include implementations written in the platform's native OS language, for example Objective-C on iOS or Java on Android. Your app is written to use the API implemented by the loader and therefore a single S3E binary can be used across all platforms with matching architecture types.

The Marmalade APIs are divided between Marmalade SystemMiddleware, and Extension Development Kit (EDK).

Marmalade System (S3E), it’s a platform abstraction layer, entirely C-based API which provides abstraction from the underlying operating system. This is low level API which allows you to work, for example, with audio, surface interaction, file IO, etc.

The Middleware modules provide higher-level functionality. For example, working with 2D and 3D graphics, animations, resource managing, etc. These modules use C++ object-oriented interfaces, are provided as libraries. There are IwGx (2D and 3D rendering), IwUI (User interface), IwHTTP (interface for performing HTTP and HTTPS requests), IwUitl and IwGeom (provide basic geometry types and utility functions), IwGL (API that performs extra OpenGL ES), IwGxFont (Fonts), etc. This modules you can combine with each other.

Let’s begin to create simple application, which just show the image on center of the screen. First of all, you should add assets to MKB project file, like a that:

assets
{
    (data)
    textures
}

And add image to folder data/textures. After that let’s write the code:

#include "s3e.h"
#include "Iw2D.h"
#include "IwGx.h"

// Main entry point for the application
int main()
{
    // Initialise graphics system(s)
    Iw2DInit();

    // Create an image from a PNG file
    CIw2DImage* image = Iw2DCreateImage("textures/image.png");

    // Set image position
    const float x = (IwGxGetScreenWidth() * 0.5) - (image->GetWidth() * 0.5);
    const float y = (IwGxGetScreenHeight() * 0.5) - (image->GetHeight() * 0.5);
    CIwFVec2 imagePosition = CIwFVec2(x, y);

    // Loop forever, until the user or the OS performs some action to quit the app
    while (!s3eDeviceCheckQuitRequest())
    {
        // Update the input systems
        s3eKeyboardUpdate();
        s3ePointerUpdate();

        // Clear screen with black color
        Iw2DSurfaceClear(0xff000000);
    
        // Draw an image
        Iw2DDrawImage(image, imagePosition);

        // Draws Surface to screen
        Iw2DSurfaceShow();

        // Sleep for 0ms to allow the OS to process events etc.
        s3eDeviceYield(0);
    }

    // Terminate modules being used
    delete image;
    Iw2DTerminate();

    return 0;
}

Compile and run the project, and you can see something like that:

I will not explain the code as it is pretty simple, I want to draw attention, that you will not forget about the fact that you should add new source files or assets directly to MKB file, not in your current IDE.

For deploying project to iOS or Android you should build project with GCC configuration and after that in your Marmalade Hub you can do it.

Marmalade’s developers have created a useful and simple tools for setup project details (such as icons, launcher images, provision profiles, etc) with a huge amount of documentation, and I think for any developer will not make difficulties to create build for different platforms and install it on device.

Happy coding!

Maxim Bilan iOS Developer