Airplay SDK

Airplay SDK 4.0 Documentation

Welcome to Airplay. This guide is designed to help you learn and get the most out of the Airplay SDK.

  • Introduction
  • Whats New
  • How to Use this Documentation
  • Installation and Licensing
  • Getting Started
  • User Guide
  • Deploying to Devices
  • Airplay Programmer Tools Reference
  • Airplay Art Tools Reference
  • Airplay API Reference
  • Whitepapers
(c) 2009 Ideaworks Labs. All rights reserved.


Airplay SDK: Introduction

Airplay SDK > Introduction >

Introduction to Airplay

Airplay SDK offers a complete solution for the creation of high-performance, cross-platform, native (C/C++) mobile applications.

Airplay SDK will enable you to:

  • Write one application that runs on all iPhone, Android, Symbian, Windows Mobile and BREW devices
  • Build a "single application binary" - native CPU instructions that run identically across all supported platforms and devices, defeating fragmentation
  • Write standard C/C++ code, with full support for all standard libraries and language features
  • Use best-in-class IDEs such as Microsoft Visual C++
  • Compile for Windows (x86) and test in powerful desktop debugging environments
  • Compile for ARM, using GCC or RVCT compilers, without leaving the IDE
  • Test and debug actual ARM code on the desktop, at source or disassembly level, without having to deploy to device
  • Deploy your application as a standard OS installer package, for all supported operating systems, using a single click
  • Build rich 2D and 3D applications using powerful tools and graphics libraries
  • Support software rendering, OpenGL ES 1.x and OpenGL ES 2.0 from within a single application, without rewriting rendering code

Read the Installation and Licensing documentation to help you get Airplay SDK up and running quickly.

It is recommended that you work through the Airplay User Guide for a thorough introduction to the main features and benefits of Airplay SDK.


Airplay SDK: What's New

Airplay SDK > What's New >

What's New

This section outlines key new features appearing in this release of Airplay SDK. For a complete list of changes, see the Release Notes.

Android support

Airplay SDK now supports deployment of native applications to Android. Just check the "Android" box in the OS selection dialog of the Deployment Tool.

Android support is "Beta" in Airplay SDK 4.0. This means that the feature is working and well tested, but some bugs remain. Known issues are:

  • Application may crash if OpenGL ES APIs are used and the device is physically reoriented rapidly a few times in succession
  • s3eVideo API is not yet supported
  • s3eCamera API is not yet supported

UI framework (IwUI module)

Airplay SDK now contains a high-level UI framework. We spent a long time looking at UI frameworks such as Apple's 'UIKit' and Nokia's 'Qt'. We learned a lot from these. We then went away and designed our own UI framework that built on the best ideas we'd seen, and tried to replace what was missing and fix what was broken.

IwUI is "Beta" in Airplay SDK 4.0. This means that the module is working and well tested, but some bugs remain, and we reserve the right to change some APIs. In particular, the IwUI Builder Tool is still in the early stages of development, and will be hugely improved in the next release of the Airplay SDK.

Known issues are:

  • Scale & rotation of elements not fully supported
  • Element transform does not effect clipping rectangle
  • Unable to scroll IwUIDynamicPopulation list using keypad, only via touch
  • ScrollableView & TextInput interfaces are likely to change
  • Airplay Studio UI Builder: Editing of softkeyboard not supported
  • Airplay Studio UI Builder: Editing 'OnButtonClick' and other slots only supported as strings
  • Airplay Studio UI Builder: Minimal stylesheet support
  • Airplay Studio UI Builder: No editing of CIwUILayoutItemContainer: left/right/up/down
  • Airplay Studio UI Builder: 'Make project from group' - projects that use stylesheets may not display correctly
  • Airplay Studio UI Builder: CIwUILayoutForm is not yet supported

New licensing system

The technical infrastructure, terms and conditions, and pricing model for Airplay SDK are all changing from version 4.0. Customers using previous versions of Airplay SDK should not experience any difficulties in upgrading to Airplay SDK 4.0, as the previous licensing database has been moved over to the new one. If you experience difficulties, please use contact us through your existing support channels.

Support for Open Source modules

Airplay SDK's code building process includes support for dynamically downloading Open Source code modules hosted by Ideaworks Labs. The first time a particular module is referenced by your makefile, the Open Source code is pulled down from our server, and copied into your Airplay SDK installation. From that point on, the source code is simply compiled as part of your application.

Currently, Ideaworks Labs hosts the following Open Source modules, all of which are compatible with Airplay applications:

  • libjpeg
  • libxml
  • lua
  • ode (Open Dynamics Engine)
  • sqlite3
  • tinyxml
  • zlib

Removal of ARM tools

Airplay SDK fully supports ARM's RVCT compiler. Previously, we bundled a version of this compiler together with an evaluation licence. We have had to remove the bundled compiler and evaluation licence for Airplay SDK 4.0.

Similarly, previously we bundled ARM's RTSM desktop emulator, together with an evaluation licence. We have had to remove the bundled RTSM emulator and evaluation licence for Airplay SDK 4.0.

Note that Airplay SDK 4.0 is integrated with the QEMU ARM desktop emulator, so full testing and debugging of the ARM binary on the desktop is still possible (and indeed an extremely valuable feature).

OpenGL ES improvements

We've made many improvements to the support for OpenGL ES 1.x and OpenGL ES 2.0. Here are just some of them:

  • Widespread improvement in OpenGL ES 2.0 support including per instance parameters, extra uniforms, etc.
  • Automatic use of VBOs
  • PVRTC compression for non-square textures. PVRTC textures are now compressed even if not square. IwGx will tile them up to square and scale incoming UVs
  • ETC compression is now supported

IwGx and IwGraphics improvements

We've made some improvements to the core drawing interface, and the 3D model rendering, including:

  • Default rasterisation is now HW to reflect the march of technology
  • Gamma is now supported in HW rasterisation modes
  • Models can be conditioned in strip major order for optimal vertex cache usage

Visual Studio type decoration

Airplay SDK now provides the file "../docs/airplay_autoexp.dat" for type decoration in Visual Studio. It should be added appended manually to Visual Studio's autoexp.dat file.


Airplay SDK: How to Use This Documentation

Airplay SDK > How to Use This Documentation >

How to Use This Documentation

This section explains the different parts of the documentation and the best order for you to read it to gain the most understanding. It also includes notes on other sections that are related to that particular topic.

Getting Started

This section demonstrates how to get up and running with Airplay in a few easy steps. It takes you through the process of building a simple Airplay project, testing it in the Windows Simulator and ARM Emulator, and finally deploying the build to a device.

>> Getting Started

User Guide

If you are new to Airplay, the User Guide provides a starting point for learning about the SDK. The User Guide provides a full introduction, describing what the system can do and detailing its various components and key concepts.

The guide introduce the process of developing applications using Airplay by walking through the set up of a project from scratch, the building of an application, the inclusion of art assets, and finally the deployment of the application to devices. Tutorials and game examples are provided to introduce more advanced topics.

>> User Guide

Deploying to Devices

The deployment process is independent of the application build process. This section provides a full reference for deployment, describing how to deploy an application to all the supported devices using the Airplay System Deployment Tool, plus a reference for all the available options.

>> Deploying to Devices

Programmer Tools Reference

This section provides a detailed reference for using the programming-related tools that come with the SDK. This includes full settings listings for the MKB and ICF file systems that are used to configure Airplay applications and build environments. You should read the introductions to these tools in the User Guide first.

>> Airplay Programmer Tools Reference

Art Tools Documentation

If you are only concerned with the creation of art assets and their preparation for application integration, you should refer to the Airplay Art Tools Reference, which provides thorough documentation for each tool.

>> Airplay Art Tools Reference

API Documentation

This document provides a complete reference for the Airplay API set. For each API module it provides an introductory overview, a detailed reference section and a set of complete code listings for any related examples that come with the SDK.

The APIs are built in layers, and it is easiest to work from bottom layer to top in order to gain a proper understanding of the API set. See the API Reference Overview for more information.

>> Airplay API Reference

Whitepapers

This section lists the whitepapers supplied with the SDK. These are intended as supplemental reading and cover a wide range of topics related to Airplay.

Documentation Conventions

The table below describes the conventions used throughout the SDK documentation:

Convention | Description
Italics | Italics are used to indicate the titles of documents, file names and paths, and to indicate emphasis. For example, Airplay SDK Documentation
Mono-spaced
font 		Mono-spaced font indicates commands or code.
Mono-spaced
italic font 		Mono-spaced italic font indicates a place holder for an item that you should replace.
Bold | Bold text is used to indicate application names and also interface elements that you may have to interact with.
UPPERCASE | Uppercase text is used to indicate Airplay file types. For example, GEO refers to a *.geo file.


Airplay SDK: Installation and Licensing

Airplay SDK > Installation and Licensing >

Installation and Licensing

The Installation and Licensing guide contains all the information required to install and setup Airplay, including listings of any required and supported third-party software.

Also included here are the License Agreement and Copyright Notices which must be read before using the SDK.

A full list of changes to the SDK since the previous release is provided within the Release Notes.

  • System Requirements
  • Installation
  • Release Notes
  • Licence Agreement
  • Copyright Information


Airplay SDK: System Requirements

Airplay SDK > Installation and Licensing > System Requirements >

System Requirements

The requirements for installing and running Airplay are listed below.

Airplay supports integration with a selection of art applications and development environments which are also listed here.

Operating System

  • Microsoft Windows XP Service Pack 2 (or above)
  • or Microsoft Vista (admin user only)
  • Internet connection (in order to acquire SDK license)
  • iPhone Deployment requires access to an Apple Mac in order to perform application signing

Note: If using Windows Vista, you must be running as the administrator user and have full access permissions in order to install Airplay.

Deployment Environment

Airplay supports deployment to the following platforms:

  • iPhone & iPod Touch
  • Android
  • BREW
  • Windows Mobile
  • N-Gage (Symbian 9)
  • Symbian 9 s60
  • Symbian 9 UIQ3
  • Symbian 8
  • Symbian 7

Additional SDKs are not required for compiling applications. However, some platforms require additional 3rd party tools and certificates in order to deploy to device or to support advanced features. For a detailed list of requirements for each supported platform see Deploying To Devices > Platform-Specific Deployment Guides.

Development Environments

The recommended development environment is Visual C++. This is widely considered to be the most advanced and efficient development environment available (full support for both code and data breakpoints, edit-and-continue and fast compilation).

The following IDEs are supported:

  • Microsoft Visual C++ 6
  • Microsoft Visual C++ .NET 2003
  • Microsoft Visual Studio 2005
  • Microsoft Visual Studio 2008

Building of projects using the command line is supported using SCons (installed with the SDK).

3D Modelling Packages

Airplay supports exporting assets from a number of 3rd party 3D modelling packages through the Airplay Studio Exporters.

The following modelling packages are supported:

  • 3D Studio Max 8
  • 3D Studio Max 9
  • 3D Studio Max 2008
  • 3D Studio Max 2009
  • 3D Studio Max 2010
  • Maya 7
  • Maya 8
  • Maya 8.5
  • Maya 2008
  • Maya 2009
  • Maya 2010


Airplay SDK: Installation

Airplay SDK > Installation and Licensing > Installation >

Installation

The Airplay SDK is installed by double clicking on the executable installer file, which will be named "Airplay-SDK-<version>-<revision>.exe", where <version> is the version number of the SDK and <revision> is the revision build number. This file will open the SDK Setup Wizard which will guide you through the installation process.

Note that full admin user privileges are required in order to install Airplay on Windows Vista. To do this, right-click on the installer and select Run as administrator or configure the installer application to run with admin privileges using Windows' User Account Control settings.

Airplay Studio Exporters

Airplay supports exporting assets from a number of 3rd party 3D modelling packages through the Airplay Studio Exporters. You will be prompted to install these during the SDK installation. You can also install Exporters after installation using the LaunchPad Application ("Airplay SDK LaunchPad" from the Windows Start Menu). Select Advanced Mode, then click the Install Exporters tab. Change the install path if necessary and hit the Install button for each Application you wish to install an exporter for.

SDK Configuration

During the the SDK installation process the Airplay System Configuration Utility will be run. This tool is used for specifying the S3E base directory and the Default build environment as well as other global SDK settings.

A custom S3E base installation directory can be specified to allow for multiple Airplay SDK installations. Generally it should be left at the default value, which will be the directory the SDK was just installed to.

The 'Default build environment' is used to specify the installed programming IDE preferred by the developer. When the developer clicks an Airplay project file (.mkb), this setting is queried and the relevant IDE workspace file is automatically generated.

The configuration can be reset at any point by running the Configuration Utility again. The utility is available from the Airplay SDK folder under the Windows Start > Programs menu. It is also available by opening "C:\Airplay SDK\<version>\s3e\bin\s3eConfig.exe" (if the default location was installed to). For more information on the Configuration Utility, see Airplay SDK > Airplay Programmer Tools Reference > Airplay System Configuration Utility in AirplaySDK.chm.

Default Installation Location

The Airplay SDK is by default installed in the following location: "C:\Airplay SDK\<version>"

Folders Installed with the SDK

The following folders are installed as part of the SDK:

  • docs: This folder contains all of the Airplay SDK documentation, including user manuals and whitepapers.
  • examples: This folder contains the example applications and their code, which demonstrate correct use of the SDK.
  • modules: This folder contains all Airplay Studio header files and runtime libraries.
  • s3e: This folder contains all Airplay System header files and runtime libraries.
  • tools: This folder contains all the Airplay Studio tools, the DZip compression utility, the Deployment Tool, and the SDK LaunchPad.

Uninstalling

The Airplay SDK can be installed by clicking Programs > Airplay SDK > Uninstall under the Windows Start menu (or by double clicking 'unins000.exe' in the SDK root installation folder).


Airplay SDK: Release Notes

Airplay SDK > Installation and Licensing > Release Notes >

Release Notes

Contents

The Airplay SDK Release Notes contain the following sections:

  • Change List SDK
  • Change List S3E
  • Known Issues

Change List SDK

Change log for SDK features between 3.7 and 4.0
===============================================

Android Support Added
---------------------

Deploying airplay applications to android (via an .apk) is now supported.
The deployment tool also support installiing and runing on android devices directly from the GUI.

New Module: IwUI
----------------

IwUI is a new module for building rich user interfaces that is fully integrated with the Airplay Studio asset pipeline.

Improvements to Airplay Studio
------------------------------

Airplay SDK 4.0 includes widespread improvements to Airplay Studio:
OpenGL ES 2.x support is extended with instance parameters and many new standard uniforms.
VBOs are automatically used.
HW rasterisation is now the default rendering mode.
PVRTC compression for non-square textures. PVRTC textures are now compressed even if not square. IwGx will tile them up to square and scale incoming uvs.
Support for ETC compression has been added.
Gamma is now supported in HW rasterisation modes.
Various new examples have been added.
Single-boned animations can now be played without creating a single-boned skeleton in data. Models can be conditioned in strip major order for optimal vertex cache usage.

IDE Integration
---------------

Airplay SDK includes docs/airplay_autoexp.dat for type decoration in Visual Studio. It should be added manually to Visual Studio's autoexp.dat.

Change log for SDK features between 3.6 and 3.7
===============================================

iPhone 3.0 Features Exposed
---------------------------

Many of the iPhone 3.0 features have been exposed through the several S3E extensions:

s3eExt_MicroTransaction.h s3eExt_IPhone.h s3eExt_IPhoneGameKit.h s3eExt_EMail.h s3eExt_BackgroundMusic.h

These extensions are only available when deploying to iPhone 3.0.

Documentation Updated
---------------------

The existing documentation has been reordered and combined into a single chm file. Existing PDF documents, including DevelopingInAirplay.pdf and Ideaworks Labs-authored whitepapers have been merged into this main document.
All content has been reviewed and largely re-written.

New sections added: Installation and Licensing, Getting Started, User Guide, Airplay Programmer Tools Reference.
All API listings are now in a sub-document called Airplay API Reference.
AirplayStudioTools.chm has been replaced by the Airplay Art Tools sub-document.

Specular Lighting in IwGx
-------------------------

An OpenGL ES 1.x-equivalent specular component is now supported in scene lighting.

IwGxSurface added for offscreen rendering
-----------------------------------------

Cross-platform (including SW) offscreen rendering is now supported on a large range of target devices through CIwGxSurface. Note that performance varies significantly between devices.

CPU Exceptions Handling Support
-------------------------------

The S3E loader now supports CPU exception handling on platforms where the underlying OS supports this. This means it is possible for an application the crash and for the loader to continue to run and launch other applications. When an application crashes subsequent applications can see which exception cased the crash use S3E_DEVICE_EXIT_SIGNAL.

Accelerometer Support Added
---------------------------

Airplay System now support accelerometer input vis the s3eAccelerometer.h interface. Accelerometer support is currently available for iPhone, Symbian9 and NGage 2.0.

Windows Accelerometer Simulation
--------------------------------

The Windows debug environment now supports simulation of an accelerometer.
Accelerometer values can be inputted manually or by orientating a 3D display of a device.

Windows Pointer Configuration
--------------------------------

Various pointer properties can now be configured in the Windows debug environment. It also supports a means of simulating multi-touch events.

Change log for SDK features between 3.5 and 3.6
===============================================

iPhone support added
--------------------

Beta support for the iPhone/iPod touch has been added to the SDK.
Deploying for iPhone will create a .app (for use with XCode) and a .ipa file (for use with iTunes).

Signing of the application can be performed after deployment (using auto-generated scripts) or at deploy time using RPC to a Mac OS X machine on the network. To enable this feature you need to run the provided signing server (s3e/deploy/iphone/signing_server.py) on a OS X machine and set the S3E_IPHONE_SIGN_HOST environment variable on the development machine to the hostname of the OS X machine.

LZMA support added
------------------

The s3eCompression API now supports decompressing LZMA data. The compressed archive manager derbh has been updated to support compressing data in LZMA format, which provides around a 5-10% improvement in compression ratio. S3E executable files are also compressed using LZMA giving a similar saving. The deployment option 's3e-compression' has been added to allow switching of the compression format used in the s3e file.

QEMU/Insight Debugger support added
-----------------------------------

The Airplay SDK now allows desktop emulation and debugging of ARM binaries through QEMU and Insight. To use this system, simply select QEMU/Insight as the debugger during SDK configuration. QEMU/Insight provides improved support for finding exceptions in ARM code, improved debugging display and better performance.

GCC improvements
----------------

The GCC build included with the SDK had been upgraded to CodeSourcery's 2008 release. The newlib c library that it uses has been recompiled with space optimisations and we ship only the thumb version.

Also, the GCC libraries within the SDK are all now built the RVCT in GCC compatibility mode. This means that speed and size of the SDK code is now identical between RVCT and GCC.

The GCC libraries have also all been recompiled with -fshort-wchar to match the settings used by MSVC and RVCT. This means that size of all basic types is now the same in all supported compiler environments.

Improved Linux support
----------------------

We now ship two different ARM Linux loaders. One for EABI Linux systems and one for Old-ABI systems. Examples of EABI Linux systems are the Nokia N-series internet tablets.

Windows S3E environment UI-only mode
------------------------------------

If you hold down F5 whilst the windows S3E environment starts up, it will go into UI-only mode where the application is not run but configuration settings can be adjusted. This is useful if the application can't startup properly in the current configuration.

Brew MIF file creation
----------------------

The deployment system will now modify/create the brew MIF file at deploy time such that includes the icons, name, version, uid and vendor information that were specified in the MKB.

Change log for SDK features between 3.4 and 3.5
===============================================

Improved standard library support
---------------------------------
The standard library headers and implementation have been updated considerably to the extent the many large open source projects can now be compiled and run on s3e without modification.

Improved GCC linking
--------------------
GCC binaries are now linked as executables rather than shared objects which allows the linker to discard unused objects.

Windows metrics support
-----------------------
The Windows S3E environment supports metrics display via the s3eExtMetrics interface, which can provide run-time readouts of S3E metrics (memory, API usage, socket usage, filesystem usage) as well as S3D metrics (polygon throughput, resource usage, memory buckets, etc.).

GLES2.0/EGL1.3 support in the API
---------------------------------
GLES2.0/EGL1.3 functions are now part of the S3E API and can be used under windows.

OpenKODE Core 1.0 Provisional support in the API
------------------------------------------------
We now support OpenKODE. To use it, just include KD/kd.h, write your kdMain function and away you go. OpenKODE will automatically be linked in. Currently there is a complete implementation of the OpenKODE core, that is slightly newer than the version corresponding to the bugfix 2 release of the conformance tests. Look in kd.h to find out exactly what's available.
(Note that s3e currently does not support threading; the OpenKODE threading API is present but all functions will fail, as is required on systems without preemptive threading.)

ARM Emulator UI
---------------
The RTSM ARM emulator now has the same UI as that of the windows S3E environment. The UI is only accessible when ARM code is running.

UIQ Support
-----------
Support for UIQ based phones have now been added as a Beta feature.

Keyboard API
------------
s3eKeyboard.h now has support for all keys on a standard keyboard.

Audio & Video API
-----------------
The START, PAUSE and RESUME callbacks have been deprecated from the Audio & Video APIs. The Video API now has an expanded list of codecs for determining whether a video file can be played.

IwGxFont
--------
A module for handling texture-based font formatting and rendering has been added.

dzip enhancements
-----------------
Existing dz file contents can be listed and extracted using --extract and --list.
Alternative syntax is now provided for automated use by scripts (running without a dcl file input).

ARM libraries now thumbed for size
----------------------------------
Non-speed critical code paths in the middleware libraries are now thumbed, reducing RAM required by library code by ~1/3.

ABGR4444 format supported in SW renderer
----------------------------------------
Textures can be uploaded to ABGR4444 format for variable alpha.

Binary Serialising Enhancements
-------------------------------
An assert message is triggered if the same resource is specified multiple times in a group. Test for EOF when serialising.
Smaller binary format.

Smoother animation
------------------
Support in IwAnim for performing animations in a higher precision space than world space. Defaults to 4x.

Visual memory dump
------------------
Ability to dump a HTML file containing a detailed picture of all memory allocations.

ATITC texture compression
-------------------------
ATITC texture compression is now supported for the Imageon platform. Note that ATITC textures will not be visible on the PC.
Asset sets for beattoy and racing demo are included.

Support for 32-bit viewspace vertex streams
-------------------------------------------
These are now supported through the IwGx pipeline.

Guaranteed texture page defragmenting
-------------------------------------
IwGx now guarantees that if textures are allocated/free in FILO order the texture pages will return to the start state. This incurs a small memory overhead, but can be disabled using [GX] MaxTexturesPerPage=0 if this behaviour is not required.

Separated parameters for HW/SW
------------------------------
Since z-offsetting behaviour and requirements differ radically between HW and SW builds, materials now specify these separately.
Likewise separate [GX] DataCacheHW and [GX] VertCacheHW will be respected for switchable builds.

Texture pages without mipmaps
-----------------------------
The application can now initialise a number of tpages without mipmaps using [GX] NumTPagesNoMipMaps. Textures with mipmapping disabled will be uploaded to these in preference to normal tpages. Tpages without mipmaps are 20k smaller.

SW renderer convergence with HW
-------------------------------
Many differences between SW rendering and HW rendering removed. Of particular note:
Material alpha modes are now consistent (ALPHA_NONE will never be chromakeyed in SW). To defer to the texture ALPHA_DEFAULT should be used (this is the default).
Vertex alpha is respected for flat-shaded polys. In the next release it will be supported across the board.

Metrics for Airplay Studio
--------------------------
Airplay Studio now exposes an extensive range of metrics for tracking rendering load and resource overhead.

Custom memory buckets
---------------------
IwMemBucketRegister can be used to register a user defined custom memory bucket derived from CIwMemoryBucket.

Modified .config.txt system
---------------------------
The system of documenting .icf settings has now been extended so that any .config.txt files in the project serve as documentation for .icf file settings.

Windows context sensitive help
------------------------------
The Windows S3E environment documentation has been improved and is now available as context-sensitive help from the menus and dialogs of the x86 Simulator.

Windows S3E environment allows setting of DirectInput exclusivity for the keyboard
----------------------------------------------------------
A new option on the Preferences/Keyboard dialog allows Direct Input to be used in exclusive mode, which may help issues with spurious key presses whilst debugging.

Improved assertion/error dialog in Windows S3E environment
----------------------------------------------------------
The assert/error dialog displayed when calling s3eDebugErrorShow or s3eDebugAssertShow (used by the IwAssert/IwError macros) has been improved to allow resizing of the dialog and copying text to the clipboard. It also automatically detects hyperlinks in the error message.

Windows S3E environment window resizing
---------------------------------------
Resizing the window in the windows S3E environment can be controlled by holding Shift and Control whilst resizing. Holding Shift will maintain the displayed surface aspect ratio, holding Control will ensure the displayed surface size is a multiple of the original surface size.

Windows S3E environment option for sound latency
------------------------------------------------
There is now an option under Configuration... > Sound that allows the latency of the sound device (i.e., how much internal buffer occurs) to be controlled.

Windows S3E environment option for surface alignment
----------------------------------------------------
There is now an option under Configuration... > Surface that causes s3eSurfacePtr() to return a 16-bit aligned pointer rather than the normal 32-bit alignment.
This will help catch errors in the windows environment that would otherwise only occur on devices with unaligned screen buffers. This setting defaults to 'on'.

Windows S3E environment backlight simulation
--------------------------------------------
The windows S3E environment simulates a phone's backlight by darkening the display to simulate the backlight turning off. The backlight timeout can be set under Configuration...
> Surface, and the darkening can be enabled or disabled in Preferences... Display

Quantised Surface Width & Height Properties
-------------------------------------------
The properties S3E_SURFACE_DEVICE_WIDTH_QUANTISED and S3E_SURFACE_DEVICE_HEIGHT_QUANTISED have been added. These return the device screen width and height quantised into specific sizes. The icf setting [S3E] SCREENSIZE is now set internally to be the quantised width and height multiplied together. The purpose of this is to help the user to create the same sized memory buffers etc for devices with similar sized screens.

Improved support for SW and HW builds in a single SKU
-----------------------------------------------------
Rasterisation icf parameter now supports "SW or HW" which will only initialise half of IwGx (based on it's appraisal of the GL support present). "DataCacheSizeHW" and "VertCacheSizeHW" added to icf to override cache sizes if HW is initialised. Better correspondence between SW and HW for non-power-2 textures and screenspace polys.

Improved consistency of ARM runtime environment
-----------------------------------------------
On ARM devices the runtime environment now guarantees the stack size in which the game runs is equal to the [S3E] Stacksize icf setting (Default 32k). S3E function calls now consume the same small quantity of stack on all platforms (about 20 bytes per call), and set all temporary registers to zero.

Change log for SDK features between 3.3 and 3.4
===============================================

Standard Template Library
-------------------------

The STL and C++ runtime library is now supported on GCC, RVCT and win32 consistently via use of STLport. Your S3E applications can now freely use <vector>, <set>, <map>, etc.

Unified Standard C Headers
--------------------------

The standard C headers are now shared between all compiler environments, so there should be far fewer cases where it is necessary to write code to compensate for different C library implementations. Also, where ever possible the compilers supplied C library functions will be linked directly, so you should get the optimal implementation for your target.

New X86 Development Environment GUI
-----------------------------------

The Windows S3E execution environment now has GUI options for configuring all the Airplay System subdevices, for better simulation of target hardware.

Selective Linking
-----------------

Selective linking has been added for IwGx and IwGraphics. Selective linking provides smaller builds by eliminating features you know are not used.

New Scanline Renderer
---------------------

An additional software renderer, the scanline renderer, has been added in addition to the standard software renderer.

s3eSocket API Updated
---------------------

The s3eSocket API has been updated to make it more consistent with other subsystems. The s3eInetLookupCancel() function has been added to cancel asynchronous DNS requests.

OS Version Property
-------------------

A new device property has been added to allow you to query the underlying OS version: S3E_DEVICE_OS_VERSION

New Batch Files for Standard Python Tools
-----------------------------------------

New bat files have bee added to run the standard python tools: s3e_deploy.bat and i3d_make_build.bat. These can be run from the command-line prompt regardless of current working directory or python installation.

Brew
----

Brew files opened in append mode now work correctly.

Airplay Studio Exporter Updated
-------------------------------

World files can be exported and viewed. Locators, Curves and Static models can be exported from one scene. MultiGeo has been removed as an export type.

Exporter - Known Issues: Max Export of face selection sets produces multiple entries for each face.

Asset Viewer
------------

The background colour of the Asset Viewer has been changed to black.

s3eVideoPlay Updated
--------------------

s3eVideoPlay has been changed so that it correctly shows videos and jpegs with the correct size and location on the Windows platform.

New Events Menu
---------------

An 'Events' menu has been added to the Windows Loader to simulate 'suspend' and 'resume' events on the Windows platform.

Symbian Deployment
------------------

Deployment now supports running on Symbian 7 & 8 emulators, and there is now increased stability when task-switching.

OpenKODE support advanced to 1.0.2
----------------------------------

The OpenKODE implementation now uses the 1.0.2 header files, and passes the 1.0.2r1 conformance tests. The differences between 1.0 and 1.0.2 are very minor; see the included OpenKODE spec for more details.

Change List S3E

ChangeLog for the S3E loader
----------------------------

This log only includes changes to the S3E API that require a change to the S3E minor version number.

For more detailed logs, including changes to other modules within the SDK, please see the SDK Change List and Release Notes.

Most recent changes are listed first.

4.23.0 - 2009-06-06 (version header changed 2009-09-18)

* Add s3eHash.h which contains an inline version of the simple string has used by Airplay System.

* Add s3eConfigGetIntHash and s3eConfigGetStringHash and s3eExtGetHash which work exactly like the s3eConfigGetInt, s3eConfigGetString and s3eExtGet but take a hashed version of the string inputs.

4.22.1 - 2009-06-03

* glXXXOES functions removed from S3E API, as per GL specification

4.22.0 - 2009-03-30

* Add S3E_DEVICE_SUPPORTS_SIGNAL_HANDLING
* Add S3E_DEVICE_EXIT_SIGNAL

4.21.0 - 2009-03-13

* Add S3E_DEVICE_NAME property.

4.20.0 - 2009-02-11

* Add S3E_AUDIO_CODEC_AMR codec to s3eAudioCodec.

4.19.0 - 2009-01-13

* Add S3E_DEVICE_LOCALE string property.

4.18.0 - 2009-01-05

* Add s3eSocketGetPeerName()

4.17.0 - 2008-12-24

* Add s3eMemoryHeapGetAddress() which returns the start of an s3e heap.

4.16.0 - 2008-12-19

* s3eKeyboardGetInt.
* Add S3E_KEYBOARD_GET_CHAR property.

4.15.0 - 2008-10-30

* Add S3E_KEYBOARD_NUMPAD_ORIENTATION property.

4.14.1 - 2008-10-30

* Remove S3E_COMPRESSION_ERR_USER_ABORT error

4.14.0 - 2008-10-17

* Add S3E_DEBUG_FONT_SCALE property that allows the application to scale up the size of the debug font.
* Add S3E_DEBUG_FONT_SIZE_WIDTH property that allows the game to query at run-time the current width of the debug font.
* Add S3E_DEBUG_FONT_SIZE_HEIGHT property that allows the game to query at run-time the current height of the debug font.

4.13.0 - 2008-09-18

* Add S3E_DEVICE_AIRPLAY_VERSION property that allows the application to query the version of the SDK that the S3E loader comes from at run-time.
* Add S3E_DEBUG_AVAILABLE property that allows the game to query at run-time whether the S3E loader was built with assertion and tracing support.

4.12.0 - 2008-09-18

* Minor change to expose multi-touch capabilities on devices that support them (iPhone) by extending s3ePointerMotionEvent and re-interpreting m_Button and m_Pressed in s3ePointerEvent.
By default this extension is disabled unless S3E_POINTER_MULTI_TOUCH_ENABLE is true.

4.11.2 - 2008-09-08

* Add S3E_POINTER_HIDE_CURSOR property.

4.11.1 - 2008-08-26

* Add S3E_POINTER_MOTION_EVENT callback for pointer motion.

4.11.0 - 2008-07-16

* Add s3eKeyboardGetChar() for returning logical character generated by multiple key presses.

4.10.1 - 2008-06-10

* Applications build with this revision will now separate their code and data sections when loaded, reducing OS memory fragmentation issues

4.10.0 - 2008-06-10

* Add s3ePointerGetInt

4.9.0 - 2008-04-22

* Minor, backwards compatible change to the s3e file header. As usual older games will work on the 4.9.0 loaders, but new game binaries will work with older loaders.

4.8.2 - 2008-03-04

* Add support for [S3E] StackSwitch argument which will cause loader and game code to run in separate stacks, on all platforms.

4.8.1 - 2008-02-27

* Add argument to s3eDeviceExit so you can set the exit code and exit with a single call. The loader will ignore the argument for games older that 4.8.1.

4.8.0 - 2008-02-13

* Add extra arguments to s3eDeviceExecPushNext for setting config data for child processes.
* add S3E_DEFAULT macro

4.7.4 - 2008-01-29

* Remove s3eLicenseSetInt since there are no settable properties.

4.7.3 - 2008-01-29

* Add the AVAIL error code (5) to some more subdevices (File, Timer, Memory, Keyboard).

4.7.2 - 2008-01-04

* Move the socket accept callback from s3eSocketListen to s3eSocketAccept.
Only bumped minor version since there should be little or no use of this API in real application so far.

4.7.1 - 2008-01-03

* Added new internal IwCore API IwDebugTraceChannelSwitch to enable the dynamic switching of trace channels at runtime.

4.7.0 - 2007-10-10

* change absolute value of S3E_DEVICE_YIELD_FOREVER from MAN_UINT to MAX_INT to avoid accidental collision when application pass in small negative numbers. Treat all negative numbers passed to s3eDeviceYield as 0

4.6.0 - 2007-10-10

* add s3eFilePrintf to bring s3eFile closer to 1-1 mapping of stdio.h functions.

4.5.0 - 2007-09-06

* Added surface properties S3E_SURFACE_DEVICE_WIDTH_QUANTISED and S3E_SURFACE_DEVICE_HEIGHT_QUANTISED. Removed unused/unimplemented device notifications (S3E_DEVICE_NOTIFY_*)

4.4.2 - 2007-09-06

* remove s3eKeyboartSetInt as there are no settable keyboard properties.
Only bumping minor revision as there won't be any users of this entry point out there.

4.4.1 - 2007-08-03

* add S3E_DEBUG_ASSERT_ENABLED and S3E_DEBUG_TRACE_ENABLED properties to s3eDebug.h for globally enabling/disabling assertions and tracing
* add device property S3E_DEVICE_EXIT_CODE which is then used by s3eDeviceExit()

4.4.0 - 2007-07-31

* add s3eKey* for remaining keys on standard keyboard

4.3.0 - 2007-07-23

* add s3eInetLookupCancel() to socket API

4.2.0 - 2007-07-18

* Added GLES2.0 functions as API entry points

4.1.0 - 2007-06-15

* Added S3E_SOUND_VOLUME_DEFAULT, S3E_AUDIO_VOLUME_DEFAULT and S3E_VIDEO_VOLUME_DEFAULT

4.0.0 - 2007-06-15

* Update the socket API to use the built-in callback mechanism.
* Renumbered the socket error numbers

3.0.2 - 2007-06-01

* Add S3E_DEVICE_OS_VERSION property

3.0.1 - 2007-05-31

* Remove highly unused s3eKeyboardIsKeySupported(). This function was also hard/impossible to implement on some platforms.

3.0.0 - 2007-05-14

* Removed all support for legacy API entry points and legacy macros

2.13.0 - 2007-04-08

* Added S3E_DEVICE_MAINS_POWER property

2.12.0 - 2007-03-16

* Added s3eMemoryGetUserMemMgr
* Added S3E_DEVICE_LANGUAGE_x for most world languages

2.11.0 - 2007-03-16

* s3eFileFlush returns success for user file systems
* Added S3E_DEVICE_LEFT_SOFTKEY_IS_BACK property
* Added s3eKeyboardClearState()

2.10.0 - 2007-01-25

* Capitalise a lot of enum values
* Give absolute value to a lot of enum values
* Change the name of enums such that they are not plural.
* Make for all s3eFooSetInt function take a signed int32 not a uint32
* Remove some Get/SetInt function from subdevices with no properties.

2.9.0 - 2006-12-21

* s3eDeviceExecPushNext now automatically appends a .s3e or .s86 extension as appropriate

2.8.0 - 2006-12-13

* S3E_AUDIO_VOLUME_MAX changed to S3E_AUDIO_MAX_VOLUME
* S3E_VIDEO_VOLUME_MAX changed to S3E_VIDEO_MAX_VOLUME
* S3E_DEVICE_STATE_PAUSED changed to s3eDeviceStatePaused
* S3E_DEVICE_STATE_EXITING changed to s3eDeviceStateExiting
* S3E_DEVICE_STATE_RUNNING changed to s3eDeviceStateRunning
* S3E_DEVICE_STATE_MAX changed to s3eDeviceStateMax

2.7.0 - 2006-12-12

* s3eplink now adds license information. This information is checked for validity
* the validity check is not performed if the version is less than 2.7.0

2.6.1 - 2006-12-11

* add S3E_DEVICE_CLASS_SYMBIAN_SERIES60_EMULATOR
* add S3E_DEVICE_CLASS_SYMBIAN_UIQ
* add S3E_DEVICE_CLASS_SYMBIAN_UIQ_EMULATOR

2.6.0 - 2006-12-01

* add s3eTimerGetUTC
* add s3eTimerGetLocaltimeOffset

2.5.0 - 2006-11-16

* change for endianness of s3eInetAddress.m_Port from host order to network order. This makes the m_Port consistent with the m_IPAddress.
For backward compatibility, the network code only treats m_Post as host order if the game was built for loader version < 2.5.0

2.4.0 - 2006-11-09

* unified s3eCallbacksDeviceID and s3eDeviceID, required global search-replace
* deprecated deviceActivityState, added UnYield and YieldUntilEvent

Known Issues

Known Issues for Airplay SDK 4.0
================================

- UDP networking in Windows Mobile does not work over ActiveSync connections. This is a known issue with Windows Mobile.

- The S3E_DEVICE_BATTERY_LEVEL property does not currently work on UIQ devices.

- The S3E_DEVICE_PROXIMITY property does not currently work on iPhone devices and should be ignored. The proximity sensor is currently always disabled.

Windows Vista Compatibility
---------------------------

There are a number of known issues encountered when running the Airplay SDK on Vista.

- Running s3eConfig requires administrative privileges. You can enable this by doing the following:

1. Right-click on s3eConfig.exe (found in s3e/bin), 2. Select properties and then the compatibility tab 3. Select the check box labelled "Run this program as an administrator".
The administrative privileges are required to set up file associations and alter the system environment variable S3E_DIR.

- Some Vista machines experience problems running the ARM Real Time System Model.

If you discover any other issues, please let us know via your support web site and we will investigate.


Airplay SDK: Licence Agreement

Airplay SDK > Installation and Licensing > Licence Agreement >

Licence Agreement

Airplay SDK 4.0 End User Licence Agreement

BY CONTINUING WITH THIS INSTALLATION YOU ARE ACCEPTING THE TERMS OF THE USER LICENCE AGREEMENT BELOW.

You should be aware that this is a legal agreement between you and Ideaworks3D Limited (the "Agreement"). "Ideaworks Labs" is a trading name only.

Please ensure that you understand the terms and conditions of this agreement before continuing with the installation of the accompanying software development product.

BEFORE YOU CLICK ON THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT AND DOWNLOAD OR USE THE SOFTWARE DEVELOPMENT PRODUCT AND ASSOCIATED MATERIALS, CAREFULLY READ THE TERMS AND CONDITIONS OF THIS LICENCE. BY CLICKING ON THE "ACCEPT" BUTTON AND BY DOWNLOADING OR USING THE SOFTWARE DEVELOPMENT PRODUCT AND ASSOCIATED MATERIALS YOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING THE LICENSEE TO THIS LICENCE. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS LICENCE CLICK THE "DO NOT ACCEPT" BUTTON AND DO NOT DOWNLOAD OR USE THE SOFTWARE DEVELOPMENT PRODUCT AND ASSOCIATED MATERIALS.

1. AIRPLAY SOFTWARE LICENCE

1. When you "click" the "Accept" button, Ideaworks3D Limited (the "Licensor") grants you (either on behalf of yourself as an individual or on behalf of an entity as its authorised representative, the "Licensee"), jointly the "Parties", in consideration for and subject to your continued compliance with the terms and conditions set out herein, a non-exclusive, non-transferable, world-wide licence (the "Licence") for the accompanying software development product, including (if applicable) electronic documentation and associated material (the "SDK") for a duration of 30 days, which may be renewed and updated according to the availability of subsequent versions of the SDK from the Licensor's website, and only in the quantity expressly authorised by Licensor and implemented using software licence key(s) for the Software's electronic licence management system (each a "Licence Key") ("Term"). The Licence permits you to "Use" (as hereinafter defined) the SDK as follows upon the terms and subject to the conditions contained herein:
- in a closed computer network (the "System") - on a Windows 32 based PC and such mobile devices, software development platforms and/or game development platforms and operating systems supported by the SDK, including but not limited to Apple iPhone, Google Android, BREW, Symbian OS, Windows Mobile and Linux (the "Platform(s)") - the SDK may NOT be transferred electronically to another computer or device outside of the System nor copied (other than as provided for specifically within this Licence) - Any 3rd party technology shall be used only as part of the SDK during the evaluation licence for the SDK

2. In this Licence, "Use" shall mean:
utilisation of the SDK by copying, transmitting or loading the same into the permanent memory (such as, by way of example only, hard disk, CD ROM, flash memory or other storage device) of the System for the processing by the System of instructions or statements contained in such SDK; and for Licensee's internal assessment of the SDK by building so-called "Demonstration Applications" on the Platform(s) solely to enable a Licensee (or its employees or representatives as applicable) to familiarise itself with the SDK for the purpose of evaluating if the Licensee wishes to take a separate licence of the SDK for commercial purposes including but not limited the selling or to public distribution of derivatives of Demonstration Applications. Any such Demonstration Applications developed may not be distributed publicly, and must contain a splash screen or permanent watermark, as provided by Licensor, which clearly identifies to the viewer that the application is powered by Airplay and is not licensed for public distribution or resale. Any such Demonstration Applications must include a copyright notice with due attribution to the ownership of the SDK as residing with and provided with the permission of the Licensor by name.
Any use of the SDK beyond the scope set out above will require the purchase of a separate licence for commercial deployment or public distribution purposes from the Licensor.

3. Upon accepting this Licence, you undertake:
(a) not to copy the SDK (other than for normal operation and as specified in Clause 1 above) nor to disassemble, decompile, reverse engineer or attempt to discover the source code of the SDK. All information required to achieve interoperability of the SDK with other SDK programs in accordance with section 50B of the Copyright, Designs and Patents Act 1988, as amended, or any other applicable local law which may apply to you, is available from the Licensor and you agree to provide the Licensor with all reasonable relevant information which may be requested of you in order to achieve such interoperability. The Licensor has the right to impose reasonable conditions, including without limitation a reasonable charge, for doing so; (b) not to translate, modify, lease, rent, loan, redistribute, sub-lease, sub-license or create derivative works from the SDK; (c) to supervise and control Use of the SDK in accordance with the terms of this Licence; (d) to ensure that your employees, agents and other parties who will use the SDK are notified of this Licence and the terms hereof prior to such employee, agent or party using the same; (e) not to provide or otherwise make available the SDK to any person other than your employees, subcontractors, or as specified herein without prior written consent from the Licensor save that you shall be entitled to use and display any research and developments created for demonstration purposes pursuant to the Use; (f) not to display the SDK on a public bulletin board, file transfer protocol ('ftp') site, internet site, chat room, file sharing site, instant messaging service or by any other unauthorised means; (g) not to use the SDK for immoral, illegal or for any other purpose which may be determined threatening, abusive or harmful including but not limited to the creation or transmission of any virus, worms, trojan horse, cancel-bot or any other destructive or contaminating program; (h) not to remove copyright notices or other forms of proprietary notice from the SDK or Demonstration Applications provided by the Licensor or its Licensors as applicable; and (i) within 30 days after the date of termination or discontinuance of this Licence for whatever reason, to destroy or delete (as applicable) the SDK (including, for the avoidance of doubt and without limitation, any associated documentation and/or any other associated material) and all upgrades or copies.

4. (a) THE SDK IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. THE LICENSOR AND ITS LICENSORS DOES NOT WARRANT THAT THE SDK WILL BE ERROR-FREE OR THAT SUCH ERRORS WILL BE CORRECTED. YOU ARE SOLELY RESPONSIBLE FOR ALL COSTS AND EXPENSES ASSOCIATED WITH RECTIFICATION, REPAIR OR DAMAGE CAUSED BY SUCH ERRORS.
(b) THE LICENSOR SHALL NOT BE LIABLE TO THE LICENSEE OR TO ANY OTHER PARTY FOR ANY LOSS OR DAMAGE WHATSOEVER OR HOWSOEVER CAUSED OR ARISING DIRECTLY OR INDIRECTLY IN CONNECTION WITH THIS LICENCE, THE SDK, ITS USE OR OTHERWISE, EXCEPT TO THE EXTENT THAT SUCH LIABILITY MAY NOT BE LAWFULLY EXCLUDED UNDER THE APPLICABLE LAW.
(c) NOTWITHSTANDING THE GENERALITY OF (b) ABOVE, THE LICENSOR SHALL NOT BE LIABLE IN CONTRACT, TORT (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE), PRE-CONTRACT OR OTHER REPRESENTATIONS (OTHER THAN FRAUDULENT MISREPRESENTATIONS) OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THIS LICENCE FOR:
(i) ANY LOSS OF REVENUES, PROFITS, CONTRACTS, BUSINESS OR ANTICIPATED SAVINGS; (ii) ANY LOSS OF GOODWILL OR REPUTATION; OR (iii) ANY SPECIAL, INDIRECT OR CONSEQUENTIAL LOSSES IN ANY CASE, WHETHER OR NOT SUCH LOSSES WERE WITHIN YOUR CONTEMPLATION AT THE DATE OF THIS LICENCE, SUFFERED OR INCURRED BY YOU ARISING OUT OF OR IN CONNECTION WITH THE PROVISIONS OF ANY MATTER UNDER THIS LICENCE.
(d) THE LICENSOR'S MAXIMUM AGGREGATE LIABILITY IN RESPECT OF ANY CLAIM OR SERIES OF CLAIMS SHALL BE LIMITED TO THE LICENCE FEE PAID BY YOU, IF ANY, FOR THE SDK (EXCEPT FOR DEATH OR PERSONAL INJURY ARISING FROM THE LICENSOR'S NEGLIGENCE, OR FROM ANY FRAUDULENT REPRESENTATION, WHERE THE LICENSOR'S LIABILITY SHALL NOT BE LIMITED).

5. All copyright, trade marks and other intellectual property rights subsisting in or used in connection with the SDK (including but not limited to all images, text, code or other identifiable material relating to the SDK) are and remain the sole property of the Licensor, and where applicable its Licensors, and you acknowledge that no title to any rights is transferred to you. All rights not expressly granted in this Agreement are reserved by Ideaworks3d Ltd.

6. You may terminate this Licence at any time by deleting or destroying the SDK, documentation and all copies. The Licensor may terminate this Licence (i) at any time if you are found to be in breach of any of these terms; or (ii) at any time upon not less than 3 days' notice. If you are notified of such termination, you must comply with the provisions of Clause 2(h) above.

7. In the event that any provision of this Agreement shall be found invalid or unenforceable, the Parties agree that this shall not affect the validity of the remaining provisions.

8. Notwithstanding any other provision in this Licence, a person who is not a party to this Licence has no right under the Contracts (Rights of Third Parties) Act 1999 (the "Act") to rely upon or enforce any term of this Licence. Nothing in this Licence shall affect any right or remedy of a third party which exists or is available apart from that Act.

9. This Agreement is the entire agreement between the Parties and it supersedes any prior agreement whether written or oral relating to the provisions of such prior agreement.

10. This Licence shall be governed by and construed in accordance with the laws of England and Wales and the parties hereby submit to the exclusive jurisdiction of the English courts in respect of any dispute or matter arising out of or connected with this Licence although the Licensor shall have the right to commence and pursue proceedings in alternative jurisdictions. In terms of the enforceability of this Licence, the Licence shall be deemed "in writing" and "accepted" by both parties.

AIRPLAY SDK CONTAINS THE FOLLOWING SEPARATE FILES NOT COVERED BY THE ABOVE LICENCE AND THAT HAVE THEIR OWN APPLICABLE LICENCE TERMS.

A number of components in the SDK are 3rd party components used under 'Open Source' or similar licenses. These are listed below, along with details of how to find the exact license terms used. Note that some of these components (typically licensed under 'BSD style' licenses) are libraries that will become included into products produced with the SDK, while others (in particular those licensed under the GPL) are tools that a user of the SDK will not need to redistribute.

The following components are licensed under the GNU General Public License, version 2 ('The GPL'):

gcc The Gnu C Compiler gdb The Gnu Debugger distcc cygwin.dll

A copy of the general public license is available in gpl-2.0.txt in the licenses directory of this installation. These are all tools which do not get incorporated into products generated with the SDK, with the exception of theGCC libraries, which are also licensed under another license that permits binary-only distribution without restriction. (Seelicenses/ASSORTED.LICENSES.TXT for details)

The following components are licensed under the GNU Lesser General Public License, version 2.1 ('The LGPL'):

libstdc++ The GNU Standard C++ library.
QEmu (Those parts of it that we use) A copy of the license is available in lgpl-2.1in the licenses directory.
libstdc++ may be incorporated into products developed with the SDK.

For all these components (GPLed and LGPLed components), source code is available on request. No warranty is provided for these components; see thelicense files referenced above for more details.

The following open-source components are included under 'BSD-like' licenses:

zlib bzip2 STLPort newlib (The above may be incorporated into products developed with the SDK) scons openssl.exe libeay.dll

lzma is included under a license which permits unmodified redistribution. dlmalloc, which is public domain, is also included. Both of these components may be distributed in products developed with the SDK.

The exact licenses for all these components are contained in ASSORTED.LICENSES.TXT in the licenses directory, except for Newlib, whose licenses are contained in COPYING.NEWLIB in the same place.ASSORTED.LICENSES.TXT also contains details of the non-GPL license applicable to gcc libraries.

Python2.5 is included under the following license:

PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
--------------------------------------------

1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using this software ("Python") in source or binary form andits associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Python Software Foundation; All Rights Reserved" are retained in Python alone or in any derivative version prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or incorporates Python or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python.

4. PSF is making Python available to Licensee on an "AS IS" basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.

8. By copying, installing or otherwise using Python, Licensee agrees to be bound by the terms and conditions of this License Agreement.


Airplay SDK: Copyright Information

Airplay SDK > Installation and Licensing > Copyright Information >

Copyright Information

Copyright © 2001-2009 Ideaworks Labs.

All Rights Reserved.

This document is protected by copyright, and contains information proprietary to Ideaworks Labs.

Airplay SDK is released by Ideaworks Labs under the terms of the accompanying End User License Agreement (EULA).

Please do not use Airplay SDK before you have read the EULA and have agreed to be bound by its terms.


Airplay SDK: Getting Started

Airplay SDK > Getting Started >

Getting Started with Airplay

This section will take you through the process of building a simple Airplay project, testing in the Windows Simulator and ARM Emulator, and finally deploying the build to a device. All of this should take less than 10 minutes.

You should already have installed and licensed the Airplay SDK. See Installation and Licensing for more details.

Creating an Airplay project within the programmer IDE

Open this file in a text editor:

<SDK installation dir>/examples/Basic/Basic.mkb

Notice that this is a simple text file that just lists a single CPP source file, "Basic.cpp".

Double-click the file. Airplay will automatically create a project workspace file for the programming IDE of your choice (this is the IDE you selected when you installed the SDK; or whenever you run the s3eConfig.exe configuration tool). Airplay then launches your chosen IDE and loads the workspace file.

Within the IDE, double-click on the source file "Basic.cpp". Notice the main() entry point and the simple application loop. The simple fillScreen() function uses the s3eSurface API to fill the screen with a time-dependent colour. The application will exit if the user presses any key, or if Airplay receives a "quit" event from the underlying operating system.

Building the project for x86 architecture, and debugging

Within the IDE, open up the list of project build configurations (in Visual C++ 2008 go to Build > Configuration Manager). Notice how the project has 6 build configurations, including Debug and Release configurations for x86, GCC ARM and RVCT ARM compilers.

Select the x86 Debug build. Build the project, using the IDE menu option or shortcut key, (in Visual C++ 2008 hit the F7 key). The compiler log can be seen in the Output window.

Launch the x86 Debug build within the IDE debugger, using the IDE menu option or shortcut key, (in Visual C++ 2008 hit the F5 key). The application runs as expected, filling the screen with a different colour as time elapses. All the powerful features of the IDE debugger are available. Notice how the Airplay application is running within a Windows wrapper (the "Windows Simulator") that provides useful real-time functionality such as the ability to change the screen size, rotate the screen, view metrics, etc.

Exit the application by pressing any key, or by closing the Windows Simulator.

Building the project for ARM architecture, and debugging

Within the IDE, open up the list of project build configurations (in Visual C++ 2008 go to Build > Configuration Manager).

Select the GCC ARM Debug build. Build the project (in Visual C++ 2008 hit the F7 key). The ARM compiler log appears in the Output window.

Launch the debugger, (in Visual C++ 2008 hit the F5 key). Instead of launching the standard IDE x86 debugger, the ARM Emulator is launched (this is the QEMU emulator with Insight debugger). Once the ARM debugger is loaded, select Control > Continue to begin execution. The application runs as expected, filling the screen with a different colour as time elapses. All the powerful features of the ARM Emulator and attached debugger are available, including source-level and disassembly-level debugging.

Exit the application by pressing any key, or by closing the ARM Emulator and attached debugger.

Building the project for ARM architecture, and deploying

Within the IDE, open up the list of project build configurations (in Visual C++ 2008 go to Build > Configuration Manager).

Select the GCC ARM Release build. Build the project (in Visual C++ 2008 hit the F7 key). Notice how the ARM compiler log appears in the Output window. Because this is a Release build, the compiler is invoked with optimisation switches turned on, building smaller and faster ARM code.

Launch the debugger (in Visual C++ 2008 hit the F5 key). Instead of launching a debugger, the Airplay Deployment Tool is launched. This tool allows you to take any application binary you have built, and package it for deployment to any supported device.

In the list of available binaries, select ARM GCC Release, then click Next.

The Deployment Tool now shows a list of "deployment configurations". This is a relatively advanced concept and can be ignored for now; also, the Basic project defines only a single "Default" configuration. Click Next.

The Deployment Tool now shows a list of supported deployment platforms (operating systems). Select "Symbian v9.x S60" and "Windows Mobile".

Click "Deploy All". The right-hand panel shows the deployment progress; in each case, the ARM Release binary (the "single application binary", or S3E file) is packaged together with the Airplay Loader for that platform, and some automatically-generated platform-specific resources, to create an application installer for that platform.

Now open Windows Explorer and navigate to:

/examples/Basic/build_<...>/deployments/default

Within this folder, there should be a single folder for each platform deployment. Within the "symbian9/release" folder is a SIS file, ready for deployment to any Symbian x9.x S60 device, and within the "winmobile/release" folder is a CAB file, ready for deployment to any Windows Mobile device.

If you have an appropriate device available, connect the device to your PC. With the device connection software installed on your PC (for example, Nokia PC Suite or Microsoft ActiveSync), it should be a simple process to install the SIS or CAB file to the device. Use the device user interface to launch the application.

Summary of what we have just achieved

From an IDE-agnostic project file (MKB file), we have automatically created a workspace file for the IDE of our choice.

We have automatically been provided with 6 build configurations, to aid the process of building and debugging, first using x86 architecture, then ARM architecture.

Using the x86 Debug build, we have been able to leverage the IDE's powerful x86 debugger.

Using the ARM Debug build, we have been able to leverage the integrated ARM Emulator and attached debugger.

Using the ARM Release build, we have been able to build an optimised ARM binary (S3E file).

Using the deployment tool, we have been able to package the single application binary (S3E file) for deployment to multiple platforms (operating systems), creating the application installers for multiple platforms using a single click.


Airplay SDK: User Guide

Airplay SDK > User Guide >

User Guide

The User Guide explains the concepts behind the Airplay SDK and how it can be used to create applications. It explores the processes behind creating these applications and the tools that are included with the SDK which make this possible.

A selection of tutorials and examples are included within this section to assist in understanding some of the more complicated aspects of the Airplay SDK.

  • Overview of Airplay
  • Creating an Application
  • API Examples
  • Simple Game Tutorials
  • Full Game Examples
  • FAQ
  • File Types
  • Using Open Source Modules


Airplay SDK: Overview of Airplay

Airplay SDK > User Guide > Overview of Airplay >

Overview of Airplay

The Airplay SDK is made up of a set of C-based APIs, a selection of freestanding tools, and plugins for various applications. These are linked together with a collection of specialised file types which allow data to be used, stored, and passed between the different processes. These elements, combined with a tailored workflow, allow applications to be planned, created, built and deployed with all the advantages that Airplay brings. These applications, processes and workflows are explained in more detail in the following sections.

  • The Two Sides of Airplay
  • Airplay Concepts
  • Application Development Workflow


Airplay SDK: The Two Sides of Airplay

Airplay SDK > User Guide > Overview of Airplay > The Two Sides of Airplay >

The Two Sides of Airplay

Airplay consists of two major components:

Airplay System

Airplay System is an operating system (OS) abstraction API, together with the associated runtime libraries and application build system. It provides a series of tools (integrated with standard programming IDEs) and a C API (the S3E API) to fully abstract the developer from the underlying target device OS.

Airplay System can be thought of as a "virtual platform" that the programmer writes to.

Airplay Studio

Airplay Studio is a suite of tools and runtime components, focused on (but not restricted to) high-performance 2D/3D graphics and animation. Modules are provided to facilitate fixed-point and floating-point geometry, 2D and 3D drawing, model rendering, skinned animation, bitmap fonts, and more. Airplay Studio includes support for fast software rendering, OpenGL ES 1.x and OpenGL ES 2.0. Airplay Studio functionality is provided as C++ APIs. Airplay Studio "sits on top of" the Airplay System OS-abstraction APIs, and thus all Airplay Studio functionality is completely OS-independent.

Airplay Studio can be thought of collectively as classic "middleware".

  • Airplay System
  • Airplay Studio


Airplay SDK: Airplay System

Airplay SDK > User Guide > Overview of Airplay > The Two Sides of Airplay > Airplay System >

Airplay System

Airplay System is the foundation of the Airplay SDK. It features a simple C-style API that provides access and control of core device services, events and subdevice properties. The developer is thus entirely abstracted from a given platform's programming model and relieved of having to consider device-specific issues or even install any device specific development kits.

The C-style API, known as S3E (Segundo Embedded Execution Environment) behaves identically across all target platforms, thus reducing device and OS fragmentation. It does this by using a combination of a single application binary (the same for all platforms) and a thin C API which abstracts all relevant core OS services. This abstraction removes the need to consider device-specific issues while developing, and results in a binary that can be deployed straight to device.

Airplay supports an x86 build and debug environment, which is intended to be the primary means of development. It allows applications to be built and debugged without ever being sent to a device. It provides a much faster debug turn-around cycle than continually deploying to and testing on devices.


Airplay SDK: Airplay Studio

Airplay SDK > User Guide > Overview of Airplay > The Two Sides of Airplay > Airplay Studio >

Airplay Studio

The Airplay SDK provides a set of powerful libraries that equip a developer to construct advanced and graphically-rich applications. These libraries can be incorporated into application code to quickly and effectively create your application.

Airplay Studio provides the following modules:

  • Derbh: A compression utility. It allows you to create an application which is able to compress and decompress assets and archives.
  • IwGeom: A 2D/3D geometry library, which supplies the basic fixed-point and floating-point types that allow you to construct geometric objects.
  • IwUtil: A selection of utility APIs and C++ base classes. It performs such operations as the generation of hash numbers, memory management and text parsing.
  • IwGx: A stream-based API for 2D and 3D drawing, which provides abstraction from the underlying low-level renderer. It handles such things as object lighting, transformation and rasterisation.
  • IwResManager: Resource management. Resources are application assets, such as textures, materials, or models.
  • IwGraphics: Model-rendering and processing.
  • IwAnim: Skinned/boned animation.
  • IwGxFont: Processing and rendering of bitmap fonts.
  • IwUI: High-level UI framework.
  • IwHTTP: Basic HTTP support.
Airplay Studio Component Diagram

Art Assets

Airplay Studio also includes an Art Exporter, called the Airplay Studio Exporter, which supports multiple 3D Modelling packages such as Maya and 3D Studio Max. All data in Airplay Studio is exchanged in intermediary text files, allowing easy integration with any existing developer tools and workflows. Also included is an art asset management tool called Airplay Studio Director. This tool allows assets within an application project to be managed, as well as viewing animations, compressing assets and editing files.

For more information on the Airplay Studio Exporters and Airplay Studio Director, see the Airplay Art Tools Reference


Airplay SDK: Airplay Concepts

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts >

Airplay Concepts

The Airplay development process is built upon a number of key concepts which are introduced in the following sections.

MKB files are used to configure projects for building Airplay applications, while ICF files configure run-time options for the applications. The Loader/Binary System explains how OS/platform abstraction works and the files and processes Airplay uses to achieve this.

  • MKB Files
  • Loader/Binary System
  • ICF Files
  • Data Files
  • Memory
  • Device Interoperability
  • Debugging
  • Extensions
  • Callback Functionality


Airplay SDK: MKB Files

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > MKB Files >

MKB Files

MKB (.mkb) files are project files for Airplay applications. They are used to specify various build and configuration options that enable an Airplay System application to be compiled and run on both x86-based and ARM-based target devices.

MKB files can be used to specify:

  • Source and header files to be included in a build.
  • Preprocessor definitions.
  • The type of build that is to be created.
  • Options to use when deploying to devices.

MKB files are independent of any particular IDE (for example, different versions of Microsoft Visual Studio) and independent of any particular platform build system (for example, the Symbian OS build system). Thus, using an MKB file provides a simple way of switching between different build environments.

When Airplay SDK is installed, a file association is set up between MKB files and an Airplay script that can generate IDE workspace files for all supported IDEs (e.g. all versions of Microsoft Visual Studio). The Airplay Configuration Utility allows the user to select a preferred programming IDE. Thereafter, double-clicking an MKB file will generate a workspace file for the programmer's chosen IDE and open the workspace file within the chosen IDE.

MKF files are identical in format to MKB files, and are used to define "subprojects" of the main application project. Any project uses a single MKB file, but can use multiple MKF files. Only MKB files can be double-clicked to generate an IDE workspace. Documentation that refers to "MKB files" can usually be taken to refer to both MKB and MKF files.

It is important to note that IDE workspace files should not be edited directly, as these changes will be lost the next time the workspace is auto-generated from the MKB. Instead, the MKB file (or associated MKF files) should be edited. MKB files generally appear within the IDE workspace itself; they can be edited within the IDE, and the IDE workspace will be auto-generated from the updated MKB files the next time the application is built (generally this is a 2-stage process; attempting to build a project after editing an MKB first results only in the IDE workspace being regenerated, after which the user is required to repeat the build request, at which point the build actually commences).

The open source build system 'SCons' is also included within Airplay SDK; this allows the building of MKB projects without using any IDE.

Creating an MKB File

The top-level MKB file normally contains general build information. Further subprojects can be included in the build by pointing the top-level MKB at other MKF files. These files can define more specific build information. The top-level file is given a 'MKB' file extension, and any MKB file that is subordinate to a top-level MKB (i.e., any file that is not directly build-able) is given the 'MKF' file extension.

Below is an example of an MKB containing the basic syntax required for a simple S3E application

  • files
  • {
    • ["Basic Example"]
    • (source)
    • main.cpp
  • }

  • files {}: Lists the source files to be included in the project. Paths are relative to the root folder, which is the directory the MKB is in by default but can be set using the rootdir command.
  • ["Basic Example"]: The group name under which subsequently listed files will appear in a supported development environment.
  • (source): Subfolder in which subsequently listed files are to be searched for.
  • main.cpp: A source file to be included. File and group names can contain special characters and spaces but must then be enclosed in quotes ("").

MKB Syntax and Settings

For a full listing of available MKB settings and syntax, see MKB File Settings.

The MKB settings include a subset used to specify deployment options for the Deployment Tool. See MKB Deployment Options for more information.

See Advanced MKB Usage for how to use command line options and custom settings.


Airplay SDK: Loader/Binary System

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Loader/Binary System >

Loader/Binary System

When an Airplay application is built for a device, the resulting executable file is an S3E binary. An S3E file is a compressed OS-independent binary format file that makes external calls to the S3E API. S3E files contain native ARM CPU instructions.

In order to run a S3E file on a target platform, an S3E "loader" is required. The loader performs two functions:

  • Load the S3E binary into memory.
  • Implement the S3E API and link the external calls in the S3E binary to its S3E API implementation.

This system makes porting an application between platforms trivial; so long as the application can respond to a small set of parameters that change between platforms (screen size, available keys, available media codecs, etc.) then porting between different OS's is simple.

Airplay applications can also be built for the x86 CPU architecture (as Windows .dll files) and run using the Windows Simulator. The Windows Simulator is a fully-fledged simulation environment capable of simulating all the parameters that may vary between target platforms and devices. The Windows Simulator also provides additional debugging features such as metrics display and external event simulation.

The x86 and S3E binaries have been designed so that memory usage and allocation patterns are almost always identical between the two. This means that situations where the x86 build works but the S3E build does not are rare.

For more information on the Windows Simulator, see the Windows Simulator Options section.

Compiler Support

The Airplay System build environment supports 3 compilers:

  • Microsoft x86 compiler (included with Visual Studio)
  • Codesourcery GCC ARM
  • ARM RVCT (not included in the SDK)

These are available as 3 different build configurations within the MKB-generated IDE workspace.

The Visual Studio/x86 compiler is used for debugging and testing x86 builds. When building for devices, the user can choose between the ARM RVCT and GCC compilers. Generally, the ARM RVCT compiler produces code that is smaller and faster than the GCC compiler. Usage of the ARM RVCT compiler requires purchasing and licensing the RealView Development Suite(RVDS) from ARM. Note that ARM provide a free 30-day evaluation of RVDS, available from www.arm.com


Airplay SDK: ICF Files

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > ICF Files >

ICF Files

Airplay applications and also the S3E runtimes (the "loaders") are partially data-driven via Airplay-specific text configuration files. These files are known as "ICF files", and use the .ICF extension (ICF stands for "Ideaworks Labs Configuration File"). ICF files look similar in structure to Microsoft INI files, and are used to specify dynamic configuration options for the Airplay application and the S3E runtime environment.

An Airplay application will generally need some reconfiguration between target devices, and ICF files provide an easy way of accomplishing this. By default, an Airplay application has a single ICF file (known as the "application ICF file"). By default, this file is named 'app.icf' and is placed in the application's data directory (usually a subdirectory of that containing the MKB, named 'data'). A different location and name for this file can be specified using the 'app-icf' option in the application's MKB file. Multiple ICF files can be used by specifying a comma-separated list of file names for this option. For example:

  • options
  • {
    • app-icf="icfs/app1.icf,icfs/app2.icf"
  • }

Internally, Airplay System uses another ICF file named 's3e.icf' to ensure the loader is configured correctly for every device. Together, app.icf and s3e.icf provide all the dynamic configuration required to run an Airplay application.

The S3E file format supports embedding ICF files inside the application's S3E file. In general, the Deployment Tool only embeds the ICF files for 'release' deployments. For 'debug' deployments, the app.icf and s3e.icf files are placed in the same directory as the application's data. For 'debug' deployments, being able to edit app.icf quickly is often useful, for example the configuration settings can be used to quickly enable or disable debug features.

For more information on ICF files, see the ICF File Settings section.

Conditional ICF File Expressions

ICF file settings can be made conditional on target platforms (operating systems), i.e. a given setting is only used when running on a specific target platform, as follows:

  • { OS=Windows }
  • icf settings here...

The ICF settings are only applied if the target OS is Windows.

ICF file settings can be made conditional on specific target devices, i.e. a given setting is only used when running on a specific target device, as follows:

  • { ID=BREW 1206} # LG VX8800
  • icf settings here...

The ICF settings are only applied if the target device is the LG VX8800.

Within a single platform, multiple device IDs can be specified, separated by commas. A device's ID can be discovered using s3eDeviceGetInt(S3E_DEVICE_ID); this ID is also written to the default trace file, and displayed briefly to the screen, when running a Debug build on a device.

ICF files also support the use of settings that can be controlled based upon the value of other settings. For example, the application might want to enable some settings related to a device camera, but only if the device camera's minimum image size is above a certain value.

The conditional settings must be placed in a block following a boolean test for another setting value, as follows:

  • { [groupname] valuename == value }
  • icf settings here...

The conditional settings will only be used if '[groupname] valuename' is equal to 'value'.

Note the double equals '==' in this expression. The comparison of values is performed as a string comparison.

Settings as Modifiers

ICF files support the use of settings as modifiers. It is possible to assign a setting to be the result of an arithmetic operation upon another setting. Only a simple multiply-and-add calculation is supported. Both the setting modified and the setting that forms part of the arithmetic operation must take integer values, as follows:

  • [DestGroupName] destValueName = ([SrcGroupName] srcValueName * integer) + integer

[DestGroupName] destValueName is given the value of of the arithmetic operation ([SrcGroupName] srcValueName * integer) + integer.

Custom Settings

It is possible to create custom ICF settings that can be used in an application's ICF file.

All such custom settings must be documented, and the Windows debug loader will assert on any undocumented settings. Documentation allows Airplay to check that entered settings are valid, and eliminate the possibility of erroneous settings being added to the application's ICF files.

Document custom ICF settings in a file with the CONFIG.TXT extension. This file must be listed within the "files" section of the application's MKB, or reside in the root application data directory. The documentation should declare the named ICF section in square brackets, followed by user settings (each with a comment) on successive lines. For example:

  • [MySection1]
  • mySetting1 My user setting - should be an integer
  • mySetting2 My other setting - should be a string
  • [MySection2]
  • mySetting3 My user setting 3 - should be an integer
  • mySetting4 My other setting 4 - should be a string

These can then be read in code as follows:

  • int myInt;
  • s3eConfigGetInt("MySection1", "mySetting1", &myInt);
  • char str[0x100];
  • s3eConfigGetString("MySection2", "mySetting4", str);


Airplay SDK: Data Files

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Data Files >

Data Files

Airplay applications are generally required to load and save data to and from the device's persistent storage (generally a memory card or non-volatile memory). The S3E API allows you to achieve this in a way that is uniform and platform-independent.

The S3E API presents a file system to the application, and the S3E implementation for each target platform (OS) maps this file system to a known location on the target platform's native file system. The Deployment Tool ensures that when an S3E application is installed on a target device, the S3E application automatically has access to the data files in the deployed Airplay application package. Generally, this means that the applications installation/private directory will be the default read/write root folder. The application code should specify relative file paths for all file operations and these will then be considered relative to this location.

When using the Windows Simulator, the S3E file system is mapped to a known Windows directory (the application data directory). This defaults to a subdirectory named 'data' directly beneath the directory containing the application MKB file (although the location can be changed using MKB options). For example, if the application data directory contains a file named 'foo.txt', calling s3eFileOpen("foo.txt", "r") will succeed.

The Deployment Tool can collect data files from the application data directory and place them in the installation package for the target platform. In the above example, this process would ensure that when the application is deployed to any device, s3eFileOpen("foo.txt", "r") will also succeed. MKB deployment options can be used to control which files are included in the installation package.

ROM and RAM Drives

There are two deployment scenarios that are supported by the S3E file-system:

  • When the deployed application data is writable; for example, when the application has been installed into writable flash memory on the phone.
  • When the deployed application data is not writable; for example, when the application is run from compressed storage.

The S3E file system and S3E file API ensure that in most cases, no code changes are required in order to deal with both scenarios. To accomplish this, the S3E file system supports two drives, rom:// and ram://. rom:// represents a read-only area, and ram:// represents a read-write area. Both of the drives can be mapped to different locations within the device's native file system. When the user attempts to open a file for reading without specifying a drive, both drives are searched for the file (ram:// first, then rom://). When the user attempts to open a file for writing, ram:// is used exclusively.

When the deployed application data is writable, the rom:// drive is disabled, and all file read and write operations will go to the ram:// drive. This is the common situation for most target platforms. The ram:// drive is usually mapped to the installation directory of the application.

When the deployed application data is not writable, the rom:// drive is mapped to the (read-only) installation directory of the application, and the ram:// drive is mapped to a writable storage area. File read operations (that do not specify an explicit drive) will read files from both drives, and file write operations will write files to the ram:// drive. Thus the application can freely open deployed data files for reading and save-state files for writing without worrying about where the files are being stored.

By default the Windows Simulator emulates the scenario where deployed application data is not writable; the rom:// drive is mapped to the application data directory, which is treated as read-only, and the ram:// drive is mapped to a directory of the same name, but with '-ram' appended (this directory is automatically created if it does not exist). Thus all files written by the application will normally be placed in a subdirectory named 'data-ram' directly beneath the main MKB directory.

Absolute File Paths

Absolute file paths can be specified by using the raw:// prefix. This is useful for debugging on Windows but should not be used on devices since the user may be able to install to different locations/drives, which the game has no control over. It is recommended that an application has all its data files placed in local folders and accesses them using relative file paths. This is particularly important since other areas of memory may not be accessible on many platforms.

File APIs

For more information on using the S3E file system, see the S3E File section of the API Reference. Note that the use of standard library file functions such as fopen() is supported. These wrap the s3eFile functionality and perform as would normally be expected. Note that only binary file access mode (not text file mode) is supported.


Airplay SDK: Memory

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Memory >

Memory

Airplay applications can only allocate memory through the S3E Memory API (the IwUtil memory APIs are simply a higher-level wrapper for the S3E memory API). The S3E Memory API allows memory allocation from a number of separate heaps, the sizes of which are specified by the application ICF file. These heaps are created using native operating system memory on application startup.

Once created, these heaps cannot be resized. Because all memory allocations come from within the S3E heaps, the Airplay application is very unlikely to suffer memory problems caused by the operating system or other external events. The application does have the ability to destroy and re-create heaps, although this behaviour is discouraged. At startup, if there is insufficient memory for the application and its heaps, the S3E implementation will provide the appropriate error message and fail gracefully. Otherwise the application can be expected to run normally.

By default, there is a single S3E memory heap. The IwUtil memory bucket API maps bucket 0 to the single S3E memory heap.

Internally S3E uses the same memory allocation algorithms for all platforms, so there is no possibility of problems arising due to different memory allocation patterns on different devices. Importantly, the contents of the heaps for any given execution point in the Windows Simulator environment can exactly mirror those on device. This means problems caused by reading uninitialised or unallocated data (which might otherwise only show up on one particular device) will almost always show up in the Windows Simulator.

Often, when debugging, additional memory is required to enable debug functionality. To ensure debug and release builds retain the same memory layout, an S3E extension exists that can provide a debug memory heap. Debug-only memory allocations come out of the debug heap, leaving the main heap unaffected. The IwUtil memory bucket API maps bucket 1 to the S3E debug memory heap.

It must be noted that using the C-Runtime library functions can cause different allocation patterns between x86, ARM RVCT and ARM GCC builds, especially when using functions involving FILE pointers. This is due to varying implementations of the C Runtime library for the three compilers. For this reason it is recommended that the S3E API is used directly for file operations.

For more information on using memory heaps, see the S3E Memory section.


Airplay SDK: Device Interoperability.

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Device Interoperability. >

Device Interoperability

Airplay applications must interact correctly with the target devices they run on. This means for example that mobile phone devices must still be able to receive phone calls, receive SMS messages, notify the user of device events such as low battery, etc.

The S3E implementation takes care of the vast majority of these issues automatically. If necessary it will suspend the Airplay application when receiving certain types of device event, and resume the application when it is safe to do so. For example, on an incoming phone call the application is automatically suspended until the call is over. The S3E implementation is also responsible for the managing of media output so that it does not interfere with device operation. For example, incoming SMS message alerts (sounds) and ringtones will still be heard, even if the application is trying to play sound at the same time. The S3E implementation notifies the Airplay application of external events via the S3E callback mechanism.

There is little that the Airplay application has to do explicitly to enable correct inter-operation with a target device. One of the few requirements is that the Airplay application must "yield" frequently to the device operating system, using s3eDeviceYield(). This function allows the S3E implementation to give CPU processing time to the target operating system so that it can handle external device events. Therefore the Airplay application must call the s3eDeviceYield() function frequently to ensure a timely response to external events.

On some operating systems (for example BREW) a significant amount of time must be given up to enable sound to function correctly. For this reason and others, it is strongly recommended that the Airplay application calls s3eDeviceYield() at least once every 10 milliseconds. The application may have to break up functions that take a long time in order to manage this, but the yield function is designed to take a minimal amount of time if called very frequently.


Airplay SDK: Debugging

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Debugging >

Debugging

The Airplay SDK provides a number of debugging features to aid troubleshooting.

Build and Execution Environments

  • x86 Build Environment: Airplay System supports building x86 code using the x86 Debug and x86 Release build configurations. When using a Visual Studio IDE, the x86 Debug configuration supports full use of the Visual Studio debugger and associated features such as Edit and Continue, Conditional Breakpoints, etc.
  • Windows Simulator: The Windows Simulator is a Windows application that wraps an x86 build of an Airplay application (built using the x86 Debug or x86 Release build configurations). It provides a variety of configuration options to simulate different target devices; for example screen size, screen rotation, touchscreen support, etc. It also provides runtime metrics from usage of the Airplay System APIs and Airplay Studio APIs. See Windows Simulator for more information
  • ARM Emulator: Airplay System supports running and debugging ARM binaries on the Windows desktop using a selection of the supported ARM emulators. All ARM binaries that are run on target devices can also be run in the emulator, so nearly all ARM-specific problems can be caught in the ARM emulator without the need for a target device.

ARM Emulator Configuration

Airplay currently supports the following emulators for ARM:

  • GNU Insight Debugger with QEMU
  • ARM Maxview Debugger using ARM Realtime System Model (RTSM)
Which emulator is used can be selected via the Airplay SDK Configuration utility. This is available from the Airplay SDK folder on the Windows start menu (default location: Programs > Airplay SDK > [version] > Airplay SDK Configuration). Using the RTSM emulator requires a separate licence from ARM.

Tracing and Assertions

Airplay System supports runtime assertions and tracing text to a log-file. Both assertions and tracing are supported at two levels; firstly, the S3E Debug API can be used to output to a single channel, and secondly the IwUtil API can be used to output via a series of channels. These include both user-defined channels and predefined channels for each Airplay Studio module and each S3E subdevice. Assertion and tracing functions only produce output in Debug build configurations (in Release configurations, the functions do nothing).

Each S3E subdevice (such as s3eAudio or s3eConfig) and each Airplay Studio module (such as IwUtil or IwAnim) has a pre-defined assertion and trace channel which is turned on by default. The Airplay System runtime will output general information to this channel regarding the usage of the particular subdevice or module.

When running a debug loader, trace information will be output to a text file. The related subdevice name or module name is written at the start of each line of trace output. Applications can also write trace output to these channels, using the IwTrace*() functions. Applications can define custom trace channels simply by specifying a unique channel name; for example:

  • IwTrace(FOO, ("Some text"));

When running a debug loader, assertions are written to the screen. The related subdevice name or module name is also displayed. Applications can also use these assertion channel, using the IwAssert*() functions. Applications can define custom assertion channels simply by specifying a unique channel name, for example:

  • IwAssertMsg(FOO, somevalue > 1, ("Some text"));

Trace and assertion channels can be turned on and off via ICF settings. Turning off a channel stops any output for that specific subdevice/module. This is useful for making the output more readable if you are not concerned with what certain parts of the system are doing. Each part of the system also has a _VERBOSE trace channel which is off by default. Turning this on results in detailed and less important information for that part also being output.

For x86 builds, the trace file is written to the application build directory (i.e. the same directory as the IDE workspace). For ARM builds running on devices, the location of the trace file varies by platform; it is output to a convenient/standard location for the given platform, which is usually the root of an accessible drive or the private folder that the application was installed to. These locations vary to match the platform's standard behaviour and to avoid restrictions on which parts of memory are user-accessible. The following shows the location by platform.

Location of the default trace file on each platform:

  • Platform
  • Windows x86
  • BREW
  • Symbian 7.x S60
  • Symbian 8.x S60
  • Symbian 9.x S60
  • Symbian 9.x UIQ
  • N-Gage
  • Windows Mobile
  • iPhone
  • Trace file output location
  • Application build directory
  • Application's directory
  • Application's directory
  • Application's directory
  • Memory card root folder
  • Memory card root folder
  • Application's private directory
  • Device drive root folder
  • Use XCode Organizer -> Summary -> Applications, and extract the trace file from the Application Data bundle

For more information on using tracing and assertions, see the S3E Debug Overview section. For more information on using the advanced debug functionality, see the Debug section under IwUtil.


Airplay SDK: Extensions

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Extensions >

Extensions

Extensions are Airplay API components that are not commonly available on all platforms, and may be entirely platform-specific.

Airplay provides basic abstraction from the underlying operating system through the S3E API. This allows the same functionality to be performed across all platforms with the same API calls. In contrast, the Extensions APIs provide interfaces for functionality that is only supported on specific platforms or on a subset of supported platforms.

Examples of extensions include:

  • Extra debugging support.
  • Support for launching web pages by URL in the device's browser.
  • Support for platform-specific functionality such as:
    • Micro-transactions on iPhone.
    • iPod music library integration on iPhone.

Using Extensions

To use a specific set of extensions, simply include the relevant header for that set and call the functions as with any other S3E API.

The use of extension functions should be wrapped in checks to make sure that they are only called on devices which support them, in order to avoid unexpected behaviour on incompatible devices. If an extension function is called and it is not supported, it will typically do nothing and return a sensible value such as NULL or 0 depending on the function.

Extensions API Reference

See S3E Extensions in the API Reference for a detailed explanation of using the extensions and full reference listings.


Airplay SDK: Callback Functionality

Airplay SDK > User Guide > Overview of Airplay > Airplay Concepts > Callback Functionality >

Callback Functionality

The S3E API allows you to register callback functions ("callbacks") for certain system events. When a system event occurs, if a callback has been registered for that event type, the callback function is executed.

Two simple examples of system events that can be associated with callback functions include:

  • The ending of an audio track (using the S3E Audio API)
  • The copying of source surface data to the destination surface (using the S3E Surface API)

The ability to register callbacks vastly simplifies the optimisation and customisation of event response. It also relieves you from writing code that would continuously test for such events.

Registering a callback is very simple. Each S3E API which allows the registration of callbacks has a register function. A register function is generally passed three things:

  • The name of the event,
  • The user defined callback function, and
  • Any user data that is required for that callback.

The user defined callback function must conform to the S3E callback type, as defined in Types API Reference. Therefore, the callback must return an int and be able to take two input parameters:

  • void* systemData
  • void* userData


Airplay SDK: Airplay Application Development Workflow

Airplay SDK > User Guide > Overview of Airplay > Airplay Application Development Workflow >

Application Development Workflow

The Application Development Workflow is the process used to create an application, from the creation of artwork, through coding, testing and debugging, to the deployment of the application to a device. Each part of this process is crucial to creating an application and may often be carried out by many different people.

The image below shows a simplified version of the process for creating an application. The art assets are converted using the Airplay Studio Tools and added into the application built using the Airplay SDK. This creates a single binary that can be used by the deployment tool to create an application to run on any of the different platforms.

Airplay Development Process

The content pipeline in Airplay Studio is simple and flexible, and can integrate into any established studio workflow.

  • Creating Art Assets
  • Creating an Application Project
  • Test and Debug
  • Deployment to Device


Airplay SDK: Creating Art Assets

Airplay SDK > User Guide > Overview of Airplay > Airplay Application Development Workflow > Creating Art Assets >

Creating Art Assets

Virtually every application requires art assets of some kind.

2D images can be created in any art package. Airplay Studio supports importing many different standard image formats. See Image Manipulation for a definitive list.

3D models can be created in any supported 3D modelling package. Airplay provides exporter plugins (the Airplay Studio Exporters) to export 3D scene data to intermediate text files that can be read by the Airplay Studio runtimes.

Exporting Assets

The Airplay Studio Exporters are plugins for 3D modelling packages. These are used to export assets into specially formatted text files that are readable by the Airplay runtimes.

There are many ways of making art assets for an application, and these will depend on the art pipeline you use, as well as specific requirements that the application imposes. The Airplay Studio Exporters try to accommodate these different requirements and thus offer different methods for the export of assets.

There are several preset options for exporting assets, which allow the export of models, rigged characters, animations, and materials, up to entire 3D scenes. It is important to understand the different types of assets and how they can be used within the an application. For more information on these Export Types see the Export Types section in the Airplay Tools Reference.

For more information on the Airplay Studio Exporters, see the Airplay Studio Exporters section of the Airplay Tools Reference

Asset Management

Airplay Studio Director allows the creation of a project space to manage application assets once they are exported. Director can also be used to view assets using the Airplay Studio Viewer, edit assets either within the program or within an external editor, and create reports about the assets within a project including information about any data dependencies.

For more information on the Airplay Studio Director, see the Airplay Studio Director section of the Airplay Tools Reference


Airplay SDK: Creating an Application Project

Airplay SDK > User Guide > Overview of Airplay > Airplay Application Development Workflow > Creating an Application Project >

Creating an Application Project

The project makefile, workspace and programming IDE

Programmers work within an Integrated Development Environment ("IDE") such as Microsoft Visual Studio. For each application, the IDE requires a "workspace" file (for instance, Visual Studio 2008 requires a SLN file).

Airplay provides a level of abstraction from the IDE workspace file, using the MKB text file format. Programmers specify their code project using the MKB text file. This file lists, for example, the source and header files used to compile the project. For more information on MKB files see Airplay Concepts > MKB Files.

The MKB file is written in any text editor. The programmer then double-clicks this file to automatically generate the IDE workspace of their choice (for example, the SLN file for Visual Studio 2008). Programmers never edit the IDE workspace file directly; instead, they edit the MKB file(s). This allows Airplay projects to be moved seamlessly between different IDEs.

Once the MKB file has been created, it can be run to create the project with all the settings and files linked together as required. The coding of the application can then begin.

Airplay System and Airplay Studio

Airplay System provides a set of simple C APIs that can easily be combined with an application main loop. Typically an application main loop will run until some exit conditions are met. Exit conditions are application defined by the application, but should always respect the device operating system's own "exit" event (for example, if the user elects to quit the application through some OS mechanism). The application must also 'yield' to the device operating system periodically, to ensure correct inter-operation of the device and the application.

Airplay Studio provides higher-level C++ APIs that support many rich features across a number of modules. Typically each module must be initialised before use and terminated on shutdown explicitly.


Airplay SDK: Test and Debug

Airplay SDK > User Guide > Overview of Airplay > Airplay Application Development Workflow > Test and Debug >

Test and Debug

The Airplay x86 runtime environment is known as the Airplay Windows Simulator. This is designed to model, as closely as possible, all aspects of the target devices, and to expose issues within the IDE before testing on device. Application screen size, available heap memory, available stack memory, portrait or landscape display, CPU/GPU load balancing of graphics pipeline and many more parameters can all be configured and respected within the Airplay Windows Simulator.

The x86 build of the application can be debugged within the Airplay Windows Simulator, as well as within some of the OS-specific simulators (e.g. the BREW simulator, the Symbian 8 (S60 2nd edition) simulator).

Airplay offers a unique innovation by providing a full build-and-debug cycle for ARM code directly within the development environment. This provides the ability to test and debug, within a PC environment, the exact ARM code that will be run on a device. Having built the single application binary within an ARM build configuration, it can then be executed within the supported desktop ARM Emulators, and debugged within the supported ARM debuggers.

Airplay includes support for two real-time ARM Emulators, which allows execution of the single ARM binary on the desktop, and support for source-level and disassembly-level debugging of the ARM binary on the desktop.


Airplay SDK: Deployment to Device

Airplay SDK > User Guide > Overview of Airplay > Airplay Application Development Workflow > Deployment to Device >

Deployment to Device

The building of an application using the Airplay SDK results in a single platform-independent native application binary, known as an 'S3E file'. This file can be used by the Deployment Tool to create platform-specific installation packages for the target devices.

Deployment to specific platforms (operating systems) is achieved as follows:

  • Build the application in an ARM build configuration. This generates a "single application binary", or S3E file.
  • Use the Airplay Deployment tool to package the S3E file into a platform-specific (OS-specific) installer file.
  • Use the Airplay Deployment Tool, or any other mechanism, to send the platform-specific installer file to the device.

For a detailed explanation of the deployment process and using the Airplay Deployment Tool, see the Deploying to Device documentation.


Airplay SDK: Creating an Application

Airplay SDK > User Guide > Creating an Application >

Creating an Application

This section will take you through the process of building a basic Hello World application from scratch using Airplay. It will introduce some of the main components and concepts of Airplay and provide a typical application structure upon which more advanced applications can be based.

The following steps are required in order to create an Airplay application:

  • Set-up a typical directory structure in which to place the application source and data files.
  • Configure the project by creating an MKB file.
  • Configure run time options by creating an ICF file.
  • Add source code utilising Airplay APIs.
  • Use the MKB file to generate an IDE project for the application.
  • Build and debug the project.
  • Configure deployment settings and deploy to a device.

The sections below step through the process of creating the Hello World application:

  • Creating Project Folders
  • Configuring the Project (MKB File)
  • Configuring Runtime Options (ICF File)
  • Creating a Main Application Loop
  • The Hello World Source File
  • Building the Hello World Project
  • Building for the Windows Simulator and Debugging
  • Building for ARM and Deploying to Devices


Airplay SDK: Creating Project Folders

Airplay SDK > User Guide > Creating an Application > Creating Project Folders >

Creating Project Folders

A folder must be created for all the project's files to be placed within. The files for the project can be divided between the source code for the application and data files - such as audio, graphics and configuration files - that the application will use. A data directory is required for the data files to be placed within. This can be anywhere under our project folder, the default location being a subfolder called "data". Source code can also be placed at any location within the project folder but it is sensible to place it within a distinct subfolder.

To set up project folders:

  1. Create a new top-level project folder called "HelloWorld" at any location.
  2. Create a new folder within "HelloWorld" called "data".
  3. Create a new folder within "HelloWorld" called "source".

The files to be included in the project and their folder locations will now be specified via the project's MKB file.

Next Step

Configuring the Project (MKB File)


Airplay SDK: Configuring the Project (MKB File)

Airplay SDK > User Guide > Creating an Application > Configuring the Project (MKB File) >

Configuring the Project (MKB File)

MKB files are used to configure build settings for a project. The MKB specifies all the information required to generate a Visual Studio project, build the project and deploy the compiled application to devices. Within the MKB, as standard, are the definitions for the subdirectories that are to be included, the position of the data directory, and the names of the files that make up the project.

The Hello World project will require the following source files:

  • HelloWorld.cpp
  • HelloWorldMain.cpp

The data directory created earlier is also specified here. This is where any application assets live and also is the default location for the application ICF file which is used for runtime configuration. if no data directory is specified, the default of "data" is used.

Creating the MKB File:

  1. Open a new text file.
  2. Add the following code to it:

    • options
    • {
      • s3e-data-dir="data"
    • }
    • files
    • {
      • (source)
      • HelloWorld.cpp
      • HelloWorldMain.cpp
    • }
    • subprojects
    • {
      • iwutil
    • }

  3. Save it as "HelloWorld.mkb" within the HelloWorld folder created earlier.

The s3e-data-dir option sets the position at which the project will look for its data files and ICF. Since we are using the default location, this line is not strictly necessary. The files command sets which files are included in the project, and the subprojects command includes other projects from which functionality will now be available.

All files are assumed to be relative to the MKB unless full paths are given. The (source) line indicates that the subsequent files are within a subfolder called "source".

For more information on using MKB files, see Airplay Concepts > MKB Files. For a list of available options, see MKB File Settings.

Next Step

Configuring Runtime Options (ICF File)


Airplay SDK: Configuring Runtime Options (ICF File)

Airplay SDK > User Guide > Creating an Application > Configuring Runtime Options (ICF File) >

Configuring Runtime Options (ICF File)

The application ICF file allows runtime configuration options to be set for an application. These can contain a wide range of settings which are read in when the application starts. They may be used to specify different behaviour between platforms/devices, to configure memory usage, change input controls, disable specific functionality, and more. As they do not affect the build or deployment processes at all, during development the ICF settings may be edited post-deployment in order to quickly try out different configurations or for debugging purposes.

By default, the project will look for an ICF file called "app.icf" in its data directory. This can be changed by using the app-icf option in the project's MKB file.

To create the ICF file:

For the Hello World application we will set some very simple options:

  1. Open a new text file.
  2. Add the following code to the file:

    • [S3E]
    • SplashscreenBkR=255
    • SplashscreenBkG=255
    • SplashscreenBkB=255
    • MemSize = 1000000

  3. Save the file as "app.icf" within the data directory created earlier (HelloWorld/data).

The ICF file above includes some simple settings to demonstrate its use. The Splashscreen* options instruct the game to display a splash screen with the given RGB colours at start-up. More splashscreen options are available such as displaying a .jpg image. MemSize sets a limit on the amount of memory that the application can use at runtime.

The [S3E] line specifies a subsection. All the settings below it are assumed to be from the S3E group of settings. Other groups exist such as [Graphics] (animation), [GL] (OpenGL) and [Util] (utilities) as defined in the ICF File Settings.

For more information on using ICF files, see Airplay Concepts > ICF Files. For a list of available options, see ICF File Settings. It is also possible to create Custom Settings.

Next Step

Creating a Main Application Loop


Airplay SDK: Creating a Main Application Loop

Airplay SDK > User Guide > Creating an Application > Creating a Main Application Loop >

Creating a Main Application Loop

A typical approach to structuring an Airplay application is to use a main loop with standard maintenance functions and application-specific functions being repeatedly called form within it. For Hello World, we will create a source file for this main application loop, HelloWorldMain.cpp, and another, HelloWorld.cpp, for the functions that are to be called.

This source file specifies an entry point function, main() which contains our main loop. Within the loop, we call important maintenance functions and the following functions (which will be defined in the HelloWorld.cpp file):

  • ExampleInit()
  • ExampleUpdate()
  • ExampleRender()
  • ExampleShutDown()

Initialisation will be carried out in the ExampleInit() function, ExampleUpdate() will handle updating any variables, and ExampleRender() will perform rendering to the screen. The loop continues until some end condition is met, at which point ExampleShutDown() will perform any termination steps required.

The following Airplay functions are also used:

  • s3eDeviceYield()
  • s3eKeyboardUpdate()
  • s3eKeyboardGetState()
  • s3eDeviceCheckQuitRequest()
  • s3eSurfaceShow()

s3eDeviceYield() is called to return control to the OS temporarily in order for it to perform critical device functionality. This may include allowing task switching to take place, incoming calls to be processed, background tasks to update themselves and so on. This is also the point at which any callback functionality would take place. s3eKeyboardUpdate() must be called once before checking any key presses in order to update the internal keyboard state, after which s3eKeyboardGetState() can be used to check for key presses (in this case it quits the loop). s3eSurfaceShow()is called to update the device screen and s3eDeviceCheckQuitRequest() checks for any requests to quit from the loader or OS, at which point it breaks out of the loop to terminate the example.

Creating the HelloWorldMain.cpp file:

  1. Open a new file.
  2. Add the following code to it:

    • //--------------------------------------------------------------------------
    • // HelloWorld main file
    • //--------------------------------------------------------------------------
    • #include "s3e.h"
    • // Externs for functions which examples must implement
    • void ExampleInit();
    • void ExampleShutDown();
    • void ExampleRender();
    • bool ExampleUpdate();
    • //--------------------------------------------------------------------------
    • // Main global function
    • //--------------------------------------------------------------------------
    • S3E_MAIN_DECL void IwMain()
    • {
    • #ifdef EXAMPLE_DEBUG_ONLY
    • // Test for Debug only examples
    • #endif
      • // Example main loop
      • ExampleInit();
      • while (1)
      • {
        • s3eDeviceYield(0);
        • s3eKeyboardUpdate();
        • bool result = ExampleUpdate();
        • if (
          • (result == false) ||
          • (s3eKeyboardGetState(s3eKeyEsc) & S3E_KEY_STATE_DOWN)
          • ||
          • (s3eKeyboardGetState(s3eKeyLSK) & S3E_KEY_STATE_DOWN)
          • ||
          • (s3eDeviceCheckQuitRequest())
          • )
          • break;
        • ExampleRender();
        • s3eSurfaceShow();
      • }
      • ExampleShutDown();
    • }

  3. Save the new file using the name "HelloWorldMain.cpp" to the HelloWorld/source/ folder created earlier.

Next Step

The Hello World Source File


Airplay SDK: The Hello World Source File

Airplay SDK > User Guide > Creating an Application > The Hello World Source File >

The Hello World Source File

The final element needed for the application is the main source file. This source file implements the functionality to display the phrase "Hello World" on screen.

The main function used to achieve this is s3eDebugPrint() which requires 's3eDebug.h' to be included. The function is fed an output string and a screen position. The string begins with a special formatting string, "`x000000" (note the use of ` and not a regular apostrophe), which in this case causes the text to be printed in black. See the s3eDebugPrint reference for more information.

To creating the application source file:

  1. Create a new text file.
  2. Add the following code to it:

    • #include "s3e.h"
    • #include <memory.h>
    • //--------------------------------------------------------------------------
    • void ExampleInit()
    • {}
    • //--------------------------------------------------------------------------
    • void ExampleShutDown()
    • {}
    • //--------------------------------------------------------------------------
    • bool ExampleUpdate()
    • {
      • return true;
    • }
    • //--------------------------------------------------------------------------
    • // The following function clears the screen and outputs the
    • // phrase "Hello World". It uses The s3eDebugPrint() function
    • // to print the phrase.
    • //--------------------------------------------------------------------------
    • void ExampleRender()
    • {
      • // Get pointer to the screen surface
      • // (pixel depth is 2 bytes by default)
      • uint16* screen = (uint16*)s3eSurfacePtr();
      • int height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);
      • int width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
      • int pitch = s3eSurfaceGetInt(S3E_SURFACE_PITCH);
      • // Clear screen to white
      • for (int i=0; i < height; i++)
      • {
        • memset((char*)screen + pitch * i, 255, (width * 2));
      • }
      • // Print Hello World
      • s3eDebugPrint(10, 20, "`x000000Hello World", 0);
    • }

  3. Save the file as "HelloWorld.cpp" in the source folder.

Next Step

Building the Hello World Project


Airplay SDK: Building the Hello World Project

Airplay SDK > User Guide > Creating an Application > Building the Hello World Project >

Building the Hello World Project

With project files assembled and an MKB file set up to include them, the project can now be built and deployed using the MKB. Building can be performed using a supported IDE (for example Microsoft Visual Studio) or without an IDE by using the included open source build system SCons.

See System Requirements > Development Environments for a list of supported IDEs.

Creating an IDE Project

If a supported IDE such as Microsoft Visual Studio is present on the development machine, when Airplay was installed a file association will have been set up to generate a project for the IDE whenever an MKB file is run. The project generated will have all the relevant compiler and build options set so that all that is required is to hit Build. The lists of source files and folders that were entered in the MKB earlier, plus any Airplay sub-projects/modules (MKFs) that were specified, are used to generate the included files in the IDE.

If more than one supported IDE is installed, the default build environment can be changed using the Airplay SDK Configuration utility. This is available from the Airplay SDK folder on the Windows start menu (default location: Programs > Airplay SDK > [version] > Airplay SDK Configuration). It can also be overridden for a specific project by adding the buildenv= setting to the MKB followed by the desired IDE name. If the buildenv is set to "SCONS", Scons will be used to build the application without generating an IDE project and by default all available ARM versions (GCC/RVCT and Debug/Release) will be built unless specified otherwise by the MKB build settings.

To create the Hello World project:

  • Simply double click on HelloWorld.mkb in Windows Explorer.
  • The project will open automatically in your preferred supported IDE, with project files created in a conveniently named sub folder (for example, build_helloworld_vc6. for Visual Studio 6).
  • Observe that the Hello World source files, the core API headers (Airplay System (S3E)) and the subproject (IwUtil) are all included in the solution explorer. The MKB file HelloWorld.mkb is automatically included in the project for convenience.
  • To re-open an existing project, double-click the MKB again. Although a project could be opened using the generated project files, using the MKB will update any IDE settings that need changing if any alterations have been made to the MKB file itself.

Building from the IDE

An Airplay application is compiled in the same way as any regular application is within the IDE being used.

In the IDE's active configuration dialog there will be an entry for each configuration that Airplay supports:

  • (x86) Debug
  • (x86) Release
  • GCC (ARM) Debug
  • GCC (ARM) Release
  • RVCT (ARM) Debug
  • RVCT (ARM) Release

The x86 builds use the Microsoft x86 compiler to produce binaries for running on x86/Windows while the ARM builds use the GCC or RVCT compilers to produce binaries for running on ARM architecture devices. See Airplay Concepts > Loader/Binary System for an overview of the build types and compilers supported.

The Debug configurations each support a variety of debugging related functionality, while for Release builds this functionality is either disabled by default or unavailable. Release builds are optimised to run as fast as possible and should be used for creating release versions of the application.

The usual process for developing and debugging an application is to compile for x86, to efficiently test generic functionality in Windows first, and then to deploy ARM builds to the relevant devices to work out any device-specific issues. Windows debugging is performed using the Windows Simulator tool.

Next Step

Building for the Windows Simulator and Debugging


Airplay SDK: Building for the Windows Simulator and Debugging

Airplay SDK > User Guide > Creating an Application > Building for the Windows Simulator and Debugging >

Building for the Windows Simulator and Debugging

In order to debug an application efficiently without having to deploy to a device repeatedly, Airplay includes the Windows Simulator tool. The Simulator is a wrapper for running x86 compiled versions of applications and as such requires the application to be built using the x86 Debug or x86 Release configurations. Airplay x86 applications are .dlls rather than .exes and will not run without the tool present. The Windows Simulator displays a window representing the "device surface" which defaults to 320 x 240 pixels in size. This window is resizable for easier viewing and can be configured to simulate a wide range of devices through the various menus.

See the Windows Simulator reference for a complete list of available configuration settings.

An application can be compiled and run using the Simulator and then easily debugged using the combined functionality of the IDE and Airplay. Often more effective debugging can be performed in Windows due to the constrained nature of many of the devices and platforms running on them. For example, many devices have restricted memory access and the OS may not provide on-device debugging functionality.

Both Debug and Release Airplay builds can be compiled for and debugged in the Windows Simulator. Debug builds have features such as tracing and assertions turned on by default and certain API features will only work for this build type.

To build Hello World for x86 and run in the Windows Simulator:

  1. Open the IDE's build configuration dialog. For example, in Visual Studio either click the Solution Configurations drop down menu on the toolbar or click Build > Set Active Configuration... to open the Set Active Project Configuration dialog.
  2. Select one of the x86 build configurations:
    • (x86) Debug
    • (x86) Release
  3. Select the IDE's build solution/project option. For example, press F7 or click Build > Build <project name> in Visual Studio.
  4. Once the project is built, select the IDE's run option to launch the application in the Windows Simulator. For example, press F5 or click Start Debugging from the Build/Debug menu in Visual Studio.
  5. A screen like the following will be displayed in the Windows Simulator:

    The Hello World application window

  6. Try using the IDE's debug functionality. Trace output from the application will be displayed in the IDE's output window and code execution can be paused and stepped through.
  7. Try altering the various options in the Simulator's menus.

For more information on Airplay debugging functionality, see Airplay Concepts > Debugging.

Next Step

Building for ARM and Deploying to Devices


Airplay SDK: Building for ARM and Deploying to Devices

Airplay SDK > User Guide > Creating an Application > Building for ARM and Deploying to Devices >

Building for ARM and Deploying to Devices

Airplay supports two compilers for ARM:

  • Codesourcery GCC ARM
  • ARM RVCT (version 3.0 and above)

These are referred to as "GCC" and "RVCT" respectively and need to be installed separately in order to make use of them. The result of building either ARM build configuration is a file with an S3E extension.

Usage of the ARM RVCT compiler requires downloading and licensing the RealView Development Suite (RVDS) from ARM. ARM provide a 30-day free evaluation version of RVDS, available at www.arm.com

ARM builds can be deployed to Device using the Deployment Tool or run on the Windows desktop though the QEMU ARM emulator using the same .s3e binaries. The emulator provides a means for testing arm code without the need for a physical device, however it is important to bare in mind it will not show up device-specific problems or allow testing of device inter-operation situations like receiving calls and interacting with the OS.

To build Hello World for ARM:

  1. Open the IDE's build configuration dialog. For example, in Visual Studio either click the Solution Configurations drop down menu on the toolbar or click Build > Set Active Configuration... to open the Set Active Project Configuration dialog.
  2. Select one of the ARM build configurations:
    • GCC (ARM) Debug
    • GCC (ARM) Release
    • RVCT (ARM) Debug
    • RVCT (ARM) Release
  3. Select the IDE's build solution/project option. For example, press F7 or click Build > Build <project name> in Visual Studio.
  4. Once the project is built, select the IDE's run option (F5 in Visual Studio) to either run the application in an emulator or launch the Deployment Tool (see below).

To debug in the ARM Emulator:

If an ARM Debug build configuration, for example GCC (ARM) Debug, is selected in the IDE and run is chosen, the application will be launched in the ARM emulator.

To deploy the build to an ARM device:

If an ARM Release build configuration, for example GCC (ARM) Release, is selected in the IDE and run is chosen, the Airplay System Deployment Tool is launched. This tool combines the application's S3E binary file with a platform-specific binary called the Loader to create a platform-specific version of the application.

To deploy the Hello World application to a device, see Using the Deployment Tool. If deploying to a platform that requires the application to be signed - e.g. NGage or iPhone - then the relevant security and certification options need to be set (see Platform-Specific Deployment Requirements). Otherwise no further configuration is required; simply step through the stage-by-stage instructions in the tool to deploy the build to the device.


Airplay SDK: API Examples

Airplay SDK > User Guide > API Examples >

API Examples

The SDK provides a set of examples that illustrate how to use some of the functionality contained within Airplay.

For each Airplay System subdevice and each Airplay Studio module, an example application has been included to illustrate the functionality of that specific component.

Examples can be found in the 'examples' folder under the Airplay SDK installation directory.

The examples all use a common framework which is demonstrated in the Example Structure, and used within a basic "hello world" application.

  • Example Structure
  • S3E Hello World Example

Airplay System

The following examples demonstrate the use of the low-level components that make up Airplay System (S3E):

  • S3E Audio Basic Example
  • S3E Audio Advanced Example
  • S3E Accelerometer Example
  • S3E Compression Basic Example
  • S3E Configuration Example
  • S3E Launcher Example
  • S3E Event Example
  • S3E File IO Basic Example
  • S3E Memory Example
  • S3E Socket Example
  • S3E Sound Basic Example
  • S3E Sound Advanced Example
  • S3E Sound Streaming Example
  • S3E Surface Example
  • S3E Timer Basic Example
  • S3E Timer Advanced Example
  • S3E Vibra Example
  • S3E Video Example

Airplay Studio

The following examples demonstrate the use of higher-level components from the Airplay Studio modules:

  • Derbh (compression)

    • Derbh Basic Example

  • IwUtil (utility)

    • Class Factory Example
    • Hash Example
    • Image Format Example
    • Managed Object Example
    • Text Parsing
    • Serialising Example
    • Key Mapping Example
    • Memory Utility Example
    • Array Example
    • Debug Example
    • Debug Menu Example
    • Random Number Example

  • IwGeom (geometry)

    • Primitives Example
    • Matrix Rotation Example
    • Vectors Example

  • IwGx (2D and 3D drawing)

    • IwGx Polygon Display Example
    • IwGx Drawing Modes Example
    • IwGx Coordinate Spaces Example
    • IwGx Texture Examples:
      • IwGx Texture Example
      • IwGx CIwTexture Example
    • IwGx Lighting Examples:
      • IwGx Basic Lighting Example
      • IwGx Lighting Example
    • IwGx Surface Examples:
      • IwGx Surface Offscreen Example
      • IwGx Surface Post Process Example
    • IwGx Billboards Example
    • IwGx DebugPrim Example
    • IwGx Resource Groups Example
    • IwGx Alpha Modes Example
    • IwGx UV Animation Example

  • IwResManager (resource management)

    • IwResManager Groups Example
    • IwResManager Resource Search Example
    • IwResManager Templates Example
    • IwResManager Advanced Resource Search Example
    • IwResManager Resource Handler Example

  • IwGraphics (model-rendering)

    • Example IwGraphics Model
    • Example IwGraphics Model Two
    • Example IwGraphics Model Builder
    • Example IwGraphics Manual Model Builder
    • Example IwGraphics Resource Groups
    • IwGraphics Model Builder Callbacks Example

  • IwAnim (animation)

    • Animation Rendering Example
    • Animation Playback Example
    • Animation Skeleton Example
    • Animation SubSkeleton Example
    • IwAnim Offset Example

  • IwGxFont (texture-based fonts)

    • IwGxFont Basic Example
    • IwGxFont Parameters Example
    • IwGxFont Clipping Example
    • IwGxFont 3D Example
    • IwGxFont Browser Example

  • IwUI (high-level UI framework)

    • IwUI Hello World Example
    • IwUI Hello World Dynamic Example
    • IwUI Dynamic Population Example
    • IwUI Layout Example
    • IwUI Localise Example
    • IwUI Stylesheets Example
    • IwUI Calculator Example
    • IwUI Data Binding Example
    • IwUI RSS Example
    • IwUI Signals and Slots Example
    • IwUI Widgets Example
    • IwUI Animation Example

  • IwHTTP (HTTP requests)

    • IwHTTP Example


Airplay SDK: Example Structure

Airplay SDK > User Guide > API Examples > Example Structure >

Example Structure

The source file for each example application has been included for your convenience. Definitions of functions are contained within the example headers, so these are not visible within the quoted examples.

Every example is written in a similar format, containing at least the four following functions:

  • ExampleInit()
  • ExampleUpdate()
  • ExampleRender()
  • ExampleShutDown()

Each function is called in a loop, which is implemented using the ExampleMain file. This file contains the following code:

S3E_MAIN_DECL void IwMain()
{
#ifdef EXAMPLE_DEBUG_ONLY
    // Test for Debug only examples
#ifndef IW_DEBUG
    DisplayMessage("This example is designed to run from a Debug build.
Please build the example in Debug mode and run it again.");
    return;
#endif
#endif

    // Example main loop
    ExampleInit();
    while (1)
    {
        s3eDeviceYield(0);
        s3eKeyboardUpdate();

        int64 start = s3eTimerGetMs();

        bool result = ExampleUpdate();
        if  (
            (result == false) ||
            (s3eKeyboardGetState(s3eKeyEsc) & S3E_KEY_STATE_DOWN) ||
            (s3eKeyboardGetState(s3eKeyLSK) & S3E_KEY_STATE_DOWN) ||
            (s3eDeviceCheckQuitRequest())
            )
            break;

        ExampleRender();

        // Attempt frame rate
        while ((s3eTimerGetMs() - start) < MS_PER_FRAME)
        {
            int32 yield = (int32) (MS_PER_FRAME - (s3eTimerGetMs() - start));
            s3eDeviceYield(yield);
        }
    }
    ExampleShutDown();
}

In each example, initialisation is carried out in the ExampleInit() function, any updating of values for each loop is carried out in the ExampleUpdate() function, and any update of output to screen is carried out in the ExampleRender() function.

Each example also requires the following items:

  • Application MKB File
  • Application Data Directory
  • Application ICF File

For information on these project elements and how they are created, see Airplay Concepts.

For a walkthrough of building a basic project, see Creating an Application.


Airplay SDK: S3E Hello World Example

Airplay SDK > User Guide > API Examples > S3E Hello World Example >

S3E Hello World Example

The following example, in typical Hello World style, displays the phrase "Hello World" on screen.

The functions required to achieve this are:

  • s3eDebugPrint()

All examples will follow this basic pattern; a brief description of what the example does will be given followed by a list of all the important functions and, perhaps, classes.

Should the example be more complex, a more detailed explanation of what the example does and how it does it will be added.

//-----------------------------------------------------------------------------
// ExampleS3EHelloWorld
//-----------------------------------------------------------------------------

#include "ExamplesMain.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{}

//-----------------------------------------------------------------------------
void ExampleShutDown()
{}

//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs the phrase "Hello World" to screen. It uses
// The s3eDebugPrint() function to print the phrase.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Print Hello, World
    s3eDebugPrint(50, 100, "`x666666Hello, World", 0);
}


Airplay SDK: Simple Game Tutorials

Airplay SDK > User Guide > Simple Game Tutorials >

Simple Game Tutorials

The Airplay Tutorials provide practical examples to aid in learning about the different components of the Airplay SDK. These examples are tailored for novice users of Airplay, who have a good understanding of programming in C++.

Tutorials for the Airplay Art Tools are found in the Tutorials section of the Airplay Art Tools Reference.

More tutorials will be added in the future.

  • Rendering an Animated Character Using Airplay Studio
  • Rendering a World With Multiple Instances Using Airplay Studio


Airplay SDK: Rendering an Animated Character Using Airplay Studio

Airplay SDK > User Guide > Simple Game Tutorials > Rendering an Animated Character Using Airplay Studio >

Rendering an Animated Character Using Airplay Studio

This tutorial walks you through a simple example of how to render an animated character using Airplay Studio. You will learn how to export a model from your 3D art package and how to render the animated character from an Airplay code project.

Building and exporting the assets

The art files for this tutorial are found in the sdk install\examples\games\beattoy\art\combateva\, files for each 3D modelling package are within appropriately named folders.

Exporting the Model

The character is exported in two sections. First the rig is exported. This includes the skin and skeleton and all the controllers. Within the game, the base file is used for all animations for the character, so the animations should all use an exact copy of the rig, else errors will occur.

The Rigged Character

  • Open the file combatEva_rig in your preferred 3D Modelling Package
  • Open the Exporter Dialog
  • Choose an appropriate project (if required create a new project for this tutorial and add a data directory)

    • The Exporter Dialog

  • Choose a Model Export if not already selected
  • Change the 'Save to Location' option to 'data'

    • The Exporter Dialog

  • Leave all the other options as they are already set
  • Click Export

Exporting the Animations

The animations for a character are usually exported from separate source files. The animation is the only thing that is saved within an 'anim' Export; all the information about the character is stored when the initial rig is exported, as completed above.

The Animated Character

  • Open the file combatEva_anim in your preferred 3D Modelling Package
  • Open the Exporter Dialog
  • Select the same project as before
  • Choose a anim Export
  • Change the 'Save to Location' option to 'data'

    • The Exporter Dialog

  • Leave all the other options as set
  • Click Export

Rendering the animated character

Now we must write the code to render the character in the application.

We include the headers of the modules we will be using.

  • IwGx provides low-level rendering API, abstracting software and hardware rendering.
  • IwGraphics provides a higher-level API that renders models.
  • IwAnim extends IwGraphics, providing skinned animation.
  • IwResManager provides resource management - the loading and binarising of assets.
#include "IwAnim.h"
#include "IwGraphics.h"
#include "IwGx.h"
#include "IwResManager.h"

The entry point (where the code starts executing) is the standard c main function.

int main()
{

Airplay Studio modules must be explicitly initialised before use. Modules may implicitly initialise other modules they depend on. In this example IwGx will initialise IwResManager.

    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

Now we load our animated character. Airplay Studio resources are held in atomic units called resource groups (.group files). A resource group contains one or more resources.

A .group file is a human readable text file specifying which resource are contained in the group.

The group for this example looks like:

// Source file: C:/Dev/sdk/main/sdk_examples/ArtAssets/combatEva/Maya7/combatEva_rig.mb
// Exported By:  on 04/03/08 17:04:26

CIwResGroup
{
 name "combatEva"
 "./models/combatEva.geo"
 "./models/combatEva_rig.skel"
 "./models/combatEva.skin"
 //animations
 "./anims/LfFwShuffle.anim"
 "./anims/armUpFullAnim.anim"
 //subanims
 "./anims/armUpSubAnim.anim"
}

As you can see, her model (.geo), skeleton (.skel), skin (.skin) and animations (.anim) are all resources included in the group file.

To load a group we simply call the LoadGroup method of the resource manager singleton.

    IwGetResManager()->LoadGroup("combatEva.group");

Once the group file has been loaded, the resource manager singleton can retrieve resources by name and type.

Let's retrieve the resources from the group. Notice that the resource's name is the filename without the extension. Each resource is asked for by its name and its c++ type.

    CIwModel* pModel = (CIwModel*)IwGetResManager()->GetResNamed("combatEva", "CIwModel");
    CIwAnimSkin* pSkin = (CIwAnimSkin*)IwGetResManager()->GetResNamed("combatEva", "CIwAnimSkin");
    CIwAnimSkel* pSkel = (CIwAnimSkel*)IwGetResManager()->GetResNamed("combatEva_rig", "CIwAnimSkel");
    CIwAnim* pAnim = (CIwAnim*)IwGetResManager()->GetResNamed("LfFwShuffle", "CIwAnim");

To play an animation on a model we create a CIwAnimPlayer object, set the skeleton and play the animation. The animation player contains its own copy of the skeleton which it will pose according to the current interpolated frame of the animation.

    CIwAnimPlayer* pPlayer = new CIwAnimPlayer;
    pPlayer->SetSkel(pSkel);
    pPlayer->PlayAnim(pAnim, IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F);

We keep track of how many milliseconds elapse every frame to play the animation at a constant speed independent of the framerate.

    uint64 lastFrame = s3eTimerGetMs();

Now we enter the main loop. The exit condition is s3eDeviceCheckQuitRequest. This will return true if the OS requires us to exit. In the windows simulator this will be when the close icon is clicked.

    while(!s3eDeviceCheckQuitRequest())
    {

First of all, update the player according to how long the last frame took.

The return value of s3eTimerGetMs() is in milliseconds, while update takes a value based on fixed-point seconds. In Airplay Studio fixed-point numbers are in 1.19.12 bit format - IW_GEOM_ONE is defined to be (1 << 12).

        uint64 now = s3eTimerGetMs();
        pPlayer->Update((uint32)(now - lastFrame) * IW_GEOM_ONE / 1000);
        lastFrame = now;

Now we begin rendering.

First of all we clear the screen.

        IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

Set a simple camera matrix.

Starting from identity (which means looking along the positive Z axis from the origin) we move backwards along the Z axis, upwards along the Y axis, and finally rotate 180 degrees around the Z axis. Rotations are specified in fractions of an entire revolution i.e. IW_GEOM_ONE is 360 degrees. This final rotation is required because positive Y is downwards in screenspace - (0,0) is the top left hand corner of the screen.

        CIwMat view = CIwMat::g_Identity;
        view.t.z -= 200;
        view.t.y += 100;
        view.PostRotateZ(IW_GEOM_ONE/2);
        IwGxSetViewMatrix(&view);

Set the model matrix.

In this example we just rotate Eva 120 degrees around the Y axis so she's facing us, but slightly askew (she is looking down the Z axis in maya).

        CIwMat model = CIwMat::g_Identity;
        model.SetRotY(IW_GEOM_ONE/3);
        IwGxSetModelMatrix(&model);

We must set the animation context so the model gets the skeleton from the player when it renders.

        IwAnimSetSkelContext(pPlayer->GetSkel());
        IwAnimSetSkinContext(pSkin);

Now we actually render the model. This will submit draw commands to iwgx. Nothing will actually be rendered until IwGxFlush is called.

        pModel->Render();

Although not strictly necessary in this example it's good practice to return the anim context to its default state, so errors when rendering future characters without setting up the context correctly are easier to understand.

        IwAnimSetSkelContext(NULL);
        IwAnimSetSkinContext(NULL);

IwGxFlush commits all the drawing commands to the renderer.

        IwGxFlush();

Finally we call IwGxSwapBuffers to present the rendered output to the screen.

        IwGxSwapBuffers();

Airplay applications are co-operatively threaded. This means they must yield frequently to the system so background processes can continue to run. This is done using s3eDeviceYield. In this example we want to run as fast as possible, so we pass 0 to s3eDeviceYield. This will return control to our application as soon as possible.

        s3eDeviceYield(0);
    }

Once the main loop has ended, we must free up any resources we created. Note that the resource allocations in the resource manager are owned by that module. Resource manager resources are destroyed using DestroyGroup. However, any groups still loaded when resource manager terminates will be freed automatically, so we will not explicitly free them here.

    delete pPlayer;

Finally, we terminate the modules we created for a clean exit. Airplay Studio will assert if any allocations are leaked. There are various useful debugging options for identifying leaks.

    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();

main() should return 0 to indicate no errors occurred.

    return 0;
}


Airplay SDK: Rendering a World With Multiple Instances Using Airplay Studio

Airplay SDK > User Guide > Simple Game Tutorials > Rendering a World With Multiple Instances Using Airplay Studio >

Rendering a World With Multiple Instances Using Airplay Studio

This tutorial walks you through a simple example of how to build and render a world using instanced geometry in Airplay Studio. You will learn how to export a world from your 3D art package and how to render it from an Airplay code project.

Building and exporting the assets

The art files for this tutorial are found in the sdk install\examples\games\kartz\art\tracks\track_01\, files for each 3D modelling package are within appropriately named folders.

Exporting the Models

The first step is to Export all the different models that will appear in the world. All these separate 'pieces' are stored in a single file. Each piece only occurs once in this file, and the positioning is not relevant. This allows the pieces to only be Exported once. The scene should be Exported as a Model Export, with local transforms.

The Pieces of the World

  • Open the file track_01_world_ModelExport in your preferred 3D Modelling Package
  • Open the Exporter Dialog
  • Choose an appropriate project (if required create a new project for this tutorial and add a data directory)

    • The Exporter Dialog

  • Choose a Model Export if not already selected

    • The Exporter Dialog

  • Leave all the other options as they are already set
  • Click Export

Exporting the World

The next step is to decide on the placements for all the objects within the world. Each object has a class type and the name of the model that it is a copy of. This means that if the world has 100 trees, only 1 tree model will be exported, and this will be used everywhere a tree is required. This saves space and makes it easy to alter the world if the original model changes.

The Whole World

  • Open the file track_01_ModelExport in your preferred 3D Modelling Package
  • Open the Exporter Dialog
  • Select the same project as before
  • Choose a World Export

    • The Exporter Dialog

  • Leave all the other options as set
  • Click Export

Rendering the world

Now we need to write the code to render the world.

We include the headers of the modules we will be using.

  • IwGx provides low-level rendering API, abstracting software and hardware rendering.
  • IwGraphics provides a higher-level API that renders models.
  • IwResManager provides resource management - the loading and binarising of assets.
#include "s3e.h"
#include "IwGraphics.h"
#include "IwGx.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"

The basic building block of our world will be an entity.

Entities are read out of a text-based .world file. The exact format of the world file is application-definable using the expmetatemplate system. This example uses a very simple default format where each entity looks like:

CStatic
{
  name "myInstance"
  pos { 100 0 100 }
  rot { 0 0 0 1 }
  model "myModel"
}

The world file is a standard itx file. As it is read in, the itx parser will feed each token it encounters to the ParseAttribute function of the current object (if any). If this is not recognised the class factory will attempt to instantiate an object of that class.

So for this sample, an object of type "CStatic" will be created. Then ParseAttribute will be called with "name", then "pos", etc.

We will create a CStatic object for each instance in the world file.

class CStatic : public CIwResource
{

The position and orientation of the entity are held in m_WorldMat.

  CIwMat m_WorldMat;

The entity holds a pointer to a model. A model is a bundle of streams and primitives which are held in an extensible format based on a number of blocks. For example, a model will have a vertex block that contains the model space positions of its vertices.

    CIwModel* m_Model;

IwGraphics allows the user to override some types of blocks on a per-instance basis. For example, the world might contain two tables, one in light and one in shade. The application can use model block override to display the two tables with different lighting.

    CIwManagedList m_Blocks;

The IW_MANAGED_DECLARE/IW_MANAGED_IMPLEMENT macros define a set of convenience functionality for this class, for example being able to query the classname.

public:

    IW_MANAGED_DECLARE(CStatic);

    CStatic()
    {
        m_WorldMat = CIwMat::g_Identity;
        m_Model = NULL;
    }

    ~CStatic()
    {
        m_Blocks.Delete();
    }

The ParseAttribute function is called for each line in the entity's itx entry.

    virtual	bool	ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
    {

The "pos" attribute determines the entity's translation in world space.

        if( strcmp(pAttrName, "pos") == 0 )
        {
            float fpos[3];
            pParser->ReadFloatArray(fpos, 3);

            m_WorldMat.t.x = (int32)(fpos[0]);
            m_WorldMat.t.y = (int32)(fpos[1]);
            m_WorldMat.t.z = (int32)(fpos[2]);
        }

The "rot" attribute determines the entity's orientation in world space.

        else if( strcmp(pAttrName, "rot") == 0 )
        {
            float fquat[4];
            pParser->ReadFloatArray(fquat, 4);

            CIwQuat q(
                (int32)(fquat[0] * IW_GEOM_QONE),
                (int32)(fquat[1] * IW_GEOM_QONE),
                (int32)(fquat[2] * IW_GEOM_QONE),
                (int32)(fquat[3] * IW_GEOM_QONE)
                );

            m_WorldMat.PreRotate((CIwMat)q);
        }

The "scale" attribute determines the entity's size in world space.

        else if( strcmp(pAttrName, "scale") == 0 )
        {
            float size[3];
            pParser->ReadFloatArray(size,3);
            for(uint32 x = 0; x < 3; x++)
            {
                for(uint32 y = 0; y< 3; y++)
                {
                    m_WorldMat.m[x][y] = IW_FIXED_MUL(m_WorldMat.m[x][y], (int32)(size[x]*IW_GEOM_ONE));
                }
            }

        }

The "model" attribute determines the entity's appearance. The model will have been previously loaded from a .geo file via a .group file (in this case, the same one that contains the world file).

        else if( strcmp(pAttrName, "model") == 0 )
        {
            CIwStringL s;
            pParser->ReadString(s);
            m_Model = (CIwModel*)IwGetResManager()->GetResNamed(s.c_str(), "CIwModel");
        }

The base class will handle the "name" attribute (or return false if it doesn't recognise the token)

        else
            return CIwResource::ParseAttribute(pParser, pAttrName);

We return true to indicate we recognised and consumed the token correctly.

        return true;
    }

When we've finished being read in, we add ourselves to the resource manager. This resource will now be owned by the current group and will be binarised along with the rest of the contents.

    virtual	void	ParseClose(CIwTextParserITX* pParser)
    {
        IwGetResManager()->AddRes("CStatic", this);
    }

If a block definition was embedded in our definition this call be made as that block is closed, so we just add the block.

    virtual	void	ParseCloseChild(CIwTextParserITX* pParser, CIwManaged* pChild)
    {
        m_Blocks.Add(pChild);
    }

The Serialise function is called by the resource manager to serialise a resource into or from a .group.bin file. We must ensure that our entire state is securely serialised, otherwise the resource may not function correctly on reload.

    virtual void Serialise()
    {
        CIwManaged::Serialise();

        IwSerialiseInt32(m_WorldMat.m[0][0], 12);
        IwSerialiseManagedHash(&m_Model);
        if( g_IwSerialiseContext.read )
            IwResolveManagedHash(&m_Model, IW_GRAPHICS_RESTYPE_MODEL);
        m_Blocks.Serialise();
    }

The Render function is called to render each instance.

    void Render()
    {

IwGxSetModelMatrix transforms model space to the entity's world space position/orientation

        IwGxSetModelMatrix(&m_WorldMat);

Each model block belonging to this instance is rendered, signalling to IwGraphics to use this block instead of the corresponding block in the model itself.

        uint32 i;
        for(i = 0; i < m_Blocks.GetSize(); i++)
        {
            ((CIwModelBlock*)m_Blocks[i])->Render(m_Model, 0);
        }

Now the model is rendered.

        m_Model->Render();

The PostRender method returns IwGraphics to using the blocks inside the models

        for(i = 0; i < m_Blocks.GetSize(); i++)
        {
            ((CIwModelBlock*)m_Blocks[i])->PostRender(m_Model, 0);
        }
    }
};

IW_MANAGED_IMPLEMENT(CStatic);

The IW_CLASS_FACTORY macro adds this class to the data-creatable set. This allows itx files to instantiate classes of this type.

IW_CLASS_FACTORY(CStatic);

Since we are adding a custom resource type (the .world file) we need to add a custom resource handler. This is the simplest possible resource handler - it hands off building to the ITX parser and returns no individual resource.

class CWorldHandler : public CIwResHandler
{
public:
    CWorldHandler() : CIwResHandler("world", "World") {};

    virtual CIwResource* Build(const CIwStringL& pathname)
    {
        IwGetTextParserITX()->ParseFile(pathname.c_str());
        return NULL;
    }

};

The entry point (where the code starts executing) is the standard c main function.

int main()
{

Airplay Studio modules must be explicitly initialised before use. Modules may implicitly initialise other modules they depend on. In this example IwGx will initialise IwResManager.

    IwGxInit();
    IwGraphicsInit();

Before we load our world file we need to make IwResManager aware of our .world files and our CStatic class.

    IwGetResManager()->AddHandler(new CWorldHandler);
    IW_CLASS_REGISTER(CStatic);

Now we load our world. Airplay Studio resources are held in atomic units called resource groups (.group files). A resource group contains one or more resources.

A .group file is a human readable text file specifying which resource are contained in the group.

CIwResGroup
{
 name "track"

 // the pieces file
 environment/track_01/track_01.group

 // the world file
 tracks/track_01/track_01.world
}

As you can see, the group first loads a child group. This contains the models that will be instanced. Next it includes the world file. This contains our instances.

To load a group we simply call the LoadGroup method of the resource manager singleton.

    IwGetResManager()->LoadGroup("track.group");

Once the group file has been loaded, the resource manager singleton can retrieve resources by name and type.

A resource group contains lists of resources by type. For this example we will get the list of all instances and render them. IwGraphics includes a simple bounding sphere test, but a real application would likely put the instances into a hierarchical structure for higher level culling.

    CIwResList* pInstances = IwGetResManager()->GetCurrentGroup()->GetListNamed("CStatic");

We keep track of how many milliseconds elapse every frame to move the camera at a constant speed independent of the framerate.

    uint64 lastFrame = s3eTimerGetMs();

In this example we will use the keyboard to navigate the world. To this end we keep track of the camera translation.

    CIwVec3 cameraTrans(0,0,0);

Now we enter the main loop. The exit condition is s3eDeviceCheckQuitRequest. This will return true if the OS requires us to exit. In the windows simulator this will be when the close icon is clicked.

    while(!s3eDeviceCheckQuitRequest())
    {

First of all, move the camera according to the keys pressed and how long the last frame took.

        uint64 now = s3eTimerGetMs();
        iwfixed speed = (int32)(now - lastFrame);
        lastFrame = now;

        if( s3eKeyboardGetState(s3eKeyAbsUp) & S3E_KEY_STATE_DOWN )
            cameraTrans.z -= speed;
        if( s3eKeyboardGetState(s3eKeyAbsDown) & S3E_KEY_STATE_DOWN )
            cameraTrans.z += speed;
        if( s3eKeyboardGetState(s3eKeyAbsLeft) & S3E_KEY_STATE_DOWN )
            cameraTrans.x -= speed;
        if( s3eKeyboardGetState(s3eKeyAbsRight) & S3E_KEY_STATE_DOWN )
            cameraTrans.x += speed;

Now we begin rendering.

First of all we clear the screen.

        IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

Set a simple camera matrix.

We use the LookAt function to set up a diagonal view of the world, then move to the current cameraTrans.

        CIwMat view;
        view.LookAt(CIwVec3(IW_GEOM_ONE,IW_GEOM_ONE,IW_GEOM_ONE), CIwVec3(0,0,0), -CIwVec3::g_AxisY);
        view.t = cameraTrans;
        view.t.y += 1000;
        IwGxSetViewMatrix(&view);

Now we walk the list of instances, rendering each one.

        for(uint32 i = 0; i < pInstances->m_Resources.GetSize(); i++)
        {
            ((CStatic*)pInstances->m_Resources[i])->Render();
        }

IwGxFlush commits all the drawing commands to the renderer.

        IwGxFlush();

Finally we call IwGxSwapBuffers to present the rendered output to the screen.

        IwGxSwapBuffers();

Airplay applications are co-operatively threaded. This means they must yield frequently to the system so background processes can continue to run. This is done using s3eDeviceYield. In this example we want to run as fast as possible, so we pass 0 to s3eDeviceYield. This will return control to our application as soon as possible.

        s3eDeviceYield(0);

To update the state of the keyboard we must call s3eKeyboardUpdate() once a frame.

        s3eKeyboardUpdate();
    }

Once the main loop has ended, we must free up any resources we created. Note that the resource allocations in the resource manager are owned by that module. Resource manager resources are destroyed using DestroyGroup. However, any groups still loaded when resource manager terminates will be freed automatically, so we will not explicitly free them here.

Finally, we terminate the modules we created for a clean exit. Airplay Studio will assert if any allocations are leaked. There are various useful debugging options for identifying leaks.

    IwGraphicsTerminate();
    IwGxTerminate();

main() should return 0 to indicate no errors occurred.

    return 0;
}


Airplay SDK: Full Game Examples

Airplay SDK > User Guide > Full Game Examples >

Full Game Examples

Airplay comes with a set of more advanced game examples to demonstrate the use of various features of the SDK in a more complex situation. Each of these is documented here with an explanation of the game design and use of the Airplay API.

The source code and assets for these games can be found in the examples/games folder of your Airplay installation directory.

  • Kartz - 3D Racing Game Example
  • BlocSlot - 2D Puzzle Game Example
  • BeatToy - 3D Fighting Game Example


Airplay SDK: Kartz 3D Racing Game Example

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example >

Kartz 3D Racing Game Example

Kartz is a simple example of a racing game created using Airplay. The game consists of a single track around which four go karts race, one of which is user controlled and the other three are AI controlled.

The Kartz Game

Initially the user is presented with a splash screen displaying the user options: Start and Quit. The s3eKeyAbsASK and s3eKeyAbsBSK keys are used to select from the presented options. Selecting Start (s3eKeyAbsASK) loads the game, which will automatically start when loaded. At any point during the game the user can press the s3eKeyAbsBSK key to pause, and once more to return to the front end splash screen. When the user has completed four laps the game will end and the user will once again be presented with the front end splash screen listing the options to either start or quit.

The source code for Kartz is located under: <SDK installation path>/examples/games/kartz/

Kartz illustrates the use of the following Airplay components:

  • S3E
  • IwUtil
  • IwGeom
  • IwGx
  • IwResManager
  • IwGraphics
  • Derbh

The ExampleGameFramework, a C++ framework for game states entities etc, is also included as source code.

Contents

  • Art Overview
  • Code Overview
  • Building the example
  • Running the example
  • What is happening with the assets?
  • Testing an ARM build within the ARM RTSM
  • Building and deploying the game on device


Airplay SDK: Art Overview

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Art Overview >

Art Overview

Before the code can be written, all the basic elements of the game need to be assembled. There are three main art elements to the game:

  • The UI Graphics.
  • The Track: The track scene is exported in two distinct parts, a mesh (GEO file) and design file (WORLD file).
  • The Go Kart: Each go kart is based on one GEO file.
    • The Go Kart body: This provides the mesh and base materials for the go karts GEO and MTL).
    • The Go Kart switchable materials: This provides an extra material file (MTL) that holds all the material variations that are used by the game on the AI go karts
    • The Go Kart wheel: This holds the mesh and material for the wheels.

Each of these items and their materials are contained in the folder <SDK installation path>/examples/games/kartz/art. These items must be exported using the Airplay Studio Exporter, thus producing the group files and model files needed by Airplay to build their compressed binary representations. The exported files are contained in <SDK installation path>/examples/games/kartz/data.

The track data includes a best line and a set drivable area. The best line is a CCurve placed on the track surface, and out of the set of CWorldObject types is of type CPath. The best line is used by the AI karts to guide them around the track. The driveable area is the part of the track on which the karts can drive, this must be specified so that the game code knows where the karts can go. To do this, a selection set called "drivable" should be created that contains all the faces the karts can drive on. This is included by adding it to the WORLD export.

The kart is constructed in such a way as to allow for the materials on the model to be swapped for each of the AI characters. To do this, the gokart has been broken into three separate parts. Only one kart is described in totality using a GEO and MTL file, and this kart is then taken and used to produce the other three karts by swapping in the other coloured textures.

A Single Track Model or Multiple Components

Depending on the requirements of your game, you may approach the asset creation process from two different angles:

A Single Geometry File per Level

  • The benefits for this are you have a simpler asset creation process (i.e. you only have one GEO and one MTL file for each level).
  • The limitations of this are that the maximum size of any mesh described in a GEO file has to be less than 30,000 units in any axis. This is quite a large amount, but if you are working in meters for your working scale, then 1 unit is going to be exported as 100 units (as the exporter always exports in centimetres), leaving you with a maximum model size of 300 meters in your art package.

Using Components (Multiple Geometry Files)

  • The benefits for this are:
    • You can build assets out of multiple GEO files, creating a new asset that may be greater than 30,000 units in any direction.
    • You can make use of instancing (repeat the usage of a model many times, which will save you space on disk).
  • The limitations of this are more complicated asset creation and resource management.
    • A separate WORLD file export will be needed to place the components into the right places.
    • Manual sorting of objects is much harder, especially when using instancing, as the instances cannot be uniquely sorted and a ‘catch all’ approach will be needed, which may not be possible.
    • All the instances must share the same mesh data, i.e. instances cannot be uniquely lit with vertex colour.

For this example you can see how to make a level using both of the methods mentioned above.

As this example is targeted to work across a wide range of handsets in both software and hardware rendering, the polygon count and number of textures used has been kept to a minimum.

Note: The demo has a code imposed requirement: the position of the track model which contains the drivable surface must have a position of 0,0,0.

The Single Geometry Approach

The game track is made up of two parts, a mesh (GEO) and design file (WORLD). The design file contains a 'bestline' path for the AI cars to follow as well as a placement for the mesh.

The Track Mesh (GEO file)

This approach will create a single GEO and MTL file with associated textures, from the Maya or Max file.

The files for the GEO file are called track_01_GeoExport.

The Geo Export Example File

The example level for the go-kart track is small enough to fit into a single GEO file, and by ensuring that the centre of the track is over 0,0,0 we are going to get the most out of the space available.

When building assets that are going to be used in the Standard Renderer, you need to take into account possible sorting issues, and try to minimise the amount of Overdraw (polygons infront of other polygons). To fix any problems, put the sets of polygons into selection sets and attach a z-depth value to the set. This allows the game to place the polygons in the order required, e.g. a fence infront of a grassy hill should have the fence in a selection set, and the hill in another set. Set the fence to have a smaller z-depth value to place the fence infront of the hill.

Once the track is made, the drivable surface needs to be specified so that the code knows what faces the karts can drive on. To do this, make a face selection set called 'drivable' that contains all of the faces that the kart can drive on and add it for export in the editor.

The final stage of the track creation process is to ensure that the transforms are frozen and that the model is clean. In Maya this will involve freezing the transforms and cleaning the history of the objects. In 3D Studio Max this will involve performing a Reset XForm and collapsing the stack to an Editable Mesh.

Export the file as a GEO export called track_01, this will create a single GEO file describing all of the meshes in the scene, and a MTL file describing all of the materials they use. As with all GEO exports you will need to ensure that you export your model using the world transform type to ensure that all of the meshes that make up your scene retain their world space positions. If you accidentally export the scene in Transform: Local, all of your meshes will appear on top of each other, this is because each mesh has been added to the GEO file by exporting relative to its pivot or origin (i.e. as if each vertex position was relative to 0,0,0).

The Design File (WORLD file)

The next step is to create the elements for the game that tell it where the exported track_01.geo is to be positioned and to specify a “bestline” for the AI cars to follow.

The files for the GEO file are called track_01_world_GeoExport.

The Geo World Export Example File
  • Note: the 'bestline' path along the track.

Using the same scene that you used to create the GEO file as a starting point, you can set up a world file export.

Note: World files only export nodes that have been given specific CWorldObject class types via the Exporter Editor, and so any elements you want exported must have this information attached to them.

The demo is expecting a linear path, so create a path for the AI to follow called 'bestline' with either a 1 degree curve (in Maya), or a spline with no Bezier handles (in 3D Studio Max). Set the path up for export by selecting it and assigning it a CPath class type. The first point on the curve is used as the start point for the race and the direction of the curve will dictate the direction the cars will drive.

To set the position for the track model in the world file, we can just use the track mesh that we have in the scene. Select the track mesh, and use the Exporter Editor to assign a Class Type of CStatic. This will reconfigure the UI to show you the type data that will be exported in your world file. In the Model field, you want to put the name of the model that is to be used, in this case we previously exported the track as track_01.geo so enter track_01 in the Model field.

The multiple geometry approach

This approach will show how to export multiple models from the same art file and create our track layout in a world file for the game.

The Track Meshes (multiple GEO files)

The files for the GEO file are called track_01_ModelExport.

The Model Export Example File
  • Note: this file is like a pallete; it is made up of each of the pieces that will appear in the final track.

The difference between this approach and the previous approach is that we are going to be constructing only one version of each asset (such as the trees etc) and then using that mesh multiple times around our track. This will have the benefit of allowing us to save space on disk for the game level, as well as lowering the number of assets that need to be modified when changes are required.

The file from which we are going to export our meshes from should be thought of as more of a palette of pieces from which to build our level, rather than the final track. The pieces will be brought together in the world file, so instead of having one CStatic to position the track_01.geo, you will have many (one for each mesh in your scene).

Important things to remember that will ensure that there are no issues related to meshes appearing in your game world in the wrong places:

  • Make sure that you name everything with a unique, identifiable name
  • Make sure you have clean histories / stacks on your objects
  • Ensure that each object has its transforms frozen / Xforms reset so that the object is at the centre of the world when it has a transform of 0,0,0.

The last point is the most important point for successfully using instances, as any meshes that do not centre on 0,0,0 when their transforms are set to 0,0,0 will appear out of place in the game. This is because the game will assume that the model has a local transform of 0,0,0 when it loads it and will then apply the position and rotation found in the world file.

When all the models that you are going to use in your level are finished, you want to export the scene as a Model Export. This will export a GEO file for every mesh in your scene, as well as a group file, which will list all the GEO files that were exported. It also sets up a special field on each mesh to hold information about the model exported, so that you can have the Model field filled in for you automatically should you then use that mesh as a CStatic in a world file export.

The Design File (WORLD file)

In the previous single geometry approach, the world file only held information regarding where to place the track_01.geo and the “bestline” path for the AI. We are now going to use it to construct our level in greater detail.

The files for the GEO file are called track_01_world_ModelExport.

The Model World Export Example File
  • Note: the palette of pieces in the upper right of the image.

Using the previously exported Model file as a starting point, setup each object in the scene as a CWorldObject of class type CStatic. As you set them as CStatic, the Model field should be filled in for you automatically (as long as the piece was exported in a previous Model export).

You are now in a position that you can place duplicates of those objects around your scene.

The following constraints must be adhered to:

  • Do not make any adjustments to the objects once in the world file. This includes changes to the mesh, materials or pivots.
  • The only information that is going to be exported in this file is the name of the object and the CWorldObject data that you set on it.
  • Do not scale the object, this is not supported in the Exporter currently and, therefore, will not be respected.
  • Do not change the name of the original model you exported after you have begun the process of placing duplicates of it around in your world file. This is because the name held in the CStatic Model Field will now be incorrect, and the world file would try to load the old (incorrect) model in game.

You can however rotate and position them however you like. Remember to make a 'bestline' for the AI to follow and you can export your world file. This world file should now contain a number of CStatics that will position the models in the game as well as the 'bestline' path. Some of those Statics should be pointing to the same model, otherwise nothing is being instanced.


Airplay SDK: Code Overview

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Code Overview >

Code Overview

The following sections describe the code used to create Kartz.

The Contents of the MKB

The MKB specifies options for building and deploying the game. It also includes a kartz.mkf that specifies the code files and modules required to build the game. Code specific to this example resides in kartz/source.

The Entry Point

Any s3e has an entry point marked with S3E_MAIN_DECL. In Kartz you can find this in RacingDemo.cpp. The function IwMain initialises the memory manager, creates the game object, calls its 'run' function, and then clears up when this exits.

The Memory Manager

Kartz includes a simple memory manager (in MemoryManager.cpp) based on IwUtil's IwMemory system. This divides the s3e's heap memory into a number of 'buckets'. Dividing memory in this way makes it easier to keep track of how much memory is being used by each of the game's subsystems and allows them to allocate and free memory without disrupting the memory use of other systems (e.g. fragmenting the heap, etc.). In addition, if memory runs out an error message will be displayed describing which bucket has become full up - identifying which subsystem has malfunctioned.

The Game Object (Game.cpp)

Like most objects which interact with the GameFramework example module, CGame is derived from a base class in GameFramework, in this case, CIwGame. CIwGame provides a simple state machine for game states and virtual functions to help implement updating and frame rate independent rendering behaviour. CGame builds on this base functionality by overriding a number of virtual functions (described below).

CGame constructor and destructor

The CGame constructor initialises and configures the modules required by the example and loads the fixed UI assets (these are always loaded).

The CGame destructor terminates the modules again.

CGame::Run

This is the game's entry point: It activates the first state (the FrontendState) and then enters the main loop. Let's look at the main loop one line at a time:

The first thing the loop does each frame is yield. Typically the underlying OS on a mobile phone is cooperatively multi-threaded, so s3e applications should yield often to surrender time to other processes. If the application intends to use s3eSound on BREW it should be aiming to yield every 8ms or so.

Next, the loop calls s3eKeyboardUpdate() to update the status of s3eKeyboard. s3eKeyboard calls are not synchronous so the game must call this every frame to get the latest input status. None of the return values from s3eKeyboardGetState() will change between calls to s3eKeyboardUpdate().

Now the loop calls CIwGame virtual functions to process the game state machine. Internally the CIwGame has a stack of game states (with the topmost being the 'current' state). States are pushed and popped to change the state of the game. For example, from the FrontendState an AbsASK press will push the LoadState, which in turn will push the InGameState, once the track and cars have been loaded.

The functions CGame::Run calls are:

  • RenderStates(): This calls each state's Render virtual in turn giving it a chance to render. Typically states will only render when they are the current state.
  • Update(): This function calls each state's Update function a number of times depending on the duration since the last update call and the target FPS set.

It's important to note that 'Render' and 'Update' are kept separate, so frame rate independence can be maintained. For example, if render performed updates it would be impossible to draw the game world in a paused state.

CLoadState

The load state is unusual in that it only stays the current state for the duration of one Update call. On some devices this may be quite a long frame, so it registers for the serialise callback so it can render periodically. This is important, because otherwise the screen would not redraw if the application was interrupted during loading.

Contents of the Game World ('World' and 'Entities' project folders)

Kartz contains two distinct types of asset: the world and the cars. The world is encapsulated by CWorld and derived from the GameFramework's CIwWorld base class. This is a container class for a number of CIwEnts. CIwEnt is a generic entity class. An entity is anything that has a presence in the world: trees, the track and even the cars.

Each entity has a behaviour that is updated during CWorld::Update calls. In the CWorld::Render call all entities are then Rendered in turn; typically an entity will check its bounding sphere to see whether it should render.

Most of the entities in Kartz are of type CGeomModel. This is derived from CIwGeomModel. This type of entity holds a pointer to a CIwModel (from IwGraphics) which it renders at its model matrix (this is held in its attached CIwFrame).

The track_01.geo activates a custom ModelBuilder PostBuild callback function to build a collision surface from a face selection set in the source asset. (See World.cpp for this mechanism). This model is also chunked for rendering efficiency.

The world is constructed from a WORLD file. This places a number of CGeomModels in the world, and specifies a best line.

The cars are CGeomModels, with a CCar behaviour attached. These are constructed when the CWorld is Reset() by calling CCarFactory::Create.

The world also contains a camera entity. The CIwFrame of this entity determines what viewpoint the world is drawn from, and thus the behaviour of this entity is also the behaviour of the camera. There are a few behaviours available - the normal chase camera (CChaseCamera), the in car camera (CInCarCamera, accessible by pressing 1) and a free camera for debugging, available from the debug menu (f6).

CInGameState(InGameState.cpp)

The in game state renders the world and the HUD over the top.

One important thing to note about this state is its use of s3eDeviceCheckPauseRequest(). This function will evaluate to true if the game has been suspended. The game may be suspended inside any s3eDeviceYield if the another process to take control of the device. The most obvious example is a phone call.

Normally an s3e application does not need to worry about suspension, but it is good practise for action games like Kartz to pause if they are suspended in-game. That way, when the application resumes the player is not thrown into a disorientating situation. Note that this is a requirement for passing certification on some platforms.

The main other reason to be aware of suspension is that s3eTimerGetMs() calls should be protected against unexpectedly long intervals being returned. For example:

uint64 now = s3eTimerGetMs();
s3eDeviceYield(0);
uint64 duration = s3eTimerGetMs() - now;

The duration here could be anything from 0 ms to the just under the battery life of the phone (or longer if it's attached to the mains).

If a player has just finished a long conversation, it's unlikely they want the game to perform enough physics to compensate for the duration of their call! The base class of IwGame performs this capping in this demo.

Abstracting the device (BaseState.cpp)

If you look in CBaseState::PopOnBack() you'll notice that it uses an abstract s3e key (s3eKeyAbsBSK). Abstract keys are provided to abstract the underlying device and respect OS norms.

Generally phones have two softkeys, one which is 'forwards' or 'select' and one which is 'back' or 'cancel'. The abstract B softkey is attached to this secondary softkey. For example, on a BREW device this is the left hand softkey, whereas on Symbian it is the right hand one.

The application can use s3eDeviceGetInt(S3E_DEVICE_LEFT_SOFTKEY_IS_BACK) to determine which side of the screen to draw the respective actions on (see CBaseState::RenderSoftKeys for an example of this).

A variety of abstract game keys are also available to use (if the game's control scheme fits them). Kartz uses s3eKeyAbsLeft, s3eKeyAbsRight and s3eKeyAbsDown for its control scheme. On most normal phones these will be assigned to the d-pad, but on phones that do not have a d-pad alternatives will be defined.

CBestLineTracker (BestLineTracker.cpp)

The AI in this demo is very basic, but a quick overview may be helpful.

The WORLD file includes a CCurve which is used as the best line. Each car has a CBestLineTracker member called m_BestLineTracker. This class is responsible for maintaining whereabouts on the line the car is, and where they should be going. This also provides a notion of 'how far around the track' the car is, which is used to calculate how many laps have been done and who's winning.

The tracker maintains a pair of points on the line which act as virtual 'walls', when the front one is broken the tracker advances the point a distance around the line. The back one is used to measure distance from.

The AI simply drives toward the current point, which will advance as they approach it. They will also attempt to avoid drivers in front of them (to an extent). They do this by testing for another car in a cone in front of them and adjusting their target direction to avoid anything in their way. This is all tweakable from AIDriver.cpp.

Improving the demo

Kartz is intentionally kept simple, but here are some ideas of ways it could be improved:

  • Support more than one level and let the player choose between them.
  • Improve the physics. The physics here are very simple. Try adding drifting... or a much more complex driving model.
  • Improve the AI. Currently, the AI drivers just zoom round at a speed determined by how much the section of curve they are on is changing. Ideally they would look ahead to see whether a tight corner is coming up and slow down accordingly. This could be approached in a procedural way (CBestLineTracker could have a 'caution' rating reflecting the difficulty of the path ahead) or by placing markers in the world file.
  • Level Of Detail models. The number of polygons in the racers could be decreased when they are far from the camera. This could be done at the CGeomModel level - essentially have an array of CIwModel pointers and choose one based on distance from the camera. This could also be used for the environment in an instance-based world, providing richer environments and better car models.
  • Support multiple models with collision meshes. Instead of using one collision mesh held in the world, allow individual CGeomModels (or a derivatives) to hold individual collision meshes and let the car drive between them. This could allow much larger worlds and modular construction of tracks.
  • Add sound. See Beattoy for usage of the example SoundEngine.


Airplay SDK: Building the Example

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Building the Example >

Building the Example

To build the example, do the following:

  • Right click kartz.mkb in the examples/games/kartz folder. This will create a workspace for your programming IDE (VC++ or .NET, as set by the user when running s3eConfig.exe), launch the IDE and load the workspace.
  • Open up the list of Build Configurations. The list of Build Configurations are contained in a drop down list at the top of you IDE as illustrated in the following diagram.

    • You should see the following options:

    • Win32 ARM RVCT Build Release
    • Win32 ARM RVCT Build Debug
    • Win32 ARM GCC Build Release
    • Win32 ARM GCC Build Debug
    • Win32 Release
    • Win32 Debug
  • Select Win32 Debug.
  • Build the project, from within the IDE.


Airplay SDK: Running the Example

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Running the Example >

Running the Example

To run the example, do the following:

  • Run the project from within the IDE – either inside or outside the debugger.

    • Kartz Splash Screen

    The game displays a series of “splash” screens, and then the main menu.

  • Press F1 to start the game.

The following controls can be used within the game:

  • Arrow keys: left and right steer, down brakes.
  • F3: Back action: pause the game, exit the game, or exit the application.
  • F1: Forward action: Start or continue game.


Airplay SDK: What is Happening with the Assets

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > What is Happening with the Assets >

What is Happening with the Assets

Take a look at examples/games/kartz/data/environment/track_01/track_01.group.

This text file (in ITX format) describes which “input assets” the game will load into the resource group named “track_01”.

Note that this file is loaded as a child group by examples/games/kartz/data/tracks/track_01.group.

Generating Binary Resources

When the Win32 Debug build of the game is run, the following happens:

  • The track_01.group text file is parsed and the required “input assets” (for example, track_01.geo) are loaded.
  • A single binary file is written containing minimal binary versions of all the assets (resources). This file was written to: examples/games/kartz/data-ram/data-gles1/environment/track_01/track_01.group.bin.

Note that whenever an Airplay application writes a file, it writes it to “data-ram” rather than “data”. This is because it is useful for Airplay to maintain a separate concept of the file systems it is reading from and writing to. When Airplay is asked to read a file, it first looks within “data”, and if the file is not found, it looks within “data-ram”. When Airplay is asked to write a file, it always writes to “data-ram” (unless the user specifies an explicit absolute path to write to).

The resource manager outputs to a further subdirectory based on the current build style. The default build style is gles1, so the binaries are output to data-gles1.

Note that two other files have also been written:

  • examples/games/kartz/data-ram/data-gles1/environment/track_01/track_01.group.bin.txt
  • examples/games/kartz/data-ram/data-gles1/environment/track_01/track_01.group.hst

Open track_01.group.bin.txt. This is a description of all the resources which have been included in the respective GROUP.BIN file. This can be useful for debugging resource-related issues.

track_01.group.hst is a binary file which contains the string names of all the objects within the respective GROUP.BIN file. This file, if it exists, can be loaded by the game and used to provide full string names of all objects which have been loaded from a GROUP.BIN file. This can be useful for debugging purposes.

Now, once the resource manager has written the GROUP.BIN file, it proceeds to delete the entire resource group (named “track_01”) it has just created. It then loads back the binary version (track_01.group.bin) and the accompanying string table file (track_01.group.hst) if it exists.

In this way, the entire process for building binary resources and loading binary resources is tested from within the Win32 Debug build of the game.

Note that resources are built using a seperate heap (the debug heap), but loaded back using the normal heap, so memory usage in the normal heap will exactly match the normal release build.

Loading Only Binary Resources

To load a GROUP.BIN binary file, rather than a GROUP text file, do the following

  • Exit the game (by pressing Esc, or repeatedly pressing F3).
  • Open up the "app.icf” text file.

    • This file contains settings which are read by Airplay at initialisation time to determine various parameters.

  • Find the “ResBuild” setting, and change it to:

    • ResBuild=0

  • Now run the game again.

This time, the resource manager has been placed into a mode where it only loads the binary resources.

Therefore, a call to:

IwGetResManager()->LoadGroup(...)

…will load a GROUP.BIN binary file, rather than a GROUP text file.

We are now in a position where we can do an ARM build of the game, and deploy it to a device together with all the GROUP.BIN files, and other script files required by the game.

Compressing Resources

Before we do that, let’s try creating a compressed Derbh archive (DZ file), which contains ALL our game assets. This is achieved by doing the following:

  • Open up a command-line window, and navigate to: <SDK installation dir>/examples/games/kartz/data/derbhscripts
  • Open up the RacingResources-gles1.dcl text file. This file describes how to create a Derbh compressed binary archive (DZ file) from several input files.
  • Double click on the dcl file to invoke the DZip executable (<SDK installation dir>/tools/DZip/DZip.exe)

    You should see the message "Compressing: DerbhZip". The DZip command-line (DCL) tool can take several seconds to create the archive.

    The RacingResources-gles1.dcl text file describes the pathname for the archive. In this case, we have chosen to place it in kartz/data/RacingResources-gles1.dz.

    Always remember to run the Win32 Debug build to refresh your binaries when source assets change before producing a new Derbh file. Otherwise any assets changes will not be reflected.

  • To test your Derbh file in Win32 Debug set the icf flag LoadFromDerbh to 1. It is advisable to delete your data-ram directory first to make sure you are definitely running with the derbh'd resources. The game will assert if you try to run with LoadFromDerbh and ResBuild both enabled. See the CGame constructor in kartz/source/Game.cpp for the code which checks this condition.


Airplay SDK: Testing an ARM build within the ARM Emulator

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Testing an ARM build within the ARM Emulator >

Testing an ARM build within the ARM Emulator

To test an ARM build within an ARM emulator, do the following:

  • Open up the workspace again within the programming IDE, and select the Win32 ARM RVCT/GCC Build Debug configuration.
  • Build the project in the usual way, from within the IDE.
  • When the build is complete, press F5 to run the application in the ARM emulator.

The game should run in the emulator, and you can set breakpoints and debug at either source code or ARM disassembly level.

Note that Airplay supports more than one ARM emulator, and which emulator is used can be selected via the Airplay SDK Configuration utility. For more information see ARM Emulator Configuration.


Airplay SDK: Building and deploying the game on device

Airplay SDK > User Guide > Full Game Examples > Kartz 3D Racing Game Example > Building and deploying the game on device >

Building and deploying the game on device

To build and deploy the game on device, do the following:

  • Open up the workspace again within the programming IDE, and select the ARM RVCT/GCC Build Release configuration.
  • Build the project in the usual way, from within the IDE.
  • When the build is complete, press F5 to run the Airplay System Deployment Tool.
    • The Deployment Tool
  • Follow the standard steps to complete the deployment process:
    • Select the build configuration you wish to deploy (this should be "ARM GCC Release"). Only build whose binaries exist locally will be selectable.
    • Select the deployment configuration you wish to deploy. Kartz includes several asset sets for different types of target device. Default can be expected to work on most devices.
    • Select the OS/Platform you wish to deploy to.
    • Check the configuration options (the chosen platform may require signing certificates to be set).
    • Choose Package or Package and Install at the Deploying stage.
    • Hit Deploy All and follow the on screen prompts if you chose to install, or copy the output files to device if you chose Package
  • Run the game on the device!


Airplay SDK: BlocSlot 2D Puzzle Game Example

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example >

BlocSlot 2D Puzzle Game Example

BlocSlot is a simple 2D puzzle game, provided in source code together with all data assets. The aim of the game is to get sets of 12 or more of the same coloured block together. Each level increases in speed and new coloured blocks are added at intervals.

This tutorial leads the user through key aspects of the application data and source code, with the aim of illustrating:

  • Management of texture, material and font resources using the IwResManager API
  • 2D drawing using the Iw2D API
  • Bitmap font rendering using the Iw2D API
  • Using Airplay APIs to write a single application that can accommodate many screen resolutions and screen rotations
  • Using Airplay APIs to write a single application that can accommodate keypad or touchscreen input

The following sections are included in this tutorial:

  • Building for Win32 and Playing the Game in the Windows Simulator
  • Building for ARM and Playing the Game on Device
  • Testing how the Application responds to Screen Size and Rotation
  • Testing how the application responds to both key and touch inputs
  • Source Code Overview
  • Management of image and font resources using the IwResManager API
  • 2D drawing using the Iw2D API
  • Bitmap Font Rendering using the Iw2D API
  • Writing a Single Application that Accommodates Multiple Screen Resolutions and Rotations
  • Writing a Single Application that Accommodates Keypad or TouchScreen Input


Airplay SDK: Building for Win32 and playing the game in the Windows Simulator

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Building for Win32 and playing the game in the Windows Simulator >

Building for Win32 and Playing the Game in the Windows Simulator

Before we go any further, let’s build and play the game as follows:

  • Double-click the file blocslot.mkb.

    Airplay will create a workspace for the IDE of your choice, and load it into the IDE.

  • From the list of build configurations, select Win32 Debug and build the application.

    Once built, launch the application within the IDE debugger. The application runs within the “Airplay Windows Simulator”.

    • BlocSlot Splash Screen

  • In the Windows Simulator, the left soft key is by default mapped to F1. Press F1 to start the game.

The game is played as follows:

  • Use up/down/left/right to rotate and move the blocks. Try to group blocks of the same colour together.
  • If the total size of a coloured area exceeds 12 tiles, the coloured area explodes and disappears.
  • If the player fails to join coloured blocks together, the stack of blocks gets higher. If the stack of blocks gets too high, the game is over.

Exit the game when finished.


Airplay SDK: Building for ARM and Playing the Game on Device

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Building for ARM and Playing the Game on Device >

Building for ARM and Playing the Game on Device

Select the Win32 ARM GCC Build Release build configuration. Build the game and select to launch the application; instead, the Airplay Deployment Tool will be launched.

  • Select the ARM GCC Release option.

    • The Deployment Tool

  • Click “Next” twice, and select the OS you wish to deploy to (for instance, Symbian v9.x S60).
  • Click “Deploy All”, and an appropriate OS installation package will be created.
  • If you have an appropriate device, deploy the application installation package to the device, and launch and play the game on the device.


Airplay SDK: Testing how the Application responds to Screen Size and Rotation

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Testing how the Application responds to Screen Size and Rotation >

Testing how the Application responds to Screen Size and Rotation

Revert to the Win32 Debug build configuration, and launch the application within the Windows Simulator.

  • Select Configuration > Surface… and type a new width and height for the screen. Click OK.

    In GL mode the game must restart when surface size if changed. If GL API 'none' is selected the game immediately responds to the new screen size, by moving and resizing all elements accordingly.

  • Try a ridiculous screen size such as (1000, 128). The application displays a warning that this size is unsupported.

    Again select Configuration > Surface… and this time choose a screen rotation of 90 degrees. Notice how the game immediately responds to the new screen rotation.

  • Select Configuration > Surface… and reset the screen rotation to 0 degrees.

    Try screen sizes of (176, 208) and (480, 640). Notice how the font size changes to accommodate both “small” and “large” screen sizes.


Airplay SDK: Testing how the application responds to both key and touch inputs

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Testing how the application responds to both key and touch inputs >

Testing how the application responds to both key and touch inputs

  • Click the mouse inside the Windows Simulator main window.

    Notice how several control icons appear.

  • Click these icons to control the game using the mouse; this indicates how the game will respond to touch inputs on devices that support touch.

    Both key and touch control can be used simultaneously.


Airplay SDK: Source Code Overview

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Source Code Overview >

Source Code Overview

Let’s take a brief look at each source file:

main.cpp

This contains the application main() function. The main() function initialises application data and required Airplay modules; it then enters a while() loop that exits only when the application throws a “quit” event. Each iteration of this loop performs a general “update” and “render” of the application. If the loop exits, application data is deleted and Airplay modules are terminated before exiting.

game.cpp / game.h

These are the “workhorse” files for the main gameplay. Much of this is general C++ game programming, and not specific to Airplay. There are some calls to Airplay input and rendering methods, but most rendering is performed within separate files (see below).

rendering.cpp / rendering.h

Other than minimal use of fonts, the entire game is rendered using 2D “sprites” (texture-mapped rectangles). These files contain all the sprite management and rendering code, using the Iw2D API.

effects.cpp / effects.h

The BlocSlot game is designed to illustrate key Airplay concepts related to 2D rendering and “scalability” of applications across different devices; it is not intended to illustrate complex visual effects. Two very simple “effects” are illustrated; an “exploding stars” effect that is used when coloured blocks disappear, and a “floating text” effect that is used to illustrate the associated score. These source files manage these two effects.

localise.cpp / localise.h

These files are a trivial illustration of how indexed string tables, rather than “hard” strings, should be used when specifying application text; this makes language localisation simple.


Airplay SDK: Management of texture, material and font resources using the IwResManager API

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Management of texture, material and font resources using the IwResManager API >

Management of texture, material and font resources using the IwResManager API

The IwResManager API must be initialised and terminated at the top and bottom of the application main loop:

  • int main(int argc, char* argv[])
  • {
    • ...
    • IwResManagerInit();
    • ...
    • IwResManagerTerminate();
  • }

Source files making calls to IwResManager APIs should include “IwResManager.h”.

All application data is loaded using a single line of code within the main() function:

  • int main(int argc, char* argv[])
  • {
  • ...
    • // Load resources
    • IwGetResManager()->LoadGroup("tiles.group");
  • ...
  • }

When running any build configuration other than Win32 Debug, this will load the file data-ram/tiles.group.bin. However, for this file to exist, we must first run using the Win32 Debug build configuration. In this configuration, the file data/tiles.group is loaded. Let’s take a look at this file:

  • CIwResGroup
  • {
    • name "tiles"
    • tiles.mtl
    • fonts/font.gxfont
    • fonts/font_small.gxfont
  • }

The file is specifying a resource group named “tiles”. Within this resource group, three further files are specified. Let’s take a look at tiles.mtl:

  • // General materials
  • CIwMaterial
  • {
    • name "background"
    • texture0 "background.bmp"
    • colAmbient {255 255 255}
  • }
  • CIwMaterial
  • {
    • name "grid_background"
    • colAmbient {0 0 0 128}
    • alphaMode HALF
  • }
  • ...
  • CIwMaterial
  • {
    • name "tiles32_5"
    • texture0 "tiles32/tiles32#yellow.bmp"
    • colAmbient {255 255 255}
  • }

This file has been created “by hand”, and specifies many material resources (objects of type CIwMaterial). Polygons drawn using the IwGx API are always rendered using some material.

Note that some of these materials specify texture maps; these are also loaded into the resource group (as objects of type CIwTexture).

Now let’s look at the file fonts/font.gxfont:

  • //Temp file created by AS Font Builder (User: Tom At: 05/12/09 18:22:09)
  • //Command Line:
  • //: -fontdesc "0;-19;0;0;0;400;0;0;0;0;3;2;1;34;Arial" 0 4 0 -pad 0 1
  • //: -col #FFFFFF -shadow 0 -spacing 4 -force16 0
  • CIwGxFont
  • {
    • utf8 1
    • image font.tga
    • charmap " !\"#$%&'()*+,-./0123456789:;... "
  • }

This file has been created using the Airplay Studio Font Builder tool, and specifies a single bitmap font (object of type CIwGxFont). The font description references an image file, font.tga. This is loaded into the resource group (as an object of type CIwTexture). The font description also contains a long string indicating exactly what characters are contained within the associated font image.

As the resource files are loaded, the associated Airplay Studio object types (CIwMaterial, CIwTexture, CIwGxFont, etc.) are created. When all the resource files have been processed, these objects are “serialised out” (written) to the file data-ram/tiles.group.bin in a small and efficient form. When the application is run in any build configuration other than Win32 Debug, this binary file is read directly; this is much faster, and does not require any of the “source data files” to be present.

An aside

Look back at tiles.mtl and notice how some of the texture names include the “#” symbol. Airplay Studio treats this as a special character within texture filenames, for the purposes of “texel sharing”. This allows multiple textures to share the same texels, but have different palettes, resulting in a smaller total file size on disk. A filename having the “#” symbol directly before the file extension (e.g. tiles12#.bmp) indicates that the texture’s texel data will be shared by other textures. A filename that shares this same prefix, with additional appended characters (e.g. tiles12#green.bmp) will share the texels of the former texture, but specify a different palette; the texels of the latter texture will not be serialised (written to disk).


Airplay SDK: 2D Drawing Using the IwGx API

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > 2D Drawing Using the IwGx API >

2D drawing using the Iw2D API

Iw2D is Airplay’s simple 2D drawing API. Iw2D provides a simple way to write 2D rendering based on a small number of primitives. The principle primitives used in BlocSlot are images and strings.

The Iw2D API must be initialised and terminated at the top and bottom of the application main loop:

  • int main(int argc, char* argv[])
  • {
    • ...
    • Iw2DInit();
    • ...
    • Iw2DTerminate();
  • }

Source files making calls to Iw2D APIs should include “Iw2D.h”.

First, let’s look at rendering.cpp > SetupImages()

  • void SetupImages(int tileSize)
  • {
    • backgroundImage = Iw2DCreateImageResource("background");
    • starImage = Iw2DCreateImageResource("star");
    • logoImage = Iw2DCreateImageResource("logo");
      • ...
  • }

This function retrieves named images from the resource manager and prepares them for rendering with Iw2D.

We now look at rendering.cpp -> DrawSpriteCentered()

  • void DrawSpriteCentered(CIw2DImage* img, int x, int y, int size)
  • {
    • Iw2DDrawImage(img, CIwSVec2(x, y) - CIwSVec2(size/2, size/2), CIwSVec2(size, size));
  • }

This function takes an (x, y) pixel coordinate to draw to, and a pointer to an image to draw with (we previously stored the pointers to images in the SetupMaterials() function).

Iw2DDrawImage() draws the image to the specified coordinates stretched to the specified size.

CIwSVec2 is a class representing a 2D vector.

The (x, y) passed into the function becomes the (x, y) vector representing the top-left screen coordinate of the sprite.

Note: Several versions of Iw2DDrawImage() exist, taking different inputs. For example, it is possible to specify a sub-region of the image to draw use Iw2DDrawImageRegion.

The other Draw… functions within rendering.cpp are variations of this function, using the same Iw2D call.

Finally, look at game.cpp > PuzzleGame::Render()

  • void PuzzleGame::Render()
  • {
  • ...
    • // Set the 2D transform to have a translation to the top-left corner of where we want
    • // the main game area drawn. This reduces the complexity of the actual render functions
    • CIwMat2D trans = CIwMat2D::g_Identity;
    • trans.t.x = int16( displayWidth/2 - centeringWidth/2 );
    • trans.t.y = int16( displayHeight/2 - centeringHeight/2 );
    • if (previewTop)
      • trans.t.y += 3 * g_TileSize;
    • Iw2DSetTransformMatrix(trans);
  • ...
  • }

The call to Iw2DSetTransformMatrix() sets a matrix to multiply all incoming position by. This allows multiple 2D elements (in this case, the entire main play area) to be moved around easily.


Airplay SDK: Bitmap Font Rendering using the IwGxFont API

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Bitmap Font Rendering using the IwGxFont API >

Bitmap Font Rendering using the Iw2D API

Iw2D can also be used to render bitmap fonts output by the Airplay Studio Font Builder tool. This tool is used to generate two types of font files that are read by the Airplay runtime:

  • TGA – The Font Builder tool generates a TGA image containing all required font characters
  • GXFONT – The Font Builder tool generates a text file that points to the accompanying TGA file and specifies which characters are contained within the font

The Iw2D API must be initialised and terminated at the top and bottom of the application main loop:

  • int main(int argc, char* argv[])
  • {
    • ...
    • Iw2DInit();
    • ...
    • Iw2DTerminate();
  • }

Source files making calls to Iw2D APIs should include “Iw2D.h”.

Let’s look at main.cpp > UpdateScreenSize():

  • void UpdateScreenSize()
  • {
    • ...
    • // Choose font based on tile size
    • if (g_TileSize <= 16)
      • font = Iw2DCreateFontResource("font_small");
    • else
      • font = Iw2DCreateFontResource("font");
    • Iw2DSetFont(font);
    • ...
  • }

Ignore for the moment the use of the g_TileSize variable, and instead focus on how the code is storing a pointer to an Iw2D font object (object of type CIw2DFont). The call to Iw2DSetFont() then sets the font to draw with. (In BlocSlot, all text is rendered using a single font, but there is no restriction on how many times the current font can be changed within the application’s rendering code).

Now let’s look at game.cpp > PuzzleGame::Render():

  • void PuzzleGame::Render()
  • {
    • ...
    • // Draw player's score
    • char scoreString[32];
    • sprintf(scoreString, "%s %d\n%s %d", g_Localisation[ID_SCORE], score, g_Localisation[ID_LEVEL], level);
    • Iw2DDrawString(scoreString,
      • CIwSVec2(0,0), CIwSVec2((int16)displayWidth, (int16)displayHeight),
      • IW_2D_FONT_ALIGN_LEFT, IW_2D_FONT_ALIGN_TOP);
    • ...
  • }

The standard sprintf() call is used to build up the text string to draw. IwGxFont uses char strings, where each character is assumed to be in UTF-8 format; thus, 16-bit characters are also supported.

Then Iw2DDrawString() is used to draw the text string into the specified rectangle. The text is aligned with the top left of this rectangle.


Airplay SDK: Writing a Single Application that Accommodates Multiple Screen Resolutions and Rotations

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Writing a Single Application that Accommodates Multiple Screen Resolutions and Rotations >

Writing a Single Application that Accommodates Multiple Screen Resolutions and Rotations

Rather than assuming a particular screen size, the developer should write their application to accommodate multiple screen sizes. The application can query the device screen size using Iw2DGetScreenWidth() and Iw2DGetScreenHeight(). These functions return the width and height of the “screen” as far as the application is concerned; i.e. they may change if the physical device screen is rotated.

There are 3 elements that make up the BlocSlot game rendering:

  • Full-screen background image
  • Fonts (text showing score and game level)
  • Main play area (grid of tiles)

The full-screen background image is composed of many copies of a single sprite. The sprite is always the same size, irrespective of the screen size. The number of copies depends on the screen size. See rendering.cpp > DrawBG() for more details.

The font size varies according to the screen size. Two font sizes are provided; small and standard. See the UpdateScreenSize() function (copied below) for details on how the font size is changed according to screen size.

The main play area is made up of a grid of tiles. The tile size varies according to the screen size. Rather than having a single set of tile sprites that are stretched to different sizes, BlocSlot provides multiple tile sets at different pixel sizes; 12, 16, 24, 32 and 48. This allows the 2D artwork to be “pixel perfect” at all screen sizes. Whether a 2D game should use multiple image sets, or simply “stretch” a single image set to the required size, depends on the style of game and the artwork involved.

Let’s look at how BlocSlot responds to different screen sizes. Firstly, the main() function registers an Airplay System callback that will be called whenever the device screen is rotated:

  • int main(int argc, char* argv[])
  • {
    • ...
    • // Register a callback so we are informed when the screen is rotated
    • s3eSurfaceRegister(S3E_SURFACE_SCREENSIZE, ScreenSizeChangeCallback, NULL);
    • ...
  • }

The application callback function ScreenSizeChangeCallback() simply sets a global boolean variable:

  • // Callback from S3E when the screen size or rotation changes
  • int32 ScreenSizeChangeCallback(void* systemData, void* userData)
  • {
    • g_ScreenSizeChanged = true;
    • return 0;
  • }

Now, the main game loop checks this boolean value every frame, through the UpdateScreenSize() function:

  • int main(int argc, char* argv[])
  • {
    • ...
    • while(1)
    • {
      • // Check for user quit
      • if (s3eDeviceCheckQuitRequest())
        • break;
      • // Check for screen resizing/rotation
      • UpdateScreenSize();
      • ...
    • }
    • ...
  • }

Based on the screen width and height, the UpdateScreenSize() function sets up the following:

  • Tile size, as used by the main puzzle play area
  • Pointers to the tile materials to draw with, based on the calculated tile size
  • Pointer to the font to draw with, based on the calculated tile size
  • void UpdateScreenSize()
  • {
    • if (g_ScreenSizeChanged)
    • {
      • g_ScreenSizeChanged = false;
      • int x = Iw2DGetScreenWidth() / GAME_WIDTH;
      • int y = Iw2DGetScreenHeight() / GAME_HEIGHT;
      • int tempSize = MIN(x, y);
      • g_ScreenTooSmall = (tempSize<12);
      • if (tempSize < 16)
        • tempSize = 12;
      • else if (tempSize < 24)
        • tempSize = 16;
      • else if (tempSize < 32)
        • tempSize = 24;
      • else if (tempSize < 48)
        • tempSize = 32;
      • else
        • tempSize = 48;
      • if (g_TileSize != tempSize)
      • {
        • g_TileSize = tempSize;
        • // Look up materials by name
        • SetupImages(g_TileSize);
        • // Choose font based off tile size
        • if (g_TileSize <= 16)
          • font = Iw2DCreateFontResource("font_small");
        • else
          • font = Iw2DCreateFontResource("font")
        • Iw2DSetFont(font);
      • }
    • }
  • }

The game rendering code then uses g_TileSize to determine the (x, y) and (w, h) of all sprites. Thus, the entire game rendering becomes independent of screen size.


Airplay SDK: Writing a Single Application that Accommodates Keypad or TouchScreen Input

Airplay SDK > User Guide > Full Game Examples > BlocSlot 2D Puzzle Game Example > Writing a Single Application that Accommodates Keypad or TouchScreen Input >

Writing a Single Application that Accommodates Keypad or TouchScreen Input

Most Airplay System APIs allow for runtime checking of device functionality. Airplay applications should always perform runtime checking of device input hardware, and support all variants by supplying multiple variants of the application’s input code.

For example, the s3eKeyboard API allows for runtime checking of various aspects of key input available:

s3eKeyboard.h

  • typedef enum s3eKeyboardProperty
  • {
    • /**
    • * [read] Returns 1 if the keyboard supports numeric keypad s3eKey0 ... s3eKey9, 0 otherwise
    • */
    • S3E_KEYBOARD_HAS_NUMPAD = 0,
    • /**
    • * [read] Returns 1 if the keyboard supports alphabetic keys s3eKeyA...s3eKeyZ, 0 otherwise
    • */
    • S3E_KEYBOARD_HAS_ALPHA = 1,
    • /**
    • * [read] Returns 1 if the keyboard supports directional controls s3eKeyUp,
    • * s3eKeyDown, s3eKeyLeft, s3eKeyRight and s3eKeyOk, 0 otherwise.
    • */
    • S3E_KEYBOARD_HAS_DIRECTION = 2,
  • ...
  • };

Source files using the s3eKeyboard API should include “s3eKeyboard.h”.

Similarly, the s3ePointer API allows for runtime checking of the type of touchscreen/mouse/stylus input available:

s3ePointer.h

  • typedef enum s3ePointerProperty
  • {
    • /**
    • * [read,int] Pointer is available on device
    • */
    • S3E_POINTER_AVAILABLE = 0,
    • /**
    • * [read,write,int]
    • * Setting this to 1 will disable the cursor on system
    • * that have an OS/hardware cursor. Default is 0.
    • */
    • S3E_POINTER_HIDE_CURSOR = 1,
    • /**
    • * [read, int] Returns the type of pointer, one of @ref s3ePointerType.
    • */
    • S3E_POINTER_TYPE = 2,
    • /**
    • * [read, int] If the pointer is a stylus, returns the type of stylus, one of @ref s3eStylusType.
    • */
    • S3E_POINTER_STYLUS_TYPE = 3,
    • /**
    • * [read, int] Returns true if multitouch is avaliable.
    • */
    • S3E_POINTER_MULTI_TOUCH_AVALIABLE = 4
    };

Source files using the s3ePointer API should include “s3ePointer.h”.

Let’s look at how BlocSlot supports both key (e.g. mobile keypad) and pointer (e.g. mobile touchscreen) input. The workhorse function is game.cpp > UpdateInput():

  • void UpdateInput(int deltaTimeMs)
  • {
    • s3ePointerUpdate();
    • s3eKeyboardUpdate();
    • old_input_y = input_y;
    • input_y = input_x = input_rotation = 0;
    • int xMovement = 0;
    • if (s3eKeyboardGetState(s3eKeyAbsLeft) & S3E_KEY_STATE_DOWN)
      • xMovement--;
    • if (s3eKeyboardGetState(s3eKeyAbsRight) & S3E_KEY_STATE_DOWN)
      • xMovement++;
    • input_rotation = 0;
    • if (s3eKeyboardGetState(s3eKeyAbsGameA) & S3E_KEY_STATE_PRESSED)
      • input_rotation = -1;
    • if (s3eKeyboardGetState(s3eKeyAbsGameB) & S3E_KEY_STATE_PRESSED)
        • input_rotation = 1;
    • if (s3eKeyboardGetState(s3eKeyAbsUp) & S3E_KEY_STATE_PRESSED)
      • input_rotation = -1;
    • if (s3eKeyboardGetState(s3eKeyAbsDown) & S3E_KEY_STATE_DOWN)
      • input_y = 1;
    • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_DOWN)
    • {
      • g_DrawTouchscreenButtons = 1;
      • int displayWidth = IwGxGetScreenWidth();
      • int displayHeight = IwGxGetScreenHeight();
      • int x = s3ePointerGetX() * 3 / displayWidth;
      • int y = s3ePointerGetY() * 4 / displayHeight;
      • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_PRESSED)
      • {
        • if (x==0 && y==2)
          • input_rotation = -1;
        • if (x==2 && y==2)
          • input_rotation = 1;
      • }
      • if (x==0 && y==3)
        • xMovement--;
      • if (x==2 && y==3)
        • xMovement++;
      • if (x==1 && y==3)
        • input_y = 1;
    • }
    • // Clamp xMovement to the range [-1,1]
    • if (ABS(xMovement) > 1)
      • xMovement = (xMovement < 0) ? -1 : 1;
    • if (xMovement != autoRepeatValue || xMovement == 0)
    • {
      • // Reset auto-repeat timer
      • autoRepeatValue = xMovement;
      • autoRepeatTimer = 0;
      • input_x = xMovement;
    • }
    • else
    • {
      • autoRepeatTimer += deltaTimeMs;
      • if (autoRepeatTimer >= 200)
      • {
        • // Faster auto-repeat after the first repeat
        • autoRepeatTimer = 100;
        • input_x = xMovement;
      • }
      • else
        • input_x = 0;
    • }
  • }

s3ePointerUpdate() and s3eKeyboardUpdate() should be called once for each iteration of the application main loop.

s3eKeyboardGetState() gets the state of a specified key. The state can be compared against various fixed flag value (e.g. S3E_KEY_STATE_DOWN) to see if the key is currently up or down, and whether the key has just been pressed (i.e. was up, but now is down).

The accepted values of specified keys are enumerated in s3eKeyboard.h. Note how BlocSlot checks against “abstract keys”, using the s3eKeyAbs… values. This is highly recommended, as it allows the application to leverage Airplay’s mapping of these values to usable physical device keys for devices that might not support explicit key values. For example, a particular device might not support an explicit “select” key (s3eKeyOk), but will almost certainly support s3eKeyAbsOk (if the device has any keys at all) because Airplay will have mapped this “abstract key” to a usable physical device key. Furthermore, “s3eKeyAbsLeft/Right/Up/Down” are automatically remapped as appropriate if the physical device screen is rotated.

For devices with no key support, none of the s3eKeyboardGetState() checks will pass, and the code is effectively redundant.

Next, BlocSlot checks for pointer support:

  • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_DOWN)
  • {
  • ...
  • }

This check will fail if the device does not support pointer input. Otherwise, the code continues to run some pointer code as follows:

  • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_DOWN)
  • {
    • g_DrawTouchscreenButtons = 1;
    • int displayWidth = IwGxGetScreenWidth();
    • int displayHeight = IwGxGetScreenHeight();
    • int x = s3ePointerGetX() * 3 / displayWidth;
    • int y = s3ePointerGetY() * 4 / displayHeight;
    • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_PRESSED)
    • {
      • if (x==0 && y==2)
        • input_rotation = -1;
      • if (x==2 && y==2)
        • input_rotation = 1;
    • }
    • if (x==0 && y==3)
      • xMovement--;
    • if (x==2 && y==3)
      • xMovement++;
    • if (x==1 && y==3)
      • input_y = 1;
  • }

First, the g_DrawTouchscreenButtons global variable is set to ensure that “soft keys” are displayed; i.e. the when the player uses the pointer (e.g. touches the touchscreen) for the first time, this will trigger the display of the “soft keys” – see the function DrawTouchscreenButtons() further down the source file).

Next, we get the current x and y coordinate of the pointer:

  • int x = s3ePointerGetX() * 3 / displayWidth;
  • int y = s3ePointerGetY() * 4 / displayHeight;

We then check that the pointer has been pressed (e.g. the user has pressed the mouse button, or touched the touchscreen):

  • if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_PRESSED)

In this way, the game supports both key and pointer control from within a single application. The same concept could be used to accommodate other input mechanisms, e.g. accelerometer input through the s3eAccelerometer API.


Airplay SDK: BeatToy 3D Fighting Game Example

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example >

BeatToy 3D Fighting Game Example

BeatToy is a simple 3D Fighting Game. The game consists of 2 levels, where the aim is to win a fight against the opponent, or knock the opponent out of the arena. The opponent is controlled by ai.

The BeatToy Game

BeatToy illustrates the use of the following Airplay components:

  • S3E
  • IwUtil
  • IwGeom
  • IwGx
  • IwResManager
  • IwGraphics
  • IwAnim

The source code for BeatToy is located under: <SDK installation path>/examples/games/beattoy/

Two other modules are provided as source code:

  • ExampleSoundEngine

    A higher-level C++ sound API which sits on top of the S3E sound device.

  • ExampleGameFramework

    A C++ framework for game states, entities, etc.

Contents

  • Building the example
  • Running the example
  • What is happening with the assets?
  • Testing an ARM build within the ARM RTSM
  • Building and deploying the game on device


Airplay SDK: Building the Example

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > Building the Example >

Building the Example

To build the example, do the following:

  • Right click beattoy.mkb in the games/examples/beattoy directory and select Build All.

    • This will create a workspace for your programming IDE (VC++ or .NET, as set by the user when running s3eConfig.exe), launch the IDE and load the workspace.

  • Open up the list of Build Configurations. The list of Build Configurations is contained in a drop-down menu at the top of you IDE as illustrated in the following diagram.

    • You should see the following options:

    • Win32 ARM RVCT Build Release
    • Win32 ARM RVCT Build Debug
    • Win32 ARM GCC Build Release
    • Win32 ARM GCC Build Debug
    • Win32 Release
    • Win32 Debug
  • Select Win32 Debug.
  • Build the project in the usual way, from within the IDE.


Airplay SDK: Running the Example

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > Running the Example >

Running the Example

To run the example, do the following:

  • Run the project in the usual way, from within the IDE - either inside or outside the debugger.

    • The game displays a series of splash-screens, and then the main menu.

    The BeatToy Splash Screen

  • Press F1 to select the Lava level.

A Loading screen is displayed as the level assets are loaded and then the game begins.

The following controls can be used:

  • Arrow keys: move left, right, up or down
  • 5: Kick
  • 6: Punch
  • 8 : Crouch/Block
  • F3: Exit game (or Exit main menu)
  • F1: Select level (when in main menu)


Airplay SDK: What is Happening with the Assets

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > What is Happening with the Assets >

What is Happening with the Assets

Take a look at beattoy/data/data-low/environment/lava/lavaPieces_sw.group.

This text file (in ITX format) describes which input assets the game will load into the resource group named lavaPieces_sw.

Generating Binary Resources

When the Win32 Debug build of the game is run, the following happens:

  • The lavaPieces_sw.group text file is parsed and the required input assets (for example, lava.geo) are loaded.
  • A single binary file is written containing minimal binary versions of all the assets (resources). This file was written to:

    • beattoy/data-ram/data-gles1/environment/lava/lavapieces_sw.group.bin

Note that whenever an Airplay application writes a file, it writes it to data-ram rather than data. This is because it is useful for Airplay to maintain a separate concept of the file systems it is reading from and writing to. When Airplay is asked to read a file, it first looks within data, and if the file is not found, it looks within data-ram. When Airplay is asked to write a file, it always writes to data-ram (unless the user specifies an explicit absolute path to write to).

The resource manager outputs to a further subdirectory based on the current build style. The default build style is gles1, so the binaries are output to data-gles1.

Note that two other files have also been written:

  • beattoy/data-ram/data-gles1/environment/lava/lavapieces_sw.group.bin.txt
  • beattoy/data-ram/data-gles1/environment/lava/lavapieces_sw.group.hst

Open lavapieces_sw.group.bin.txt. This is a description of all the resources which have been included in the respective GROUP.BIN file. This can be useful for debugging resource-related issues.

lavapieces_sw.group.hst is a binary file which contains the string names of all the objects within the respective GROUP.BIN file. This file, if it exists, can be loaded by the game and used to provide full string names of all objects which have been loaded from a GROUP.BIN file. This can be useful for debugging purposes.

Now, once the resource manager has written the GROUP.BIN file, it proceeds to delete the entire resource group (named lavapieces_sw) it has just created. It then loads back the binary version (lavapieces_sw.group.bin) and the accompanying string table file (lavapieces_sw.group.hst) if it exists.

In this way, the entire process for building binary resources and loading binary resources is tested from within the Win32 Debug build of the game.

Note that resources are built using a seperate heap (the debug heap), but loaded back using the normal heap, so memory usage in the normal heap will exactly match the normal release build.

Loading Only Binary Resources

To load a GROUP.BIN binary file, rather than a GROUP text file, do the following

  • Exit the game (by pressing Esc, or repeatedly pressing F3).
  • Open up the app.icf text file.

    • This file contains settings which are read by Airplay at initialisation time to determine various parameters.

  • Find the ResBuild setting, and change it to:

    • ResBuild=0

  • Now run the game again.

This time, the resource manager has been placed into a mode where it ONLY loads the binary resources.

Therefore, a call to:

IwGetResManager()->LoadGroup(...)

...will load a GROUP.BIN binary file, rather than a GROUP text file.

Note that the user must play both levels of the game to ensure that all the GROUP.BIN files for the game are correctly built.

We are now in a position where we can do an ARM build of the game, and deploy it to a device together with all the GROUP.BIN files, and other script files required by the game.

Compressing Resources

Before we do that, let's try creating a compressed Derbh archive (DZ file), which contains ALL our game assets. This is achieved by doing the following:

  • Open up a command-line window, and navigate to:

    • <SDK installation path>/examples/games/beattoy/data/derbhscripts

  • Open up the beattoy-gles1.dcl text file.

    • This file describes how to create a Derbh compressed binary archive (DZ file) from several input files.

  • Double click on the dcl file to invoke the DZip executable (<SDK installation dir>/tools/DZip/DZip.exe)

    You should see the message "Compressing: DerbhZip". The DZip command-line (DCL) tool can take several seconds to create the archive.

    The beattoy-gles1.dcl text file describes the pathname for the archive. In this case, we have chosen to place it in beattoy\data\resources-gles1.dz.

  • Run the Win32 Debug build of the game again (still with the ICF file setting as ResBuild=0). You should see a dialog box indicating that the game has detected the DZ file, and will load all resources from the compressed archive. You should notice that the resources load much faster, even when running the Windows build.


Airplay SDK: Building Resources From Airplay Studio Director

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > Building Resources From Airplay Studio Director >

Building Resources From Airplay Studio Director

To build resources from within the Airplay Studio Director, do the following. The following sequence of actions will only be true the first time you build resources using Airplay Studio Director:

  • Launch the Airplay Studio Director tool.
  • Select a new project by clicking Project->Setup Project...
  • Use the presented Select Project... dialog to browse to /examples/games/beattoy/data and set this as your project.
  • Name the project 'BeatToy'.

    • Airplay Studio Director now displays the complete folder hierarchy of all the game assets.

  • In the tree view, open environment\lava.
  • Right-click on lava.group and Select Action->Build binary.
  • Click past the following dialog, with OK.

    • Airplay Studio Director now displays the Select game .s86 file dialog.

  • In this dialog enter the location of the game's Win32 Debug build (for example, when using Visual Studio 6 the Win32 Debug build is the .s86 file located at beattoy\build_beattoy_vc6\Debug_beattoy_vc6_x86\beattoy.s86.
  • Click Open.

Airplay Studio Director now runs the game, and tells it to build the GROUP.BIN file corresponding to 'lava.group'. This process takes several seconds.

In this way, artists/designers can build GROUP.BIN files from within their own environment.

We can also build Derbh archives (DZ files) from within Airplay Studio Director. To do this:

  • In the tree view, open derbhscripts, and right-click on beattoy.dcl.
  • Select Action->Build Archives.

Airplay Studio Director now runs the DZip command-line tool, and in this case builds the resources.dz archive.

The process takes several seconds, according to the size of the archive. If the archive built without errors, you will see the following lines in the Airplay Studio Director log window:

Derbh: Compressing: DerbhZip
Derbh: Created successfully
Derbh: Process Finished


Airplay SDK: Testing an ARM build within the ARM Emulator

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > Testing an ARM build within the ARM Emulator >

Testing an ARM build within the ARM Emulator

To test an ARM build within the ARM Emulator, do the following:

  • Open up the workspace again within the programming IDE, and select the Win32 ARM RVCT Build Debug configuration.
  • Build the project in the usual way, from within the IDE.
  • When the build is complete, press F5 to run the game in the ARM Emulator tool.

The game should run in the tool, and you can set breakpoints and debug at either source code or ARM disassembly level.


Airplay SDK: Building and Deploying the Game on Device

Airplay SDK > User Guide > Full Game Examples > BeatToy 3D Fighting Game Example > Building and Deploying the Game on Device >

Building and Deploying the Game on Device

To build and deploy the game on device, do the following:

  • Open up the workspace again within the programming IDE, and select the ARM RVCT/GCC Build Release configuration.
  • Build the project in the usual way, from within the IDE.
  • When the build is complete, press F5 to run the Airplay System Deployment Tool.

    • The Deployment Tool

  • Follow the standard steps to complete the deployment process:
    • Select the OS/Platform you wish to deploy to.
    • Check the configuration options (the chosen platform may require signing certificates to be set).
    • Choose Package or Package and Install at the Deploying stage.
    • Hit Deploy All and follow the on screen prompts if you chose to install, or copy the output files to device if you chose Package
  • Run the game on the device!


Airplay SDK: F.A.Q.

Airplay SDK > User Guide > F.A.Q. >

F.A.Q.

This document lists frequently asked questions, and answers, regarding the Airplay SDK.

Question List

Generic Questions:

  • Why does my application run in the Windows Simulator but not on device?
  • How will the profile setting on a device affect an application running on it?
  • What is the best way to display non roman type fonts (for example: Japanese, Chinese, Korean,... characters)?
  • How can a "PTVert cache overflow" error be resolved?
  • How can .RAW sound data (for usage by the s3e Sound module) be created?
  • How can two or more sounds (music and sound effects) be played at the same time?
  • What is the correct way of dealing with an "Out of T-Pages" error?
  • How can the sizes of polygon buffer, vertex- and data cache be optimised best?
  • How can the material of a CIwModel be changed once it has been loaded from file?
  • How can hardware supported floating point processing be taken advantage of?
  • How can the function of "IwGxSetPerspMul" be interpreted correctly?
  • What is the concept of pitch (e.g. S3E_SURFACE_DEVICE_PITCH)?
  • In which order are valid s3e files executed?
  • How does command line input correlate to icf file settings?
  • How do the GPRS Settings need to be configured to work with UK Operators?
  • How can the "Win32Surface S3E"-Extension be used to redirect the output of s3eSurface?
  • How are paths handled in Airplay?
  • How can Device IDs in win32 builds be set by command line?
  • What does the error message "System malloc failed allocating x bytes" upon application startup mean?
  • Which icf settings can be used to manipulate the memory heap?

BREW Related Questions:

  • How to configure the BREW 3.1.x Simulator to be able to test socket functionality?
  • How are BREW "Debug Key Sequences" activated and what is their effect?
  • How can the APN (Access Point Name) setting be changed on BREW WCDMA handsets?
  • How can handset signature files (.sig) using MEIDs rather than ESNs be created?
  • How can PCM streaming be disabled in the Brew 3.x Simulator?
  • How can content be loaded onto the Siemens-Benq EF91 handset?

iPhone/iPod Touch Related Questions:

  • How does Airplay support pinch-in/pinch-out gestures on multi-touch devices?

Windows Mobile Related Questions:

  • Why is the Windows Mobile CAB compression option disabled by default?

Why does my application run in the Windows Simulator but not on device?

When moving from Windows development to testing the application on a device, there are sometimes discrepancies between the two environments that can cause errors.

The following are common reasons why an application runs in Windows, but not on device:

  • The device runs out of memory. Solution: reduce memory size in the application ICF file. It is recommended that you work to a 4mb maximum from the start
  • Typed pointers are cast to larger typed pointers. Under ARM, the resulting pointer will be aligned at the new size (i.e. point to a different place) - avoid this type of code.
  • The application is not yielding enough. The application is not giving the device OS enough time to carry out its essential tasks. Solution: force the application to yield using the relevant functionality. For information on how to force an application to yield, see the S3E Device Interface section of the API Reference.
  • Windows Mobile compression is on but not supported. This option is only valid for Windows Mobile 6 and above, see here.

How will the profile setting on a device affect an application running on it?

Applications created using Airplay respect the Profile configuration selected on a handset. How this affects the application will vary to conform to the standard requirements for each given platform.

The most obvious effect of this is that if the Silent profile is selected on a handset, the Airplay application will produce no sound on start-up. On most platforms, using the functions contained in s3eAudio, s3eSound and s3eVideo to change the application volume while the Silent profile is selected will have no affect. The notable exception to this is N-Gage, on which the volume will start at zero but can be subsequently increased (in order to conform to N-Gage standard game requirements).

Other functionality such as the ability to vibrate using s3eVibra will also depend on whether the current profile allows these features to be used.

What is the best way to display non roman type fonts (for example: Japanese, Chinese, Korean,... characters)?

Displaying non-roman type fonts is easiest achieved by using the IwGxFont module, which supports rendering of texture based fonts and therefore supplies the potential to display localised text in virtually any character set. It uses specialised fonts which need to be created using the Airplay Studio Font Builder.

Note: Please be careful to save any text to be imported as a UTF-8 text file. (See the documentation of your editor on how to save files in this format)

How can a "PTVert cache overflow" error be resolved?

This error can be observed, when rendering of a large number of primitives is being performed. It can be countered by increasing the value of the "[GX] VertCacheSize" icf setting in the application icf file, which in effect increases the number of vertices, that can be processed at once.

The following [GX] icf settings are also having an effect on the number of polygons which can be rendered at the same time: (all sizes mentioned are measured in bytes)

  • [GX] PolyBufferSize: Size of the buffer used for the draw-list.
  • [GX] DataCacheSize: Size of the global IwGx data cache.

Note: Increasing of these values is will require more memory and therefore may cause problems, when running on device.

When indicated in the error message, it is also useful to have a look at the "IwGxInfo.txt" file, which is created in such an incident; It contains a dump of all cached geometry info. In the above mentioned situation, the "Verts Transformed" section will provide a good starting point for fixing this problem

Fur further reading please refer to the Airplay Performance Guidelines whitepaper.

How can .RAW sound data (for usage by the s3e Sound module) be created?

For creation of raw sound data files, any general purpose sound conversion utility can be used.

The SoX - Sound eXchange application is one of them and can be found here.

Example command lines are:

  • sox originalsound.wav convertedsound.raw rate 8000

  • sox originalsound.wav convertedsound.raw channels 1 rate 8000

How can two or more sounds (music and sound effects) be played at the same time?

Included in the Airplay SDK are two modules which deal with playback of sounds:

  • S3E Audio
  • S3E Sound

S3E Audio plays an assortment of file types, is platform dependent and relies on the functionality of the underlying OS. S3E Audio uses the capabilities of the hardware to handle various compressed audio file formats and should only be used for simple sound file playback, whereas S3E Sound exposes a multi-channel software mixer to ensure hardware independent functionality. Usage of the S3E Sound Module is therefore the "correct" way to achieve multi-channel sound.

Note: Due to hardware restrictions, it is not possible to use S3E Audio and S3E Sound simultaneously.

For further help, please use any of the provided examples :

  • S3E Sound Basic Example
  • S3E Sound Advanced Example
  • S3E Sound Streaming Example

What is the correct way of dealing with an "Out of T-Pages" error?

When using the software renderer, uploading textures moves them into specially allocated texture pages (T-pages). Each texture page is 256 bytes wide and 256 bytes high. The above error indicates, that there is no more space for further texture uploading left.

The default number of texture pages used for storing textures is 16, however the number of T-pages can be increased via [GX] icf setting in the application's icf, such as:

  • [GX]
  • NumTPages=EnterNumberHere

Note: It is important to mention that increasing the number of T-pages also increases demand for memory and therefore might cause problems on low end devices.
Before increasing this value please determine if the increased demand for T-Pages is warranted. Many times this behaviour is connected to a bug, where new textures are constantly being uploaded without old ones ever getting released. Another possible solution would be to determine which textures need to be available at a certain time and therefore manage uploaded textures (for example game level dependent).

How can the sizes of polygon buffer, vertex- and data cache be optimised best?

All three values correspond to different aspects of the drawing pipeline and can be changed via [GX] icf settings in the application's icf:

  • [GX] PolyBufferSize: Size of the buffer used for the draw-list.
  • [GX] DataCacheSize: Size of the global IwGx data cache.
  • [GX] VertCacheSize: Size of the IwGx software vertex cache.

It is important to note, that the amount of polygon buffer, vertex- and data cache used by primitives depends on several factors, including:

  • Modulation mode
  • Colour space
  • Alpha mode
  • SW or GL rendering

In order to determine the exact amount of these buffers used, the Windows Simulator's metrics system should be utilized. It can be accessed via the "Metrics" entry in the menu bar of the Windows Simulator: Choose "Display Metrics" to open the metrics display window, then expand "Airplay Studio", followed by "IwGx" in the tree control. All three buffer sizes are represented by the following entries:

  • "Vert Cache Entries"
  • "Poly Buffer Bytes"
  • "Data Cache Bytes"

Note: The vertex cache is actually displaying the number of entries, not the actual number of bytes used. However, the value being set in the ICF file also corresponds to the number of entries, not bytes, therefore the metrics display is still useful.

Using this system along with the polygon throughput (entry "Polygons Rendered" in the GX metrics page), it is straightforward, to determine maximum usage and therefore easy to optimise memory requirements.

Example:
Using the above described method, the following values have been determined for a given application, per rendered quad:

  • 32 bytes of DataCache
  • 4 entries in the VertexCache
  • 60 bytes of PolyBuffer

with icf settings configured as follows:

  • DataCacheSize=100000 //allows rendering of 3125 (=100000/32) quads
  • VertCacheSize=10000 //allows rendering of 2500 (=10000/4) quads
  • PolyBufferSize=200000 //allows rendering of 3333 (=200000/60) quads

a maximum of 2500 quads could be displayed, as the limiting factor in this case would be the vertex cache.

How can the material of a CIwModel be changed once it has been loaded from file?

There are three different ways in which this can be achieved:

First use CIwModel::CloneWithNewMaterials. This function creates a new model, which points to the original model-blocks, except the standard primitive model-blocks, which are copied and pointed at by the newly created model. Once this is done, it is possible to modify the new model's m_Materials list, which is a public member of CIwModel, directly.

The second way to achieve this, is to set a different list of materials using IwGetGraphicsState()->m_OverrideMaterials, whereas m_OverrideMaterials is a pointer to the new materials to use by CIwModel's Render() function instead of its own material array.
Note: The overriding list must be the same length as the model's material array.

Pseudo-code:

  • CIwManagedList myMaterials1, myMaterials2; //contain alternative materials
  • IwGetGraphicsState()->m_OverrideMaterials = &myMaterials1;
  • pModel->Render(); //render with myMaterials1
  • IwGetGraphicsState()->m_OverrideMaterials = &myMaterials2;
  • pModel->Render(); //render with myMaterials2
  • IwGetGraphicsState()->m_OverrideMaterials = NULL;
  • pModel->Render(); //render with original materials

Finally, it is also possible to use IwGxSetMaterialFixed() if the model has only one material.

How can hardware supported floating point processing be taken advantage of?

Internally Airplay uses 1.3.12 fixed-point only in all the IwGx, IwGraphics and IwAnim pipelines (positions, normals, colours, UVs). This approach is even preferable to, for example the iPhone GPU, as the use of 16-bits per component is half the bandwidth compared to 32-bits per component used by float. It is however planned to include an optional floating-point pipeline in future Airplay SDK versions.

If the application code itself makes heavy use of C++ float types, it is possible to create builds which assume hardware enabled float support via the arm-fpu icf setting, which is to be set as an MKB option.

How can the function of "IwGxSetPerspMul" be interpreted correctly?

The IwGxSetPerspMul function sets the "perspective multiple", which is a way for the user to set the frustum's field-of-view. The "perspective multiple" represents the distance from the camera (the "eye point") to the viewing plane, whereas the viewing plane can be seen as the conceptual 2D plane onto which a 3D world is being projected on;
Note: The viewing plane is not the same as the near plane.

Example:
In order to obtain a horizontal field-of-view of 90 degrees, the perspective multiple would have to be set to equal to half the screen width:

  • IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

What is the concept of pitch (e.g. S3E_SURFACE_DEVICE_PITCH)?

Even tough a display surface is represented by a contiguous range of addresses, it is not safe to assume that the last pixel on one row exists at an address one byte below the address of the first pixel on the next row. The actual difference between two rows is called "pitch" and will be different on display adapters from different manufacturers.

Example:
The Basic Example contains a function fillScreen, in which the addresses of single pixels of the display surface are calculated by the following formula: y * pitch/2 + x. As this example is written using 16 bit colour information per pixel, the pitch which is usually calculated in bytes needs to be processed as 16 bits as well and therefore halved (=divided by 2).

In which order are valid s3e files executed?

First the application's icf file and the s3e.icf file in the same directory as the loader are checked for the "[S3E] gameExecutable" icf setting . Using this setting, an alternative pathname to the .s3e application executable to load can be specified in the following way:

  • [S3E]
  • gameExecutable="FileName.s3e"

Note: The alternative s3e files path needs to being specified as a path relative to the loader.

In case multiple "[S3E] gameExecutable" settings are encountered, an error is thrown, otherwise, the s3e file specified is loaded and executed. If unspecified, the loader scans the current directory for s3e files. If a single s3e file is found, it is executed. If multiple or no s3e files are found, an error is thrown.

How does command line input correlate to icf file settings?

S3E loaders on Windows and Linux platforms parse the command line options as follows:

"-myvar:myval" as a command line option is equivalent to the following line in the application's icf file:

  • [Commandline] myvar=myval

,while "-mysection:myvar=myval" as a command line option translates to the following icf setting:

  • [mysection] myvar=myval

How do the GPRS Settings need to be configured to work with UK Operators?

O2 GPRS settings:

  • Access Point Address: mobile.o2.co.uk
  • Username: "mobileweb"
  • Password: "password"
  • Session Type: Continuous / permanent
  • Authentication: Normal
  • Security: Off
  • HTTP Proxy: 193.113.200.195
  • Port Number: 8080
  • DNS Servers: 193.113.200.200 and 193.113.200.201

Note: The "Mobile Web" service must be enabled for these settings to work.

Vodafone GPRS settings:

  • Contract Access Point Address : internet
  • Access Point Address : pp.vodafone.co.uk
  • Username: "web"
  • Password: "web"
  • Session Type: Continuous / permanent
  • Authentication: Normal
  • Security: Off
  • Port Number: 8799
  • DNS Server: 212.183.137.012

Note: It is also possible to try the following alternative account:

  • Username: "faster"
  • Password: "password"

Orange GPRS settings:

  • Contract Access Point Address: "orangeinternet"
  • Pay-as-you-go Access Point address: "payginternet"
  • Username: [leave blank]
  • Password: [leave blank]
  • Authentication: Normal
  • Email SMTP server: smtp.orange.net
  • Primary DNS Server: 158.43.192.1
  • Secondary DNS Server: 158.43.128.1

How can the "Win32Surface S3E"-Extension be used to redirect the output of s3eSurface?

The Win32Surface S3E Extension makes it possible to redirect the output of s3eSurface to a specified HWND. This functionality is useful to allow development of Win32 GUI Tools.

Example Code:

  • #include "S3E.h"
  • #include "s3eExt_Win32.h"
  • #include <windows.h>
  • HWND g_hwnd;
  • //-----------------------------------------------------------------------------
  • // Main global function; Required by IwMain.cpp
  • S3E_MAIN_DECL void IwMain()
  • {
    • // Create handle
    • g_hwnd = CreateWindow("MainWndClass",
          • "S3E TEST",
          • WS_OVERLAPPED|WS_CAPTION|WS_SYSMENU|
          • WS_MINIMIZEBOX|WS_THICKFRAME|WS_CLIPCHILDREN,
          • CW_USEDEFAULT,
          • CW_USEDEFAULT,
          • 120,
          • 240,
          • (HWND)NULL,
          • (HMENU)NULL,
          • GetModuleHandle(NULL),
          • (LPVOID)NULL);
    • // Attach extension
    • s3eExtWin32SurfaceAttachFn pAttachFn = NULL;
    • s3eGetExt("Win32Surface", &pAttachFn, 1);
    • if (pAttachFn)
      • pAttachFn((void*)g_hwnd,120,240);
    • //Main application loop
    • while (!s3eDeviceCheckQuitRequest())
    • {
      • uint16* ptr = (uint16*)s3eSurfacePtr();
      • for (int x=40;x<80;x++)
        • for (int y=40;y<80;y++)
          • ptr[x+y*120] = 3456;
      • s3eSurfaceShow();
      • s3eDeviceYield(0);
    • }
    • return;
  • }

How are paths handled in Airplay?

Paths in s3e are similar to those seen on other platforms. They are made up of an optional drive, a list of directories separated by either forward-slashes '/' or back-slashes '\' and usually a filename.

The drive specified is of the form '<drive>://' where <drive> is one of:-

  • 'rom' : for the read-only portion of the s3e data area
  • 'ram' : for the writable portion of the s3e data area
  • 'rst' : for a removable memory card
  • 'raw' : for paths that will be passed directly to the underlying operating system without modification. These paths are for debugging only and are not supported in release loaders.

Paths can be up to a maximum of S3E_FILE_MAX_PATH (=128 bytes) long, including the NULL terminator. Longer Paths will cause an "S3E_FILE_ERR_INVALID_PATH" error to be thrown.

Paths in s3e are not case sensitive. Any slashes at the beginning of the path will be ignored. Duplicate separators (mydir//myfile) are automatically reduced to a single separator (mydir/myfile). The use of the previous directory '..' is permitted in paths, provided that the path does not resolve to one that is higher than the root.

Examples of valid paths are:

  • myfile
  • rom://myfile
  • mydirectory/myfile
  • MYDIRECTORY\myfile (same as mydirectory/myfile)
  • /MYDIRECTORY\myfile (same as mydirectory/myfile)
  • /MYDIRECTORY\\myfile (same as mydirectory/myfile)
  • mydirectory/ignored/../myfile (same as mydirectory/myfile)
  • raw://c:\temp\myoutputfile (for debugging only!)

The concept of different S3E Drives (ram, rom, rst and raw), is very powerful and explained in detail in the Airplay concept's data section. This section also explains, why using explicit drives in paths is a discouraged practice.

How can Device IDs in win32 builds be set by command line?

As the Windows Simulator is a powerful debugging tool, it might be sometimes useful, to use it for testing of device specific configurations. This can be done by adding extra entries in the application's icf file:

The icf entry needs to be in the following form:

  • {ID=WINDOWS DeviceID}
  • Setting=Value

  • DeviceID provides the trigger for a device specific configuration;
  • Setting represents an attribute that a value can be assigned to; Attributes can either be predefined icf settings (like MemSize, ScreenSize, KeyboardHasKeypad, SupportsAudioMP3,...) or completely arbitrary settings, which can be parsed via the S3E Configuration Module.
  • Value represents a valid value associated with the setting and might be of different types (string, integer, boolean,..)

When starting a win32 build from command line, the trigger (=DeviceID) can be set by using the following command line option:

  • -win32deviceid:DeviceID

where DeviceID corresponds to the above added entry in the application's icf file.

What does the error message "System malloc failed allocating x bytes" upon application startup mean?

Airplay applications can only allocate memory from a number of separate heaps through the S3E Memory API. These heaps are created using native operating system memory on application startup. If the asked for heapsize is bigger than the available memory on target device, the above error message is being displayed.

This means, that the application needs to reduce the amount of memory it uses, before it can run on the target device.

Which icf settings can be used to manipulate the memory heap?

The ICF file settings for game heap configuration, which are part of the [S3E] group, are as follows:

The user can create up to S3E_MEMORY_MAX_HEAPS (=8) different memory heaps for use. Most of the times one or two heaps are sufficient tough.

The size of each heap is specified by specifying MemSize<x> = <size> Where x is the heap number (1-8) and <size> is the desired size of that heap:
Example:

  • [s3e]
  • MemSize5=100000

Creates heap 5 of size 100000 bytes.

If MemSize<x> is not present for a heap or <size> is zero then the heap is not created. The only exception is heap 0 (the main application memory heap), which will be created with a default size of 4Mb on Device or 10Mb on Windows/Linux if no size is specified.

Switching between different heaps in the user application is done by the function s3eMemorySetInt(S3E_MEMORY_HEAP, x). Subsequent allocations will be done from the selected heap. There is no need to switch back to the correct heap to free or reallocate a memory block, because s3eFree/s3eRealloc will always free/realloc from the appropriate heap.

MemSize=<size> (without a heap specified), behaves as an alias for MemSize0=<size>

There are several options for configuring each heap. These options are specified in the following manner:

MemFlags<x>=<flag1>,<flag2>,...,<flagn> where <x> is the number of the heap and <flag1>, <flag2>,... are one or more of the following:

  • NO_MSG_ON_FAIL : prevents s3e from displaying out-of-memory dialogs if allocations fail on the specified heap
  • USE_STACK_ALLOCATOR : uses a simple stack based allocator for the heap instead of the usual memory allocator. This can minimise memory wastage if the heap is to be used in a purely stack based fashion (first allocated is last freed)
  • INACTIVE : prevents the heap from being initially created (and therefore prevents it consuming OS memory). The heap can then be instantiated later with a call to s3eMemoryHeapCreate. Likewise calling s3eMemoryHeapDestroy on any heap will free all OS memory used by the heap and put it in an inactive state. All attempts to allocate from an inactive heap will fail immediately.

How to configure the BREW 3.1.x Simulator to be able to test socket functionality?

Upon Simulator startup, an image of a device, defined in the device configuration file (.qsc), is opened up. Included in this file is the following line

  • SOCKETS 1 0 0 0 1472

Whereas: SOCKETS <nSocketLimit> <bListenAccept> <bShutdown> <bLoopback> <nMaxSendTo>

  • nSocketLimit: maximum number of sockets. Default: 1
  • bListenAccept: the device supports Listen/Accept(). Default: 0
  • bShutdown: the device supports Shutdown(). Default: 0
  • bLoopback: the device supports a loopback interface (i.e. 127.0.0.1). Default: 0
  • nMaxSendTo: the maximum payload size for UDP datagrams sent via OEM_SendTo(). Default: 1472 bytes

Correct socket functionality can be tested, by increasing the number of sockets and at the same time turning the Listen/Accept flag to "on", resulting in the following:

  • SOCKETS 2 1 0 0 1472

Note: It is possible, for device images running on the BREW 3.1.x Simulator, that the SOCKETS parameter may not work. In this case the IDS_DD_DATA_MAX_UDP and/or IDS_DD_DATA_MAX_TCP values need to be configured in the .dsd file.

The behaviour does not occur on the BREW 2.1.x Emulator.

How are BREW "Debug Key Sequences" activated and what is their effect?

Debug key sequences are intended for use by developers to assist in troubleshooting BREW application errors. Unfortunately, phone behavior may be adversely impacted when debug sequences are active ? including crashing the device. As such, BREW applications should be designed in such a way that the user is not likely to inadvertently enter a debug sequence while interacting with the application. This is primarily a concern on BREW 2.0 devices, as later BREW versions incorporate protections to prevent unintentional debug mode activation. If there is a large potential within a BREW application for accidental debug mode activation during typical use cases, NSTL may fail the application.

Debug sequences may be activated at any time while BREW is active ? including within the BREW applications manager.

Behaviour in the different BREW versions, is as follows:

  • BREW 2.0: The debug sequences are enabled by default - regardless of whether the phone has been test-enabled. To activate the debug sequence, enter ###
  • BREW 2.1, 3.0: Debug sequences are enabled only if the phone is in test-enabled state. To activate the debug sequence, enter ###
  • BREW 3.1+: The debug key sequence has been lengthened, reducing the likelihood of accidental activation. To activate the debug sequence, enter ###BREWDEBUG#, then ###[debug type]#

The initial ### sequence before the debug type is OEM-configurable. For example, LGE has opted to use ********** (10 * keys) rather than ###. Most OEMs use the default sequence. However: The LG VX6000/4500/4600 line, for example uses **********X as the sequence. The LG VX7000/8000, on the other hand, uses #######X and On other VX8000's it's *******X ( '*' 7 times ). This information is typically documented on the known issues page for each device.

The different debug types are listed below:
0: Turn Debugging off. This debug key sequence resets/toggles off all debug states.

1: Memory validation on every heap access. BREW walks the heap to determine if the pointer is in valid range and will not over-write/over-read a heap node. An exception will be thrown if the heap access will cause corruption of a heap node.

2: Net Debug Tool: The "Net Debug Tool" can be used to view the device's network (socket and PPP) states while your application is running. When the Net Debug Tool is turned on, a box will appear in the right hand corner and will display a series of codes that can be used to determine the state of your application's data call. The codes vary depending on BREW version and are shown below:

Network State Codes:
BREW 1.0:

  • c : Socket Connecting
  • C : Socket Connected
  • x : Socket Closing
  • X : Socket Closed
  • I : Socket Idle
  • R : Socket Read
  • W : Socket Write
  • d : PPP Opening
  • D : PPP Open
  • - : PPP Closing
  • O : PPP Closed

BREW 1.1:

  • c : Socket Connecting
  • C : Socket Connected
  • x : Socket Closing
  • X : Socket Closed
  • I : Socket Idle
  • R : Socket Read
  • W : Socket Write
  • r : Socket RecvFrom
  • w : Socket SendTo
  • d : PPP Opening
  • D : PPP Open
  • z : PPP Closing
  • Z : PPP Closed

BREW 2.0:

  • c : Socket Connecting
  • C : Socket Connected
  • x : Socket Closing
  • X : Socket Closed
  • I : Socket Idle
  • b : Socket Bind
  • B : Socket Bound
  • R : Socket Read
  • W : Socket Write
  • r : Socket RecvFrom
  • w : Socket SendTo
  • v : PPP Opening
  • = : PPP Open
  • v : PPP Closing
  • # : PPP Closed
  • < : PPP Sleeping
  • & : PPP Asleep
  • > : PPP Waking

3: "Largest Available Heap Block": Displays the maximum size block that can be allocated on the heap in the upper left corner of the screen.

4: "Debug Privileges": This debug sequence is not yet implemented.

5: "Debug Malloc": Throws an exception on malloc failure.

6: "Debug Null": When this debug sequence is turned on, every Nth MALLOC will fail, even if RAM is available. Currently, N is set to 100.

7: "Sync/Async DBGPRINTF": This debug sequence toggles between two modes: synchronous DBGPRINTF and asynchronous DBFPRINTF. In synchronous DBGPRINTF mode, BREW waits for certain duration before returning from a DBGPRINTF statement in order to allow time for the DBGPRINTF message to be sent on the serial port. In the default, asynchronous mode, the DBGPRINTF returns immediately.

8: "Debug Dump Modules": This debug sequence is not yet implemented.

9: "Debug Dump Heap": Every time this sequence is pressed, heap and resource usage information is dumped on the emulator debug window or onto the Serial port. The heap info consists of the number of bytes, the system that allocates it, an internally used index, the file name and line number, and whether the memory is locked (L) or unlocked(U). Additional information is displayed on Allocated and Free RAM, and resource usage.

How can the APN (Access Point Name) setting be changed on BREW WCDMA handsets?

Changing of the APN setting can be achieved by using any modem control application, like HyperTerminal (which is part of Windows) or minicom (for Linux users). The first step is to connect the modem control application to the handset. The actual settings change is done using an AT command. AT commands are instructions used to control a modem, whereas AT is the abbreviation of ATtention.

In order to change the APN, the following line should be used, where "newAPN" represents the new Access Point Name:

  • AT +CGDCONT=1, "IP", "newAPN"

How can handset signature files (.sig) using MEIDs rather than ESNs be created?

Signature files can be created using either ESN, IMEI or MEID, whereas:

  • ESN (Electronic Serial Number): Are control numbers used for cell phone activation in wireless carrier networks. ESN-DEC are 12 numeric digits long and ESN-HEX are 8 numeric digits long.
  • IMEI (International Mobile Equipment Identity): Are numbers unique to every GSM and UMTS mobile phone used to identify valid devices. IMEI are 15 digits long.
  • MEID (Mobile Equipment Identifiers): Are unique numbers found on CDMA mobile phones. MEID are 15 alpha-numeric digits long followed by six zeros and a serial number.

On BREW handsets, the MEID printed on the back is only 14 digits long. Attempting to generate a sig file using only 14 digits will fail, because the form of an MEID is:

  • First 8 digits from the manufacturer's code
  • Next 6 digits from the serial number
  • The last digit (0 to 9) is the check digit

Therefore, if the handset MEID are only 14 digits long, correct length for the Qualcomm signature generation site can by accomplished by simply suffixing the MEID with an additional digit; Which in effect creates an arbitrary check digit.

How can PCM streaming be disabled in the Brew 3.x Simulator?

Since PCM streaming is a very expensive functionality, it is sometimes useful to disable PCM streaming in the Brew 3.x Simulator, in order to run applications at a sensible speed:

To disable it, open the ".dsd" xml file from the device pack, using a text editor and change the IDS_AEECLSID_MEDIAPCM section accordingly:

Example:

The original entry:

  • <String Id="8219" Name="IDS_AEECLSID_MEDIAPCM">
    • <Text>16798993,1,65536,65537,65538,65539,65540,65541,4,5</Text>
  • </String>

The second argument in the comma delimited list needs to be set to "0":

  • <String Id="8219" Name="IDS_AEECLSID_MEDIAPCM">
    • <Text>16798993,0,65536,65537,65538,65539,65540,65541,4,5</Text>
  • </String>

How can content be loaded onto the Siemens-Benq EF91 handset?

As with all BREW devices, the first step is to generate a valid signature file (".sig") using either of the handset's IMEI, ESN or MEID on Qualcomm's signature generation site. The device's IMEI can be retrieved by typing "*#06#".

In the next step, the contents is uploaded to the device by the BREW Apploader, using settings for a BREW 3.1 device.

Once the contents is loaded onto the handset, access can be gained via the application manager, which can be activated using the following key combination "*#APPMGR#" followed by the green "Send"-key.

How does Airplay support pinch-in/pinch-out gestures on multi-touch devices?

The Airplay SDK (as well as the Apple iPhone SDK) handles gesture detection explicitly based on touch information. The s3ePointer Module -which supports multi-touch- provides the functionality to retrieve and set pointer state information;

Pinch-in/pinch-out gesture detection can be implemented in the following way: On receiving either an s3ePointerTouchEvent or s3ePointerTouchMotionEvent, query the m_TouchID member, which is being uniquely, generated by the system for every active touch point. As the user touches and drags, all the events associated with that touch point will retain the same ID. Therefore when a 'pinch action' is being performed, you will receive events with two distinct IDs, which can be easily identified and processed.

Testing can be done using the Windows Simulator. Make sure tough, that multi touch simulation is enabled by checking the "Report multi touch available"-checkbox from the Configuration->Pointer... entry in the menu bar. Use the middle mouse button to add, drag and remove touches.

Why is the Windows Mobile CAB compression option disabled by default?

Cab (installation) files support a compression option which can be set through the 'Compress cab' deployment option (see Windows Mobile Configuration Settings) or corresponding winmobile-cab-compress MKB Setting (see MKB Deployment Options).

This is only supported by devices running the Windows Mobile operating system at version 6 or newer. When attempting to install a compressed cab on an older device - e.g. a smartphone running Windows Mobile 5 - the application will fail to install, and usually without providing useful feedback to the user. For this reason, this option is disabled by default and should not be used if you intend the application to be deployed to any devices running a Windows Mobile version older than version 6.


Airplay SDK: File Types

Airplay SDK > User Guide > File Types >

File Types

Airplay makes use of several specifically designed file types to store and manage data. These are listed below and are broken up into System and Studio groups for ease of viewing. This is not an exhaustive list of all the files that may be used within Airplay; see the appropriate sections of the documentation for more information on other file types and file compatibility.

Files are referred to by file-type throughout the documentation by using the extension in uppercase. For example, 'ICF file' refers to a file of format '<filename>.icf'.

Airplay System File Types

(APP).ICF

This is the application-specific configuration file. It uses the ICF format which is similar to that of Windows INI files. The ICF file used by an application/project is named 'app.icf' by default. This filename can by modified by using the app-icf MKB option.

See Airplay Concepts > ICF Files for an overview of using ICF files.

.CONFIG.TXT

The files 's3e.config.txt' and 'app.config.txt' describe the legal section names and legal settings for the ICF files. In debug builds, each ICF setting is checked for validity. This helps avoid common problems such as spelling mistakes in ICF files. These files should not be edited.

.DEFINES.TXT

Any files ending in 'defines.txt' are assumed to be text files describing (documenting) application-specific configuration settings (ICF settings). All application-specific ICF settings must be documented in a defines.txt file. You can have as many defines.txt files as you require.

.MKB

Project files for specifying build and configuration options for Airplay applications.

See Airplay Concepts > MKB Files for an overview of using MKB files.

.MKF

Subproject configuration files which can be included by an application's main MKB file.

See Airplay Concepts > MKB Files for an overview of using MKB and MKF files.

.ICF

Application configuration files. These look similar in structure to Windows INI files and are used to specify dynamic configuration options for the Airplay application and the S3E runtime environment.

See Airplay Concepts > ICF Files for an overview of using ICF files.

.S3E

S3E files are platform/loader-independent application binary files which are output at compilation time when building for device (ARM architecture). This file is combined with a platform-specific executable, the Airplay "loader", at the deployment stage to produce a platform-specific version of the application.

S3E.ICF

This is the system-wide configuration file for Airplay System. It uses the ICF format which is similar to Windows INI files. This file should not be edited. Use 'app.icf' for specifying application-specific settings.

See Airplay Concepts > ICF Files for an overview of using ICF files.

.S86

An x86 version of the S3E file that is produced for a device build. This file is created when compiling for x86 and is run using the Windows Simulator.

Airplay Studio File Types

.ANIM

Text file exported from modelling package describing an animation (CIwAnim object).

.DCL

Derbh command-line script describing files to place into a Derbh compressed archive.

See DZip Tool and Compressed Derbh Archives for more information.

.DZ

Derbh compressed archive.

See DZip Tool and Compressed Derbh Archives for more information.

.GEO

Text file exported from art application, describing a mesh (CIwModel object).

.GROUP

Text file created by the user (perhaps using Airplay Studio Director) describing files to place into a resource group, and loaded by the IwResManager runtime module.

.GROUP.BIN

Binary file containing serialised versions of all resources in a group. When the IwResManager resource manager is in BUILD mode, GROUP files (text files) are read and the resource group is constructed. The entire resource group is then serialised to the binary GROUP.BIN file. The existing resources are then freed from memory, and the GROUP.BIN file is read back in.

.GROUP.BIN.TXT

Text file created during the resource group building process written out after the GROUP.BIN file. Gives details on what resources have been created, their size on disk and other useful debugging information.

.GROUP.HST

Hash-String Table, created when building GROUP.BIN files. Contains a list of (string, hash) pairs for all CIwManaged objects in the resource group. The full string names of CIwManaged objects are not contained within the GROUP.BIN file itself, so save space. However, if the HST file exists, it is loaded, and the CIwManaged objects within the resource group are patched with their full string names. This is very useful when debugging.

.GXFONT

Text File listing the description of a font created using the Font Builder.

.ITX

Text file in "Ideaworks Labs TeXt format". Can be read by the CIwTextParserITX singleton.

.MTL

Text file exported from modelling package, or created by hand, describing a series of materials (CIwMaterial objects). Whenever a mesh is exported from the modelling package, a GEO and accompanying MTL are written.

.SKEL

Text file exported from a modelling package, describing an animation skeleton (CIwAnimSkel object).

.SKIN

Text file exported from a modelling package, describing an animation skin (CIwAnimSkin object).

.WORLD

Text File exported from a modelling package, describing the placement of objects (GEO files) within a scene.

.VSH

A file describing a vertex shader to be used with a material.


Airplay SDK: Using Open Source Modules

Airplay SDK > User Guide > Using Open Source Modules >

Using Open Source Modules

Airplay SDK’s excellent support for C/C++ standard libraries means that existing C/C++ codebases are very likely to compile “out of the box” without any changes required (or with only trivial changes). This means you can leverage any useful C/C++ codebases you can get your hands on, including Open Source code.

To make life even easier, Airplay SDK’s code building process includes support for dynamically downloading Open Source code modules hosted by Ideaworks Labs. The first time a particular module is referenced by your makefile, the Open Source code is pulled down from our server, and copied into your Airplay SDK installation. From that point on, the source code is simply compiled as part of your application.

As a specific example, to include libjpeg within your application, simply name the libpjeg module as a dependent project as follows:

    subproject libjpeg

You also need to instruct Airplay’s makefile builder as to where to find the module by adding the module_path option to your mkb file :

    options
{
    module_path="$AIRPLAY_ROOT/modules/third_party"
}

Currently, Ideaworks Labs hosts the following Open Source modules, all of which are compatible with Airplay applications:

  • expat: XML parsing
  • libjpeg: JPEG image encoding
  • libpng: PNG image encoding
  • lua: Lua scripting language
  • ode: Open Dynamics Engine
  • sqlite3: SQL database engine
  • tinyxml: XML parsing
  • zlib: Compression

Ideaworks Labs will continue to add new Open Source modules to this list. Feel free to request support for any Open Source module you think might be useful to yourself and others!


Airplay SDK: Airplay Programmer Tools Reference

Airplay SDK > Airplay Programmer Tools Reference >

Airplay Programmer Tools Reference

This section provides a detailed reference for using the programming-related tools that come with the SDK.

This includes full settings listings for the MKB and ICF file systems that are used to configure Airplay applications and build environments.

For a more thorough introduction to each of the tools and concepts documented here, see Airplay Concepts in the user guide.

  • Airplay System Configuration Utility
  • MKB File Settings
  • ICF File Settings
  • Windows Simulator
  • dzip Tool and Compressed Derbh Archives


Airplay SDK: Airplay System Configuration Utility

Airplay SDK > Airplay Programmer Tools Reference > Airplay System Configuration Utility >

Airplay System Configuration Utility

The Airplay System Configuration Utility is a desktop application for configuring the Airplay SDK. It is used to specify IDE options, compiler options, the current Airplay directory (to allow for multiple versions of the SDK to be installed) and also performs SDK licensing operations.

Launching the Tool

Airplay System Configuration is available by default on the Windows start menu by clicking Start > Programs > Airplay SDK > [version] > Airplay SDK Configuration.

Configuration Utility options

  • Basic Options
  • Advanced Options
  • License Information


Airplay SDK: Configuration Utility Basic Options

Airplay SDK > Airplay Programmer Tools Reference > Airplay System Configuration Utility > Configuration Utility Basic Options >

Configuration Utility Basic Options

The following options are displayed at the top of the Configuration Utility:

  • Airplay System (S3E) Base Directory: Specifies the base directory of the version of the Airplay SDK to use. This option allows for multiple versions of Airplay to be installed on one machine. The drop down list will show all installations found on the machine plus locations can be entered manually. This path is used for running MKB files and for finding all Airplay tools and utilities.
  • Default Build Environment: The build environement/IDE to use when running Airplay MKB files (application projects). This list is populated with all the supported environments found on the local machine. Use Advanced Options > Show experimental build environments to enable support for additional environments which are not yet fully supported in this version of Airplay.
  • RVCT ARM Compiler: Specify the version of the ARM RVCT compiler to use for RVCT builds. If you have a version of RVCT installed, it can be selected from this list.


Airplay SDK: Configuration Utility Advanced Options

Airplay SDK > Airplay Programmer Tools Reference > Airplay System Configuration Utility > Configuration Utility Advanced Options >

Configuration Utility Advanced Options

Click the Advanced Options button to display the following options, all of which are disabled by default:

  • Always show console output from running mkbs: If checked, when launching a project using an MKB file, the output from the build process will be displayed in a console window.
  • Show experimental build environments: If checked, additional options will be added to the list under Default Build Environment. These environments are experimental and as such may not be fully supported or documented within the SDK.
  • Streamline tools for iPhone: If checked, GUI tools such as the Deployment Tool and Director will be streamlined to only display options relevant for iPhone development. The Windows Simulator uses the iPhone skin in this mode: Options such as surface size are fixed match those of the iPhone.


Airplay SDK: Configuration Utility License Information

Airplay SDK > Airplay Programmer Tools Reference > Airplay System Configuration Utility > Configuration Utility License Information >

Configuration Utility License Information

The panel at the bottom of the Configuration Utility displays the license information for the Airplay SDK.

To request a new license, click the Request New License button. A dialogue asking for user information will be presented. Complete the fields as directed in the dialogue and hit OK to submit the information. A confirmation dialogue will display if the license is succesfully retrieved and installed. Please contact Ideaworks Labs for further assistance.


Airplay SDK: MKB File Settings

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings >

MKB File Settings

MKB files are used to configure build settings for Airplay application projects.

The pages below provide detailed listings of the available options and how to use them.

For an introduction to MKB files, see the MKB Files section of Airplay Concepts.

  • Preprocessor Definitions
  • MKB File Syntax Information
  • Build Options
  • Deployment Options
  • Advanced MKB Usage


Airplay SDK: Preprocessor Definitions

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > Preprocessor Definitions >

Preprocessor Definitions

An MKB file can be used to support conditional compilation. Preprocessor statements can be added in an MKB file and will then be set within the application code.

For example, the definition expected by an ifdef directive can be defined in the MKB file; therefore, the ifdef directive is satisfied and the conditional code is included.

Source files depend on preprocessor definitions, and the inclusion of many preprocessor definitions and the values attributed to them depend on the settings included in the MKBs. When changes are made to an MKB, the MKB system will attempt to rebuild the files that depend on the MKB; however, occasionally this is not enough.

Therefore, it is recommended that you perform a complete rebuild after changing an MKB file, so that the changes you have made are observed and the knock-on effects these changes have on your code are incorporated.

Example Define Statement

The following example uses definition statements to decide which files are included in a build.

  • if {{ defined MYFILE_UDP }}
  • {
    • files
    • {
      • UDP.cpp
    • }
  • }
  • elif {{ defined MYFILE_TCPIP }}
  • {
    • files
    • {
      • TCPIP.cpp
    • }
  • }

This piece of code includes the file UDP.cpp if MYFILE_UDP has previously been defined, or TCPIP.cpp if MYFILE_TCPIP has previously been defined.


Airplay SDK: MKB File Syntax Information

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information >

MKB File Syntax Information

This section outlines the syntax of commands used in MKB files. It covers the following subjects:

  • Comments
  • File Format
  • Commands


Airplay SDK: Comments

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Comments >

Comments

Comments in MKB files begin with a # symbol, and continue to the end of the line.


Airplay SDK: File Format

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > File Format >

File Format

Basic file format is a list of statements, mostly in the form of either:

  • COMMAND PARAMETER or
  • COMMAND { SET OF PARAMETERS }

For example:

file foo.cpp files { foo.cpp foo.h bar.cpp bar.h } define XXX=1 defines { XXX=1 YYY=2 }

Unless otherwise specified all files and directories referenced are relative the file in which they occur.

Special characters and keywords can be used in parameters if they are surrounded by quotation marks. Double braces, '{{' or '}}', should not be used except in if/elif/else commands.


Airplay SDK: Commands

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands >

Commands

The following MKB commands are outlined in this section:

  • asset(s)
  • debug_define(s)
  • define(s) / undefine(s)
  • deployment(s)
  • file(s)
  • if / elif / else
  • includepath(s)
  • library(s)
  • librarypath(s)
  • option(s)
  • subproject(s)
  • target

Formatting Legend

The formatting conventions for all command descriptions is contained in the table below.

  • Format
  • Italic
  • Bold
  • Ellipsis (...)
  • Between brackets ([])
  • Meaning
  • Information that the user must supply
  • Elements that the user must type exactly as shown
  • Parameter that can be repeated several times
  • Optional items


Airplay SDK: asset

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > asset >

asset

Specifies data files for deployment

Syntax

asset FILE

or

assets
{ [[CONFIG-NAME]]
[(directory)]
[<include PARENT-CONFIG>]
 FILE1 FILE2 ... }

Examples

  • asset level1.dat
  • assets
  • {
    • level1.dat
    • level2.dat
  • }
  • assets
  • {
    • (.)
    • core.dat
    • ["Base Config"]
    • <include "Default">
    • (level1)
    • level1.dat
    • ship1.dat
    • ["Extended Config"]
    • <include "Base Config">
    • (level2)
    • level2.dat
    • ship2.dat
  • }

Detailed Description

The asset command specifies files for inclusion in deployment packages

Files are listed in a similar manner to the file command; The optional preceding (dir) construct specifies the root-relative directory the files are located in.

Note:

The build system does not check for the presence of these files, if they do not exist this will cause an error only at the time of deployment.

The optional [CONFIG-NAME] construct defines an asset configuration. Subsequent asset files will be included in the configuration. If no [CONFIG-NAME] has been specified, asset files are included in a configuration named "Default". This is the default asset configuration used by any deployment.

'CONFIG-NAME' can be used in an <include CONFIG-NAME> construct in another asset configuration, or as an assets=CONFIG-NAME deployment option an a deployment command. This allows for different deployment configurations to include different assets, see the deployment command for more information.

The optional <include PARENT-CONFIG> includes the contents of asset configuration PARENT-CONFIG in the current configuration. This enables a hierarchy of asset configurations to be established.


Airplay SDK: debug_defines

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > debug_defines >

debug_defines

This command allows you to specify preprocessor symbol(s) to be used in debug builds only.

Syntax

debug_defines SYMBOL...[=VALUE]

or

debug_defines { SYMBOL1...[=VALUE1] SYMBOL2...[=VALUE2] ...}

Example

  • if {{ defined I3D_HOST_PEARL_7650 or defined I3D_HOST_SMARTPHONE
  • or defined I3D_HOST_UIQ_INNOVATOR }}
    • debug_defines I3D_NO_SCREEN_BUTTONS

Detailed Description

The debug_define command defines one or more C/C++ preprocessor symbols for Debug configurations only.

This statement is equivalent to prepending define SYMBOL VALUE to C/C++ source files, with some caveats.

See the documentation for define for more information.

When using MKBs with command-line only builds, debug_defines will be ignored unless the --debug option is specified.


Airplay SDK: define

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > define >

define

This command allows you to define preprocessor symbol(s).

Syntax

define SYMBOL...[=VALUE]

or

define { SYMBOL1...[=VALUE1] SYMBOL2...[=VALUE2] ...}

Example

define MY_MACRO if {{ defined MY_MACRO }} define MY_MACRO_2 undefine MY_MACRO

In this example and MY_MACRO_2 will all be defined in the final project where as MY_MACRO will not.

Detailed Description

The define command defines one or more C/C++ preprocessor symbols for the whole project. The undefine command will undefine a previously defined symbol which mean the symbol will not be defined in the resulting project.

The define statement is equivalent to prepending '#define SYMBOL VALUE' to C/C++ source files, with some caveats. These caveats are:

  • To include double quote marks in the symbol definition, use define SYMBOL='"QuotedString"' (note the extra single quotes). define SYMBOL="QuotedString" is equivalent to define SYMBOL=QuotedString.
  • Backslashes must be escaped. The MKB equivalent the of define SYMBOL "mystring\n" is define SYMBOL='"mystring\n"'. The MKB equivalent of define SYMBOL "c:\\mypath\\file" is define SYMBOL '"c:\\mypath\\file"'


Airplay SDK: deployment

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > deployment >

deployment

Specifies deployment configurations

Syntax

deployments { [DEPLOYMENT-NAME] deployment-platform deployment-option1=value1 deployment-option2=value2 ...}

Examples

  • deployments
  • {
    • ["BREW demo build"]
    • brew
    • uid=0x12345678
    • assets="Base Config"
    • ["Symbian full application"]
    • symbian8
    • caption="My great application"
    • assets="Extended Config"
  • }

Detailed Description

The deployment command specifies one or more deployment configurations. A deployment configuration results in a package of files ready for distribution onto a mobile platform. When required, the deployment configuration information is passed to the Airplay System Deployment Tool which performs the necessary actions to generate the packages. To run the Deployment Tool, use 'RUN' (F5) in Visual Studio whilst the ARM Build Release configuration is selected.

Deployment options allow configuration of the package with options for setting icons, UID numbers, digital signatures, etc.

The [DEPLOYMENT-NAME] construct specifies a name for the deployment configuration. DEPLOYMENT-NAME will appear in the Deployment Tool as a selectable configuration.

deployment-platform must be on the line following [DEPLOYMENT-NAME] and can be one of:

  • linux
  • win32
  • symbian7
  • symbian8
  • symbian9
  • brew
  • winmobile

After deployment-platform, zero or more deployment options may be specified in the form option=value. Each deployment platform has its own set of specific deployment options, however some deployment options are common. See the deployment documentation for more information on deployment platforms and their options.

Common deployment options are:

  • assets: sets the list of asset files to use for this deployment configuration. See the asset command for more information.
  • caption: sets the displayed name for the application in the phone's UI.
  • uid: sets the unique identifier number for the application.

Note: For a description of all the deployment options, see Deployment Options.


Airplay SDK: file

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > file >

file

This command allows you to specify files to include in the project.

Syntax

file file

or

files { file... }

Example

  • files
  • {
    • (myapp/source)
    • ["Source Files", group1]
    • blah.cpp
    • blah_internal.h
    • ["Source Files",group2]
    • myfile.h
    • myfile.cpp
  • }

Detailed Description

The file command supports the following special constructs:

  • (comma separated path list): Where to find subsequent files A list of one or more paths relative to the root directory in which to search for files. If a file is found in more than one directory, an error is generated. Prefix this list with use_first_found to suppress this error, and use the file that is found first by scanning the list of paths from left to right. The list of search paths is state that is maintained at file-scope, so code such as

Detailed Description

The file command supports the following special constructs:

  • (comma separated path list): Where to find subsequent files A list of one or more paths relative to the root directory in which to search for files. If a file is found in more than one directory, an error is generated. Prefix this list with use_first_found to suppress this error, and use the file that is found first by scanning the list of paths from left to right. The list of search paths is state that is maintained at file-scope, so code such as
    • file (my_directory)
    • file blah.txt

    Will search for blah.txt in <rootdir>/my_directory

  • [comma separated name list]: Group hierarchy to store subsequent files under. This is a comma separated list which descends the group hierarchy and ends with the leaf group which contains the files. This is used to create source file groups under Visual Studio. Each mkf file in the project has its own group, which in turn contains the groups listed in file commands. To specify a group name that includes a space, enclose the group name in quotes. The group hierarchy is state that is maintained at file-scope, so code such as:
    • file ["My Group"]
    • file blah.txt

    Will place blah.txt in "My Group"

  • List of one or more files: These files will be included in the project. The file names should not include any path information, the paths in which to find files should be listed using the () construct. Files ending in .c or .cpp will be compiled as C/C++ source. Files ending ".defines.txt" will automatically be scanned for documentation of preprocessor symbols. Other files will be included as text or binary documents and will be otherwise ignored by the build system.
Note: See the file ARM_compiler_notes.txt for more information on using the arm option.


Airplay SDK: if/elif/else

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > if/elif/else >

if/elif/else

This command allows create conditional statements.

Syntax

if {{condition}} statement

[elif {{condition}} statement]...

[else {{condition}} statement]

Example

  • if {{ defined MY_SYMBOL1 }}
    • message "MY_SYMBOL1 defined"
  • elif {{ not defined MY_SYMBOL2 }}
    • message "MY_SYMBOL2 not defined"
  • else
  • {
    • message "hello"
    • message "goodbye"
  • }

Detailed Description

The elif and else clauses are optional, and multiple elif expressions are supported.Any preprocessor symbols defined by define will be replaced with their value in condition. Symbols which have not been defined with a value will assume a value of 0.Expressions such as SYMBOL==1 will evaluate to true if SYMBOL is defined to 1, false if SYMBOL is defined to any other value, and will generate an error if SYMBOL is not defined.

The expression defined SYMBOL can be used in condition. This will evaluate to true when SYMBOL is defined (like the C preprocessor), and false otherwise.


Airplay SDK: includepath

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > includepath >

includepath

This command adds path to the C/C++ preprocessor include path.

Syntax

includepath { path...}

Example

  • includepath module/h
  • includepaths
  • {
    • module/h1
    • module/h2
  • }

Detailed Description

The includepath command adds paths from which your application can include files. One or more paths may be specified in each command. All paths are relative to the file in which they appear.


Airplay SDK: library

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > library >

library

Specify static libraries to be linked into the application.

Syntax

library { library}

or

librarys { library... }

or

library <ROOTDIR,BASENAME>

Example

  • library
  • {
    • MyLibrary.lib
  • }
  • librarys
  • {
    • MyLibrary1.lib
    • MyLibrary2.lib
  • }

Detailed Description

Multiple libraries can be specified using the library command. The linker is supplied the cumulative list of libraries and the list of library search paths specified by the librarypath command.

Libraries can be specified with or without a path. If they are specified withouta path then the library search path with be used by the linker to search the the library at link time.

If the <ROOTDIR,BASENAME> syntax is used then mkb system will automatically link the approprate library based on the current architecture and whether the current build is debug or release. Effectively it specifies one of many different libraries in a single line. The ROOTDIR specified a base directory that must contain and folder called "lib". Within the lib folder much exist both "arm" and "x86" folders and within those folders live the debug and release version of the libraries. The BASENAME is then used to contruct the full name of the library according the current compiler being using. The example below shows how the actual filename for a library is contructed from the ROOTDIR and BASENAME pair.

Example tree in filesystem:

ROOTDIR/
`-- lib
    |-- arm
    |   |-- BASENAME.a
    |   |-- BASENAME_d.a
    |   |-- libBASENAME.a
    |   |-- libBASENAME_d.a
    |   |-- v5
    |   |   |-- BASENAME.a
    |   |   `-- libBASENAME.a
    |   `-- v6
    |       |-- BASENAME.a
    |       `-- vfp
    |           `-- BASENAME.a
    `-- x86
        |-- BASENAME.lib
        |-- BASENAME_d.lib
        `-- linux
            |-- libBASENAME.a
            `-- libBASENAME_d.a


Airplay SDK: librarypath

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > librarypath >

librarypath

Add paths to the linker's library search path.

Syntax

librarypath { path...}

Example

  • librarypath
  • {
    • module\lib
  • }
  • librarypaths
  • {
    • module\lib1
    • module\lib2
  • }

Detailed Description

The librarypath command adds paths to the linker's library search path. One or more paths may be specified in each command. All paths are relative to the file in which they are specified.


Airplay SDK: option

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > option >

option

Sets one or more options.

Syntax

option build-option

or

option build-option= value

or

options build-option { build-option1 build-option2=value ... }

Example

  • option arm-cpu=5
  • options
  • {
    • optimise-size
    • s3e-data-dir=data
  • }

Detailed Description

This command sets one or more build options. This is equivalent to setting the option on the command line.

For a list of build options, see the section Build Options.


Airplay SDK: subproject

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > subproject >

subproject

This command allows you to specify any projects this project is dependent upon.

Syntax

subproject project[.mkf]subprojects{ project1[.mkf] project2[.mkf] ... }

Example

  • subprojects
  • {
    • subproj1
    • subdir/subproj2
  • }

Detailed Description

This command allows the inclusion of other mkf files in the current project. project is the name of a subproject, or a relative path to a subproject. There is no need to specify the .mkf extension.

The build system searches for project in the following paths:

  • The S3E "modules" directory, (<S3E_DIR>/modules/project.mkf) and (<S3E_DIR>/modules/project/project.mkf). This enables the build system to find system modules that are provided with the S3E installation
  • The S3E parent directory, (<S3E_DIR>/../project.mkf) and (<S3E_DIR> /../project/project.mkf).
  • The root directory (<rootdir>/project.mkf) and (<rootdir>/project/project.mkf)
  • The parent of the root directory, (<rootdir>/../project.mkf) and (<rootdir>/../project/project.mkf)

The subproject is parsed in place of the 'subproject' command, therefore the user must be aware that the placement of the 'subproject' command can be important, especially when setting and testing preprocessor symbols is involved.

Note: When including a subproject, the directory that was found containing project/project.mkf or project.mkf will become the new root directory. Thus it is recommended that all .mkf files assume that the root directory is the parent of the directory containing the mkf.


Airplay SDK: target

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > MKB File Syntax Information > Commands > target >

target

Specifies the name of the project.

Syntax

target targetname

Example

  • target myname

Detailed Description

The 'target' command changes the name generated project as well as the default name of the executable. By default the target name is the same as that of the top-level MKB. This option should rarely be needed.


Airplay SDK: Build Options

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > Build Options >

Build Options

Build options are specified as either on/off flags - by their presence/absence in the MKB - or as option=value lines depending on their type. Build options control the way in which the application is built.

Contents

  • Adding Build Options to Your MKB
  • General options
  • S3E environment options
  • Compiler/Linker options

Adding Build Options to Your MKB

Build options must be wrapped in an options section in your MKB file.

The following is an example of an options section:

  • options
  • {
  • s3e-data-dir="datadir"
  • app-icf="icfs/app.icf"
  • verbose=1
  • }

The following tables detail the available options. Options ending with an = symbol require a value to be set while those without are flags that can either be on or off. Options ending += use lists which can be added to by specifying more values. Options may have a default value specified with option=default in the table. A value in the "Format" column indicates the value for that option must be given in a specific format. Otherwise, it will be read as a string and interpreted as described in the description for that specific option. Options of format 'file' can be given as either full file paths or paths relative to the mkb root directory.

General options

Option | Format | Description
quick |  | Assume all external projects are already built
non-interactive,n |  | This option allows you to disable any prompt for input after a failure. This only has an effect under Windows.
internal |  | Process is being run from anther MKB process.
verbose,v=0 | int | Sets the verbosity level.
brief,b,q,quiet |  | This option allows you to reduces printing of status messages. It suppresses all output, except error messages.
x86 | bool | Only build X86 binaries. This Builds a Visual Studio project that contains only x86 configurations. The resulting project name will be postfixed with '_x86'.
arm | bool | Only build ARM binaries.
no-asm |  | Don't output assembler for ARM builds.
arm-debugger= |  | One of 'rtsm' or 'qemu'. Selects the ARM emulator and debugger to use; either ARM's Realtime System Model (RTSM) and Maxview debugger, or QEMU based emulation with GDB-based Insight debugger
deploy= |  | Deploy the target for the specified OS (invokes s3e_deploy).
deployargs,deploy-args+= |  | Extra arguments to pass to s3e_deploy
execute |  | Sets the project to run when it has been built.
executeargs+= |  | This option allows you to supply a set of Arguments on the command line when executing the application.
offline |  | Enable offline mode in which no network operations will be attempted.
no-ide |  | Stops the automatic launch of the IDE after generating build file. This option only works on IDE build environment such as VC6, VC7 and VC8.
debug | bool | Build debug build (release is default). Builds debug build when building on Linux. Has no effect for MKBs that output Visual Studio projects.
deploy-only |  | This option stops the running of emitters. It only creates deploy_config.py.
release | bool | Builds release build only when building on Linux. Has no effect for MKBs that output Visual Studio projects.
nologo |  | Suppresses the start-up banner. This option only has effect if it is specified from the command line.
msvc-project |  | Make process fail if it writes a dsp or vcp file. It causes an error to be generated if project files have been written. It should only be used when running this script from inside MSVC.
no-make |  | Don't automatically build targets. Does not effect IDE builds such as VC6, VC7 and VC8. This only has effect when building on Linux. Building under Linux uses an intermediate Scons makefile; This option prevents the execution of the Scons makefile.
preinclude+= | file | This option allows you to specify a file that is pre-included in all compilation phases. This option can be specified more than once, and files are included in the order in which they are specified.
clean |  | Clean (delete) the build tree, and everything in it.
rebuild |  | Rebuild everything, including any object files and the generated makefile.
no-modules |  | Prevents the subproject command from searching <S3E Install Dir>/modules for MKF files. Do not take modules from <S3E Install Dir>/modules when using the subproject command.
output-name= |  | Sets the name of the resulting executable, optionally with a full path. This does not affect the name of the project. If this is not set to an absolute path it is interpreted as a path relative to <mkb directory>/<build directory>/<object files>.
output-name-debug= |  | Same as output-name but only effects the debug output.
default-buildenv= |  | Sets the default build environment.
buildenv= |  | Sets the project build environment. This overrides the default buildenv. If the buildtype command specifies an IDE, this option will be overridden. It must be one of 'VC6' 'VC7' 'VC71' 'VC8' 'SCONS'. This option is automatically added to the command line by s3eConfig.exe.
builddir,use-subdir= |  | Uses the specified subdirectory for all project files, intermediate files, etc.
list-targets |  | Generate a .targets file list all the targets of the MKB
make |  | Builds Visual Studio projects without using the IDE. This will use Visual Studio command-line options to compile and link all the project configurations.
module_path+= |  | Path (separated by semi-colons) to use when searching for subprojects (modules). The default is S3E_DIR/modules.
module_path_append+= |  | Path (separated by semi-colons) to use when searching for subprojects (modules). The default is S3E_DIR/modules.
dist,archive |  | Generates a source archive of all files used to build a project.
dist-format= | str | Specify the format of the archive to create. Valid values: 'zip', 'tar', 'exe', 'apk'.
dist-dir= | str | Specify a subfolder in to use within the generated archive package rather than the archive root.
line-width=80 | int | Formats output of the MKB process to a certain line width.
incredibuild |  | Use Incredibuild (if installed) when running commandline win32 builds
no-vc6 |  | Signal that the current project is not compatible with VC6.
extension= |  | Run an extension script after parsing has completed
shared-arm-lib |  | Build a library target with the RVCT and GCC library targets shared

S3E environment options

Option | Format | Description
s3e-data-dir= | file | Sets the S3E data dir used by the emulator/simulator.
s3e-force-arch |  | Forces the architecture in the s3e file to be this, ignoring the cpu/compiler settings. Can be set to one of 4T, 4, 5T, 5TE, 5TEJ, 6, 6K, 6T2,6Z. This enables an image that has been built with a higher-level CPU setting to be loaded by a loader that supports only a lower-level CPU. This is useful if the higher-level CPU code can be dynamically switched according to the host CPU.
app-icf= | file | Specifies the application's .icf (Configuration file). This defaults to <s3e-data-dir>/app.icf. This option can accept a comma-separated value for multiple ICFs.
s3e-dir= |  | S3E folder for the build. Used internally, do not set.

Compiler/Linker options

Option | Format | Description
compiler= |  | Sets the compiler for native builds. Current valid values are: 'rvct', 'gcc'.
arm-cpu= |  | Sets the ARM processor build is created for. This should be one of 4T, 4, 5T, 5TE, 5TEJ, 6, 6K, 6T2,6Z, or the name of an ARM CPU (run armcc --cpu list for the full supported list). The default is 4T. Consult the ARM documentation for information on differences between CPU architectures. Building for a later-revision architecture or CPU will increase performance but may prevent the application from running on devices with earlier revisions. S3E checks the architecture an application is built for and will produce errors if the device does not support it.
arm-fpu= |  | Valid options are 0, 1, vfp, vfpv2, vfpv3. Options 1, vfp and vfpv2 have the same effect of enabling the use of VFP (Vector Floating Point) v2 floating-point instructions which will improve the performance of floating point code. Option 0 (the default) disables the use of VFP instructions. Enabling VFP instructions should only be used if the application is going to run on devices that have VFP units (e.g. the iPhone, or most Symbian 9 devices). Setting arm-fpu=vfpv3 (use of VFP v3 instructions) provides additional peformance gains but can only run on ARM Cortex - based CPUs and above. Note that airplay applications always build with software (softvfp) floating point linkage for maxmimum compatibility between object files.
external-compiler |  | Use the external system compiler rather than any bundled compiler (this current only applies to RVCT).
rvct-version= |  | Sets the version of RVCT to use. Valid values are '3.0', '3.1', '4.0' and 'custom'. If this is set to 3.0, 3.1 or 4.0, then the environment variables RVCT30BIN, RVCT31BIN or RVCT40BIN respectively will be used to locate RVCT. If this is set to 'custom' then RVCT will be located by the text file located in <Airplay SDK>/s3e/bin/rvct_location.txt. 'custom' is intended for use by the Airplay configuration tool only.
optimise-size |  | Optimises the ARM build of the application for size (ARM compiler option -Ospace).
optimise-speed |  | Optimises the ARM build of the application for speed (ARM compiler option -Otime).
compile-thumb |  | Compiles the ARM build of the application into thumb code; On average it will consume 75% of the space whilst running 25% slower. The default is to compile for ARM code.
enable-exceptions |  | Enables exception handling in the ARM build of the application (ARM compiler option -exceptions).
strict | bool | Turns all makefile_builder and compiler warnings into errors.
strict-compile |  | Turns all compiler warnings into errors.
strict-mkb |  | Turns all makefile_builder warnings into errors.
warn-level=2 | int | Warning level 0, 1 or 2. 0=disable warnings, 2=all warnings
enable-stdinc |  | Enable compilers standard include paths which are disabled by default.
warn-level=2 | int | Warning level 0, 1 or 2. 0=disable warnings, 2=all warnings
distcc |  | Use distcc, if possible.
no-distcc |  | Don't use distcc to distribute the build.
ccache=1 | bool | Enable/Disable use of ccache when compiling
compile-debug-as-release | bool | Uses the release compiler settings even when building debug builds.
iphone |  | enables iPhone builds of s3e


Airplay SDK: Deployment Options

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > Deployment Options >

Deployment Options

Deployment options are specified by option=value lines in a deployment command. Deployment options control the packaging of files for running on mobile devices. Some deployment options apply to more than one deployment platform, some are platform-specific.

Contents

  • Adding Deployment Options to Your MKB
  • Available Platform Types
  • Deployment Options by Platform
    • Generic Options
    • iPhone specific options
    • BREW specific options
    • N-Gage specific options
    • Symbian specific options
    • UIQ3 specific options
    • Windows Mobile specific options
    • Windows (x86) specific options

Adding Deployment Options to Your MKB

Deployment options must be wrapped in a deployments section in your MKB file. The deployments section supports the creation of multiple deployment configurations. The ability to create an individual configuration means instead of having to reenter deployment settings each time you wish to execute a very specific deployment type, you create an individual configuration within your deployments section that holds and stores all the required deployment specifics. Therefore, each time you deploy, all you have to do is supply the configuration name.

The following is an example of a deployment section:

  • deployments
  • {
    • name='s3eBasic'
    • ["Test Config"]
      • symbian9
      • target-folder='Symbian9'
      • uid='0xA0002A92'
  • }

As illustrated in the code section above, square brackets must enclose the configuration name, which in this case is "TestConfig". The settings that come after that configuration name are specific to that configuration. The end of that configuration is either indicated by the closing bracket of the deployments section or the beginning of a new configuration.

The specification of platform type must occur directly after the configuration name. It is possible to include multiple platform types in any configuration. If multiple platform types are specified, they must be placed in a comma separated list enclosed in a set of quotation marks, for example:

  • ["TestConfig"]
    • "symbian9, symbian8, winmobile"

Available Platform Types

Option | Description
iphone | Builds an application for the iPhone platform.
brew | Builds an application for the BREW platform.
winmobile | Builds an application for the Windows Mobile platform.
ngi / ngi2 | Builds an application for the N-Gage platform.
symbian9 | Builds an application for the Symbian 9 s60 platform.
uiq3 | Builds an application for the Symbian 9 UIQ3 platform.
symbian8 | Builds an application for the Symbian 8 platform.
symbian7 | Builds an application for the Symbian 7 platform.
win32 | Builds an application to run in the Windows Simulator.
linux | Builds an application for the Linux platform.

Deployment Options by Platform

The following tables outline the general and platform-specific deployment options.

All options require a value to be given using the format option=value. Options may have a default value (specified with option=default in the table). A value in the "Format" column indicates the value for that option must be given in a specific format. Otherwise, it will be read as a string and interpreted as described in the description for that specific option. Options of format 'file' can be given as either full file paths or paths relative to the mkb root directory.

Generic Options

Option | Format | Description
assets |  | Specifies which asset set to used (defaults to "Default"). "Default" is the default set under which asset files are placed. To create other asset configurations, use the asset build system command.
name |  | Sets the name of the deployment (i.e. the folder name and executable name). The default is to use the MKB target.
arch |  | Restrict deployment to only one architecture. The default behaviour is to create deployments for both x86 and ARM. The architecture must be set to either 'x86' or 'arm'.
uid | int | Specify the 32-bit Unique Identifier (UID) for the application. This option is for BREW and all Symbian platforms only. To ship products on these platforms, a UID must be obtained from the OS provider.
caption |  | Sets the displayed name of the application in the device's menu system.
long-caption |  | Sets the longer version of the displayed application name. Used when Symbian displays the application's icon in list view.
embed-icf | bool | Specifies whether the ICF files (app.icf, s3e.icf, etc) should be embedded into the executable (.s3e) file. The default is to embed the configuration files for release builds only. If embed-icf is set to 1, configuration files are embedded for both debug and release builds. If embed-icf is set to 0, configuration files are not embedded in either debug or release builds. Embedding .icf files increases the application's security at the expense of reducing the ability to make quick changes to the .icf files.
pub-sign-key | file | Specifies that the loader should be locked to the s3e file, via the specified public key. priv-sign-key must also be specified. This sets a public key (OpenSSL 1024-bit public RSA key) to embed in the loader that will verify a signature embedded in the .s3e file. This locks the .s3e file to the loader, as the loader will not load a .s3e file with a signature that it cannot verify. If this option is specified, priv-sign-key must also be specified. These options will force the embedding of .icf files into the .s3e file (equivalent to embed-icf=1). If pub-sign-key and priv-sign-key are not specified, the default is to automatically generate a random key-pair and lock the release build using this key-pair.
priv-sign-key | file | Specifies the private part of the key specified by pub-sign-key. pub-sign-key must also be specified. This can be the same as the key specified by pub-sign-key if the key is a public/private key-pair. This private key is used to generate a signature that is embedded in the .s3e file, and used to lock the loader to the .s3e file. The default is to automatically generate a private key for release builds only.
app-icf |  | Specifies an alternative application-specific configuration file (e.g. app.icf) to use for this deployment. The default is to use the file specified in the app-icf build option. If this is not set, the default is app.icf contained in the directory pointed to by the s3e-data-dir build option.
provider |  | Sets the provider/author/owner name (e.g. for BREW .inf).
manufacturer |  | Sets the manufacturer name (e.g. for BREW .inf). Defaults to provider.
copyright |  | Sets the copyright string to be used during deployment (defaults to "(C) <provider>").
auto-derbh | bool | Automatically create a derbh archive of all assets.
target-folder |  | Sets the output folder for the deployment. By default this is set to the name of the deployment.
version |  | Sets the version number (format major.minor.revision).
version-major | int | Sets the major version number.
version-minor | int | Sets the minor version number.
version-revision | int | Sets the revision version number.
version-string |  | Set the version string for platforms where 'version' can be any valid string. Defaults to the stringified version number.
networking | bool | Enable networking capabilities on platforms that support capabilities. Default is 1 (enabled).
s3e-compression |  | One of 'lzma', 'gzip' or 'none'. Specifies compression type of s3e file.

iPhone specific options

Option | Format | Description
iphone-splash | file | Sets the iPhone splash screen image (320x480 24-bit png).
iphone-icon | file | Sets the icon for the app deployed on iPhone (57x57 24-bit png).
iphone-appid |  | Sets the app ID (CFBundleIdentifier) in the Info.plist explicitly (defaults to com.<provider>.<gamename>).
iphone-region |  | Sets the CFBundleDevelopmentRegion field of the Info.plist (defaults to English).
iphone-signing-identity |  | Sets the identity to use when signing iPhone applications.
iphone-signing-host |  | Sets the hostname (with optional port number) of the Mac on which the signing server is running.
iphone-sign-for-distribution | bool | Tells the signing server to use an entitlements file suitable for AppStore distribution.
iphone-provisioning-profile | file | Sets the provisioning profile to use when signing iphone applications.
itunes-artwork | file | Sets the iTunes icon for the deployed app (512x512 24-bit png).
iphone-prerendered-icon | bool | Declare that the iPhone icon is pre-rendered and should not have the "shine" effect added on device.
iphone-info-plist | file | Sets an external Info.plist file to use. This makes most other iphone deployment options invalid.

BREW specific options

Option | Format | Description
brew-mif | file | Specifies a BREW .mif file to use. BREW .mif files contain application metadata including icon bitmaps, application name and type, and licensing information. Airplay System does not provide utilities to automatically create .mif files, .mif files must be created by using the BREW Mif Editor available in the BREW SDK Tools, available from Qualcomm. This option will override any mif-related settings specified by the other brew-* deployment options.
brew-uid | int | Sets the BREW CLSUID (overrides 'uid' setting when deploying to BREW). Ignored if brew-mif is set.
brew-compress-loader=1 | bool | Enables LZMA compression on the BREW loader. ARM builds only.
brew-icon-small | file | Specify the small icon file for the BREW MIF. Ignored if brew-mif is set.
brew-icon-medium | file | Specify the medium icon file for the BREW MIF. Ignored if brew-mif is set.
brew-icon-large | file | Specify the large icon file for the BREW MIF. Ignored if brew-mif is set.
brew-priviledges |  | A comma-separated list of BREW priviledges for using the MIF file. Ignored if brew-mif is set.
brew-depends |  | A comma-separated list of hexadecimal BREW class dependencies. Ignored if brew-mif is set.
brew-encoding |  | String encoding (one of "sjis", "utf16", "utf8") to use when writing to the MIF file. Ignored if brew-mif is set.

N-Gage specific options

Option | Format | Description
ngi-uid |  | Sets the N-Gage UID (overrides 'uid' setting when deploying to N-Gage).
ngi-gcce-loader | bool | Deploy the N-Gage loader that was built with GCCE (use this if you don't have RVCT2.2 installed on your system)
ngi-gameinfo | file | Sets the gameinfo xml file for N-Gage deployment.
ngi-metadata | file | Sets the metadata xml file for N-Gage deployment.
ngi-achievements | file | Sets the achievements xml file for N-Gage deployment.
ngi-game-extras | bool | Sets whether the game should be built as a game extra upgrade. False by default.
ngi-install-sisx-only | bool | Sets that only the .sis file, not.n-gage, should be deployed. Use for updating existing installations only.
ngi-no-assets | bool | Sets the N-Gage deployment not to deploy game assets.
ngi-icon1 | file | Sets the 1st small icon for identifying the application in the N-Gage Play App (56x56 24-bit png).
ngi-icon2 | file | Sets the 2nd small icon for identifying the application in the N-Gage Play App (56x56 24-bit png).
ngi-icon3 | file | Sets the main icon for launching the application in the N-Gage Play App (212x56 24-bit png).
ngi-icon4 | file | Sets the large icon for use in notifications (installation, errors, etc.) in the N-Gage Play App (240x56 24-bit png).
ngi-arena-config | file | Sets the arena configuration file (e.g., config.xml) for N-Gage deployment.
ngi-arena-rsc | file | Sets the compiled arena game resource file (e.g. game.rsc) for N-Gage deployment. Incompatible with ngi-arena-rss.
ngi-arena-rss | file | Sets the arena game resource settings file (e.g. game.rss) for N-Gage deployment. Incompatible with ngi-arena-rsc. This will be compiled into game.rsc.
ngi-arena-locales |  | Localises N-Gage Arena resources by deploying a resource file for each language. Provided as a string of Symbian language identifiers.
ngi-splashscreen-land | file | Sets an alternative file to use for "n-gage" splash screen when starting in landscape.
ngi-splashscreen-port | file | Sets an alternative file to use for "n-gage" splash screen when starting in portrait.
ngi-filemanager-dll | file | Sets a game-specific filemanager dll to use (from your game's GSDP).
ngi-filemanager-lib | file | Sets a game-specific filemanager lib to link in (from your game's GSDP).
ngi-splash-producer |  | Sets optional localised producer splashscreen (e.g. copyrights). This will include any files found of the format <value>_<language>_<orientation>.jpg. Orientations: "port", "land". Languages: "en", "fr", "de", "es", "ti", "zn_cn", "zn_tw" - defaults to English. e.g. if the value is "splash/nokia" it will search for "splash/nokia_en_port.jpg" etc.
ngi-cert | file | Sets a certificate that is used to digitally sign the application and metadata sis files.
ngi-key | file | Sets a key that is used to digitally sign the application and metadata sis files.

Symbian specific options

Option | Format | Description
symbian7-uid | int | Sets the Symbian 7 UID (overrides 'uid' setting when deploying to symbian7).
symbian8-uid | int | Sets the Symbian 8 UID (overrides 'uid' setting when deploying to symbian8).
symbian9-uid | int | Sets the Symbian 9 UID (overrides 'uid' setting when deploying to symbian9).
symbian-icon1 | file | Sets the 44x44x24 bitmap icon to use. This file path should be an MKB-relative path to a 44x44x24bpp bitmap file (.bmp). This will be used as the application's larger icon in the Symbian UI. When specifying this, symbian-icon1-mask, symbian-icon2, symbian-icon2-mask should also be specified.
symbian-icon1-mask | file | Sets the 44x44x24 bitmap that acts as a mask for the bitmap specified for Icon 1 (symbian-icon1). This file path should be an MKB-relative path to a 44x44x24bpp bitmap file. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
symbian-icon1-mask-black | file | Sets the 44x44x24 bitmap that acts as a mask for the bitmap specified for Icon 1 (symbian-icon1). Symbian 7/8 only. This file path should be an MKB-relative path to a 44x44x24bpp bitmap file. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
symbian-icon1-format |  | Sets the colour format to which symbian-icon1 will be converted (eg '/c24,8'). Symbian 9/UIQ only. This is of the format /C,M where C is one of 1, 2, 4, 8, c4, c8, c12, c16, c24, c32 and M is 1 or 8. C specifies the stored icon colour format (1-8 for palettised 1-8 bit, c4-c32 for non-palettised 4-32bit). M specifies mask colour depth, 1 for 1-bit mask, 8 for 8 bit mask (which enables partial icon transparency). The default is /c24, 8.
symbian-icon2 | file | Sets the application's smaller, 42x29x24 bitmap icon. This file path should be an MKB-relative path to a 44x29x24bpp bitmap file (.bmp).
symbian-icon2-mask | file | Sets the 44x29x24 bitmap that acts as a mask for the bitmap specified for Icon 2 (symbian-icon2). This file path should be an MKB-relative path to a 44x29x24bpp bitmap file. This acts as a mask for the bitmap specified by symbian-icon2. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
symbian-icon2-mask-black | file | Sets the 44x44x24 bitmap that acts as a mask for the bitmap specified for Icon 1 (symbian-icon1). Symbian 7/8 only. This file path should be an MKB-relative path to a 44x29x24bpp bitmap file. This acts as a mask for the bitmap specified by symbian-icon2. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
symbian-icon2-format |  | Sets the colour format to which symbian-icon2 will be converted. Symbian 9/UIQ only. This is of the format /C,M where C is one of 1, 2, 4, 8, c4, c8, c12, c16, c24, c32 and M is 1 or 8. C specifies the stored icon colour format (1-8 for palettised 1-8 bit, c4-c32 for non-palettised 4-32bit). M specifies mask colour depth, 1 for 1-bit mask, 8 for 8 bit mask (which enables partial icon transparency). The default is /c24, 8.
symbian-icon-svg | file | Sets the .svg icon to use for deployment to Symbian 9 only. This file path should be an MKB-relative path to a .svg icon to use for UI display. This can be used instead of symbian-icon1, symbian-icon1-mask, etc.
symbian-cert | file | Sets a certificate that is used to digitally sign the application sis file.
symbian-key | file | Sets a key that is used to digitally sign the application sis file.
symbian-keypwd |  | Sets the password for the key that is used to digitally sign the application sis file.
symbian-platsecflags |  | Sets the Platsec permission flags to sign sis files with, separate with +.
symbian-disable-ecompxl |  | Disables the use of executable (.app file) compression in Symbian 8 and Symbian 7 only. Default is 0 (compression enabled).
pkguid-as-uid | bool | This option allows you to specify that the sis package UID for Symbian/UIQ deployment is the same as the application's UID. Disabled by default.
symbian-run-on-install |  | This option enable the application to starts immediately after being installed on a phone. Default is 0.
symbian-sensorssupport | bool | Include support for the acceleromter.
symbian-locationsupport | bool | Include support for the device's location module. e.g. GPS.

UIQ3 specific options

Option | Format | Description
uiq3-uid |  | Sets the UIQ3 UID (overrides 'uid' setting when deploying to UIQ3).
uiq3-icon1 | file | Sets the 18x18x24 bitmap icon to use. This file path should be an MKB-relative path to a 18x18x24bpp bitmap file (.bmp).
uiq3-icon1-mask | file | Sets the 18x18x24 bitmap that acts as a mask for the bitmap specified for Icon 1 (uiq3-icon1). This file path should be an MKB-relative path to a 18x18x24bpp bitmap file. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
uiq3-icon1-format |  | Sets the colour format to which uiq3-icon1 will be converted (eg '/c24,8'). This is of the format /C,M where C is one of 1, 2, 4, 8, c4, c8, c12, c16, c24, c32 and M is 1 or 8. C specifies the stored icon colour format (1-8 for palettised 1-8 bit, c4-c32 for non-palettised 4-32bit). M specifies mask colour depth, 1 for 1-bit mask, 8 for 8 bit mask (which enables partial icon transparency). The default is /c24, 8.
uiq3-icon2 | file | Sets the 40x40x24 bitmap icon to use. This file path should be an MKB-relative path to a 40x40x24bpp bitmap file (.bmp).
uiq3-icon2-mask | file | Sets the 40x40x24 bitmap that acts as a mask for the bitmap specified for Icon 2 (uiq3-icon2). This file path should be an MKB-relative path to a 40x40x24bpp bitmap file. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
uiq3-icon2-format |  | Sets the colour format to which uiq3-icon2 will be converted (eg '/c24,8'). This is of the format /C,M where C is one of 1, 2, 4, 8, c4, c8, c12, c16, c24, c32 and M is 1 or 8. C specifies the stored icon colour format (1-8 for palettised 1-8 bit, c4-c32 for non-palettised 4-32bit). M specifies mask colour depth, 1 for 1-bit mask, 8 for 8 bit mask (which enables partial icon transparency). The default is /c24, 8.
uiq3-icon3 | file | Sets the 64x64x24 bitmap icon to use. This file path should be an MKB-relative path to a 64x64x24bpp bitmap file (.bmp).
uiq3-icon3-mask | file | Sets the 64x64x24 bitmap that acts as a mask for the bitmap specified for Icon 2 (uiq3-icon3). This file path should be an MKB-relative path to a 64x64x24bpp bitmap file. Black pixels will cause the corresponding icon pixel to be displayed. White pixels will cause the icon pixel to be transparent.
uiq3-icon3-format |  | Sets the colour format to which uiq3-icon3 will be converted (eg '/c24,8'). This is of the format /C,M where C is one of 1, 2, 4, 8, c4, c8, c12, c16, c24, c32 and M is 1 or 8. C specifies the stored icon colour format (1-8 for palettised 1-8 bit, c4-c32 for non-palettised 4-32bit). M specifies mask colour depth, 1 for 1-bit mask, 8 for 8 bit mask (which enables partial icon transparency). The default is /c24, 8.

Windows Mobile specific options

Option | Format | Description
winmobile-icon16 | file | Sets 16x16 (256 colours) icon for Windows Mobile deployment. This file path should be an MKB-relative path to a 16x16 256 colour bitmap file. This will be used as the smallest version of the application's icon.
winmobile-icon32 | file | Sets 32x32 (256 colours) icon for Windows Mobile deployment. This file path should be an MKB-relative path to a 32x32 256 colour bitmap file. This will be used as the medium-size version of the application's icon.
winmobile-icon48 | file | Sets 48x48 (256 colours) icon for Windows Mobile deployment. This file path should be an MKB-relative path to a 48x48 256 colour bitmap file. This will be used as the large-size version of the application's icon.
winmobile-icon64 | file | Sets 64x64 (256 colours) icon for Windows Mobile deployment. This file path should be an MKB-relative path to a 64x64 256 colour bitmap file. This will be used as the extra-large-size version of the application's icon.
winmobile-start-menu-folder |  | Sets where the application should appear under the start menu when installed from CAB.
winmobile-install-folder |  | Sets an optional subfolder in which to install the game. (e.g. Program Files/<FOLDER>/Game)
winmobile-setup-dll | file | Sets an optional DLL to run on install/uninstall.
winmobile-trace-file |  | Sets the position to output the trace file to. This must be a full path.
winmobile-ampd-part-number |  | Sets the part number for ampd DRM build.
winmobile-nouninstall | bool | Application will not appear in Remove Programs.
winmobile-cab-compress | bool | Output CAB file will use compression. Only supported by Windows Mobil 6 or newer - CAB will fail to install on Windows Mobile 5.

Windows (x86) specific options

Option | Format | Description
win-icon | file | Sets the icon for the Windows application. This file should be a 32x32 (256 colours) bitmap file.
win32-pref-windowposx |  | Sets the starting X screen position of the window for the deployed app.
win32-pref-windowposy |  | Sets the starting Y screen position of the window for the deployed app.
win32-pref-windowtitle |  | Sets the window title for the deployed app.


Airplay SDK: Advanced MKB Usage

Airplay SDK > Airplay Programmer Tools Reference > MKB File Settings > Advanced MKB Usage >

Advanced MKB Usage

A project's settings can be defined as a whole via the command line. This becomes of great advantage when you plan on creating more than one build type from the same application.

In this case it is a good idea to put the main settings, which are unlikely to change from build to build, in an MKB file. This MKB file can then be run from the command line and any other build-specific settings, which are not included within the MKB file, can be supplied at this point.

To run an MKB from the command line, open a command prompt in the directory of the MKB file and enter:

  • <name>.mkb [options]

Where [options] are one or more build options. Running <name>.mkb --help will provide the list of possible options. For further information on build options, see Build Options.

Custom Preprocessor Definitions

You can add custom definitions to a project using an MKB file. To do this simply add the custom definitions within a defines block as shown below. These do not need to be documented.

  • defines
  • {
  • CUSTOM_DEFINE_ONE
  • ANOTHER_CUSTOM_DEFINE
  • etc.
  • }


Airplay SDK: ICF File Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings >

ICF File Settings

This section describes how to use ICF configuration files. A full description of how to use ICF files along with how to create custom settings can be found in the ICF Files section of Airplay Concepts.

Each list of ICF settings, as described in the relevant ICF Settings subsection below, is preceded by a string contained within a set of square brackets, "[", "]"; for example, '[S3E]'. Should you use any of the settings contained within a listing, you must place the relevant string at the head of these settings, as illustrated below:

  • [S3E]
  • MemSize=3800000
  • MemSizeDebug=5200000

A significant amount of ICF settings are concerned with the activation of Trace (logging) channels and Assert messages within your project. These can be a helpful way of debugging, especially on device.

Settings by Module

  • S3E ICF Settings
  • Derbh ICF Settings
  • IwUtil ICF Settings
  • IwGeom ICF Settings
  • IwGx ICF Settings
  • IwResmanager ICF Settings
  • IwGraphics ICF Settings
  • IwAnim ICF Settings
  • IwGxFont ICF Settings
  • IwHTTP ICF Settings

Note:

For more information on using tracing and assertions, see the Debugging section of Airplay Concepts.


Airplay SDK: S3E ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > S3E ICF Settings >

S3E ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • S3E (all platforms)
  • S3E (iPhone)
  • S3E (Android)
  • S3E (NGI)
  • S3E (Symbian)
  • S3E (Windows Mobile)
  • S3E (Windows x86)
  • S3E trace channels
  • S3E assertion channels
  • GX config values
  • EGL config values

S3E (all platforms)

[S3E]

Setting | Allowed Values | Description
app_version | <Integer> | The application version, normally set from the deployment settings.
app_caption | <String> | User friendly name for the application, normally set from the deployment 'caption' setting.
MemSize | <Integer> | Size of main application heap (heap 0) in bytes. Default is 3Mb (3145728 bytes). Equivalent to MemSize0.
MemNoMsgOnFail | <0 or 1> | If 1, suppress assertions for memory allocation failures.
MemSize0 | <Integer> | Size of main application heap (heap 0) in bytes. Default is 3Mb (3145728 bytes). Equivalent to MemSize.
MemSize1 | <Integer> | Size of heap 1 in bytes. Default is 0 (heap not created).
MemSize2 | <Integer> | Size of heap 2 in bytes. Default is 0 (heap not created).
MemSize3 | <Integer> | Size of heap 3 in bytes. Default is 0 (heap not created).
MemSize4 | <Integer> | Size of heap 4 in bytes. Default is 0 (heap not created).
MemSize5 | <Integer> | Size of heap 5 in bytes. Default is 0 (heap not created).
MemSize6 | <Integer> | Size of heap 6 in bytes. Default is 0 (heap not created).
MemSize7 | <Integer> | Size of heap 7 in bytes. Default is 0 (heap not created).
MemSize8 | <Integer> | Size of heap 8 in bytes. Default is 0 (heap not created).
MemSize9 | <Integer> | Size of heap 9 in bytes. Default is 0 (heap not created).
MemFlags0 | <String> | Flags for heap 0. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags1 | <String> | Flags for heap 1. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags2 | <String> | Flags for heap 2. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags3 | <String> | Flags for heap 3. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags4 | <String> | Flags for heap 4. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags5 | <String> | Flags for heap 5. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags6 | <String> | Flags for heap 6. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags7 | <String> | Flags for heap 7. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags8 | <String> | Flags for heap 8. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemFlags9 | <String> | Flags for heap 9. These can be one or more of NO_MSG_ON_FAIL, USE_STACK_ALLOCATOR or INACTIVE. Default is no flags (Heap active, using normal allocator, with failure messages). See the s3e docs for more information.
MemRequired | <Integer> | User-specified total memory requirement of the s3e application, beyond that of the S3E runtime. Before loading the user s3e application and allocating memory for its heaps, S3E ensures that this amount of memory is available, and displays a platform-specific error message if not. Default is 64k (65536 bytes). The user should not normally need to set this setting.
MemSizeDebug | <Integer> | Size of X86 main application debug heap in bytes. Default is 5Mb (5242880 bytes). Note this heap is
MemSizeDebugDevice | <Integer> | Size of ARM main application debug heap in bytes. Default is 1Mb (1048576 bytes). Note this heap is allocated only when the s3eExtDebugHeap extension is called.
OutOfMemoryMessage | <String> | Message to display if the device doesn't have enough memory to run the app.
OutOfMemoryMessage2 | <String> | Message to display if the device doesn't have enough memory to even begin loading the app.
APITrace | <0 or 1> | If 1, traces all calls to s3e.
ErrorTrace | <0..3> | 0=trace no errors, 1=trace only major errors, 2=trace major and normal errors, 3=trace major, normal and minor errors. Default is 2
stdout | <string> | If specified then writes to stdout will go to this file
stderr | <string> | If specified then writes to stderr will go to this file
OverrideArch | <Integer> | Override the loaders reported architecture. Must be a number from the s3eDeviceArchitecture enumeration.
OverrideVFP | <1 or 0> | Override the loaders reported VFP status.
HandleCPUExceptions | <1 or 0> | Set to 1 to force the load the handle CPU exceptions. By default the loader will handle exceptions only when a debugger is not attached.
Profile | <1 or 0> | On platforms that support outputting profile data, this setting can be used to enable it. Default is 0.
MaxAllocationWarning | <0 or 1> | Set this to 0 to disable an assertion when the debug memory manager runs out of storage for debug memory info (occurs when > 20,000 memory blocks are in use). Default is 1
GLESVersion | <Integer> | The major version of GLES the application would prefer to use when multiple versions are available. On some platforms all versions will be available and can be selected using EGL; on those devices this setting will affect only the return value of s3eGetGLInt(S3E_GL_VERSION). By default, GLES 1.x will be used. GLESVersion=2 will allow the application to initialise GLES 2.x on devices that provide it, if GLES 2.x is not present then GLES 1.x will be linked and available as usual.
AbsGameA | <String> | Abstract key A assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyA=Enter. s3eKeyAbsGameA will be 'pressed' whenever the specified key is pressed. Default is '5'.
AbsGameB | <String> | Abstract key B assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyB=Enter. s3eKeyAbsGameB will be 'pressed' whenever the specified key is pressed. Default is '6'.
AbsGameC | <String> | Abstract key C assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyC=Enter. s3eKeyAbsGameC will be 'pressed' whenever the specified key is pressed. Default is '8'.
AbsGameD | <String> | Abstract key D assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyD=Enter. s3eKeyAbsGameD will be 'pressed' whenever the specified key is pressed. Default is '9'.
AbsUp | <String> | Abstract key Up assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyUp=Enter. s3eKeyAbsGameUp will be 'pressed' whenever the specified key is pressed. Default is 'Up'.
AbsDown | <String> | Abstract key Down assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyDown=Enter. s3eKeyAbsGameDown will be 'pressed' whenever the specified key is pressed. Default is 'Down'.
AbsLeft | <String> | Abstract key Left assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyLeft=Enter. s3eKeyAbsGameLeft will be 'pressed' whenever the specified key is pressed. Default is 'Left'.
AbsRight | <String> | Abstract key Right assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyRight=Enter. s3eKeyAbsGameRight will be 'pressed' whenever the specified key is pressed. Default is 'Right'.
AbsOk | <String> | Abstract key "OK" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyOk=Enter. s3eKeyAbsGameOk will be 'pressed' whenever the specified key is pressed. Default is 'OK'.
AbsASK | <String> | Abstract key "Action softkey" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyASK=Enter. s3eKeyAbsGameASK will be 'pressed' whenever the specified key is pressed. Default is 'LSK' or 'RSK' according to whether the left or right softkey is used for 'select' on the device
AbsBSK | <String> | Abstract key "Back softkey" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyBSK=Enter. s3eKeyAbsGameBSK will be 'pressed' whenever the specified key is pressed. Default is 'LSK' or 'RSK' according to whether the left or right softkey is used for 'back' on the device
AbsGameA2 | <String> | Second abstract key A assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyA=Enter. s3eKeyAbsGameA will be 'pressed' whenever the specified key is pressed. Default is '5'.
AbsGameB2 | <String> | Second abstract key B assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyB=Enter. s3eKeyAbsGameB will be 'pressed' whenever the specified key is pressed. Default is '6'.
AbsGameC2 | <String> | Second abstract key C assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyC=Enter. s3eKeyAbsGameC will be 'pressed' whenever the specified key is pressed. Default is '8'.
AbsGameD2 | <String> | Second abstract key D assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyD=Enter. s3eKeyAbsGameD will be 'pressed' whenever the specified key is pressed. Default is '9'.
AbsUp2 | <String> | Second abstract key Up assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyUp=Enter. s3eKeyAbsGameUp will be 'pressed' whenever the specified key is pressed. Default is 'Up'.
AbsDown2 | <String> | Second abstract key Down assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyDown=Enter. s3eKeyAbsGameDown will be 'pressed' whenever the specified key is pressed. Default is 'Down'.
AbsLeft2 | <String> | Second abstract key Left assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyLeft=Enter. s3eKeyAbsGameLeft will be 'pressed' whenever the specified key is pressed. Default is 'Left'.
AbsRight2 | <String> | Second abstract key Right assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyRight=Enter. s3eKeyAbsGameRight will be 'pressed' whenever the specified key is pressed. Default is 'Right'.
AbsOk2 | <String> | Second abstract key "OK" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyOk=Enter. s3eKeyAbsGameOk will be 'pressed' whenever the specified key is pressed. Default is 'OK'.
AbsASK2 | <String> | Second abstract key "Action softkey" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyASK=Enter. s3eKeyAbsGameASK will be 'pressed' whenever the specified key is pressed. Default is 'LSK' or 'RSK' according to whether the left or right softkey is used for 'select' on the device
AbsBSK2 | <String> | Second abstract key "Back softkey" assignment. Specify any s3eKey enumeration, with the 's3eKey' prefix removed. For example, AbsGameKeyBSK=Enter. s3eKeyAbsGameBSK will be 'pressed' whenever the specified key is pressed. Default is 'LSK' or 'RSK' according to whether the left or right softkey is used for 'back' on the device
AbsASKPositionPortrait | <Integer> | Abstract key "Action softkey" on-screen label position when orientation is portrait. The value must be one of the s3eDeviceSoftKeyPosition enumerations. For example S3E_DEVICE_SOFTKEY_BOTTOM_LEFT. Defaults are device specific based on OS/hardware setup.
AbsBSKPositionPortrait | <Integer> | Abstract key "Back softkey" on-screen label position when orientation is portrait. The value must be one of the s3eDeviceSoftKeyPosition enumerations. For example S3E_DEVICE_SOFTKEY_BOTTOM_LEFT. Defaults are device specific based on OS/hardware setup.
AbsASKPositionLandscape | <Integer> | Abstract key "Action softkey" on-screen label position when orientation is landscape. The value must be one of the s3eDeviceSoftKeyPosition enumerations. For example S3E_DEVICE_SOFTKEY_BOTTOM_LEFT. Defaults are device specific based on OS/hardware setup.
AbsBSKPositionLandscape | <Integer> | Abstract key "Back softkey" on-screen label position when orientation is landscape. The value must be one of the s3eDeviceSoftKeyPosition enumerations. For example S3E_DEVICE_SOFTKEY_BOTTOM_LEFT. Defaults are device specific based on OS/hardware setup.
StackSize | <Integer> | Size of the runtime stack in bytes. Note that x86 usually consumes more stack that ARM does. Default is 32k (32768 bytes)
AutoStop | <Integer> | Debug loader only: if non-zero, will send a quit request to application after N milliseconds. Useful for automated testing. Default is 0.
TraceToFile | <0 or 1> | Debug loader only: if 1, enable tracing to a file. This is set to 1 by default on platforms that do not support a debug logger (e.g. Symbian), and set to 0 on those that do (e.g. Windows).
TraceToConsole | <0 or 1> | Debug loader only: if 1, enable tracing to the debug console. Default: 1
TraceToSurface | <0 or 1> | Debug loader only: if 1, enable tracing to the s3eSurface. Default: 0
TraceToNetwork | <0 or 1> | Debug loader only: if 1, listen on TCP port 4990 for incoming connections, and send trace data to any connecting client.
AssertDontStop | <0 or 1> | Debug loader only: if 1, suppress assertions from producing dialogs and halting execution. Default is 0.
ErrorDontStop | <0 or 1> | Debug loader only: if 1, suppress errors from producing dialogs and halting execution. Default is 0.
PermitNewerGameVersion | <0 or 1> | If 1, suppress assertion that loader version does not match application version. Default is 0.
SkipFreeRamCheck | <0 or 1> | If 1, skip the free ram check prior to loading the s3e.
ExtraDrive0_ID | <String> | Drive identifier for extra drive 0 (e.g. my_files://). Default is to have no extra drive.
ExtraDrive0_Prefix | <String> | Drive prefix for extra drive 0 (e.g. c:\my_documents\my_files). This is for use in allowing S3E applications to access areas outside the normal data directory. Required if ExtraDrive0_ID is specified.
ExtraDrive1_ID | <String> | Drive identifier for extra drive 1 (e.g. my_files://). Default is to have no extra drive.
ExtraDrive1_Prefix | <String> | Drive prefix for extra drive 1 (e.g. c:\my_documents\my_files). This is for use in allowing S3E applications to access areas outside the normal data directory. Required if ExtraDrive1_ID is specified.
ExtraDrive2_ID | <String> | Drive identifier for extra drive 2 (e.g. my_files://). Default is to have no extra drive.
ExtraDrive2_Prefix | <String> | Drive prefix for extra drive 2 (e.g. c:\my_documents\my_files). This is for use in allowing S3E applications to access areas outside the normal data directory. Required if ExtraDrive2_ID is specified.
SplashScreenBkR | <0..255> | Background colour red component to use for the splash screen. This colour will fill any remaining screen space that is not occupied by the image specified by SplashScreen. Default is 0.
SplashScreenBkG | <0..255> | Background colour green component to use for the splash screen. This colour will fill any remaining screen space that is not occupied by the image specified by SplashScreen. Default is 0.
SplashScreenBkB | <0..255> | Background colour blue component to use for the splash screen. This colour will fill any remaining screen space that is not occupied by the image specified by SplashScreen. Default is 0.
SplashScreen | <String> | Filename (relative to the data dir) of an image file to display as a splash screen before .s3e/.s86 file loading takes place. If this and all of SplashScreenBk* are unset, no splashscreen is displayed.
SplashScreenWidth | <Integer> | The width of the image on the screen - the image will be centred using this value (and stretched up on platforms that support it). If unset, the splashscreen will be displayed at the top-left of the screen.
SplashScreenHeight | <Integer> | The height of the image on the screen - the image will be centred using this value (and stretched up on platforms that support it). If unset, the splashscreen will be displayed at the top-left of the screen.
SplashMinDuration | <Integer> | The minimum amount of milliseconds to display the application's splashscreen for
ScreenSize | <Integer> | This property is set by the system and should not be assigned to. It is set to the quantised screen area in pixels, i.e. the value of s3eSurfaceGetInt(S3E_SURFACE_DEVICE_WIDTH_QUANTISED)*s3eSurfaceGetInt(S3E_SURFACE_DEVICE_HEIGHT_QUANTISED). This property is useful in assigning sizes for e.g. memory buffers for the screen
ScreenSize_NQ | <Integer> | This property is set by the system and should not be assigned to. It is set to the screen area in pixels, i.e. the value of s3eSurfaceGetInt(S3E_SURFACE_DEVICE_WIDTH)*s3eSurfaceGetInt(S3E_SURFACE_DEVICE_HEIGHT). This property is useful in assigning sizes for e.g. memory buffers for the screen. [S3E] ScreenSize should be used in preference to this setting, as it will vary less between handsets.
StereoSound | <0 or 1> | If possible open the hardware device in stereo mode and call the stereo callbacks when generating audio.
SoundOutputFrequency | <Integer> | If possible open the sound hardware device at this frequency.
AllowBackgroundAudio | <0 or 1> | This enables the BACKGROUND_AUDIO extension, and allows the app's audio to mix in with other background audio the device is playing (e.g. an mp3 played the built in iPod app on iPhone).
UseKeypadMapping | <0 or 1> | Set this integer to 1 to map the keyboard keys to keypad numbers, used for UIQ.
InvalidKeysGuard | <0 or 1> | Set this to 1 to enable the fix for the N91 problem of pressing 4,5,7 and 8 together generated a KAknUidValueEndKeyCloseEvent event.
DisableMultiKeys | <0 or 1> | Set this to 1 to disable allowing simultaneous key presses on the device.
AudioVolumeZeroOffset | <Integer> | This is the first non-zero value that actually produces audio on the device.
AudioVolumeDefault | <0..255> | This is the volume level with which the application will start up
SoundVolumeDefault | <0..255> | This is the volume level with which the application will start up
VideoVolumeDefault | <0..255> | This is the volume level with which the application will start up
ZeroVolThreshold | <0..255> | The threshold volume below which the sound stops
WindowWidth | <Integer> | On devices with a window manager, set the initial window width.
WindowHeight | <Integer> | On devices with a window manager, set the initial window height.
Tracing | <0 or 1> | Disable tracing at startup
Assertions | <0 or 1> | Disable assertions at startup
CameraSetupDelay | <Integer> | Number of milliseconds delay between initialising camera interface and starting preview (defaults to 300)
CameraCustomWidth | <Integer> | Known image width which will work with camera
CameraCustomHeight | <Integer> | Known image height which will work with camera
CameraStartTimeout | <Integer> | Time (in ms) to wait in order to allow frames to start being received. If timeout occurs default image size will be attempted.
CameraQueuedInterval | <Integer> | Time (in ms) that frames will be considered as queued by device, and therefore discarded. Stops device getting bogged down by more frames than user code can deal with
KeyboardCharDisabledAtStart | <0 or 1> | If 1, s3eKeyboardGetChar() will not return any characters and any device-specific character input method will be disabled. If 0, s3eKeyboardGetChar() will return characters if the device supports this. Default value is 1. Use s3eKeyboardSetInt() with the S3E_KEYBOARD_GET_CHAR property to subsequently enable/disable this at runtime.
StackSwitch | <0 or 1> | Set this to 0 to run the application in the same stack as the loader. This may prevent the [S3E] StackSize setting from working, and removes guarantees about the loader's use of the stack during s3e function calls. However it may solve problems when using extensions/OS code outside the loader. Not recommended for normal use. Default value is 1
FixScreenOrientation | <0 or 1 or 2> | If set to 1 sets the screen to portrait mode, 2 is for landscape mode and prevents s3e from automatically rotating the screen to compensate for the device being physically rotated. Default 0 is to set the screen to the native device orientation and follow any automatic rotation.
AccelDampingFactor | <Integer> | Default is OS specific. 0..100 as percentage of old value to factor in. 0 = no damping, 20 = 20% previous value.
AccelScaleFactor | <Integer> | Default is OS specific. 100 = 1x, 200 = 2x, 50 = 0.5x
SO_KEEPALIVE | <0 or 1> | Sets the default SO_KEEPALIVE socket option
SO_NODELAY | <0 or 1> | If set, the Nagel algorithm is disabled

S3E (iPhone)

Setting | Allowed Values | Description
iPhoneVideoShowControls | <0 or 1> | If set to 1 the on-screen controls will be shown during s3eVideo playback

S3E (Android)

Setting | Allowed Values | Description
AndroidFileNoMemoryCard | <0 or 1> | Do not use SD card as RAM drive for application data

S3E (NGI)

Setting | Allowed Values | Description
StartGSSTestServer | <0 or 1> | If 1, enables GSS Server (that comes with N-GageTestTool) on loader startup. Must be set to 1 for in application Notifications to work. If set to 1 and N-GageTestTool is not installed on device, launching application from the NGage Application will fail with error code -1! This will not be necessary with future NGI updates.
NGIAutoStartUpCheck | <0 or 1> | If 0, user must call s3eNGIStartUpCheck() to perform application services startup check (allow license purchase UI to be triggered etc). If 1, this occurs automatically after application is loaded / splash screen displayed.
GameSavesFolder | <String> | Specifies a folder alias to use for saving secure files. Any files saved to this "folder" will be securely stored on the devices internal drive and will persist after deleting the application. Trying access a subfolder of this folder or a file with the same name as the folder will fail. All other s3eFile operations treat this as a normal folder.
StartUpOrientation | <0 or 1> | Force splashscreens that display while application is loading to portrait(0) or landscape (1) if device does not support HW rotation. This is for if the application is in a fixed orientation that may not be the same as the devices default one. Default is use device default orientation.

S3E (Symbian)

Setting | Allowed Values | Description
VideoNone | <0 or 1> | If 1, video is not supported on this device.

S3E (Windows Mobile)

Setting | Allowed Values | Description
WaitCursorTimeout | <Integer> | Length of time in milliseconds to wait before displaying the windows wait cursor while start-up splash screen is being displayed. Default is 1000ms.
WinMobVibraMotorID | <Integer> | ID number of the Vibra motor. Vibration is controlled via an LED interface number on Pocket PCs which by default is assumed to be last available. This setting specifies a specific LED ID number to use instead. It has no effect on smartphones.

S3E (Windows x86)

Setting | Allowed Values | Description
ScreenFilter | <0 or 1> | If 1, enable bilinear filtering when expanding the S3E surface to display on the windows desktop. Default is 0.
PauseOnLoseFocus | <0 or 1> | If 0, disable sending 'pause' notifications to the application when the S3E window loses focus. Default is 1.
OGLES_Lib_1 | <String> | Name of 1st OpenGL ES library to load (overrides default).
OGLES_Lib_2 | <String> | Name of a 2nd OpenGL ES library to load if OGLES_Lib_1 is specified (do not use if no 2nd lib is needed).
OGLES_Lib_3 | <String> | Name of a 3rd OpenGL ES library to load if OGLES_Lib_2 is specified (do not use if no 3rd lib is needed).
ContactsUseWindowsAddressBook | <0 or 1> | Use the Local machines's Windows Address Book as the s3eContacts db. Default is 0.

S3E trace channels

[Trace]

Setting | Allowed Values | Description
ALL | <0 or 1> | If 1, enable tracing for all channels.
GL | <0 or 1> | If 1, output trace for GL device.
GL_VERBOSE | <0 or 1> | If 1, output trace for GL verbose.
AUDIO | <0 or 1> | If 1, output trace for S3E AUDIO.
AUDIO_VERBOSE | <0 or 1> | If 1, output trace for S3E AUDIO verbose.
CALLBACKS | <0 or 1> | If 1, output trace for S3E CALLBACKS internal.
CALLBACKS_VERBOSE | <0 or 1> | If 1, output trace for S3E CALLBACKS verbose.
CAMERA | <0 or 1> | If 1, output trace for S3E CAMERA.
CAMERA_VERBOSE | <0 or 1> | If 1, output trace for S3E CAMERA verbose.
COMPR | <0 or 1> | If 1, output trace for S3E COMPRESSION.
COMPR_VERBOSE | <0 or 1> | If 1, output trace for S3E COMPRESSION verbose.
CONFIG | <0 or 1> | If 1, output trace for S3E CONFIG internal.
CONFIG_VERBOSE | <0 or 1> | If 1, output trace for S3E CONFIG internal verbose.
CORE | <0 or 1> | If 1, output trace for IwCore module.
FIBRE | <0 or 1> | If 1, output trace for IwFibre.
CRYPTO | <0 or 1> | If 1, output trace for S3E CRYPTO.
CRYPTO_VERBOSE | <0 or 1> | If 1, output trace for S3E CRYPTO verbose.
DEBUG | <0 or 1> | If 1, output trace for S3E DEBUG.
DEBUG_VERBOSE | <0 or 1> | If 1, output trace for S3E DEBUG verbose.
DEFAULT | <0 or 1> | The default trace channel. This channel is always 'on'.
DEVICE | <0 or 1> | If 1, output trace for S3E DEVICE.
DEVICE_VERBOSE | <0 or 1> | If 1, output trace for S3E DEVICE verbose.
EXT | <0 or 1> | If 1, output trace for S3E EXT (extensions).
EXT_VERBOSE | <0 or 1> | If 1, output trace for S3E EXT (extensions) verbose.
FIBRE | <0 or 1> | If 1, output trace for S3E FIBRE (internal thread switching).
FIBRE_VERBOSE | <0 or 1> | If 1, output trace for S3E FIBRE verbose.
FILE | <0 or 1> | If 1, output trace for S3E FILE.
FILE_VERBOSE | <0 or 1> | If 1, output trace for S3E FILE verbose.
KEYBOARD | <0 or 1> | If 1, output trace for S3E KEYBOARD.
KEYBOARD_VERBOSE | <0 or 1> | If 1, output trace for S3E KEYBOARD verbose (traces all key events).
LOADER | <0 or 1> | If 1, output trace for S3E binary file loader.
LOADER_VERBOSE | <0 or 1> | If 1, output trace for S3E binary file loader.
LICENSE | <0 or 1> | If 1, output trace for S3E LICENSE.
LICENSE_VERBOSE | <0 or 1> | If 1, output trace for S3E LICENSE verbose.
MEMORY | <0 or 1> | If 1, output trace for S3E MEMORY.
MEMORY_VERBOSE | <0 or 1> | If 1, output trace for S3E MEMORY verbose.
LOADER_MEMORY | <0 or 1> | If 1, output trace for S3E LOADER_MEMORY.
MIC | <0 or 1> | If 1, output trace for S3E MIC.
MIC_VERBOSE | <0 or 1> | If 1, output trace for S3E MIC verbose.
S3E | <0 or 1> | If 1, output trace for S3E
SECSTORE | <0 or 1> | If 1, output trace for S3E SECSTORE.
SECSTORE_VERBOSE | <0 or 1> | If 1, output trace for S3E SECSTORE verbose.
SOCKET | <0 or 1> | If 1, output trace for S3E SOCKET.
SOCKET_VERBOSE | <0 or 1> | If 1, output trace for S3E SOCKET verbose.
SOUND | <0 or 1> | If 1, output trace for S3E SOUND.
SOUND_VERBOSE | <0 or 1> | If 1, output trace for S3E SOUND verbose.
SURFACE | <0 or 1> | If 1, output trace for S3E SURFACE.
SURFACE_VERBOSE | <0 or 1> | If 1, output trace for S3E SURFACE verbose.
VIBRA | <0 or 1> | If 1, output trace for S3E VIBRA.
VIBRA_VERBOSE | <0 or 1> | If 1, output trace for S3E VIBRA verbose.
VIDEO | <0 or 1> | If 1, output trace for S3E VIDEO.
VIDEO_VERBOSE | <0 or 1> | If 1, output trace for S3E VIDEO verbose.
IWCRT | <0 or 1> | If 1, output trace for C runtime.
IWCRT_VERBOSE | <0 or 1> | If 1, output trace for C runtime.
POINTER | <0 or 1> | If 1, output trace for S3E POINTER.
POINTER_VERBOSE | <0 or 1> | If 1, output trace for S3E POINTER verbose.
ZEROCONF | <0 or 1> | If 1, output trace for S3E ZEROCONF.
ZEROCONF_VERBOSE | <0 or 1> | If 1, output trace for S3E ZEROCONF verbose.
BACKGROUNDAUDIO | <0 or 1> | If 1, output trace for S3E ZEROCONF.
BACKGROUNDAUDIO_VERBOSE | <0 or 1> | If 1, output trace for S3E ZEROCONF verbose.
OSREADSTRING | <0 or 1> | If 1, output trace for S3E OSREADSTRING.
OSREADSTRING_VERBOSE | <0 or 1> | If 1, output trace for S3E OSREADSTRING verbose.
PSGL | <0 or 1> | If 1, output trace for S3E PSGL.
PSGL_VERBOSE | <0 or 1> | If 1, output trace for S3E PSGL verbose.
PTHREAD | <0 or 1> | If 1, output trace for PTHREAD.
ZEROCONF | <0 or 1> | If 1, output trace for ZEROCONF.

S3E assertion channels

[Assert]

Setting | Allowed Values | Description
DEFAULT | <0 or 1> | If 1, output assertions on the default channel
S3E | <0 or 1> | If 1, output assertions on user errors.
DEPRECATED | <0 or 1> | If 1, output assertions on deprecated functions/features.

GX config values

[GX]

Setting | Allowed Values | Description
RecreateGLSurfaceOnResize | <0 or 1> | Does the GL surface need to be recreated when the device rotates?
RecreateGLSurfaceOnResume | <0 or 1> | Does the GL surface need to be recreated when the device regains focus?

EGL config values

[GL]

Setting | Allowed Values | Description
EGL_BUFFER_SIZE | <Integer> | Depth of screen buffer in bits requested from EGL.
EGL_DEPTH_SIZE | <Integer> | Depth of depth buffer in bits requested from EGL.
EGL_SURFACE_TYPE | <1 or 2> | 1 for EGL window surface, 2 for EGL pixmap surface. Default is 1.
EGL_RED_SIZE | <Integer> | Number of bits per pixel for the red channel.
EGL_GREEN_SIZE | <Integer> | Number of bits per pixel for the green channel.
EGL_BLUE_SIZE | <Integer> | Number of bits per pixel for the blue channel.
EGL_ALPHA_SIZE | <Integer> | Number of bits per pixel for the alpha channel (-1 for 'do not care').
EGL_STENCIL_SIZE | <Integer> | Number of bits for the stencil buffer.
EGL_SAMPLE_BUFFERS | <0 or 1> | 1 for anti-aliasing, else 0.
EGL_SAMPLES | <1, 2 or 4> | 1 for no anti-aliasing, 2 for multi-sampling, 4 for super-sampling.
EGLTerminateOnSuspend | <0 or 1> | If 1 the application must handle termination of EGL when the app suspends. IwGx will do this by expanding heap 6 and using it as a shadow for all uploaded resources...


Airplay SDK: Derbh ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > Derbh ICF Settings >

Derbh ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels
  • Airplay Studio assertion channels

General

[Derbh]

Setting | Allowed Values | Description
autoload | <string> | Filename of archive to initialise on startup.
MinBufSize | <int> | Minimum buffer size to use when decompressing data. The default size is the compression window size used when compressing the data (this is the minimum). However larger buffers can be used, which facilitates seeking within a compressed file (seeking to data thats already buffered is free, whereas otherwise the file needs to be re-decompressed up to the seek point)

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
DERBH | <0 or 1> | If 1, output trace for Derbh module.
DERBH_VERBOSE | <0 or 1> | If 1, output detailed derbh trace, defaults to 0

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
DERBH | <0 or 1> | If 1, output assertions for Derbh module.


Airplay SDK: IwUtil ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwUtil ICF Settings >

IwUtil ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels
  • Airplay Studio assertion channels

General

[UTIL]

Setting | Allowed Values | Description
NumMemBuckets | <Integer> | Maximum number of memory buckets allowed.
MaxAllocationWarning | <0 or 1> | Whether to warn when the application exceeds the maximum number of track-able memory allocations. (Default to on)
NumClassFactories | <Integer> | Space reserved for class factories. Extra class factories will cause a reallocation. Defaults to 192.
MemoryBreakpoint | <Integer> | Memory allocation number to break on.
MenuUp | <s3eKey> | Binding for Menu Up
MenuDown | <s3eKey> | Binding for Menu Down
MenuLeft | <s3eKey> | Binding for Menu Left
MenuRight | <s3eKey> | Binding for Menu Right
MenuEnter | <s3eKey> | Binding for Menu Enter (Select item)
MenuShift | <s3eKey> | Binding for Menu Shift (quick change value)
MenuControl | <s3eKey> | Binding for Menu Control (very quick change value)
MenuPlus | <s3eKey> | Binding for Menu Plus (Increase value)
MenuMinus | <s3eKey> | Binding for Menu Minus (Decrease value)
MenuInput | <s3eKey> | Binding for Menu Input (Toggles control of menu without exiting)
MenuFocus | <s3eKey> | Binding for Menu Focus (Exits menu)

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
UTIL | <0 or 1> | If 1, output trace for IwUtil module.

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
UTIL | <0 or 1> | If 1, output assertions for IwUtil module.


Airplay SDK: IwGeom ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwGeom ICF Settings >

IwGeom ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • Airplay Studio assertion channels

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
GEOM | <0 or 1> | If 1, output assertions for IwGeom module.


Airplay SDK: IwGx ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwGx ICF Settings >

IwGx ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels
  • Airplay Studio assertion channels

General

[GX]

Setting | Allowed Values | Description
Rasterisation | <String> | 'SW', 'HW', 'SW/HW' or 'HW/SW', indicating support for software rasterisation only, hardware rasterisation, or both. If both are specified, both are supported, and the first indicates which mode is started in.
Transform | <String> | 'SW', 'HW', 'SW/HW' or 'HW/SW', indicating support for software transform only, hardware transform, or both. If both are specified, transform will begin in hardware can be dynamically switch to software.
Lighting | <String> | 'SW', 'HW', 'SW/HW' or 'HW/SW', indicating support for software lighting only, hardware lighting, or both. If both are specified, lighting will begin in hardware can be dynamically switch to software.
DataCacheSize | <Integer> | Size in bytes of the global IwGx data cache. Default is 16384.
DataCacheSizeHW | <Integer> | (Optional) Size in bytes of the global IwGx data cache when HW rasterisation is initialised. If not specified DataCacheSize will be used.
NumSlotsFront | <Integer> | Number of sorting slots for 2D drawing that are in front of the 3D geometry. Default is 32.
NumSlotsBack | <Integer> | Number of sorting slots for 2D drawing that are behind the 3D geometry. Default is 4.
NumAnimatingMaterials | <Integer> | Number of animating textures to reserve space for. If unspecified, memory will be allocated dynamically.
DrawPriorityFIFO | <0 or 1> | If 1, for polys with equal Z (or equal sort slot), favor the first one submitted. Default is 0.
AssertPowerOf2 | <0 or 1> | If 1, assert if a non-power-of-2 texture is uploaded. Non-power-2 textures have certain limitations associated with them. Default is 0.
VertCacheSize | <Integer> | Software transform only: size of the IwGx software vertex cache. Default is 2048 vertices. Each cached vert is 20 bytes.
VertCacheSizeHW | <Integer> | Software transform only: size of the IwGx software vertex cache when HW rasterisation is initialised. If not specified VertCacheSize will be used.
PolyBufferSize | <Integer> | Software rasterisation only: size in bytes of the buffer used for the draw-list for the software renderer. Default is 32768.
PolyOTSize | <Integer> | Software rasterisation only: size in (4-byte) slots of the bucket-sorting ordering table used for the software renderer. Defaults is 4096.
PolyOTSizeSafety | <Integer> | Software rasterisation only: number of ordering table slots which will be behind the far z clip plane. The total number of slots remains the same as PolyOTSize.
NumTPages | <Integer> | Software rasterisation only: number of texture pages used for storing textures for the software renderer. Default is 16. Each page consumes 47306 bytes. The number of pages will be rounded up to the next even number.
NumTPagesNoMipMap | <Integer> | Software rasterisation only: number of texture pages without mipmaps. Default is 0. These pages will be used automatically when textures with mipmapping disabled are uploaded. This can be used to optimise memory usage, since each page consumes only 32768 bytes. The number of pages will be rounded up to the next even number.
NumTPageFreeRects | <Integer> | Software rasterisation only: maximum number of free rectangles that can be stored per texture page. Default is 14. Each rectangle consumes 8 bytes. If this number is exceeded then new memory will be allocated, and may not be freed until gx terminate.
MaxTexturesPerTPage | <Integer> | Software rasterisation only: maximum number of textures that can be allocated from each texture page. Default is 50. Each texture consumes 8 bytes. If this number is exceeded then new memory will be allocated, and may not be freed until gx terminate. One list is kept for each t-page, and used to ensure that, when used in a FILO fashion, t-pages will return to the same free rect state following de-allocation. If this icf setting is set to zero, no list will be kept (saving memory) but t-pages may not return to the same state after deallocation.
NumPalettes16 | <Integer> | Software rasterisation only: maximum number of 16-colour palettes that can be stored. Default is 192. Each 16 colour palette consumes 48 bytes.
NumPalettes256 | <Integer> | Software rasterisation only: maximum number of 256-colour palettes that can be stored. Defaults is 64. Each 256 colour palette consumes 528 bytes.
UseEnvMap | <0 or 1> | Software rasterisation only: if 1, enable a screen-based environment map when software rendering. Default is 0.
PaletteSaturation | <0 or 1> | Software rasterisation only: if 1, calculated colour components from 128..255 result in textures being over-saturated. Note that this affects software rasterisation only. Default value is 0.
NumPaletteCacheBlocks | <Integer> | Software rasterisation only: maximum number of lit 16/256 colour palette cache blocks. Default is 16. Each block consumes 16896 bytes.
NumU16PaletteCacheBlocks | <Integer> | Software rasterisation only: maximum number of unlit 16 colour palettes that can be cached. Default is 24. Each 16 colour palette requires 32 bytes.
NumU256PaletteCacheBlocks | <Integer> | Software rasterisation only: maximum number of unlit 256 colour palettes that can be cached. Default is 4. Each 256 colour palette requires 512 bytes.
PixelsDrawnBeforeYield | <Integer> | Software rasterisation only: equivalent pixels to draw before calling s3eDeviceYield(0) within a SW IwGxFlush(). Default is 5120 or 32 times the NumSpansBuffered setting.
NumScanLineRendEdges | <Integer> | Software rasterisation only: number of Edges in the ScanLine renderer. Default is 600. Each Edge is 100 bytes
NumScanLineRendPolys | <Integer> | Software rasterisation only: number of Polys in the ScanLine renderer. Default is 300. Each Poly is 40 bytes
NumScanLineRendLists | <Integer> | Software rasterisation only: number of Lists in the ScanLine renderer. Default is 20. Each List is 32 bytes
NumScanLineRendBuckets | <Integer> | Software rasterisation only: number of Buckets in the ScanLine renderer. Default is 60. Each Bucket is 64 bytes
Force4BitGouraudDither | <Integer> | Software rasterisation only: dither between shades to reduce colour banding when Gouraud rendering 4bit-1555 textures. Default is 0.
PaletteTintByAmbientColour | <Integer> | Software rasterisation only: tint all palettes by the AmbientColour of the material. Default is 0.
UseRgbLighting | <0 or 1> | Software rasterisation only: globally disable/enable RGB modulation during SW rendering. RGB polys are significantly more expensive to render, so it is advisable to set this on only on higher-end devices. Default is off.
ScreenOrientAutoHandled | <0 or 1> | If 1 GX will handle rotated screen so that s3e doesn't have to do a rotated blit
ZDepthOfsSafety | <Integer> | The ordering table spans from NearZ to FarZ plus ZDepthOfsSafety
DisplayFrameRate | <0 or 1> | Display the frame rate on screen
GL_IMG_vertex_program | <0 or 1> | - set to 0 to disable that extension
GL_IMG_texture_compression_pvrtc | <0 or 1> | - set to 0 to disable that extension
GL_ARB_texture_env_combine | <0 or 1> | - set to 0 to disable that extension
GL_IMG_texture_env_enhanced_fixed_function | <0 or 1> | - set to 0 to disable that extension
GL_OES_matrix_palette | <0 or 1> | - set to 0 to disable that extension
GL_IMG_user_clip_planes | <0 or 1> | - set to 0 to disable that extension
GL_OES_draw_texture | <0 or 1> | - set to 0 to disable that extension
GL_ATI_texture_compression_atitc | <0 or 1> | - set to 0 to disable that extension
GL_ATI_extended_texture_coordinate_data_formats | <0 or 1> | - set to 0 to disable that extension
GL_OES_framebuffer_object | <0 or 1> | - set to 0 to disable that extension
GL_OES_compressed_ETC1_RGB8_texture | <0 or 1> | - set to 0 to disable that extension
GL_S3E_async | <0 or 1> | - set to 0 to disable that extension
CompressedTexCacheSize | <Integer> | Sets the value in bytes of the maximum size of the compressed textures cache on disk. Defaults to 10 Mbs (10485760 bytes).
GLErrorChecking | <0 or 1> | In debug, check for gl errors frequently. This can adversely affect performance (dramatically so on some platforms).
PrintStringNumChars | <Integer> | Total number of characters permitted when using IwGxPrintString(), between each call to IwGxFlush(). Default is 2048.
PrintStringNumStrings | <Integer> | Total number of strings permitted when using IwGxPrintString(), between each call to IwGxFlush(). Default is 128.
ResBuild | <0 or 1> | If 1, enable building of resources (conversion of text-format resources into binary assets), 0 to disable resource building and only load binary assets. Default is 1 for debug configurations, 0 for release configurations.
ResBuildStyle | <String> | Name of build style to use for building resources. Build styles must be defined in /resbuildstyles.itx
PaletteCacheSize | <Integer> | Software rasterisation only: maximum number of entries in the palette cache. Default is 800.
useGLContextShadow | <Integer> | If non-zero, Gx will allocate a block of memory in IwGxInit() of the specified size and maintain a copy of the data required to restore the GL context. On suspend, the GL context will be freed and on suspend it will be restored and configured back to pre-suspension state. This behaviour is required on KDDI GL devices. Default is 0 (i.e. off).
DisableSurfaces | <0 or 1> | Disable IwGxSurface. All calls to CreateSurface will fail and return false.
ShaderUniformShadowMem | <Integer> | Size (in bytes) of the GL2 Shader Uniform Shadow. If this space runs out more gl calls than are strictly required will be made. Default value is 30000.
DisableCustomShaders | <0 or 1> | Disable custom shaders on materials
NoTextureUpload | <0 or 1> | If 1, bypass texture upload (all textures will be solid white)
UploadStreams | <0 or 1> | High-level control over whether streams are uploaded to VBOs. Defaults to 1 (streams are uploaded).
FreeStreamData | <0 or 1> | High-level control over whether local copis of stream data is ever deleted. Note IwGraphics models can be instructed to keep local copies of data using the geo template. Defaults to 1 (CIwGxStream::Upload ignores the passed parameters)
RecreateGLSurfaceOnResize | <0 or 1> | Does the GL surface need to be recreated when the device rotates?
BrowseAtlas | <0 or 1> | Browse atlases as they load

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
GX | <0 or 1> | If 1, output trace for GX module.
GX_VERBOSE | <0 or 1> | If 1, output verbose trace for GX module.

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
GX | <0 or 1> | If 1, output assertions for GX module.


Airplay SDK: IwResmanager ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwResmanager ICF Settings >

IwResmanager ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels
  • Airplay Studio assertion channels

General

[RESMANAGER]

Setting | Allowed Values | Description
ResBuild | <0 or 1> | If 1, enable building of resources (conversion of text-format resources into binary assets), 0 to disable resource building and only load binary assets. Default is 1 for debug configurations, 0 for release configurations.
ResBuildStyle | <String> | Name of build style to use for building resources. Build styles must be defined in /resbuildstyles.itx
DontTestBinaries | <0 or 1> | Usually when a group is generated from source resources the versions of the resources built from source are destroyed and reloaded from the generated binaries. Enabling this flag disables that behaviour (the binaries are untested, but execution will continue more quickly). Use with caution - often resources have special behaviour when reading in serialise (for example, textures may be uploaded) any such behaviour will not be executed and thus resources are very unlikely to be in a usable state. The binaries generated will be identical. Default is 0.
BuildOnly | <String> | If set, build only groups appearing in this list. The list must be the plain filename of the group, e.g. BuildOnly=fixed will build only fixed.group. Note that if a parent group is excluded from being build using this setting, it's children will be also.
IgnoreInlining | <0 or 1> | If 1, ignore "inline" directives in group templates. Child groups will always be built as distinct binaries. Default 0 (obey inline directives)

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
RESMANAGER | <0 or 1> | If 1, output trace for IwResManager module.
RESMANAGER_MOUNT | <0 or 1> | If 1, output trace of detailed information about mounted groups

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
RESMANAGER | <0 or 1> | If 1, output assertions for IwResManager module.


Airplay SDK: IwGraphics ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwGraphics ICF Settings >

IwGraphics ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels
  • Airplay Studio assertion channels

General

[Graphics]

Setting | Allowed Values | Description
SelSetZOffset | <Integer> | Meaning of Selection set Z Offset 1 in worldspace units. By default, other offsets proceed in powers of 2 from this value.
BrowseAtlas | <0 or 1> | Browse produced texture atlas(es)

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
GRAPHICS | <0 or 1> | If 1, output trace for IwGraphics module.
GRAPHICS_VERBOSE | <0 or 1> | If 1, output verbose trace for IwGraphics module.

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
GRAPHICS | <0 or 1> | If 1, output assertions for IwGraphics module.


Airplay SDK: IwAnim ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwAnim ICF Settings >

IwAnim ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • Airplay Studio trace channels
  • Airplay Studio assertion channels

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
ANIM | <0 or 1> | If 1, output trace for IwAnim module.

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
ANIM | <0 or 1> | If 1, output assertions for IwAnim module.


Airplay SDK: IwGxFont ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwGxFont ICF Settings >

IwGxFont ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • Airplay Studio trace channels
  • Airplay Studio assertion channels

Airplay Studio trace channels

[Trace]

Setting | Allowed Values | Description
GX_FONT | <0 or 1> | If 1, output trace for IwGxFont module.
GX_FONT_VERBOSE | <0 or 1> | If 1, output verbose trace for IwGxFont module.

Airplay Studio assertion channels

[Assert]

Setting | Allowed Values | Description
GX_FONT | <0 or 1> | If 1, output assertions for IwGxFont module.


Airplay SDK: IwHTTP ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwHTTP ICF Settings >

IwHTTP ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General
  • Airplay Studio trace channels

General

[connection]

Setting | Allowed Values | Description
httpproxy | <String> | The proxy that the client should route all HTTP request via. If not set then either the default proxy will be used or the connection will be made directly.
httpproxyport | <Integer> | The port to connect to on the proxy server. Default is 80
usehttpproxy | <Integer> | If set to 0, connect directly, ignoring any proxy data specified either in the icf or by s3e. Default 1
httpproxiestoignore | <String> | Comma-separated list of proxies to ignore if told to use them by s3e. Each proxy is in the format hostname:port, however it must be the same as the string returned by s3e. (e.g. myhost:80 and myhost are different despite 80 being the default port) Behaviour is undefined if the proxy specified in the icf is in this list.
httpconnecttimeout | <Integer> | The connect timeout in milliseconds. Defaults to 60000 (1 minute)

Airplay Studio trace channels

[trace]

Setting | Allowed Values | Description
HTTP | <Integer> | Trace all the HTTP traffic 0=None,1=Status,2=Headers,3=Short,4=All


Airplay SDK: IwUI ICF Settings

Airplay SDK > Airplay Programmer Tools Reference > ICF File Settings > IwUI ICF Settings >

IwUI ICF Settings

The tables below list the available ICF settings for this module of Airplay.

The value given in square brackets must appear in your icf file before any options that follow it in the listing below.

See the ICF Files section of Airplay Concepts for more details including how to define your own ICF settings.

Adding undocumented settings to an icf will result in an error when reading the file using a debug loader.

Settings by subgroups:

  • General

General

[UI]

Setting | Allowed Values | Description
TextInputEditorMode | <String> | One of the following: SoftKeyboard, SoftNumpad, HardwareKeyboard, HardwareNumpad, OS


Airplay SDK: Windows Simulator

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator >

Windows Simulator

The Windows Simulator is a Windows application that runs the Win32/x86 build of an Airplay application and can be used to debug on Windows before deploying to devices.

The simulator is launched by selecting run (F5) from the IDE for an x86 build of an Airplay application or by running a .s86 file that was deployed using Airplay.

The application will be run in a window which can be configured so that it more accurately reflects the configuration of a specific device. Constraining the Windows Simulator to emulate the configuration of a device means you can run and test your application quickly and efficiently on the desktop without having to physically deploy to the device. A variety of configuration options are provided to simulate different target devices; for example screen size, screen rotation, touchscreen support, etc. These options may be set via the menu at the top of the window.

Note that the Windows Simulator can be run in configuration-only mode by holding down F5 as it starts up. This disables loading of any Airplay application, and is useful for changing the configuration via the menus without interruption from the application.

The Windows Simulator provides the following menu options:

  • File Menu Option
  • Configuration Menu Option
  • Preferences Menu Option
  • Events Menu Option
  • Metrics Menu Option
  • Help Menu Option


Airplay SDK: File Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > File Menu Option >

File Menu Option

The File menu option has two options:

  • Restart Application: This option allows you to quickly restart the application, enabling you to change configuration and check the status of the application on start up.
  • Exit: This option closes the application.


Airplay SDK: Configuration Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option >

Configuration Menu Option

The options contained in the Configuration menu allow you to configure certain Airplay System options. The following options are available:

  • Accelerometer Configuration
  • Audio Configuration
  • Device Configuration
  • File Configuration
  • GL Configuration
  • Keyboard Configuration
  • License Configuration
  • Location Configuration
  • Memory Configuration
  • Pointer Configuration
  • Sound Configuration
  • Socket Configuration
  • Surface Configuration
  • Vibra Configuration
  • Video Configuration
  • All Settings
  • Reset to Default


Airplay SDK: Accelerometer Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Accelerometer Configuration >

Accelerometer Configuration

Clicking 'Configuration > Accelerometer...' displays the 'Accelerometer Settings' Dialog. This dialog allows you to simulate movement of a device by using the mouse to tip, spin or shake the image of the phone to see how the application responds. Specific movement instructions are provided within the dialog box.

  • Enable Accelerometer: This tickbox enables or disables the Accelerometer and the controls
  • X: This is the X axis value, this can be altered using the slider or typing a value directly into the field
  • Y: This is the Y axis value, this can be altered using the slider or typing a value directly into the field
  • Z: This is the Z axis value, this can be altered using the slider or typing a value directly into the field
  • Reset Orientation: This button resets the orientation of the simulated device


Airplay SDK: Audio Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Audio Configuration >

Audio Configuration

Clicking 'Configuration > Audio...' displays the 'Audio Configuration' dialog. This dialog allows you to select the codecs that are available on the device you are trying to emulate. Select the check box beside the name of each codec you would like to include. The codecs available are illustrated below.

  • MIDI: Select this option to allow s3eAudioPlay() to succeed on MIDI format (.mid) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_MIDI) will return 1 if this option is set.
  • MP3: Select this option to allow s3eAudioPlay() to succeed on MP3 format (.mp3) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_MP3) will return 1 if this option is set.
  • AAC: Select this option to allow s3eAudioPlay() to succeed on AAC format (.aac) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_AAC) will return 1 if this option is set.
  • AAC Plus: Select this option to allow s3eAudioPlay() to succeed on AAC -plus format (or MPEG4 - AAC HE) (.aac) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_AAC_PLUS) will return 1 if this option is set.
  • QCP: Select this option to allow s3eAudioPlay() to succeed on Quallcomm QCP format (.qcp) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_QCP) will return 1 if this option is set.
  • PCM: Select this option to allow s3eAudioPlay() to succeed on uncompressed PCM format (.wav) files. s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_PCM) will return 1 if this option is set.
  • Default Volume: This is the volume returned by s3eAudioGetInt(S3E_AUDIO_VOLUME_DEFAULT). This is also the volume that the audio device is set to when the application starts up.


Airplay SDK: Device Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Device Configuration >

Device Configuration

Clicking 'Configuration > Device...' displays the 'Device Configuration' dialog as illustrated below.

The Device Configuration options are as follows:

  • Reported Operating System: This option allows you to enter the operating system that will be returned by s3eDeviceGetInt(S3E_DEVICE_OS) or s3eDeviceGetString(S3E_DEVICE_OS). It has no other effect on the system.
  • Reported Device Class: This option allows you to enter the device class that will be returned be s3eDeviceGetInt(S3E_DEVICE_CLASS) or s3eDeviceGetString(S3E_DEVICE_CLASS). It has no other effect on the system.
  • Reported String Device ID: This option allows you to enter the device ID that will be returned be s3eDeviceGetString(S3E_DEVICE_ID). It does not affect the return value of s3eDeviceGetInt(S3E_DEVICE_ID). It has no other effect on the system. If this is blank, the network name of the host computer is used.
  • Reported Phone Number: This option allows you to enter the string that will be returned by s3eDeviceGetString(S3E_DEVICE_PHONE_NUMBER). If this is blank, the network name of the host computer is used. (This is useful in cases where phone numbers are used by an application to identify devices)
  • Reported Device Language: This options allows you to enter the language that will be returned by s3eDeviceGetInt(S3E_DEVICE_LANGUAGE).
  • Reported Integer Device ID: This option allows you to enter the integer that will be returned by s3eDeviceGetInt(S3E_DEVICE_ID). It does not affect the return value of s3eDeviceGetString(S3E_DEVICE_ID). It has no other effect on the system. Note that when the application is run under the ARM emulator, s3eDeviceGetInt(S3E_DEVICE_ID) will always return 1, irrespective of the setting entered here.
  • Reported Free RAM: This option allows you to enter the integer that will be returned by s3eDeviceGetInt(S3E_DEVICE_FREE_RAM).
  • Reported Total RAM: This option allows you to enter the integer that will be returned by s3eDeviceGetInt(S3E_DEVICE_TOTAL_RAM).
  • Reported Architecture: This option allows you to enter the processor architecture that will be returned by s3eDeviceGetInt(S3E_DEVICE_ARCHITECTURE). It has no other effect on the system. Note that when the application is run under the ARM emulator, s3eDeviceGetInt(S3E_DEVICE_ARCHITECTURE) will always return S3E_DEVICE_ARCHITECTURE_ARM6Z , irrespective of the setting entered here.
  • Reported Floating Point Unit: This option allows you to specify whether s3eDeviceGetInt(S3E_DEVICE_FPU) will indicate the presence of an FPU or not. It has no other effect on the system.
  • Reported Battery Level: This option allows you to enter the integer returned by s3eDeviceGetInt(S3E_DEVICE_BATTERY_LEVEL).
  • Reported Using Mains Power: This option allows you to set whether the device is using mains power. If checked, it is considered to be using mains power and s3eDeviceGetInt(S3E_DEVICE_MAINS_POWER) will return 1. Otherwise the battery is in use and this function call will return 0.
  • Reported Back Softkey Position: This option allows you to set the position relative to the screen at which the 'back' softkey is located. To emulate a BREW-style device where the softkeys are placed below the screen and the left one is used for 'back', this should be set to 'Bottom Left'. For a Symbian-style device this should be set to 'Bottom Right'. Calling s3eDeviceGetInt() with S3E_DEVICE_BACK_SOFTKEY_POSITION as the property parameter will return one of s3eDeviceSoftKeyPosition that matches the position selected here.
  • Reported Advance Softkey Position: This option allows you to set the position relative to the screen at which the 'advance' softkey is located. To emulate a BREW-style device where the softkeys are placed below the screen and the left one is used for 'back', this should be set to 'Bottom Right'. For a Symbian-style device this should be set to 'Bottom Left'. Calling s3eDeviceGetInt() with S3E_DEVICE_BACK_SOFTKEY_POSITION as the property parameter will return one of s3eDeviceSoftKeyPosition that matches the position selected here.


Airplay SDK: File Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > File Configuration >

File Configuration

Clicking 'Configuration > File...' displays the 'File Configuration' dialog as illustrated below. This dialog allows you to configure filesystem settings.

The Device Configuration options are as follows:

  • Use separate directories for rom and ram drives: This option allows you to specify whether you would like to create and use separate folders for rom and ram - see Using Separate Directories for ROM and RAM Drives. Selecting the checkbox in this dialog configures the application to use separate directories.
  • Limit Storage Size: This option allows you to limit the amount of storage space available to the application. If checked, available space is limited to the value set in the Total Storage Size input. If unchecked, storage is not limited by Airplay.
  • Total Storage Size (MB): This option allows you to set the total storage space available to the application in megabytes. Limit Storage Size must be set for this to take effect.

Using Separate Directories for ROM and RAM Drives

If this option is set, then s3e will map the 'rom://' and the 'ram://' drives to different locations. The 'rom://' drive will be mapped to the applications 'data' directory (by default there exists a directory named 'data' next to the .mkb file), and the 'ram://' drive will be mapped to a folder of the same name but with '-ram' appended on the end.

When the application opens a file for reading without specifying a drive, they will be opened from either the 'ram://' or 'rom://' drives. When the application opens a file for writing, it is only opened from the 'ram://' drive. This is the default configuration.

If this option is unset, then s3e will map the 'ram://' drive to the application's data directory and the 'rom://' drive will be unmapped.

All file operations without an explicit drive specified will go via the 'ram://' drive. This is the common situation when running on device, however it is not the default because it is easy for the application to make assumptions under this configuration that will break under a separated rom/ram situation.

Note: Changing these options requires a restart of the application.


Airplay SDK: GL Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > GL Configuration >

GL Configuration

Clicking 'Configuration > GL...' displays the 'GLES API Configuration' dialog as illustrated below. This dialog allows you to select the GLES API that is supported by the device that you are emulating.

GLES API Supported

The S3E API available to the application includes a superset of all versions of the EGL/GLES APIs, and this option controls which GLES APIs are active.

Calling an inactive GLES function will cause an assertion message to be displayed.

This option also controls the return value of s3eGLGetInt(S3E_GL_VERSION) and s3eGLGetInt(S3E_EGL_VERSION). The options available are:

  • None: s3eGLGetInt(S3E_GL_VERSION) and s3eGLGetInt(S3E_EGL_VERSION) will return 0. Any call to a GLES function will cause an assertion.
  • GLES Common-Lite Profile v1.0: The functions available in the GLES 1.0 common-lite (non-floating point) profile are available, all others will cause an assertion. s3eGLGetInt(S3E_GL_VERSION) will return 0x0100, and s3eGLGetInt(S3E_EGL_VERSION) will return 0x0100.
  • GLES Common-Lite Profile v1.1: The functions available in the GLES 1.1 common-lite (non-floating point) profile are available, all others will cause an assertion. s3eGLGetInt(S3E_GL_VERSION) will return 0x0101, and s3eGLGetInt(S3E_EGL_VERSION) will return 0x0101.
  • GLES Common Profile v1.0: The functions available in the GLES 1.0 common (floating point) profile are available, all others will assert. s3eGLGetInt(S3E_GL_VERSION) will return 0x0100, and s3eGLGetInt(S3E_EGL_VERSION) will return 0x0100.
  • GLES Common Profile v1.1: The functions available in the GLES 1.1 common (floating point) profile are available, all others will assert. s3eGLGetInt(S3E_GL_VERSION) will return 0x0101, and s3eGLGetInt(S3E_EGL_VERSION) will return 0x0101.
  • GLES Common Profile v2.0: The functions available in the GLES 2.0 profile are available, all others will assert. s3eGLGetInt(S3E_GL_VERSION) will return 0x0200, and s3eGLGetInt(S3E_EGL_VERSION) will return 0x0200.

Note: Note that GLES2.0 applications are not compatible with GLES1.x and vice versa; this option must be set correctly for the application.

Changing the available GL API requires a restart of the application.


Airplay SDK: Keyboard Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Keyboard Configuration >

Keyboard Configuration

Clicking 'Configuration > Keyboard...' displays the 'Keyboard Configuration' dialog as illustrated below. This dialog allows you to select which types of keys the device simulator supports in order to more accurately emulate a device which supports only a subset of the available S3E keys.

This dialog displays the following options:

  • Reported keyboard has numeric keypad keys...: If enabled, s3eKeyboardGetInt(S3E_KEYBOARD_HAS_NUMPAD) will return 1. This indicates that the device supports keys s3eKey0 through to s3eKey9. The simulator will still detect key-presses in this range - for example using s3eKeyboardAnyKey() - even if this option is disabled.
  • Reported keyboard has alphabetic keys...: If enabled, s3eKeyboardGetInt(S3E_KEYBOARD_HAS_ALPHA) will return 1. This indicates that the device supports keys s3eKeyA through to s3eKeyZ. The simulator will still detect key-presses in this range - for example using s3eKeyboardAnyKey() - even if this option is disabled.
  • Reported keyboard has direction keys...: If enabled, s3eKeyboardGetInt(S3E_KEYBOARD_HAS_DIRECTION) will return 1. This indicates that the device supports keys s3eKeyUp, s3eKeyDown, etc. The simulator will still detect key-presses in this range - for example using s3eKeyboardAnyKey() - even if this option is disabled.
  • Report number pad orientation: s3eKeyboardGetInt(S3E_KEYBOARD_NUMPAD_ORIENTATION) will return the s3eKeyboardNumpadOrientation value corresponding to the value selected in the drop-down box.


Airplay SDK: License Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > License Configuration >

License Configuration

Clicking 'Configuration > License...' displays the 'License Configuration' dialog as illustrated below. This dialog allows you to enter license information, thus enabling you to test an application on a device possessing a license of a specific type. For example, an application may be written so as to behave differently on a device that has a DEMO license, and setting the loader to have a DEMO license will allow you to test that application's response.

This dialog displays four options:

  • Reported License Status: This option allows you to set the license status returned by s3eLicenseGetInt(S3E_LICENSE_STATUS). The following types are available:
    • EXPIRED
    • DEMO
    • USECOUNT
    • EXPIRYDATE
    • EXPIRYMINSUSE
    • PURCHASE
    • SUBSRIPTION
    • UPGRADE
    • NONCOMMERCIAL
  • Reported Uses Remaining: This option allows you to set the number of uses remaining. This sets the integer returned by s3eLicenseGetInt(S3E_LICENSE_USES_LEFT). Note that this value will not change once set - the Simulator will not decrement this value when the application is run.
  • Reported Minutes Remaining: This option allows you to set the number of uses remaining. This sets the integer returned by s3eLicenseGetInt(S3E_LICENSE_MINS_LEFT). Note that this value will not change once set - the Simulator will not decrease this value over time.
  • Reported Expiry Date: This option allows you to set the expiry date for the license selected. This sets the date returned by s3eLicenseGetInt(S3E_LICENSE_EXPIRY_DATE).
Note that the Simulator does not attempt to simulate a license system - the values returned by s3eLicenseGetInt(xxx) are always those set in this dialog.


Airplay SDK: Location Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Location Configuration >

Location Configuration

Clicking 'Configuration > Location...' displays the 'Location Configuration' dialog as illustrated below. This dialog allows you to enter the current location that the s3eLocation API will return.

This dialog allows you to edit the following options:

  • Reported latitude: This allows you to set the current latitude as returned by s3eLocationGet(), in degrees, minutes and seconds.
  • Reported longitude: This allows you to set the current longitude as returned by s3eLocationGet(), in degrees, minutes and seconds.
  • Reported latitude (numeric value): This allows you to set the current latitude as returned by s3eLocationGet(), in degrees only.
  • Reported longitude (numeric value): This allows you to set the current longitude as returned by s3eLocationGet(), in degrees only.
  • Reported altitude: This allows you to set the current altitude (in metres) as returned by s3eLocationGet()
  • Reported horizontal accuracy: This allows you to set the horizontal accuracy (in metres) returned by s3eLocationGet(). It does not affect the latitude/longitude position returned by s3eLocationGet().
  • Reported vertical accuracy: This allows you to set the vertical accuracy (in metres) returned by s3eLocationGet(). It does not affect the altitude returned by s3eLocationGet().

    • (c) 2009 Ideaworks Labs. All rights reserved.


Airplay SDK: Memory Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Memory Configuration >

Memory Configuration

Clicking 'Configuration > Memory...' displays the 'Memory Configuration' dialog. This dialog allows you to specify whether memory allocated to the application and subsequently freed is set with "Memory Poison", a bit pattern. Selecting the checkbox contained in the dialog causes all allocated and freed memory to be set with a bit pattern.

This dialog displays four options:

  • Reported Uses Remaining: If memory poison is enabled, memory blocks are set to the values specified below when the corresponding action takes place. Memory poisoning increases the chance of detecting errors due to reading uninitialised or freed memory.
  • Byte value to set on init: If memory poison is enabled, then every byte in the whole heap is set to this value at startup.
  • Byte value to set on allocate: If memory poison is enabled, any newly allocated memory block from s3eMallocBase or s3eReallocBase (or from s3eMalloc/s3eRealloc if no user memory manager is installed) will be initialised to this value.
  • Byte value to set on free: If memory poison is enabled, any newly freed memory block will be set to this value.


Airplay SDK: Pointer Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Pointer Configuration >

Pointer Configuration

Clicking 'Configuration > Pointer...' displays the 'Pointer Configuration' dialog as illustrated below. This dialog allows you to select which pointer properties should be returned to the application, allowing you to simulate various mouse and touch-screen configurations.

The Pointer Configuration options are as follows:

  • Enable pointer: Enables or disables the pointer device. When the pointer device is disabled, s3ePointer API functions will fail with error S3E_POINTER_ERR_UNAVAIL.
  • Reported pointer type: Controls the value returned by s3ePointerGetInt(S3E_POINTER_TYPE). This can be set to INVALID, MOUSE or STYLUS, corresponding to the S3E_POINTER_TYPE_INVALID, S3E_POINTER_TYPE_MOUSE and S3E_POINTER_TYPE_SYLUS return codes.
  • Reported stylus rype: Controls the value returned by s3ePointerGetInt(S3E_POINTER_STYLUS_TYPE). This can be set to INVALID, STYLUS or FINGER, corresponding to the S3E_SYLUS_TYPE_INVALID, S3E_SYLUS_TYPE_SYLUS and S3E_SYLUS_TYPE_FINGER return codes.
  • Report multi-touch available: If this is checked, s3ePointerGetInt(S3E_POINTER_MULTI_TOUCH_AVAILABLE) will return 1 and S3E_POINTER_TOUCH_EVENT/S3E_POINTER_TOUCH_MOTION_EVENT will be sent for left mouse button clicks (using touch id 1) in addition to the normal S3E_POINTER_BUTTON_EVENT/S3E_POINTER_MOTION_EVENT events.
  • Enable multi-touch simulation mode: If this is checked, the user can simulate multiple simultaneous touchscreen presses. Click the middle mouse button on the Airplay window to create a permanent touch, simulating pressing (and holding) down on a device's screen. A coloured circle will be displayed representing the touch. Up to 5 touches can be created in this way. Click and drag a touch with the middle mouse button to move it. Click without dragging on a touch to remove (release) it. The left mouse button functions as a temporary touch, pressing when the mouse button is down and releasing when it is up.


Airplay SDK: Sound Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Sound Configuration >

Sound Configuration

Clicking 'Configuration > Sound...' displays the 'Sound Configuration' dialog as illustrated below.

This dialog displays five options:

  • Enable Sound Device: This option enables sound. If this is checked, sound will be supported, s3eSoundGetInt(S3E_SOUND_AVAILABLE) will return 1 and the s3eSound API will function correctly. If this is unchecked, sound will not be supported, s3eSoundGetInt(S3E_SOUND_AVAILABLE) will return 0 and the s3eSound functions will fail.
  • Enable Stereo Sound: This option enables stereo sound. If this is checked, stereo sound will be supported and s3eSoundGetInt(S3E_SOUND_STEREO_ENABLED) will return 1. If this is unchecked, stereo sound will not be supported and s3eSoundGetInt(S3E_SOUND_STEREO_ENABLED) will return 0.
  • Sample Sound Rate: This option allows you to set sound output frequency. This option only affects the final output rate for the sound device. This will not normally affect the S3E application. This option is equivalent to the sound property S3E_SOUND_OUTPUT_FREQ. This determines the frequency of the sound output channel. S3E mixes the individual sound channels into a single output channel that is played at this rate. Each sound channel has its own playback frequency and when it is mixed, S3E performs the appropriate rate conversion so that each channel is heard at its playback frequency. Therefore the frequency of the output channel does not normally affect the user. However, if the sound channel callback S3E_SOUND_GENERATE_AUDIO is registered, then the user is expected to perform the mixing and rate conversion from input channel to output channel manually. The user needs to be aware of the output channels frequency, which is returned by s3eSoundGetInt(S3E_SOUND_OUTPUT_FREQ). The value returned by s3eSoundGetInt(S3E_SOUND_OUTPUT_FREQ) will be the same as the value set using the Sound Configuration dialog.
  • Sound Latency: This option allows you to set the sound latency in ms.
  • Default Volume: This option allows you to set the default volume in the range 0-256. This is the volume returned by s3eSoundGetInt(S3E_SOUND_VOLUME_DEFAULT). This is also the volume that the sound device is set to when the application starts up.


Airplay SDK: Socket Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Socket Configuration >

Socket Configuration

Clicking 'Configuration > Socket...' displays the 'Socket Configuration' dialog. This dialog allows you specify names and addresses for simulating networking functionality.

This dialog displays three options:

  • Reported host name: This option set the string returned when calling s3eSocketGetString() with the S3E_SOCKET_DOMAINNAME property.
  • Reported HTTP proxy address: This option set the string returned when calling s3eSocketGetString() with the S3E_SOCKET_HTTP_PROXY property.
  • Simulated DNS Loopup Delay: This option allows you to set a minimum duration for DNS lookups. When performing a DNS lookup, it will take at least the amount of time specified by this option for the lookup process to complete.


Airplay SDK: Surface Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Surface Configuration >

Surface Configuration

Clicking 'Configuration > Surface...' displays the 'Surface Configuration' dialog as illustrated below.

This dialog displays the following options:

Basic

  • Predefined Resolution: This option allows you to select a resolution for the Simulator to use from a drop-down list. The values available match those found on a wide range of popular devices.
  • Width: This option allows you to set the width of the display surface which is presented within the application window. This corresponds to the value returned by s3eSurfaceGetInt(S3E_SURFACE_DEVICE_WIDTH). It will also affect the value returned by s3eSurfaceGetInt(S3E_SURFACE_WIDTH) and/or s3eSurfaceGetInt(S3E_SURFACE_HEIGHT) depending on surface orientation. This value controls the width of the display surface presented in the application window. Changing this value will cause a surface resize event (S3E_SURFACE_SCREENSIZE) to be sent to the application.
  • Height: This option allows you to set the height of the display surface which is presented within the application window. This corresponds to the value returned by s3eSurfaceGetInt(S3E_SURFACE_DEVICE_HEIGHT). It will also affect the value returned by s3eSurfaceGetInt(S3E_SURFACE_HEIGHT) and/or s3eSurfaceGetInt(S3E_SURFACE_HEIGHT) depending on surface orientation. This value controls the height of the display surface presented in the application window. Changing this value will cause a surface resize event (S3E_SURFACE_SCREENSIZE) to be sent to the application.
  • Backlight Timeout: This option allows the simulation of a device with a backlight that fades out after a certain amount of time has elapsed. After the given amount of time in milliseconds has elapsed since the user last performed an input action (for example a key-press), the Simulator screen window will fade to darker tones. Setting this to 0 results in the screen always staying at full brightness.

Advanced

  • Surface Orientation: This controls the rotation of the user surface, returned by s3eSurfacePtr(), when transferred to the device surface, which is displayed on-screen. This simulates the situation where such a rotation is required on a device to achieve a 'normal' upright display. However in the Simulator, setting this to any other value than Rot0 will cause the surface to be displayed rotated. This has four possible settings: Rot0, Rot90, Rot180 and Rot270 Note that if the rotation is set to Rot90 or Rot270, then the user surface's width and height will be swapped.

    This corresponds to the value returned by s3eSurfaceGetInt(S3E_SURFACE_DEVICE_BLIT_DIRECTION)Changing this value will generate a surface resize event (S3E_SURFACE_SCREENSIZE) and can be used to simulate a device changing between 'landscape' mode and 'portrait' mode (this happens, for example, when using the Nokia N-95). This option allows you to set the degree of rotation required by the application. This has four possible settings:

    • Rot0: The surface is rotated by 0 degrees.
    • Rot90: The surface is rotated by 90 degrees.
    • Rot180: The surface is rotated by 180 degrees.
    • Rot270: The surface is rotated by 270 degrees.
  • Device Pixel Format: This option allows you to set the pixel format that will be used by the surface. This determines the pixel format of the simulated native device surface. Note that by default the surface returned by s3eSurfacePtr() is a RGB565 surface. This value only affects the format of the simulated, native device surface. This surface is only visible to the user if a callback is registered for S3E_SURFACE_COPYUP where the user can override the user-to-device surface copy. This corresponds to the value returned by s3eSurfaceGetInt(S3E_SURFACE_DEVICE_PIXEL_TYPE). This has possible options:
    • RGB444
    • RGB555
    • RGB565
    • RGB666
    • RGB888
    • BGR444
    • BGR555
    • BGR565
    • BGR666
    • BGR888
  • Device Surface Pitch: This sets the distance in bytes from one horizontal surface line to the next. The pitch must be greater than or equal to the width of the surface multiplied by the pixel byte size. Certain devices allow for a number of extra bytes for each line. A pitch of zero entered in this field means the default base pitch is observed. This determines the pitch of the simulated native device surface (the number of bytes between one line of raster data and the next). Note that by default the pitch of the surface returned by s3eSurfacePtr() is the surface's width multiplied by 2. This value only affects the pitch of the simulated native device surface, which is only accessible to the user if a callback is registered for S3E_SURFACE_COPYUP where the user can override the user to device surface copy. This corresponds to the value returned by s3eSurfaceGetInt(S3E_SURFACE_DEVICE_PITCH)
  • Double Buffer: Selecting this option makes sure there is always a copy taking place between the device buffer and the surface returned by the s3eSurface pointer. If the native device surface and the S3E user surface have identical properties then the pointer returned by s3eSurfacePtr() will normally be a pointer to the native device surface, and s3eSurfaceShow() will not perform a copy operation. However on some devices this can cause problems, and setting the 'Double Buffer' option simulates the solution that S3E employs, which is to ensure that the pointer returned by s3eSurfacePtr() is never a direct pointer to the native device surface, and that s3eSurfaceShow() always performs a copy operation. Selecting this option can eliminate surface update issues.
  • 16-bit Unalign result of s3eSurfacePointer(): Forces the data returned by s3eSurfacePointer to be aligned to a 2 byte rather than 4 byte boundary. This option is included since, although the data may often be aligned to a 4-byte boundary and it is easier to write code that assumes this, it will not always be the case. It is a good idea to enforce this while testing cross-platform surface code.
  • Enable s3eSurfacePtr() rotation: If enabled, s3eSurfacePtr() will return a pointer to different area of memory for each possible surface orientation. This will cause the application to fail if the programmer has assumed the surface pointer will remain constant. It is recommended to enable this option.


Airplay SDK: Vibra Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Vibra Configuration >

Vibra Configuration

Clicking 'Preferences > Vibra...' displays the 'Vibra Preferences' dialog as illustrated below.

  • Enable Vibra: Setting this option enables vibra simulation. s3eVibraGetInt(S3E_VIBRA_AVAILABLE) will return 1, and a call to s3eVibraVibrate is simulated by shaking the application window. If this option is unset, s3eVibraGetInt(S3E_VIBRA_AVAILABLE) will return 0 and the vibra API will fail with error S3E_VIBRA_ERR_UNAVAIL.


Airplay SDK: Video Configuration

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Video Configuration >

Video Configuration

Clicking 'Preferences > Video...' displays the 'Video Preferences' dialog as illustrated below. This dialog allows you to select the video codecs that are available to your application. This dialog controls which codecs are available for playing videos via s3eVideoPlay.

The possible options are:

  • MPEG4: If this is set, MPEG4 videos can be played via s3eVideoPlay or s3eVideoPlayFromBuffer. The codecs enumerants S3E_VIDEO_CODEC_MPEG4, S3E_VIDEO_CODEC_MPEG4_VIDEO_MPEG4, S3E_VIDEO_CODEC_MPEG4_VIDEO_H264 and S3E_VIDEO_CODEC_MPEG4_AUDIO_AAC will be reported as supported in a call to s3eVideoIsCodecSupported. Otherwise the MPEG4 codecs will be reported as unsupported and playing MPEG4 videos via s3eVideoPlay will fail.
  • 3GPP: If this is set, 3GPP videos can be played via s3eVideoPlay or s3eVideoPlayFromBuffer. The codecs enumerants S3E_VIDEO_CODEC_3GPP, S3E_VIDEO_CODEC_3GPP_VIDEO_H263, S3E_VIDEO_CODEC_3GPP_VIDEO_H264, S3E_VIDEO_CODEC_3GPP_AUDIO_AAC and S3E_VIDEO_CODEC_3GPP_AUDIO_AMR will be reported as supported in a call to s3eVideoIsCodecSupported. Otherwise the 3GPP codecs will be reported as unsupported and playing 3GPP videos via s3eVideoPlay will fail.
  • JPEG: If this is set, JPEG images can be played via s3eVideoPlay or s3eVideoPlayFromBuffer. s3eVideoIsCodecSupported(S3E_VIDEO_CODEC_JPEG) will return true, and passing a jpeg file to s3eVideoPlay or s3eVideoPlayFromBuffer will display the jpeg on the screen. Otherwise s3eVideoIsCodecSupported(S3E_VIDEO_CODEC_JPEG) will return false and playing JPEG files will fail.
  • Default Volume: This option allows you to set the volume that will be returned by s3eVideoGetInt(S3E_VIDEO_VOLUME_DEFAULT). This is also the volume that the video device is set to when the application starts up.


Airplay SDK: All Settings

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > All Settings >

All Settings

Clicking Configuration > All Settings allows you to see and set all the options discussed in this section through one dialog.


Airplay SDK: Reset to Default

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Configuration Menu Option > Reset to Default >

Reset to Default

Clicking Configuration > Reset to Default resets any changes you may have made.


Airplay SDK: Preferences Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Preferences Menu Option >

Preferences Menu Option

The Preferences menu allows you to set the application to display in the way you would like and the keys to map to the keys you prefer to use.

The following preference options are available:

  • Display Preferences
  • Keyboard Preferences


Airplay SDK: Display Preferences

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Preferences Menu Option > Display Preferences >

Display Preferences

Clicking 'Preferences > Display...' displays the 'Display Preferences' dialog as illustrated below.

This dialog displays the following:

  • Initial Window X position: This option allows you to set the initial x (horizontal) position of the display window. A value of -1 will cause the window to be displayed at its default x position.
  • Initial Window Y position: This option allows you to set the initial y (vertical) position of the display window. A value of -1 will cause the window to be displayed at its default y position.
  • Display Width Scale: This option allows you to set the width of the display window. This specifies the horizontal zoom factor for displaying the device surface on screen. A setting of 1.0 will cause the device surface to be displayed unscaled. A setting of 2.0 will cause the device surface to be displayed at exactly double width. This setting is also controlled by resizing the application window
  • Display Height Scale: This option allows you to set the height of the display window. This specifies the vertical zoom factor for displaying the device surface on screen. A setting of 1.0 will cause the device surface to be displayed unscaled. A setting of 2.0 will cause the device surface to be displayed at exactly double height. This setting is also controlled by resizing the application window
  • Use Bilinear Filter: Selecting this option will turn on bilinear filtering. This option is only available if 'Use DirectX' is set. If a scale factor other than 1.0 has been set for Display Width Scale or Display Height Scale, then filtering will be used to display the device surface. This has the result of a better looking display, at the expense of being able to see individual pixels easily.
  • Use DirectX: Selecting this option displays the application on screen using the DirectX API. Some graphics cards and multi monitor displays have problems with using DirectX to display the device surface, so this is disabled by default. Enabling this option will cause DirectX to be used to display the device surface, which in turn allows the possibility of using a filtered copy for the display.
  • Simulate Backlight: Selecting this option will cause the application to simulate having a variable-brightness backlight as can be found on the majority of handsets. After a period of inactivity the surface area will appear to dim by lowering the brightness of the pixels. Upon any user input or calls to s3eDeviceBacklightOn(), the surface will return to its full brightness. The length of the inactivity timeout can be specified using the Backlight Timeout setting of the Surface Configuration menu.
  • Display iPhone skin: Selecting this option will display a visual skin arond the device surface to mimic the look of the iPhone.

Resizing of the Display

When resizing the window you can hold the Shift button to maintain the surface aspect ratio, and the Control button to ensure the displayed surface width/height is a multiple of the actual surface width/height. Holding Shift and Control together whilst resizing will ensure your window is a 1x, 2x, 3x, etc. display of the actual surface.


Airplay SDK: Keyboard Preferences

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Preferences Menu Option > Keyboard Preferences >

Keyboard Preferences

Clicking 'Preferences > Keyboard...' displays the 'Keyboard Preferences' dialog as illustrated below.

  • Preferences for mapping PC keyboard keys to s3eKeys: This dialog allows you to set your preferred keymap for each s3eKey that is used in the application.
  • Use DirectInput in exclusive mode: Selecting this option will cause DirectInput to be used in exclusive mode. If enabled, s3eKeyboardGetChar() will not return any characters.


Airplay SDK: Events Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Events Menu Option >

Events Menu Option

The Events menu has two sub options:

  • Simulate Suspend: This option allows you to simulate a suspend in the application without actually closing the application.
  • Simulate Resume: This option allows you to simulate the application resuming after a suspend action.


Airplay SDK: Metrics Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Metrics Menu Option >

Metrics Menu Option

Clicking 'Metrics > Display Metrics...' displays the Metrics Display dialog. This dialog contains a tree structure in the left pane listing all metrics elements. Expanding and selecting any of these elements will display its metrics information in the right-hand dialog pane.

Two main sets of metrics are displayed:

  • Airplay System Metrics
  • Airplay Studio Metrics


Airplay SDK: Airplay System Metrics

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Metrics Menu Option > Airplay System Metrics >

Airplay System Metrics

The following metrics information is displayed under this heading:

  • File: Selecting this node in the tree menu will display the following metrics:
    • ROM file system location: This is the position of all read only files.
    • RAM file system location: This is the position of all files which can be read and written to.

      • Note: A description of how both the ROM and RAM file systems are used can be seen in the section S3E Drives of the "S3E File Overview".

    • Num Files Open: This indicates the number of files that are currently open.

      • Upon expanding the File node the following metric is displayed:

    • All Opened Files: This displays all files that have been opened as part of this application.
  • Configuration: This displays an assortment of configuration options, all of which can be set using the Configuration menu option.
  • Memory: Displays metrics for each memory heap in use, including:
    • Heap size: This is the total size of the memory heap.
    • Heap free: This is the total amount of free memory in the heap.
    • Heap flags: This displays the flags set on the heap. (see S3E Memory Overview for details)
    • Heap allocated: This is the amount of memory that has been allocated from that heap.
    • Heap LFB (Largest Free Block): This is the largest free block available within the heap.
  • API Calls (last frame): Lists the number of calls per frame of all noteworthy functions.
  • API Calls (totals): Lists the total number of calls since starting the application of all noteworthy functions.
  • Sound: This tree item displays metrics on all available sound channels. Clicking on the Sound node will reveal the settings common to all channels:
    • S3E_SOUND_VOLUME_DEFAULT: The default volume. This setting is device dependent. When running the application using the Windows Simulator the default volume can be changed by clicking 'Configuration > Sound', and then in the Sound Configuration dialog by entering the desired value in the 'Default Volume' field. (see S3E_SOUND_VOLUME_DEFAULT for details)
    • S3E_SOUND_VOLUME: This is the current sound volume. (see S3E_SOUND_VOLUME for details)
    • S3E_SOUND_USED_CHANNELS: This reveals which channels are in use. (see S3E_SOUND_USED_CHANNELS for details)
    • S3E_SOUND_OUTPUT_FREQ: When running the application using the Windows Simulator this value can be changed by clicking 'Configuration > Sound', and editing the value in the 'Sample Sound Rate' drop-down menu. (see S3E_SOUND_OUTPUT_FREQ for details)
    • S3E_SOUND_NUM_CHANNELS: This is the number of channels available to the user. (see S3E_SOUND_NUM_CHANNELS for details).
    • S3E_SOUND_DEFAULT_FREQ: Default frequency, in Hz, at which all channels will play. (see S3E_SOUND_DEFAULT_FREQ for details)
    • S3E_SOUND_AVAILABLE: This is 1 if sound is available. When running the application using the Windows Simulator this value can be changed by clicking 'Configuration > Sound', and selecting the 'Enable Sound Device' check box. (see S3E_SOUND_AVAILABLE for details).

      • Note: When running the application using the Windows Simulator the values for each of the above settings can be changed by clicking 'Configuration > Sound', and editing the values in the 'Sound Configuration' dialog.

      The following system variable information is displayed for each channel:

    • S3E_CHANNEL_VOLUME: This displays the channel volume in a range of 0-256. (see S3E_CHANNEL_VOLUME for details)
    • S3E_CHANNEL_USERVAR: This displays any sound channel user variable. (see S3E_CHANNEL_USERVAR. for details)
    • S3E_CHANNEL_STATUS: This displays 1 if the channel is playing, 0 otherwise. (see S3E_CHANNEL_STATUS for details)
    • S3E_CHANNEL_RATE: This displays the sound channel frequency in Hz. (see S3E_CHANNEL_RATE for details)
    • S3E_CHANNEL_PITCH: This displays the sound channel pitch. (see S3E_CHANNEL_PITCH for details)
    • S3E_CHANNEL_PAUSED: This displays 1 if the channel is paused, 0 otherwise. (see S3E_CHANNEL_PAUSED for more details)


Airplay SDK: Airplay Studio Metrics

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Metrics Menu Option > Airplay Studio Metrics >

Airplay Studio Metrics

This set of metrics will only be displayed if running an application that makes use of Airplay Studio functionality.

The following metrics information is displayed under this heading:

  • MemBuckets: This tree item displays metrics on the amount of memory used by the applications memory buckets. The metrics on each memory bucket contains the following information:
    • Used: The amount of memory used by the bucket.
    • Size: The total amount of memory that this bucket can use.
    • Malloc Calls: The amount of calls to allocate memory from this bucket.
    • Largest Free Block: The largest available block within this bucket.
    • Free Calls: The amount of calls to free memory allocated from this bucket.
    • Free: The total amount of free space within this bucket
  • IwResManager: This tree item provides you with a list of the loaded groups and the objects that make up those groups. Clicking on any of the groups listed will display its constituent objects and their size in bytes in the right-hand pane. One of the nodes contained under 'IwResManager' is called 'Total Size'. This lists each of the major object types (CWorld, CIwTexture, CIwResGroup, CIwModel, CIwMaterial) and the total number of bytes used by each of these object types.
  • IwGx: This tree item provides details on all renderable items, such as quads, polys, verts and sprites.


Airplay SDK: Help Menu Option

Airplay SDK > Airplay Programmer Tools Reference > Windows Simulator > Help Menu Option >

Help Menu Option

The Help menu has two sub options:

  • Device Simulator Help: This option launches the Airplay SDK Reference help document at the Windows Simulator Options chapter.
  • SDK Help: This option launches the Airplay SDK Reference help document at the title page.


Airplay SDK: dzip Tool and Compressed Derbh Archives

Airplay SDK > Airplay Programmer Tools Reference > dzip Tool and Compressed Derbh Archives >

dzip Tool and Compressed Derbh Archives

The dzip command-line archiving tool allows you to create compressed Derbh archives (DZ files). These archives are similar to ZIP files, but can use LZMA or proprietary dzip compression to achieve a higher compression ratio. They also support additional features such a splitting files between multiple archives.

Derbh archives are used within Airplay applications using the Derbh API. This is done via transparent integration with the file system so few changes to application code are needed to use a compressed archive. The data is decompressed from the archive as the application requests it so there is low memory/storage overhead to using derbh archives.

  • Creating a Derbh Archive
  • dzip Command Line Options
  • dzip Configuration File Settings
  • dzip Archive Creation Example


Airplay SDK: Creating a Derbh Archive

Airplay SDK > Airplay Programmer Tools Reference > dzip Tool and Compressed Derbh Archives > Creating a Derbh Archive >

Creating a Derbh Archive

To create a Derbh archive, the user must do the following:

  • Construct a text file (DCL file) describing the pathnames to input files, the pathname of the output archive file, compression settings, etc.
  • Run the dzip executable using the command-line options and pass it the name of the configuration file.

For more information on the command-line options available, see the dzip Command Line Options page.

For more information on the configuration file settings, see the dzip Configuration File Settings page.

For an example of creating an archive, see dzip Archive Creation Example page.


Airplay SDK: dzip Command Line Options

Airplay SDK > Airplay Programmer Tools Reference > dzip Tool and Compressed Derbh Archives > dzip Command Line Options >

dzip Command Line Options

The following section describes the available dzip.exe command-line options. The options should be entered in the form:

dzip.exe <options> <config_file>

where are zero or more of:

  • --waitatend (-w) : pause for a keypress before exiting.
  • --help (-h) : print this message then exit.
  • --license (-L) : print the license message then exit.
  • --version (-V) : print the version information then exit.
  • --quiet (-q) : no output.
  • --verbose (-v) : extended output.
  • --command (-c) "<command>" : extra commands (in config_file file format).
  • --decompress (-d) : Extract compressed dzip file to a subdirectory with the same name as the archive.
  • --list (-l) : List compressed dzip file contents
  • --dir (-D) <dir> : Add base directory to locate input files. Similar to the basedir configuration file option.
  • --align (-A) <num> : Align each dz-compressed file to <num> byte boundary in the archive. This may improve read times.

dzip can also be used without a configuration file:

dzip.exe <options> [-a|--archive <archive_file>] [<files>|<file_options>]*

where <options> are as above and <file_options> are one or more of

  • --type (-t) <type> : Compression type: lzma, dz, zlib, zero or copy
  • --start (-s) <num>[%] : Include file from specified offset (absolute offset or percentage) onwards
  • --end (-e) <num>[%] : Include file up to specified offset (absolute offset or percentage)


Airplay SDK: dzip Archive Creation Example

Airplay SDK > Airplay Programmer Tools Reference > dzip Tool and Compressed Derbh Archives > dzip Archive Creation Example >

dzip Archive Creation Example

The following is an example of a simple DCL configuration file:

archive ..\archive\archive1.dz
basedir ..\files\
file testTexture.bmp 0 lzma
file TextFile.txt 0 lzma
file car_crash.mp4 0 lzma

The following sections examine this line-by-line.

Setting the Archive Name

archive ..\archive\archive1.dz

This specifies the name of the output archive file. The pathname is relative to the location of the DCL configuration file.

Setting the Base Directory

basedir ..\files\

This specifies a base folder name to read input files from. Multiple “basedir” folders are allowed.

Input Files

file testTexture.bmp 0 lzma
file TextFile.txt 0 lzma
file car_crash.mp4 0 lzma

This specifies the input files to add to the archive.

All “basedir” folders are searched for the specified files. If a file cannot be found on any “basedir” path, dzip will display an error. Each input file must be followed by an “archive ID”, and a “flags” field. The “archive ID” is usually “0”, unless the DCL file is specifying multiple DZ archives. The “flags” field is usually the required compression codec. This is “dz” for Derbh compression.

For information on other compression codecs and flags, see Derbh Configuration File Settings, on page 3-6.

Archiving Process

Let’s assume we have the following file structure:

<archive>

<derbh_scripts>
archive.dcl

<files>
testTexture.bmp
TextFile.txt
car_crash.mp4

  • In a command prompt, navigate to <derbh_scripts>.
  • Run the dzip tool from within the installed SDK tools folder, as follows:

    • "<installed SDK folder>\tools\dzip\dzip" archive.dcl

    The dzip tool reads the “archive.dcl” configuration file, compresses the input files, and writes “archive1.dz” to the archive folder.

Within the application code, the archive can be “attached” to the S3E file system, and then files can be read using the standard S3E file API. See the Derbh API for more information.


Airplay SDK: dzip Configuration File Settings

Airplay SDK > Airplay Programmer Tools Reference > dzip Tool and Compressed Derbh Archives > dzip Configuration File Settings >

dzip Configuration File Settings

dzip configuration files (DCL files), are used to describe the contents and format of Derbh Archives (DZ files). A DCL file can describe multiple Derbh archives.

Derbh Configuration Format

The DCL file allows you to set the following options:

  • archive <archive_name>

    • This sets the file to export to (archive_name is relative to the DCL file). The first archive file specified will contain the file/directory information.

  • basedir <dir>

    • This sets a base directory for input files. Multiple directories can be specified.

  • master <filename>

    • Inherit settings from specified base DCL file. This facilitates creating differing archives that have a shared set of common files.

  • file <path> <archive> <flags>

    • This specifies an input file. "archive" is an integer representing the archive file in which the file is placed (normally 0 - the first archive specified), and "flags" is one or more of:

    • lzma: use lzma compression (recommended for best compression ratio and good decompression speed).
    • dz: use dz compression. (good compression ratio, fair decompression speed. Allows the use of common-buffer compression)
    • zlib: use zlib compression. (lower compression ratio, very good decompression speed).
    • zero: zero out the data.
    • copy: copy with no compression. (best read speed)
    • from <num>[%]: Include file only from offset <num>(optionally as a percentage) onwards.
    • to <num>[%]: Include file only up to offset <num>(optionally as a percentage).

    Using 'from' and 'to' is useful to cause a split in the archive compression. For example specifying

    file mydata.dat 0 lzma to 10000

    file mydata.dat 0 lzma from 10000

    causes mydata.dat to be compressed in two separate 'chunks', one for the first 10000 bytes of the file, one for the rest. The result of this is that seeking to the second chunk - at position 10000 in the file - is fast. Without this seeking to position 10000 would cause the first 10000 bytes of mydata.dat to be decompressed and thrown away, as its not possible to randomly seek compressed streams. If a lot of seeking is done by the application when using the archive, it may be wise to consider splitting files in this manner to improve performance.

  • options dz

    • This specifies advanced options for the dz encoder (used on files marked with 'dz' compression type). This should be followed by one or more of the following on subsequent lines:

    • use_combuf [1|0]

      • Adding use_combuf 1 will enable common-buffer compression of all dz-encoded data in the archive. Common-buffer compression searches for large chunks of duplicate data across all archive files and stores them seperately, which can allow for large gains in compression ratio under certain circumstances. Compressing with common-buffer compression on can take a long time with large data sets.

    • WinSize [0...24]

      • The WinSize option controls the size of the dz codec's sliding window. The window size in bytes is 2 raised to the power WinSize. The default value of WinSize is 16. Increasing WinSize will consume more memory on decompression but may improve compression ratio, depending on input.


Airplay SDK: Whitepapers

Airplay SDK > Whitepapers >

Whitepapers

This document lists the whitepapers supplied with the SDK, which cover a wide range of topics. These are provided in HTML and PDF formats. The HTML files will open within this window, and the PDF files will open in an external reader.

HTML Format

  • Technical Comparison of IwGx and OpenGL ES 1.x
  • Porting Render Code from OpenGL ES 1.x to IwGx
  • Airplay Software Renderer
  • Airplay Performance Guidelines - Maximising 3D Performance
  • Airplay SDK – Optimisations for PowerVR

PDF Format

These Whitepapers are supplied in Adobe PDF format. Adobe Reader is required to view PDF documentation. The latest version of Adobe Reader is available for free from http://www.adobe.com/products/reader/


Airplay SDK: Technical Comparison of IwGx and OpenGL ES 1.x

Airplay SDK > Whitepapers > Technical Comparison of IwGx and OpenGL ES 1.x >

Technical Comparison of IwGx and OpenGL ES 1.x

Contents

  • Introduction
  • High-level view
    • Similarities
    • Differences
  • Medium-level view
    • Surface set-up
    • Transform
      • Projection transform
      • Model and view transforms
    • Lighting
      • Emissive contribution
      • Ambient contribution
      • Diffuse contribution
      • Scene lights
    • Rasterisation
    • Textures
    • Materials
  • Low-level view

Introduction

This document explores the main similarities and differences between the OpenGL ES 1.x API and Airplay's IwGx API. Whilst OpenGL ES is an API primarily designed to abstract hardware 3D acceleration, which often limits the performance available from software-only OpenGL ES implementations, IwGx is designed to provide high-performance access both to heavily optimised software rasterisers as well as a variety of 3D hardware APIs such as Direct3D Mobile in addition to OpenGL ES 1.x.

High-level view

This section examines the highest-level similarities and differences between OpenGL ES 1.x and IwGx.

Similarities
  • Both are stream-based “immediate mode” 2D/3D drawing APIs.
  • Both support vertex, normal, colour, UV and index streams.
  • Both support various primitive types, e.g., triangle list and triangle strip
  • Both contain concepts of textures, materials and lights.
  • Both contain no concept of a model/mesh.
  • Both contain no concept of vertex or bone animation (excepting the OpenGL ES 1.x matrix palette functions, which are a skinning rather than an animation API).

Differences
  • IwGx is slightly “higher level” than OpenGL ES 1.x.
  • IwGx is a C++ API (albeit mostly in a C-style), whereas OpenGL ES 1.x is a pure C API.
  • IwGx requires no explicit surface set-up, whereas OpenGL ES 1.x requires surface set-up via EGL.
  • IwGx “wraps up” most of the valuable rendering state in a material object, whereas OpenGL ES 1.x has many individual rendering states.
  • IwGx contains a best-in-class mobile software renderer, which out-performs any OpenGL ES 1.x software renderer (OpenGL ES 1.x is an API designed for hardware abstraction, not for high-performance software rendering).
  • IwGx handles all 4 screen rotations without any impact on the user.
  • IwGx allows vertex streams to be submitted in modelspace, worldspace, viewspace or screenspace, whereas OpenGL ES 1.x requires the user to explicitly set up different projection and modelview matrices.
  • IwGx will automatically cache geometry calls and batch them either by material or by Z (according to the user’s preference). It will also draw opaque geometry from front to back, followed by alpha geometry from back to front. OpenGL ES 1.x provides no such functionality.
  • IwGx is paired with an extensive 2D/3D geometry library, whereas OpenGL ES 1.x has very limited matrix rotation and translation functions.
  • IwGx is paired with an image library which allows textures to be loaded from BMP, GIF, PNG and TGA, whereas OpenGL ES 1.x has none.
  • IwGx supports other 3D hardware rendering APIs such as Direct3D mobile, and seamlessly supports the transition to OpenGL ES 2.0.
  • IwGx does not currently support stencil buffers, a matrix stack, or user clipping planes, whereas OpenGL ES does.

Medium-level view

This section examines in more detail IwGx’s approach to surface set-up, transform, lighting, rasterisation, textures and materials. In each case, we compare and contrast the approach with OpenGL ES 1.x.

Surface set-up

To use OpenGL ES 1.x, the user must go through a reasonably complex set-up process involving display, context and surface. Despite EGL’s concept of “configs”, some knowledge of the underlying device may be required in order to obtain the optimal set-up.

IwGx requires no surface set-up by the user. When IwGxInit() is called, the underlying surface is prepared optimally for the device, irrespective of whether rasterisation will be performed using OpenGL ES 1.x or IwGx’s software renderer. The surface is always the largest which can be displayed on the underlying device.

Transform

Let’s look at projection, view, and model transforms:

Projection transform

OpenGL ES 1.x has a 4x4 projection matrix. This can be set explicitly using glMatrixMode(GL_PROJECTION), or implicitly using glFrustum(). Theoretically the projection matrix can also be read by the user, although this is not implemented on all drivers.

IwGx does not expose a projection matrix to the user. Instead, it restricts the projection to a rectangular (i.e., non-sheared) perspective. The frustum is thus defined using two API calls:

  • void IwGxSetFarZNearZ(int32 ifar, int32 inear);

This sets the far and near clipping planes, in units from the view position.

  • Void IwGxSetPerspMul(int32 pm);

This sets the “perspective multiple” – i.e., the distance from the view position to the viewing plane.

The “perspective multiple” may seem an unfamiliar concept, but is easy to get to grips with. The viewing plane is conceptually the screen; so a perspective multiple of (screenwidth/2) results in a horizontal field-of-view of 90 degrees.

Note that the viewing plane is the same size as the surface, which is set up automatically by IwGxInit(), as described above. Its aspect is thus already defined.

The clipping plane and perspective multiple values can always be read by the user.

Model and view transforms

OpenGL ES 1.x has a 4x4 combined modelview matrix. This can be set explicitly using glMatrixMode(GL_MODELVIEW). Theoretically the modelview matrix can also be read by the user, although this is not implemented on all drivers.

IwGx separates the model and view transforms. Each can be set and read independently, as a 4x3 matrix:

  • void IwGxSetViewMatrix(const CIwMat* pMat);

This sets the view (camera) matrix.

  • void IwGxSetModelMatrix(const CIwMat* pMat, bool rotIsI = false);

This sets the model matrix. Note that this function also updates IwGx’s internal combined modelview matrix, so it must be called after IwGxSetViewMatrix().

Here, CIwMat is a fixed-point 4x3 matrix, with a 3x3 rotation member and a 3-vector translation member. The rotation components are in 1.19.12 fixed-point format (i.e. 32-bit values, with 1 sign bit and 12 fractional bits).

IwGx provides the option of “switching the transform pipeline” between software (SW) and hardware (HW). By “hardware” we mean any available drivers abstracting any hardware graphics acceleration; in this case, we are talking about the OpenGL ES 1.x drivers.

The “transform pipeline”, whilst functionally identical, has different implementations in order to provide optimal behaviour depending on whether it is switched to SW or HW:

If the transform pipeline is set to “SW”:

  • Transform vertex stream to viewspace.
  • Clip polygons against the view frustrum.
  • Backface-cull polygons.
  • Build up a list of polygons which are not clipped, and not backface culled, ready for the rasterisation stage.

If the transform pipeline is set to “HW”:

  • Prepare perspective transform and modelview transform appropriately for HW drivers.
  • Do no clipping or backface-culling within IwGx.
  • Pass vertex and normal streams to the HW drivers.

You may question why it is useful to set the transform pipeline to SW when targeting OpenGL ES 1.x. Ideaworks Lab's extensive experience of developing games for early hardware-accelerated mobile devices, using OpenGL ES 1.x, has shown that driver behaviour is a critical factor in determining game performance. On some devices and drivers, it is faster to perform the clipping and backface-culling within the middleware, building up a triangle list containing only those triangles which are visible within the frustum. This list is then sent to the drivers, resulting in much lower data bandwidth and increased performance.

Lighting

IwGx uses the same lighting model as OpenGL ES 1.x, as defined below;

Cv = Me + (Ma * Sa) + (Md * Sd * falloff)

where:

  • Cv = per-vertex colour, the output of the calculation
  • Me = material emissive colour
  • Ma = material ambient colour (or “ambient light response”)
  • Md = material diffuse colour (or “diffuse light response”)
  • Sa = scene ambient light colour
  • Sd = scene diffuse light colour
  • falloff = dot product of scene diffuse light direction with vertex normal

OpenGL ES 1.x supports at least 8 lights, which can be of type emissive, ambient, or diffuse (with cone falloff). By contrast, IwGx currently supports only a single ambient and a single diffuse (parallel) light. This might seem restrictive, but in practice for games on mobile devices today this is perfectly adequate. Light settings can be changed at will, so different geometries can be lit differently.

We can break this lighting model calculation down into three terms:

Emissive contribution

The "emissive contribution" corresponds to the term "Me". If emissive lighting is enabled, this term is equal to the material emissive colour; otherwise, this term is zero.

Emissive lighting is enabled and disabled as follows:

  • IwGxLightingEmissive(bool set);

The default material emissive colour is zero (black).

Ambient contribution

The "ambient contribution" corresponds to the term "(Ma * Sa)". If ambient lighting is enabled, this term is equal to the material ambient colour multiplied by any scene ambient light colour. In this sense, the "material ambient colour" is better thought of as the "material ambient lighting response". Note that if no scene ambient light has been created, this term will be zero. If ambient lighting is disabled, this term is not zero; instead, this term takes the value of the material ambient colour. This is more useful, as it means the user can disable all lighting contributions, but still control the colour of a primitive by modifying the material ambient colour.

Ambient lighting is enabled and disabled as follows:

  • IwGxLightingAmbient(bool set);

Diffuse contribution

The "diffuse contribution" corresponds to the term + "(Md * Sd * falloff)". If diffuse lighting is enabled, this term is equal to the material diffuse colour multiplied by any scene diffuse light colour, modified by the falloff term (the dot product between the scene diffuse light direction and the vertex normal). In this sense, the "material diffuse colour" is better thought of as the "material diffuse lighting response". Note that if no scene diffuse light has been created, this term will be zero. Note also that diffuse lighting requires a normal stream to be submitted; otherwise the term will be zero. If diffuse lighting is disabled, this term is zero. Diffuse lighting is enabled and disabled as follows:

  • IwGxLightingDiffuse(bool set);

Additionally, emissive, ambient and diffuse lighting can all be enabled and disabled together, using:

  • IwGxLightingOn(); // Turn emissive, ambient + diffuse lighting on
  • IwGxLightingOff(); // Turn emissive, ambient + diffuse lighting off

To repeat, if all lighting is turned off, the only contribution to the per-vertex colour will be the material ambient colour.

Scene lights

A single ambient scene light and a single diffuse scene light are supported. These lights are usually created at the game level initialisation stage, although they can equally be created, destroyed and modified dynamically. Each scene light is identified through an index, which must be 0 or 1. Each scene light can be set to be AMBIENT or DIFFUSE, although only up to one of each type may be set.

Create a scene ambient light as follows:

  • IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
  • IwGxSetLightCol(0, 0x40, 0x40, 0x40);

Here we have decided to make light 0 the AMBIENT light, and have set the ambient scene light colour to dark grey.

Create a scene diffuse light as follows:

  • IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
  • IwGxSetLightCol(1, 0xc0, 0xc0, 0xc0);
  • CIwSVec3 dd(0x93c, 0x93c, 0x93c);
  • IwGxSetLightDirn(1, &dd);

Here we have decided to make light 1 the DIFFUSE light, and have set the diffuse scene light colour to light grey. Note that a diffuse light also requires a direction; here we have set the direction to be at 45 degrees to each axis. Note that CIwSVec3 is a 3-component vector object, where the components are in 1.3.12 fixed-point format.

The “lighting pipeline”, whilst functionally identical, has different implementations in order to provide optimal behaviour depending on whether it is switched to SW or HW:

If lighting pipeline set to “SW”:

  • Material emissive, ambient and diffuse colours, together with any submitted colour stream and any scene lights, are used as inputs to the Lighting Model calculation.
  • Note that various factors affect the efficiency of this calculation: the material modulation mode, the lighting switches, etc.

If lighting pipeline set to “HW:

  • Material emissive, ambient and diffuse colours, together with any scene lights, are passed to the underlying HW drivers (in this case, OpenGL ES 1.x drivers).
  • Any submitted colour stream is also passed to the drivers.
  • The HW rasterisation will then perform any necessary colour calculations internally.

You may question why it is useful to set the lighting pipeline to SW when targeting OpenGL ES 1.x. Again, driver behaviour is a critical factor, and on some devices and drivers it is faster to perform the lighting calculations within the middleware, building up a per-vertex colour stream which is then sent to the drivers. This can be done without creating any scene lights on the driver side.

Rasterisation

By “rasterisation”, we mean that part of the API which performs the actual drawing of primitives to the surface. Some of these API calls may be cached, and the literal rasterisation may be postponed to a “flushing” stage. Again, IwGx allows the “rasterisation pipeline” to be switched between SW and HW, as follows:

If rasterisation pipeline set to “SW”:

  • Using the coordinates output from the transform stage, and the colours output from the lighting stage, construct triangle and quadrilateral packets and send them to the software renderer.

If rasterisation pipeline set to “HW”:

  • Call the underlying driver functions required to rasterise the primitives.

OpenGL ES 1.x provides the following rasterisation functions:

  • void glDrawElements(GLenum mode, GLsizei count, GLenum type,const GLvoid* indices);
  • void glDrawArrays(GLenum mode, GLint first, GLsizei count);
  • void glFlush(void);
  • EGLBoolean eglSwapBuffers(EGLDisplay display, EGLSurface surface);

Equivalently, IwGx provides the following:

  • void IwGxDrawPrims(IwGxPrimType primType, uint16* pInds, uint32 numInds);
  • void IwGxFlush();
  • void IwGxSwapBuffers();

The following OpenGL ES 1.x primitive types map directly to IwGx types:

  • GL_TRIANGLES
  • GL_TRIANGLE_STRIP
  • GL_TRIANGLE_FAN
  • GL_LINES
  • GL_LINE_STRIP
  • …maps to IW_GX_TRI_LIST
  • …maps to IW_GX_TRI_STRIP
  • …maps to IW_GX_TRI_FAN
  • …maps to IW_GX_LINE_LIST
  • …maps to IW_GX_LINE_STRIP

In addition, GL_POINTS is similar to IW_GX_SPRITE_LIST.

GL_LINE_LOOP has no equivalent; the user should simply add an extra entry to the end of the streams, and use IW_GX_LINE_LIST.

IwGx also provides the following types:

  • IW_GX_QUAD_LIST
  • IW_GX_QUAD_STRIP
  • IW_GX_NPOLY_LIST
  • …quadrilateral list
  • …quadrilateral strip
  • …n-gon list

Passing a NULL index stream pointer to IwGxDrawPrims is equivalent to passing in the index stream (0, 1, 2, …, n).

Textures

In OpenGL ES 1.x, textures are dealt with using handles. Image data can be written but not read directly. Palettised formats are supported, but there are no functions for modifying palette entries without also re-writing the texels. Texture dimensions must be powers of 2.

In IwGx, textures are C++ objects. The user can create an empty texture object, then either set the format/texels/palette manually, or load the image data from a file, as follows:

  • CIwTexture* pTex = new CIwTexture;
  • pTex->LoadFromFile(“./textures/image.bmp”);
  • pTex->Upload();

Supported image formats are BMP, GIF, PNG and TGA. 4-bit and 8-bit palettised formats are supported in addition to unpalettised formats. The following image types may be read:

Format

Bits per pixel

Palettised?

Run-length encoded?

  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • 4
  • 4
  • 8
  • 8
  • 16
  • 24
  • 32
  • YES
  • YES
  • YES
  • YES
  • NO
  • NO
  • NO
  • NO
  • YES
  • NO
  • YES
  • NO
  • NO
  • NO
  • GIF
  • GIF
  • GIF
  • GIF
  • 4
  • 5
  • 6
  • 8
  • YES
  • YES
  • YES
  • YES
  • NO
  • NO
  • NO
  • NO
  • PNG
  • PNG
  • PNG
  • 4
  • 8
  • 24
  • YES
  • YES
  • NO
  • NO
  • NO
  • NO
  • TGA
  • TGA
  • TGA
  • TGA
  • TGA
  • TGA
  • 16
  • 16
  • 24
  • 24
  • 32
  • 32
  • NO
  • NO
  • NO
  • NO
  • NO
  • NO
  • NO
  • YES
  • NO
  • YES
  • NO
  • YES

The Upload() method is critical; this is the point at which the image data is transferred from the “client side” to the “driver side”. The “driver side” may be the OpenGL ES 1.x drivers, or the software renderer’s virtual VRAM. If the user wishes to modify the texel or palette data after upload, they must flag the texture as “modifiable” in advance, so that the data is also kept on the client side.

At Upload() time, the image data is converted by default into a format appropriate for the underlying hardware drivers (or the software renderer). If necessary, the user can override this and specify a precise format for the texture. The entire set of OpenGL ES 2.0 formats is supported (luminance formats excepted).

CIwTexture contains many useful methods for modifying the image data and texture properties. Some of these methods must be called prior to Upload(), or the texture must be flagged as “modifiable” in advance. Here are just a few examples of CIwTexture methods:

  • GetWidth()

    • Get the width of the texture, in texels. Texture dimensions in IwGx must also be powers of 2.

  • SetClamping(…)

    • Set whether the texture should “wrap” or “clamp” if UV coordinates extend beyond the range [0,1].

  • ChangePalette(…)

    • Modify the palette of a palettised image.

If the user creates the CIwTexture object, they are responsible for deleting it. Note that the user never “binds” a texture; the current texture is always set indirectly through the material object (see “Materials”).

Note: Airplay Studio also contains an extensive resource-management module, IwResManager, for loading/serialising/querying groups of textures and other assets such as materials, models, animations, etc. The user is free to ignore this module and perform their own management of textures and other resources.

Materials

In OpenGL ES 1.x, a “material” is simply a concept used by the lighting model. In IwGx, materials are C++ objects, and are a key part of the entire API. A material object defines to a large extent exactly how primitives are rasterised. The material object includes the following data:

  • Shade mode – FLAT or GOURAUD.
  • Modulation mode – NONE, R or RGB.
  • Alpha mode – NONE, ADD, SUB, HALF or BLEND.
  • Cull mode – NONE, FRONT or BACK.
  • Colours – emissive, ambient and diffuse.
  • Z-depth offset – for decals and z-buffer offsetting.
  • Textures – pointers to CIwTexture objects for 2 texture stages.
  • UV animation – information for cel-based or UV-scrolling animation.

The user can create blank CIwMaterial objects, then set them up as required. For instance:

  • CIwMaterial* pMat = new CIwMaterial;
  • pMat->SetShadeMode(CIwMaterial::SHADE_FLAT);
  • pMat->SetAlphaMode(CIwMaterial::ALPHA_ADD);
  • pMat->SetTexture(pTex); // set some texture on stage 0
  • pMat->SetColAmbient(0x404040); // set ambient light response

At any time, the user then sets the current drawing material using:

  • IwGxSetMaterial(CIwMaterial*);

This then defines the drawing state for all calls to IwGxDrawPrims(), until a different material is set.

Wrapping up most of the rendering state in the material object enables IwGx to automatically batch drawing calls by material. In this way we can minimise the number of calls to the OpenGL ES 1.x drivers which change render states, including changes to the bound texture. The batching process also allows IwGx to automatically draw all opaque geometry from front to back (near to far), followed by all alpha geometry from back to front, thus minimising z-buffer artefacts.

Note: Airplay Studio also contains an extensive resource-management module, “IwResManager”, for loading/serialising/querying groups of materials and other assets such as textures, models, animations, etc. The user is free to ignore this module and perform their own management of textures and other resources.

Low-level view

We now look at every function in the OpenGL ES 1.x specification, and describe how it equates (if at all) to the IwGx API.

Please note that many features unsupported by IwGx are either very inefficient to implement in software, are used solely to improve performance on hardware (in which case they are used internally by IwGx but not exposed via the API) or this functionality (with enhancements) is provided by other modules within the Airplay SDK.

EGL
As described in “Surface set-up”, IwGxInit() performs all steps necessary to set up the surface (backbuffer and z-buffer).

eglSwapBuffers
IwGxSwapBuffers() is equivalent.

glActiveTexture
IwGxSetMaterial() sets the current material, which contains up to two texture pointers. The user is abstracted from the concept of setting texture stages or units.

glAlphaFunc
Alpha testing is a property of the material. If alpha testing is on, the test function is always equivalent to GL_GREATER.

glBindBuffer
IwGx currently does not support VBOs.

glBindTexture
IwGxSetMaterial() sets the current material, which contains up to two texture pointers. The user is abstracted from the concept of settings texture stages or units.

glBlendFunc
Alpha blending is a property of the material. Limited modes are supported; for instance, ALPHA_ADD is equivalent to glBlendFunc(GL_SRC_ALPHA, GL_ONE).

glBufferData
IwGx currently does not support VBOs.

glBufferSubData
IwGx currently does not support VBOs.

glClear
IwGxClear() is equivalent.

glClearColor
IwGxSetColClear() is equivalent.

glClearDepth
IwGx currently does not support setting this value. The z-buffer is always cleared to the default value.

glClearStencil
IwGx currently does not support a stencil buffer.

glClientActiveTexture
IwGxSetMaterial() sets the current material, which contains up to two texture pointers. The user is abstracted from the concept of settings texture stages or units.

glClipPlane
IwGx currently does not support setting user clip planes.

glColor
The vertex colour for drawing is the result of the standard lighting model. The inputs to this are the colour stream (if any), the scene lights, and the current material colours.

glColorMask
IwGx currently does not support setting a colour mask.

glColorPointer
IwGxSetColStream() is equivalent.

glCompressedTexImage2D
Internally, IwGx supports all the palettised image formats supported by OpenGL ES 2.0, which is a superset of those supporte by OpenGL ES 1.x.

glCompressedTexSubImage2D
IwGx currently does not support partial overwriting of texel data.

glCopyTexImage2D
IwGx currently does not support copying of texel data from the backbuffer.

glCopyTexSubImage2D
IwGx currently does not support partial copying of texel data from the backbuffer.

glCullFace
Backface culling is a property of the material. For example, CULL_FRONT is equivalent to glCullFace(GL_FRONT).

glCurrentPaletteMatrix
IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).

glDeleteBuffers
IwGx currently does not support VBOs.

glDeleteTextures
Textures in IwGx are instances of the class CIwTexture. These can be manually constructed and destructed by the user.

glDepthFunc
IwGx currently does not support changing the depth function. The function is initialised to GL_LEQUAL.

glDepthMask
IwGx currently does not support changing the depth mask. Writing to the z-buffer is always on for opaque geometry and off for alpha geometry. This is because IwGx automatically caches drawn geometry, then flushes opaque geometry from front to back followed by alpha geometry from back to front, this minimises any artefacts related to the z-buffer and transparency.

glDepthRange
“Z-depth offset” is a property of the material. This allows geometry to write values to the z-buffer which differ from the default values, thus providing a way of “pushing” geometry forward or backwards in the z-buffer. The OpenGL ES 1.x implementation of this property may use glDepthRange.

glDrawTex
IwGx provides helper functions for screenspace drawing; for example, IwGxDrawRectScreenSpace(). Screenspace drawing always occurs in front of or behind the frustum. A variable number of “slots” are provided for layering screenspace drawing. The current slot is set with IwGxSetScreenSpaceSlot().

glDisable / glEnable
We look at each parameter in turn:

  • GL_ALPHA_TEST
    Alpha testing is a property of the material. Default is disabled.
  • GL_BLEND
    Alpha blending is a property of the material. Default is disabled.
  • GL_CLIP_PLANE
    IwGx currently does not support user clip planes.
  • GL_COLOR_LOGIC_OP
    IwGx currently does not support user colour logic operations.
  • GL_COLOR_MATERIAL
    Not exposed; but IwGxSetColStream() effectively enables/disables this according to whether the input is non-NULL/NULL.
  • GL_CULL_FACE
    Backface culling is a property of the material. Default is enabled.
  • GL_DEPTH_TEST
    Not exposed; enabled for opaque geometry, disabled for alpha geometry.
  • GL_DITHER
    IwGx currently does not support dithering.
  • GL_FOG
    Enabled/disabled with IwGxFogOn() / IwGxFogOff(). Default is disabled.
  • GL_LIGHT
    Enabled with IwGxSetLightType(i, type). Disabled with IwGxSetLightType(i, IW_GX_LIGHT_UNUSED). Default is disabled.
  • GL_LIGHTING
    Enabled/disabled with IwGxLightingOn() / IwGxLightingOff().
  • GL_LINE_SMOOTH
    IwGx currently does not support line filtering.
  • GL_MATRIX_PALETTE_OES
    IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).
  • GL_MULTISAMPLE
    IwGx does not support fragment multisampling. It does however support full-screen anti-aliasing, through exposure of the EGL_SAMPLE_BUFFERS and EGL_SAMPLES settings in the ICF file.
  • GL_NORMALIZE
    IwGx currently does not support auto-normalisation of vertex normals.
  • GL_POINT_SMOOTH
    IwGx currently does not support point filtering.
  • GL_POINT_SPRITE_OES
    IwGx supports the primitive type IW_GX_SPRITE_LIST. These are effectively unscaled point sprites. Unlike point sprites, the top-left and bottom-right can have UV coordinates which differ from (0,0) and (1,1).
  • GL_POLYGON_OFFSET_FILL
    See glDepthRange.
  • GL_RESCALE_NORMAL
    IwGx currently does not support auto-scaling of vertex normals.
  • GL_SAMPLE_ALPHA_TO_COVERAGE
    IwGx has no such concept.
  • GL_SAMPLE_ALPHA_TO_ONE
    IwGx has no such concept.
  • GL_SAMPLE_COVERAGE
    IwGx has no such concept.
  • GL_SCISSOR_TEST
    IwGxSetViewRect() is equivalent.
  • GL_STENCIL_TEST
    IwGx currently does not support a stencil buffer.
  • GL_TEXTURE_2D
    Not exposed; always enabled, as IwGx currently only supports 2D textures.

glDisableClientState / glEnableClientState
We look at each parameter in turn:

  • GL_COLOR_ARRAY
    Not exposed; IwGxSetColStream() effectively enables/disables this according to whether the input is non-NULL/NULL.
  • GL_MATRIX_INDEX_ARRAY_OES
    IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).
  • GL_NORMAL_ARRAY
    Not exposed; IwGxSetNormStream() effectively enables/disables this according to whether the input is non-NULL/NULL. Diffuse lighting must also be enabled for the normal stream to affect the lighting calculation.
  • GL_POINT_SIZE_ARRAY_OES
    IwGx supports the primitive type IW_GX_SPRITE_LIST. These are unscaled screen-aligned quadrilaterals. The size of each “sprite” is determined by the span of the UV mapping across the rectangle; i.e., a 1-1 mapping of texels to pixels is enforced.
  • GL_TEXTURE_COORD_ARRAY
    Not exposed; IwGxSetUVStream() effectively enables/disables this according to whether the input is non-NULL/NULL.
  • GL_VERTEX_ARRAY
    Not exposed; effectively always enabled. IwGxSetVertStream() is used to submit the vertex stream.
  • GL_WEIGHT_ARRAY_OES
    IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).

glDrawArrays
IwGxDrawPrims() is equivalent, where the index stream pointer is passed as NULL.

glDrawElements
IwGxDrawPrims() is equivalent, where the index stream pointer is passed as non-NULL.

glFinish
IwGx does not provide a blocking flush in this way; see IwGxFlush().

glFlush
IwGxFlush() is equivalent.

glFog
IwGxSetFogFarZNearZ() and IwGxSetFogColour() are equivalent. Fog mode is linear.

glFrontFace
Not exposed; however, see glCullFace().

glFrustum
IwGxSetFarZNearZ() and IwGxSetPerspMul() are equivalent.

glGenBuffers
IwGx currently does not support VBOs.

glGenTextures
Textures in IwGx are instances of the class CIwTexture. These can be manually constructed and destructed by the user.

glGet
For brevity, we do not list all equivalents. IwGx pairs all setter functions with corresponding getters.

glGetBufferParameter
IwGx currently does not support VBOs.

glGetClipPlane
IwGx currently does not support user clip planes.

glGetError
IwGx does not provide a “silent” error logging mechanism; rather, it displays an assertion dialog whenever illegal behaviour is trapped.

glGetLight
IwGxGetLightType(), IwGxGetLightCol(), IwGxGetLightDirn() are equivalent.

glGetMaterial
The CIwMaterial class has getters for all its data.

glGetPointer
IwGx currently does not support getting back the stream pointers.

glGetString
Not exposed; used by IwGx to determine the best settings for the Transform, Lighting and Rasterisation pipelines, as well as various other set-up information.

glGetTexEnv
The CIwTexture class has getters for all its data.

glGetTexParameter
The CIwTexture class has getters for all its data, including filtering, mipmapping and clamping modes.

glHint
Not exposed; IwGx provides hints to the OpenGL ES 1.x drivers for optimal performance.

glIsBuffer
IwGx currently does not support VBOs.

glIsEnabled
Not exposed; IwGx operates in a manner which is independent of missing capabilities.

glIsTexture
Not exposed; textures are CIwTexture objects.

glLight
IwGxSetLightType(), IwGxSetLightCol() are equivalent.

glLightModel
Not exposed; IwGx has no concept of an ambient colour outside of the CIwMaterial object, and lighting calculations are always one-sided.

glLineWidth
IwGx currently does not support line widths other than 1.

glLoadIdentity
IwGx is paired with with the IwGeom geometry module, which has the CIwMat::SetIdentity() method.

glLoadMatrix
IwGxSetViewMatrix(), IwGxSetModelMatrix(), IwGxSetFarZNearZ(), IwGxSetPerspMul() are equivalent. Material UV animation replicates the translation component of the GL texture matrix.

glLoadPaletteFromModelViewMatrix
IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).

glLogicOp
IwGx currently does not support logical pixel operations.

glMaterial
CIwMaterial object is equivalent.

glMatrixIndexPointer
IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).

glMatrixMode
IwGxSetViewMatrix(), IwGxSetModelMatrix(), IwGxSetFarZNearZ(), IwGxSetPerspMul() are equivalent. Material UV animation replicates the translation component of the GL texture matrix.

glMultMatrix
IwGx is paired with the IwGeom geometry module, which has a full set of matrix and vector methods.

glMultiTexCoord
IwGx currently supports only 2D texture coordinates, and supports setting streams rather than single values. See glTexCoordPointer.

glNormal
IwGx supports setting normal streams rather than single values. See glNormalPointer.

glNormalPointer
IwGxSetNormStream() is equivalent.

glOrtho
IwGx currently only supports a perspective projection. However, the user can submit screenspace vertex streams using IwGetSetVertStreamScreenSpace(). Also, there are helper functions such as IwGxDrawRectScreenSpace().

glPixelStore
IwGx currently does not supporting reading data from the backbuffer.

glPointParameter glPointSize
IwGx supports the primitive type IW_GX_SPRITE_LIST. These are unscaled screen-aligned quadrilaterals. The size of each “sprite” is determined by the span of the UV mapping across the rectangle; i.e., a 1-1 mapping of texels to pixels is enforced.

glPointSizePointer
See glPointSize.

glPolygonOffset
See glDepthRange.

glPopMatrix
IwGx does not support a matrix stack.

glPushMatrix
IwGx does not support a matrix stack.

glReadPixels
IwGx currently does not supporting reading data from the backbuffer.

glRotate
IwGx is paired with the IwGeom geometry module, which has a full set of matrix and vector methods.

glSampleCoverage
IwGx does not support fragment multisampling. It does however support full-screen anti-aliasing, through exposure of the EGL_SAMPLE_BUFFERS and EGL_SAMPLES settings in the ICF file.

glScale
IwGx is paired with the IwGeom geometry module, which has a full set of matrix and vector methods.

glScissor
IwGx currently does not support a variable clip rectangle.

glShadeModel
CIwMaterial::SetShadeMode() is equivalent.

glStencilFunc
IwGx currently does not support a stencil buffer.

glStencilMask
IwGx currently does not support a stencil buffer.

glStencilOp
IwGx currently does not support a stencil buffer.

glTexCoordPointer
IwGxSetUVStream() is equivalent.

glTexEnv
CIwTexture and CIwMaterial objects replicate some of this functionality, e.g. CIwMaterial::SetModulateMode().

glTexImage2D
CIwTexture object provides equivalent methods.

glTexParameter
The CIwTexture class has setters for all its data, including filtering, mipmapping and clamping modes.

glTexSubImage2D
IwGx currently does not support partial setting of texel data.

glTranslate
IwGx is paired with the IwGeom geometry module, which has a full set of matrix and vector methods.

glVertexPointer
IwGxSetVertStream() is equivalent.

glViewport
Not exposed; the projection always maps the viewing plane to the entire backbuffer.

glWeightPointer
IwGx does not contain any skinning functionality (Airplay Studio’s IwAnim module provides a full skinned animation API).


Airplay SDK: Porting Render Code from OpenGL ES 1.x to IwGx

Airplay SDK > Whitepapers > Porting Render Code from OpenGL ES 1.x to IwGx >

Porting Render Code from OpenGL ES 1.x to IwGx

Contents

  • Introduction
  • Why port render code to IwGx?
  • Prerequisites for porting render code
  • Suggested porting path
    • Comment out ALL gl calls
    • Add IwGxInit() and IwGxTerminate()
    • Set up the projection transform
    • Set up the view and model transforms
    • Set a single default material
    • Set vertex streams
    • Set index streams
    • Draw primitives
    • Create and manage textures
    • Create and manage materials
    • Set UV streams
    • Set scene lights
    • Set normal streams
    • Set colour streams
    • Next Steps
  • Optimising render code for IwGx

Introduction

This document provides some context and suggestions for porting application render code from OpenGL ES 1.x to IwGx. It is highly recommended that you read “Comparison of OpenGL ES 1.x and IwGx” prior to reading this document.

Why port render code to IwGx?

An application written directly to the OpenGL ES 1.x API must be paired with an OpenGL ES 1.x driver in order to run on a mobile device. This limits the application in the following ways:

  • OpenGL ES 1.x is an API designed to abstract hardware graphics acceleration. It is not an API for high-performance software rendering. Today, the vast majority of addressable mobile devices have no hardware graphics acceleration. An application written directly to OpenGL ES 1.x is thus severely performance-limited on the majority of mobile devices. IwGx contains a software renderer which is widely recognised as being the highest-performing commercial mobile software renderer available. Render code written to IwGx will thus run optimally on all software-only devices, as well as hardware-enabled devices.
  • Devices with hardware graphics acceleration vary a great deal in terms of the hardware itself, and the quality of the OpenGL ES 1.x drivers. It is highly recommended on some hardware-accelerated devices still to perform the clipping, backface culling, or lighting calculations within the application code, thus taking load away from the drivers. Unless the developer is prepared to include all these possible calculation paths within the application render code, performance will be limited on the majority of first-generation hardware-accelerated mobile devices. IwGx allows transform and lighting paths to be switched away from the drivers and calculated within the middleware. IwGx makes this decision on each device based on prior knowledge of the possible architectures. Render code written to IwGx will thus run optimally on all first-generation hardware-acclerated devices.
  • Alternative hardware-abstraction APIs such as OpenGL ES 2.x or D3D Mobile may become prevalent. Application render code written only to OpenGL ES 1.x will not be able to run on devices which have only alternative drivers. IwGx will support OpenGL ES 2.x, D3D Mobile and all other relevant drivers, and thus render code written to IwGx will run optimally on all device drivers.

Prerequisites for porting render code

IwGx is part of the Airplay Studio middleware. Airplay Studio is implemented as a platform-independent library on top of the Airplay System OS-abstraction layer. Thus a prerequisite for using IwGx is to port any OS-specific application code to Airplay System (i.e., to the S3E API).

This is generally a very simple process since the Airplay System platform is in general more powerful and flexible than most other current mobile development environments.

Suggested porting path

Airplay System directly exposes the OpenGL ES 1.x API, so once the OS-specific application code has been ported to the S3E API, your application will be able to run on any supported platform which provides OpenGL ES 1.x drivers. This includes the Airplay Windows Simulator.

A suggested path for porting the application render code is as follows:

Comment out ALL gl calls

Mixing calls to the IwGx API with calls to OpenGL ES 1.x is not a good starting point. IwGx maintains its own knowledge of the OpenGL ES 1.x state, which is not exposed to the user, and does not want the user to interfere with.

Start by commenting out all “gl” and “egl” calls within the application code. Your application should still run, albeit with no display. We can then begin the process of replacing the “gl” and “egl” calls with suitable equivalents.

Add IwGxInit() and IwGxTerminate()

Add the start of your application code, where you would normally perform egl initialisation, instead make a simple call to IwGxInit(). This will initialise the IwGx state, and prepare the backbuffer (“surface”) and any required z-buffer. The buffers are always sized maximally for the device. At the end of your application code, where you normally perform egl shutdown, make a simple call to IwGxTerminate().

Set up the projection transform

Where your application code currently sets up the GL projection matrix, instead make calls to IwGxSetFarZNearZ() and IwGxSetPerspMul(). The example below sets up a frustrum with a 90 degree horizontal field-of-view, and near/far planes at 50/50000:

  • IwGxSetFarZNearZ(50000, 50);
  • IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

These values can be modified during the application. However, they must never be set between calls to IwGxDrawPrims() and IwGxFlush(). That is, any drawn geometry must be flushed before the projection is modified.

The near and far plane distances must obey (0x8 <= near < far <= 0xffff).

Set up the view and model transforms

IwGx separates the combined modelview transform into its separate components. For each application camera, you should call IwGxSetViewMatrix() once, followed by calls to render any geometry using that camera. For each piece of geometry (or each model space) you should call IwGxSetModelMatrix() once, followed by calls to render any geometry in that model space.

Note that calling IwGxSetModelMatrix() also updates IwGx’s internal combined modelview matrix, so it must be called AFTER IwGxSetViewMatrix().

IwGx matrices are instances of the CIwMat class. This has a 3x3 rotational part, whose 32-bit components are in 1.19.12 fixed-point format, and a 3-vector translational part, also with 32-bit components. IwGx is paired with the IwGeom module, which is the home of CIwMat, and contains extensive classes and methods for fixed-point (and floating-point) geometry.

For example, a matrix representing a 90 degree rotation about the Y axis, and a translation of –0x100 units along the Z axis, could be constructed as follows:

  • CIwMat m0;
  • m0.SetRotX(IW_FIXED(90));
  • m0.SetTrans(CIwVec3(0, 0, -0x100));

Set a single default material

Before performing any drawing, the user must set a material, to define the bulk of the IwGx drawing state. Eventually the user will need to set up the correct material for each rendered geometry; but to get up and running, a single default material will suffice.

Directly after calling IwGxInit(), create a single global material (not as a static object!) and set it as follows:

  • CIwMaterial* g_DefaultMaterial;
  • g_DefaultMaterial = new CIwMaterial;
  • IwGxSetMaterial(g_DefaultMaterial);

Directly before calling IwGxTerminate(), delete the material as follows:

  • delete g_DefaultMaterial;

Set vertex streams

IwGx supports vertex streams in 16-bit format only, equivalent in size to GL_SHORT. Where you are currently calling glVertexPointer(), instead prepare your vertex streams in 16-bit format, and call IwGxSetVertStream(). Note that this must be done AFTER calling IwGxSetModelMatrix().

It’s worth talking briefly here about scale. The conceptual unit scale is the user’s choice. One example however would be to choose 1 integer unit to represent 1cm. In this way, the far plane limit of 0xffff represents just over 650m. This would be sufficient draw-distance for most applications. With this choice, a car of length 3m would equate to an integer span of 300 units; i.e. we could expect the vertex components to be in the range [-150,150].

Most applications using OpenGL ES 1.x will provide their vertex streams in GL_FIXED format; i.e. 32-bit components in 1.15.16 fixed-point. To convert these into vertex streams suitable for IwGx, it will therefore be necessary to shift the values down into 16-bit format. The required shift will depend on the value ranges of the original streams, and the user’s choice of scale in the IwGx scheme.

Set index streams

IwGx supports index streams in 16-bit format only, equivalent in size to GL_SHORT. Unless you are using 8-bit indices, your index streams should be re-usable with no modifications.

Draw primitives

Where you are currently calling glDrawElements() or glDrawArrays(), instead call IwGxDrawPrims(). IwGx supports all the same primitive types as OpenGL ES 1.x, with the exception of GL_POINTS and GL_LINE_LOOP (GL_LINE_LOOP can be achieved using IW_GX_LINE_STRIP, with a duplicated first element).

Once you have scaled your vertex streams correctly in line with your view frustrum, you should now see all your application geometry rendered correctly, albeit unlit, using your default material.

Given that all the geometry will be unlit, it may be helpful to visualise the scene better by turning on the debug wireframe mode. You can do this as follows:

  • IwGxSetDebugFlags(IW_GX_DEBUG_WIREFRAME_F);

You should now see your application scene rendered in red wireframe.

Create and manage textures

In IwGx, textures are instances of the CIwTexture class. It is likely that the application will already have its own code for loading textures from disk and sending them to OpenGL ES 1.x. This code needs to be converted to create CIwTexture objects.

There are two choices for conversion here:

  • Convert the code at the file-loading level. This will only be appropriate if the application loads standard image files on device. If this is the case, image data can be loaded into CIwTexture objects as follows:
    • CIwTexture* pTex = new CIwTexture;
    • pTex->LoadFromFile(“./textures/image.bmp”);
    • pTex->Upload();

    Supported image formats are BMP, GIF, PNG and TGA. 4-bit and 8-bit palettised formats are supported in addition to 16-bit formats.

    The Upload() method is critical; this is the point at which the image data is transferred from the “client side” to the “driver side”. The “driver side” may be the OpenGL ES 1.x drivers, or the software renderer’s virtual VRAM. If the user wishes to modify the texel or palette data after upload, they must flag the texture as “modifiable” in advance, so that the data is also kept on the client side.

  • Convert the code at the raw image data level. This is the more likely scenario. In this case, the user will need to create an empty CIwTexture object, set the required width/height/format, copy the raw image data into the object, and finally upload. For example, say the application has a 64x64 image in the format GL_PALETTE8_R5_G6_B5_OES. Assume we have pointers pTexels, pPalette to the texel and palette data respectively. We could turn this into a IwGx texture as follows:
    • CIwTexture* pTex = new CIwTexture;
    • pTex->CopyFromBuffer(64, 64, CIwImage::Format::PALETTE8_RGB_565, 0, pTexels, pPalette);
    • pTex->SetName(“MyTexture”);
    • pTex->Upload();

    Note how we have named the texture object for possible future reference (or debugging convenience).

The user must delete the texture object when it is no longer required, as follows:

  • delete pTex;

CIwTexture objects can never be constructed as static data, as they rely on IwGxInit() having been called.

The following table shows how OpenGL ES 1.x texture formats translate to IwGx CIwImage::Format values:

  • GL_UNSIGNED_SHORT_5_6_5
  • GL_UNSIGNED_SHORT_4_4_4_4
  • GL_UNSIGNED_SHORT_5_5_5_1
  • GL_PALETTE4_RGB8_OES
  • GL_PALETTE4_RGBA8_OES
  • GL_PALETTE4_RGB5_A1_OES
  • GL_PALETTE4_R5_G6_B5_OES
  • GL_PALETTE4_RGBA4_OES
  • GL_PALETTE8_RGB8_OES
  • GL_PALETTE8_RGBA8_OES
  • GL_PALETTE8_RGB5_A1_OES
  • GL_PALETTE8_R5_G6_B5_OES
  • GL_PALETTE8_RGBA4_OES
  • RGB_565
  • RGBA_4444
  • RGBA_5551
  • PALETTE4_RGB_888
  • PALETTE4_RGBA_8888
  • PALETTE4_RGBA_5551
  • PALETTE4_RGB_565
  • PALETTE4_RGBA_4444
  • PALETTE8_RGB_888
  • PALETTE8_RGBA_8888
  • PALETTE8_RGBA_5551
  • PALETTE8_RGB_565
  • PALETTE8_RGBA_4444

Textures are mipmapped by default, but this can be turned off (for OpenGL ES 1.x targets only) using:

  • CIwTexture::SetMipMapping(false);

Textures are bilinear filtered by default (for OpenGL ES 1.x targets only), but this can be turned off using:

  • CIwTexture::SetFiltering(false);

Note that for OpenGL ES 1.x targets, a mipmapped filtered texture will use GL_LINEAR_MIPMAP_NEAREST, as GL_LINEAR_MIPMAP_LINEAR usually incurs a performance penalty (unless it has been determined that GL_LINEAR_MIPMAP_LINEAR on a given device does not incur a performance penalty).

Create and manage materials

CIwTexture objects are of little use in themselves. The workhorse object for defining drawing state is CIwMaterial. This can contain pointers to up to two textures, as well as defining colours, shade mode, modulation mode, etc.

It is likely that the application will already have its own code for managing materials (perhaps even having a material object) and binding that data to models or model surfaces. In this case it should be relatively simple to convert the application render code over to using the CIwMaterial object.

The following table shows how some OpenGL ES 1.x drawing state concepts translate to CIwMaterial concepts:

  • glCullFace()
  • glShadeModel()
  • GL_REPLACE, GL_MODULATE
  • glBlendFunc()
  • glAlphaFunc()
  • GL_EMISSION
  • GL_AMBIENT
  • GL_DIFFUSE
  • glBindTexture()
  • glPolygonOffset
  • glDepthRange
  • glMatrixMode(GL_TEXTURE)
  • CIwMaterial::SetCullMode()
  • CIwMaterial::SetShadeMode()
  • CIwMaterial::SetModulateMode()
  • CIwMaterial::SetAlphaMode()
  • CIwMaterial::SetAlphaTestMode()
  • CIwMaterial::SetAlphaTestRefVal()
  • CIwMaterial::SetColEmissive()
  • CIwMaterial::SetColAmbient()
  • CIwMaterial::SetColDiffuse()
  • CIwMaterial::SetTexture()
  • CIwMaterial::SetZDepthOfs()
  • CIwMaterial::SetUVOfs()
  • CIwMaterial::CreateAnim()

CIwMaterial objects can never be constructed as static data, as they rely on IwGxInit() having been called.

Assuming the application code has been converted to create/destroy CIwMaterial objects and set them up correctly to replicate the previous drawing state, all the user then has to do is set the current drawing state by setting the current material, as follows:

  • IwGxSetMaterial(CIwMaterial*);

Any subsequent calls to IwGxDrawPrims() will then use this material.

Often it’s useful to be able to set a temporary drawing state without having to “new” and “delete” a material object. IwGx provides a “data cache” which is useful for such temporary data. The IwGx data cache is cleared at the end of each call to IwGxFlush(). Data written to the cache thus persists only up to the next call to IwGxFlush().

For example, we could set up a material on the data cache as follows:

  • CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
  • pMat->SetShadeMode(CIwMaterial::SHADE_FLAT);
  • pMat->SetColEmissive(0x0000ff);
  • IwGxSetMaterial(pMat);

If a material has been used to draw some geometry, it is legal to modify some properties of a the material and re-use it within the same scene. However, some properties of the material must never be modified before the next call to IwGxFlush() – any attempt to do so will result in an assertion. The following material methods are the only ones which are legal to modify if the material has already been used in the scene:

  • SetColEmissive()
  • SetColAmbient()
  • SetColDiffuse()
  • SetZDepthOfs()
  • SetUVOfs()

Another useful concept is that of the “template material”. Whenever a material object is constructed, its members are copied from a single global “template material”. This material is exposed to the user and may be modified at any time (usually only at application initialisation). For example, say we want the default shade mode for all materials to be SHADE_FLAT:

  • IwGxGetMaterialTemplate()->SetShadeMode(CIwMaterial::SHADE_FLAT);

Set UV streams

Textured materials require UV streams to determine the texture coordinates. IwGx supports UV streams in 16-bit format only, equivalent in size to GL_SHORT. These are in 1.3.12 fixed-point format; equating to a floating-point range of [-8.0, 8.0].

The UV stream is set with IwGxSetUVStream().

If existing application code is using UV coords in GL_FIXED format, these will need shifting down by 4 bits into the 1.3.12 format. If existing application code relies on being able to wrap the texture more than +/- 8 times, you could try repeating the image several times within a larger texture, thus effectively increasing the total number of possible wraps. Failing that, the source artwork would need to be modified.

Texture coordinates wrap by default, but can be set to clamp with:

  • CIwTexture::SetClamping(true);

Note that the material object provides the facility for UV animation; the user can manually modify the material’s UV offset using CIwMaterial::SetUVOfs(), or they can create a full UV animation (see AirplaySDK.chm for more details).

Once you have converted the code for textures, materials and UV streams, turn off wireframe mode as follows:

  • IwGxClearDebugFlags(IW_GX_DEBUG_WIREFRAME_F);

You should now be able to view the scene with textures correctly applied. You will still have no lighting (everything will be flatly lit), so let’s address that next.

Set scene lights

IwGx supports a simplified lighting model consisting of one ambient and one diffuse (parallel) light. Each can have a colour, and the diffuse light can have a direction in the world. These could be set up as follows:

  • IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
  • IwGxSetLightCol(0, 0x40, 0x40, 0x40); // dark grey
  • IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
  • IwGxSetLightCol(1, 0xc0, 0xc0, 0xc0); // light grey
  • CIwSVec3 dd(0x93c, 0x93c, 0x93c); // 45 degrees to each axis
  • IwGxSetLightDirn(1, &dd);

Existing application code calls to glLight() should be easily converted in this way. IwGx allows all scene light values to be modified at any time.

In addition, the emissive/ambient/diffuse components of the lighting equation can be turned on and off individually. See AirplayAPIReference.chm for more details.

Set normal streams

IwGx supports normal streams in 16-bit format only, equivalent in size to GL_SHORT. These are in 1.3.12 fixed-point format. If existing application code is using normals in GL_FIXED format, these will need shifting down by 4 bits into the 1.3.12 format.

The normal stream is set with IwGxSetNormStream().

Once scene lights and normal streams have been set up, the scene should begin to respect diffuse lighting.

Set colour streams

IwGx supports colour streams as RGBA, 8-bits per component, equivalent to GL_UNSIGNED_BYTE. If existing application code is using colour streams in GL_UNSIGNED_BYTE format, these will need no conversion.

The colour stream is set with IwGxSetColourStream(). It can be cleared by passing in a NULL pointer. If a colour stream is present, the colour replaces the material ambient and diffuse colours in the lighting equation at each vertex (in the same way as the OpenGL ES 1.x lighting equation).

Next Steps

Once you have successfully completed these conversion steps, your application scene should now contain geometry that is transformed, textured and lit correctly. For more detail on these issues, and information on effects such as fog and motion blur, see AirplayAPIReference.chm.

Optimising render code for IwGx

Here are some recommendations which should allow the user to increase performance of their application’s render code when using IwGx:

Minimise the number of calls to IwGxDrawPrims()
Each call to IwGxDrawPrims() incurs a certain overhead. The user should try to minimise the number of materials in the scene, and create long geometry streams to minimise the number of calls to IwGxDrawPrims().

Use MODULATE_R and MODULATE_NONE
IwGx’s software renderer is much faster at rendering primitives which do not require a full RGB modulation of texel colour by vertex colour. Often, “white lighting” is sufficient, in which case the material’s modulation mode can be set to MODULATE_R. In this case, only the R component of the calculated vertex colour is used to apply greyscale lighting to the texture.

Similarly, where the material is not required to be lit at all (for example, a sky dome), MODULATE_NONE provides a small performance boost as it enables the lighting calculation to be completely bypassed.

Use palettised textures
4-bit (16 colour) palettised textures are the most efficient for the software renderer, followed by 8-bit (256 colour) palettised textures. Unpalettised textures are slower as they require a more expensive modulation path.

Use IW_GX_QUAD_STRIP and IW_GX_QUAD_LIST
IwGx supports the quadrilateral primitives IW_GX_QUAD_STRIP and IW_GX_QUAD_LIST (see the Airplay SDK Reference Guide for diagrams of the index mappings). IwGx’s software renderer is not restricted natively to triangles, so if the source geometry naturally maps to quads, performance is lost on software-rendering targets if the quads are preprocessed into tris.

IW_GX_QUAD_STRIP is actually the most efficient primitive of all, as on OpenGL ES 1.x targets the same index buffer can be passed through as a tri strip (again, you can see this from the index mapping diagrams).

Turn off diffuse lighting when not required
Diffuse lighting can be turned off in the following ways:

  • // EITHER
  • IwGxLightingDiffuse(false);
  • // OR
  • IwGxSetNormStream(NULL);

Don’t use fog
IwGx supports vertex fog – but it’s expensive.

Don’t use floating-point geometry types
The IwGx API is currently fixed-point only; however, the underlying IwGeom module supports floating-point geometry types. Don’t use these at all (and avoid any use of the “float” type) during the main application loop.

Application Optimisations
Of course all the general application rendering optimisations still apply, like performing high-level frustrum culling (for example, culling models by bounding sphere), using level-of-detail models, etc.


Airplay SDK: Airplay Software Renderer

Airplay SDK > Whitepapers > Airplay Software Renderer >

Airplay Software Renderer

Contents

  • Introduction
  • The Standard Renderer
    • Sorting By Z
    • Front and Back Slots
    • Safety Slots
    • Poly Z Depth Offsets
    • Pre-Sorted Polys
  • The Scanline Renderer
  • Tuning Assets for Software Rendering
    • Quads and N-polys
    • Overdraw and Fill Rate
    • Opaque vs. transparent geometry
  • Tuning Assets for the Scanline Software Renderer
    • Vertex sharing
    • Opaque vs. transparent geometry
    • Sharing of UV texture coordinates
    • UV tiling can reduce the number of polys
  • Lighting and Colour Effects
    • Lighting Modulation Modes (R, RGB) and Palette Caches
    • Texel Sharing
    • Tinting
    • Brightness
  • Texture Pages
    • Adding Transparencies
    • EXAMPLE
  • Yield Frequency
  • Minimising Build Size

Introduction

Many embedded devices do not have dedicated hardware for graphics acceleration. Airplay caters for such devices by means of a software renderer - that is, an optimised library for transforming, lighting and rasterising polygons that runs entirely on the CPU.

The Airplay software renderer is a mature piece of technology with a history of producing outstanding results with very few resources. For the most part software rendering can be switched seamlessly with hardware rendering. This document describes some of the background to the software rendering technology in the Airplay SDK and how to get the best results from it.

The Airplay software renderer is available in two flavours:

  • The Standard Renderer
  • The Scanline Renderer

By default, the Standard Renderer is used. However, the developer has the option of alternatively using the Scanline Renderer, by utilising the Airplay Studio Selective Linking process. For more details, see the Selective Linking page.

The Airplay software renderer is used implicitly by the IwGx runtime. If the device has no hardware graphics acceleration, the Airplay software renderer is used. Alternatively, the developer can set their application to use software rendering even if the device supports hardware graphics acceleration.

The Standard Renderer

The Standard Renderer sorts the render order by submitting polys into an order table and flushing each entry farthest-to-nearest. The renderer's default method of sorting the drawing of polygons is based on the maximum Z value. Polys are drawn from back to front with nearer polygons drawing over top of far ones.

For a scene without intersecting polys, there is usually some order of drawing the polygons which will be correct.

The exception is the case of cyclical overlap.

IwGx offers an automatic method of ordering the polys by their farthest z-value.

Sorting By Z

When using the sorting mode IW_GX_SORT_BY_Z (which is set using the function IwGxSetSortMode()), the ordering table is made up of a number of Z buckets, or “slots”. The number of slots is set using the ICF setting [GX] PolyOTSize, the default of which is 4096.

The distance between the far and near clipping planes is split into a number of uniform regions, the number of which corresponds to the number of slots. The index used to decide which slot a polygon is assigned to is the maximum Z value of its vertices. The region this maximum Z value exists in decides which slot the polygon is placed in. The polygons are not sorted within each slot.

On calling IwGxFlush() the polys are drawn by slots, with the farthest slot first. Within a slot the polys are drawn in last-in first-out order.

Front and Back Slots

In addition to the main order table there are 32 near clipping plane slots, and 4 far clipping plane slots. These extra slots can be used to attach 2D graphics to the front and back of the rendered scene. The number of slots for each can be changed using the [GX] NumSlotsFront and [GX] NumSlotsBack ICF settings.

The user can specify a front slot (i.e., drawn in front of the main frustrum) as follows:

  • IwGxSetScreenSpaceSlot(2); // a front slot

The user can specify a back slot (i.e, drawn behind the main frustrum) as follows:

  • IwGxSetScreenSpaceSlot(-2); // a back slot

As can be seen, non-negative values refer to front slot, and negative values refer to back slot.

Safety Slots

The number of slots specified by PolyOTSize is split into two lots: those that exist within the bounds of the near and far clipping plane and then those that exist behind the far clipping plane, which act as safety slots. The safety slots allow you to correctly order those polys that exist in the viewable area, but which have a maximum Z value that does not. The number of safety slots is set using the [GX] PolyOTSizeSafety ICF setting.

Poly Z-Depth offsets

Unfortunately the order table's Z-ordering will sometimes produce the wrong result. A common example is small polys behind larger polys. These bad results can be fixed by applying a Z-Depth offset to the troublesome polygons. Groups of polys can be adjusted by the IwGxSetZDepthOfs() function, in their CIwMaterial or using face sets.

Pre-Sorted Polys

If you have data in a sorted format, you can override this sorting by using the IwGxSetZDepthFixed() function to enter the entire list into a single slot - submitting the nearest polys first.

The Scanline Renderer

When the Scanline Renderer option is selected, the scene is drawn one scanline at a time. Each poly is considered in a left to right pass across the screen.

For opaque polys, only the ones closest to the viewpoint are drawn. Transparent polys that are in front of the opaque polys are drawn in a back to front order.

This algorithm generally produces a scene with correct visibility of polys.

To use the Scanline Renderer you must selectively link it. To do this you must call the call the IwGxInit_SWRenderScanline() function after calling IwGxInit_Base().

Tuning Assets for Software Rendering

Quads and N-polys

The software renderers will draw quads and n-sided polys without triangulation (tesselation) of the poly. If a quad or n-sided poly has texture mapping that is not an orthographic projection onto the plane of the poly, artefacts will appear.

Tip: The software renderer draws one quad faster than two triangles.

Overdraw and fill rate

Since the software renderer runs without any dedicated hardware, rasterisation is somewhat expensive. Therefore, when targetting the software renderer any attempt to reduce overdraw will pay dividends. Typically a game running in Airplay will need to aim at 1.5x overdraw to run in realtime.

Be aware that not all pixels are equal for the purposes of overdraw. See the Airplay Performance Guidelines Whitepaper for more details.

Opaque vs. transparent geometry

The software renderer is fastest rendering opaque, non-alpha'd geometry. Chromakey transparency is somewhat more expensive and full alpha modes like ADDITIVE are significantly more expensive.

The use of pure magenta (0xFF00FF) in a texture indicates transparent (chromakeyed) texels. These texels will appear cut out during rendering. There is still some cost associated with chromakeyed texels, so large areas of chromakey should be avoided in favour of actually cutting out transparent areas in the geometry.

Alpha mode rendering can be also be optimised by using chromakey for areas that would be zero-alpha (for example, using magenta rather than black for zero pixels in textures for ADDITIVE rendering).

If a texture contains only a small amount of chromakey consider splitting it into two and using separate geometry - chromakeyed textures will incur some cost even if no chromakeyed texels are encountered.

Tuning Assets for the Scanline Software Renderer

Vertex sharing

Vertex sharing amongst polys should be maximised.

Opaque vs. transparent geometry

Using the Scanline Renderer, visible opaque pixels effectively have zero overdraw, because the algorithm knows not to plot any pixels that would be overdrawn later. The Standard Renderer uses no such algorithm, and results in more overdraw.

Tip: Use the Scanline Renderer when there are a lot of opaque polygons obscuring others.

Sharing of UV texture coordinates

Using the same UV coordinates on adjacent polys is faster in the Scanline Renderer. In the example below, the first and second quads cannot share the same UV coordinates.

The mapping for the second, third and fourth quads is preferred.

Sharing Texture Coordinates Example

UV tiling can reduce the number of polys

A texture can be made to repeat over a poly. This feature can be used to reduce the number of polys.

The illustration below shows how you can tile over a larger poly and therefore save on the number of ploys used.

UV Tiling Example

Lighting and Colour Effects

Lighting Modulation Modes (R, RGB) and Palette Caches

In addition to full colour (RGB) lighting, a faster greysscale (R) lighting may be selected. The lighting mode used is determined by the material modulation mode, which is set using the SetModulateMode() function. The modulation modes can be any of the following:

  • MODULATE_RGB
  • MODULATE_R
  • MODULATE_NONE

R modulation is only valid for textured materials. In this mode only the R component of the light value is used to determine the brightness of the material.

The R modulation mode is optimised by using a cached version of the texture palettes being drawn. Each cache consists of 32 copies of the owning palette, each at different brightness. The caches are allocated from a single palette cache buffer. The buffer should be large enough to store all of the palettes required to draw a frame. This avoids generating palette caches every frame. The size of the buffer is set using the [GX] NumPaletteCacheBlocks ICF setting. Each palette cache block can hold one 256 colour palette or sixteen 16 colour palettes.

In R modulation, as each polygon is drawn, the colour values for pixels are taken from the palette cache.

It is possible that some banding may be visible due to the limited size of the cache; a small number of palettes will make shifts in intensity very obvious, due to large jumps in intensity.

The illustration below shows the effect a limited palette cache can have. The number on each edge represents a lighting intensity.

Lighting Effects Example

The artifacts related to banding can be reduced by using the ICF setting [GX] Force4BitGouraudDither to dither 4-bit textured rendering.

MODULATE_NONE will make textures appear full bright regardless of lighting settings/vertex colours. This is fast and requires only a minimal palette cache.

The palette caches fall into two essential types:

  • 4-bit using 16 colours.
  • 8-bit using 256 colours.

To set the amount of memory for the Cached Palettes use the following ICF settings:

  • [GX] NumPaletteCacheBlocks <integer>: This setting applies when using software rasterisation only. It sets the maximum number of lit 16/256-colour palette cache blocks. The default is 16. Each block requires 16896 bytes of space.
  • [GX] NumU16PaletteCacheBlocks : This setting applies when using software rasterisation only. It sets the maximum number of unlit 16-colour palettes that can be cached. Each 16-colour palette requires 32 bytes of space.
  • [GX] NumU256PaletteCacheBlocks : This setting applies when using software rasterisation only. It sets the maximum number of unlit 256-colour palettes that can be cached. Each 256-colour palette requires 512 bytes of space.

Tune these values so that your game does not assert "cached palette thrash" while rendering.

Tip: To get the effect of RGB modulation, whilst still using only R modulation, call SetPaletteCacheRGBs() with an array of 32 CIwColours. These colours will be used to light the 32 palette copies in the Cached Palette. These values can be set to a path through colour space that is indexed into by the top 5 bits in the ambient colour R component.

Texel sharing

The Airplay Studio resource pipeline allows textures to be constructed that share texels, but use different palettes. This can be used to produce much richer asset sets with very little texture memory overhead.

Tinting

A colour tint may be applied to textures when using software rendering. This is done by applying a gamma tint to the palette caches using IwGxSetPalette16Tint().

This applies the tint globally to all of the R modulated materials. The final texel colour is determined by:

  • R = (texR/255) ^ (256 - tintR)
  • G = (texG/255) ^ (256 - tintG)
  • B = (texB/255) ^ (256 - tintB)

Brightness

The SW renderer can change its Gamma correction values to compensate for dark displays or bright viewing conditions. You can set the screen brightness from 0-15 using the [S3E] Brightness ICF setting.

Set the gamma to 10 to give unbiased results. Set the gamma above 10 to brighten the materials or set the gamma below 10 to darken them.

To set the gamma correction value directly from your game, call IwGxSetGamma() with a parameter of 0 for very bright and 15 for dark.

Calling this function flushes all the palette caches (which is slow), so it should not be called every frame.

Texture Pages

When using the software renderer, uploading the textures moves them into specially allocated texture pages (T-pages). These are used for convenience in access and avoiding fragmentation. Each texture page is 256 bytes wide and 256 bytes high. This stores the following maximum texture sizes:

  • 512x256 at 4-bit
  • 256x256 at 8-bit
  • 128x256 at 16-bit.

However, when a larger texture is uploaded, the Texture page manager attempts to merge a number of T-pages to accommodate the large texture. This process should not concern the user except for one issue:

The larger textures will have the ability to tile restricted when compared to standard sized textures.

This means that artifacts might appear when using texture coordinates of greater than 1 or less than 0.

For example: a 256x256 16-bit texture will not tile correctly when using texture coordinates of 4.0 or greater.

Set the number of T-pages allocated by using the NumTPages parameter in the icf file. Each T-page is divided up into rectangles for simplicity. The maximum number of rectangles stored for free space is set using the icf file parameter NumTPageFreeRects. For convenience with analysing the packing of textures into the T-pages, the T-page usage can be output using CIwTexturePageManager::DumpTPages(). This displays the usage in a single bitmap named /TPageDump.bmp/ which is output to the root of the data directory.

Adding Transparencies

There is a fast path in the software renderer to accelerate additive transparencies. For example, to create the effect of a glow, use a 16-bit texture that fades from a light colour to black.

The colour progression must exist along the U-axis, and the V coordinate must not change.

EXAMPLE

Create a 32bit bitmap "Black2WhiteU.bmp" of dimensions 64x1.

The following code shows how the material should be defined within the .MTL file:

  • CIwMaterial
  • {
  • native16bit true
  • mapDiffuse "Black2WhiteU.bmp"
  • modulateMode NONE
  • shadeMode FLAT
  • alphaMode ADD
  • }

The UV coordinates should be of the form:

  • 0,0 0,0
  • 1,0 1,0

This would ensure that only one vertical pixel would be shown of the material at a time.

Yield Frequency

To assure that s3eDeviceYield() is called during the render stage, you can set the ICF setting [GX] PixelsDrawnBeforeYield. The default is set so that the devices which need more time for the OS behave well. To slightly speed up the renderer on a device that requires less time for the OS and therefore fewer yields increase this value above the default.

Minimising Build Size

It is possible to create smaller builds when not using some features of IwGx. This process is called Selective Linking. (For more details, see the Selective Linking page)

The software renderer provides an additional level of selective linking where individual scanloops can be eliminated. Scanloops are the highly optimised pixel programs that perform the actual rendering of individual scanlines. Typically each combination of texture, alpha mode, etc. needs its own scanloop, so there are very many more of them than any individual application will ever use. IwGx allows the program to only link those that have been used.

Which scanloops have ever been used by the application is tracked in a file called "iwgxscanloopusage.bin" (delete the file to start again). On shutdown IwGx writes a file called "iwgxinit_bespoke.cpp". To link only the scanloops used, include this CPP file in your project and call:

  • IwGxInit_Base();
  • IwGxInit_Bespoke();


Airplay SDK: Airplay Performance Guidelines

Airplay SDK > Whitepapers > Airplay Performance Guidelines >

Airplay Performance Guidelines

Contents

  • Introduction
  • General considerations
    • Software or OpenGL ES?
    • HW/SW Pipeline
    • General Performance Advice
  • Recommended Budgets
  • Optimising For Software
    • SW Pipeline
  • SW Rasteriser
    • Primitives
    • Other considerations
  • Optimising For Hardware

Introduction

This document provides an overview of how to achieve good performance on the various devices supported by Airplay Studio.

General considerations

Software or OpenGL ES

To a certain extent this decision will be made for you: if a device supports OpenGL ES then, generally, the performance in OpenGL ES is significantly better than it is using the software rasteriser. IwGx will select software rasterisation on devices where the accelerated driver is not usable for secondary reasons. For example, if the chipset generally does not beat software performance or requires significant other sacrifices (for example, it inter-operates badly with the OS).

HW/SW Pipeline

A number of OpenGL ES devices do not yet support hardware transform and lighting. On these devices, better performance can often be achieved using IwGx's software pipelines.

General Performance Advice

Less is cheaper.

Disable unused features. IwGx will do its best to use the fastest path available in any circumstance. You can help it do this by disabling unused features; for example, if your vertices do not need to be diffuse lit, disable diffuse lighting (or set the material diffuse contribution to zero).

Minimise the number of calls to IwGxDrawPrims(). Each call to IwGxDrawPrims() incurs a certain overhead. The user should try to minimise the number of materials in the scene, and create long geometry streams to minimise the number of calls to IwGxDrawPrims().

Minimise the number of unique materials in use, and use the same CIwMaterial object for all instances. For efficiency IwGx's batching and scene-optimisation work by pointer-equivalence, so to be indentified as using the same material two draw calls must have exactly the same material object.

Frustum-cull geometry as soon as possible. IwGx will cull individual polys as soon as it can, but these polys will generally need their associated vertices to be transformed before that can happen. The application can often use higher-level information to avoid submitting large amounts of geometry altogether; for example, by culling models using bounding spheres. IwGx provides a large number of utility functions to help you do this (See IwGxClip).

Use efficient texture formats. Palettised textures are smaller on disk and more efficient for software rendering. 4-bit (16 colour) palettised textures are the most efficient for the software renderer, followed by 8-bit (256 colour) palettised textures. Unpalettised textures are slower as they require a more expensive modulation path. Textures will be depalettised at upload time for OpenGL ES. Texture compression is generally both smaller and faster so should be used on OpenGL ES platforms that make it available.

Don’t use floating-point geometry types. The IwGx API is currently fixed-point only; however, the underlying IwGeom module supports floating-point geometry types. Don’t use these at all (and avoid any use of the “float” type) during the main application loop.

Of course all the general application rendering optimisations still apply; using level-of-detail models, etc.

Recommended Budgets
  • Device type
  • verts translated
  • cols calced
  • polys processed
  • polys rendered
  • pixel overdraw
  • frame rate
  • low end sw only
    (eg LG8000)
  • mid range sw only
    (eg Nokia N70)
  • OpenGL ES 1.x
    (eg iPhone, Nokia N95)
  • 1000
  • 1500
  • 5000
  • 1000
  • 1500
  • 15000
  • 450
  • 600
  • 5000**
  • 250
  • 400
  • 2500
  • 1.5*
  • 1.5*
  • -
  • 20
  • 20
  • 30

* This assumes the application is entirely covering the screen area 1.5 times with 'average' polys. If IwGxClear is used, the Pixel Overdraw will start from 1.0. This 1.0 is very cheap compared to most poly types. If expensive polytypes are being used then 1.5 may be too much. See “Relative costs of poly types” for more details.

** Models prepared for OpenGL ES will have more faces in general (since quads will be split).

Optimising For Software

SW Pipeline

Relevant Metrics: Verts Transformed and Cols Calculated.

Use screen space vertex streams instead of view/world/model space where possible.

Disable unnecessary lighting if it is not required, especially diffuse lighting. Diffuse lighting can be turned off in the following ways:

  • // EITHER
  • IwGxLightingDiffuse(false);
  • // OR
  • IwGxSetNormStream(NULL);

Less expensive modulation modes can be used if a material is not required to be fully lit. Often greyscale lighting is sufficient - MODULATE_R will only calculate the red component and copy it into the green and blue. It will also help the software rasteriser to perform more efficiently (see below).

If the material is not required to be lit at all (for example, a sky dome), material modulation mode MODULATE_NONE enables the lighting calculation to be completely bypassed.

Disable fog. IwGx supports vertex fog – but it is expensive.

SW Rasteriser

Relevant Metrics: Polys Rendered and Pixel Overdraw.

Typically, when using software rasterising, pixel overdraw is a better guide to performance than poly count. Also certain types of polys/primitives present the rasteriser with different loads.

Relative costs of poly types:

  • R Modulation
  • RGB Modulation
  • Texture Format
  • None
  • 4-bit
  • 4-bit chromakeyed*
  • 8-bit
  • 8-bit chromakeyed*
  • 16-bit
  • 16-bit chromakeyed*
  • Flat
  • always RGB
  • 0.85
  • 0.95
  • 0.80
  • 0.90
  • 1.25
  • 1.30
  • Gouraud
  • always RGB
  • 1.00
  • 1.10
  • 1.10
  • 1.32
  • 2.19
  • 2.00
  • Flat
  • 0.21
  • 1.65
  • 1.50
  • 1.65
  • 1.60
  • 1.50
  • 1.40
  • Gouraud
  • 0.87
  • 2.60
  • 2.30
  • 2.70
  • 2.67
  • 2.55
  • 2.40

* The exact performance of chroma-keyed polys will vary according to the amount of transparency in the texture

NB. If polys committed with a gouraud material are actually flat coloured, the renderer performance will be comparable with flat materials.

IwGx's software renderer is much faster at rendering primitives which do not require a full RGB modulation of texel colour by vertex colour. Often, “white lighting” is sufficient, in which case the material’s modulation mode can be set to MODULATE_R. In this case, only the red component of the calculated vertex colour is used to apply greyscale lighting to the texture.

Primitives

Use IW_GX_QUAD_STRIP and IW_GX_QUAD_LIST: IwGx supports the quadrilateral primitives IW_GX_QUAD_STRIP and IW_GX_QUAD_LIST (see AirplaySDK.chm for diagrams of the index mappings). IwGx’s software renderer is not restricted natively to triangles, so if the source geometry naturally maps to quads, performance is lost on software-rendering targets if the quads are preprocessed into tris.

IW_GX_QUAD_STRIP is actually the most efficient primitive of all, as on OpenGL ES 1.x targets the same index buffer can be passed through as a tri strip (again, you can see this from the index mapping diagrams).

Sprites are extremely fast, because no interpolation at all is required for them. Use them wherever possible.

Other considerations

Avoid Alpha Mode polys as much as possible: Additive/Subtractive/Blended polys cost approximately 1.25 times as much, half-blended polys about 1.2 times.

Because the rasteriser is scanline based, in general wide polys are cheaper than tall ones. Try to combine many adjacent vertical polys into a single one.

Optimising For Hardware

HW Pipeline/Rasteriser:

Relevant Metrics: Mats in Scene and Lists to HW.

In general, HW accelerated applications will be less limited by fillrate, so the volume of geometry will have a greater effect on the performance of the renderer.

GL devices are sensitive to the number of state changes and individual draw calls. IwGx will batch primitives with the same material to help with these requirements, but you should keep the number of materials down to minimise these factors.

Some GL devices carry a very large per-draw call overhead even if the gl state is not altered between calls. IwGx supports physical batching of multiple draw calls with the same material into a single draw call submission. To use this feature "MergeGeom" should be set on the material in question and the TnL pipeline must be set to software. This may require a large amount of memory and work. It is often more natural for the application to do this work. For example, you could use geometry merging to batch many individual particles into a single draw call, but it would be more efficient to build the particles into a single draw call on the application side.

Condition the assets for the target platform using per-platform build styles. While managing multiple assets sets adds deployment complexity, the rewards are often significant.


Airplay SDK: Airplay SDK – Optimisations for PowerVR

Airplay SDK > Whitepapers > Airplay SDK – Optimisations for PowerVR >

Airplay SDK – Optimisations for PowerVR

Contents

  • Introduction
  • Multi-texturing
  • Texture Compression
  • Full Screen Anti - Aliasing
  • Compiling for ARM11
  • Optimising Airplay SDK Examples

Introduction

This document outlines optimisations within the Airplay SDK which exploit key features of the Imagination Technologies PowerVR GPU design.

Multi-Texturing

The PowerVR GPU allows for 2-stage multi-texturing. This means that 2-stage effects such as light mapping, reflection mapping and normal mapping can be achieved in a single render pass, rather than using multiple passes.

IwGx’s material class (CIwMaterial) supports 2 texture stages, which are mapped directly to the texture stages in OpenGL ES 1.1. CIwMaterial also supports a definable blend mode between these stages.

For example, a text-file description of a material which uses a diffuse map and a light map might look like:

  • CIwMaterial
  • {
    • name “LightMapping”
    • texture0 “myDiffuseMap.bmp”
    • texture1 “myLightMap.bmp”
    • blendMode MODULATE
  • }

In addition, CIwMaterial provides the following “out of the box” preset effects; normal mapping (“dot3”) and reflection mapping.

A material which uses the preset normal mapping effect might look like:

  • CIwMaterial
  • {
    • name “NormalMapping”
    • texture0 “myDiffuseMap.bmp”
    • texture1 “myNormalMap.bmp”
    • vertexShader dot3_VGP
    • effectPreset NORMAL_MAPPING
  • }

See ExamplesIwGx_Effects for more details of preset effects.

Texture Compression

The PowerVR GPU natively supports a proprietary texture compression format known as PVRTC. Textures in this format are faster for the GPU to access, and take less memory than uncompressed RGB or RGBA textures.

Airplay supports PVRTC. There are two ways in which Airplay can be told to convert appropriate textures to PVRTC format:

  • When referencing images (BMP, GIF, PNG or TGA) in resource group files, a simple token is able to trigger conversion of the image into PVRTC format. For example:
    • IwResGroup
    • {
      • name "MyGroup"
      • "./textures/myTestTexture.bmp" { formatHW PVRTC_4 }
    • }

    If the source image meets the required conditions for the PVRTC compression algorithm (texture must be square, not too big or small, not using chromakeying, etc), it will be compressed prior to being uploaded to the OpenGL ES 1.1 drivers. It will also be serialised to disk in compressed form; i.e. the group.bin file will contain the compressed data (note that this only happens if the user is running in a “pure hardware” environment, so “Rasterisation=HW” in the user ICF file).

  • See AirplayAPIReference.chm > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Building a Data Set Optimised for a Specific Hardware Platform . This describes how a CIwResBuildStyle declaration can declare a "platform" to optimise the data set for. If specifying "IMG_MBX" or "IMG_MBX_VGP", then for that data set, all textures which meet the required conditions will be compressed with PVRTC.

See the BeatToy game example, and look at “res_templates.itx”.

Full Screen Anti-Aliasing

The PowerVR GPU supports two forms of full-screen anti-aliasing. The Airplay SDK supports both forms, as follows:

  • "Multi-sampling" anti-aliases in the horizontal direction only, and has no run-time performance cost. To make your application run with multi-sampling, add the following lines to your app.icf file:
    • [GL]
    • EGL_SAMPLE_BUFFERS=1
    • EGL_SAMPLES=2
  • "Super-sampling" anti-aliases in both horizontal and vertical directions. It incurs a small run-time performance cost. To make your application run with super-sampling, add the following lines to your app.icf file:
    • [GL]
    • EGL_SAMPLE_BUFFERS=1
    • EGL_SAMPLES=4

Compiling for ARM11

The PowerVR GPU is usually found next to an ARM CPU supporting at least the ARM v6 instruction set, and supporting a Vector Floating Point (VFP) unit for floating point operations.

Airplay libraries are built in different flavours, to support the varieties of ARM instruction set. By setting the 'arm-cpu' and 'arm-fpu' options in an MKB file, a project can be linked with Airplay libraries for the specified architecture.

Assuming the underlying chipset supports the ARMv6 instruction set and a VFP unit, then the optimal build settings are:

  • options
  • {
    • arm-cpu=6
    • arm-fpu=vfp
  • }

See the MKB documentation for more details.

Optimising Airplay SDK Examples

The Airplay SDK Examples contain a configuration file (“app.icf”) which is set up to enable examples to run on the “base specification” handset supported by the SDK. This configuration file is therefore set up to configure IwGx to perform transform, lighting and rasterisation all in software; it is also set up NOT to attempt any form of Full Screen Anti-Aliasing.

Each app.icf file contains the following sections, which can easily be tailored to allow the SDK Examples to run optimally on the PowerVR GPU:

  • # Uncomment this line to switch Rasterisation (and by default, Transform and Lighting also) to the GL drivers, and build resources for GL
  • #Rasterisation=HW

  • # Uncomment this section to use full-screen anti-aliasing.
  • #[GL]
  • #EGL_SAMPLE_BUFFERS=1
  • #EGL_SAMPLES=4 # Use super-sampling if available