Airplay SDK > Airplay API Reference >

Airplay API Reference

This document describes each of the APIs that make up the SDK.

The documentation for each API contains an overview, which describes its purposes and main concepts, and accompanying Examples and API Reference sections. These demonstrate how the API can be used in practice and provide an in-depth reference listings respectively.

See the Overview for a brief explanation of the API sets included and how to use the documentation for them.

  • API Reference Overview

  • S3E API Documentation
  • Derbh API Documentation
  • IwUtil API Documentation
  • IwGeom API Documentation
  • IwGx API Documentation
  • Iw2D API Documentation
  • IwResManager API Documentation
  • IwGraphics API Documentation
  • IwAnim API Documentation
  • IwGxFont API Documentation
  • IwHTTP API Documentation
  • IwUI API Documentation

  • Data Structures
  • Class Hierarchy
  • Namespace List
  • Namespace Members
  • Data Fields
(c) 2009 Ideaworks Labs. All rights reserved.


Airplay API Reference: API Reference Overview

Airplay API Reference > API Reference Overview >

API Reference Overview

API Modules

The Airplay APIs are divided into various modules, each of which provides the interface for a specific area of functionality. The APIs can also be divided between Airplay System and Airplay Studio (see Overview of Airplay).

Airplay System (S3E)

The S3E (Segundo Embedded Execution Environment) is a low level, entirely C-based API which provides abstraction from the underlying operating system. The functions which make up the API are split into subdevices which cover distinct types of tasks, for example audio, surface interaction, file IO, etc.

Airplay Studio (Iw*)

The other modules, named Iw*, provide higher-level functionality for tasks such as building models, 2D and 3D graphics, animation and resource handling, as well as providing general utility functions. These modules use C++ object-oriented interfaces.

Documentation Structure

The documentation for each Airplay module contains the three following sections:

  • Overview: This section contains a discursive description of the API; it outlines the purpose of the API and provides details and descriptions of how the API can be used.
  • API Reference: This section describes all the functions and classes contained within the API.
  • Examples: This section contains a set of examples that illustrate the scope of the API functionality. Each example has been created to showcase a major part of that APIs functionality. The examples, in most cases, are graduated in their level of complexity so they can be more easily understood.

The exception to this format is the S3E API description, which contains an Overview, Example section and Reference section for each of its subdevices.

Recommended Documentation Reading Order

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. The following list shows the order in which you should approach the API documentation:

  1. S3E: Provides an understanding of how to abstract application code from the underlying device OS. The S3E documentation should be your starting point; it is on top of this API that everything is built.
  2. Both of the following, in any order:
    • IwGeom: Provides an understanding of the low-level geometry structures and functions. These are used heavily by the higher level graphics APIs, and are also intended for direct use by developers.
    • IwUtil: Provides an understanding of the low-level C++ base classes used by all higher-level Airplay Studio modules, such as the generation of hash numbers, memory management and text parsing. These are also intended for direct use (usually by sub-classing) by developers.
  3. For 2D Applications Iw2D: Provides an understanding of Airplay Studio's simplified 2D API.
  4. For 3D Applications IwGx: Provides an understanding of geometry streams (vertices, vertex normals, colours, texture coordinates), textures, materials, and the transformation, lighting and rasterisation pipelines.
  5. IwResManager: Provides an understanding of the resource management framework used by all Airplay Studio modules. Textures, materials, models, animations and fonts are all managed in this way. Developers can also use this framework to manage their own resource classes.
  6. IwGxFont: Provides an understanding of the creation and management of bitmap fonts.
  7. IwGraphics: Provides an understanding of the creation, management and rendering of 3D models (meshes).

    NOTE: It may be of merit to read the documentation on the Airplay Studio Exporters to understand what items are exported and how they are exported.

  8. IwAnim: Provides an understanding of skinned/boned animation.
  9. Derbh: Reading the documentation for this API will allow you to understand how Airplay handles the compression of assets.
  10. Additional self contained modules:
    • IwHTTP: Provides an interface for performing HTTP requests.


Airplay API Reference: S3E API Documentation

Airplay API Reference > S3E API Documentation >

S3E API Documentation

The Segundo Embedded Execution Environment provides a means for rapid development of mobile applications across multiple platforms.

It is based on a low-level, simple API which provides abstraction from the underlying operating system. It supports a single binary format for ARM-based devices, providing a build-once, run-anywhere methodology; thus, enabling fast porting across handsets.

S3E supports the Windows environment, which means development can be done under Windows with full debugger support.

The S3E Windows environment is built to match the device environment as closely as possible, reducing the scope for errors caused by the differences between Windows and the device.

The S3E API is designed to be a minimal, low-level API for application development. It is entirely C-based and divided up into devices, such as Surface (Screen), Keyboard and Sound. A low-level API enables the developer to write platform-independent code easily, and at the same time still be able to account for the differences between device platforms.

The S3E environment also supports the C Runtime standard library.For each supported platform there is a debug and release version of S3E. The debug version aids development by displaying error messages and debugger output. The release version is built for performance and size reasons.

  • S3E Accelerometer
  • S3E Audio
  • S3E Compression
  • S3E Configuration
  • S3E Crypto Collection
  • S3E Debug
  • S3E Device Interface
  • S3E Extensions
  • S3E File
  • S3E GL
  • S3E Keyboard
  • S3E Licensing
  • S3E Location
  • S3E Memory
  • S3E Pointer
  • S3E Secure Storage
  • S3E Socket
  • S3E Sound
  • S3E Surface
  • S3E Timer
  • S3E Types
  • S3E Vibra
  • S3E Video


Airplay API Reference: S3E Accelerometer

Airplay API Reference > S3E API Documentation > S3E Accelerometer >

S3E Accelerometer

The S3E Accelerometer documentation contains the following sections:

  • S3E Accelerometer Overview
  • Accelerometer API Reference
  • S3E Accelerometer Examples


Airplay API Reference: S3E Accelerometer Overview

Airplay API Reference > S3E API Documentation > S3E Accelerometer > S3E Accelerometer Overview >

S3E Accelerometer Overview

The accelerometer produces three integer values corresponding the X, Y and Z axis. These axes are defined as follows:

  • The X and Y axes are in the same plane as the device's screen.
  • The X axis runs across the screen and will record increasing values when the phone is moved to the user's left.
  • The Y axis runs up/down the screen and will record increasing values when the phone is moved away from the user.
  • The Z axis is perpendicular to the plane of the screen and will record increasing values when the phone is moved downwards

The magnitude of the acceleration vector will be 0 when the device is experiencing no acceleration and 1000 when the device is experiences only the gravitational pull of the planet. Thus a magnitude of 3000 corresponds to 3G (3x gravitational force).

The definition of 'across' and 'up/down' the screen are according to how the user would normally be holding the device. Therefore if the device screen changes orientation, the accelerometer axes will also change. Thus the application should not normally have to rotate accelerometer coordinates if the screen rotates.

Note: For an example of how the Accelerometer functionality can be used, see the S3E Accelerometer Examples.

For more information on the functionality outlined in this section, see the Accelerometer API Reference.


Airplay API Reference: Accelerometer API Reference

Airplay API Reference > S3E API Documentation > S3E Accelerometer > Accelerometer API Reference >

Accelerometer API Reference
[S3E]

Enumerations

enum | s3eAccelerometerError
enum | s3eAccelerometerProperty

Functions

S3E_API s3eAccelerometerError | s3eAccelerometerGetError ()
S3E_API const char * | s3eAccelerometerGetErrorString ()
S3E_API int32 | s3eAccelerometerGetX ()
S3E_API int32 | s3eAccelerometerGetY ()
S3E_API int32 | s3eAccelerometerGetZ ()
S3E_API s3eResult | s3eAccelerometerStart ()
S3E_API void | s3eAccelerometerStop ()

Detailed Description

The accelerometer produces three integer values corresponding the X, Y and Z axis. The X and Y axes are in the same plane as the device's screen. The X axis runs across the screen and will record increasing values when the phone is moved to the user's left. The Y axis runs up/down the screen and will record increasing values when the phone is moved away from the user. The Z axis is perpendicular to the plane of the screen and will record increasing values when the phone is moved downwards.

The definition of 'across' and 'up/down' the screen are according to how the user would normally be holding the device. Therefore if the device screen changes orientation, the accelerometer axes will also change. Thus the application should not normally have to rotate accelerometer coordinates if the screen rotates.

The magnitude of the acceleration vector will be 0 when the device is experiencing no acceleration and 1000 when the device is experiences only the gravitational pull of the planet. Thus a magnitude of 3000 corresponds to 3G (3x gravitational force).

Enumeration Type Documentation

enum s3eAccelerometerError

Accelerometer Errors.

See also:
s3eAccelerometerGetError

s3eAccelerometerGetErrorString

Required Header Files
s3eAccelerometer.h
Enumerator:
S3E_ACCELEROMETER_ERR_NONE | No Error.
S3E_ACCELEROMETER_ERR_PARAM | Invalid parameter.
S3E_ACCELEROMETER_ERR_UNAVAIL | ACCELEROMETER is unavailable.

enum s3eAccelerometerProperty

Accelerometer Properties

Required Header Files
s3eDevice.h

Function Documentation

S3E_API s3eAccelerometerError s3eAccelerometerGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3ePointerGetErrorString
Required Header Files
s3eAccelerometer.h

S3E_API const char* s3eAccelerometerGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eAccelerometerGetError
Required Header Files
s3eAccelerometer.h

S3E_API int32 s3eAccelerometerGetX ( )

Gets the current X acceleration.

Required Header Files
s3eAccelerometer.h

S3E_API int32 s3eAccelerometerGetY ( )

Gets the current Y acceleration.

Required Header Files
s3eAccelerometer.h

S3E_API int32 s3eAccelerometerGetZ ( )

Gets the current Z acceleration.

Required Header Files
s3eAccelerometer.h

S3E_API s3eResult s3eAccelerometerStart ( )

Starts the accelerometer if it is available. The accelerometer will not start generating data until this function is called. This is because, on some platforms, running the accelerometer uses power and therefore is not enabled by default.

Required Header Files
s3eAccelerometer.h

S3E_API void s3eAccelerometerStop ( )

Stop the accelerometer. Future calles to s3eAccelerometerGetX/Y/Z will fail.

Required Header Files
s3eAccelerometer.h


Airplay API Reference: S3E Accelerometer Examples

Airplay API Reference > S3E API Documentation > S3E Accelerometer > S3E Accelerometer Examples >

S3E Accelerometer Examples

This section illustrates how you can use the Accelerometer functionality provided with S3E. This section contains one example application:

  • S3E Accelerometer Example

Note: For more information on the S3E Accelerometer functionality, see the S3E Accelerometer Overview.


Airplay API Reference: S3E Accelerometer Example

Airplay API Reference > S3E API Documentation > S3E Accelerometer > S3E Accelerometer Examples > S3E Accelerometer Example >

S3E Accelerometer Example

The following example demonstrates S3E's accelerometer functionality.

The main functions used to achieve this are:

  • s3eAccelerometerStart()
  • s3eAccelerometerStop()
  • s3eAccelerometerGetX()
  • s3eAccelerometerGetY()
  • s3eAccelerometerGetZ()

The example allows the user to stop and start the accelerometer subdevice and displays the last reported X, Y & Z values it generated.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleS3EAccelerometer
//-----------------------------------------------------------------------------

#include "ExamplesMain.h"
#include "Logo.h"
#include "s3eAccelerometer.h"
#include <math.h>

static bool g_Enabled = false;
static Button* g_ButtonStart = NULL;
static Button* g_ButtonStop = NULL;
static Button* g_ButtonRotate = NULL;

void ExampleInit()
{
    g_ButtonStart = NewButton("Start Accelerometer");
    g_ButtonStop = NewButton("Stop Accelerometer");
    g_ButtonRotate = NewButton("Rotate");
    g_ButtonStart->m_Enabled = true;
    g_ButtonStop->m_Enabled = false;
    if (s3eAccelerometerStart() == S3E_RESULT_SUCCESS)
    {
        g_Enabled = true;
        g_ButtonStart->m_Enabled = false;
        g_ButtonStop->m_Enabled = true;
    }
}

void ExampleShutDown()
{
    s3eAccelerometerStop();
}

bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    // Press 1 to play.
    if (pressed == g_ButtonStart)
    {
        if (s3eAccelerometerStart() == S3E_RESULT_SUCCESS)
        {
            g_Enabled = true;
            g_ButtonStart->m_Enabled = false;
            g_ButtonStop->m_Enabled = true;
        }
    }

    if (pressed == g_ButtonStop)
    {
        s3eAccelerometerStop();

        g_Enabled = false;
        g_ButtonStart->m_Enabled = true;
        g_ButtonStop->m_Enabled = false;
    }

    if (pressed == g_ButtonRotate)
    {
        int dir = s3eSurfaceGetInt(S3E_SURFACE_BLIT_DIRECTION);
        dir += 1;
        dir = dir % 4;
        s3eSurfaceSetup(S3E_SURFACE_PIXEL_TYPE_RGB565, 0, NULL, (s3eSurfaceBlitDirection)dir);
        LogoShutDown();
        LogoInit();
    }
    return true;
}

static void DrawLineHoriz(int x, int y, int length, int16 color)
{
    int16* ptr = (int16*)s3eSurfacePtr();
    int32 pitch = s3eSurfaceGetInt(S3E_SURFACE_PITCH)/2;
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);

    if (length < 0)
    {
        for (int32 x1 = x; x1 > x+length; x1--)
        {
            if (x1 > width || x1 < 0)
                return;
            ptr[y*pitch+x1] = color;
        }
    }
    else
    {
        for (int32 x1 = x; x1 < x+length; x1++)
        {
            if (x1 > width || x1 < 0)
                return;
            ptr[y*pitch+x1] = color;
        }
    }
}

//-----------------------------------------------------------------------------
// The ExampleRender function outputs a set of strings indicating the state of
// playback. The additional output that can occur outputs whether the callback
// was registered successfully or not.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int ypos = GetYBelowButtons() + textHeight * 2;

    //Displaying status
    if (g_Enabled)
    {
        int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
        int32 x = s3eAccelerometerGetX();
        int32 y = s3eAccelerometerGetY();
        int32 z = s3eAccelerometerGetZ();
        //Calculate magnitude as square root of squares of the components
        float mag = (float)sqrt((x*x) + (y*y) + (z*z));
        s3eDebugPrintf(10, ypos, 1, "`x666666X: %3ld Y: %3ld Z: %ld", x, y, z);
        ypos += textHeight;
        s3eDebugPrintf(10, ypos, 1, "`x666666Magnitude: %.2f", mag);
        ypos += 2 * textHeight;
        DrawLineHoriz(width/2, ypos, x, (int16)s3eSurfaceConvertRGB(0xff, 0, 0));
        ypos += textHeight;
        DrawLineHoriz(width/2, ypos, y, (int16)s3eSurfaceConvertRGB(0, 0xff, 0));
        ypos += textHeight;
        DrawLineHoriz(width/2, ypos, z, (int16)s3eSurfaceConvertRGB(0, 0, 0xff));
        ypos += textHeight;
    }
    else
    {
        s3eDebugPrintf(10, ypos, 1, "`x666666Accelerometer disabled");
    }
}


Airplay API Reference: S3E Audio

Airplay API Reference > S3E API Documentation > S3E Audio >

S3E Audio

The S3E Audio documentation contains the following sections:

  • S3E Audio Overview
  • Audio API Reference
  • S3E Audio Examples


Airplay API Reference: S3E Audio Overview

Airplay API Reference > S3E API Documentation > S3E Audio > S3E Audio Overview >

S3E Audio Overview

The Audio Module is an API for playing compressed audio data. It plays an assortment of file types including MP3, QCP and AAC. The file types that a platform supports can be queried at run-time using s3eAudioIsCodecSupported(). The functionality included allows you to play audio from a buffer or from a file, it also lets you pause, resume, stop and query whether audio is playing.

The Audio callback mechanism allows you to register or unregister functions that will be called when certain events occur. Callbacks can be registered and unregistered using the s3eAudioRegister() and s3eAudioUnRegister() functions respectively.

Note: For an example of how the Audio functionality can be used, see the S3E Audio Examples.

For more information on the functionality outlined in this section, see the Audio API Reference.


Airplay API Reference: Audio API Reference

Airplay API Reference > S3E API Documentation > S3E Audio > Audio API Reference >

Audio API Reference
[S3E]

Data Structures

struct | s3eAudioCallbackData

Enumerations

enum | s3eAudioCallback { S3E_AUDIO_STOP = 2 }
enum | s3eAudioCodec
enum | s3eAudioError
enum s3eAudioProperty {
S3E_AUDIO_VOLUME = 0,
S3E_AUDIO_STATUS = 1,
S3E_AUDIO_POSITION = 2,
S3E_AUDIO_VOLUME_DEFAULT = 3,
S3E_AUDIO_CHANNEL = 4,
S3E_AUDIO_NUM_CHANNELS = 5
}
enum s3eAudioStatus {
S3E_AUDIO_STOPPED = 0,
S3E_AUDIO_PLAYING = 1,
S3E_AUDIO_PAUSED = 2,
S3E_AUDIO_FAILED = 3
}

Functions

S3E_API s3eAudioError | s3eAudioGetError ()
S3E_API const char * | s3eAudioGetErrorString ()
S3E_API int32 | s3eAudioGetInt (s3eAudioProperty property)
S3E_API s3eBool | s3eAudioIsCodecSupported (s3eAudioCodec codec)
S3E_API s3eBool | s3eAudioIsPlaying ()
S3E_API s3eResult | s3eAudioPause ()
S3E_API s3eResult | s3eAudioPlay (const char *filename, uint32 repeatCount)
S3E_API s3eResult | s3eAudioPlayFromBuffer (void *buffer, uint32 bufferLen, uint32 repeatCount)
S3E_API s3eResult | s3eAudioRegister (s3eAudioCallback cbid, s3eCallback fn, void *userData)
S3E_API s3eResult | s3eAudioResume ()
S3E_API s3eResult | s3eAudioSetInt (s3eAudioProperty property, int32 value)
S3E_API void | s3eAudioStop ()
S3E_API s3eResult | s3eAudioUnRegister (s3eAudioCallback cbid, s3eCallback fn)

Detailed Description

For more information on the Audio functionality provided by the S3E module, see the S3E Audio Overview section of the S3E API Documentation.

Define Documentation

#define S3E_AUDIO_MAX_VOLUME (0x100)

Maximum audio volume allowed (minimum is 0).

Enumeration Type Documentation

enum s3eAudioCallback

Audio Callbacks. The following callback types can be registered to enable user notification of audio events.

See also:
s3eAudioRegister, s3eAudioUnRegister
Required Header Files
s3eAudio.h
Enumerator:
S3E_AUDIO_STOP This callback is called whenever audio playing stops.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData The systemData paramater passed to this callback will either be NULL or a pointer to a s3eAudioCallbackData structure. If it is NULL, assume the channel number is 0 (this happens on platforms which only support one channel)
Returns:
No return value is expected from a callback registered using this enumeration.
Remarks:
It is not called between repetitions of a single track. It is called if audio playback begins successfully but later fails due to an error. This callback will be called from within s3eAudioStop(), and may be called from within s3eVideoPlay() if video playback overrides audio playback. It may also be called in s3eDeviceYield() if external events or data corruption cause audio playback to fail.

enum s3eAudioCodec

Audio codecs.

Required Header Files
s3eAudio.h
Enumerator:
S3E_AUDIO_CODEC_MIDI | MIDI files.
S3E_AUDIO_CODEC_MP3 | MP3 files.
S3E_AUDIO_CODEC_AAC | AAC files.
S3E_AUDIO_CODEC_AACPLUS | AAC plus files.
S3E_AUDIO_CODEC_QCP | QCP files.
S3E_AUDIO_CODEC_PCM | PCM files.
S3E_AUDIO_CODEC_SPF | SPF files.
S3E_AUDIO_CODEC_AMR | AMR files.

enum s3eAudioError

Audio Errors.

See also:
s3eAudioGetError

s3eAudioGetErrorString

Required Header Files
s3eAudio.h
Enumerator:
S3E_AUDIO_ERR_NONE | No error.
S3E_AUDIO_ERR_PARAM | Invalid parameter.
S3E_AUDIO_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_AUDIO_ERR_ALREADY_REG | The specified callback is already registered.
S3E_AUDIO_ERR_NOT_FOUND | File not found / The specified callback was not found for removal.
S3E_AUDIO_ERR_UNAVAIL | Audio is unavailable.
S3E_AUDIO_ERR_DEVICE | Audio device failed.
S3E_AUDIO_ERR_UNSUPPORTED | The action requested is not supported.
S3E_AUDIO_ERR_MEM | Out of operating system memory during operation.
S3E_AUDIO_ERR_INVALID_DRIVE | Invalid/unsupported drive specified in path.
S3E_AUDIO_ERR_INVALID_PATH | The path could not be resolved onto the device filesytem (e.g. opening ROM://../file).
S3E_AUDIO_ERR_FILEFORMAT | File format not supported.
S3E_AUDIO_ERR_WRONG_STATE | Attempting to pause audio when its not playing, or resume audio when its not paused.

enum s3eAudioProperty

Audio Properties.

See also:
s3eAudioGetInt

s3eAudioSetInt

Required Header Files
s3eAudio.h
Enumerator:
S3E_AUDIO_VOLUME | [read,write] Audio device volume. This volume applies only to the audio device, and can be set before or during audio playback.
S3E_AUDIO_STATUS | [read] Status - returns one of s3eAudioStatus. This parameter cannot be set.
S3E_AUDIO_POSITION | [read] Position - Current playing position of the audio track in milliseconds. Returns zero if no audio is playing.
S3E_AUDIO_VOLUME_DEFAULT [read] Default audio volume. The property S3E_AUDIO_VOLUME is set to this value on startup.

This value is in .8 fixed point format, 0x100 (S3E_AUDIO_MAX_VOLUME) is the maximum possible default volume.

This value is device-dependent, so that the result of playing audio at default volume produces the same audible result across all devices.

S3E_AUDIO_CHANNEL | [read,write] Audio channel number. Defaults to 0. Cannot be set higher than S3E_AUDIO_NUM_CHANNELS
S3E_AUDIO_NUM_CHANNELS | [read] Return the number of available audio channels. On most platforms this is 1.

enum s3eAudioStatus

Audio status.

Required Header Files
s3eAudio.h
Enumerator:
S3E_AUDIO_STOPPED | Stopped after playing or no play command issued yet. It is the initial status and does not gurantee the validity of the audio device.
S3E_AUDIO_PLAYING | Audio is playing.
S3E_AUDIO_PAUSED | Paused during play.
S3E_AUDIO_FAILED | Error occurred during play. Note, if the call to Play fails before audio playback begins, the call to s3eAudioPlay() will fail and S3E_AUDIO_STATUS will be set to S3E_AUDIO_STOPPED rather than S3E_AUDIO_FAILED. The audio status may change to failed only following an attempt to play an audio.

Function Documentation

S3E_API s3eAudioError s3eAudioGetError ( )

Retrieves the last error, if any, for this subdevice.

Returns:
One of the errors specified in s3eAudioError.
See also:
s3eAudioGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eAudio.h

S3E_API const char* s3eAudioGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This funtion is only available in debug builds.

See also:
s3eFileGetError.
Remarks:
This function, as opposed to s3eAudioGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eAudio.h

S3E_API int32 s3eAudioGetInt ( s3eAudioProperty property )

Retrieves an integer value representing an audio property on this subdevice.

Parameters:
property The audio property to return.
Returns:
  • The value of the requested property if property is valid.
  • -1 if the property is not valid. Call s3eAudioGetError() to retrieve an error code. This will return: S3E_AUDIO_ERR_PARAM if property is not valid.
See also:
s3eAudioSetInt
Required Header Files
s3eAudio.h

S3E_API s3eBool s3eAudioIsCodecSupported ( s3eAudioCodec codec )

Query whether or not the given codec is supported. This gives the user application the ability to choose a media file that the device is capable of playing. The are many variations of file format for each codec and if s3eAudioIsCodecSupported() returns S3E_TRUE for a given codec, it is not guaranteed that every variation can be played.

Parameters:
codec s3eAudioCodec enumeration.
Returns:
S3E_TRUE if S3E is capable of playing files belonging to this codec, S3E_FALSE otherwise.
Required Header Files
s3eAudio.h

S3E_API s3eBool s3eAudioIsPlaying ( )

Query whether audio is playing

Returns:
S3E_TRUE if audio is playing, S3E_FALSE otherwise. This is equivalent to the expression s3eAudioGetInt(S3E_AUDIO_STATUS) == S3E_AUDIO_PLAYING, i.e. if audio is stopped, paused or has failed, this will return S3E_FALSE.
Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioPause ( )

Pauses any currently playing audio track.

Remarks:
The sound device used by the s3eSound interface will remain silenced whilst the audio file is in paused state. Note that any call to s3eAudioPlay(), s3eAudioPlayFromBuffer(), s3eVideoPlay() or s3eVideoPlayFromBuffer() will stop the audio track, even if it is in paused state. If the audio successfully enters paused state, the status subsequently returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will be S3E_AUDIO_PAUSED.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve the error code. This will return one of:
    • S3E_AUDIO_ERR_DEVICE if the underlying audio device failed.
    • S3E_AUDIO_ERR_WRONG_STATE if audio is not playing.
See also:
s3eAudioResume

s3eAudioPlay

s3eAudioStop

Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioPlay | ( | const char * | filename,
 |  | uint32 | repeatCount
 | ) |  |

Plays an audio file from the file system.

Parameters:
filename | Name of file to play.
repeatCount | one of the following values: 0 = Play forever, 1 = Play once, >1 = Play a certain number of times.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve the error code. This will return one of:
    • S3E_AUDIO_ERR_PARAM if filename is NULL.
    • S3E_AUDIO_ERR_INVALID_DRIVE if filename specifies an invalid drive.
    • S3E_AUDIO_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
    • S3E_AUDIO_ERR_NOT_FOUND if filename specifies a file that does not exist.
    • S3E_AUDIO_ERR_DEVICE if the underlying audio device failed.
    • S3E_AUDIO_ERR_FILEFORMAT if the format of filename is not recognised by the device.
    • S3E_AUDIO_ERR_MEM if the operating system ran out of memory attempting to play the file.
    • S3E_AUDIO_ERR_UNAVAIL if no audio playback functionality is available.
Remarks:
This function waits until audio playback starts before returning. The audio status returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will return S3E_AUDIO_PLAYING immediately after s3eAudioPlay() returns.

The name and extension of filename need not bear any relation to the format of the file; S3E will automatically use any available audio codec.

s3eAudioPlay() will not succeed on files that exist on file systems registered by s3eFileAddUserFileSys().

If audio is already playing, this function behaves as if s3eAudioStop() were called just before the call to s3eAudioPlayFromBuffer(). This means the current audio track will stopped and a S3E_AUDIO_STOP callback will be issued before the new track begins playing.

If the S3E_AUDIO_STOP callback attempts to play an audio track, this track will be stopped without an additional S3E_AUDIO_STOP callback.

If video is playing, the video will be stopped and a S3E_VIDEO_STOP callback will be sent.

If audio playback fails at any stage after playback has started (for example, due to a corrupted file) the S3E_AUDIO_STOP callback will be sent and the status returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will go to S3E_AUDIO_FAILED.

The sound device used by the s3eSound interface will be silenced whilst the audio file is playing. The sound device will however keep playing and continue issuing callbacks etc.

See also:
s3eAudioPlayFromBuffer
Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioPlayFromBuffer | ( | void * | buffer,
 |  | uint32 | bufferLen,
 |  | uint32 | repeatCount
 | ) |  |

Plays an audio file from buffer.

Parameters:
buffer | Pointer to the data to play. This data must remain valid until audio play is complete.
bufferLen | Length of the data buffer.
repeatCount | one of the following values: 0 = Play forever, 1 = Play once, >1 = Play a certain number of times.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve the error code. This will return one of:
    • S3E_AUDIO_ERR_PARAM if buffer is NULL or bufferLen is 0.
    • S3E_AUDIO_ERR_DEVICE if the underlying audio device failed.
    • S3E_AUDIO_ERR_FILEFORMAT if the format of filename is not recognised by the device.
    • S3E_AUDIO_ERR_MEM if the operating system ran out of memory attempting to play the buffer.
    • S3E_AUDIO_ERR_UNAVAIL if no audio playback functionality is available.
Remarks:
This function waits until audio playback starts before returning. The audio status returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will return S3E_AUDIO_PLAYING immediately after s3eAudioPlay() returns.

The contents of the buffer supplied in buffer must not be overwritten until audio play is complete.

S3E will automatically use any available audio codec to play the data in buffer.

If audio is already playing, this function behaves as if s3eAudioStop() were called just before the call to s3eAudioPlayFromBuffer(). This means the current audio track will stopped and a S3E_AUDIO_STOP callback will be issued before the new track begins playing.

If the S3E_AUDIO_STOP callback attempts to play an audio track, this track will be stopped without an additional S3E_AUDIO_STOP callback.

If video is playing, the video will be stopped and a S3E_VIDEO_STOP callback will be sent.

If audio playback fails at any stage after playback has started (for example, due to corrupted data) the S3E_AUDIO_STOP callback will be sent and the status returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will go to S3E_AUDIO_FAILED.

The sound device used by the s3eSound interface will be silenced whilst the audio file is playing. The sound device will however keep playing and continue issuing callbacks etc.

See also:
s3eAudioPlay
Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioRegister | ( | s3eAudioCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Registers a callback for a given event. The available callback types are listed in s3eAudioCallback.

Parameters:
cbid | ID of the callback for which to register.
fn | callback function.
userData | Value to pass to the userData paramater of fn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve an error code. This will return one of:
    • S3E_AUDIO_ERR_PARAM if cbid is not a valid member of s3eAudioCallback or fn is NULL.
    • S3E_AUDIO_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_AUDIO_ERR_ALREADY_REG If (cbid, fn) has already been registered.
Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eAudioCallback enum.

It is not necessary to define a return value for any registered callback.

Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioResume ( )

Resumes the currently paused audio track.

Remarks:
If the audio successfully resumes playing, the status subsequently returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will be S3E_AUDIO_PLAYING.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve the error code. This will return one of:
    • S3E_AUDIO_ERR_DEVICE if the underlying audio device failed .
    • S3E_AUDIO_ERR_WRONG_STATE if audio is not paused.
See also:
s3eAudioPause

s3eAudioPlay

s3eAudioStop

Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioSetInt | ( | s3eAudioProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | audio proprety to set.
value | value to set the property to.
See also:
s3eAudioGetInt
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve an error code. This will return: S3E_AUDIO_ERR_PARAM if property is invalid or value is invalid.
Remarks:
Note that when setting volume via the S3E_AUDIO_VOLUME property, the volume will be clipped to the range [0, S3E_AUDIO_MAX_VOLUME (0x100)].
See also:
s3eAudioGetInt
Required Header Files
s3eAudio.h

S3E_API void s3eAudioStop ( )

Stops any currently playing audio track. If audio is playing, this will stop audio playback and then send the S3E_AUDIO_STOP callback. The audio status returned by s3eAudioGetInt(S3E_AUDIO_STATUS) will go to S3E_AUDIO_STOPPED. The sound device used by the s3eSound interface will be un-muted.

See also:
s3eAudioPlay

s3eAudioPause

s3eAudioResume

Required Header Files
s3eAudio.h

S3E_API s3eResult s3eAudioUnRegister | ( | s3eAudioCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eAudioGetError() to retrieve an error code. This will return one of:
    • S3E_AUDIO_ERR_PARAM if cbid is not a valid member of s3eAudioCallback, or fn is NULL.
    • S3E_AUDIO_ERR_NOT_FOUND if fn is not registered for callback cbid.
Required Header Files
s3eAudio.h


Airplay API Reference: S3E Audio Examples

Airplay API Reference > S3E API Documentation > S3E Audio > S3E Audio Examples >

S3E Audio Examples

This section illustrates how you can use the Audio functionality provided with S3E. This section contains two example applications:

  • S3E Audio Basic Example
  • S3E Audio Advanced Example

Note: For more information on the S3E Audio functionality, see the S3E Audio Overview.


Airplay API Reference: S3E Audio Basic Example

Airplay API Reference > S3E API Documentation > S3E Audio > S3E Audio Examples > S3E Audio Basic Example >

S3E Audio Basic Example

The following example plays a music file using S3E's audio functionality.

The main functions used to achieve this are:

  • s3eDebugPrint()
  • s3eKeyboardGetState()
  • s3eAudioPlay()
  • s3eAudioPause()
  • s3eAudioResume()
  • s3eAudioStop()

The application waits for buttons to be pressed before using any of the Audio functionality. Detection of button presses are handled using the generic code in ExamplesMain.cpp

The state of playback is output to screen using the s3eDebugPrint() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//----------------------------------------------------------------------------
// ExampleS3EAudioBasic
//----------------------------------------------------------------------------

#include "ExamplesMain.h"

enum PlayerState
{
    kPlaying,
    kPaused,
    kStopped
};

static PlayerState g_Status = kStopped;        //player status information
static Button* g_ButtonPlay = 0;
static Button* g_ButtonPause = 0;
static Button* g_ButtonResume = 0;
static Button* g_ButtonStop = 0;
static s3eBool g_MP3Supported = S3E_FALSE;

void ExampleInit()
{
    g_ButtonPlay    = NewButton("Play");
    g_ButtonPause   = NewButton("Pause");
    g_ButtonResume  = NewButton("Resume");
    g_ButtonStop    = NewButton("Stop");

    g_MP3Supported = s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_MP3);
}

void ExampleShutDown()
{
    s3eAudioStop();
}

//-----------------------------------------------------------------------------
// If a button has been pressed then start/pause/resume/stop playback.
//
// The other code in the function is in place to make sure the application
// exits cleanly once the escape or "left shoulder" button has been pressed.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (!g_MP3Supported)
        return true;

    if (pressed == g_ButtonPlay && (g_Status == kStopped))
    {
        if (s3eAudioPlay("test.mp3", 0) == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    if (pressed == g_ButtonPause && (g_Status == kPlaying))
    {
        if (s3eAudioPause() == S3E_RESULT_SUCCESS)
            g_Status = kPaused;
    }

    if (pressed == g_ButtonResume && (g_Status == kPaused))
    {
        if (s3eAudioResume() == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    if (pressed == g_ButtonStop)
    {
        s3eAudioStop();
        g_Status = kStopped;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs a set of strings. A switch is used to
// output a string indicating the status. Each string is output using the
// s3eDebugPrint() function.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    g_ButtonPlay->m_Enabled = (g_Status == kStopped);
    g_ButtonPause->m_Enabled = (g_Status == kPlaying);
    g_ButtonResume->m_Enabled = (g_Status == kPaused);
    g_ButtonStop->m_Enabled = (g_Status == kPlaying);

    int ypos = GetYBelowButtons() + textHeight * 2;

    //Displaying status
    if (g_MP3Supported)
    {
        switch (g_Status)
        {
            case kPlaying:
                s3eDebugPrint(10, ypos, "`x666666Music Playing", 0);
                break;
            case kPaused:
                s3eDebugPrint(10, ypos, "`x666666Music Paused", 0);
                break;
            case kStopped:
                s3eDebugPrint(10, ypos, "`x666666Music Stopped", 0);
                break;
        }
    }
    else
    {
        s3eDebugPrint(10, ypos, "`x666666Device does not support mp3 playback", 0);
    }
}


Airplay API Reference: S3E Audio Advanced Example

Airplay API Reference > S3E API Documentation > S3E Audio > S3E Audio Examples > S3E Audio Advanced Example >

S3E Audio Advanced Example

The following example plays a music file using S3E's audio functionality.

The main functions used to achieve this are:

  • s3eAudioPlayFromBuffer()
  • s3eFileOpen()
  • s3eFileRead()
  • s3eAudioResume()
  • s3eFileGetSize()
  • s3eMallocBase()
  • s3eAudioPause()
  • s3eAudioResume()
  • s3eAudioStop()

The example builds on the AudioBasic example by playing the music from buffer using the s3eAudioPlayFromBuffer() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleS3EAudioAdvanced
//-----------------------------------------------------------------------------

#include "ExamplesMain.h"

enum PlayerState
{
    kPlaying,
    kPaused,
    kStopped
};

static PlayerState g_Status = kStopped;
static void*   g_AudioData;
static int32   g_AudioSize;
static Button* g_ButtonPlay = 0;
static Button* g_ButtonPause = 0;
static Button* g_ButtonResume = 0;
static Button* g_ButtonStop = 0;
static s3eBool g_MP3Supported = S3E_FALSE;

//-----------------------------------------------------------------------------
// The following function opens a file and reads it using the the s3eFileOpen()
// and s3eFileRead() functions. The s3eFileGetSize() function is used to obtain
// the length of the file that is to be read in. This result is the used by the
// s3eMallocBase() function to reserve the right amount of memory for that file.
//-----------------------------------------------------------------------------

void ExampleInit()
{
    // Allocating buffer for audio data
    s3eFile * FileHandle = s3eFileOpen("test.mp3", "rb");
    g_AudioSize = s3eFileGetSize(FileHandle);
    g_AudioData = s3eMallocBase(g_AudioSize);

    // Reading in audio data
    s3eFileRead(g_AudioData, g_AudioSize, 1, FileHandle);

    s3eFileClose(FileHandle);

    g_ButtonPlay    = NewButton("Play");
    g_ButtonPause   = NewButton("Pause");
    g_ButtonResume  = NewButton("Resume");
    g_ButtonStop    = NewButton("Stop");

    g_MP3Supported = s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_MP3);
}

//-----------------------------------------------------------------------------
// The following function frees memory that was alocated during the example.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    s3eAudioStop();
    s3eFree(g_AudioData);
}

//-----------------------------------------------------------------------------
// The following function changes the state of playback based on which button was
// pressed (if any).
//
// The difference between this example and AudioBasic is that this
// example uses s3eAudioPlayFromBuffer() function is used to play the music
// file from buffer.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (!g_MP3Supported)
        return true;

    // Press 1 to play.
    if (pressed == g_ButtonPlay && g_Status == kStopped)
    {
        if (s3eAudioPlayFromBuffer(g_AudioData, g_AudioSize, 0) == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    // Press 2 to pause.
    if (pressed == g_ButtonPause && g_Status == kPlaying)
    {
        if (s3eAudioPause() == S3E_RESULT_SUCCESS)
            g_Status = kPaused;
    }

    // Press 3 to resume.
    if (pressed == g_ButtonResume && g_Status == kPaused)
    {
        if (s3eAudioResume() == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    // Press 4 to stop.
    if (pressed == g_ButtonStop && g_Status != kStopped)
    {
        s3eAudioStop();
        g_Status = kStopped;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The ExampleRender function outputs a set of strings indicating the state of
// playback. The additional output that can occur outputs whether the callback
// was registered successfully or not.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    g_ButtonPlay->m_Enabled = (g_Status == kStopped);
    g_ButtonPause->m_Enabled = (g_Status == kPlaying);
    g_ButtonResume->m_Enabled = (g_Status == kPaused);
    g_ButtonStop->m_Enabled = (g_Status != kStopped);

    int ypos = GetYBelowButtons() + textHeight * 2;

    if (!g_MP3Supported)
    {
        s3eDebugPrint(10, ypos, "`x666666Device does not support mp3 playback", 0);
        return;
    }

    //Displaying status
    switch (g_Status)
    {
        case kPlaying:
            s3eDebugPrint(10, ypos, "`x666666Music Playing", 0);
            break;
        case kPaused:
            s3eDebugPrint(10, ypos, "`x666666Music Paused", 0);
            break;
        case kStopped:
            s3eDebugPrint(10, ypos, "`x666666Music Stopped", 0);
            break;
    }
}


Airplay API Reference: S3E Compression

Airplay API Reference > S3E API Documentation > S3E Compression >

S3E Compression

The S3E Compression documentation contains the following sections:

  • S3E Compression Overview
  • Compression API Reference
  • S3E Compression Examples


Airplay API Reference: S3E Compression Overview

Airplay API Reference > S3E API Documentation > S3E Compression > S3E Compression Overview >

S3E Compression Overview

The Compression Module performs decompression of data. The decompression functionality allows you to choose the decompression algorithm used. You can choose either GZIP or ZLIB.

The functionality allows you to decompress data in chucks; therefore, allowing you to decompress data in a stream-like fashion.

Note: For an example of how the Compression functionality can be used, see the S3E Compression Examples.

For more information on the functionality outlined in this section, see the Compression API Reference.


Airplay API Reference: Compression API Reference

Airplay API Reference > S3E API Documentation > S3E Compression > Compression API Reference >

Compression API Reference
[S3E]

Data Structures

struct | s3eDecompressionInput

Typedefs

typedef struct
s3eDecompressionHandle 		s3eDecompressionHandle

Enumerations

enum s3eCompressionAlgorithms { ,
S3E_COMPRESSION_ALG_ZLIB = 2,
S3E_COMPRESSION_ALG_GZIP = 3,
S3E_COMPRESSION_ALG_LZMA = 4
}
enum | s3eCompressionError

Functions

S3E_API s3eResult | s3eCompressionDecomp (void *bufferIn, uint32 lenIn, void **bufferOut, uint32 *lenOut, s3eCompressionAlgorithms algorithm)
S3E_API s3eResult | s3eCompressionDecompFinal (s3eDecompressionHandle *handle)
S3E_API s3eDecompressionHandle * | s3eCompressionDecompInit (s3eCompressionAlgorithms alg, s3eCallback inputFn, void *userData)
S3E_API s3eResult | s3eCompressionDecompRead (s3eDecompressionHandle *handle, void *bufferOut, uint32 *lenOut)
S3E_API s3eCompressionError | s3eCompressionGetError ()
S3E_API const char * | s3eCompressionGetErrorString ()

Detailed Description

For more information on the Compression functionality provided by the S3E module, see the S3E Compression section of the S3E API Documentation.

Define Documentation

#define S3E_DECOMPRESSION_MAX_HANDLES 4

Maximum number of s3eDecompressionHandle* handles available for use.

Typedef Documentation

typedef struct s3eDecompressionHandle s3eDecompressionHandle

Handle for use with s3eCompressionDecompInit(), s3eCompressionDecompRead() and s3eCompressionDecompFinal()

Enumeration Type Documentation

enum s3eCompressionAlgorithms

Compression algorithms.

Enumerator:
S3E_COMPRESSION_ALG_ZLIB | ZLIB compression using inflate/deflate. This differs from GZIP compression in that gzip headers will not be parsed or output. This compression method cannot read data output by GZIP
S3E_COMPRESSION_ALG_GZIP | GZIP compression using inflate/deflate and gzip headers. This differs from ZLIB compression in that gzip headers will be parsed or output. This compression method can read data output by GZIP.
S3E_COMPRESSION_ALG_LZMA | LZMA algorithm This will decompress a stream output from the lzma tool (part of the 7-zip SDK)

enum s3eCompressionError

Compression/Decompression Errors.

See also:
s3eCompressionGetError

s3eCompressionGetErrorString

Enumerator:
S3E_COMPRESSION_ERR_NONE | No error.
S3E_COMPRESSION_ERR_PARAM | Invalid parameter.
S3E_COMPRESSION_ERR_TOO_MANY | Maximum number of decompression handles exceeded.
S3E_COMPRESSION_ERR_DEVICE | The underlying system-specific device failed.
S3E_COMPRESSION_ERR_MEM | Out of memory performing operation.
S3E_COMPRESSION_ERR_BAD_DATA | Compressed data is corrupted or invalid.
S3E_COMPRESSION_ERR_INSUFF | The output buffer supplied to compress/decompress was too small.

Function Documentation

S3E_API s3eResult s3eCompressionDecomp | ( | void * | bufferIn,
 |  | uint32 | lenIn,
 |  | void ** | bufferOut,
 |  | uint32 * | lenOut,
 |  | s3eCompressionAlgorithms | algorithm
 | ) |  |

Decompress a buffer

Parameters:
bufferIn | buffer of input data to decompress
lenIn | length of input data to decompress
[in,out] | bufferOut | pointer to output data buffer. On input, *bufferOut should be NULL or a valid buffer. If *bufferOut is NULL on input, then on output *bufferOut will be set to a newly allocated memory buffer containing the compressed data.
[in,out] | lenOut | pointer to length of output data buffer. On input, if *bufferOut is not NULL then *lenOut must be set to the length of the buffer *bufferOut. If *bufferOut is NULL, lenOut can be NULL. On output, *lenOut will be set to the number of bytes written to *bufferOut
algorithm | algorithm to use for decompression
Returns:
  • S3E_RESULT_SUCCESS if no error occurred
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eCompressionGetError() to retrieve an error code. This will return one of:
    • S3E_COMPRESSION_ERR_PARAM for an invalid parameter condition: bufferIn or bufferOut is NULL, lenIn is zero, algorithm is invalid, or *bufferOut is non-NULL and *lenOut is zero.
    • S3E_COMPRESSION_ERR_BAD_DATA if the compressed data cannot be read by the decompressor
    • S3E_COMPRESSION_ERR_MEM if the function fails to allocate the required output buffer
    • S3E_COMPRESSION_ERR_DEVICE if the underlying compression device failed
Remarks:
This function allows decompression into either a user-allocated memory buffer or via a memory buffer allocated by the function. To supply a user-allocated memory buffer, set bufferOut and lenOut to point to a buffer and its length respectively. To make the function allocate a memory buffer, set bufferOut to point to NULL. The user should free this buffer after use with a call to s3eFree().

The function will decompress data into the output buffer. If a user-allocated buffer has been supplied it will decompress up to *lenOut bytes of data. If a function-allocated buffer is used it will attempt to decompress all the compressed data.

If a user-allocated buffer is used and *lenOut is not long enough to hold the entire decompressed buffer, *lenOut bytes will be written to *bufferOut and the function will return success. On success the number of bytes decompressed will be written to *lenOut.
On error the output buffer will be left in an undetermined state. *lenOut and *bufferOut will not be written to.
When used with an lzma-compressed stream, this function will call s3eMalloc and s3eFree internally to allocate workspace memory. The amount of memory allocated will usually be the stream dictionary size plus approximately 17k.

See also:
s3eCompressionDecompInit

s3eCompressionDecompRead

s3eCompressionDecompFinal

Required Header Files
s3eCompression.h

S3E_API s3eResult s3eCompressionDecompFinal ( s3eDecompressionHandle * handle )

Ends decompression of a stream of data

Parameters:
handle handle returned from s3eDecompressionDecompInit()
Returns:
  • S3E_RESULT_SUCCESS if no error occurred
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eCompressionGetError() to retrieve an error code. This will return one of:
    • S3E_COMPRESSION_ERR_PARAM for an invalid parameter condition: if handle is invalid
Remarks:
This function frees all resources associated with decompressing a stream. handle will no longer be valid for calls to s3eCompressionDecompRead() after this function has been called.
See also:
s3eCompressionDecompInit

s3eCompressionDecompRead

Required Header Files
s3eCompression.h

S3E_API s3eDecompressionHandle* s3eCompressionDecompInit | ( | s3eCompressionAlgorithms | alg,
 |  | s3eCallback | inputFn,
 |  | void * | userData
 | ) |  |

Begins the decompression of a stream of data

Parameters:
alg | algorithm to use for decompression
inputFn | function pointer for a callback to retrieve input data
userData | user data that will be passed to the outputFn callback
Returns:
  • A valid handle if no error occurred
  • NULL if the operation failed.
    Call s3eCompressionGetError() to retrieve an error code. This will return one of:
    • S3E_COMPRESSION_ERR_PARAM for an invalid parameter condition: if alg is invalid or inputFn is NULL.
    • S3E_COMPRESSION_ERR_DEVICE if the underlying decompression device failed
    • S3E_COMPRESSION_ERR_TOO_MANY if maximum number of decompression handles has been reached
    • S3E_COMPRESSION_ERR_MEM If memory could not be allocated for decompression
    • S3E_COMPRESSION_ERR_BAD_DATA if there was an error whilst beginning to decompress the stream
Remarks:
Call this function to begin the decompression of data in a stream-like fashion using the algorithm specified by alg. The handle returned should be passed to s3eCompressionDecompRead() to begin data decompression.

When the decompressor requires input data inputFn will be called.
When used with an lzma-compressed stream, this function will call s3eMalloc to allocate workspace memory. The amount of memory allocated will usually be the stream dictionary size plus approximately 17k. This memory is free'd by s3eCompressionDecompFinal

See s3eCompressionDecompRead() for how to use the callback.
Call s3eCompressionDecompFinal() to free the handle returned in handle.
See also:
s3eCompressionDecompInit

s3eCompressionDecompRead

s3eCompressionDecompFinal

Required Header Files
s3eCompression.h

S3E_API s3eResult s3eCompressionDecompRead | ( | s3eDecompressionHandle * | handle,
 |  | void * | bufferOut,
 |  | uint32 * | lenOut
 | ) |  |

This function decompresses part of a stream of data.

Parameters:
handle | Handle returned from s3eCompressionDecompInit()
bufferOut | Output buffer for decompressed data.
See also:
s3eCompressionDecompInit

s3eCompressionDecompRead

s3eCompressionDecompFinal

Parameters:
[in,out] lenOut
  • input: a pointer to number of bytes of output requested (bufferOut must be large enough). The function will fail if this is zero.
  • output: the number of bytes written to bufferOut. This will equal lenOut unless the end of the stream is reached or an error occurrs
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eCompressionGetError() to retrieve an error code This will return one of:
    • S3E_COMPRESSION_ERR_PARAM for an invalid parameter condition: if handle is invalid or bufferOut is NULL.
    • S3E_COMPRESSION_ERR_DEVICE if the underlying decompression device failed.
    • S3E_COMPRESSION_ERR_BAD_DATA if the compressed data cannot be read by the decompressor.
    • S3E_COMPRESSION_ERR_INSUFF if not enough input data was supplied to complete decompression.
Remarks:
This function decompresses compressed data in a stream-like manner. The compressor requests input data via the callback passed to s3eCompressionDecompInit() and writes decompressed data to bufferOut. The compressor requests input data until lenOut bytes have been written to bufferOut, end-of-stream occurs or an error occurrs. If the end of the compressed stream is reached the function will return S3E_RESULT_SUCCESS.

When the compressor requires input data, the callback passed to s3eCompressionDecompInit() will be called. The systemData paramater to the callback will point to a s3eDecompressionInput structure, which contains a pointer to output data in its m_Data member and the size of the data in its m_Size member.

The callback should fill m_Data with m_Size bytes of data. If it cannot fill m_Data (e.g., if the end of the compressed stream is reached), then if should write as much data as possible into m_Data and return the number of bytes written. The decompressor assumes there is no more input data if the callback returns < m_Size bytes of data. If the input data is exhausted before the end of the compressed stream, S3E_COMPRESSION_ERR_INSUFF will result.

Call s3eCompressionDecompFinal() to free handle once all desired decompressed data has been read, or an error has occurred.
See also:
s3eCompressionDecompInit

s3eCompressionDecompFinal

Required Header Files
s3eCompression.h

S3E_API s3eCompressionError s3eCompressionGetError ( )

Retrieves the last error, if any, for the Compression module.

See also:
s3eCompressionGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eCompression.h

S3E_API const char* s3eCompressionGetErrorString ( )

Retrieve the last error as a string, if any, for the Compression module. This is only available in debug builds.

See also:
s3eCompressionGetError
Remarks:
This function, as opposed to s3eCompressionGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eCompression.h


Airplay API Reference: S3E Compression Examples

Airplay API Reference > S3E API Documentation > S3E Compression > S3E Compression Examples >

S3E Compression Examples

This section describes how you can use the compression functionality provided with S3E. S3E allows you to compress or decompress data in one swoop. You can also decompress data in discrete parts; therefore, minimising the amount of space taken up in memory by the compressed version of the data.

This section contains one example application:

  • S3E Compression Basic Example

Note: For more information on the S3E Compression functionality, see the Compression API Reference


Airplay API Reference: S3E Compression Basic Example

Airplay API Reference > S3E API Documentation > S3E Compression > S3E Compression Examples > S3E Compression Basic Example >

S3E Compression Basic Example

This example decompresses a text file and prints the decompressed text to screen.

The main functions used to achieve this are:

  • s3eCompressionDecomp()
  • s3eFree()

The ExampleInit() function opens and reads in the compressed contents of the specified file. This means the file must first be opened and loaded into a buffer, and this is done using S3E IO functionality.

Note:
For more information on using the S3E IO functionality, see S3E File IO or the File System section of the S3E API Reference documentation.
The ExampleUpdate() function waits for a button to be pressed before calling s3eCompressionDecomp(). This function decompresses the data contained in an input buffer and then writes it to an output buffer.

ExampleUpdate() outputs the example controls and the contents of the the specified file once it has been decompressed.

ExampleShutDown() uses the s3eFree() function to free the buffers used in the application before it exits.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

static void*   g_BufferPointer;                // Contains compressed data
static char*   g_OutBufferPointer;             // Contains decompressed data
static char*   g_Output;                       // Contains colour specifier and decompressed data
static char    g_ErrorString[256] = {'\0'};    // Contains error info for displaying

static uint32  g_FileSize;                     // Size of comressed data file
static bool    g_OutputContents = false;       // Set when output needs to be printed
static uint32  g_OutputDataSize = 1000;        // Size of uncompressed data
static Button* g_ButtonDecompress = 0;

//-----------------------------------------------------------------------------
// The following function opens and reads in the compressed contents of the
// specified file.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Read in compressed file
    s3eFile * FileHandle = s3eFileOpen("test.txt.gz", "rb");
    g_FileSize = s3eFileGetSize(FileHandle);
    g_BufferPointer = s3eMallocBase(g_FileSize);

    // Reading in compressed data
    s3eFileRead(g_BufferPointer, g_FileSize, 1, FileHandle);

    s3eFileClose(FileHandle);

    g_OutBufferPointer = (char *)s3eMallocBase(g_OutputDataSize);
    g_Output = (char *)s3eMallocBase(g_OutputDataSize+8);

    g_ButtonDecompress = NewButton("Decompress file");
}

//-----------------------------------------------------------------------------
// The following function uses the s3eFree() function to free the buffers used
// in the applictation before it exits.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Freeing data buffers
    s3eFree(g_OutBufferPointer);
    s3eFree(g_BufferPointer);
    s3eFree(g_Output);
}

//-----------------------------------------------------------------------------
// The following function checks the state of the keyboard for input. If the
// s3eKey1 has been pressed, it creates a buffer for the decompressed data.
// The s3eCompressionDecomp() function is called, which takes the compressed
// data, decompresses it and puts it into the new output buffer.
//
// If there is no keyboard, the pointer state is checked instead.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if ((pressed == g_ButtonDecompress) && g_OutputContents == false)
    {
        // Initialise buffer space for decompressed data
        memset(g_OutBufferPointer, 0, g_OutputDataSize);

        // The s3eCompressionDecomp() function is used to decompress a compressed txt
        // file and place the contents of that file into a buffer.
        if (s3eCompressionDecomp(g_BufferPointer, g_FileSize, (void**)&g_OutBufferPointer, &g_OutputDataSize, S3E_COMPRESSION_ALG_GZIP) == S3E_RESULT_ERROR)
        {
            // An error occurred, update error string for displaying
            strcpy(g_ErrorString, s3eCompressionGetErrorString());
        }
        else
        {
            memset(g_Output, 0, g_OutputDataSize+8);

            // decompression successful
            g_OutputContents = true;

            strcpy(g_Output, "`x666666");
            strcat(g_Output, g_OutBufferPointer);
        }
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs the example controls and the contents of the
// specified file (should it have been decompressed) to the screen.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int ypos = GetYBelowButtons() + textHeight * 2;

    // Display contents
    if (g_OutputContents == true)
    {
        s3eDebugPrint(10, ypos, "`x666666Contents:", 0);

        ypos += textHeight;

        s3eDebugPrint(10, ypos, g_Output, 1);
    }

    ypos += textHeight * 3;

    s3eDebugPrint(10, 10 * textHeight, g_ErrorString, 1);
}


Airplay API Reference: S3E Configuration

Airplay API Reference > S3E API Documentation > S3E Configuration >

S3E Configuration

The S3E Configuration documentation contains the following sections:

  • S3E Configuration Overview
  • Configuration API Reference
  • S3E Configuration Examples


Airplay API Reference: S3E Configuration Overview

Airplay API Reference > S3E API Documentation > S3E Configuration > S3E Configuration Overview >

S3E Configuration Overview

The Configuration module provides a simple text parser for reading in Airplay configuration files. Airplay configuration files, or ICF files, are similar to Windows .ini files, with [group] marking the start of a settings group, and var=value assigning settings within that group.

ICF files provide a flexible way of configuring different behaviour at runtime based on a range of conditions. Settings such as memory heap size, key binding, screen size and so on can be altered and these may be condition on factors such as which OS or device the application is running on. ICF settings are defined for variables across each Airplay module. They support conditional statements, settings based on the values of other statements and custom user settings.

Note: For detailed information on using ICF files and settings, see the ICF Files section of Airplay Concepts.

For an example of how the Configuration functionality can be used, see the S3E Configuration Examples.

For more information on the functionality outlined in this section, see the Configuration API Reference.

For more information on settings that can be configured using this functionality, see ICF Settings.


Airplay API Reference: Configuration API Reference

Airplay API Reference > S3E API Documentation > S3E Configuration > Configuration API Reference >

Configuration API Reference
[S3E]

Defines

#define | S3E_CONFIG_STRING_MAX 256

Enumerations

enum | s3eConfigError

Functions

S3E_API s3eConfigError | s3eConfigGetError ()
S3E_API const char * | s3eConfigGetErrorString ()
S3E_API s3eResult | s3eConfigGetInt (const char *group, const char *name, int *value)
S3E_API s3eResult | s3eConfigGetString (const char *group, const char *name, char *value)

Detailed Description

For more information on the Configuration functionality provided by the S3E module, see the S3E Configuration section of the S3E API Documentation.

Define Documentation

#define S3E_CONFIG_STRING_MAX 256

The maximum length of a variable name or value used in s3eConfigGetInt or s3eConfigGetString, including the null terminator. Any names or values longer than this in the icf file will be truncated.

Enumeration Type Documentation

enum s3eConfigError

Config Errors.

See also:
s3eConfigGetError

s3eConfigGetErrorString

Required Header Files
s3eConfig.h
Enumerator:
S3E_CONFIG_ERR_NONE | No Error.
S3E_CONFIG_ERR_PARAM | Invalid parameter.
S3E_CONFIG_ERR_NOT_FOUND | Requested configuration value not found.
S3E_CONFIG_ERR_PARSE | Config value could not be parsed as an integer.

Function Documentation

S3E_API s3eConfigError s3eConfigGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eConfigGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it * from memory; therefore, any further calls to this function will not return * an error unless a subsequent error has occurred.
Required Header Files
s3eConfig.h

S3E_API const char* s3eConfigGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eConfigGetError
Remarks:
This function, as opposed to s3eConfigGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eConfig.h

S3E_API s3eResult s3eConfigGetInt | ( | const char * | group,
 |  | const char * | name,
 |  | int * | value
 | ) |  |

Gets a configuration setting as an integer from the group/name.

Parameters:
group | Group string name.
name | Variable string name.
value | Stores configuration setting integer. The variable value is only modified if the setting is found.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eConfigGetError() to retrieve the error code. This will return one of:
    • S3E_CONFIG_ERR_PARAM if any of group, name or value are NULL.
    • S3E_CONFIG_ERR_NOT_FOUND if the [group] name configuration setting was not found in the .icf files
    • S3E_CONFIG_ERR_PARSE if the string for this setting cannot be parsed as an integer
Remarks:
This function first reads the configuration value as a string, then attempts to intpret it as an integer. The strings 'true' and 'on' will be converted to integer value 1. The strings 'false' and 'off' will be converted to 0. A string of the form 0x<number>, e.g., 0x1000, will be parsed as a hexadecimal integer. Otherwise the string will be parsed as decimal integer.
Note:
If the setting is not found or some error occurs, value is not changed. If the setting is found value is set to be the recovered integer or the integer as it has been interpreted.
See also:
s3eConfigGetString

S3E_API s3eResult s3eConfigGetString | ( | const char * | group,
 |  | const char * | name,
 |  | char * | value
 | ) |  |

Gets a configuration setting as a string from the given group and name.

Parameters:
group | Group string name.
name | Variable string name.
value | Is set to the recovered configuration string.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eConfigGetError() to retrieve the error code. This will return one of:
    • S3E_CONFIG_ERR_PARAM if any of group, name or value are NULL.
    • S3E_CONFIG_ERR_NOT_FOUND if the [group] name configuration setting was not found in the .icf files
Remarks:
value should be large enough to store the entire value. The maximum size of a value is S3E_CONFIG_STRING_MAX (256) bytes
Note:
If the string is not found or some error occurs, value is not changed.
See also:
s3eConfigGetInt
Required Header Files
s3eConfig.h


Airplay API Reference: S3E Configuration Examples

Airplay API Reference > S3E API Documentation > S3E Configuration > S3E Configuration Examples >

S3E Configuration Examples

This section illustrates how you can use the configuration functionality provided with S3E. This section contains one example application:

  • S3E Configuration Example

Note: For more information on the S3E Configuration functionality, see the S3E Configuration Overview.


Airplay API Reference: S3E Configuration Example

Airplay API Reference > S3E API Documentation > S3E Configuration > S3E Configuration Examples > S3E Configuration Example >

S3E Configuration Example

This example reads the application .icf file and prints out the desired value to screen.

The main functions used to achieve this are:

  • s3eConfigGetString()

The ExampleInit() function uses the s3eConfigGetString() function to query the application icf file for the specified setting, which in the case of our example is the memory size of the application heap.

The ExampleRender() function outputs the value that is gained from the s3eConfigGetString() to screen.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

static char g_DisplayString[S3E_CONFIG_STRING_MAX] = {'\0'};

//-----------------------------------------------------------------------------
// The following function gets the required configuration variable using the
// s3eConfigGetString() function.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    char TempString[S3E_CONFIG_STRING_MAX+8] = {'\0'};

    if (s3eConfigGetString("FooSection", "BarSetting", TempString) == S3E_RESULT_ERROR)
    {
        //An error occurred during reading of the configuration file
        strcpy(g_DisplayString, "`x666666");                    //Make the string grey
        strcat(g_DisplayString, s3eConfigGetErrorString());
    }
    else
    {
        //Reading of configuration successful
        strcpy(g_DisplayString, "`x666666");        //Make the string grey
        strcat(g_DisplayString, TempString);        //Add the result of s3eConfigGetString
    }
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs the value of the queried configuration
// variable using the s3eDebugPrint() function.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textWidth = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_WIDTH);
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    //Displaying info
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    s3eDebugPrint(  (width-strlen("The current FooSetting is:")*textWidth)/2,
                    5 * textHeight, "`x666666The current FooSetting is:", 0);
    s3eDebugPrint(  (width-(strlen(g_DisplayString)-8)*textWidth)/2,
                    7 * textHeight, g_DisplayString, 0);
}


Airplay API Reference: S3E Crypto Collection

Airplay API Reference > S3E API Documentation > S3E Crypto Collection >

S3E Crypto Collection

The S3E Crypto Collection documentation contains the following sections:

  • S3E Crypto Collection Overview
  • Cyrpto Collection API Reference


Airplay API Reference: S3E Crypto Collection Overview

Airplay API Reference > S3E API Documentation > S3E Crypto Collection > S3E Crypto Collection Overview >

S3E Crypto Collection Overview

The Crypto Collection Module is used to carry out message signature generation and verification. The functions contained in the module use the Secure Hash Algorithm, SHA-1, to compute the message signature. This process is carried out as follows:

  • The message is converted into a 20 byte SHA-1 hash, which is called a message digest.
  • The message digest has a Digital Signature Algorithm (DSA) applied to it, using a generated key to produce the message signature.
  • The received message can now be verified by ensuring the received signature matches the supplied hash and key.
  • The 32 bit key is produced using the s3eCryptoRand() function.
  • The message data is converted into a 20 byte SHA-1 hash, or message digest, using the s3eCryptoSha1() function.
  • The signature is progressively produced using the s3eCryptoSha1Init(), s3eCryptoSha1Update() and s3eCryptoSha1Final() functions.
  • Verification that the signature matches the hash and key is carried out using the s3eCryptoVerifyRsa() function.

Note: For more information on the functionality outlined in this section, see the Crypto Collection API Reference.


Airplay API Reference: Crypto Collection API Reference

Airplay API Reference > S3E API Documentation > S3E Crypto Collection > Crypto Collection API Reference >

Crypto Collection API Reference
[S3E]

Enumerations

enum | s3eCryptoError

Functions

S3E_API s3eCryptoError | s3eCryptoGetError ()
S3E_API const char * | s3eCryptoGetErrorString ()
S3E_API uint32 | s3eCryptoRand ()
S3E_API s3eResult | s3eCryptoSha1 (const uint8 *data, uint32 dataLen, uint8 *hash)
S3E_API s3eResult | s3eCryptoSha1Final (s3eSHA1 *ctx, uint8 *hash)
S3E_API s3eSHA1 * | s3eCryptoSha1Init ()
S3E_API s3eResult | s3eCryptoSha1Update (s3eSHA1 *ctx, const uint8 *data, uint32 dataLen)
S3E_API s3eResult | s3eCryptoVerifyRsa (uint8 *sig, int sigLen, uint8 *hash, int hashLen, uint8 *mod, int modLen, uint8 *exp, int expLen)

Detailed Description

For more information on the Crypto Collection functionality provided by the S3E module, see the S3E Crypto Collection section of the S3E API Documentation.

Define Documentation

#define S3E_CRYPTO_MAX_SHA1_HANDLES 4

The maximum number of simultaneous SHA1 hashing contexts supported by S3E.

Typedef Documentation

typedef struct s3eSHA1 s3eSHA1

Abstract SHA1 pointer type.

Enumeration Type Documentation

enum s3eCryptoError

Crypto Errors.

See also:
s3eCryptoGetError

s3eCryptoGetErrorString

Required Header Files
s3eCrypto.h
Enumerator:
S3E_CRYPTO_ERR_NONE | No Error.
S3E_CRYPTO_ERR_PARAM | Invalid parameter.
S3E_CRYPTO_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_CRYPTO_ERR_DEVICE | The underlying crypto device failed.
S3E_CRYPTO_ERR_INVALID_SIG | Crypto RSA signature verification failed, signature could not be read.
S3E_CRYPTO_ERR_SIG_CHECK | Crypto RSA signature verification failed, signature check failed.

Function Documentation

S3E_API s3eCryptoError s3eCryptoGetError ( )

Retrieve the last error, if any, for this subdevice.

See also:
s3eCryptoGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eCrypto.h

S3E_API const char* s3eCryptoGetErrorString ( )

Retrieve the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eCryptoGetError
Remarks:
This function, as opposed to s3eCryptoGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eCrypto.h

S3E_API uint32 s3eCryptoRand ( )

Generates a 32-bit random bit pattern suitable for crypto usage. This will generate different things every time the program is run.

Note: that the exact quality of this number may be low on some platforms. Don't use it for generating high-value keys.

Returns:
32-bit random bit pattern.
Required Header Files
s3eCrypto.h

S3E_API s3eResult s3eCryptoSha1 | ( | const uint8 * | data,
 |  | uint32 | dataLen,
 |  | uint8 * | hash
 | ) |  |

Fills hash with the 20-byte SHA1 hash of the supplied data.

Parameters:
data | Pointer to the source data buffer. This can be NULL, in which case the hash of a zero-length input will be returned.
dataLen | Length of the source data buffer in bytes. This can be zero, in which case the hash of a zero-length input will be returned.
hash | Pointer to the 20-byte destination buffer to write the SHA1 hash.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eConfigGetError() to retrieve the error code. This will return one of:
    • S3E_CONFIG_ERR_PARAM if hash is NULL
Required Header Files
s3eCrypto.h

S3E_API s3eResult s3eCryptoSha1Final | ( | s3eSHA1 * | ctx,
 |  | uint8 * | hash
 | ) |  |

Finishes a hashing operation, returns the 20 byte hash and clears all used resources.

Parameters:
ctx | A hash context returned from s3eCryptoSha1Init.
hash | Pointer to hash result. Must point to 20 bytes of storage or be NULL.
Remarks:
hash must be NULL or point to a 20-byte storage area. If hash is NULL the s3eSHA1 object is destroyed without generating a SHA1 result.
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eCryptoGetError() to retrieve an error code. This will return one of:
    • S3E_CRYPTO_ERR_PARAM if ctx is invalid
Required Header Files
s3eCrypto.h

S3E_API s3eSHA1* s3eCryptoSha1Init ( )

Creates a context for incremental SHA1 hashing

Returns:
  • A non-zero s3eSHA1 pointer if no error occurred.
  • NULL if the operation failed.
    Call s3eCryptoGetError() to retrieve an error code. This will return one of:
    • S3E_CRYPTO_ERR_TOO_MANY If the maximum number of s3eSHA1 handles has been exceeded.
Remarks:
Pass the result from this function onto s3eCryptoSha1Update() to incrementally calculate the SHA1 hash of a block of data. Call s3eCryptoSha1Final() to free the s3eSHA1 object and return the hash.
Required Header Files
s3eCrypto.h

S3E_API s3eResult s3eCryptoSha1Update | ( | s3eSHA1 * | ctx,
 |  | const uint8 * | data,
 |  | uint32 | dataLen
 | ) |  |

Adds some data for incremental hashing.

Parameters:
ctx | A hash context returned from s3eCryptoSha1Init().
data | Pointer to data to be hashed. If this is NULL, the function does nothing.
dataLen Byte length of data to be hashed. If this is 0, the function does nothing.
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eCryptoGetError() to retrieve an error code. This will return one of:
    • S3E_CRYPTO_ERR_PARAM if ctx is invalid.
Remarks:
If dataLen is 0, this function will return S3E_RESULT_SUCCESS.
Required Header Files
s3eCrypto.h

S3E_API s3eResult s3eCryptoVerifyRsa | ( | uint8 * | sig,
 |  | int | sigLen,
 |  | uint8 * | hash,
 |  | int | hashLen,
 |  | uint8 * | mod,
 |  | int | modLen,
 |  | uint8 * | exp,
 |  | int | expLen
 | ) |  |

Verifies a PKCS1 RSA signature matches the supplied hash and public key.

Parameters:
sig | The signature, in PKCS#1 format.
sigLen | Length of the signature, in bytes.
hash | A Hash of the data that has been signed.
hashLen | Length of the hash, in bytes.
mod | The modulus of the public key.
modLen | Length of the modulus, in bytes.
exp | The exponent of the public key.
expLen | Length of the exponent, in bytes.
Returns:
S3E_RESULT_SUCCESS if successful, S3E_RESULT_ERROR on signature failure.
Note:
This function may yield and may be quite slow.
Required Header Files
s3eCrypto.h


Airplay API Reference: S3E Debug

Airplay API Reference > S3E API Documentation > S3E Debug >

S3E Debug

The S3E Debug documentation contains the following sections:

  • S3E Debug Overview
  • Debug API Reference


Airplay API Reference: S3E Debug Overview

Airplay API Reference > S3E API Documentation > S3E Debug > S3E Debug Overview >

S3E Debug Overview

The Debug module provides platform-dependent debugging support. Debugging is supported through the use of assert message, trace message and error message output.

Using an assert function, you can validate the current state of the code and send a message should an error be detected. Should an assert message be triggered, a modal dialog is displayed containing the assert message.

Note: For more information on creating assert messages, see the s3eDebugAssertShow() function.

Trace output is written to the file s3eDebugTrace.txt, the location of which will vary across platforms. Trace output is useful in helping you follow and diagnose problems that may occur in your code.

Note: For more information on creating trace output, see the s3eDebugTraceLine() function. For an overview of Airplay tracing and other debug functionality plus a detailed listing of trace file output location by platform, see the Debugging section of Airplay Concepts.

Neither assert nor trace messages will be output in a release build of the S3E environment.

When running a program in a Windows environment, debug messages can be output in your debug console. If you are running a program on a mobile device, then the debugging messages can be output to a logging window displayed on the computer to which the mobile device is attached.

Note: For more information on displaying debug messages, see the s3eDebugOutputString() function.

S3E supports reporting error messages using s3eDebugErrorShow(). These messages are similar to those output by s3eDebugAssertShow() but they will appear in a release build. They are useful for trapping fatal errors that would otherwise cause a crash.

S3E concerns itself with low-level error message output.

Note: For information on higher-level tracing and asserting functions, see the IwUtil API Documentation.

For more information on the functionality outlined in this section, see the Debug API Reference.


Airplay API Reference: Debug API Reference

Airplay API Reference > S3E API Documentation > S3E Debug > Debug API Reference >

Debug API Reference
[S3E]

Enumerations

enum s3eDebugCallback {
S3E_DEBUG_ASSERT = 0,
S3E_DEBUG_ERROR = 1
}
enum | s3eDebugError
enum s3eDebugProperty {
S3E_DEBUG_TRACE_ENABLED = 0,
S3E_DEBUG_TRACE_TO_FILE = 1,
S3E_DEBUG_ASSERT_ENABLED = 2,
S3E_DEBUG_AVAILABLE = 3,
S3E_DEBUG_FONT_SCALE = 4,
S3E_DEBUG_FONT_WIDTH = 5,
S3E_DEBUG_FONT_HEIGHT = 6
}
enum s3eMessageType {
S3E_MESSAGE_CONTINUE = 0,
S3E_MESSAGE_CONTINUE_STOP = 1,
S3E_MESSAGE_CONTINUE_STOP_IGNORE = 2
}

Functions

S3E_API s3eErrorShowResult | s3eDebugAssertShow (s3eMessageType type, const char *string)
S3E_API s3eErrorShowResult | s3eDebugErrorShow (s3eMessageType type, const char *string)
S3E_API s3eDebugError | s3eDebugGetError ()
S3E_API const char * | s3eDebugGetErrorString ()
S3E_API int32 | s3eDebugGetInt (s3eDebugProperty property)
S3E_API s3eBool | s3eDebugIsDebuggerPresent ()
S3E_API void | s3eDebugOutputString (const char *pStr)
S3E_API void | s3eDebugPrint (int x, int y, const char *string, s3eBool wrap)
S3E_EAPI void | s3eDebugPrintf (int x, int y, s3eBool wrap, const char *fmt,...) PRINTFLIKE4
S3E_API s3eResult | s3eDebugRegister (s3eDebugCallback cbid, s3eCallback fn, void *userData)
S3E_API s3eResult | s3eDebugSetInt (s3eDebugProperty property, int32 value)
S3E_API s3eBool | s3eDebugTraceChannelSwitch (const char *channel, s3eBool new_state)
S3E_API void | s3eDebugTraceClearFile ()
S3E_API void | s3eDebugTraceFlush ()
S3E_API void | s3eDebugTraceLine (const char *string)
S3E_EAPI int | s3eDebugTracePrintf (const char *fmt,...) PRINTFLIKE
S3E_API s3eResult | s3eDebugUnRegister (s3eDebugCallback cbid, s3eCallback fn)

Detailed Description

For more information on the Debug functionality provided by the S3E module, see the S3E Debug section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eDebugCallback

Debug Callbacks.

See also:
s3eDebugRegister, s3eDebugUnRegister
Required Header Files
s3eDebug.h
Enumerator:
S3E_DEBUG_ASSERT Called when an assert is generated via s3eDebugAssertShow() (or the higher level IwAssert*()).

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to message text.
Returns:
One of s3eErrorShowResult.
Remarks:
If the return value is not equal to S3E_ERROR_SHOW_AGAIN then s3e will not display the assertion, and the return value of the callback will be the return value of s3eDebugAssertShow(). If the return value is S3E_ERROR_SHOW_AGAIN then s3e will display the assertion as normal, and return a value according to user input.
S3E_DEBUG_ERROR Called when an assert is generated via s3eDebugErrorShow() (or the higher level IwError*()).

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to message text.
Returns:
One of s3eErrorShowResult.
Remarks:
If the callback return value is not equal to S3E_ERROR_SHOW_AGAIN then s3e will not display the error, and the return value of the callback will be the return value of s3eDebugErrorShow(). If the callback return value is S3E_ERROR_SHOW_AGAIN then s3e will display the error as normal, and return a value according to user input.

enum s3eDebugError

Debug Errors.

See also:
s3eDebugGetError

s3eDebugGetErrorString

Required Header Files
s3eDebug.h
Enumerator:
S3E_DEBUG_ERR_NONE | No Error.
S3E_DEBUG_ERR_PARAM | Invalid parameter.
S3E_DEBUG_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_DEBUG_ERR_ALREADY_REG | The specified callback is already registered.
S3E_DEBUG_ERR_NOT_FOUND | The specified callback was not found for removal.

enum s3eDebugProperty

Debug Properties.

See also:
s3eDebugGetInt

s3eDebugSetInt

Required Header Files
s3eDebug.h
Enumerator:
S3E_DEBUG_TRACE_ENABLED | [read,write,int] If this is non-zero then tracing is enabled
S3E_DEBUG_TRACE_TO_FILE | [read,write,int] If this is non-zero and tracing is enabled then all trace messages will be written to the trace file as well as the debug output.
S3E_DEBUG_ASSERT_ENABLED | [read,write,int] If this is non-zero then assertions are enabled.
S3E_DEBUG_AVAILABLE | [read, int] Returns non-zero if the S3E loader was built with debug support.
S3E_DEBUG_FONT_SCALE | [read,write,int] Controls how large the debug print font is, 1 = normal size, 2 = twice normal size
S3E_DEBUG_FONT_WIDTH | [read, int] Returns the width of the debug print font in pixels.
S3E_DEBUG_FONT_HEIGHT | [read, int] Returns the height of the debug print font in pixels.

enum s3eErrorShowResult

Enumerator:
S3E_ERROR_SHOW_CONTINUE | 'Continue' button in in error dialog was selected.
S3E_ERROR_SHOW_STOP | 'Stop' button in error dialog was selected.
S3E_ERROR_SHOW_IGNORE | 'Ignore' button in in error dialog was selected.
S3E_ERROR_SHOW_AGAIN | For use in S3E_DEBUG_ASSERT or S3E_DEBUG_ERROR callbacks; causes s3e to continue to display the assertion or error message.

enum s3eMessageType

Types of error message.

Enumerator:
S3E_MESSAGE_CONTINUE | A Message dialog with a single 'continue' option for the user to select to dismiss the message. When displayed via s3eDebugErrorShow() or s3eDebugAssertShow(), this dialog will return S3E_ERROR_SHOW_CONTINUE.
S3E_MESSAGE_CONTINUE_STOP | A Message dialog with a 'continue' and a 'stop' option for the user to select. When displayed via s3eDebugErrorShow() or s3eDebugAssertShow(), this dialog will return S3E_ERROR_SHOW_CONTINUE or S3E_ERROR_SHOW_STOP according to what the user selected.
S3E_MESSAGE_CONTINUE_STOP_IGNORE | A Message dialog with 'continue', 'stop' and 'ignore' options for the user to select. When displayed via s3eDebugErrorShow() or s3eDebugAssertShow(), this dialog will return S3E_ERROR_SHOW_CONTINUE, S3E_ERROR_SHOW_STOP or S3E_ERROR_SHOW_IGNORE according to what the user selected.

Function Documentation

S3E_API s3eErrorShowResult s3eDebugAssertShow | ( | s3eMessageType | type,
 |  | const char * | string
 | ) |  |

Displays the text specified by the input parameter string as a modal dialog. This debug message type is not included in release builds. This differs from s3eDebugErrorShow() in that this will do nothing when running ina release environment.

Parameters:
type | Message type to display.
string | Error text for dialog (if too long, this will be truncated).
Returns:
s3eErrorShowResult enumeration value according to how the user dismissed the dialog. In a release environment, this function will return immediately with S3E_ERROR_SHOW_CONTINUE.
Required Header Files
s3eDebug.h

S3E_API s3eErrorShowResult s3eDebugErrorShow | ( | s3eMessageType | type,
 |  | const char * | string
 | ) |  |

Displays the text specified by the input parameter string as a modal dialog. This debug message type is included in release builds, so should be used for errors that may be encountered by the end user.

Parameters:
type | Message type to display.
string | Error text for dialog (if too long, this will be truncated).
Returns:
s3eErrorShowResult enumeration value according to how the user dismissed the dialog.
Required Header Files
s3eDebug.h

S3E_API s3eDebugError s3eDebugGetError ( )

Retrieve the last error, if any, for this Debug.

See also:
s3eDebugGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eDebug.h

S3E_API const char* s3eDebugGetErrorString ( )

Retrieve the last error as a string, if any, for this Debug. This is only available in debug builds.

See also:
s3eDebugGetError
Remarks:
This function, as opposed to s3eDebugGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eDebug.h

S3E_API int32 s3eDebugGetInt ( s3eDebugProperty property )

Retrieves an integer property for the debug device.

See also:
s3eDebugSetInt
Parameters:
property The property to query.
Returns:
  • The value of the requested property if property is valid.
  • -1 if property is not valid.
    Call s3eDebugGetError() to retrieve an error code. This will return: S3E_DEBUG_ERR_PARAM if property is not valid.
Required Header Files
s3eDebug.h

S3E_API s3eBool s3eDebugIsDebuggerPresent ( )

Returns whether or not a debugger is present.

Returns:
S3E_TRUE if a debugger is connected to the S3E appliaction, S3E_FALSE otherwise.
Required Header Files
s3eDebug.h

S3E_API void s3eDebugOutputString ( const char * pStr )

Outputs a single line debug message to a logger, console, etc. depending on the system on which the progam is run. The string should not contain any newline characters.

Parameters:
pStr NULL terminated string to output to debug console.
Remarks:
If pStr is too long for the underlying system it will be truncated. Under IDE's such as Visual Studio this will output text to the logger window.
Under Visual Studio 6, calling this too frequently (> ~1000 per second) may cause trace lines to be lost
Required Header Files
s3eDebug.h

S3E_API void s3eDebugPrint | ( | int | x,
 |  | int | y,
 |  | const char * | string,
 |  | s3eBool | wrap
 | ) |  |

Prints a text message on the current surface.

Parameters:
x | Row from top.
y | Column from left.
string | Message to be printed.
wrap | set to S3E_TRUE to wrap text at right edge of the screen. Otherwise text will be clipped.
Remarks:
string will be printed at (x, y) on the surface returned by s3eSurfacePtr() with an 6x8 pixel font. By default the text will be drawn white. There are several special commands that can be inserted into string which will affect the printing of following character. The commands begin with the apostrophe (`) character
  • `xrrggbb will colour the text. rr, gg, bb are (lower-case) hex values from 00 to ff specifying red, green and blue. e.g "`xff0000MyText" will print "MyText" in red. The text will no longer be xor'd against the surface.
  • `a will cause the background of the text to be drawn black, and the foreground text will be drawn white without any xor operation
  • `i will cause the background of the text to be drawn with the text colour (default white, but changeable via `x) and the text itself to be drawn black
  • `s will cause the text will be drawn white but this will be xor'd with the current surface contents. This is so that the text is always visible.

S3E_EAPI void s3eDebugPrintf | ( | int | x,
 |  | int | y,
 |  | s3eBool | wrap,
 |  | const char * | fmt,
 |  |  | ...
 | ) |  |

Prints a text message on the current surface. Functions exactly like s3eDebugPrint but takes printf-style arguments.

S3E_API s3eResult s3eDebugRegister | ( | s3eDebugCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Registers a callback for a given event.

The available callback types are listed in s3eDebugCallback.

Parameters:
cbid | ID of the callback for which to register.
fn | callback function.
userData | Value to pass to the userData paramater of fn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDebugGetError() to retrieve an error code. This will return one of:
    • S3E_DEBUG_ERR_PARAM if cbid is not a valid member of s3eDebugCallback or fn is NULL.
    • S3E_DEBUG_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_DEBUG_ERR_ALREADY_REG If (cbid, fn) has already been registered.
Remarks:
This can be used to register callbacks for when asserts and errors occur. These in turn can override assert and error behaviour.
Note:
For more information on the systemData passed as a parameter to the callback registered using this function or the expected return values of that callback, see the s3eDebugCallback enum.
Required Header Files
s3eDebug.h

S3E_API s3eResult s3eDebugSetInt | ( | s3eDebugProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for the debug device.

Parameters:
property | The property to set.
value | The value to set the property to.
See also:
s3eDebugGetInt
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDebugGetError() to retrieve an error code. This will return: S3E_DEBUG_ERR_PARAM if property is invalid or value is invalid.
Remarks:
This function can be used with S3E_DEBUG_TRACE_ENABLED to enable or disable tracing at runtime.
Required Header Files
s3eDebug.h

S3E_API s3eBool s3eDebugTraceChannelSwitch | ( | const char * | channel,
 |  | s3eBool | new_state
 | ) |  |

Function to dynamically turn the given trace channel on or off. Returns the channel's previous state.

Parameters:
channel | Name of the trace channel to change.
new_state | The new boolean state of the channel.S3E_TRUE to enable or S3E_FALSE to disable tracing to the channel.

S3E_API void s3eDebugTraceClearFile ( )

Clear the existing trace file.

Required Header Files
s3eDebug.h

S3E_API void s3eDebugTraceFlush ( )

Flush buffers writing output.

Remarks:
On many platforms this is unneccessary as s3eDebugTraceLine() guarantees its output has been written to a file.
Required Header Files
s3eDebug.h

S3E_API void s3eDebugTraceLine ( const char * string )

Write to the trace output.

Parameters:
string NULL-terminated string to write.
Remarks:
string will be written as a line to the trace file, preceeded with a timestamp Writing to the trace file involves writing to permanent storage and can be slow on some devices (writing trace to flash memory, e.g. an MMC card, can take up to 200ms per call to s3eDebugTraceLine).
Required Header Files
s3eDebug.h

S3E_EAPI int s3eDebugTracePrintf | ( | const char * | fmt,
 |  |  | ...
 | ) |  |

Write to the trace output. Functions exactly like s3eDebugTraceLine but takes printf-style arguments.

S3E_API s3eResult s3eDebugUnRegister | ( | s3eDebugCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDebugGetError() to retrieve an error code. This will return one of:
    • S3E_DEBUG_ERR_PARAM if cbid is not a valid member of s3eDebugCallback.
    • S3E_DEBUG_ERR_NOT_FOUND if fn is not registered for callback cbid.
Required Header Files
s3eDebug.h


Airplay API Reference: S3E Device Interface

Airplay API Reference > S3E API Documentation > S3E Device Interface >

S3E Device Interface

The S3E Device documentation contains the following sections:

  • S3E Device Interface Overview
  • Device Interface API Reference
  • S3E Device Interface Examples


Airplay API Reference: S3E Device Interface Overview

Airplay API Reference > S3E API Documentation > S3E Device Interface > S3E Device Interface Overview >

S3E Device Interface Overview

The Device Interface Module allows you to query the details of your sub-device, and configure your application to work best with that device. You can gain a variety of device information using the Device Interface Module, this information includes: OS type, device type, language used, available memory, etc. To get device class, device OS, device ID, etc. use one of the s3eDeviceGetString() or s3eDeviceGetInt() functions.

The Device Interface Module allows you to manage and control CPU handover to OS functions and other low priority programs via s3eDeviceYield(). This functionality enables your program to cope with balancing OS behaviour and application requirements. The Device Interface Module callback mechanism allows you to register or unregister functions that will be called when OS notifications are received. The ability to do this means you can create user-friendly responses to OS notifications. An application can yield in two ways:

  • As part of an application loop.
  • Continually, taking processor control back for the application only when certain events have occurred, such as keyboard events.

It is possible to yield to the OS while waiting for an event, such as keyboard input. A callback can be registered which will return control of the processor to the application. Callbacks can be registered and unregistered using the s3eDeviceRegister() and s3eDeviceUnRegister() functions respectively.

The Device Interface Module also includes a set of functions that allow you to set the activity state, and so inform the system as to what power savings it can make.

Note:For more information on the functionality outlined in this section, see the Device Interface API Reference.


Airplay API Reference: Device Interface API Reference

Airplay API Reference > S3E API Documentation > S3E Device Interface > Device Interface API Reference >

Device Interface API Reference
[S3E]

Data Structures

struct | s3eDeviceStateChangeInfo
struct | s3eDeviceVolChangeInfo

Enumerations

enum | s3eDeviceArchitecture
enum s3eDeviceCallback {
S3E_DEVICE_PAUSE = 0,
S3E_DEVICE_UNPAUSE = 1,
S3E_DEVICE_EXIT = 2,
S3E_DEVICE_VOL_UP = 17,
S3E_DEVICE_VOL_DOWN = 18,
S3E_DEVICE_MAINS_POWER_CHANGED = 20,
S3E_DEVICE_PUSH_NOTIFICATION = 21
}
enum | s3eDeviceClassID
enum | s3eDeviceError
enum | s3eDeviceLanguage
enum s3eDeviceOSID {
S3E_OS_ID_SYMBIAN = 1,
S3E_OS_ID_BREW = 2,
S3E_OS_ID_WINDOWS = 3,
S3E_OS_ID_WINMOBILE = 4,
S3E_OS_ID_LINUX = 5,
S3E_OS_ID_WIPI = 6,
S3E_OS_ID_NDS = 7,
S3E_OS_ID_ARM_SEMIH = 8,
S3E_OS_ID_NUCLEUS = 9,
S3E_OS_ID_NGI = 10,
S3E_OS_ID_WINCE = 11,
S3E_OS_ID_SHARPEMP = 12,
S3E_OS_ID_OSX = 13,
S3E_OS_ID_IPHONE = 14,
S3E_OS_ID_UIQ = 15,
S3E_OS_ID_PS3 = 16,
S3E_OS_ID_X360 = 17
}
enum s3eDeviceProperty {
S3E_DEVICE_OS = 0,
S3E_DEVICE_CLASS = 1,
S3E_DEVICE_ID = 2,
S3E_DEVICE_PHONE_NUMBER = 3,
S3E_DEVICE_LANGUAGE = 4,
S3E_DEVICE_STATE = 5,
S3E_DEVICE_FREE_RAM = 6,
S3E_DEVICE_TOTAL_RAM = 7,
S3E_DEVICE_ARCHITECTURE = 8,
S3E_DEVICE_S3E_VERSION = 9,
S3E_DEVICE_BATTERY_LEVEL = 10,
S3E_DEVICE_LEFT_SOFTKEY_IS_BACK = 11,
S3E_DEVICE_MAINS_POWER = 12,
S3E_DEVICE_OS_VERSION = 13,
S3E_DEVICE_CHIPSET = 14,
S3E_DEVICE_EXIT_CODE = 15,
S3E_DEVICE_FPU = 16,
S3E_DEVICE_BACK_SOFTKEY_POSITION = 17,
S3E_DEVICE_ADVANCE_SOFTKEY_POSITION = 18,
S3E_DEVICE_AIRPLAY_VERSION = 19,
S3E_DEVICE_LOCALE = 20,
S3E_DEVICE_NAME = 21,
S3E_DEVICE_SUPPORTS_SIGNAL_HANDLING = 22,
S3E_DEVICE_EXIT_SIGNAL = 23,
S3E_DEVICE_PROXIMITY = 24
}
enum | s3eDeviceSoftKeyPosition
enum s3eDeviceState {
S3E_DEVICE_STATE_PAUSED = 3,
S3E_DEVICE_STATE_EXITING = 4,
S3E_DEVICE_STATE_RUNNING = 5
}

Functions

S3E_API void | s3eDeviceBacklightOn ()
S3E_API s3eBool | s3eDeviceCheckPauseRequest ()
S3E_API s3eBool | s3eDeviceCheckQuitRequest ()
S3E_API s3eResult | s3eDeviceExecPushNext (const char *filename, const char *config_prepend=0, const char *config_append=0)
S3E_API void | s3eDeviceExit (int code=0) NO_RETURN
S3E_API s3eDeviceError | s3eDeviceGetError ()
S3E_API const char * | s3eDeviceGetErrorString ()
S3E_API int32 | s3eDeviceGetInt (s3eDeviceProperty property)
S3E_API const char * | s3eDeviceGetString (s3eDeviceProperty property)
S3E_API s3eResult | s3eDeviceRegister (s3eDeviceCallback cbid, s3eCallback fn, void *userdata)
S3E_API void | s3eDeviceRequestQuit ()
S3E_API s3eResult | s3eDeviceSetInt (s3eDeviceProperty property, int32 value)
S3E_API s3eResult | s3eDeviceUnRegister (s3eDeviceCallback cbid, s3eCallback fn)
S3E_API void | s3eDeviceUnYield ()
S3E_API int64 | s3eDeviceYield (int32 ms=0)
S3E_API void | s3eDeviceYieldUntilEvent (int32 ms=2147483647L)

Detailed Description

For more information on the Device Interface functionality provided by the S3E module, see the S3E Device Interface section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eDeviceArchitecture

Architecture returned through s3eDeviceGetInt(S3E_DEVICE_ARCHITECTURE).

Required Header Files
s3eDevice.h
Enumerator:
S3E_DEVICE_ARCHITECTURE_ARM4T | ARM processor with v4 instruction set and thumb support.
S3E_DEVICE_ARCHITECTURE_ARM4 | ARM processor with v4 instruction set and no thumb support.
S3E_DEVICE_ARCHITECTURE_ARM5T | ARM processor with v5 instruction set and thumb support.
S3E_DEVICE_ARCHITECTURE_ARM5TE | ARM processor with v5 instruction set, dsp extensions and thumb support.
S3E_DEVICE_ARCHITECTURE_ARM5TEJ | ARM processor with v5 instruction set, dsp extensions, thumb and jazelle support.
S3E_DEVICE_ARCHITECTURE_ARM6 | ARM processor with v6 instruction set and thumb support.
S3E_DEVICE_ARCHITECTURE_ARM6K | ARM processor with v6 instruction set, SMP extensions and thumb support.
S3E_DEVICE_ARCHITECTURE_ARM6T2 | ARM processor with v6 instruction set, thumb and thumb-2 support.
S3E_DEVICE_ARCHITECTURE_ARM6Z | ARM processor with v6 instruction set and trustzone support.
S3E_DEVICE_ARCHITECTURE_X86 | x86 architecture.
S3E_DEVICE_ARCHITECTURE_PPC | PowerPC architecture.

enum s3eDeviceCallback

Device notifications. The following callback types can be registered to enable user notification of device events. For all device notifications, the systemData paramater passed to the callback will be NULL, unless specified.

Required Header Files
s3eDevice.h
Enumerator:
S3E_DEVICE_PAUSE This allows you to create a callback when the user application has been suspended, for example during a phone call or when the application has lost focus.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This paramater will be NULL.
Returns:
No return value is expected.
S3E_DEVICE_UNPAUSE This allows you to create a callback when the user application has been resumed after being suspended.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This paramater will be NULL.
Returns:
No return value is expected.
S3E_DEVICE_EXIT This allows you to create a callback when the OS has requested that application exits.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This paramater will be NULL.
Returns:
No return value is expected.
S3E_DEVICE_VOL_UP This allows you to create a callback when the user wants to increase the sound volume.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This points to an instance of s3eDeviceVolChangeInfo.
Returns:
No return value is expected.
Remarks:
If this callback does not set m_OverrideDefaultBehaviour to S3E_TRUE S3E will perforce the default behaviour which is to increase the sound, audio and video volumes by a fixed amount (usually 32, but may vary between platforms)
S3E_DEVICE_VOL_DOWN This allows you to create a callback when the user wants to decrease the sound volume.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This points to an instance of s3eDeviceVolChangeInfo.
Returns:
No return value is expected.
Remarks:
If this callback does not set m_OverrideDefaultBehaviour to S3E_TRUE S3E will perforce the default behaviour which is to decrease the sound, audio and video volumes by a fixed amount (usually 32, but may vary between platforms)
S3E_DEVICE_MAINS_POWER_CHANGED This allows you to create a callback which will be called when the mains power status has changed. Specifically it is called when an external power source is connected or disconnected.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This points to a s3eDeviceStateChangeInfo structure. The m_State member of s3eDeviceStateChangeInfo is set by the callback to 1 if the change in device state is that it is now connected to mains power, or 0 if its new state is that it has been disconnected from mains power.
Returns:
No return value is expected.
S3E_DEVICE_PUSH_NOTIFICATION This allows you to create a callback when the app recieves a push notification

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This points to the notification string.
Returns:
No return value is expected.

enum s3eDeviceClassID

Device class IDs.

Required Header Files
s3eDevice.h

enum s3eDeviceError

Device Errors.

See also:
s3eDeviceGetError

s3eDeviceGetErrorString

Required Header Files
s3eDevice.h
Enumerator:
S3E_DEVICE_ERR_NONE | No Error.
S3E_DEVICE_ERR_PARAM | Invalid parameter.
S3E_DEVICE_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_DEVICE_ERR_ALREADY_REG | The specified callback is already registered.
S3E_DEVICE_ERR_NOT_FOUND | Path not found / callback not found for removal or phone info not found.
S3E_DEVICE_ERR_UNAVAIL | Device is unavailable.
S3E_DEVICE_ERR_DEVICE | The underlying file device failed.
S3E_DEVICE_ERR_UNSUPPORTED | The action requested was is not supported.
S3E_DEVICE_ERR_MEM | Out of operating system memory during operation.
S3E_DEVICE_ERR_GENERIC | Unspecified error.
S3E_DEVICE_ERR_INVALID_DRIVE | Invalid/unsupported drive specified in path.
S3E_DEVICE_ERR_INVALID_PATH | The path could not be resolved onto the device filesytem (e.g. opening ROM://../file).

enum s3eDeviceLanguage

Language used on device.

Enumerator:
S3E_DEVICE_LANGUAGE_UNKNOWN | Unknown Language.
S3E_DEVICE_LANGUAGE_ENGLISH | English Language.
S3E_DEVICE_LANGUAGE_FRENCH | French Language.
S3E_DEVICE_LANGUAGE_GERMAN | German Language.
S3E_DEVICE_LANGUAGE_SPANISH | Spanish Language.
S3E_DEVICE_LANGUAGE_ITALIAN | Italian Language.
S3E_DEVICE_LANGUAGE_PORTUGUESE | Portugese Language.
S3E_DEVICE_LANGUAGE_DUTCH | Dutch Language.
S3E_DEVICE_LANGUAGE_TURKISH | Turkish Language.
S3E_DEVICE_LANGUAGE_CROATIAN | Croatian Language.
S3E_DEVICE_LANGUAGE_CZECH | Czech Language.
S3E_DEVICE_LANGUAGE_DANISH | Danish Language.
S3E_DEVICE_LANGUAGE_FINNISH | Finnish Language.
S3E_DEVICE_LANGUAGE_HUNGARIAN | Hungarian Language.
S3E_DEVICE_LANGUAGE_NORWEGIAN | Norwegian Language.
S3E_DEVICE_LANGUAGE_POLISH | Polish Language.
S3E_DEVICE_LANGUAGE_RUSSIAN | Russian Language.
S3E_DEVICE_LANGUAGE_SERBIAN | Serbian Language.
S3E_DEVICE_LANGUAGE_SLOVAK | Slovak Language.
S3E_DEVICE_LANGUAGE_SLOVENIAN | Slovenian Language.
S3E_DEVICE_LANGUAGE_SWEDISH | Swedish Language.
S3E_DEVICE_LANGUAGE_UKRAINIAN | Ukranian Language.
S3E_DEVICE_LANGUAGE_GREEK | Greek Language.
S3E_DEVICE_LANGUAGE_JAPANESE | Japanese Language.
S3E_DEVICE_LANGUAGE_SIMPL_CHINESE | Simplified Chinese Language.
S3E_DEVICE_LANGUAGE_TRAD_CHINESE | Traditional Chinese Language.
S3E_DEVICE_LANGUAGE_KOREAN | Korean Language.
S3E_DEVICE_LANGUAGE_ICELANDIC | Icelandic Language.
S3E_DEVICE_LANGUAGE_FLEMISH | Flemish Language.
S3E_DEVICE_LANGUAGE_THAI | Thai Language.
S3E_DEVICE_LANGUAGE_AFRIKAANS | Afrikaans Language.
S3E_DEVICE_LANGUAGE_ALBANIAN | Albanian Language.
S3E_DEVICE_LANGUAGE_AMHARIC | Amharic Language.
S3E_DEVICE_LANGUAGE_ARABIC | Arabic Language.
S3E_DEVICE_LANGUAGE_ARMENIAN | Armenian Language.
S3E_DEVICE_LANGUAGE_AZERBAIJANI | Azerbaijani Language.
S3E_DEVICE_LANGUAGE_TAGALOG | Tagalog Language.
S3E_DEVICE_LANGUAGE_BELARUSSIAN | Belarussian Language.
S3E_DEVICE_LANGUAGE_BENGALI | Bengali Language.
S3E_DEVICE_LANGUAGE_BULGARIAN | Bulgarian Language.
S3E_DEVICE_LANGUAGE_BURMESE | Burmese Language.
S3E_DEVICE_LANGUAGE_CATALAN | Catalan Language.
S3E_DEVICE_LANGUAGE_ESTONIAN | Estonian Language.
S3E_DEVICE_LANGUAGE_FARSI | Farsi Langage.
S3E_DEVICE_LANGUAGE_GAELIC | Gaelic Language.
S3E_DEVICE_LANGUAGE_GEORGIAN | Georgian Language.
S3E_DEVICE_LANGUAGE_GUJARATI | Gujarati Language.
S3E_DEVICE_LANGUAGE_HEBREW | Hebrew Language.
S3E_DEVICE_LANGUAGE_HINDI | Hindi Language.
S3E_DEVICE_LANGUAGE_INDONESIAN | Indonesian Language.
S3E_DEVICE_LANGUAGE_IRISH | Irish Language.
S3E_DEVICE_LANGUAGE_KANNADA | Kannada Language.
S3E_DEVICE_LANGUAGE_KAZAKH | Kazakh Language.
S3E_DEVICE_LANGUAGE_KHMER | Khmer Language.
S3E_DEVICE_LANGUAGE_LAO | Lao Language.
S3E_DEVICE_LANGUAGE_LATVIAN | Latvian Language.
S3E_DEVICE_LANGUAGE_LITHUANIAN | Lithuanian Language.
S3E_DEVICE_LANGUAGE_MACEDONIAN | Macedonian Language.
S3E_DEVICE_LANGUAGE_MALAY | Malay Language.
S3E_DEVICE_LANGUAGE_MALAYALAM | Malayalam Language.
S3E_DEVICE_LANGUAGE_MARATHI | Marathi Language.
S3E_DEVICE_LANGUAGE_MOLDOVIAN | Moldovian Language.
S3E_DEVICE_LANGUAGE_MONGOLIAN | Mongolian Language.
S3E_DEVICE_LANGUAGE_PUNJABI | Punjabi Language.
S3E_DEVICE_LANGUAGE_ROMANIAN | Romanian Language.
S3E_DEVICE_LANGUAGE_SINHALESE | Sinhalese Language.
S3E_DEVICE_LANGUAGE_SOMALI | Somali Language.
S3E_DEVICE_LANGUAGE_SWAHILI | Swahili Language.
S3E_DEVICE_LANGUAGE_TAJIK | Tajik Language.
S3E_DEVICE_LANGUAGE_TAMIL | Tamil Language.
S3E_DEVICE_LANGUAGE_TELUGU | Telugu Langauge.
S3E_DEVICE_LANGUAGE_TIBETAN | Tibetan Language.
S3E_DEVICE_LANGUAGE_TIGRINYA | Tigrinya Language.
S3E_DEVICE_LANGUAGE_TURKMEN | Turkmen Language.
S3E_DEVICE_LANGUAGE_URDU | Urdu Language.
S3E_DEVICE_LANGUAGE_UZBEK | Uzbek Language.
S3E_DEVICE_LANGUAGE_VIETNAMESE | Vietnamese Language.
S3E_DEVICE_LANGUAGE_WELSH | Welsh Language.
S3E_DEVICE_LANGUAGE_ZULU | Zulu Language.

enum s3eDeviceOSID

Device OS IDs.

Required Header Files
s3eDevice.h
Enumerator:
S3E_OS_ID_SYMBIAN | Symbain OS.
S3E_OS_ID_BREW | Qualcomm BREW.
S3E_OS_ID_WINDOWS | Any version of Microsoft Windows(tm).
S3E_OS_ID_WINMOBILE | Any version of Microsoft Windows(tm) Mobile.
S3E_OS_ID_LINUX | Any version of Linux.
S3E_OS_ID_WIPI | SKT or KTF WIPI.
S3E_OS_ID_NDS | Nintendo DS.
S3E_OS_ID_ARM_SEMIH | ARM Semihosted environment (dev board).
S3E_OS_ID_NUCLEUS | Nucleus-based RTOS dev board
S3E_OS_ID_NGI | PRIVATE
S3E_OS_ID_WINCE | Microsoft Windows(tm) CE (excluding Windows Mobile).
S3E_OS_ID_SHARPEMP | Sharp device running EMP chipset
S3E_OS_ID_OSX | Apple OSX
S3E_OS_ID_IPHONE | Apple iPhone OS
S3E_OS_ID_UIQ | UIQ OS.
S3E_OS_ID_PS3 | PS3 OS.
S3E_OS_ID_X360 | XBOX 360 OS.

enum s3eDeviceProperty

Device Properties

Required Header Files
s3eDevice.h
Enumerator:
S3E_DEVICE_OS | [read, int, string] Return the device's operating system. When retrieved as an integer this will be one of s3eDeviceOSID. When retrieved as a string is will be the string form of the enum value with out the S3E_OS_ID_ prefix. For OS version information use S3E_DEVICE_OS_VERSION.
S3E_DEVICE_CLASS | [read, int, string] Return the device's class as an integer or a string. When read as an interger it will be one of s3eDeviceClassID.
S3E_DEVICE_ID | [read, int, string] Return the platform-specific device type ID as an integer or string. This can be used as a way to indentify the exact handset model in use. In the underlying platform supports integer model identifiers then the string property will be the string version the integer. If the underlying platform uses string identifiers then the integer property will be a hash on the the string.
S3E_DEVICE_PHONE_NUMBER | [read, string] Return the device's phone number as a string. On devices without a valid phone number, this will return the empty string.
S3E_DEVICE_LANGUAGE | [read, int] Return the current language in use on the device, one of s3eDeviceLanguage.
S3E_DEVICE_STATE | [read, int] Return the current state of the device, one of s3eDeviceState. This can be used to query whether the device is paused or if the s3e application has been requested to quit.
S3E_DEVICE_FREE_RAM | [read, int] Return the amount of free physical RAM available to the operating system (note: this is not the same as the memory available to S3E or to the application).
S3E_DEVICE_TOTAL_RAM | [read, int] Return the total physical RAM installed on the device.
S3E_DEVICE_ARCHITECTURE | [read, int, string] Return the CPU architecture of the device. As an integer it will return one of s3eDeviceArchitecture, as a string it will return a string version of one of s3eDeviceArchitecture, without the 'S3E_DEVICE_ARCHITECTURE_' prefix, e.g. "ARM4T".
S3E_DEVICE_S3E_VERSION | [read, int, string] Return the highest version of S3E supported by the loader, as an integer or as a string. The integer is of hex format 0x00mmnnrr where mm is the major version, nn the minor version and nn the revision number. The string is of the format "m.n.r", where m,n,r are decimal version of the major, minor and revision version numbers.
S3E_DEVICE_BATTERY_LEVEL | [read, int] Return the battery level as a percentage 0-100. If this functionality is not supported, s3eDeviceGetInt() will return 100.
S3E_DEVICE_LEFT_SOFTKEY_IS_BACK | [read, int] Returns whether the left softkey (1) or the right softkey (0) should be used as a 'back' key for menus. For example, this is 0 on Nokia/Symbian devices and 1 on BREW devices.
S3E_DEVICE_MAINS_POWER | [read, int] Return 1 if device is connected to a power cable, 0 if it is running on battery power. If this functionality is not supported, s3eDeviceGetInt() will return 0.
S3E_DEVICE_OS_VERSION | [read, int, string] Return version information about the underlying OS. When retrieved as an integer top and bottom 16-bits represent the major and minor OS versions respectively. When retrieved as a string the full OS name and version is reported. e.g. "Linux 2.6.24", "Windows XP SP2", "Symbian 9"
S3E_DEVICE_CHIPSET | [read, string] Return ID of the chipset. On BREW these are of the form "MSM3100", "MSM5100" etc.
S3E_DEVICE_EXIT_CODE | [read, write, int] When read, this property returns the exit code of the last S3E application that ran, or 0 if no previous application has run. When written to, this property set the return code of the current application. This will then be read by the s3e implementation when s3eDeviceExit() is called.
S3E_DEVICE_FPU | [read, int] Return the type of ARM FPU present on the current device. 0 = None, 1 = ARM_VFP
S3E_DEVICE_BACK_SOFTKEY_POSITION | [read, int] When read, this property returns the position of the back action softkey base on the enum s3eDeviceSoftKeyPosition.
S3E_DEVICE_ADVANCE_SOFTKEY_POSITION | [read, int] When read, this property returns the position of the advance action softkey base on the enum s3eDeviceSoftKeyPosition.
S3E_DEVICE_AIRPLAY_VERSION | [read, int, string] When read, this property returns the version of the Airplay SDK that the S3E loader shiped with. When read as a string this has the save format as the S3E_VERSION_STRING macro. When read as an int it returns the major, minor and revision numbers only in 0x00mmnnrr format. This only time this will differ to the content AirplayVersion.h is when an application is build with one SDK and run using a loader from anther SDK.
S3E_DEVICE_LOCALE | [read, string] Return the current device locale as a language-country code pair using the ISO 639 and ISO 3166 formats respectively. For example, if the device is set to English (UK) it will return "en_GB". If the device does not support providing a locale, it will return the empty string.
S3E_DEVICE_NAME | [read, string] Return the name given to the current device by the user, if they OS supports such a concept. For example: "John's Smartphone".
S3E_DEVICE_SUPPORTS_SIGNAL_HANDLING | [read, int] Return true of the OS supports the handling of CPU excpetions and therefore the loader can continue when an application crashes. If this feature is available the current application will exit and the next application on the stack will then run.
S3E_DEVICE_EXIT_SIGNAL | [read, int] This property returns the signal, if any, that killed the previous appliction. This property is generally only meaning if the device supports handling of CPU exceptions. The possible signals that can be returned are the same as those listed in <signal.h>
S3E_DEVICE_PROXIMITY | [read, int] This property returns the boolean value of the devices proximity sensor or -1 if it doesn't have one. Possible uses include triggering audio recording when the sensor signals that the user is proximity with the device.

enum s3eDeviceSoftKeyPosition

Postion of the softkey returned through s3eDeviceGetInt(S3E_DEVICE_BACK_SOFTKEY_POSITION) or s3eDeviceGetInt(S3E_DEVICE_ADVANCE_SOFTKEY_POSITION).

Required Header Files
s3eDevice.h

enum s3eDeviceState

Device state.

Required Header Files
s3eDevice.h
Enumerator:
S3E_DEVICE_STATE_PAUSED | Paused. The S3E_DEVICE_PAUSE notification has been sent, and S3E_DEVICE_UNPAUSE has not been sent.
S3E_DEVICE_STATE_EXITING | Exiting the application. The S3E_DEVICE_EXIT has been sent, and s3eDeviceCheckQuitRequest() will return true.
S3E_DEVICE_STATE_RUNNING | Normal running

Function Documentation

S3E_API void s3eDeviceBacklightOn ( )

Reset the backlight timeout, keeping the backlight on.

Remarks:
A single call to this function will ensure the backlight stays on for a device-specified length of time (at least 1 second). Usually the backlight timeout is chosen by the user in the device settings. If an S3E application wishes to keep the backlight on for a significant duration, it should repeatedly call this function, for example every frame during the desired period.
Required Header Files
s3eDevice.h

S3E_API s3eBool s3eDeviceCheckPauseRequest ( )

Check whether the application has been suspended since the last call. to s3eDeviceCheckPauseRequest(). The pause flag is set when the callback S3E_DEVICE_PAUSE is triggered, and cleared when s3eDeviceCheckPauseRequest() is called.

Required Header Files
s3eDevice.h

S3E_API s3eBool s3eDeviceCheckQuitRequest ( )

Check whether or not the application has been requested to quit. Once the quit state has been set, i.e. when the S3E_DEVICE_EXIT callback has been generated, it will remain true until device exit.

Returns:
0 only if the application has not been quitted.
See also:
s3eDeviceCheckPauseRequest
Required Header Files
s3eDevice.h

S3E_API s3eResult s3eDeviceExecPushNext | ( | const char * | filename,
 |  | const char * | config_prepend = 0,
 |  | const char * | config_append = 0
 | ) |  |

Set the next S3E application to run after the current one has quit.

Parameters:
filename | The .s3e or .s86 S3E application file to load and run.
config_prepend | Contends of .icf file to prepend to that applications own settings.
config_append | Contends of .icf file to append to that applications own settings.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return one of:-
    • S3E_DEVICE_ERR_INVALID_DRIVE if an invalid drive was specified.
    • S3E_DEVICE_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
    • S3E_DEVICE_ERR_NOT_FOUND if filename does not exist.
    • S3E_DEVICE_ERR_TOO_MANY if too many .s3e/.s86 files are on the stack.
Remarks:
The .s3e or .s86 extension may be omitted from filename, in which case the system will append .s3e or .s86 for the ARM and x86 versions of S3E respectively.

Each call to s3eDeviceExecPushNext adds filename to the top of a stack of .s3e/.s86 files to run. When the current s3e file quits, the s3e file at the top of the stack is removed from the stack and executed.

This function does not cause filename to be loaded (although its existance is checked) so no memory will be consumed. If loading filename fails after the current .s3e/.s86 has quit, then S3E will shut down.

If filename is NULL then the current S3E application if pushed onto the stack.

S3E_API void s3eDeviceExit ( int code = 0 )

Exit the current s3e application.

Parameters:
code The return code that will be available to the parent application. This will exit the current s3e application immediately. All resources consumed by the application will be cleared up automatically. Static destructors for globally-defined classes and atexit() registered functions will not be called. If this behaviour is desired then the user should exit IwMain() normally. If another s3e application is set to execute via s3eDeviceExecPushNext(), it will be executed. If you want to return a non-zero exit code to the S3E layer use the S3E_DEVICE_EXIT_CODE property.
Required Header Files
s3eDevice.h

S3E_API s3eDeviceError s3eDeviceGetError ( )

Retrieve the last error, if any, for this subdevice.

See also:
s3eDeviceGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eDevice.h

S3E_API const char* s3eDeviceGetErrorString ( )

Retrieve the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eDeviceGetError
Remarks:
This function, as opposed to s3eDeviceGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eDevice.h

S3E_API int32 s3eDeviceGetInt ( s3eDeviceProperty property )

Retrieves an integer property for the Device Module.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 if the property is not valid.
    Call s3eAudioGetError() to retrieve an error code. This will return:
    S3E_DEVICE_ERR_PARAM if property is not valid.
Remarks:
You can pass in the following properties to the function:
  • S3E_DEVICE_OS:
    Returns one of the s3eDeviceOSID.
  • S3E_DEVICE_CLASS:
    Returns one of s3eDeviceClassID; the device class.
  • S3E_DEVICE_ID:
    Gets the device ID. This maps directly to a system-dependent device ID therefore device ID's cannot be assumed to be unique between different OS's. Previously unseen devices may return device ID's not in the enumeration. For BREW see device data sheets.
  • S3E_DEVICE_LANGUAGE:
    Return the current device language, which will be one of s3eDeviceLanguage.
  • S3E_DEVICE_TOTAL_RAM:
    Return the total physical RAM of this device.
  • S3E_DEVICE_FREE_RAM:
    Return the free memory that is currently available to the OS. This memory is not necessarily available to the s3e application.
  • S3E_DEVICE_ARCHITECTURE:
    Returns one of the s3eDeviceArchitecture.
  • S3E_DEVICE_S3E_VERSION:
    Returns S3E_VERSION.
See also:
s3eDeviceGetString

S3E_API const char* s3eDeviceGetString ( s3eDeviceProperty property )

Retrieves a string property for this subdevice.

Parameters:
property property to get.
Returns:
  • A NULL-terminated property string of length >= 1 if the operation succeeded.
  • The empty string ("") if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return: S3E_DEVICE_ERR_PARAM if property is invalid.
Remarks:
Valid properties are:
  • S3E_DEVICE_OS:
    returns one of {"SYMBIAN", "BREW", "WINDOWS", "WINMOBILE", "LINUX", "WIPI"}.
  • S3E_DEVICE_CLASS:
    returns e.g. "BREW_QCIF_3G".
  • S3E_DEVICE_ID:
    Gets the device ID. This maps directly to a system-dependent device ID therefore device ID's cannot be assumed to be unique between different OS's. Previously unseen devices may return device ID's not in the enumeration. For BREW see device data sheets.
  • S3E_DEVICE_PHONE_NUMBER:
    returns e.g. ("01321435345").
  • S3E_DEVICE_ARCHITECTURE:
    returns one of {"ARM4T", "ARM4", "ARM5T", "ARM5TE", "ARM5TEJ", "ARM6", "ARM6K", "ARM6T2", "ARM6Z", "x86"}.
  • S3E_DEVICE_S3E_VERSION:
    returns e.g. ("2.0.1") whereas the first number represents the major version (see S3E_VERSION_MAJOR) the second one the minor version (see S3E_VERSION_MINOR) and the third one being the revision (see S3E_VERSION_REVISION).
See also:
s3eDeviceGetInt

S3E_API s3eResult s3eDeviceRegister | ( | s3eDeviceCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userdata
 | ) |  |

Registers a callback to be called for an operating system event.

The available callback types are listed in s3eDeviceCallback.

Parameters:
cbid | ID of the event for which to register.
fn | callback function.
userdata | Value to pass to the userdata paramater of NotifyFunc.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return one of:
    • S3E_DEVICE_ERR_PARAM if cbid is not a valid member of s3eDeviceCallback or NotifyFunc is NULL.
    • S3E_DEVICE_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_DEVICE_ERR_ALREADY_REG If (cbid, NotifyFunc) has already been registered.
See also:
s3eDeviceUnRegister
Note:
For more information on the system data passed as a parameter to the callback registered using this function, see the s3eDeviceCallback enum.
Required Header Files
s3eDevice.h

S3E_API void s3eDeviceRequestQuit ( )

Request the quit state to be set.

See also:
s3eDeviceCheckQuitRequest
Required Header Files
s3eDevice.h

S3E_API s3eResult s3eDeviceSetInt | ( | s3eDeviceProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for the Device module.

Parameters:
property | property to set.
value | New value for property.
See also:
s3eDeviceGetInt
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return:
    • S3E_FILE_ERR_PARAM if property is invalid or value is invalid. You can pass in the following property to the function:
      • S3E_DEVICE_EXIT_CODE:
        Sets the return code of the current application.
Required Header Files
s3eDevice.h

S3E_API s3eResult s3eDeviceUnRegister | ( | s3eDeviceCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return one of:
    • S3E_FILE_ERR_PARAM if cbid is not a valid member of s3eDeviceCallback.
    • S3E_FILE_ERR_NOT_FOUND if fn is not registered for callback cbid.
Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eDeviceCallback enum.

It is not necessary to define a return value for any registered callback.

See also:
s3eDeviceRegister
Required Header Files
s3eDevice.h

S3E_API void s3eDeviceUnYield ( )

Exits the top-level yield.

See also:
s3eDeviceYield

s3eDeviceYieldUntilEvent

Remarks:
This function should be called from within a callback. It will cause the call to s3eDeviceYield(), during which the callback was generated, to exit immediately without completing the remainder of the yield duration.
This can be used for example, to wait for specific events by calling s3eDeviceYield(S3E_DEVICE_YIELD_FOREVER) then calling s3eDeviceUnYield() in the callback for a specific event.

If s3eDeviceYield() has been called recursively (ie a callback has called s3eDeviceYield()) then s3eDeviceUnYield() will only exit the last call to s3eDeviceYield(). Calling s3eDeviceUnYield() followed by s3eDeviceYield() will cancel the call to s3eDeviceUnYield().

Required Header Files
s3eDevice.h

S3E_API int64 s3eDeviceYield ( int32 ms = 0 )

Yield to the OS for a specified period of time.

Parameters:
ms Maximum number of milliseconds to yield. If this is zero, s3eDeviceYield() performs a minimal yield to the OS and fires any events generated from the OS devices. If this is S3E_DEVICE_YIELD_FOREVER, s3eDeviceYield() will not return until either a quit request is reveived or s3eDeviceUnYield() is called (e.g. from a callback).
Remarks:
This also allows the OS to do any required processing for this application, for example processing Device or UI messages. It may also permit the CPU to enter a low-power state. If ms is zero, S3E will yield for the minimum amount of time required by the underlying OS to perform essential processing. Therefore the S3E Application should call s3eDeviceYield(0) frequently to enable the underlying OS to respond in a timely manner to external events. S3E ensures that s3eDeviceYield(0) can be called very frequently (more that once a millisecond) with very little overhead. If ms is non-zero S3E will allow the OS to perform necessary processing and return control to the caller after ms milliseconds.
Required Header Files
s3eDevice.h

S3E_API void s3eDeviceYieldUntilEvent ( int32 ms = 2147483647L )

Yields until an event.

Parameters:
ms Maximum time to yield for. If this is zero or S3E_DEVICE_YIELD_FOREVER, s3eDeviceYieldUntilEvent() will yield forever (note that this is different to s3eDeviceYield)
See also:
s3eDeviceYield

s3eDeviceUnYield

Remarks:
This function yields until any callback event occurs. The yield will exit whether or not a callback is registered for the event.
Callback events include input events (see s3eKeyboardCallback), network events (see s3eSocketCallback) and operating system events (see s3eDeviceCallback). Therefore calling this function is a good way of reducing CPU usage when waiting for external events, for example in application menus. Sound channel callbacks (see s3eSoundChannelCallback) do not cause s3eDeviceYieldUntilEvent to return.
Required Header Files
s3eDevice.h


Airplay API Reference: S3E Device Interface Examples

Airplay API Reference > S3E API Documentation > S3E Device Interface > S3E Device Interface Examples >

S3E Device Interface Examples

This section illustrates how you can use the Device Interface functionality provided by S3E. This section contains two example applications:

  • S3E Launcher Example
  • S3E Event Example

Note: For more information on using the S3E Device Interface functionality, see the S3E Device Interface Overview.


Airplay API Reference: S3E Launcher Example

Airplay API Reference > S3E API Documentation > S3E Device Interface > S3E Device Interface Examples > S3E Launcher Example >

S3E Launcher Example

The following example demonstrates how to launch other applications from a base application using S3E's device interface functionality.

The main functions used to achieve this are:

  • s3eDeviceExecPushNext()
  • s3eDeviceExit()

The applications builds a list of sub applications by looking for folders in .. It then assigns buttons to launch each of these and displays this to the user. Airplay uses a push/pop stack to queue applicationsto be launched after the current one exits. This example waits for the relevant button to be pressed and then pushes itself followed by the relative sub-application to the stack using s3eDeviceExecPushNext(). It then exits using s3eDeviceExit(), at which point the subapp is popped from the stack and run. On exiting the subapp, the original application is popped and re-run.

Detection of button presses is handled using generic code in ExamplesMain.cpp. The state of playback is output to screen using the s3eDebugPrint() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "IwPath.h"
#include "IwDebug.h"
#include <sys/stat.h>
#include <dirent.h>

#include <vector>
#include <string>

//Base directory were launch applications subfolders are situated
#define APP_FOLDER "launcher"

static std::vector<std::string>   g_Applist;  //List of launch applications
static std::vector<char*>         g_Desclist; //List of matching descriptions
static unsigned int               g_App = 0;  //Index into list of applications

//-----------------------------------------------------------------------------
// Reads in a list of applications from the data\launcher folder for
// subsequent launching
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Navigate to basedirectory were launch applications are situated
    if (chdir(APP_FOLDER))
    {
        IwError(("launcher folder not found: %s", APP_FOLDER));
        return;
    }

    // Open directory for reading in all subfolders in which the launch applications are situated
    DIR* dir = opendir(".");

    struct dirent *dirent;

    // Read in a list of applications for launching
    while ((dirent = readdir(dir)))
    {
        if (dirent->d_type == DT_DIR)
        {
            g_Applist.push_back(dirent->d_name);

            // Store user friendly descriptions to display. The button
            // code needs these strings to persist in memory
            char* description = new char[256];
            sprintf(description, "launch subapp: %s", dirent->d_name);
            g_Desclist.push_back(description);
            NewButton(g_Desclist[g_Desclist.size()-1]);
        }
    }

    // dirent operation is finished so directory can be closed now
    closedir(dir);
}

//-----------------------------------------------------------------------------
// Do cleanup work
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    for (std::vector<char*>::iterator i = g_Desclist.begin(); i < g_Desclist.end(); i++)
    {
        delete[] (*i);
    }
}

//-----------------------------------------------------------------------------
// Assemble filename of application to launch and push it onto the stack.
// Beforehand push this application onto the stack so it gets restarted
// after the launched application has quit.
//-----------------------------------------------------------------------------
void LaunchGame()
{
    // Get basefolder in which the applications subfolders are situated
    char folder[S3E_FILE_MAX_PATH];
    strcpy(folder, APP_FOLDER);

    // Append folder name in which application resides
    IwPathJoin(folder, g_Applist[g_App].c_str(), S3E_FILE_MAX_PATH);

    // Append filename of application
    IwPathJoin(folder, g_Applist[g_App].c_str(), S3E_FILE_MAX_PATH);

    // Push the current application onto the device exec stack so it
    // will be launched after sample application has quit.
    s3eDeviceExecPushNext(NULL);

    // Specify which application to launch after s3eLauncher has quit
    if (s3eDeviceExecPushNext(folder) == S3E_RESULT_ERROR)
    {
        s3eDeviceError err = s3eDeviceGetError();

        if (err == S3E_DEVICE_ERR_UNSUPPORTED)
        {
            IwError( ("s3eDeviceExecPushNext unsupported on this platform!") );
        }
        else
        {
            IwError(("failed to launch app: %s", s3eDeviceGetErrorString()));
        }
    }

    // Quit this application in order to start the next one on the stack
    s3eDeviceExit();
}

//-----------------------------------------------------------------------------
// Process button state and launch subapp
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button *pressed = GetSelectedButton();

    if (pressed)
    {
        g_App = pressed->m_Index;
        LaunchGame();
    }

    return true;
}

//-----------------------------------------------------------------------------
// Display launch application text
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int ypos = GetYBelowButtons() + textHeight * 2;

    s3eDebugPrint((s3eSurfaceGetInt(S3E_SURFACE_WIDTH)-strlen("Launch an application")*6)/2, ypos, "`x666666Launch an application", 0);
}


Airplay API Reference: S3E Event Example

Airplay API Reference > S3E API Documentation > S3E Device Interface > S3E Device Interface Examples > S3E Event Example >

S3E Event Example

This example explains how an event based application can be implemented.

The main functions used to achieve this are:

  • s3eDeviceYield()
  • s3eDeviceUnYield()
  • s3eKeyboardRegister()
  • s3eDebugPrint()

Instead of having a loop with the following characteristics:

 loop until exit
 {
    update
    render
    yield
 }
the application yields to the mobile operating system and reacts to events. In this case we register a keyboard callback. Every time a key is pressed the application unyields and performs it's operation (in this case it queries the key, displays the result and then yields to the OS again).

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "s3e.h"
#include <string.h>
#include <stdio.h>
#include "Logo.h"

void ExampleRender();
void ExampleUpdate(s3eKey keyPressed);

static int32 KeyEventHandler(void* _systemData, void* userData);

//player status information
static char g_StatusString[256];

//-----------------------------------------------------------------------------
// Initialises the logo, screen & status and registers handler for key events
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Load logo for display
    LogoInit();

    // Initialise string for display
    strcpy(g_StatusString, "`x666666Press any directional key");

    // Update screen
    ExampleRender();

    // Register pointer event handler
    s3ePointerRegister(S3E_POINTER_BUTTON_EVENT, &KeyEventHandler, NULL);

    // Register keyboard event handler
    s3eKeyboardRegister(S3E_KEYBOARD_KEY_EVENT, &KeyEventHandler, NULL);
}

//-----------------------------------------------------------------------------
// Frees image data used for displaying of logo
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    LogoShutDown();
}

static void SoftkeyRender(const char* text, s3eDeviceSoftKeyPosition pos, void(*handler)())
{
    int width = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_WIDTH);
    int height = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    width *= strlen(text) - 8;
    int x = 0;
    int y = 0;
    switch (pos)
    {
        case S3E_DEVICE_SOFTKEY_BOTTOM_LEFT:
            y = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT) - height;
            x = 0;
            break;
        case S3E_DEVICE_SOFTKEY_BOTTOM_RIGHT:
            y = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT) - height;
            x = s3eSurfaceGetInt(S3E_SURFACE_WIDTH) - width;
            break;
        case S3E_DEVICE_SOFTKEY_TOP_RIGHT:
            y = 0;
            x = s3eSurfaceGetInt(S3E_SURFACE_WIDTH) - width;
            break;
        case S3E_DEVICE_SOFTKEY_TOP_LEFT:
            x = 0;
            y = 0;
            break;
    }
    s3eDebugPrint(x, y, text, 0);
    if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_PRESSED)
    {
        int pointerx = s3ePointerGetX();
        int pointery = s3ePointerGetY();
        if (pointerx >= x && pointerx <= x+width && pointerx >=x && pointery <= y+height)
            handler();
    }
}

static void SoftkeysRender()
{
    //int advance = s3eDeviceGetInt(S3E_DEVICE_ADVANCE_SOFTKEY_POSITION);
    //SoftkeyRender("`x666666ASK", (s3eDeviceSoftKeyPosition)advance);
    int back = s3eDeviceGetInt(S3E_DEVICE_BACK_SOFTKEY_POSITION);
    SoftkeyRender("`x666666Exit", (s3eDeviceSoftKeyPosition)back, s3eDeviceRequestQuit);
}

//-----------------------------------------------------------------------------
// Main global function
//-----------------------------------------------------------------------------
int main()
{
    ExampleInit();

    // Yield to the operating system until the user/loader/OS has requested a shutdown
    while (!s3eDeviceCheckQuitRequest())
    {
        // Yield until unyield is called or a quit request is recieved
        s3eDeviceYield(S3E_DEVICE_YIELD_FOREVER);
    }

    strcpy(g_StatusString, "`x666666Exiting example");

    ExampleShutDown();
    return 0;
}

//-----------------------------------------------------------------------------
// Key event handler:
// systemData contains a structure of type s3eKeyboardEvent which contains
// information about the pressed key.
// Note the generic makeup of the callback function, which always supplies
// the parameters:
// systemData - callback-specific system supplied data.
// userData - data supplied by user at callback registration (in this case
// NULL) and returns int32 as success staus.
//-----------------------------------------------------------------------------
static int32 KeyEventHandler(void* systemData, void* userData)
{
    // Wake up and take control from the OS
    s3eDeviceUnYield();

    s3ePointerUpdate();

    // Read in the type of key that has been pressed
    s3eKeyboardEvent* pkeyPressed = (s3eKeyboardEvent*)systemData;
    s3eKey keyPressed = (*pkeyPressed).m_Key;

    // Update internal state
    ExampleUpdate(keyPressed);

    // Update screen representation
    ExampleRender();

    return 0;
}

//-----------------------------------------------------------------------------
// Update the internal state by testing for valid key presses. Furthermore
// checks if the application needs to be exited triggered either by user
// request (pressed "Esc" or "Leftshift") or the OS (s3eDeviceCheckQuitRequest
// returns S3E_TRUE).
//-----------------------------------------------------------------------------
void ExampleUpdate(s3eKey keyPressed)
{
    // Check for valid key presses
    if (keyPressed == s3eKeyAbsLeft)
        strcpy(g_StatusString, "`x666666Left key pressed");
    else if (keyPressed == s3eKeyAbsUp)
        strcpy(g_StatusString, "`x666666Up key pressed");
    else if (keyPressed == s3eKeyAbsRight)
        strcpy(g_StatusString, "`x666666Right key pressed");
    else if (keyPressed == s3eKeyAbsDown)
        strcpy(g_StatusString, "`x666666Down key pressed");
    else if (keyPressed == s3eKeyEsc || keyPressed == s3eKeyLSK)
    {
        // An exit request has occurred
        s3eDeviceRequestQuit();
    }
    else
    {
        if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT))
        {
            sprintf(g_StatusString, "`x666666Pointer event detected. x=%ld, y=%ld", s3ePointerGetX(), s3ePointerGetY());
        }
        else
            strcpy(g_StatusString, "`x666666Invalid key pressed");
    }
}

//-----------------------------------------------------------------------------
// Update screen representation
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textWidth = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_WIDTH);
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    const int width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    const int height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);

    // Draw logo
    LogoRender();

    // Draw the exit key
    SoftkeysRender();

    // Print centered information about keypresses
    if (!s3eKeyboardGetInt(S3E_KEYBOARD_HAS_DIRECTION))
    {
        strcpy(g_StatusString, "`x666666Device has no direction keys.");
    }

    s3eDebugPrint((width-(strlen(g_StatusString)-8)*textWidth)/2, 10 * textHeight, g_StatusString, 1);

    s3eDebugPrint((width-strlen("Press Esc or LS to Exit")*textWidth)/2,
                (height -1 * textHeight ), "`xfb0b0cPress Esc or LSK to Exit", 0);

    // Redraw screen
    s3eSurfaceShow();
}


Airplay API Reference: S3E Extensions

Airplay API Reference > S3E API Documentation > S3E Extensions >

S3E Extensions

Basic Extensions functionality:

  • S3E Extensions Overview
  • Extensions API Reference

Extension functions available by platform:

  • Generic Extensions
  • iPhone Extensions


Airplay API Reference: S3E Extensions Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > S3E Extensions Overview >

S3E Extensions Overview

The Extension Module provides support for extra low-level, often platform-specific, functionality that is not covered by the generic subdevices in the rest of the S3E API. This is in contrast to other Airplay APIs, which provide the same functionality independent of which device or OS the application is being run on.

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.

Extension documentation is sub-divided into Generic Extensions (supported on multiple platforms) and platform-specific extensions (for example iPhone Extensions). An extension may be extended to support more platforms in future updates of the SDK.

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 APIs.

Each extension set includes a function of the format s3eExt*Available(). This will return S3E_TRUE at runtime if the functions in the relevant extension are supported on the current device. 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. Calls to any extension functionality should be wrapped in s3eExt*Available() checks to avoid unexpected behaviour on devices that the do not support the extension.

For a simple example of using an extension, see the OS Read String Extension Example.

Support for generic extension functionality such as accessing any extension function by name and getting error information is provided though s3eExt.h. See Extensions API Reference for more information.


Airplay API Reference: Extensions API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Extensions API Reference >

Extensions API Reference
[S3E]

Functions

S3E_API s3eResult | s3eExtGet (const char *extension, void *functions, uint32 functionsLen)
S3E_API s3eExtError | s3eExtGetError ()
S3E_API const char * | s3eExtGetErrorString ()
S3E_API s3eResult | s3eExtGetHash (uint32 hash, void *functions, uint32 functionsLen)

Detailed Description

For more information on the Extensions functionality provided by the S3E module, see the S3E Extensions section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eExtError

Enumerator:
S3E_EXT_ERR_NONE | No Error.
S3E_EXT_ERR_PARAM | Invalid parameter.
S3E_EXT_ERR_NOT_FOUND | The specified callback was not found for removal.

Function Documentation

S3E_API s3eResult s3eExtGet | ( | const char * | extension,
 |  | void * | functions,
 |  | uint32 | functionsLen
 | ) |  |

Retrieves an S3E extension.

Parameters:
extension | The name of the extension to load.
functions | Pointer to an array of function pointers to be filled in in order to access the extension.
functionsLen | Length of array functions in bytes.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return:
    • S3E_EXT_ERR_PARAM if extension is NULL, functionsLen is 0 and functions is non-NULL, functions is NULL and functionsLen is non-NULL, or functionsLen is not the correct size for extension extension.
    • S3E_EXT_ERR_NOT_FOUND if extension extension is not found.
Remarks:
To check for the presence of an extension without retreiving it set functions=NULL and functionsLen = size of function structure. This function will return S3E_RESULT_SUCCESS if the extension is available.
This will fill functions with a list of function pointers. The s3e Extension will usually have an associated structure which functions can be cast to. This structure can then be used to invoke s3e extension functions.

Required Header Files
s3eExt.h

S3E_API s3eExtError s3eExtGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eExtGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eExt.h

S3E_API const char* s3eExtGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eExtGetError
Remarks:
This function, as opposed to s3eExtGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eExt.h

S3E_API s3eResult s3eExtGetHash | ( | uint32 | hash,
 |  | void * | functions,
 |  | uint32 | functionsLen
 | ) |  |

Works exactly like s3eExtGet but takes the hash of the string name of the extension. This makes it possbible for an application to reduce the number of string contants it contains.

Required Header Files
s3eExt.h


Airplay API Reference: Generic Extensions

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions >

Generic Extensions

The following extensions are supported on multiple platforms. They are grouped by the type of functionality they cover and declared in similarly-named headers located in s3e/h/s3eExtensions. Which platforms are supported is documented alongside the function or group of functions as required. Functions will produce no result, and return null where appropriate, when called on an OS or OS version that is not supported for them. Each group provides a function for checking whether it is supported at runtime.

The following generic extension functions are available:

  • Debug Heap Extension
  • Library Extension
  • Metrics Extension
  • OS Exec Extension
  • OS Read String Extension


Airplay API Reference: Debug Heap Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Debug Heap Extension >

Debug Heap Extension

The S3E Debug Heap Extension documentation contains the following sections:

  • Debug Heap Extension Overview
  • Debug Heap Extension API Reference


Airplay API Reference: Debug Heap Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Debug Heap Extension > Debug Heap Extension Overview >

Debug Heap Extension Overview

The s3eExtDebugHeap API allows access to the pointer to the debug heap. The debug heap is a bucket of memory which is separate from the memory heap available to the application.

Typically this memory is used by middle-ware engines for tasks that should not disturb the running application's memory heap. e.g. Creating debugging objects or temporary resources.


Airplay API Reference: Debug Heap Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Debug Heap Extension > Debug Heap Extension API Reference >

Debug Heap Extension API Reference

Functions

void * | s3eExtDebugHeap ()
S3E_BEGIN_C_DECL s3eBool | s3eExtDebugHeapAvailable ()
int32 | s3eExtDebugHeapSize ()

Detailed Description

This extension API allows access to the pointer to the debug heap.

For more information on the functionality provided by this extension, see the "Debug Heap Extension" section of the S3E API Documentation.

Function Documentation

void* s3eExtDebugHeap ( )

The first time this is called, it returns a pointer that points to the icf-file defined [S3E] DebugHeap bytes of memory

S3E_BEGIN_C_DECL s3eBool s3eExtDebugHeapAvailable ( )

Returns S3E_TRUE if the DebugHeap extension is available.

int32 s3eExtDebugHeapSize ( )

Returns the size of the debug heap


Airplay API Reference: Library Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Library Extension >

Library Extension

The S3E Library Extension documentation contains the following sections:

  • Library Extension Overview
  • Library Extension API Reference


Airplay API Reference: Library Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Library Extension > Library Extension Overview >

Library Extension Overview

This extension API allows runtime loading of DLLs and getting pointers to their functions.

By using this API, the application can get access to functionalities on the device that are not supported by the Airplay SDK.


Airplay API Reference: Library Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Library Extension > Library Extension API Reference >

Library Extension API Reference

Functions

S3E_BEGIN_C_DECL s3eBool s3eExtLibraryAvailable ()

Detailed Description

This extension API allows runtime loading of DLLs and getting pointers to their functions.

For more information on the functionality provided by this extension, see the "Library Extension" section of the S3E API Documentation.

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtLibraryAvailable ( )

Returns S3E_TRUE if the Library extension is available.


Airplay API Reference: Metrics Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Metrics Extension >

Metrics Extension

The S3E Metrics Extension documentation contains the following sections:

  • Metrics Extension Overview
  • Metrics Extension API Reference


Airplay API Reference: Metrics Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Metrics Extension > Metrics Extension Overview >

Metrics Extension Overview

This API allows access to the Airplay metrics logging system.

Currently this API is only supported under the Win32 emulator platform.


Airplay API Reference: Metrics Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > Metrics Extension > Metrics Extension API Reference >

Metrics Extension API Reference

Data Structures

struct | s3eExtMetricsFuncs
struct | s3eExtMetricsInfo

Metrics Functionality

Required Header Files
s3eDebug.h

void | s3eExtMetricsAdd (const char *metric, int32 val)
void | s3eExtMetricsFrameReset (const char *metric, s3eBool reset)
int64 | s3eExtMetricsGetInt (const char *metric)
const char * | s3eExtMetricsGetString (const char *metric)
bool | s3eExtMetricsIsEnabled ()
void | s3eExtMetricsRegister (const char *metric, s3eCallback fn, void *data)
void | s3eExtMetricsRemove (const char *metric)
void | s3eExtMetricsSetInt (const char *metric, int64 val)
void | s3eExtMetricsSetString (const char *metric, const char *string)

Detailed Description

This API allows access to the Airplay metrics logging system.

For more information on the functionality provided by this extension, see the "Metrics Extension" section of the S3E API Documentation.

Function Documentation

void s3eExtMetricsAdd | ( | const char * | metric,
 |  | int32 | val
 | ) |  |

Increase the value of a metric by a specific amount

Parameters:
metric | Metric to increase, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
val | Value to add to the metric
Remarks:
If metric has not been created, this will create an integer metric named metric whose value is val. By default this metric will reset to zero at the end of a frame.
Otherwise, val will be added to the metric metric. If metric is a string metric, an assertion message will be displayed.

void s3eExtMetricsFrameReset | ( | const char * | metric,
 |  | s3eBool | reset
 | ) |  |

Determines whether a metric resets at the end of frame.

Parameters:
metric | Metric to set, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
reset | S3E_TRUE to cause metric to reset at the end of frame, S3E_FALSE otherwise
Remarks:
The end of a frame is marked by a call to s3eSurfaceShow or eglSwapBuffers by the application. If a metric resets at the end of a frame, its value will be set to zero whenever s3eSurfaceShow or eglSwapBuffers is called.
Only metrics created by s3eExtMetricsAdd will reset at the end of a frame by default.

int64 s3eExtMetricsGetInt ( const char * metric )

Retrieve the value of an integer metric

Parameters:
metric Metric to get, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
Returns:
On success, the value of the metric, or 0 if the metric does not exist.

const char* s3eExtMetricsGetString ( const char * metric )

Retrieve the value of a string metric

Parameters:
metric Metric to get, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
Returns:
On success, a pointer to the metrics NULL terminated string data, or the empty string ("") if the metric does not exist.

bool s3eExtMetricsIsEnabled ( )

Return whether the metrics host is accepting metrics updates

Returns:
true if the metrics host is accepting updates, false if not
Remarks:
The return value of this function corresponds to whether metrics are enabled in the emulator. If metrics are disabled in the emulator, this function returns false and all calls to metrics functions are ignored. This function is therefore useful for disabling metrics-updating code for performance reasons if metrics are disabled in the emulator.

void s3eExtMetricsRegister | ( | const char * | metric,
 |  | s3eCallback | fn,
 |  | void * | data
 | ) |  |

Registers an integer metric whose value is retrieved by a callback

Parameters:
metric | Metric to set, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
fn | callback to call
data | user data value to supply to fn
Remarks:
When the system wishes to know the value for the metric, fn will be called. fn will be called with systemData as a pointer to s3eExtMetricsInfo and userData set to data.
If metric has not been created, this will create an integer metric named metric whose value is obtained by calling fn

Otherwise, the function will fail

void s3eExtMetricsRemove ( const char * metric )

Remove one or more metrics

Parameters:
metric Metric(s) to remove, 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
Remarks:
if metric specifies a sub-module under which more sub-modules or metrics are listed, then all submodules and metrics under metric will be removed.

void s3eExtMetricsSetInt | ( | const char * | metric,
 |  | int64 | val
 | ) |  |

Set the value of an integer metric

Parameters:
metric | Metric to set, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
val | Value to set
Remarks:
If metric has not been created, this will create an integer metric named metric whose value is val. By default this metric will not reset to zero at the end of a frame.
Otherwise, metric metric will be set to val. If metric is not an integer metric, an assertion message will be displayed.

void s3eExtMetricsSetString | ( | const char * | metric,
 |  | const char * | string
 | ) |  |

Set the value of a string metric

Parameters:
metric | Metric to set, in the form 'module/submodule1/submodule2/... .../metric', up to 255 characters long.
string | String to set. There is no limit on the length of string.
Remarks:
If metric has not been created, this will create a string metric named metric whose data is copied from string.
Otherwise, the string data of metric metric will be copied from string. If metric is not a string metric, an assertion message will be displayed.

Variable Documentation

const char* s3eExtMetricsInfo::m_Name [inherited]

[in] Name of metric


Airplay API Reference: OS Exec Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Exec Extension >

OS Exec Extension

The S3E OS Exec Extension documentation contains the following sections:

  • OS Exec Extension Overview
  • OS Exec Extension API Reference
  • OS Exec Extension Example


Airplay API Reference: OS Exec Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Exec Extension > OS Exec Extension Overview >

OS Exec Extension Overview

The s3eExtOSExec API allows the application to call the underlying OS method for handling file types that can be better dealt with by the OS.

At the moment only URL type is supported by this API.

Opening an URL

On most devices, calling the function s3eOSExecExecute with a URL string, the underlying OS web browser will open the web page specified by the URL. The calling application can also decide whether it wants to remain running after the browser has launched by passing a boolean flag as the 2nd parameter.


Airplay API Reference: OS Exec API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Exec Extension > OS Exec API Reference >

OS Exec API Reference

Functions

S3E_BEGIN_C_DECL s3eBool | s3eExtOSExecAvailable ()
s3eResult | s3eOSExecExecute (const char *url, s3eBool exit)

Detailed Description

The s3eExtOSExec API allows the application to call the underlying OS method for handling file types that can be better dealt with by the OS.

For more information on the OSExec functionality provided by the S3E module, see the OSExec section of the S3E API Documentation.

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtOSExecAvailable ( )

Returns S3E_TRUE if the OSExec extension is available.

s3eResult s3eOSExecExecute | ( | const char * | url,
 |  | s3eBool | exit
 | ) |  |

Launch a URL using the operating systems builtin handlers.

Parameters:
url | The URL to launch.
exit | Flag to indicate whether the S3E application should exit once the command has been run
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.


Airplay API Reference: OS Exec Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Exec Extension > OS Exec Extension Example >

S3E s3eOSExec Example

The following example calls the s3eOSExec API to allow the user to launch a URL using the native OS handler on the device.

The functions required to achieve this are:

  • s3eExtOSExecAvailable()
  • s3eOSExecExecute()

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3eExt_OSExec.h"

static const char* g_URL = "http://www.airplaysdk.com";
static Button* g_ButtonRun = 0;
static s3eResult g_Result = S3E_RESULT_SUCCESS;

void ExampleInit()
{
    // Create the UI.
    g_ButtonRun = NewButton("Run command to open an URL");
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    // Check for the availabilty of the OS Execute functionality.
    // If it is available then enable the button.
    if (s3eExtOSExecAvailable())
    {
        g_ButtonRun->m_Enabled = true;
    }
    else
        g_ButtonRun->m_Enabled = false;

    // Check for the interface button event
    Button* pressed = GetSelectedButton();

    // If the button has been selected, try to execute the OS command
    // and store the result.
    if (pressed == g_ButtonRun)
        g_Result =  s3eOSExecExecute(g_URL, S3E_FALSE);

    return true;
}

//-----------------------------------------------------------------------------
// The following function display the user's prompt and any error messages.
// The s3eDebugPrint() function to print the strings.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Print results
    if (!s3eExtOSExecAvailable())
    {
        s3eDebugPrint(50, 100, "`xff0000Executing host OS commands API isn't available on this device.", 1);
    }

    if (g_Result == S3E_RESULT_ERROR)
    {
        s3eDebugPrint(50, 100, "`xff0000Failed to open the URL.", 1);
    }
}


Airplay API Reference: OS Read String Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Read String Extension >

OS Read String Extension

The S3E OS Read String Extension documentation contains the following sections:

  • OS Read String Extension Overview
  • OS Read String Extension API Reference
  • OS Read String Extension Example


Airplay API Reference: OS Read String Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Read String Extension > OS Read String Extension Overview >

OS Read String Extension Overview

The OSReadString API provides the application with a method to prompt the user for text input. For touch screen only devices, a call to s3eExtOSReadUserStringUTF8() will pop up a virtual keyboard and a modal dialog box for the user to enter text.

For devices with a keyboard, it is advisable to use the s3eKeyboard API to read the text input instead of using this API as it will maintain the application's GUI consistency.

At the moment only the iPhone supports this API.

Specifying the type of text

The application can specified the type of text input it's expecting from the user by setting the flags field to s3eExtOSReadUserStringUTF8. By specifying the type of text, it allows the virtual keyboard to configure itself with the dialog and the best set of keys needed to enter the text. Supported flags are S3E_OSREADSTRING_FLAG_PASSWORD, S3E_OSREADSTRING_FLAG_EMAIL and S3E_OSREADSTRING_FLAG_URL.


Airplay API Reference: OS Read String Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Read String Extension > OS Read String Extension API Reference >

OS Read String Extension API Reference

Functions

S3E_BEGIN_C_DECL s3eBool | s3eExtOSReadStringAvailable ()
const char * | s3eExtOSReadUserStringUTF8 (const char *promptUTF8, int flags=0)

Detailed Description

The API OSReadString provides the application with a method to prompt the user for text input.

For more information on the functionality provided by this extension, see the "OS Read String Extension" section of the S3E API Documentation.

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtOSReadStringAvailable ( )

Returns S3E_TRUE if the OSReadString extension is available.

const char* s3eExtOSReadUserStringUTF8 | ( | const char * | promptUTF8,
 |  | int | flags = 0
 | ) |  |

Displays an OS specific modal dialog along with the UTF8 format prompt, where the user can enter a string which is returned in UTF8 format.

Parameters:
promptUTF8 | prompt to display to user user in the text entry dialogue.
flags | optional flags the specify the type of text the user is expected to enter


Airplay API Reference: OS Read String Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > Generic Extensions > OS Read String Extension > OS Read String Extension Example >

S3E s3eOSReadString Example

The following example call the s3eOSReadString API to allow the user to use the phone's native string input dialog to enter a Password, an Email address and an URL then display the resulting texts.

The functions required to achieve this are:

  • s3eExtOSReadStringAvailable()
  • s3eExtOSReadUserStringUTF8()
  • s3eDebugPrintf()

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.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3eExt_OSReadString.h"

static char g_Password[256];
static char g_Email[512];
static char g_URL[1024];

void ExampleInit()
{
    g_Password[0] = '0';
    g_Email[0] = '0';
    g_URL[0] = '0';
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    // Check for the availabilty of the device's strings type input functionality.
    if (s3eExtOSReadStringAvailable())
    {
        // For every string type, prompt for the user's input.
        if (g_Password[0] == '0')
        {
            strcpy(g_Password, s3eExtOSReadUserStringUTF8("Enter a password", S3E_OSREADSTRING_FLAG_PASSWORD));
        }

        if (g_Email[0] == '0')
        {
            strcpy(g_Email, s3eExtOSReadUserStringUTF8("Enter an email address", S3E_OSREADSTRING_FLAG_EMAIL));
        }

        if (g_URL[0] == '0')
        {
            strcpy(g_URL, s3eExtOSReadUserStringUTF8("Enter an URL link", S3E_OSREADSTRING_FLAG_URL));
        }
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs the strings entered by the user.
// The s3eDebugPrint() function to print the strings.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Print results
    if (!s3eExtOSReadStringAvailable())
    {
        s3eDebugPrint(50, 100, "`xff0000Strings reading API isn't available on this device.", 1);
    }
    else
    {
        const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

        int y = 5 * textHeight;

        s3eDebugPrintf(10, y, 1, "`x0000ffPassword: %s", g_Password);
        y += textHeight * 3;

        s3eDebugPrintf(10, y, 1, "`x0000ffEmail: %s", g_Email);
        y += textHeight * 3;

        s3eDebugPrintf(10, y, 1, "`x0000ffURL: %s", g_URL);
    }
}


Airplay API Reference: iPhone Extensions

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions >

iPhone Extensions

Airplay supports iPhone-specific functionality through the extensions referenced here. These are grouped by the type of functionality they cover and are generally C wrappers for similarly named functionality available in the iPhone SDK. Functions in each extension group are declared in a matching header located in s3e/h/s3eExtensions.

Some functions are only valid on devices running a newer version of the iPhone operating system/firmware. These limitations are documented alongside the function or group of functions. If no limitations are given then the functions can be used on any version of the iPhone OS. Functions will produce no result, and return null where appropriate, when called on an OS or OS version that is not supported by them.

The following groups of extension functions are available for the iPhone platform:

  • Background Audio Extension
  • Background Music Extension
  • iPhone Extension
  • Micro Transaction Extension
  • ZeroConf Extension


Airplay API Reference: Background Audio Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Audio Extension >

Background Audio Extension

The Background Audio Extension documentation contains the following sections:

  • Background Audio Extension Overview
  • Background Audio Extension API Reference
  • Background Audio Extension Example


Airplay API Reference: Background Audio Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Audio Extension > Background Audio Extension Overview >

Background Audio Extension Overview

Background Audio allows the application to query whether the device is currently playing audio in the background and to specify whether to mix this audio with that of the application.

This extension is supported on iPhone/iPod touch only and is available for all versions of the OS. Use s3eExtBackgroundAudioAvailable() to check if the device running the application supports this extension. Calling any other Background Audio functions on an unsupprted device will have no effect and will display an error message when using a debug loader.

Use s3eExtBackgroundAudioSetMix() to enable/disable mixing the background audio with that of the application and s3eExtBackgroundAudioGetMix() to find the current state. s3eExtBackgroundAudioIsPlaying() returns true if the device is currently playing audio, e.g. a song from the iPod application is playing.


Airplay API Reference: Background Audio Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Audio Extension > Background Audio Extension API Reference >

Background Audio Extension API Reference

Functions

s3eBool | s3eExtBackgroundAudioGetMix ()
s3eBool | s3eExtBackgroundAudioIsPlaying ()
s3eBool | s3eExtBackgroundAudioSetMix (s3eBool mix)

Detailed Description

Background Audio allows the application to query whether the device is currently playing audio in the background and to specify whether to mix this audio with that of the application.

This extension is supported on iPhone only.

For more information on the functionality provided by this extension, see the "Background Audio Extension" section of the S3E API Documentation.

Function Documentation

s3eBool s3eExtBackgroundAudioGetMix ( )

Returns S3E_TRUE if the last call to s3eBackgroundAudioSetMix() had S3E_TRUE as the parameter.

s3eBool s3eExtBackgroundAudioIsPlaying ( )

Returns S3E_TRUE if the BackgroundAudio extension is available.

s3eBool s3eExtBackgroundAudioSetMix ( s3eBool mix )

Controlls the mixing of our audio with any background audio. If S3E_TRUE is passed then background audio will be mixed in. If S3E_FALSE is passed then only our audio will play (this is the default setting).


Airplay API Reference: Background Audio Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Audio Extension > Background Audio Extension Example >

S3E Background Audio Example

The following example uses the S3E Background Audio extension to turn on and off the mixing of audio from the application (using s3eSound) with audio from the device (e.g. from as it's music player).

The main functions used to achieve this are:

  • s3eExtBackgroundAudioAvailable()
  • s3eExtBackgroundAudioSetMix()
  • s3eSoundChannelPlay()
  • s3eSoundChannelStop()

s3eSound is used to buffer a simple audio clip from file and play it back in order to demonstrate how this can be mixed with the background audio. On-screen buttons are used to swtich mixing and s3eSound playback on and off. These are implemented in ExamplesMain.cpp.

The current background audio setting is output to screen using s3eDebugPrint().

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//----------------------------------------------------------------------------
// ExampleS3EBackgroundAudio
//----------------------------------------------------------------------------

#include "ExamplesMain.h"
#include <s3eExtensions/s3eExt_BackgroundAudio.h>
#include <set>

static int16*   g_SoundBuffer = 0;
static int32    g_SoundFileSize = 0;
static int      g_SoundChannel = 0;
static bool     g_SoundIsPlaying = false;
static Button*  g_ButtonMixAudio = 0;
static Button*  g_ButtonPlaySound = 0;

void ExampleInit()
{
    if (s3eExtBackgroundAudioAvailable())
    {
        g_ButtonMixAudio = NewButton("iPod/s3e audio mixing");
        g_ButtonPlaySound = NewButton("Play/stop s3eSound");

        // Setup sound buffer to play audio - see s3eSoundBasic example
        s3eFile *fileHandle = s3eFileOpen("test.raw", "rb");
        g_SoundFileSize = s3eFileGetSize(fileHandle);
        g_SoundBuffer = (int16*)s3eMallocBase(g_SoundFileSize);
        memset(g_SoundBuffer, 0, g_SoundFileSize);
        s3eFileRead(g_SoundBuffer, g_SoundFileSize, 1, fileHandle);
        s3eFileClose(fileHandle);
        s3eSoundSetInt(S3E_SOUND_DEFAULT_FREQ, 8000);
    }
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (s3eExtBackgroundAudioAvailable())
    {
        if (pressed == g_ButtonMixAudio)
        {
            // Enable/disable mixing s3eSound with background audio from iPod/MusicPicker
            s3eExtBackgroundAudioSetMix(!s3eExtBackgroundAudioGetMix());
        }

        else if (pressed == g_ButtonPlaySound)
        {
            // Play s3eSound to check if it can be mixed with background audio
            if (!g_SoundIsPlaying)
            {
                s3eSoundChannelPlay(g_SoundChannel, g_SoundBuffer, g_SoundFileSize/2, 0, 0);
                g_SoundIsPlaying = true;
            }
            else
            {
                s3eSoundChannelStop(g_SoundChannel);
                g_SoundIsPlaying = false;
            }
        }
    }

    return true;
}

void ExampleRender()
{
    int y = 340;
    int x = 20;

    if (s3eExtBackgroundAudioAvailable())
    {
        if (s3eExtBackgroundAudioGetMix())
            s3eDebugPrintf(x, y, 1, "`x666666Mixing of background (iPod) & s3e audio enabled");
        else
            s3eDebugPrintf(x, y, 1, "`x666666Mixing of background (iPod) & s3e audio disabled");

        y += 12;

        if (g_SoundIsPlaying)
            s3eDebugPrintf(x, y, 1, "`x666666s3eSound is playing");
        else
            s3eDebugPrintf(x, y, 1, "`x666666s3eSound is stopped");
    }
    else
    {
        s3eDebugPrint(0, 100, "`xee3333BackgroundAudio extension unavailable", 1);
    }
}


Airplay API Reference: Background Music Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Music Extension >

Background Music Extension

The Background Music Extension documentation contains the following sections:

  • Background Music Extension Overview
  • Background Music Extension API Reference
  • Background Music Extension Example


Airplay API Reference: Background Music Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Music Extension > Background Music Extension Overview >

Background Music Extension Overview

Background Music provides access to the device's music library through the Music Picker interface, plus playback controls for the currently playing music and the ability to query track and player status.

This extension is currently only supported on the iPhone platform and on devices running OS version 3.0 or newer. It accesses and plays media items from the iPod library through the Media Player Framework > Music Player Controller interface. Support for other platforms is planned for a future release.

Picking Tracks to Play

Use s3eBackgroundMusicPickMusicItems to launch the Music Picker interface. This is a variation of the regular iPod interface which allows the user to select tracks to queue up for playback while the application is running. The application blocks and waits for the Music Picker to be closed before continuing. No additional handling of the user input is required; on closing the music picker, the selected tracks will be played in the order chosen. The playback of these tracks can then be controlled using the music playback controls below.

The iPhone supports music playback through the iPod music player (controlling the built-in iPod application) and application music player (play music locally within application). Currently Airplay supports only the first of these options, meaning that changing the playback state, queuing up tracks, etc. will affect the global iPod state when the application is exited. Further Music Picker functionality may be added in a future version of Airplay.

Music Playback Controls

The playback of music, which may have been played from the regular iPod app before launching this application or from using s3eBackgroundMusicPickMusicItems(), can be controlled with a set of basic playback controls. Use s3eBackgroundMusicPlay(), s3eBackgroundMusicPause() and s3eBackgroundMusicStop() to control the currently playing track. Other controls include s3eBackgroundMusicBeginSeekingForward() to fast-forward through the current track and s3eBackgroundMusicSkipToNextItem() to skip to the next track. See the API reference for a full list of functions available.

Music Playback State

Background Music provides access to the current playback state through s3eBackgroundMusicGetInt(s3eBackgroundMusicProperty) and s3eBackgroundMusicSetInt(). These functions take an enumeration to specify which property to query/change. For some properties, a relevant enum value is returned/required. For example s3eBackgroundMusicGetInt(S3E_BACKGROUNDMUSIC_PLAYBACK_STATE) will return one of s3eBackgroundMusicPlaybackState.

Track Information

A music item/track can be represented using the s3eBackgroundMusicItem struct. s3eBackgroundMusicGetCurrentItem() obtains a pointer to a s3eBackgroundMusicItem representing the currently playing track. This struct is opaque; to access information on a track, pass a pointer to the s3eBackgroundMusicItem plus the s3eBackgroundMusicItemProperty required to s3eBackgroundMusicItemGetInt() or s3eBackgroundMusicItemGetString().


Airplay API Reference: Background Music Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Music Extension > Background Music Extension API Reference >

Background Music Extension API Reference

Enumerations

enum s3eBackgroundMusicItemProperty {
S3E_BACKGROUNDMUSICITEM_PERSISTANT_ID = 0,
S3E_BACKGROUNDMUSICITEM_MEDIA_TYPE = 1,
S3E_BACKGROUNDMUSICITEM_TITLE = 2,
S3E_BACKGROUNDMUSICITEM_ALBUM_TITLE = 3,
S3E_BACKGROUNDMUSICITEM_ARTIST = 4,
S3E_BACKGROUNDMUSICITEM_ALBUM_ARTIST = 5,
S3E_BACKGROUNDMUSICITEM_GENRE = 6,
S3E_BACKGROUNDMUSICITEM_COMPOSER = 7,
S3E_BACKGROUNDMUSICITEM_PLAYBACK_DURATION = 8,
S3E_BACKGROUNDMUSICITEM_ALBUM_TRACK_NUMBER = 9,
S3E_BACKGROUNDMUSICITEM_ALBUM_TRACK_COUNT = 10,
S3E_BACKGROUNDMUSICITEM_DISC_NUMBER = 11,
S3E_BACKGROUNDMUSICITEM_DISC_COUNT = 12,
S3E_BACKGROUNDMUSICITEM_LYRICS = 13,
S3E_BACKGROUNDMUSICITEM_IS_COMPILATION = 14
}
enum | s3eBackgroundMusicMediaType
enum | s3eBackgroundMusicPlaybackState
enum s3eBackgroundMusicProperty {
S3E_BACKGROUNDMUSIC_CURRENT_PLAYBACK_TIME = 0,
S3E_BACKGROUNDMUSIC_PLAYBACK_STATE = 1,
S3E_BACKGROUNDMUSIC_PLAYBACK_REPEAT_MODE = 2,
S3E_BACKGROUNDMUSIC_PLAYBACK_SHUFFLE_MODE = 3,
S3E_BACKGROUNDMUSIC_PLAYBACK_VOLUME = 4,
S3E_BACKGROUNDMUSIC_PLAYBACK_MIX = 5
}
enum | s3eBackgroundMusicRepeatMode
enum | s3eBackgroundMusicShuffleMode

Functions

s3eResult s3eBackgroundMusicBeginSeekingBackward ()
s3eResult s3eBackgroundMusicBeginSeekingForward ()
s3eResult s3eBackgroundMusicEndSeeking ()
struct s3eBackgroundMusicItem * | s3eBackgroundMusicGetCurrentItem ()
int32 | s3eBackgroundMusicGetInt (s3eBackgroundMusicProperty property)
int32 | s3eBackgroundMusicItemGetInt (struct s3eBackgroundMusicItem *item, s3eBackgroundMusicProperty property)
const char * | s3eBackgroundMusicItemGetString (struct s3eBackgroundMusicItem *item, s3eBackgroundMusicItemProperty property)
s3eResult s3eBackgroundMusicPause ()
s3eResult | s3eBackgroundMusicPickMusicItems (s3eBool allowMultipleItems)
s3eResult s3eBackgroundMusicPlay ()
s3eResult | s3eBackgroundMusicSetInt (s3eBackgroundMusicProperty property, int32 value)
s3eResult s3eBackgroundMusicSkipToBeginning ()
s3eResult s3eBackgroundMusicSkipToNextItem ()
s3eResult s3eBackgroundMusicSkipToPreviousItem ()
s3eResult s3eBackgroundMusicStop ()
S3E_BEGIN_C_DECL s3eBool | s3eExtBackgroundMusicAvailable ()

Detailed Description

Background Music provides access to the device's music library through the Music Picker interface, plus a means to intereact with music played through playback controls and the ability to query track and player status.

This extension is only supported on iPhone/iTouch devices running OS version 3.0 or greater.

For more information on the functionality provided by this extension, see the "Background Music Extension" section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eBackgroundMusicItemProperty

s3eBackgroundMusicItem Properties.

See also:
s3eBackgroundMusicItemGetString

s3eBackgroundMusicItemGetInt

Required Header Files
s3eExt_BackgroundMusic.h
Enumerator:
S3E_BACKGROUNDMUSICITEM_PERSISTANT_ID | [read, string] The persistent identifier for the media item. Value is a 64 bit integer in hex.
S3E_BACKGROUNDMUSICITEM_MEDIA_TYPE | [read, int] The media type of the music item. Value is a bit field.
S3E_BACKGROUNDMUSICITEM_TITLE | [read, string] The title (or name) of the music item.
S3E_BACKGROUNDMUSICITEM_ALBUM_TITLE | [read, string] The title of the album, as opposed to the title of the track
S3E_BACKGROUNDMUSICITEM_ARTIST | [read, string] The performing artist(s) for the music item.
S3E_BACKGROUNDMUSICITEM_ALBUM_ARTIST | [read, string] The primary performing artist for an album as a whole.
S3E_BACKGROUNDMUSICITEM_GENRE | [read, string] The musical genre of the item.
S3E_BACKGROUNDMUSICITEM_COMPOSER | [read, string] The musical composer(s) of the item.
S3E_BACKGROUNDMUSICITEM_PLAYBACK_DURATION | [read, int] The playback duration in milliseconds.
S3E_BACKGROUNDMUSICITEM_ALBUM_TRACK_NUMBER | [read, int] The track number of the music item, for a music item that is part of an album.
S3E_BACKGROUNDMUSICITEM_ALBUM_TRACK_COUNT | [read, int] The number of tracks in the album that contains the music item.
S3E_BACKGROUNDMUSICITEM_DISC_NUMBER | [read, int] The disc number of the media item, for a music item that is part of a multi-disc album.
S3E_BACKGROUNDMUSICITEM_DISC_COUNT | [read, int] The number of discs in the album that contains the music item.
S3E_BACKGROUNDMUSICITEM_LYRICS | [read, string] The lyrics for the song.
S3E_BACKGROUNDMUSICITEM_IS_COMPILATION | [read, int] Boolean indicating whether the music item is part of a compilation (S3E_TRUE) or not (S3E_FALSE).

enum s3eBackgroundMusicMediaType

Enum for S3E_BACKGROUNDMUSICITEM_MEDIA_TYPE.

See also:
s3eBackgroundMusicItemProperty

s3eBackgroundMusicItemGetInt

Required Header Files
s3eExt_BackgroundMusic.h

enum s3eBackgroundMusicPlaybackState

Enum for S3E_BACKGROUNDMUSIC_PLAYBACK_STATE.

See also:
s3eBackgroundMusicProperty

s3eBackgroundMusicGetInt

Required Header Files
s3eExt_BackgroundMusic.h

enum s3eBackgroundMusicProperty

BackgroundMusic Properties.

See also:
s3eBackgroundMusicGetInt

s3eBackgroundMusicSetInt

Required Header Files
s3eExt_BackgroundMusic.h
Enumerator:
S3E_BACKGROUNDMUSIC_CURRENT_PLAYBACK_TIME | [read, write, int] The current playback time, in milliseconds, of the now playing item.
S3E_BACKGROUNDMUSIC_PLAYBACK_STATE [read, int] The current playback state.
See also:
s3eBackgroundMusicPlaybackState
S3E_BACKGROUNDMUSIC_PLAYBACK_REPEAT_MODE [read, write, int] The current repeat mode of the background music player.
See also:
s3eBackgroundMusicRepeatMode
S3E_BACKGROUNDMUSIC_PLAYBACK_SHUFFLE_MODE [read, write, int] The current shuffle mode of the background music player.
See also:
s3eBackgroundMusicShuffleMode
S3E_BACKGROUNDMUSIC_PLAYBACK_VOLUME | [read, write, int] The current volume of the background music player in the range [0..255].
S3E_BACKGROUNDMUSIC_PLAYBACK_MIX | [read, write, int] This boolean is 1 if game audio should mix with BackgroundMusic or 0 if game audio should replace BackgroundMusic.

enum s3eBackgroundMusicRepeatMode

Enum for S3E_BACKGROUNDMUSIC_PLAYBACK_REPEAT_MODE.

See also:
s3eBackgroundMusicProperty

s3eBackgroundMusicGetInt

Required Header Files
s3eExt_BackgroundMusic.h

enum s3eBackgroundMusicShuffleMode

Enum for S3E_BACKGROUNDMUSIC_PLAYBACK_SHUFFLE_MODE.

See also:
s3eBackgroundMusicProperty

s3eBackgroundMusicGetInt

Required Header Files
s3eExt_BackgroundMusic.h

Function Documentation

s3eResult s3eBackgroundMusicBeginSeekingBackward ( )

Starts moving the playback point backwards faster than the normal playback rate.

s3eResult s3eBackgroundMusicBeginSeekingForward ( )

Starts moving the playback point forwards faster than the normal playback rate.

s3eResult s3eBackgroundMusicEndSeeking ( )

Stops additional movement of the playback point, returning the playback state to what it was prior to seeking.

struct s3eBackgroundMusicItem* s3eBackgroundMusicGetCurrentItem ( ) [read]

Returns the current s3eBackgroundMusicItem if there is one. Note paused, interrupted or stopped items DO NOT return NULL!

int32 s3eBackgroundMusicGetInt ( s3eBackgroundMusicProperty property )

Retrieves an integer property for the Background Music module.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 if the property is not valid.
    Call s3eAudioGetError() to retrieve an error code. This will return:
    S3E_DEVICE_ERR_PARAM if property is not valid.
See also:
s3eBackgroundMusicProperty

s3eBackgroundMusicSetInt

Required Header Files
s3eExt_BackgroundMusic.h

int32 s3eBackgroundMusicItemGetInt | ( | struct s3eBackgroundMusicItem * | item,
 |  | s3eBackgroundMusicProperty | property
 | ) |  |

Retrieves an integer property for the Background Music Item.

Parameters:
item | the s3eBackgroundMusicItem we're quering.
property | property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 if the property is not valid.
    Call s3eAudioGetError() to retrieve an error code. This will return:
    S3E_DEVICE_ERR_PARAM if property is not valid.
See also:
s3eBackgroundMusicProperty
Required Header Files
s3eExt_BackgroundMusic.h

const char* s3eBackgroundMusicItemGetString | ( | struct s3eBackgroundMusicItem * | item,
 |  | s3eBackgroundMusicItemProperty | property
 | ) |  |

Retrieves a string property for the Background Music Item.

Parameters:
item | the s3eBackgroundMusicItem we're quering.
property | property to get.
Returns:
  • A NULL-terminated property string of length >= 1 if the operation succeeded.
  • The empty string ("") if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return: S3E_DEVICE_ERR_PARAM if property is invalid.
See also:
s3eBackgroundMusicItemProperty
Required Header Files
s3eExt_BackgroundMusic.h

s3eResult s3eBackgroundMusicPause ( )

Pauses any current background Music playback.

s3eResult s3eBackgroundMusicPickMusicItems ( s3eBool allowMultipleItems )

Attempts to launch an API for selecting music item(s) to play. On an iPhone/iPod this launches the standard iPod GUI. If the user cancelled the selection or there was an error this will return S3E_RESULT_ERROR.

Parameters:
allowMultipleItems allow user to queue up multiple music items.

s3eResult s3eBackgroundMusicPlay ( )

Plays media items from the current playback queue, resuming paused playback if possible.

s3eResult s3eBackgroundMusicSetInt | ( | s3eBackgroundMusicProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for the Background Music module.

Parameters:
property | property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eDeviceGetError() to retrieve an error code. This will return:
    • S3E_FILE_ERR_PARAM if session is invalid or property is invalid or value is invalid.
See also:
s3eBackgroundMusicProperty

s3eBackgroundMusicGetInt

Required Header Files
s3eExt_BackgroundMusic.h

s3eResult s3eBackgroundMusicSkipToBeginning ( )

Restarts playback at the beginning of the currently playing music item.

s3eResult s3eBackgroundMusicSkipToNextItem ( )

Starts playback of the next music item in the playback queue..

s3eResult s3eBackgroundMusicSkipToPreviousItem ( )

Starts playback of the previous music item in the playback queue.

s3eResult s3eBackgroundMusicStop ( )

Stops any current background Music playback.

S3E_BEGIN_C_DECL s3eBool s3eExtBackgroundMusicAvailable ( )

Returns S3E_TRUE if the BackgroundMusic extension is available.


Airplay API Reference: Background Music Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Background Music Extension > Background Music Extension Example >

S3E Background Music Example

The following example uses the S3E Background Music extension to launch the external music picker interface for the selection and queueing-up of tracks. Playback of the list of tracks selected can then be controlled using on-screen buttons. The same functionality found in the Background Audio example (s3eBackgroundAudio) is also reproduced here to demonstrate interaction between music from the music picker and s3eSound. See the Background Audio example for more information.

The Background Music extension is currently only supported for iPhone v3.0 and greater.

The main functions used from Background Music are:

On-screen buttons are used to control the music playback and music picker. These are implemented in ExamplesMain.cpp.

The state of playback is output to screen using the s3eDebugPrint() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include <s3eExtensions/s3eExt_BackgroundMusic.h>
#include <s3eExtensions/s3eExt_BackgroundAudio.h>
#include <s3eExtensions/s3eExt_IPhone.h>
#include <set>

static int16*   g_SoundBuffer = 0;
static int32    g_SoundFileSize = 0;
static int      g_SoundChannel = 0;
static bool     g_SoundIsPlaying = false;

static Button*  g_ButtonIPod = 0;
static Button*  g_ButtonIPodPlay = 0;
static Button*  g_ButtonIPodPause = 0;
static Button*  g_ButtonIPodStop = 0;
static Button*  g_ButtonMixAudio = 0;
static Button*  g_ButtonPlaySound = 0;

static const char* g_Status = NULL;

void ExampleInit()
{
    if (s3eExtBackgroundMusicAvailable())
    {
        g_ButtonIPod = NewButton("open iPod Music Picker");
        g_ButtonIPodPlay = NewButton("Start iPod playback");
        g_ButtonIPodPause = NewButton("Pause iPod playback");
        g_ButtonIPodStop = NewButton("Stop iPod playback");
    }

    if (s3eExtBackgroundAudioAvailable())
    {
        g_ButtonMixAudio = NewButton("iPod/s3e audio mixing");
        g_ButtonPlaySound = NewButton("Play/stop s3eSound");

        // Setup sound buffer to play audio - see s3eSoundBasic example
        s3eFile *fileHandle = s3eFileOpen("test.raw", "rb");
        g_SoundFileSize = s3eFileGetSize(fileHandle);
        g_SoundBuffer = (int16*)s3eMallocBase(g_SoundFileSize);
        memset(g_SoundBuffer, 0, g_SoundFileSize);
        s3eFileRead(g_SoundBuffer, g_SoundFileSize, 1, fileHandle);
        s3eFileClose(fileHandle);
        s3eSoundSetInt(S3E_SOUND_DEFAULT_FREQ, 8000);
    }
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    // Ipod track playback controls
    if (s3eExtBackgroundMusicAvailable())
    {
        int playBackState = s3eBackgroundMusicGetInt(S3E_BACKGROUNDMUSIC_PLAYBACK_STATE);
        if (playBackState == S3E_BACKGROUNDMUSIC_PLAYBACK_PLAYING)
            g_ButtonIPodPlay->m_Enabled = false;
        else
            g_ButtonIPodPlay->m_Enabled = true;

        if (playBackState == S3E_BACKGROUNDMUSIC_PLAYBACK_PAUSED)
            g_ButtonIPodPause->m_Enabled = false;
        else
            g_ButtonIPodPause->m_Enabled = true;

        if (playBackState == S3E_BACKGROUNDMUSIC_PLAYBACK_STOPPED)
            g_ButtonIPodStop->m_Enabled = false;
        else
            g_ButtonIPodStop->m_Enabled = true;

        if (pressed == g_ButtonIPod)
        {
            if (s3eBackgroundMusicPickMusicItems(S3E_TRUE) == S3E_RESULT_SUCCESS)
                g_Status = "`x66ee66s3eExtIPodAccessLaunch: success";
            else
                g_Status = "`xee6666s3eExtIPodAccessLaunch: failure";
        }

        else if (pressed == g_ButtonIPodPlay)
        {
            s3eBackgroundMusicPlay();
        }

        else if (pressed == g_ButtonIPodPause)
        {
            s3eBackgroundMusicPause();
        }

        else if (pressed == g_ButtonIPodStop)
        {
            s3eBackgroundMusicStop();
        }
    }

    if (s3eExtBackgroundAudioAvailable())
    {
        if (pressed == g_ButtonMixAudio)
        {
            // Enable/disable mixing s3eSound with background audio from iPod/MusicPicker
            s3eExtBackgroundAudioSetMix(!s3eExtBackgroundAudioGetMix());
        }

        else if (pressed == g_ButtonPlaySound)
        {
            // Play s3eSound to check if it can be mixed with background audio
            if (!g_SoundIsPlaying)
            {
                s3eSoundChannelPlay(g_SoundChannel, g_SoundBuffer, g_SoundFileSize/2, 0, 0);
                g_SoundIsPlaying = true;
            }
            else
            {
                s3eSoundChannelStop(g_SoundChannel);
                g_SoundIsPlaying = false;
            }
        }
    }

    return true;
}

void ExampleRender()
{
    int y = 340;
    int x = 20;

    if (s3eExtBackgroundAudioAvailable())
    {
        if (s3eExtBackgroundAudioGetMix())
            s3eDebugPrintf(x, y, 1, "`x666666Mixing of background (iPod) & s3e audio enabled");
        else
            s3eDebugPrintf(x, y, 1, "`x666666Mixing of background (iPod) & s3e audio disabled");

        y += 12;

        if (g_SoundIsPlaying)
            s3eDebugPrintf(x, y, 1, "`x666666s3eSound is playing");
        else
            s3eDebugPrintf(x, y, 1, "`x666666s3eSound is stopped");
    }
    else
    {
        s3eDebugPrint(0, 100, "`xee3333BackgroundAudio extension unavailable", 1);
    }

    y += 20;

    if (s3eExtBackgroundMusicAvailable())
    {
        switch (s3eBackgroundMusicGetInt(S3E_BACKGROUNDMUSIC_PLAYBACK_STATE))
        {
            case S3E_BACKGROUNDMUSIC_PLAYBACK_STOPPED:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Stopped");
                break;

            case S3E_BACKGROUNDMUSIC_PLAYBACK_PLAYING:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Playing");
                break;

            case S3E_BACKGROUNDMUSIC_PLAYBACK_PAUSED:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Paused");
                break;

            case S3E_BACKGROUNDMUSIC_PLAYBACK_INTERRUPTED:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Interrupted");
                break;

            case S3E_BACKGROUNDMUSIC_PLAYBACK_SEEKING_FORWARD:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Seeking Forward");
                break;

            case S3E_BACKGROUNDMUSIC_PLAYBACK_SEEKING_BACKWARD:
                s3eDebugPrintf(x, y, 1, "`x666666Background Audio Seeking Backward");
                break;
        }

        y += 12;

        s3eBackgroundMusicItem* item = s3eBackgroundMusicGetCurrentItem();

        if (item)
        {
            const char* trackName = s3eBackgroundMusicItemGetString(item, S3E_BACKGROUNDMUSICITEM_TITLE);
            s3eDebugPrintf(x, y, 1, "`x333333iPod Track = '%s'", trackName ? trackName : "?");
        }
    }
    else
    {
        s3eDebugPrint(0, 160, "`xee3333BackgroundMusic extension unavailable", 1);
    }

    y += 20;

    if (g_SoundBuffer)
    {
        s3eDebugPrint(x, y, g_Status, 1);
        y += 12;
    }
}


Airplay API Reference: iPhone Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > iPhone Extension >

iPhone Extension

The iPhone Extension documentation contains the following sections:

  • iPhone Extension Overview
  • Iphone Extension API Reference


Airplay API Reference: iPhone Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > iPhone Extension > iPhone Extension Overview >

iPhone Extension Overview

The iPhone Extension provides miscellaneous iPhone-only functionality. This currently includes Push Notification helper functions.

Push Notifications

Push notifications are used to send requests to the application from external sources. A key use for this is to launch the app itself via an external request from a server.

Use s3eIPhone_GetPushNotificationToken() to get the push notification token ID for the device - if there is one - as a const char* string. This token is used to uniquely identify this device for the purposes of push notifications. Typically your app would send this token to your server which will then be able to use it to send a push notification via the push notification system.

To check if the application was started from a push notification request, call s3eIPhone_AppStartedWithNotification().

Other iPhone Extensions

Further iPhone functionality is provided through extensions dedicated to specific areas of functionality such as micro-transactions and background music. See iPhone Extensions for documentation for these extensions.


Airplay API Reference: Iphone Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > iPhone Extension > Iphone Extension API Reference >

Iphone Extension API Reference

Functions

S3E_BEGIN_C_DECL s3eBool | s3eExtIPhoneAvailable ()
s3eBool | s3eIPhone_AppStartedWithNotification ()
const char * | s3eIPhone_GetPushNotificationToken ()

Detailed Description

The iPhone Extension provides miscellaneous iPhone-only functionality.

For more information on the functionality provided by this extension, see the "iPhone Extension" section of the S3E API Documentation.

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtIPhoneAvailable ( )

Returns S3E_TRUE if the IPhone extension is available.

s3eBool s3eIPhone_AppStartedWithNotification ( )

Returns S3E_TRUE if the application was launched by a remote notification. S3E_FALSE indicates it was launched manually by the user.

const char* s3eIPhone_GetPushNotificationToken ( )

Returns the push notification token ID for this device, if there is one. This token is used to uniquely identify this device for the purposes of push notifications. Typically your app would send this token to your server which will then be able to use it to send a push notification via the push notification system.

Note Push Notification TokenIDs can change, this is not a device GUID!


Airplay API Reference: Microtransaction Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Microtransaction Extension >

Microtransaction Extension

The Micro Transaction Extension documentation contains the following sections:

  • Micro Transaction Extension Overview
  • Micro Transaction Extension API Reference
  • Micro Transaction Extension Example


Airplay API Reference: Microtransaction Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Microtransaction Extension > Microtransaction Extension Overview >

Microtransaction Extension Overview

This module allows for in-app purchasing of abitrary products setup by the user. This allows an application to extend itself by offering extra content and/or other extensions for the user to purchase.

This module is currently implemented only on iPhone.

Products are identified by a string identifier and must be globally unique. Product identifiers must be setup on the Store ahead of time and programmed into the application; There is no opportunity for the application to obtain a list of available products.

The application obtains information about a product by calling s3eMicroTransactionRequestProductInformation(), and then purchases the product by calling s3eMicroTransactionRequestPayment().


Airplay API Reference: Micro Transaction Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Microtransaction Extension > Micro Transaction Extension API Reference >

Micro Transaction Extension API Reference

Data Structures

struct | s3ePaymentRequest
struct | s3ePaymentTransaction
struct | s3eProductIdentifier
struct | s3eProductInformation
struct | s3eTransactionIdentifier
struct | s3eTransactionReceipt

Typedefs

typedef
s3ePaymentTransactionAction(* 		s3ePaymentTransactionUpdateCallbackFn )(s3ePaymentTransaction *transaction, void *userData)
typedef void(* | s3eProductInformationCallbackFn )(s3eProductInformation *productInfo, void *userData)

Enumerations

enum s3ePaymentTransactionAction {
S3E_TRANSACTION_KEEP = 0,
S3E_TRANSACTION_FINALIZE = 1
}
enum s3eTransactionStatus {
S3E_PAYMENT_STATUS_PENDING,
S3E_PAYMENT_STATUS_PURCHASED,
S3E_PAYMENT_STATUS_FAILED_CLIENT_INVALID,
S3E_PAYMENT_STATUS_FAILED_PAYMENT_CANCELLED,
S3E_PAYMENT_STATUS_FAILED_PAYMENT_INVALID,
S3E_PAYMENT_STATUS_FAILED_PAYMENT_NOT_ALLOWED,
S3E_PAYMENT_STATUS_FAILED_UNKNOWN_ERROR
}

Functions

S3E_BEGIN_C_DECL s3eBool | s3eExtMicroTransactionAvailable ()
s3eResult | s3eMicroTransactionInit (s3eProductInformationCallbackFn infoCallback, s3ePaymentTransactionUpdateCallbackFn updateCallback, void *userData)
s3ePaymentRequest * | s3eMicroTransactionRequestPayment (s3eProductIdentifier productID, uint32 quantity)
s3eResult | s3eMicroTransactionRequestProductInformation (s3eProductIdentifier *productIdentifiers, uint32 numProductIdentifiers)

Detailed Description

This module allows for in-app purchasing of abitrary products setup by the user. This allows an application to extend itself by offering extra content and/or other extensions for the user to purchase.

This module is currently implemented only on iPhone.

Products are identified by a string identifier and must be globally unique. Product identifiers must be setup on the Store ahead of time and programmed into the application; There is no opportunity for the application to obtain a list of available products.

The application obtains information about a product by calling s3eMicroTransactionRequestProductInformation, and then purchases the product by calling s3eMicroTransactionRequestPayment

For more information on the functionality provided by this extension, see the "Micro Transaction Extension" section of the S3E API Documentation.

Typedef Documentation

typedef s3ePaymentTransactionAction(* s3ePaymentTransactionUpdateCallbackFn)(s3ePaymentTransaction *transaction, void *userData)

Reports that a transaction has been updated.

Parameters:
transaction | The updated transaction.
userData | The user parameter specified in the s3eMicroTransactionInit call.
Returns:
If the status was S3E_PAYMENT_STATUS_PURCHASED, returning S3E_TRANSACTION_FINALIZE will remove it from the queue. NOTE the callback function MUST make a permanant record of the purchase, preferably on disc and on a remote server so that paid for items may be recovered in the event of the app being deleted and reinstalled.
Required Header Files
s3eExt_MicroTransaction.h

typedef void(* s3eProductInformationCallbackFn)(s3eProductInformation *productInfo, void *userData)

Reports the results of a product information request.

Parameters:
productInfo | The requested product information.
userData | The user parameter specified in the s3eMicroTransactionInit call.
Required Header Files
s3eExt_MicroTransaction.h

Enumeration Type Documentation

enum s3ePaymentTransactionAction

The return value from s3ePaymentTransactionUpdateCallbackFn, controls removal of the transaction from the queue.

Enumerator:
S3E_TRANSACTION_KEEP | Keep the transaction for now.
S3E_TRANSACTION_FINALIZE | If the status is S3E_PAYMENT_STATUS_PURCHASED, then this will signal the removal of the transaction from the queue.

enum s3eTransactionStatus

Enumeration passed to the s3ePaymentTransactionUpdateCallbackFn indicating transaction status

Enumerator:
S3E_PAYMENT_STATUS_PENDING | The payment is awaiting authorisation
S3E_PAYMENT_STATUS_PURCHASED | The payment has been processed, you must now make the feature avaliable
S3E_PAYMENT_STATUS_FAILED_CLIENT_INVALID | The payment has failed
S3E_PAYMENT_STATUS_FAILED_PAYMENT_CANCELLED | The payment has failed because the user cancelled
S3E_PAYMENT_STATUS_FAILED_PAYMENT_INVALID | The payment has failed because the product itentifier was invalid, etc
S3E_PAYMENT_STATUS_FAILED_PAYMENT_NOT_ALLOWED | The payment has failed because the device is not allowed to make the payment
S3E_PAYMENT_STATUS_FAILED_UNKNOWN_ERROR | The payment has failed, reason unknown

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtMicroTransactionAvailable ( )

Returns S3E_TRUE if the MicroTransaction extension is available.

s3eResult s3eMicroTransactionInit | ( | s3eProductInformationCallbackFn | infoCallback,
 |  | s3ePaymentTransactionUpdateCallbackFn | updateCallback,
 |  | void * | userData
 | ) |  |

Registers various callbacks s3ePaymentTransactionUpdateCallbackFn.

Parameters:
infoCallback | This callback is issued when the app recives localized product information from the store.
updateCallback | This callback is issued when any of the transaction payments change state. Note the updateCallback is issued on start up for any purhcased items in the queue which have not been finalized.
userData | Passed into the userData in s3eZeroConfStartSearchCallbackFn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
Required Header Files
s3eExt_MicroTransaction.h

s3ePaymentRequest* s3eMicroTransactionRequestPayment | ( | s3eProductIdentifier | productID,
 |  | uint32 | quantity
 | ) |  |

Requests payment for an item. The result of the request is returned by the s3ePaymentTransactionUpdateCallbackFn.

Parameters:
productID | The item the user wishes to purchase.
quantity | The quantity to purchase.
Returns:
  • A valid s3ePaymentRequest pointer if no error occurred.
  • NULL if the operation failed.
Required Header Files
s3eExt_MicroTransaction.h

s3eResult s3eMicroTransactionRequestProductInformation | ( | s3eProductIdentifier * | productIdentifiers,
 |  | uint32 | numProductIdentifiers
 | ) |  |

Requests localized price and other information for an array of s3eProductIdentifiers.

Parameters:
[in] | productIdentifiers | An array of numProductIdentifiers s3eProductIdentifier structures supplied by the application. For each product identifier supplied, the s3eProductInformationCallbackFn passed to s3eMicroTransactionInit will be called
numProductIdentifiers | The number of product identifiers in the array
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
Required Header Files
s3eExt_MicroTransaction.h

Variable Documentation

const char* s3eProductInformation::m_formattedPrice [inherited]

Localised formatted price string, e.g. "$0.99".

const char* s3eProductInformation::m_LocalizedDescription [inherited]

Localised product description.

const char* s3eProductInformation::m_LocalizedTitle [inherited]

Localised title of the product.

double s3eProductInformation::m_price [inherited]

Localised price as a decimal integer.

s3eDeviceLanguage s3eProductInformation::m_priceLocal [inherited]

Region from which the price is given.

uint32 s3eTransactionReceipt::m_ReceiptSize [inherited]

Receipt data size.

s3eTransactionIdentifier* s3ePaymentTransaction::m_TransactionID [inherited]

Transaction identifier.

s3eTransactionReceipt* s3ePaymentTransaction::m_TransactionReceipt [inherited]

Transaction receipt.

s3eTransactionStatus s3ePaymentTransaction::m_TransactionStatus [inherited]

Transaction status.


Airplay API Reference: Microtransaction Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > Microtransaction Extension > Microtransaction Extension Example >

S3E MicroTransaction Example

The following example demonstrates the use of the s3eMicroTransaction API to perform In-App purchasing. It connects to a store, lists the available products, and lets the user purchase one of them.

The main functions demonstrated here are:

  • s3eMicroTransactionInit()
  • s3eMicroTransactionRequestProductInformation()
  • s3eMicroTransactionRequestPayment()

This example only runs on iPhone. To run this example, you must create an In App Purchase Test account on iTunes Connect, and create some products that are available for this application to purchase

This application uses s3eMicroTransactionInit to register callbacks to receieve product and transaction information. It then uses s3eMicroTransactionRequestProductInformation to request information about available products. Finally it uses s3eMicroTransactionRequestPayment to purchase a product.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3eExt_MicroTransaction.h"
#include "s3eDebug.h"

//Unique identifier for the product id to purchase.
#define PRODUCT_ID "com.ideaworks3d.examples.s3eMicroTransaction"

//Our product ID
static s3eProductIdentifier g_ProductID = { PRODUCT_ID };

//Product information sent back from s3eMicroTransactionInit
static s3eProductInformation g_ProductInformation = { 0 };

//Whether we have product information
static bool g_GotProductInfo = false;

//Buttons for getting product information and buying
static Button* g_ProductInfoButton = NULL;
static Button* g_ProductBuyButton = NULL;

//Status string to print at bottom of screen
static char g_StatusStr[512];

static void SetStatus(const char* statusStr, ...);

//This callback is called after the call to s3eMicroTransactionRequestPayment when
//the state of a transaction has changed (ie an item as been successfully bought,
//or an error occurred)
s3ePaymentTransactionAction TransactionUpdateCallback(s3ePaymentTransaction* transaction, void* userData)
{
    if (transaction->m_TransactionStatus == S3E_PAYMENT_STATUS_PURCHASED)
    {
        SetStatus("Buying %s completed!", g_ProductInformation.m_LocalizedTitle);
    }
    else if (transaction->m_TransactionStatus == S3E_PAYMENT_STATUS_PENDING)
    {
        SetStatus("Buying %s in progress...", g_ProductInformation.m_LocalizedTitle);
    }
    else
    {
        SetStatus("Buying %s FAILED", g_ProductInformation.m_LocalizedTitle);
    }

    return S3E_TRANSACTION_FINALIZE;
}

//This callback is called after the call to s3eMicroTransactionRequestProductInformation when
//product information is available
void ProductInfoCallback(s3eProductInformation* productInfo, void* userData)
{
    g_ProductInformation = *productInfo;
    g_GotProductInfo = true;
    SetStatus("Got Product information. Title: %s, Description %s, Price %s. Press button to buy...",
        g_ProductInformation.m_LocalizedTitle, g_ProductInformation.m_LocalizedDescription, g_ProductInformation.m_priceLocal);

    char str[256];
    sprintf(str, "Buy (%s %d)", g_ProductInformation.m_LocalizedTitle, g_ProductInformation.m_priceLocal);
    g_ProductBuyButton = NewButton(str);
}

//Sets a string to be displayed beneath the buttons
static void SetStatus(const char* fmt, ...)
{
    va_list args;
    va_start(args, fmt);
    strcpy(g_StatusStr, "`x000000");
    vsprintf(g_StatusStr+strlen(g_StatusStr), fmt, args);
    va_end(args);
}

void ExampleInit()
{
    if (!s3eExtMicroTransactionAvailable())
    {
        s3eDebugErrorShow(S3E_MESSAGE_CONTINUE, "This example only works on iPhone with a test store set up for in-app purchase");
        s3eDeviceExit(1);
    }

    //Initialise the MicroTransaction module and register for callbacks
    //when product & transaction information is available
    s3eMicroTransactionInit(ProductInfoCallback, TransactionUpdateCallback, NULL);

    //Add a button to start requesting product information
    g_ProductInfoButton = NewButton("Request product info");

    SetStatus("Waiting for user input to get product info for: %s", PRODUCT_ID);
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (g_ProductInfoButton == pressed)
    {
        //When the user presses the 'get product info' button, request product information
        //and set the status string accordingly.
        //s3eMicroTransactionRequestPayment will cause the ProductInfoCallback to be
        //called, which then fills in the g_ProductInformation structure
        if (s3eMicroTransactionRequestProductInformation(&g_ProductID, 1) == S3E_RESULT_SUCCESS)
        {
            SetStatus("Requesting product info for: %s...", PRODUCT_ID);
        }
        else
        {
            SetStatus("Requesting product info for %s FAILED", PRODUCT_ID);
        }
    }

    if (g_ProductBuyButton && g_ProductBuyButton == pressed)
    {
        //Once the user has product information he/she can now buy the product.
        //Create a transaction request. When the transaction has completed,
        //the TransactionUpdateCallback will be called
        if (s3eMicroTransactionRequestPayment(g_ProductID, 1) != NULL)
        {
            SetStatus("Purchasing %s...", PRODUCT_ID);
        }
        else
        {
            SetStatus("Purchasing %s FAILED", PRODUCT_ID);
        }

    }

    return true;
}

void ExampleRender()
{
    //Print status string just below the buttons
    s3eDebugPrint(0, GetYBelowButtons(), g_StatusStr, S3E_TRUE);
}


Airplay API Reference: ZeroConf Extension

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension >

ZeroConf Extension

The ZeroConf Extension documentation contains the following sections:

  • Zero Conf Extension Overview
  • Zero Conf Extension API Reference
  • Zero Conf Extension Example


Airplay API Reference: ZeroConf Extension Overview

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension > ZeroConf Extension Overview >

ZeroConf Extension Overview

The s3eZeroConf API allows applications to create usable Internet Protocol (IP) network connections without manual operator intervention or special configuration servers. The application can use the API to obtain a list of servers and their services on the connected network.

Use s3eZeroConfStartSearch() to start discovering network services.


Airplay API Reference: ZeroConf Extension API Reference

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension > ZeroConf Extension API Reference >

ZeroConf Extension API Reference

Data Structures

struct | s3eZeroConfAddRecord
struct | s3eZeroConfUpdateRecord

Typedefs

typedef int32(* | s3eZeroConfAddCallbackFn )(s3eZeroConfSearch *search, s3eZeroConfAddRecord *record, void *userData)
typedef int32(* | s3eZeroConfRemoveCallbackFn )(s3eZeroConfSearch *search, void *recordRef, void *userData)
typedef int32(* | s3eZeroConfUpdateCallbackFn )(s3eZeroConfSearch *search, s3eZeroConfUpdateRecord *record, void *userData)

Functions

S3E_BEGIN_C_DECL s3eBool | s3eExtZeroConfAvailable ()
s3eZeroConfPublished * | s3eZeroConfPublish (uint16 port, const char *name, const char *serviceType, const char *domain, uint16 numTxtRecords, const char **txtRecords)
s3eZeroConfSearch * | s3eZeroConfStartSearch (const char *serviceType, const char *domain, s3eZeroConfAddCallbackFn addCallback, s3eZeroConfUpdateCallbackFn updateCallback, s3eZeroConfRemoveCallbackFn removeCallback, void *userData)
s3eResult | s3eZeroConfStopSearch (s3eZeroConfSearch *searchRef)
s3eResult | s3eZeroConfUnpublish (s3eZeroConfPublished *serviceRef)
s3eResult | s3eZeroConfUpdateTxtRecord (s3eZeroConfPublished *service, uint16 numTxtRecords, const char **txtRecords)

Detailed Description

For more information on the ZeroConf functionality provided by the S3E module, see the ZeroConf Extension section of the S3E API Documentation.

Typedef Documentation

typedef int32(* s3eZeroConfAddCallbackFn)(s3eZeroConfSearch *search, s3eZeroConfAddRecord *record, void *userData)

Reports the discovery of a network service matching a s3eZeroConfStartSearch query.

Parameters:
search | The corresponding s3eZeroConfSearch.
record | Pointer to a strcture detailing the discovered service.
userData | The user parameter specified in the s3eZeroConfStartSearch call.
Returns:
A user refrence to be passed into s3eZeroConfUpdateCallbackFn & s3eZeroConfRemoveCallbackFn
Required Header Files
s3eZeroConf.h

typedef int32(* s3eZeroConfRemoveCallbackFn)(s3eZeroConfSearch *search, void *recordRef, void *userData)

Reports the update of a network service matching a s3eZeroConfStartSearch query.

Parameters:
search | The corresponding s3eZeroConfSearch.
recordRef | This is the same value as m_RecordRef from the corresponding s3eZeroConfAddRecord.
userData | The user parameter specified in the s3eZeroConfStartSearch call.
Required Header Files
s3eZeroConf.h

typedef int32(* s3eZeroConfUpdateCallbackFn)(s3eZeroConfSearch *search, s3eZeroConfUpdateRecord *record, void *userData)

Reports the update of a network service matching a s3eZeroConfStartSearch query.

Parameters:
search | The corresponding s3eZeroConfSearch.
record | Pointer to a strcture detailing the new txt record for the updated service.
userData | The user parameter specified in the s3eZeroConfStartSearch call.
Required Header Files
s3eZeroConf.h

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eExtZeroConfAvailable ( )

Returns S3E_TRUE if the ZeroConf extension is available.

s3eZeroConfPublished* s3eZeroConfPublish | ( | uint16 | port,
 |  | const char * | name,
 |  | const char * | serviceType,
 |  | const char * | domain,
 |  | uint16 | numTxtRecords,
 |  | const char ** | txtRecords
 | ) |  |

Publishes the existance of a network service with ZeroConf.

Parameters:
port | The port the service uses.
name | The name of the service
serviceType | The type of the service (e.g. _http._tcp or _ftp._tcp)
domain | The domain the service was in (if NULL then local is assumed)
numTxtRecords | The number of strings to register (can be 0).
txtRecords | The txtRecord strings (can be NULL).
serviceRef | Returns a pointer to a s3eZeroConfPublished which you can s3eZeroConfUnregister later.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
Required Header Files
s3eZeroConf.h

s3eZeroConfSearch* s3eZeroConfStartSearch | ( | const char * | serviceType,
 |  | const char * | domain,
 |  | s3eZeroConfAddCallbackFn | addCallback,
 |  | s3eZeroConfUpdateCallbackFn | updateCallback,
 |  | s3eZeroConfRemoveCallbackFn | removeCallback,
 |  | void * | userData
 | ) |  |

Starts discovering network services of a specified type, the system will continue listening until you call s3eZeroConfStopSearch.

Parameters:
serviceType | The type of service to look for (e.g. _http._tcp or _ftp._tcp)
domain | The domain to look in, if this is NULL then local will be assumed.
callback | Results are found asynchronously and reported vis this callback s3eZeroConfStartSearchCallbackFn.
userData | Passed into the userData in s3eZeroConfStartSearchCallbackFn.
searchRef | Returns a pointer to a s3eZeroConfSearch which you can s3eZeroConfStopSearch later.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
Required Header Files
s3eZeroConf.h

s3eResult s3eZeroConfStopSearch ( s3eZeroConfSearch * searchRef )

Stops a previous search.

Parameters:
searchRef The search to stop...
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
Required Header Files
s3eZeroConf.h

s3eResult s3eZeroConfUnpublish ( s3eZeroConfPublished * serviceRef )

Unregisters a network service previously registered with s3eZeroConfPublish.

Parameters:
serviceRef The service to unregister.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
Required Header Files
s3eZeroConf.h

s3eResult s3eZeroConfUpdateTxtRecord | ( | s3eZeroConfPublished * | service,
 |  | uint16 | numTxtRecords,
 |  | const char ** | txtRecords
 | ) |  |

Updates the txtRecord associated with a previously registered service.

Parameters:
service | The service to update.
numTxtRecords | The number of strings to register(can be 0).
txtRecords | The txtRecord strings (can be NULL).
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
Required Header Files
s3eZeroConf.h


Airplay API Reference: ZeroConf Extension Examples

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension > ZeroConf Extension Examples >

ZeroConf Extension Examples

This section illustrates how you can use the ZeroConf functionality provided with S3E. This section contains two example applications:

  • S3E ZeroConf Example
  • S3E Shared Whiteboard Example

Note: For more information on the S3E ZeroConf functionality, see the S3E ZeroConf Overview.


Airplay API Reference: ZeroConf Extension Example

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension > ZeroConf Extension Examples > ZeroConf Extension Example >

S3E ZeroConf Example

The following example demonstrate the use of the s3eZeroConf API to connect to the network and list the available services.

The main functions used to achieve this are:

  • s3eZeroConfStartSearch()
  • s3eZeroConfStopSearch()
  • s3eZeroConfPublish()
  • s3eZeroConfUnpublish()
  • s3eZeroConfUpdateTxtRecord()

The application uses s3eZeroConf to makes a connection to the network then enumerated the devices and their services that was found on the network.

The results list is output to screen using the s3eDebugPrint() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//----------------------------------------------------------------------------
// ExampleS3EZeroConf
//----------------------------------------------------------------------------

#include "ExamplesMain.h"
#include "s3e.h"
#include "s3eExt_ZeroConf.h"
#include <string.h>
#include <stdio.h>

/*
 * Used to record infomation about the services we've discovered
 */
struct Record
{
    char*           m_name;
    char*           m_txt;
    char*           m_ip;
    void*           m_Ref;
    s3eInetAddress  m_addr;
    Record*         m_pNext;
    Record*         m_pPrev;

    void Free()
    {
        if (m_name)
            s3eFree(m_name);
        m_name = 0;

        if (m_txt)
            s3eFree(m_txt);
        m_txt = 0;

        if (m_ip)
            s3eFree(m_ip);
        m_ip = 0;
    }
};

static Record*                  g_ResultList = 0;
static s3eZeroConfPublished*    g_Service = 0;
static s3eZeroConfSearch*       g_Search = 0;
static uint32                   g_Counter = 0;
static uint32                   g_Timer = 75;
static const unsigned char*     g_TxtRecord = 0;

// this call back is issued when an IP address is resolved.
int32 ResolveIPCallback(void* addr, void* userData)
{
    Record* pResult = (Record*)userData;
    Record* pIter = 0;
    char    buf[512];

    // if addr is null then it couldn't resolve the IP address.
    if (!addr)
    {
        uint32 len = snprintf(buf, sizeof(buf), "`x666666ip resolve failed");

        pResult->m_ip = (char*) s3eMalloc(len);

        memcpy(pResult->m_ip, buf, len);

        return 0;
    }

    // we'd better check this record still exists, since it's
    // possible for it to have been deleted before the DNS came back
    for (pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
        if (pIter == pResult)
            break;

    if (!pIter)
        return 0;  // it's been deleted, so ignore!

    uint32 len = snprintf(buf, sizeof(buf), "`x666666ip %s", s3eInetToString(&pResult->m_addr)) + 1;

    pResult->m_ip = (char*) s3eMalloc(len);

    memcpy(pResult->m_ip, buf, len);

    return 0;
}

// this call back is issued when a new service (matching the query) is discovered
int32 SearchAddCallBack(s3eZeroConfSearch* search, s3eZeroConfAddRecord* rec, void* userData)
{
    char buf[512];
    char buf2[64];

    s3eDebugTracePrintf("SearchAddCallBack: %s %s %d", rec->m_Name, rec->m_Hostname, rec->m_Port);

    // push a new record onto the list
    Record  *pResult = (Record*) s3eMalloc(sizeof(Record));

    pResult->m_pPrev = 0;
    pResult->m_Ref = rec->m_RecordRef;
    pResult->m_pNext = g_ResultList;

    if (g_ResultList)
        g_ResultList->m_pPrev = pResult;

    g_ResultList = pResult;

    // fill it out
    uint32 len = snprintf(buf, sizeof(buf), "`x666666txt '%s'", rec->m_NumTxtRecords ? rec->m_TxtRecords[0] : "") + 1;
    pResult->m_txt = (char*) s3eMalloc(len);
    memcpy(pResult->m_txt, buf, len);

    len = snprintf(buf, sizeof(buf), "`x666666ihp %s", s3eInetNtoa(rec->m_HostIP, buf2, sizeof(buf2))) + 1;
    pResult->m_ip = (char*) s3eMalloc(len);
    memcpy(pResult->m_ip, buf, len);

    len = snprintf(buf, sizeof(buf), "`x666666%s\n@ %s:%d", rec->m_Name, rec->m_Hostname, rec->m_Port) + 1;
    pResult->m_name = (char*) s3eMalloc(len);
    memcpy(pResult->m_name, buf, len);

    return 0;
}

// this call back is issued when a previously discovered service updates it's txtRecord
int32 SearchUpdateCallBack(s3eZeroConfSearch* search, s3eZeroConfUpdateRecord* rec, void* userData)
{
    Record  *pIter;
    char    buf[512];

    for (pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
        if (pIter->m_Ref == rec->m_RecordRef)
            break;

    if (!pIter)
        return 0;

    // fill it out
    uint32 len = snprintf(buf, sizeof(buf), "`x666666txt '%s'", rec->m_NumTxtRecords ? rec->m_TxtRecords[0] : "") + 1;

    s3eFree(pIter->m_txt);

    pIter->m_txt = (char*) s3eMalloc(len);
    memcpy(pIter->m_txt, buf, len);
    return 0;
}

// this call back is issued when a previously discovered service is unregisted
int32 SearchRemoveCallBack(s3eZeroConfSearch* search, void* userRef, void* userData)
{
    Record  *pIter;

    for (pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
        if (pIter->m_Ref == userRef)
            break;

    if (!pIter)
        return 0;

    // remove pResult from the linked list
    if (pIter->m_pNext)
        pIter->m_pNext->m_pPrev = pIter->m_pPrev;

    if (pIter->m_pPrev)
        pIter->m_pPrev->m_pNext = pIter->m_pNext;
    else
        g_ResultList = pIter->m_pNext;

    // free pResult
    pIter->Free();
    s3eFree(pIter);

    return 0;
}

void ExampleInit()
{
    const char* string = "A test txt record!";
    const char* argv[] = { string };

    // create a dummy service
    g_Service = s3eZeroConfPublish(8080, "s3eDummyService", "_http._tcp", 0, 1, argv);

    // search for "_http._tcp" services in domain "local"
    g_Search = s3eZeroConfStartSearch("_http._tcp",
                        "local",
                        SearchAddCallBack,
                        SearchUpdateCallBack,
                        SearchRemoveCallBack,
                        0);
}

void ExampleShutDown()
{
    s3eDebugTracePrintf("Stopping search: %p", g_Search);
    s3eZeroConfStopSearch(g_Search);
    s3eZeroConfUnpublish(g_Service);

    Record *pNext;

    // free the results
    for (Record *pIter = g_ResultList; pIter; pIter = pNext)
    {
        pNext = pIter->m_pNext;

        // free pIter
        pIter->Free();
        s3eFree(pIter);
    }

    g_ResultList = 0;
}

void ClearScreen()
{
    uint16* screen = (uint16*)s3eSurfacePtr();
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    int32 height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);
    int32 pitch = s3eSurfaceGetInt(S3E_SURFACE_PITCH);

    for (int y = 0; y < height; y++)
        for (int x = 0; x < width; x++)
            screen[y * pitch/2 + x] = 0;
}

bool ExampleUpdate()
{
    if (g_Timer == 0)
    {
        g_Timer = 75;

        // create a new txtRecord
        char                    txtRec[100];

        snprintf(txtRec, sizeof(txtRec),  "txt record #%lu!", g_Counter++);

        const char*             argv[] = { txtRec };

        if (g_TxtRecord)
            s3eFree((void*)g_TxtRecord);
        g_TxtRecord = 0;

        // update the txt record
        s3eZeroConfUpdateTxtRecord(g_Service, 1, argv);
    }
    else
        g_Timer--;

    return true;
}

void ExampleRender()
{
    const int   textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int         y = 50;

    // create a winsock event to go with this socket for use with WSAWaitForMultipleEvents
    for (Record *pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
    {
        if (pIter->m_name)
        {
            s3eDebugPrint(10, y, pIter->m_name, 0);
            y += textHeight * 2;
        }

        if (pIter->m_ip)
        {
            s3eDebugPrint(10, y, pIter->m_ip, 0);
            y += textHeight;
        }

        if (pIter->m_txt)
        {
            s3eDebugPrint(10, y, pIter->m_txt, 0);
            y += textHeight;
        }

        y += textHeight;
    }
}


Airplay API Reference: Shared Whiteboard Example

Airplay API Reference > S3E API Documentation > S3E Extensions > iPhone Extensions > ZeroConf Extension > ZeroConf Extension Examples > Shared Whiteboard Example >

S3E Shared Whiteboard Example

The following example demonstrate the use of s3eZeroConf for s3e applications to exchange data between each other.

The main functions used to achieve this are:

  • s3eSocketCreate()
  • s3eSocketBind()
  • s3eInetLookup()
  • s3eSocketSendTo()
  • s3eSocketRecvFrom()
  • s3eZeroConfStartSearch()
  • s3eZeroConfStopSearch()
  • s3eZeroConfPublish()
  • s3eZeroConfUnpublish()

The application makes a connection to another whiteboard application running on the same network. The 2 applications then share their pointer's data so that they can display both sets on the screen.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3e.h"
#include "s3eExt_ZeroConf.h"
#include "s3eSocket.h"
#include "s3ePointer.h"
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

struct DrawLine
{
    uint8           m_r;
    uint8           m_g;
    uint8           m_b;
    uint16          m_x0;
    uint16          m_y0;
    uint16          m_x1;
    uint16          m_y1;
};

/*
 * Used to record infomation about the services we've discovered
 */
struct Record
{
    void*           m_Ref;
    s3eInetAddress  m_addr;
    Record*         m_pNext;
    Record*         m_pPrev;
};

Record*                 g_ResultList = 0;
s3eZeroConfPublished*   g_Service = 0;
s3eZeroConfSearch*      g_Search = 0;
s3eSocket*              g_Sock;
s3eInetAddress          g_MyAddr;
uint32                  g_Counter = 0;
uint32                  g_Timer = 75;
uint16                  g_Port = 0;
uint16                  g_PrevX = 0;
uint16                  g_PrevY = 0;
int32                   g_RGBIndex = 0;
int32                   g_PrevPointerState = 0;

enum {
    kDrawBucketSize = 256,
};

DrawLine                g_Bucket[kDrawBucketSize];
uint32                  g_nDraw = 0;

uint8   g_r[] = {255,   0, 0,   255, 0,   255, 255, 127, 127, 255, 127, 255};
uint8   g_g[] = {0,   255, 0,   255, 255, 0,   127, 255, 127, 255, 255, 127};
uint8   g_b[] = {0,     0, 255, 0,   255, 255, 127, 127, 255, 127, 255, 255};

#define _SWAP(a,b) {int32 tmp = a; a = b; b = tmp;}

int32 PixelSize()
{
    int         pxlType = s3eSurfaceGetInt(S3E_SURFACE_PIXEL_TYPE);
    switch(pxlType & S3E_SURFACE_PIXEL_SIZE_MASK)
    {
    case S3E_SURFACE_PIXEL_SIZE_8:
        return 1;
    case S3E_SURFACE_PIXEL_SIZE_16:
        return 2;
    case S3E_SURFACE_PIXEL_SIZE_24:
        return 3;
    case S3E_SURFACE_PIXEL_SIZE_32:
        return 4;
    }
    return 0;
}

// draw a line in uniform colour using Bressenham's algorithm
void DrawLineRGB(int32 x0, int32 y0, int32 x1, int32 y1, uint8 r, uint8 g, uint8 b )
{
    int32       pitch   = s3eSurfaceGetInt( S3E_SURFACE_PITCH );
    int         pxlSize = PixelSize();
    uint32      col = s3eSurfaceConvertRGB(r,g,b);
    bool        steep = false;

    if (abs(y1 - y0) > abs(x1 - x0))
    {
        _SWAP(x0, y0)
        _SWAP(x1, y1)
        steep = true;
    }

    if (x0 > x1)
    {
        _SWAP(x0, x1)
        _SWAP(y0, y1)
    }

    int32 deltax = x1 - x0;
    int32 deltay = abs(y1 - y0);
    int32 error = deltax / 2;

    int32 _mx = steep ? pitch : pxlSize;
    int32 _my = steep ? pxlSize : pitch;
    int32 ystep = (y0 < y1) ? _my : -_my;
    uint8 *dest = ((uint8 *) s3eSurfacePtr()) + (x0 * _mx) + (y0 * _my);

    int32 x;
    switch (pxlSize)
    {
        case 1:
            for (x = x0; x <= x1; x++, dest += _mx)
            {
                *(uint8*)dest = (uint8)col;

                error -= deltay;

                if (error < 0)
                {
                    dest += ystep;
                    error += deltax;
                }
            }
            break;

        case 2:
            for (x = x0; x <= x1; x++, dest += _mx)
            {
                //don't make assumptions about alignment of dest
                *(uint8*)dest =     (uint8)col;
                *(uint8*)(dest+1) = (uint8)(col>>8);

                error -= deltay;

                if (error < 0)
                {
                    dest += ystep;
                    error += deltax;
                }
            }
            break;

        case 3:
            for (x = x0; x <= x1; x++, dest += _mx)
            {
                //don't make assumptions about alignment of dest
                *(uint8*)dest =     (uint8)col;
                *(uint8*)(dest+1) = (uint8)(col>>8);
                *(uint8*)(dest+2) = (uint8)(col>>16);

                error -= deltay;

                if (error < 0)
                {
                    dest += ystep;
                    error += deltax;
                }
            }
            break;

        case 4:
            for (x = x0; x <= x1; x++, dest += _mx)
            {
                //don't make assumptions about alignment of dest
                *(uint8*)dest =     (uint8)col;
                *(uint8*)(dest+1) = (uint8)(col>>8);
                *(uint8*)(dest+2) = (uint8)(col>>16);
                *(uint8*)(dest+3) = (uint8)(col>>24);

                error -= deltay;

                if (error < 0)
                {
                    dest += ystep;
                    error += deltax;
                }
            }
            break;

        default:
            break;
    }
}

//-----------------------------------------------------------------------------
// this call back is issued when a new service (matching the query) is discovered
//-----------------------------------------------------------------------------
int32 SearchAddCallBack(s3eZeroConfSearch* search, s3eZeroConfAddRecord* rec, void* userData)
{
    s3eDebugTracePrintf("SearchAddCallBack: %s %s %d", rec->m_Name, rec->m_Hostname, rec->m_Port);

    Record  *pResult = (Record*) s3eMalloc(sizeof(Record));

    s3eResult err = s3eInetLookup(rec->m_Hostname, &pResult->m_addr, 0, 0);
    pResult->m_addr.m_Port = rec->m_Port;

    if (err == S3E_RESULT_ERROR)
    {
        s3eDebugTracePrintf("Inet lookup failed\n");
        s3eFree(pResult);
        return 0;
    }
    else
    {
        s3eDebugTracePrintf("Inet lookup ok: %s\n", s3eInetToString(&pResult->m_addr));
    }

    // make sure this is not our own server (waste of bandwith to send packets to ourself)
    if ((rec->m_Port == g_Port) && g_MyAddr.m_IPAddress == pResult->m_addr.m_IPAddress)
    {
        s3eDebugTracePrintf("Was self, ignoring\n");
        s3eFree(pResult);
        return 0;
    }

    // push a new record onto the list
    s3eDebugTracePrintf("Add to list as %p\n", pResult);

    pResult->m_pPrev = 0;
    pResult->m_Ref = rec->m_RecordRef;
    pResult->m_pNext = g_ResultList;

    if (g_ResultList)
        g_ResultList->m_pPrev = pResult;

    g_ResultList = pResult;

    return 0;
}

//-----------------------------------------------------------------------------
// this call back is issued when a previously discovered service updates it's txtRecord
//-----------------------------------------------------------------------------
int32 SearchUpdateCallBack(s3eZeroConfSearch* search, s3eZeroConfUpdateRecord* rec, void* userData)
{
    return 0;
}

//-----------------------------------------------------------------------------
// this call back is issued when a previously discovered service is unregisted
//-----------------------------------------------------------------------------
int32 SearchRemoveCallBack(s3eZeroConfSearch* search, void* userRef, void* userData)
{
    Record  *pIter;

    for (pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
        if (pIter->m_Ref == userRef)
            break;

    if (!pIter)
        return 0;

    s3eDebugTracePrintf("SearchRemoveCallBack: %p", pIter);

    // remove pResult from the linked list
    if (pIter->m_pNext)
        pIter->m_pNext->m_pPrev = pIter->m_pPrev;

    if (pIter->m_pPrev)
        pIter->m_pPrev->m_pNext = pIter->m_pNext;
    else
        g_ResultList = pIter->m_pNext;

    // free pResult
    s3eFree(pIter);
    return 0;
}

void ExampleInit()
{
    int64   utcTime = s3eTimerGetUTC();

    // randomise the port to allow multiple instances to run on one host machine for debugging
    g_Port = 8000 + (uint16)((utcTime >> 3) & 127);
    g_RGBIndex = ((int32)(utcTime >> 2) % sizeof(g_r));

    g_Sock = s3eSocketCreate(S3E_SOCKET_UDP, 0);

    memset(&g_MyAddr, 0, sizeof(g_MyAddr));

    g_MyAddr.m_Port = g_Port;

    s3eSocketBind(g_Sock, &g_MyAddr, 1);

    // look up our IP address
    s3eInetLookup(s3eSocketGetString(S3E_SOCKET_HOSTNAME), &g_MyAddr, 0, 0);

    // create a dummy service
    g_Service = s3eZeroConfPublish(g_Port, "s3eDummyService", "_s3ewhiteboard._udp", 0, 0, 0);

    // search for "_http._tcp" services in domain "local"
    g_Search = s3eZeroConfStartSearch(  "_s3ewhiteboard._udp",
                                        "local",
                                        SearchAddCallBack,
                                        SearchUpdateCallBack,
                                        SearchRemoveCallBack,
                                        0);
}

void ExampleShutDown()
{
    s3eDebugTracePrintf("Stopping search: %p", g_Search);
    s3eZeroConfStopSearch(g_Search);
    s3eZeroConfUnpublish(g_Service);

    Record *pNext;

    // free the results
    for (Record *pIter = g_ResultList; pIter; pIter = pNext)
    {
        pNext = pIter->m_pNext;

        // free pIter
        s3eFree(pIter);
    }

    g_ResultList = 0;
}

void ClearScreen()
{
    uint16* screen = (uint16*)s3eSurfacePtr();
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    int32 height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);
    int32 pitch = s3eSurfaceGetInt(S3E_SURFACE_PITCH);

    for (int y = 0; y < height; y++)
        for (int x = 0; x < width; x++)
            screen[y * pitch/2 + x] = 0;
}

bool ExampleUpdate()
{
    // get the current pointer position and selection state
    uint16 pointerX = (uint16)s3ePointerGetX();
    uint16 pointerY = (uint16)s3ePointerGetY();
    s3ePointerState pointerState = s3ePointerGetState(S3E_POINTER_BUTTON_SELECT);

    if (g_PrevPointerState && pointerState && g_nDraw < kDrawBucketSize)
    {
        g_Bucket[g_nDraw].m_r = g_r[g_RGBIndex];
        g_Bucket[g_nDraw].m_g = g_g[g_RGBIndex];
        g_Bucket[g_nDraw].m_b = g_b[g_RGBIndex];
        g_Bucket[g_nDraw].m_x0 = g_PrevX;
        g_Bucket[g_nDraw].m_y0 = g_PrevY;
        g_Bucket[g_nDraw].m_x1 = pointerX;
        g_Bucket[g_nDraw].m_y1 = pointerY;

        // broadcast this
        for (Record *pIter = g_ResultList; pIter; pIter = pIter->m_pNext)
            s3eSocketSendTo(g_Sock, (char*)&g_Bucket[g_nDraw], sizeof(DrawLine), 0, &pIter->m_addr);

        g_nDraw++;
    }

    g_PrevPointerState = pointerState;

    // recieve any broadcasts
    while (g_nDraw < kDrawBucketSize)
    {
        s3eInetAddress sender;
        int dataSize = s3eSocketRecvFrom(g_Sock, (char*)&g_Bucket[g_nDraw], sizeof(DrawLine), 0, &sender);

        if (dataSize == sizeof(DrawLine))
            g_nDraw++;
        else
            break;
    }

    g_PrevX = pointerX;
    g_PrevY = pointerY;

    return true;
}

void ExampleRender()
{
    DontDrawCursor();
    DontClearScreen();

    for (uint32 i = 0; i < g_nDraw; i++)
        DrawLineRGB(g_Bucket[i].m_x0, g_Bucket[i].m_y0,
                    g_Bucket[i].m_x1, g_Bucket[i].m_y1,
                    g_Bucket[i].m_r, g_Bucket[i].m_g, g_Bucket[i].m_b);

    g_nDraw = 0;
}


Airplay API Reference: S3E File

Airplay API Reference > S3E API Documentation > S3E File >

S3E File

The S3E File documentation contains the following sections:

  • S3E File Overview
  • File System API Reference
  • S3E File IO Examples


Airplay API Reference: S3E File Overview

Airplay API Reference > S3E API Documentation > S3E File > S3E File Overview >

S3E File Overview

The File module provides the functionality needed to implement platform-independent file creation and manipulation. The File module contains functions that supply feedback on file system settings, as well as functions that allow standard file operations, such as file open, read, write and close. The syntax and operation of the S3E file functions are similar to those found in the standard C runtime library.

The File callback mechanism allows you to register or unregister functions that will be called when file system operations are performed. The ability to do this means you can create callbacks that implement a user-defined file system; for example, to read a compressed file archive. Callbacks are arranged in the form of a s3eFileUserCallbacks structure, which groups the callbacks together into a user-defined file handling interface. Your file system functions can be registered and unregistered using the s3eFileAddUserFileSys() and s3eFileRemoveUserFileSys() functions respectively. Once your file system functions have been registered they can be used instead of the default set provided.

The File module allows you to manipulate directories. You can create a new directory using the s3eFileMakeDirectory() function. You can also enumerate the contents of a directory, using the s3eFileListDirectory() function, and then cycle through that enumeration performing whatever task is required.

It is important to understand the following subjects in order to use S3E File correctly:

  • Paths in S3E
  • S3E Drives

Note: For an example of how the File functionality can be used, see the S3E File IO Examples.

For more information on the functionality outlined in this section, see the File System API Reference.

Paths in S3E

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. For reasons explained under 'S3E Drives', the application will not normally want to use an explicit drive in its paths. 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.

Note: Paths with 'raw' are for debugging only and are not supported in the release loaders.

Paths can be up to a maximum of S3E_FILE_MAX_PATH (128) bytes long including the NULL terminator. Paths longer than this will cause S3E to fail with an S3E_FILE_ERR_INVALID_PATH error.

Paths in s3e are not case sensitive. Any slashes at the beginning of a path will be ignored. Duplicate separators (mydir//myfile) are automatically reduced to a single separator (mydir/myfile). The use of the parent directory reference '..' is permitted in paths, provided that the path does not resolve to one that is lower than the root of the file system.

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

S3E Drives

The available drives under S3E are 'rom', 'ram' and 'raw'. Some platforms may support an extra 'rst' removable storage drive for a memory card, etc. There may be other special platform-specific drives available on some platforms; consult the platform-specific s3e documentation for more information.

The 'rom' drive is read-only (if it exists) and cannot be written to or modified by the s3e application. The 'ram' drive is read/write and is always entirely separate from the 'rom' drive. The 'rst' drive is read/write (if it exists). The 'raw' drive is only available on debug versions of the loader. The path following the 'raw://' specification is passed directly to the underlying operating system.

The 'ram' drive is the only drive that is guaranteed to exist.

S3E applications must be able to cope with two different deployment situations:

  • When the application's installation data is read-only (e.g., Read-only memory card or archive distribution).
  • When the application's installation data is writable (e.g., a downloaded application).

In situation 1, the installation data will be mounted in the ROM drive (rom://). In situation 2, the installation data will be mounted in the RAM drive (ram://) and the ROM drive will not exist.

The Windows version of S3E by default simulates situation 1. The application data directory (specified by option s3e-data-dir in the mkb) is the rom:// drive, and the ram:// drive is mounted next to the application data directory with a '(ram)' postfix on the directory name. Windows S3E can be made to simulate situation 2 by setting DataDirIsRAM=1 under the [S3E] group in app.icf. In this case the application data directory is mounted as the RAM drive and the ROM drive will not exist.

The S3E file system makes the two situations appear as similar as possible by automatic selection of ROM and RAM drives.

A path without a drive specified will automatically use ROM or RAM according to the following rules:

  • If the system is trying to read from the path (reading an audio/video file, or opening a file for read-only), then S3E will look for the file on the RAM drive first, and then check the ROM drive if the file is not found on RAM.
  • If the system is trying to write to the path, then S3E will always use the RAM drive.

Because reading files chooses the RAM drive over ROM, files in RAM effectively 'shadow' those in ROM. Consider the following under deployment situation 2, where the application installation data is writable:

  • "myfile" exists in application installation data.
  • The application reads "myfile" and obtains the installed version.
  • The application writes a new version of "myfile".
  • The application reads "myfile" which will now read the new version.

Now if the application is moved to deployment situation a, where the installation data is mounted in ROM:

  • "myfile" exists in application installation data (ROM).
  • The application reads "myfile" (will search RAM, then ROM, and find the file) and obtains the installed version.
  • The application writes a new version of "myfile", which will automatically go to RAM.
  • The application reads "myfile" which will now read the new version from RAM as RAM is searched first.

Therefore, no change to the application code is needed to cope with the two situations. The requirement is that the application does not explicitly specify the drive in its paths.

Factors to consider are:

  • Deleting and renaming files will cause different behaviour under the two deployment situations. Deleting a file under situation 2 will cause the file to be erased. Deleting a file under situation 1 will cause its RAM version to be deleted (if it exists) and the file will effectively revert to its ROM version.
  • Opening a file for read/write under situation 1 will cause the file to be copied to the RAM drive before it is opened. S3E will trace a warning when this is happening.
  • Opening a file for write in a directory that does not exist will normally fail. However under situation 1, if the directory exists in the ROM drive already, the directory will automatically be created in the RAM drive. This will only happen for directories that already exist in the ROM drive. This enables file shadowing in files that are in subdirectories.

Note: The above behaviour only applies to paths without a drive specified. If a path has an explicit drive specified, then S3E will use that drive and fail if it cannot.


Airplay API Reference: File System API Reference

Airplay API Reference > S3E API Documentation > S3E File > File System API Reference >

File System API Reference
[S3E]

Data Structures

struct | s3eFileUserCallbacks

Defines

#define | S3E_FILE_MAX_HANDLES 32
#define | S3E_FILE_MAX_PATH 128
#define | S3E_FILE_NOUSER_MODECHAR 'U'

Typedefs

typedef struct s3eFileList | s3eFileList
typedef s3eResult(* | s3eUserCloseFn )(s3eUsrFile *file)
typedef s3eResult(* | s3eUserDeleteFn )(const char *filename)
typedef s3eBool(* | s3eUserEOFFn )(s3eUsrFile *file)
typedef s3eResult(* | s3eUserListCloseFn )(s3eUsrFileList *handle)
typedef s3eUsrFileList *(* | s3eUserListDirFn )(const char *path)
typedef s3eResult(* | s3eUserListNextFn )(s3eUsrFileList *handle, char *filename, int filenameLen)
typedef s3eUsrFile *(* | s3eUserOpenFn )(const char *filename, const char *mode)
typedef uint32(* | s3eUserReadFn )(void *buffer, uint32 elemLen, uint32 noElems, s3eUsrFile *file)
typedef s3eResult(* | s3eUserSeekFn )(s3eUsrFile *file, int32 offset, s3eFileSeekOrigin origin)
typedef int32(* | s3eUserTellFn )(s3eUsrFile *file)
typedef uint32(* | s3eUserWriteFn )(const void *buffer, uint32 elemLen, uint32 noElems, s3eUsrFile *file)
typedef struct s3eUsrFile | s3eUsrFile
typedef struct s3eUsrFileList | s3eUsrFileList

Enumerations

enum | s3eFileError
enum s3eFileProperty {
S3E_FILE_DEFAULT_PATH = 0,
S3E_FILE_ROM_EXISTS = 1,
S3E_FILE_BYTES_TOTAL = 2,
S3E_FILE_BYTES_FREE = 3
}
enum | s3eFileSeekOrigin
enum s3eFileStats {
S3E_FILE_ISFILE = 0,
S3E_FILE_ISDIR = 1,
S3E_FILE_ISUSER = 2,
S3E_FILE_ISWRITABLE = 3,
S3E_FILE_SIZE = 4,
S3E_FILE_MODIFIED_DATE = 5,
S3E_FILE_DRIVE_BYTES_FREE = 6,
S3E_FILE_DRIVE = 7,
S3E_FILE_DRIVE_BYTES_TOTAL = 8
}

Functions

S3E_API s3eResult | s3eFileAddUserFileSys (s3eFileUserCallbacks *callbacks)
S3E_API s3eBool | s3eFileCheckExists (const char *filename)
S3E_API s3eResult | s3eFileClose (s3eFile *file)
S3E_API s3eResult | s3eFileDelete (const char *filename)
S3E_API s3eResult | s3eFileDeleteDirectory (const char *dirName)
S3E_API s3eBool | s3eFileEOF (s3eFile *file)
S3E_API s3eResult | s3eFileFlush (s3eFile *file)
S3E_API int32 | s3eFileGetChar (s3eFile *file)
S3E_API s3eFileError | s3eFileGetError ()
S3E_API const char * | s3eFileGetErrorString ()
S3E_API int64 | s3eFileGetFileInt (const char *filename, s3eFileStats stat)
S3E_API char * | s3eFileGetFileString (const char *filename, s3eFileStats stat, char *str, int len)
S3E_API uint64 | s3eFileGetFree (s3eFilePath path)
S3E_API int32 | s3eFileGetInt (s3eFileProperty property)
S3E_API uint64 | s3eFileGetLastWriteTime (const char *filename)
S3E_API int32 | s3eFileGetSize (s3eFile *file)
S3E_API s3eResult | s3eFileListClose (s3eFileList *handle)
S3E_API s3eFileList * | s3eFileListDirectory (const char *dirName)
S3E_API s3eResult | s3eFileListNext (s3eFileList *handle, char *filename, int filenameLen)
S3E_API s3eResult | s3eFileMakeDirectory (const char *dirName)
S3E_API s3eFile * | s3eFileOpen (const char *filename, const char *mode)
S3E_API s3eFile * | s3eFileOpenFromMemory (void *buffer, uint32 bufferLen)
S3E_EAPI int | s3eFilePrintf (s3eFile *f, const char *fmt,...)
S3E_API int32 | s3eFilePutChar (char c, s3eFile *file)
S3E_API uint32 | s3eFileRead (void *buffer, uint32 elemSize, uint32 noElems, s3eFile *file)
S3E_API char * | s3eFileReadString (char *string, uint32 maxLen, s3eFile *file)
S3E_API s3eResult | s3eFileRemoveUserFileSys (s3eFileUserCallbacks *callbacks)
S3E_API s3eResult | s3eFileRename (const char *src, const char *dest)
S3E_API s3eResult | s3eFileSeek (s3eFile *file, int32 offset, s3eFileSeekOrigin origin)
S3E_API s3eResult | s3eFileSetInt (s3eFileProperty property, int32 value)
S3E_API int32 | s3eFileTell (s3eFile *file)
S3E_API uint32 | s3eFileWrite (const void *buffer, uint32 elemSize, uint32 noElems, s3eFile *file)

Detailed Description

For more information on the File System functionality provided by the S3E module, see the S3E File section of the S3E API Documentation.

Define Documentation

#define S3E_FILE_EOF (-1)

Represents end-of-file.

#define S3E_FILE_MAX_HANDLES 32

The maximum number of file handles that can be simultaneously open in S3E

#define S3E_FILE_MAX_PATH 128

The maximum length of any file or path passed in to S3E, including the terminating NULL.

#define S3E_FILE_NOUSER_MODECHAR 'U'

additional character that can be used with fileOpen mode specification to disable use of user file systems

Typedef Documentation

typedef struct s3eFile s3eFile

Abstract File pointer type.

typedef struct s3eFileList s3eFileList

Abstract file list handle.

typedef s3eResult(* s3eUserCloseFn)(s3eUsrFile *file)

Close callback.

Parameters:
file A s3eUsrFile returned from a s3eUserOpenFn callback.
Returns:
standard s3eResult enumeration.
Required Header Files
s3eFile.h

typedef s3eResult(* s3eUserDeleteFn)(const char *filename)

Delete file callback.

Parameters:
filename path to file to delete.
Returns:
S3E_RESULT_SUCCESS if the file was deleted, S3E_RESULT_ERROR otherwise.
Required Header Files
s3eFile.h

typedef s3eBool(* s3eUserEOFFn)(s3eUsrFile *file)

EOF callback.

Parameters:
file A s3eUsrFile returned from a s3eUserOpenFn callback.
Returns:
1 if EOF has been reached, else 0.
Required Header Files
s3eFile.h

typedef s3eResult(* s3eUserListCloseFn)(s3eUsrFileList *handle)

Close directory listing callback.

Parameters:
handle s3eUsrFileList returned from the s3eUserListDirFn.
Returns:
S3E_RESULT_SUCCESS if the handle was closed successfully, S3E_RESULT_ERROR otherwise.
Required Header Files
s3eFile.h

typedef s3eUsrFileList*(* s3eUserListDirFn)(const char *path)

List directory callback.

Parameters:
path Directory to list.
Returns:
If files in the directory exist, a handle to begin enumeration of files. Otherwise NULL.
Required Header Files
s3eFile.h

typedef s3eResult(* s3eUserListNextFn)(s3eUsrFileList *handle, char *filename, int filenameLen)

Enumerate files callback.

Parameters:
handle | s3eUsrFileList returned from the s3eUserListDirFn.
filename | Buffer where the next filename is to be stored.
filenameLen | Buffer size of filename.
Returns:
S3E_RESULT_SUCCESS if a file name is returned, S3E_RESULT_ERROR if no more files remain to be enumerated.
Required Header Files
s3eFile.h

typedef s3eUsrFile*(* s3eUserOpenFn)(const char *filename, const char *mode)

Opens file callback.

Parameters:
filename | Name of file to open.
mode | fopen-style modestring for file permission options.
Returns:
a non-NULL s3eUsrFile pointer if opening succeeded, otherwise NULL.
Required Header Files
s3eFile.h

typedef uint32(* s3eUserReadFn)(void *buffer, uint32 elemLen, uint32 noElems, s3eUsrFile *file)

Read file callback.

Parameters:
buffer | Pointer to read into.
elemLen | Size of data elements.
noElems | Number of data elements.
file | A s3eUsrFile returned from a s3eUserOpenFn callback.
Returns:
The number of complete elements read into buffer.
Required Header Files
s3eFile.h

typedef s3eResult(* s3eUserSeekFn)(s3eUsrFile *file, int32 offset, s3eFileSeekOrigin origin)

Seek callback.

Parameters:
file | A s3eUsrFile returned from a s3eUserOpenFn callback.
offset | Number of bytes from origin.
origin | Origin to seek from.
Returns:
S3E_RESULT_SUCCESS on success, otherwise S3E_RESULT_ERROR.
Required Header Files
s3eFile.h

typedef int32(* s3eUserTellFn)(s3eUsrFile *file)

Tell callback.

Parameters:
file A s3eUsrFile returned from a s3eUserOpenFn callback.
Returns:
Current file pointer position.
Required Header Files
s3eFile.h

typedef uint32(* s3eUserWriteFn)(const void *buffer, uint32 elemLen, uint32 noElems, s3eUsrFile *file)

Write file callback.

Parameters:
buffer | Pointer to read into.
elemLen | Size of data elements.
noElems | Number of data elements.
file | A s3eUsrFile returned from a s3eUserOpenFn callback.
Returns:
The number of elements written to the file.
Required Header Files
s3eFile.h

typedef struct s3eUsrFile s3eUsrFile

Abstract type for a file opened via user callbacks.

typedef struct s3eUsrFileList s3eUsrFileList

Opaque handle used for directory listing

Enumeration Type Documentation

enum s3eFileError

File Errors.

See also:
s3eFileGetError

s3eFileGetErrorString

Required Header Files
s3eFile.h
Enumerator:
S3E_FILE_ERR_NONE | No Error.
S3E_FILE_ERR_PARAM | Invalid parameter.
S3E_FILE_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_FILE_ERR_ALREADY_REG | The specified callback is already registered.
S3E_FILE_ERR_NOT_FOUND | Path not found / callback not found for removal.
S3E_FILE_ERR_UNAVAIL | file support is unavailable or feature is not supported.
S3E_FILE_ERR_DEVICE | The underlying file device failed.
S3E_FILE_ERR_UNSUPPORTED | The action requested was is not supported.
S3E_FILE_ERR_MEM | Out of operating system memory during operation.
S3E_FILE_ERR_GENERIC | Unspecified error.
S3E_FILE_ERR_INVALID_DRIVE | Invalid/unsupported drive specified in path.
S3E_FILE_ERR_INVALID_PATH | The path could not be resolved onto the device filesytem (e.g. opening ROM://../file).
S3E_FILE_ERR_DATA | Data read/write error.
S3E_FILE_ERR_INVALID_MODE | Invalid mode specification for s3eFileOpen().
S3E_FILE_ERR_EXISTS | File/Path already exists.
S3E_FILE_ERR_NOT_EMPTY | Directory not empty on removal.
S3E_FILE_ERR_ACCESS | Access permission/error deleting file.
S3E_FILE_ERR_NO_MORE | No more files in directory listing.
S3E_FILE_ERR_EOF | EOF reached during file operation.

enum s3eFilePath

File path types. This is deprecated.

Enumerator:
S3E_FILEPATH_ROM | A file in ROM (e.g. on a read-only memory card).
S3E_FILEPATH_RAM | A file in RAM (e.g. on writable flash storage).
S3E_FILEPATH_MMC | A file on MMC.

enum s3eFileProperty

File Properties.

See also:
s3eFileGetInt

s3eFileSetInt

Required Header Files
s3eFile.h
Enumerator:
S3E_FILE_DEFAULT_PATH | Default path type used by functions that do not specify a path. This is now deprecated.
S3E_FILE_ROM_EXISTS | Returns wether the rom:// drive is valid and in use. This is a useful indicator for telling if the data directory has been mounted as RAM (ROM drive does not exist) or ROM (ROM drive does exist).
S3E_FILE_BYTES_TOTAL | Return the total number of bytes of the storage available on the ram:// drive
S3E_FILE_BYTES_FREE | Return the number of bytes free on ram:// drive

enum s3eFileSeekOrigin

Different seek origin types used by s3eFileSeek().

Required Header Files
s3eFile.h
Enumerator:
S3E_FILESEEK_SET | Beginning of file.
S3E_FILESEEK_CUR | Current position of file pointer.
S3E_FILESEEK_END | End of file.

enum s3eFileStats

File Stats.

See also:
s3eFileGetFileInt

s3eFileGetFileString

Required Header Files
s3eFile.h
Enumerator:
S3E_FILE_ISFILE | [int, read] Returns whether the file exists. This property will evaluate to 1 on any file that s3eFileOpen() can open, and will hence include files in any registered user filesystem. This produces the same result as calling s3eFileCheckExists(). This property will evaluate to 0 otherwise.
S3E_FILE_ISDIR | [int, read] Returns whether the directory exists. This property will evaluate to 1 on valid directory paths. This does not include directories in the user file system. This property will evaluate to 0 otherwise.
S3E_FILE_ISUSER | [int, read] Returns whether the file exists in the user file system. This property will evaluate to 1 on any file that the user file system can open. This property will evaluate to 0 otherwise.
S3E_FILE_ISWRITABLE | [int, read] Returns whether the file is writable. This property will evaluate to 1 on any file that exists on a writable drive. This property will evaluate to 0 on any file that exists on a read-only drive. For files that exists on a ROM drive but are shadowable to RAM this will return 1, as opening the file for writing would succeed. This property will fail to evaluate for a file that does not exist (return -1).
S3E_FILE_SIZE | [int, read] Returns the size of the file, in bytes. This property will fail to evaluate (return -1) on a non-existant file.
S3E_FILE_MODIFIED_DATE | [int, read] Returns the date of last modification of the file, in milliseconds elapsed since midnight (00:00:00), January 1, 1970. This is the same time datum as used by the Timer module. The date returned is in the local time of the device. Querying this property will fail for files in the the user file system. This property will fail to evaluate (return -1) on a non-existant file.
S3E_FILE_DRIVE_BYTES_FREE | [int, read] Returns the free space in bytes on the drive that stores this file. Querying the free space for any path that contains a drive specifier will return the free space on the drive specified, independent of whether the file exists. If querying the free space fails for any reason (invalid drive, invalid path), the return value of s3eFileGetFileInt() will always be 0. If S3E_FILE_DRIVE_BYTES_FREE == S3E_FILE_DRIVE_BYTES_TOTAL then the drive is empty. If S3E_FILE_DRIVE_BYTES_FREE == 0 then the drive is full.
S3E_FILE_DRIVE | [string, read] Returns a string containing the drive on which the file is stored. If the file does not exist this property will fail to evaluate (return NULL string). If the file is on the user file system, this will return "user" (without the '://' drive syntax)
S3E_FILE_DRIVE_BYTES_TOTAL | [int, read] Returns the total space available on the drive that stores this file. Querying the space available for any path that contains a drive specifier will return the free space on the drive specified, independent of whether the file exists. If querying the total space fails for any reason (invalid drive, invalid path), the return value of s3eFileGetFileInt() will always be 0.

Function Documentation

S3E_API s3eResult s3eFileAddUserFileSys ( s3eFileUserCallbacks * callbacks )

Register a user-defined filing system.

Parameters:
callbacks s3eFileUserCallbacks.
Remarks:
The contents of callbacks is added to the list of user-defined file systems, allowing the user to change the behaviour of many of the s3eFile functions. See s3eFileUserCallbacks for more information. All the members of callbacks must be non-NULL, except for m_Write and m_Delete.
Required Header Files
s3eFile.h

S3E_API s3eBool s3eFileCheckExists ( const char * filename )

Checks whether or not a specified file exists.

Parameters:
filename name of file.
Returns:
S3E_FALSE if the specified file does not exist. S3E_TRUE if the specified file exists.
Remarks:
This function checks user file systems for the ability to open the given filename in addition to the device file system. s3eFileCheckExists() will return S3E_TRUE for any file that s3eFileOpen(<name>, "r") would succeed on.
See also:
s3eFileOpen

s3eFileClose

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileClose ( s3eFile * file )

Closes an open file.

Parameters:
file Pointer to the s3eFile object to close.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return one of:
    • S3E_FILE_ERR_PARAM if file is not a valid file handle.
See also:
s3eFileOpen

s3eFileOpenFromMemory

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileDelete ( const char * filename )

Deletes a specified file, if it exists.

Parameters:
filename pathname of file.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if filename is NULL.
    • S3E_FILE_ERR_INVALID_DRIVE if filename specifies an invalid drive.
    • S3E_FILE_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
    • S3E_FILE_ERR_ACCESS if filename specifies a drive that cannot be written to.
    • S3E_FILE_ERR_NOT_FOUND if filename specifies a file that does not exist, or filename specifies a directory.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed.
See also:
s3eFileOpen

s3eFileClose

s3eFileCheckExists

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileDeleteDirectory ( const char * dirName )

Deletes a directory.

Parameters:
dirName name of directory.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if dirName is NULL.
    • S3E_FILE_ERR_INVALID_DRIVE if dirName specifies an invalid drive was specified.
    • S3E_FILE_ERR_INVALID_PATH if dirName could not be resolved onto a device-specific path.
    • S3E_FILE_ERR_NOT_FOUND if dirName specifies a directory that does not exist.
    • S3E_FILE_ERR_NOT_EMPTY if dirName specifies a directory that is not empty.
    • S3E_FILE_ERR_ACCESS if dirName specifies a drive that cannot be written to.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed.
Remarks:
Directory must be empty before this is called.
Required Header Files
s3eFile.h

S3E_API s3eBool s3eFileEOF ( s3eFile * file )

Determines whether the end of the open file has been reached.

Parameters:
file Pointer to the s3eFile object to check.
Returns:
- S3E_FALSE if the end of file has not been reaced
  • S3E_TRUE if the previous file operation reached the end of the file or file is invalid If file is invalid, S3E_FILE_ERR_PARAM will be set. Call s3eFileGetError() to check the error code.
Remarks:
s3eFileEOF will continue to retrun true once the eof of a file is reached. Only a call to s3eFileSeek will cause the EOF flag to be reset.

If file was opened with a user file system, this will call the user file system to determine the EOF status. see s3eFileUserCallbacks for more on user file systems

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileFlush ( s3eFile * file )

Flush file to disk.

Parameters:
file file handle to flush.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return one of:
    • S3E_FILE_ERR_PARAM if file is not a valid file handle.
    • S3E_FILE_ERR_DEVICE if the underlying file device could not flush data to the file.
Remarks:
If the file was opened using a user file system, this function will perform no action and return S3E_RESULT_SUCCESS.
See also:
s3eFileOpen

s3eFileOpenFromMemory

Required Header Files
s3eFile.h

S3E_API int32 s3eFileGetChar ( s3eFile * file )

Reads the next char (byte) from an open file.

Parameters:
file Pointer to the s3eFile object to read from.
Returns:
The value of the read byte, or S3E_FILE_EOF if at the end of the file. If S3E_FILE_EOF is returned, call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM if file is an invalid handle.
  • S3E_FILE_ERR_EOF if the end of the file was reached.
  • S3E_FILE_ERR_DATA if the underlying file device failed to read data.
Remarks:
If file was opened with a user file system, this will call the user file system to perform the read. See s3eFileUserCallbacks for more on user file systems
See also:
s3eFilePutChar

s3eFileRead

Required Header Files
s3eFile.h

S3E_API s3eFileError s3eFileGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eFileGetErrorString.
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eFile.h

S3E_API const char* s3eFileGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This funtion is only available in debug builds.

See also:
s3eFileGetError.
Remarks:
This function, as opposed to s3eFileGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eFile.h

S3E_API int64 s3eFileGetFileInt | ( | const char * | filename,
 |  | s3eFileStats | stat
 | ) |  |

Retrieves an integer property for a file.

Parameters:
filename | file name of file.
stat | Property of file to query.
Returns:
  • The value of the requested property if stat is valid.
  • (uint64)-1 otherwise Call s3eFileGetError() to retrieve an error code. This will return:
    • S3E_FILE_ERR_PARAM if stat is not valid or filename is NULL.
    • S3E_FILE_ERR_INVALID_DRIVE if an invalid drive was specified when querying file size or date.
    • S3E_FILE_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path when querying file size or date.
    • S3E_FILE_ERR_NOT_FOUND if filename does not exist when querying file size or date.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed.
Remarks:
Use this function to query the status of files and directories, including file size and date. See
See also:
s3eFileStats for information on propreties that can be queried.

s3eFileGetFileString

Required Header Files
s3eFile.h

S3E_API char* s3eFileGetFileString | ( | const char * | filename,
 |  | s3eFileStats | stat,
 |  | char * | str,
 |  | int | len
 | ) |  |

Retrieves a string property for a file.

Parameters:
filename | file name of file.
stat | Property of file to query.
str | buffer for output.
len | size of memory pointed to by str.
Returns:
str on success, or NULL on failure. If the return is NULL, call s3eFileGetError() to retrieve an error code. This will return:
  • S3E_FILE_ERR_PARAM if stat is not valid, filename is NULL or str is NULL.
  • S3E_FILE_ERR_INVALID_DRIVE if an invalid drive was specified.
  • S3E_FILE_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
  • S3E_FILE_ERR_NOT_FOUND if filename does not exist.
  • S3E_FILE_ERR_DEVICE if the underlying file device failed.
Remarks:
Currently the only valid string that can be returned is the drive the file is stored on using the paramater S3E_FILE_DRIVE. If the resulting string is more than len bytes long it will be truncated.
See also:
s3eFileGetFileInt
Required Header Files
s3eFile.h

S3E_API uint64 s3eFileGetFree ( s3eFilePath path )

Returns the free space, in bytes, for the specified file path. This is deprecated, use s3eFileGetFileInt() instead.

Parameters:
path an s3eFilePath.
Remarks:
path may be ROM, RAM or MMC.
Returns:
On success, the free space available on path in bytes. 0 otherwise.
Required Header Files
s3eFile.h

S3E_API int32 s3eFileGetInt ( s3eFileProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 if property is not valid.
    Call s3eFileGetError() to retrieve an error code. This will return:
    S3E_FILE_ERR_PARAM if property is not valid.
See also:
s3eFileSetInt
Required Header Files
s3eFile.h

S3E_API uint64 s3eFileGetLastWriteTime ( const char * filename )

Returns the last time the file was modified. This function is deprecated.

Parameters:
filename Pathname of file, relative to the default path already set.
Returns:
Time of last modification in milliseconds slices since 1970 (i.e. UNIX time but in milliseconds).
Required Header Files
s3eFile.h

S3E_API int32 s3eFileGetSize ( s3eFile * file )

Returns the size, in bytes, of an open file handle.

Parameters:
file Handle to a file produced by s3eFileOpen().
Returns:
On success, the size of the file, in bytes; -1 on error Call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM if file is invalid.
  • S3E_FILE_ERR_DEVICE if the size of file could not be found.
See also:
s3eFileOpen

s3eFileClose

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileListClose ( s3eFileList * handle )

Closes the handle returned by s3eFileListDirectory().

Parameters:
handle Handle returned from s3eFileListDirectory() to be closed.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if handle is invalid.
Required Header Files
s3eFile.h

S3E_API s3eFileList* s3eFileListDirectory ( const char * dirName )

Enumerates the contents of a directory.

Parameters:
dirName directory to enumerate. Can be NULL to enumerate drives.
Returns:
A handle to be passed to s3eFileListNext(), or NULL if the directory does not exist. If the result is NULL, call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_NOT_FOUND if dirName does not exist, or does not contain any files.
  • S3E_FILE_ERR_DEVICE if the underlying file device failed.
  • S3E_FILE_ERR_TOO_MANY if too many s3eFileList handles are open.
  • S3E_FILE_ERR_MEM if memory could not be allocated from the underlying operating system to generate the list.
Remarks:
Passing NULL as dirName is a special case that will enumerate the drives of the system.

Call s3eFileListNext() to read the file names or drives. Call s3eFileListClose() to close the handle.

This function calls the user file system to enumerate files in addition to the system filesystem. The files returned by s3eFileListDirectory(x) are all either files or subdirectories, including those that can be opened via the user file system.

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileListNext | ( | s3eFileList * | handle,
 |  | char * | filename,
 |  | int | filenameLen
 | ) |  |

Returns the next file in the directory.

Parameters:
handle | Handle returned from s3eFileListDirectory().
filename | Pointer to buffer where the filename will be stored.
filenameLen | Size of buffer pointed to by filename.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if handle is invalid or filename is NULL.
    • S3E_FILE_ERR_NO_MORE if no more files remain to be enumerated.
Remarks:
This function copies the name of the next file in the directory listing into filename. filename must point to at least filenameLen bytes of storage. If the actual file name is longer than filenameLen, the name will be truncated.
Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileMakeDirectory ( const char * dirName )

Creates a single new directory.

Parameters:
dirName name of directory.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if dirName is NULL.
    • S3E_FILE_ERR_INVALID_DRIVE if dirName specifies an invalid drive was specified.
    • S3E_FILE_ERR_INVALID_PATH if dirName could not be resolved onto a device-specific path.
    • S3E_FILE_ERR_NOT_FOUND if dirName specifies a subdirectory path that does not exist.
    • S3E_FILE_ERR_ACCESS if dirName specifies a drive that cannot be written to.
    • S3E_FILE_ERR_EXISTS if dirName already exists.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed .
Remarks:
The path specified by dirName must not exist but any subdirectories specified must exist as the function can only create the top level directory.
Required Header Files
s3eFile.h

S3E_API s3eFile* s3eFileOpen | ( | const char * | filename,
 |  | const char * | mode
 | ) |  |

Opens a file from the file system.

Parameters:
filename | Pathname of file, either as a relative or absolute path.
mode | stdio-style string defining the mode in which to open the file.
Returns:
  • A valid s3eFile pointer if no error occurred.
  • NULL if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return one of:
    • S3E_FILE_ERR_INVALID_DRIVE if an invalid drive was specified.
    • S3E_FILE_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
    • S3E_FILE_ERR_NOT_FOUND if filename does not exist.
    • S3E_FILE_ERR_ACCESS if permission was denied on the file.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed.
    • S3E_FILE_ERR_TOO_MANY if the maxmimum number of file handles (S3E_FILE_MAX_HANDLES) has been reached.
Remarks:
mode is a concatenation of an access string, an optional translation mode string and an optional specifier that prevents use of any user-defined file systems.
  • The access string can be one of:-
    • "r" Opens for reading only. If the file does not exist or cannot be found, the s3eFileOpen() call fails.
    • "w" Opens an empty file for writing. If the given file exists, its contents are destroyed.
    • "a" Opens for appending (doesn't remove EOF marker) creates the file first if it doesn’t exist.
    • "r+" Opens for both reading and writing. (The file must exist.)
    • "w+" Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.
    • "a+" Opens for reading and appending; creates the file first if it does not exist.
  • The translation mode string can be one of:-
    • "t" Opens the file in text translation mode. This will translate CR/LF pairs in the file into LF's during read. No write translation is performed. S3E will not translate CTRL+Z characters. This is the default.
    • "b" Opens the file in binary mode. The file will be read untranslated.
  • The optional user file system specified is:-
    • "U" Disables the use of user-defined file systems when opening this file. The call to s3eFileOpen() will not be passed on to the m_Open function of registered file systems.

Call s3eFileClose() to close the file handle. Up to S3E_FILE_MAX_HANDLES may be open at once.

Multiple simulatneous read handles to the same file are supported, but only a single write handle is supported per file. Simultaneous read and write handles are not supported.

s3eFileOpen() will first call all the registered user file systems to open the file before attempting to accesss the device's storage. See s3eFileUserCallbacks for more information on user file systems.

See also:
s3eFileClose

s3eFileOpenFromMemory

Required Header Files
s3eFile.h

S3E_API s3eFile* s3eFileOpenFromMemory | ( | void * | buffer,
 |  | uint32 | bufferLen
 | ) |  |

Opens file from memory.

Parameters:
buffer | Pointer to a buffer to use as a file store.
bufferLen | Size in bytes of the buffer.
Returns:
  • A valid s3eFile pointer if no error occurred
  • NULL if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return one of:
    • S3E_FILE_ERR_PARAM if buffer is NULL .
    • S3E_FILE_ERR_TOO_MANY if the maximum number of file handles has been reached (S3E_FILE_MAX_HANDLES).
See also:
s3eFileClose

s3eFileOpen

Required Header Files
s3eFile.h

S3E_EAPI int s3eFilePrintf | ( | s3eFile * | f,
 |  | const char * | fmt,
 |  |  | ...
 | ) |  |

Prints formatted data to a stream.

Parameters:
f | Pointer to FILE structure
fmt | Format-control string.
Returns:
The number of bytes written. A negative value is returned when an output error occurs.
Remarks:
s3eFilePrintf formats and prints a series of characters and values to the output stream. Each function argument (if any) is converted and output according to the corresponding format specification in fmt.
Required Header Files
s3eFile.h

S3E_API int32 s3eFilePutChar | ( | char | c,
 |  | s3eFile * | file
 | ) |  |

Writes the next char (byte) to an open file.

Parameters:
c | The byte value to write.
file | Pointer to the s3eFile object to write to.
Returns:
The value of the written byte, or S3E_FILE_EOF if the byte could not be written. If S3E_FILE_EOF is returned, call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM if file is an invalid handle.
  • S3E_FILE_ERR_DATA if data could not be written.
  • S3E_FILE_ERR_UNSUPPORTED if file is a file opened from a user filesystem and the user filesystem's m_Write function is NULL.
Remarks:
If file was opened with a user file system, this will call the user file system to perform the write. See s3eFileUserCallbacks for more on user file systems.
See also:
s3eFilePutChar

s3eFileGetChar

s3eFileWrite

Required Header Files
s3eFile.h

S3E_API uint32 s3eFileRead | ( | void * | buffer,
 |  | uint32 | elemSize,
 |  | uint32 | noElems,
 |  | s3eFile * | file
 | ) |  |

Reads some data from an open file.

Parameters:
buffer | Pointer to the area in memory at which to start reading.
elemSize | Size in bytes of a single data element to be read.
noElems | Number of data elements to read, in bytes.
file | Pointer to the s3eFile object to read from.
Returns:
The full number of items actually read (same caveats as fread). The total number of bytes read is (elemSize * noElems). If the number of items read is less than noElems, an error code is set. Call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM buffer is NULL or file is invalid.
  • S3E_FILE_ERR_DATA if the underlying file device failed to read in data.
  • S3E_FILE_ERR_EOF if the end of the file was reached before all the data could be read in.
Remarks:
Note that if the file was opened in text translation mode, the number of bytes read from the file may be larger than than elemSize*noElems due to CR/LF translation.

If file was opened with a user file system, this will call the user file system to perform the read. see s3eFileUserCallbacks for more on user file systems

See also:
s3eFileWrite

s3eFileOpen

s3eFileClose

Required Header Files
s3eFile.h

S3E_API char* s3eFileReadString | ( | char * | string,
 |  | uint32 | maxLen,
 |  | s3eFile * | file
 | ) |  |

Reads a newline-terminated string from a file.

Parameters:
string | Storage location for string.
maxLen | Maximum number of characters to read.
file | Pointer to the s3eFile object to read from.
Returns:
string if the function read any data, NULL if a read error or end-of-file occurred before data could be read. If the result is NULL, call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM if string is NULL or file is invalid.
  • S3E_FILE_ERR_DATA if the underlying file device failed to read in data.
  • S3E_FILE_ERR_EOF if the end of the file was reached before all the data could be read in.
Remarks:
This function reads characters from the current stream position to and including the first newline character, to the end of the stream, or until the number of characters read is equal to maxLen - 1, whichever comes first. The result stored in string is appended with a null character. The newline character, if read, is included in the string.

This function will also set S3E_FILE_ERR_DATA or S3E_FILE_ERR_EOF if a data error or end-of-file occurred after the first byte of string was read.

If file was opened with a user file system, this will call the user file system to perform the read. See s3eFileUserCallbacks for more on user file systems.

See also:
s3eFileWrite

s3eFileOpen

s3eFileClose

s3eFileRead

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileRemoveUserFileSys ( s3eFileUserCallbacks * callbacks )

Remove a user-defined filing system.

Parameters:
callbacks s3eFileUserCallbacks.
Remarks:
All members of callbacks must match those passed to s3eFileSetUserFileSys().
Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileRename | ( | const char * | src,
 |  | const char * | dest
 | ) |  |

Renames a specified file to a new filename.

Parameters:
src | Pathname of existing file.
dest | Pathname of new file.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    • S3E_FILE_ERR_PARAM if src or dest is NULL. Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_INVALID_DRIVE if src or dest specifies an invalid drive was specified.
    • S3E_FILE_ERR_INVALID_PATH if src or dest could not be resolved onto a device-specific path.
    • S3E_FILE_ERR_NOT_FOUND if src specifies a file that does not exist, or src specifies a directory.
    • S3E_FILE_ERR_ACCESS if src or dest specifies a drive that cannot be written to.
    • S3E_FILE_ERR_EXISTS if dest specifies a file that already exists.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed .
Remarks:
s3eFileRename() can be used to either rename a file or move it to a different directory. Moving files between drives is permitted, although the user should note that this may cause a slower copy operation internally. Renaming a file to itself will succeed. Renaming directories will fail with S3E_FILE_ERR_NOT_FOUND. dest must specify the full path to the new file, and not just the directory. If dest specifies a directory, the function will fail with error code S3E_FILE_ERR_EXISTS.
See also:
s3eFileOpen

s3eFileClose

s3eFileCheckExists

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileSeek | ( | s3eFile * | file,
 |  | int32 | offset,
 |  | s3eFileSeekOrigin | origin
 | ) |  |

Moves the file pointer to a specified position.

Parameters:
file | Pointer to the s3eFile object.
offset | Number of bytes from specified origin to seek to.
origin | Origin type to use.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve the error code. This will return one of:
    • S3E_FILE_ERR_PARAM if file is invalid, origin is invalid, or an attempt is made to seek before the beginning of the file.
    • S3E_FILE_ERR_DEVICE if the underlying file device failed to seek.
Remarks:
s3eFileSeek() moves the file pointer to a position that is offset bytes from origin. origin must be one of the following:
  • S3E_FILESEEK_SET : The beginning of the file.
  • S3E_FILESEEK_CUR : The current file pointer position.
  • S3E_FILESEEK_END : The end of the file.

The file pointer can be positioned anywhere within a file. For writable files it can be positioned beyond the end of the file. In this case the next write operation will cause the file to be expanded with zeros. Note that s3eFileSeek() may cause confusing results when reading a file in text (CR/LF translation) mode.

See also:
s3eFileTell

s3eFileRead

s3eFileWrite

Required Header Files
s3eFile.h

S3E_API s3eResult s3eFileSetInt | ( | s3eFileProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eFileGetError() to retrieve an error code. This will return:
    • S3E_FILE_ERR_PARAM if property is invalid or value is invalid.
Remarks:
There are currently no valid file device properties that can be set; This function will always fail.
See also:
s3eFileGetInt
Required Header Files
s3eFile.h

S3E_API int32 s3eFileTell ( s3eFile * file )

Gets the current position of a file pointer.

Parameters:
file Pointer to the s3eFile object.
Returns:
If successful, the current file pointer offset, in bytes; -1 on error. Call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM if file is invalid.
See also:
s3eFileSeek

s3eFileRead

s3eFileWrite

Required Header Files
s3eFile.h

S3E_API uint32 s3eFileWrite | ( | const void * | buffer,
 |  | uint32 | elemSize,
 |  | uint32 | noElems,
 |  | s3eFile * | file
 | ) |  |

Writes some data to an open file.

Parameters:
buffer | Pointer to the area of memory at which to start writing.
elemSize | Size in bytes of a single element of data to write.
noElems | Number of data elements to write, in bytes.
file | Pointer to the s3eFile object to write to.
Returns:
The full number of items actually written (same caveats as fwrite). The total number of bytes written is (elemSize * noElems). If the number of items written is less than noElems, an error code is set. Call s3eFileGetError() to retrieve the error code. This will return one of:
  • S3E_FILE_ERR_PARAM buffer is NULL or file is invalid.
  • S3E_FILE_ERR_DATA if the underlying file device failed to write the data or an attempt was made to write beyond the end of a memory file's buffer.
  • S3E_FILE_ERR_UNSUPPORTED if file is a file opened from a user filesystem and the user filesystem's m_Write function is NULL.
Remarks:
If file was opened with a user file system, this will call the user file system to perform the write. see s3eFileUserCallbacks for more on user file systems.
See also:
s3eFileRead

s3eFileOpen

s3eFileClose

Required Header Files
s3eFile.h


Airplay API Reference: S3E File IO Examples

Airplay API Reference > S3E API Documentation > S3E File > S3E File IO Examples >

S3E File IO Examples

This section illustrates how you can use the File IO functionality provided by S3E. This section contains one example application:

  • S3E File IO Basic Example

Note: For more information on using the S3E IO functionality, see the S3E File Overview.


Airplay API Reference: S3E File IO Basic Example

Airplay API Reference > S3E API Documentation > S3E File > S3E File IO Examples > S3E File IO Basic Example >

S3E File IO Basic Example

This application opens an existing file and reads it in.

The main functions used to achieve this are:

  • s3eFileOpen()
  • s3eFileRead()
  • s3eFileWrite()
  • s3eMallocBase()
  • memset()
This application demonstrates how to use the S3E file management functionality. The application lets you open the original file by pressing 1 and read the file by pressing 2. You can close the opened file by pressing 3.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

enum FileIO
{
    kOpen,
    kRead,
    kReset,
    kError
};

#define FILENAME "old.txt"                  // name of file which is to be operated on

static FileIO      g_Status = kReset;              // Statemachine for file operation
static s3eFile*    g_FileHandle;                   // Handle to file which is to be operated on
static char        g_ErrorString[256];             // Contains info about errors for displaying purposes
static char*       g_DataToBeRead;                 // Data which is being kRead from the file
static int         g_ColourSpecifier;
static Button*     g_ButtonOpen = NULL;
static Button*     g_ButtonRead = NULL;
static Button*     g_ButtonClose = NULL;

void ExampleInit()
{
    g_ButtonOpen = NewButton("Open");
    g_ButtonRead = NewButton("Read");
    g_ButtonClose = NewButton("Close");
}

void ExampleShutDown()
{
    s3eFreeBase((void*)g_DataToBeRead);
}

//-----------------------------------------------------------------------------
// The following function checks the keyboard state and performs a number of
// operations based on it. The options are:
// <ul>
//  <li>If s3eKey1 is pressed, the specified file is opened for reading.
//  <li>If s3eKey2 is pressed, data is read from the opened file.
//  <li>If s3eKey3 is pressed, the file is closed.
// </ul>
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if ((pressed == g_ButtonOpen) && (g_Status == kReset))
    {
        //Open file for reading
        g_FileHandle = s3eFileOpen(FILENAME, "r");

        if (g_FileHandle != NULL)
        {
            //No error has occurred
            g_Status = kOpen;
        }
        else
        {
            // Something went wrong during opening of the file
            // retrieve error for display
            g_Status = kError;
            s3eFileGetError();
            strcpy(g_ErrorString, s3eFileGetErrorString());
        }
    }

    if ((pressed == g_ButtonRead) && (g_Status == kOpen))
    {
        // Clear Buffer to make sure space is not allocated more than once
        s3eFreeBase((void*)g_DataToBeRead);

        g_ColourSpecifier = strlen("`x666666");

        // Allocate buffer to be filled with the files contents
        int32 fileSize = s3eFileGetSize(g_FileHandle);
        g_DataToBeRead = (char*)s3eMallocBase(fileSize+g_ColourSpecifier+1);
        memset(g_DataToBeRead, 0, fileSize+g_ColourSpecifier);
        strcpy(g_DataToBeRead, "`x666666");

        // Read data from file
        if (s3eFileRead(&g_DataToBeRead[g_ColourSpecifier], fileSize, 1, g_FileHandle) != 1)
        {
            // An kError has occurred, retrieve information for display
            g_Status = kError;
            s3eFileGetError();
            strcpy(g_ErrorString, s3eFileGetErrorString());
        }
        else
        {
            // Data reading has been successful
            g_DataToBeRead[fileSize+g_ColourSpecifier] = '\0';
            g_Status = kRead;
        }
    }

    if ((pressed == g_ButtonClose) && ((g_Status == kOpen) || (g_Status == kRead)))
    {
        // Make sure file has been opened before trying to close it
        if (g_FileHandle)
            s3eFileClose(g_FileHandle);
        g_Status = kReset;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs any errors that have occurred and the
// state of the File System.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int ypos = GetYBelowButtons() + 2 * textHeight;

    switch (g_Status)
    {
        case kReset:
            g_ButtonOpen->m_Enabled = true;
            g_ButtonRead->m_Enabled = false;
            g_ButtonClose->m_Enabled = false;
            break;
        case kOpen:
            g_ButtonOpen->m_Enabled = false;
            g_ButtonRead->m_Enabled = true;
            g_ButtonClose->m_Enabled = true;
            s3eDebugPrint(10, ypos, "`x666666File Opened: " FILENAME, 0);
            break;
        case kRead:
            g_ButtonOpen->m_Enabled = false;
            g_ButtonRead->m_Enabled = true;
            g_ButtonClose->m_Enabled = true;
            s3eDebugPrint(10, ypos, "`x666666File Read, Contents are:", 0);
            ypos = ypos + textHeight * 2;
            s3eDebugPrint(10, ypos, g_DataToBeRead, 1);
            break;
        case kError:
            g_ButtonOpen->m_Enabled = false;
            g_ButtonRead->m_Enabled = false;
            g_ButtonClose->m_Enabled = false;
            s3eDebugPrint(10, ypos, "`x666666Error", 0);
            ypos = ypos + textHeight * 2;
            s3eDebugPrint(10, ypos, g_ErrorString, 1);
            break;
    }
}


Airplay API Reference: S3E GL

Airplay API Reference > S3E API Documentation > S3E GL >

S3E GL

The S3E GL documentation contains the following sections:

  • S3E GL Overview
  • GL API Reference


Airplay API Reference: S3E GL Overview

Airplay API Reference > S3E API Documentation > S3E GL > S3E GL Overview >

S3E GL Overview

The GL Module provides an API to aid in setting up OpenGLES under S3E. The functionality provided in this API allows you to query properties of OpenGLES, such as the current version. It also allows you to retrieve details of any errors that have occurred while using OpenGLES.

Note: For more information on the functionality outlined in this section, see the GL API Reference.


Airplay API Reference: GL API Reference

Airplay API Reference > S3E API Documentation > S3E GL > GL API Reference >

GL API Reference
[S3E]

Enumerations

enum | s3eGLError
enum s3eGLProperty {
S3E_GL_VERSION = 0,
S3E_EGL_VERSION = 1
}

Functions

S3E_API s3eGLError | s3eGLGetError ()
S3E_API const char * | s3eGLGetErrorString ()
S3E_API int32 | s3eGLGetInt (s3eGLProperty property)
S3E_API void * | s3eGLGetNativeWindow ()

Detailed Description

For more information on the GL functionality provided by the S3E module, see the S3E GL section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eGLError

GL Errors.

See also:
s3eGLGetError

s3eGLGetErrorString

Required Header Files
s3eGL.h
Enumerator:
S3E_GL_ERR_NONE | No Error.
S3E_GL_ERR_PARAM | Invalid paramater.
S3E_GL_ERR_UNAVAIL | GL is unavailable.

enum s3eGLProperty

GL Properties.

Required Header Files
s3eGL.h
Enumerator:
S3E_GL_VERSION | Returns the current GL version in the form 0xMMNN where MM is the major version and NN is the minor version. Querying this will return 0 if GL is not available.
S3E_EGL_VERSION | Returns the current EGL version in the form 0xMMNN where MM is the major version and NN is the minor version. Querying this will return 0 if EGL is not available.

Function Documentation

S3E_API s3eGLError s3eGLGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eGLGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eGL.h

S3E_API const char* s3eGLGetErrorString ( )

Retrieve the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eGLGetError
Remarks:
This function, as opposed to s3eGLGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eGL.h

S3E_API int32 s3eGLGetInt ( s3eGLProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 if property is not valid.
    Call s3eFileGetError() to retrieve an error code. This will return:
    S3E_GL_ERR_PARAM if property is not valid.

S3E_API void* s3eGLGetNativeWindow ( )

Returns a pointer that is suitable for conversion to NativeWindowType in OpenGLES.

Returns:
If GL is supported, a non-NULL GL NativeWindowType abstract handle, NULL otherwise. If NULL is returned, the next call to s3eGLGetError() will return S3E_GL_ERR_UNAVAIL.
Remarks:
The value returned can be used as the NativeWindowType in a call to eglCreateWindowSurface which is the recommended way of creating an OpenGLES rendering surface under S3E.
Required Header Files
s3eGL.h


Airplay API Reference: S3E Keyboard

Airplay API Reference > S3E API Documentation > S3E Keyboard >

S3E Keyboard

The S3E Keyboard documentation contains the following sections:

  • S3E Keyboard Overview
  • Keyboard API Reference


Airplay API Reference: S3E Keyboard Overview

Airplay API Reference > S3E API Documentation > S3E Keyboard > S3E Keyboard Overview >

S3E Keyboard Overview

The Keyboard Module provides abstraction from the device keyboard. This module provides a mechanism to query the state of any key on the device keyboard.

Updating and Querying Key States

s3eKeyboardGetState() will return the state of a particular key from S3E's internal state buffer. s3eKeyboardUpdate() will update S3E's internal state buffer from the device keyboard. It records which keys were down at the time s3eKeyboardUpdate() was called as well as which keys were pressed since the previous call to s3eKeyboardUpdate() (these two may be different). In a normal application loop, the application calls s3eKeyboardUpdate() once per frame to obtain input state, followed by s3eKeyboardGetState() for all the keys that are application controls.

It is recommended that you call s3eKeyboardUpdate() once per application loop. Successive calls to this function will result in the overwriting of the keyboard state and thus key presses may be lost if the update function is called repeatedly between checking the state.

Key Codes and Availability

All parameters and return types for the S3E keyboard functions are of the s3eKey type. These are enum integers representing all the keys that Airplay supports across on all devices. Most devices will only support a subset of them. s3eKeyboardGetInt(s3eKeyboardProperty) can be used to query properties of the keyboard on the device, for example using S3E_KEYBOARD_HAS_ALPHA to find out if the device supports alpha keys.

Character Input

Airplay supports reading keyboard character input through s3eKeyboardGetChar(). This differs from s3eKeyboardGetState() in that the key state functionality provides information on the state of a physical key while the character functionality returns characters that key presses will logically have generated. For example, when inputting text on most devices with a full ("qwerty") keyboard, a single key-press can be combined with function key presses to produce one of various characters. s3eKeyboardGetState() will register both the press and release of both the regular key and any function key that was pressed. At the same time, Airplay will buffer the logical characters that these presses will have generated and subsequent calls to s3eKeyboardGetChar() will return each character as a wide char until the buffer is empty (at which point it will return WEOF). This should be used for reading-in text for on-screen input controls as opposed to discreet key presses to perform commands.

Whether the application can check for character input via s3eKeyboardGetChar() can be checked with s3eKeyboardGetInt(S3E_KEYBOARD_GET_CHAR). Similarly, this functionality can be enabled/disabled via s3eKeyboardSetInt(S3E_KEYBOARD_GET_CHAR). On some devices this may enable/disable a specific visual interface for this purpose; see the Keyboard API Reference for more information.

Abstract Keys

It is possible to override the key mappings used for an application. Airplay provides this functionality through Abstract Keys, which can be mapped to any available regular key code.

Abstract keys are by default mapped to the most sensible physical keys available, which will vary between devices. For example, s3eKeyAbsUp will usually map to s3eKeyUp which will be the "up" direction key. s3eKeyAbsASK (Accept Soft Key) will map to the key on the device which is usually used for "accept" commands, for example the left soft key on most Nokia devices or right softkey on most BREW devices. To override the defaults, use the relevant ICF Settings as described below. Keys are specified in the ICF without the s3eKey prefix, for example "AbsGameA=W" will set the state of s3eKeyAbsGameA to be set whenever s3eKeyW is pressed.

The following abstract keys are available:

  • s3eKeyAbsGameA: Abstract Game key A. ICF setting: AbsGameA
  • s3eKeyAbsGameB: Abstract Game key B. ICF setting: AbsGameB
  • s3eKeyAbsGameC: Abstract Game key C. ICF setting: AbsGameC
  • s3eKeyAbsGameD: Abstract Game key D. ICF setting: AbsGameD
  • s3eKeyAbsUp: Abstract Up. ICF setting: AbsUp
  • s3eKeyAbsDown: Abstract Down. ICF setting: AbsDown
  • s3eKeyAbsLeft: Abstract Left. ICF setting: AbsLeft
  • s3eKeyAbsRight: Abstract Right. ICF setting: AbsRight
  • s3eKeyAbsOk: Abstract Ok. ICF setting: AbsOK
  • s3eKeyAbsASK: Abstract forwards softkey. ICF setting: AbsASK
  • s3eKeyAbsBSK: Abstract backwards softkey. ICF setting: AbsBSK

A second set of key codes and icf settings - of the format s3eKeyAbsGameA2, s3eKeyAbsGameB2, s3eKeyAbsUp2, etc. - is also available. These allow for another key to also be mapped to the same abstract key so that, for example, on a device with both Enter and OK keys they could both be mapped to produce a press of s3eKeyAbsOk.

Abstract Keys in the Windows Emulator

The Airplay Windows emulator, as default, has the abstract keys mapped as follows:

  • s3eKeyAbsGameA: s3eKey5
  • s3eKeyAbsGameB: s3eKey6
  • s3eKeyAbsGameC: s3eKey8
  • s3eKeyAbsGameD: s3eKey9
  • s3eKeyAbsUp: s3eKeyUp
  • s3eKeyAbsDown: s3eKeyDown
  • s3eKeyAbsLeft: s3eKeyLeft
  • s3eKeyAbsRight: s3eKeyRight
  • s3eKeyAbsOk: s3eKeyF2
  • s3eKeyAbsASK: s3eKeyF1
  • s3eKeyAbsBSK: s3eKeyF3

Note: For more information on the functionality outlined in this section, see the Keyboard API Reference.


Airplay API Reference: Keyboard API Reference

Airplay API Reference > S3E API Documentation > S3E Keyboard > Keyboard API Reference >

Keyboard API Reference
[S3E]

Data Structures

struct | s3eKeyboardCharEvent
struct | s3eKeyboardEvent

Defines

#define | S3E_KEY_STATE_DOWN (1<<0)
#define | S3E_KEYBOARD_DISP_LENGTH 16

Enumerations

enum | s3eKey
enum s3eKeyboardCallback {
S3E_KEYBOARD_KEY_EVENT = 0,
S3E_KEYBOARD_CHAR_EVENT = 1
}
enum | s3eKeyboardError
enum | s3eKeyboardNumpadOrientation
enum s3eKeyboardProperty {
S3E_KEYBOARD_HAS_NUMPAD = 0,
S3E_KEYBOARD_HAS_ALPHA = 1,
S3E_KEYBOARD_HAS_DIRECTION = 2,
S3E_KEYBOARD_NUMPAD_ORIENTATION = 3,
S3E_KEYBOARD_GET_CHAR = 4
}

Functions

S3E_API s3eKey | s3eKeyboardAnyKey ()
S3E_API void | s3eKeyboardClearState ()
S3E_API s3eWChar | s3eKeyboardGetChar ()
S3E_API s3eResult | s3eKeyboardGetDisplayName (char *dst, s3eKey key, s3eBool terminateString=(1))
S3E_API s3eKeyboardError | s3eKeyboardGetError ()
S3E_API const char * | s3eKeyboardGetErrorString ()
S3E_API int32 | s3eKeyboardGetInt (s3eKeyboardProperty property)
S3E_API int32 | s3eKeyboardGetState (s3eKey key)
S3E_API s3eResult | s3eKeyboardRegister (s3eKeyboardCallback cbid, s3eCallback fn, void *userdata)
S3E_API s3eResult | s3eKeyboardSetInt (s3eKeyboardProperty property, int32 value)
S3E_API s3eResult | s3eKeyboardUnRegister (s3eKeyboardCallback cbid, s3eCallback fn)
S3E_API s3eResult | s3eKeyboardUpdate ()

Detailed Description

For more information on the Keyboard functionality provided by the S3E module, see the S3E Keyboard section of the S3E API Documentation.

Define Documentation

#define S3E_KEY_STATE_DOWN (1<<0)

All possible key states.

Required Header Files
s3eKeyboard.h

#define S3E_KEYBOARD_DISP_LENGTH 16

The maxmimum number of characters that can be returned by s3eKeyboardGetDisplayName().

Required Header Files
s3eKeyboard.h

Enumeration Type Documentation

enum s3eKey

All available raw key codes.

Required Header Files
s3eKeyboard.h
Enumerator:
s3eKeyFirst | Invalid Key.
s3eKeyEsc | Esc.
s3eKeyTab | Tab.
s3eKeyBackspace | Backspace.
s3eKeyEnter | Enter.
s3eKeyLeftShift | Left shift key.
s3eKeyLeftControl | Left control key.
s3eKeyReserved | Reserved, do not use.
s3eKeySpace | Key Space.
s3eKeyLeft | Key Left.
s3eKeyUp | Key Up.
s3eKeyRight | Key Right.
s3eKeyDown | Key Down.
s3eKey0 | Key 0 on phone/ Key 0 on main keyboard.
s3eKey1 | Key 1 on phone/ Key 1 on main keyboard.
s3eKey2 | Key 2 on phone/ Key 2 on main keyboard.
s3eKey3 | Key 3 on phone/ Key 3 on main keyboard.
s3eKey4 | Key 4 on phone/ Key 4 on main keyboard.
s3eKey5 | Key 5 on phone/ Key 5 on main keyboard.
s3eKey6 | Key 6 on phone/ Key 6 on main keyboard.
s3eKey7 | Key 7 on phone/ Key 7 on main keyboard.
s3eKey8 | Key 8 on phone/ Key 8 on main keyboard.
s3eKey9 | Key 9 on phone/ Key 9 on main keyboard.
s3eKeyA | Key A.
s3eKeyB | Key B.
s3eKeyC | Key C.
s3eKeyD | Key D.
s3eKeyE | Key E.
s3eKeyF | Key F.
s3eKeyG | Key G.
s3eKeyH | Key H.
s3eKeyI | Key I.
s3eKeyJ | Key J.
s3eKeyK | Key K.
s3eKeyL | Key L.
s3eKeyM | Key M.
s3eKeyN | Key N.
s3eKeyO | Key O.
s3eKeyP | Key P.
s3eKeyQ | Key Q.
s3eKeyR | Key R.
s3eKeyS | Key S.
s3eKeyT | Key T.
s3eKeyU | Key U.
s3eKeyV | Key V.
s3eKeyW | Key W.
s3eKeyX | Key X.
s3eKeyY | Key Y.
s3eKeyZ | Key Z.
s3eKeyF1 | Key F1.
s3eKeyF2 | Key F2.
s3eKeyF3 | Key F3.
s3eKeyF4 | Key F4.
s3eKeyF5 | Key F5.
s3eKeyF6 | Key F6.
s3eKeyF7 | Key F7.
s3eKeyF8 | Key F8.
s3eKeyF9 | Key F9.
s3eKeyF10 | Key F10.
s3eKeyNumPad0 | Key 0 on keyboard numberpad.
s3eKeyNumPad1 | Key 1 on keyboard numberpad.
s3eKeyNumPad2 | Key 2 on keyboard numberpad.
s3eKeyNumPad3 | Key 3 on keyboard numberpad.
s3eKeyNumPad4 | Key 4 on keyboard numberpad.
s3eKeyNumPad5 | Key 5 on keyboard numberpad.
s3eKeyNumPad6 | Key 6 on keyboard numberpad.
s3eKeyNumPad7 | Key 7 on keyboard numberpad.
s3eKeyNumPad8 | Key 8 on keyboard numberpad.
s3eKeyNumPad9 | Key 9 on keyboard numberpad.
s3eKeyNumPadPlus | Plus key on keyboard numberpad.
s3eKeyNumPadMinus | Minus key on keyboard numberpad.
s3eKeyNumPadEnter | Enter key on keyboard numberpad.
s3eKeyRSK | Right soft key.
s3eKeyLSK | Left soft key.
s3eKeyLS | Left shoulder button.
s3eKeyRS | Right shoulder button.
s3eKeyHash | # Key.
s3eKeyStar | * Key (on keyboard numberpad for normal keyboards).
s3eKeyOk | Select key.
s3eKeyCLR | CLR key.
s3eKeyVolUp | Volume Up key.
s3eKeyVolDown | Volume Down key.
s3eKeyCamera | Camera button.
s3eKeyMic | Microphone button.
s3eKeyFn | Fn button.
s3eKeySym | Sym button.
s3eKeyAccept | call accept (talk).
s3eKeyEnd | call end (reject).
s3eKeyHomePage | Home key.
s3eKeyButton1 | Generic Button1.
s3eKeyButton2 | Generic Button2.
s3eKeyButton3 | Generic Button3.
s3eKeyButton4 | Generic Button4.
s3eKeyButton5 | Generic Button5.
s3eKeyButton6 | Generic Button6.
s3eKeyButton7 | Generic Button7.
s3eKeyButton8 | Generic Button8.
s3eKeyF11 | Key F11.
s3eKeyF12 | Key F12.
s3eKeyLeftAlt | Left Alt key.
s3eKeyRightControl | Right Control Key.
s3eKeyRightAlt | Right Alt Key.
s3eKeyRightShift | Right Shift Key.
s3eKeyBacktick | Backtick '`' Key.
s3eKeyComma | Comma ',' Key.
s3eKeyPeriod | Period '.' Key.
s3eKeySlash | Forward slash '/' Key.
s3eKeyBackSlash | Back slash '\' Key.
s3eKeySemicolon | Semicolon ';' Key.
s3eKeyApostrophe | Apostrophe (') Key.
s3eKeyLeftBracket | Left Bracket '[' Key.
s3eKeyRightBracket | Right Bracket ']' Key.
s3eKeyEquals | Equals '=' Key.
s3eKeyMinus | Minus '-' key on main keyboard.
s3eKeyCapsLock | Caps Lock key.
s3eKeyNumPadPeriod | Period '.' key on numberpad.
s3eKeyNumPadSlash | Slash '/' key on numberpad.
s3eKeyNumLock | NumLock key.
s3eKeyInsert | Insert key.
s3eKeyHome | Home key.
s3eKeyPageUp | Page Up key.
s3eKeyPageDown | Page Down key.
s3eKeyKbEnd | End key (on keyboard).
s3eKeyDelete | Delete key.
s3eKeyPause | Pause key.
s3eKeyAbsGameA | Abstract Game keyA.
s3eKeyAbsGameB | Abstract Game keyB.
s3eKeyAbsGameC | Abstract Game keyC.
s3eKeyAbsGameD | Abstract Game keyD.
s3eKeyAbsUp | Abstract Up.
s3eKeyAbsDown | Abstract Down.
s3eKeyAbsLeft | Abstract Left.
s3eKeyAbsRight | Abstract Right.
s3eKeyAbsOk | Abstract Ok.
s3eKeyAbsASK | Abstract action softkey.
s3eKeyAbsBSK | Abstract backwards softkey.

enum s3eKeyboardCallback

Keyboard Callbacks.

Required Header Files
s3eKeyboard.h
Enumerator:
S3E_KEYBOARD_KEY_EVENT Key event callback. This is called whenever a physical key is pressed or released.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This parameter points to a s3eKeyboardEvent structure, which contains the s3eKey enumeration of the key, and whether it was pressed or released.
Returns:
No return value is expected from a callback registered using this enumeration.
Remarks:
Note that this callback will only be called during s3eDeviceYield().
S3E_KEYBOARD_CHAR_EVENT High level charator code event callback. This called whenever a new logical character is generated. Many key presses can correspond to a single char event (e.g. SHIFT + FIVE on a UK keyboard would generate the unicode symbol for '')

enum s3eKeyboardError

Keyboard Errors.

Required Header Files
s3eKeyboard.h
Enumerator:
S3E_KEYBOARD_ERR_NONE | No Error.
S3E_KEYBOARD_ERR_PARAM | Invalid parameter.
S3E_KEYBOARD_ERR_TOO_MANY | Maximum number of callbacks exceeded .
S3E_KEYBOARD_ERR_ALREADY_REG | The specified callback is already registered.
S3E_KEYBOARD_ERR_NOT_FOUND | The specified callback was not found for removal.
S3E_KEYBOARD_ERR_UNAVAIL | The specified callback was not found for removal.
S3E_KEYBOARD_ERR_DEVICE | The underlying keyboard device failed.

enum s3eKeyboardNumpadOrientation

name Keyboard Functionality Possible orientations for the number pad. NORMAL is the normal configuration which means the first row of numbers (1, 2, 3) run across the top of the number pad from the users perspective. ROT90 means this row runs down right from the users perspective.

enum s3eKeyboardProperty

Keyboard Properties

Required Header Files
s3eKeyboard.h
Enumerator:
S3E_KEYBOARD_HAS_NUMPAD | [read] Returns 1 if the keyboard supports numeric keypad s3eKey0 ... s3eKey9, 0 otherwise.
S3E_KEYBOARD_HAS_ALPHA | [read] Returns 1 if the keyboard supports alphabetic keys s3eKeyA...s3eKeyZ, 0 otherwise.
S3E_KEYBOARD_HAS_DIRECTION | [read] Returns 1 if the keyboard supports directional controls s3eKeyUp, s3eKeyDown, s3eKeyLeft, s3eKeyRight and s3eKeyOk, 0 otherwise.
S3E_KEYBOARD_NUMPAD_ORIENTATION | [read] Returns the orientation of directional pad relative the way the user is holding the device. The retuned value will be a s3eKeyboardNumpadOrientation.
S3E_KEYBOARD_GET_CHAR | [read, write] Enable/disable whether the application can check for character input via s3eKeyboardGetChar(). 1 indicates that characters can be returned and 0 that they can not. On some devices this may enable/disable a specific interface for this purpose.

Function Documentation

S3E_API s3eKey s3eKeyboardAnyKey ( )

Queries if any key is pressed.

Returns:
0 if no key was pressed, otherwise returns the pressed key.
Remarks:
Does not update the key state buffer. If this is required, call s3eKeyboardUpdate() first.
Required Header Files
s3eKeyboard.h

S3E_API void s3eKeyboardClearState ( )

Clear the internal keyboard state. Use this if you want to ignore any key state currently held in the system. This only effects the polling API (s3eKeyboardGetState) and has no effect of keyboard events that are delivered as callbacks.

S3E_API s3eWChar s3eKeyboardGetChar ( )

Returns the next logical character generated by the keyboard device.

Returns:
The next logical character to be generated by the keyboard device or WEOF if there are no characters pending.

S3E_API s3eResult s3eKeyboardGetDisplayName | ( | char * | dst,
 |  | s3eKey | key,
 |  | s3eBool | terminateString = (1)
 | ) |  |

Get a short displayable name for a key.

Parameters:
dst | Destination string buffer.
key | Key to obtain string for.
terminateString | Whether or not to add a null terminator to the end of dst.
Remarks:
Caller must ensure that there is room at dst for S3E_KEYBOARD_DISP_LENGTH characters and terminator if required. If terminateString is false then the string will not be terminated.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eKeyboardGetError() to retrieve an error code. This will return one of:
    • S3E_KEYBOARD_ERR_PARAM if key is not a valid s3eKey
Required Header Files
s3eKeyboard.h

S3E_API s3eKeyboardError s3eKeyboardGetError ( )

Retrieves the last error, if any, for the Keyboard Device.

Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eKeyboard.h

S3E_API const char* s3eKeyboardGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eKeyboardError
Remarks:
This function, as opposed to s3eKeyboardGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eKeyboard.h

S3E_API int32 s3eKeyboardGetInt ( s3eKeyboardProperty property )

Retrieves an integer property for the Keyboard subdevice.

Parameters:
property The keyboard property to be queried.
Returns:
  • The value of the requested property if property is valid.
  • -1 if property is not valid.
    Call s3eKeyboardGetError() to retrieve an error code. This will return:
    S3E_KEYBOARD_ERR_PARAM if property is not valid.
See also:
s3eKeyboardSetInt
Required Header Files
s3eKeyboard.h

S3E_API int32 s3eKeyboardGetState ( s3eKey key )

Queries the state of a specified key.

Parameters:
key Key code to query.
Returns:
Key state flags as the bitwise OR of the relevant states. The possible bits that can be set are S3E_KEY_STATE_DOWN, S3E_KEY_STATE_PRESSED and S3E_KEY_STATE_RELEASED. This will be zero if the key is up and has not been pressed or released since the last call to s3eKeyboardUpdate. If key is invalid, this function will return zero and set error code S3E_KEYBOARD_ERR_PARAM.
See also:
s3eKeyboardUpdate
Required Header Files
s3eKeyboard.h

S3E_API s3eResult s3eKeyboardRegister | ( | s3eKeyboardCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userdata
 | ) |  |

Registers a callback for a given event. Registers a callback for a given event.

The available callback types are listed in s3eKeyboardCallback.

Parameters:
cbid | ID of the callback for which to register.
fn | callback function.
userdata | Value to pass to the userdata paramater of fn
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eKeyboardGetError() to retrieve an error code. This will return one of:
    • S3E_KEYBOARD_ERR_PARAM if callback is not a valid member of s3eKeyboardCallback or fn is NULL.
    • S3E_KEYBOARD_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_KEYBOARD_ERR_ALREADY_REG If (callback, fn) has already been registered.
Remarks:
This can be used with callback set to S3E_KEYBOARD_KEY_EVENT to register for key-event callbacks. See the documentation for S3E_KEYBOARD_KEY_EVENT for more information.
See also:
S3E_KEYBOARD_KEY_EVENT,
Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eKeyboardCallback enum.

It is not necessary to define a return value for any registered callback.

Required Header Files
s3eKeyboard.h

S3E_API s3eResult s3eKeyboardSetInt | ( | s3eKeyboardProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for the Keyboard subdevice.

Parameters:
property | Property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eKeyboardGetError() to retrieve an error code. This will return:
    • S3E_KEYBOARD_ERR_PARAM if property is invalid or value is invalid.
    • S3E_KEYBOARD_ERR_UNAVAIL if the keyboard device is not available.
See also:
s3eKeyboardGetInt
Required Header Files
s3eKeyboard.h

S3E_API s3eResult s3eKeyboardUnRegister | ( | s3eKeyboardCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eKeyboardGetError() to retrieve an error code. This will return one of:
    • S3E_KEYBOARD_ERR_PARAM if callback is not a valid member of s3eKeyboardCallback
    • S3E_KEYBOARD_ERR_NOT_FOUND if fn is not registered for callback callback
Remarks:
Use this with callback set to S3E_KEYBOARD_KEY_EVENT to unregister the key-event callback
Required Header Files
s3eKeyboard.h

S3E_API s3eResult s3eKeyboardUpdate ( )

Updates the keyboard device key states with the current states from the OS.

Required Header Files
s3eKeyboard.h


Airplay API Reference: S3E Licensing

Airplay API Reference > S3E API Documentation > S3E Licensing >

S3E Licensing

The S3E Licensing documentation contains the following sections:

  • S3E Licensing Overview
  • Licensing API Reference


Airplay API Reference: S3E Licensing Overview

Airplay API Reference > S3E API Documentation > S3E Licensing > S3E Licensing Overview >

S3E Licensing Overview

The S3E Licensing API provides functionality for checking whether or not a user has a valid license, whether or not they are in demo mode, or if they are using a subscription.

Note: For more information on the functionality outlined in this section, see the Licensing API Reference.


Airplay API Reference: Licensing API Reference

Airplay API Reference > S3E API Documentation > S3E Licensing > Licensing API Reference >

Licensing API Reference
[S3E]

Enumerations

enum | s3eLicenseError
enum | s3eLicenseProperty
enum | s3eLicenseStatus

Functions

S3E_API s3eResult | s3eLicenseBuy ()
S3E_API s3eLicenseError | s3eLicenseGetError ()
S3E_API const char * | s3eLicenseGetErrorString ()
S3E_API int32 | s3eLicenseGetInt (s3eLicenseProperty property)

Detailed Description

For more information on the Licensing functionality provided by the S3E module, see the S3E Licensing section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eLicenseError

License error enumeration.

Required Header Files
s3eLicense.h
Enumerator:
S3E_LICENSE_ERR_NONE | No Error.
S3E_LICENSE_ERR_PARAM | Invalid parameter.

enum s3eLicenseProperty

License Properties.

Required Header Files
s3eLicense.h
Enumerator:
S3E_LICENSE_USES_LEFT | How many uses remain.
S3E_LICENSE_EXPIRY_DATE | Expiry date of license if it's a date-expiry type.
S3E_LICENSE_MINS_LEFT | Minutes left of license if it's a time-expiry type.
S3E_LICENSE_STATUS | One of s3eLicenseStatus, the current license status.

enum s3eLicenseStatus

License status enumeration

Required Header Files
s3eLicense.h
Enumerator:
S3E_LICENSE_EXPIRED | License has expired/No license avaialable.
S3E_LICENSE_DEMO | Demo.
S3E_LICENSE_USECOUNT | Demo limited by Usage Count.
S3E_LICENSE_EXPIRYDATE | Demo limited by Expiry Date.
S3E_LICENSE_EXPIRYMINSUSE | Demo limited by Number of Minutes Use.
S3E_LICENSE_PURCHASE | User has purchased the application.
S3E_LICENSE_SUBSCRIPTION | User is subscribed.
S3E_LICENSE_UPGRADE | User has upgraded the application.
S3E_LICENSE_NONCOMMERCIAL | Not a commercial version.

Function Documentation

S3E_API s3eResult s3eLicenseBuy ( )

Attempts to buy a license for this application. Note that the return value indicates whether or not the user was offered the chance to buy, you need to recheck the license status to get the result of the transaction.

Required Header Files
s3eLicense.h

S3E_API s3eLicenseError s3eLicenseGetError ( )

Retrieves the last error, if any, for this License.

Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eLicense.h

S3E_API const char* s3eLicenseGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eLicenseGetError
Remarks:
This function, as opposed to s3eLicenseGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eLicense.h

S3E_API int32 s3eLicenseGetInt ( s3eLicenseProperty property )

Retrieves an integer property for this License


Airplay API Reference: S3E Location

Airplay API Reference > S3E API Documentation > S3E Location >

S3E Location

The S3E Location documentation contains the following sections:

  • S3E Location Overview
  • Location API Reference
  • S3E Location Examples


Airplay API Reference: S3E Location Overview

Airplay API Reference > S3E API Documentation > S3E Location > S3E Location Overview >

S3E Location Overview

The location API provides a means for exposing the device's current physical location as determined by Global Positioning System (GPS) hardware or other means available to the device.

Determining Device Location

To determine if a device supports location functionality, call s3eLocationAvailable().

Location functionality is started and stopped using s3eLocationStart() and s3eLocationStop(). The GPS hardware is disabled on application start-up. Calling s3eLocationStart() will start the hardware if it is available. If no such hardware is available it may initialise an alternative implementation such as retrieving a position estimate from the currently connected network if the device supports this. Callbacks will then occur whenever the location changes, until s3eLocationStop() is called, at which point the hardware will be disabled again.

Location information is represented using the s3eLocation structure which contains latitude, longitude, altitude, accuracy and timestamp information. To obtain the current location, a pointer to a instance of an s3eLocation struct should be passed to s3eLocationGet(). Any information that the device cannot provide will be set to zero. The location can be polled for or a callback function can be registered using the S3E_LOCATION_CALLBACK_UPDATE callback. This will be called whenever the device determines that the location has changed and s3eLocationGet() can then be used to determine the new location.

Power Consumption

GPS hardware is one of the largest consumers of power on many devices and excessive usage should therefore be avoided. Calling s3eLocationStart() and s3eLocationStop() will start and stop the GPS hardware. Ideally, s3eLocationStart() should be called just before requesting location information is called and s3eLocationStop() called directly afterwards. There may however be a delay between calling s3eLocationStart() and the first location data becoming available. A balance between conserving power and a fast responsive time from the hardware should be struck based on the applications requirements.

Note: For an example of how the Location functionality can be used, see the S3E Location Examples.

For more information on the functionality outlined in this section, see the Location API Reference.


Airplay API Reference: Location API Reference

Airplay API Reference > S3E API Documentation > S3E Location > Location API Reference >

Location API Reference
[S3E]

Data Structures

struct | s3eLocation

Functions

S3E_BEGIN_C_DECL s3eBool | s3eLocationAvailable ()
s3eResult | s3eLocationGet (s3eLocation *location)
s3eResult s3eLocationStart ()
s3eResult s3eLocationStop ()

Detailed Description

Provides an api for exposing the device's current physical location as determined by GPS or other means.

Function Documentation

S3E_BEGIN_C_DECL s3eBool s3eLocationAvailable ( )

Returns S3E_TRUE if Location is available.

s3eResult s3eLocationGet ( s3eLocation * location )

Gets the current location.

Parameters:
location Pointer to location information.
Remarks:
s3eLocationStart must be called before this function can succeed.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
Required Header Files
s3eExt_Location.h

s3eResult s3eLocationStart ( )

Starts the location service (GPS, or other location device) if it is available. This function must be called before using s3eLocationGet to retrieve location information.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
Required Header Files
s3eExt_Location.h

s3eResult s3eLocationStop ( )

Stop the location service (GPS). All calls to s3eLocationGet will fail after calling this function.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
s3eExt_Location Header Files
s3eAccelerometer.h

Variable Documentation

double s3eLocation::m_Altitude [inherited]

Altitude at this location, in metres.

double s3eLocation::m_HorizontalAccuracy [inherited]

Accuracy of m_Latitude & m_Longitude in metres, negative means unavalaible.

double s3eLocation::m_Latitude [inherited]

Latitude at this location, in degrees. Positive numbers represent degrees East, negative numbers represent degrees West.

double s3eLocation::m_Longitude [inherited]

Longitude at this location, in degrees. Positive numbers represent degrees North, negative numbers represent degrees South.

double s3eLocation::m_VerticalAccuracy [inherited]

Accuracy of m_Altitude in metres, negative means unavalaible.


Airplay API Reference: S3E Location Examples

Airplay API Reference > S3E API Documentation > S3E Location > S3E Location Examples >

S3E Location Examples

This section illustrates how you can use the Location functionality provided with S3E. This section contains one example application:

  • S3E Location Example

Note: For more information on the S3E Location functionality, see the S3E Location Overview.


Airplay API Reference: S3E Location Example

Airplay API Reference > S3E API Documentation > S3E Location > S3E Location Examples > S3E Location Example >

S3E Location Example

The following example uses S3E's Location API to display the user's current lattitude, longitude and altitude. It also displays the accuracy of the location in meters.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3e.h"
#include "s3eLocation.h"

static s3eLocation g_Location;
static s3eResult g_Error = S3E_RESULT_ERROR;

void ExampleInit()
{
    s3eLocationStart();
}

void ExampleShutDown()
{
    s3eLocationStop();
}

bool ExampleUpdate()
{
    g_Error = s3eLocationGet(&g_Location);

    if (g_Error != S3E_RESULT_SUCCESS)
    {
        g_Location.m_Latitude = 51;
        g_Location.m_Longitude = -0.1;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function displays the current time.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int   textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int         y = 50;
    char        buf[256];

    if (g_Error == S3E_RESULT_ERROR)
    {
        s3eDebugPrint(10, y, "`x666666Could not determine location!", 0);
        return;
    }

    snprintf(buf, sizeof(buf), "`x666666Latitude %f", (float)g_Location.m_Latitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666Longitude %f", (float)g_Location.m_Longitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666Altitude %f", (float)g_Location.m_Altitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666H accuracy %f", (float)g_Location.m_HorizontalAccuracy);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666V accuracy %f", (float)g_Location.m_VerticalAccuracy);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;
}


Airplay API Reference: S3E Memory

Airplay API Reference > S3E API Documentation > S3E Memory >

S3E Memory

The S3E Memory documentation contains the following sections:

  • S3E Memory Overview
  • Memory API Reference
  • S3E Memory Examples


Airplay API Reference: S3E Memory Overview

Airplay API Reference > S3E API Documentation > S3E Memory > S3E Memory Overview >

S3E Memory Overview

The Memory Module provides memory management functionality. It allows you to query the amount of memory that is free, and lets you allocate, reallocate or free memory. The Memory Module provides error feedback on its memory management, and it also allows you to set the memory allocation mode. There are two main modes:

  • S3E_MEMORY_ALLOC_MODE_DEFAULT
  • S3E_MEMORY_ALLOC_MODE_COLLAPSIBLE

The first allocation mode, the default mode, should be used to allocate data for persistent objects that will be used throughout an application. The second allocation mode, the collapsible mode, should be used to allocate memory for objects that have only a limited use within the application. That way when OS memory is required you can collapse the collapsible memory and hand back what remains to the OS. The Memory Module callback mechanism allows you to register or unregister functions that will be called when the s3eMalloc(), s3eRealloc() and s3eFree() functions are used. The ability to do this means you can install a custom memory manager layered on top of the one provided by S3E. Callbacks can be set using the s3eMemorySetUserMemMgr() function.

S3E Memory provides a useful mechanism to avoid fragmentation:

  • Memory Heaps

Note: For an example of how the Memory functionality can be used, see the S3E Memory Examples.

For more information on the functionality outlined in this section, see the Memory API Reference.

Memory Heaps

The memory heap configuration settings are placed in the ICF file settings. The memory heap settings go in the [S3E] configuration group ([CORE] will work too, but this has been deprecated).

The user can create up to S3E_MEMORY_MAX_HEAPS(8) different memory heaps. Most applications will want to use only one or two heaps. The size of each heap is specified using the MemSize<x> = <size> icf setting, where x is the heap number (0-7) and <size> is the desired size of that heap. If MemSize<x> is not present for a heap or <size> is zero then the heap is not created. The exception to this is heap 0. If no heap is specifically defined, heap 0 will be created with a default size of 4Mb on Device or 10Mb on Windows/Linux.

To switch between different heaps, use s3eMemorySetInt(S3E_MEMORY_HEAP, x) in the user application. Subsequent allocations will come from the selected heap. There is no need to switch back to the correct heap to free or reallocate a memory block; s3eFree/s3eRealloc will always free/realloc from the appropriate heap.

MemSize = <size> 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> = <flag>

where <x> is the heap and the specified flags 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 heap is to be used in a purely stack based fashion (first alloced is last freed).
  • INACTIVE: Prevents the heap from being initially created and 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.


Airplay API Reference: Memory API Reference

Airplay API Reference > S3E API Documentation > S3E Memory > Memory API Reference >

Memory API Reference
[S3E]

Data Structures

struct | s3eMemoryUsrMgr

Defines

#define | S3E_MEMORY_MAX_HEAPS 8

Enumerations

enum | s3eMemoryError
enum s3eMemoryProperty {
S3E_MEMORY_HEAP = 0,
S3E_MEMORY_SIZE = 1,
S3E_MEMORY_FREE = 2,
S3E_MEMORY_USED = 3,
S3E_MEMORY_LFB = 4,
S3E_MEMORY_FLAGS = 5
}

Functions

S3E_API void | s3eFree (void *item)
S3E_API void | s3eFreeBase (void *item)
S3E_API void * | s3eMalloc (int size)
S3E_API void * | s3eMallocBase (int size)
S3E_API s3eMemoryError | s3eMemoryGetError ()
S3E_API const char * | s3eMemoryGetErrorString ()
S3E_API int32 | s3eMemoryGetInt (s3eMemoryProperty property)
S3E_API s3eResult | s3eMemoryGetUserMemMgr (s3eMemoryUsrMgr *callbacks)
S3E_API void * | s3eMemoryHeapAddress (int32 heapID)
S3E_API s3eResult | s3eMemoryHeapCreate (int32 heapID)
S3E_API s3eResult | s3eMemoryHeapDestroy (int32 heapID, s3eBool failIfNotEmpty)
S3E_API s3eResult | s3eMemorySetInt (s3eMemoryProperty property, int32 value)
S3E_API s3eResult | s3eMemorySetUserMemMgr (s3eMemoryUsrMgr *callbacks)
S3E_API void * | s3eRealloc (void *item, int newSize)
S3E_API void * | s3eReallocBase (void *item, int newSize)

Detailed Description

For more information on the Memory functionality provided by the S3E module, see the S3E Memory section of the S3E API Documentation.

Define Documentation

#define S3E_MEMORY_MAX_HEAPS 8

The maximum number of heaps that can be created via the icf file settings

Required Header Files
s3eMemory.h

Enumeration Type Documentation

enum s3eMemoryError

Memory Errors.

See also:
s3eMemoryGetError

s3eMemoryGetErrorString

Required Header Files
s3eMemory.h
Enumerator:
S3E_MEMORY_ERR_NONE | No Error.
S3E_MEMORY_ERR_PARAM | Invalid parameter.
S3E_MEMORY_ERR_UNAVAIL | memory support is unavailable or feature is not supported.
S3E_MEMORY_ERR_INVALID_PTR | Invalid pointer passed to free.
S3E_MEMORY_ERR_NO_MEM | Out of memory.
S3E_MEMORY_ERR_INVALID_STATE | Heap is already created when attempting to create, or already destroyed when attempting to destroy.

enum s3eMemoryFlags

Enumerator:
S3E_MEMORY_NO_MSG_ON_FAIL Do not display an error message if a memory allocation fails in this heap.
S3E_MEMORY_USE_STACK_ALLOCATOR Use a simple stack based allocator instead of the default allcator.
The stack based allocator allocates the heap from the bottom up. It maintains a free heap pointer that increases with each allocation. The free heap pointer only decreases if the memory block below it is free. Use this flag if s3eMallocBase if you plan to allocate the heap in a few large chunks e.g. when using a custom memory allocator. It will prevent memory wastage caused by the default allocator's division of memory allocations for small and large blocks.
S3E_MEMORY_INACTIVE This heap is inactive
Specifying this setting in the icf file will cause the specified heap not to be created on startup. The heap will only be created when s3eMemoryHeapCreate() is called on the heap.
Any attempts to allocate from the heap will fail until s3eMemoryHeapCreate() is called. Once the user application is running, this flag indicates current the state of the heap.

enum s3eMemoryProperty

Memory Properties.

See also:
s3eMemoryGetInt

s3eMemorySetInt

Required Header Files
s3eMemory.h
Enumerator:
S3E_MEMORY_HEAP [read,write] Gets/Sets the current heap. The user can create multiple heaps using the following settings in the icf file:
 [S3E] MemSize<x> = <size>
Setting the current heap will cause future memory allocations from s3eMallocBase and s3eReallocBase (and s3eMalloc and s3eRealloc if no user handler is installed) to come out of the specified heap.
s3eFreeBase/s3eFree can free a memory block from any heap, there is no need to set the correct heap to free memory
S3E_MEMORY_SIZE | [read] Returns the total size of the current heap
S3E_MEMORY_FREE | [read] Returns the total amount of free space left on the current heap
S3E_MEMORY_USED | [read] Returns heap size subtract free memory
S3E_MEMORY_LFB | [read] Returns the largest free block on the current heap, ie the largest possible allocation that will succeed.
S3E_MEMORY_FLAGS | [read] Returns the flags for the current heap. These will be one of more members of s3eMemoryFlags or'd together.

Function Documentation

S3E_API void s3eFree ( void * item )

Frees memory

Parameters:
item Pointer to memory region to free. If this is NULL, the function does nothing.
Remarks:
item must be a pointer returned from s3eMalloc or s3eRealloc or NULL By default this will free memory from the heap that allocated item (irrespective of the current heap setting), and behaves exactly as s3eFreeBase. However, if memory callbacks have been registered, the m_Free callback function will be called instead (even if item is NULL).
Required Header Files
s3eMemory.h

S3E_API void s3eFreeBase ( void * item )

Frees memory (bypassing callbacks)

Parameters:
item Pointer to memory region to free. If this is NULL, the function does nothing.
Remarks:
item must be a pointer returned from s3eMallocBase or s3eReallocBase or NULL This will free memory from the heap that allocated item (irrespective of the current heap setting).
Required Header Files
s3eMemory.h

S3E_API void* s3eMalloc ( int size )

Allocates memory

Parameters:
size Number of bytes to allocate
Returns:
  • A pointer to a memory area of at least size bytes if no error occurred
  • NULL if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_NO_MEM if the heap was unable to allocate the requested amount of memory
    • S3E_MEMORY_ERR_INVALID_STATE if the current heap has been destroyed or is not yet been created
Remarks:
By default this allocates memory from the current heap, and behaves exactly as s3eMallocBase. However, if memory callbacks have been registered, the m_Malloc callback function will be called instead. If the return value from the callback is NULL, the S3E_MEMORY_ERR_NO_MEM error code will be set.
Required Header Files
s3eMemory.h

S3E_API void* s3eMallocBase ( int size )

Allocates memory (bypassing callbacks)

Parameters:
size Number of bytes to allocate
Returns:
  • A pointer to a memory area of at least size bytes if no error occurred
  • NULL if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_NO_MEM if the heap was unable to allocate the requested amount of memory
    • S3E_MEMORY_ERR_INVALID_STATE if the current heap has been destroyed or is not yet been created
Remarks:
This allocates memory from the current heap. If memory cannot be allocated then an error dialog will be shown, unless the flag S3E_MEMORY_NO_MSG_ON_FAIL has been set on the current heap.
Required Header Files
s3eMemory.h

S3E_API s3eMemoryError s3eMemoryGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eMemoryGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eMemory.h

S3E_API const char* s3eMemoryGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eMemoryGetError
Remarks:
This function, as opposed to s3eMemoryGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eMemory.h

S3E_API int32 s3eMemoryGetInt ( s3eMemoryProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eMemoryGetError() to retrieve an error code. This will return:
    • S3E_MEMORY_ERR_PARAM if property is not valid.
See also:
s3eMemorySetInt
Required Header Files
s3eMemory.h

S3E_API s3eResult s3eMemoryGetUserMemMgr ( s3eMemoryUsrMgr * callbacks )

Retrieve the memory manager user callbacks.

Parameters:
callbacks Pointer to a structure to recieve the malloc, realloc and free function pointers.
Remarks:
If s3eMemorySetUserMemMgr has not yet been called or has been called with a NULL paramater (re-establishing the default callbacks), then the m_Malloc, m_Realloc and m_Free members of callbacks will be set to s3eMallocBase, s3eReallocBase and s3eFreeBase respectively.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_PARAM if callbacks is NULL.
Required Header Files
s3eMemory.h

S3E_API void* s3eMemoryHeapAddress ( int32 heapID )

Return the base address of the given heap.

Parameters:
heapID id of heap to query.
Returns:
  • the address at which the heap begins
  • NULL if the heap does not exist or is collapsed

S3E_API s3eResult s3eMemoryHeapCreate ( int32 heapID )

Creates the specified heap if it is inactive.

Parameters:
heapID id of inactive heap to create.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_PARAM for an invalid parameter condition: if heapID < 0 or heapID > S3E_MEMORY_MAX_HEAPS.
    • S3E_MEMORY_ERR_INVALID_STATE if heap heapID is already created.
Required Header Files
s3eMemory.h

S3E_API s3eResult s3eMemoryHeapDestroy | ( | int32 | heapID,
 |  | s3eBool | failIfNotEmpty
 | ) |  |

Destroys a heap and returns its memory to the operating system.

Parameters:
heapID | heap to destroy.
failIfNotEmpty | if this is S3E_FALSE the heap will be destroyed if memory blocks remain allocated from it. Otherwise the heap will only be destroyed if it is empty.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_PARAM if heapID < 0 or heapID > S3E_MEMORY_MAX_HEAPS.
    • S3E_MEMORY_ERR_NOT_EMPTY if heapID is not empty and failIfNotEmpty is S3E_TRUE.
    • S3E_MEMORY_ERR_INVALID_STATE if heapID has already been destroyed or is not yet created, or if failIfNotEmpty is S3E_TRUE and the heap is not empty.
Required Header Files
s3eMemory.h

S3E_API s3eResult s3eMemorySetInt | ( | s3eMemoryProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return:
    • S3E_MEMORY_ERR_PARAM if property is invalid or value is invalid.
Remarks:
Use this function with S3E_MEMORY_HEAP to change the active heap ID.
See also:
s3eMemoryGetInt
Required Header Files
s3eMemory.h

S3E_API s3eResult s3eMemorySetUserMemMgr ( s3eMemoryUsrMgr * callbacks )

Set the memory manager user callbacks.

Parameters:
callbacks The malloc, realloc and free function pointers.
Remarks:
callbacks May be NULL in which case the default memory allocator is reinstated; Otherwise, if either of m_Malloc, m_Realloc or m_Free is NULL the function will fail. This is separate to the normal callback registration procedure as all three functions must be defined simultaneously.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_PARAM if callbacks is non-NULL but one or more of m_Malloc, m_Realloc or m_Free is NULL.
Required Header Files
s3eMemory.h

S3E_API void* s3eRealloc | ( | void * | item,
 |  | int | newSize
 | ) |  |

Re-allocates memory

Parameters:
item | Pointer to memory region to reallocate. May be NULL
newSize | New size of memory region
Returns:
  • A pointer to a memory area of at least neSsize bytes if no error occurred
  • NULL if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_NO_MEM if the heap was unable to re-allocate the block to the requested size
    • S3E_MEMORY_ERR_INVALID_STATE if the current heap has been destroyed or is not yet been created
    • S3E_MEMORY_ERR_INVALID_PTR if item does not belong to any s3e heap and callbacks are not in place
Remarks:
item must be a pointer returned from s3eMalloc or s3eRealloc By default this reallocates memory from the heap that allocated item, (irrespective of the current heap setting) and behaves exactly as s3eReallocBase. However, if memory callbacks have been registered, the m_Realloc callback function will be called instead. If the return value from the callback is NULL, the S3E_MEMORY_ERR_NO_MEM error code will be set.
Required Header Files
s3eMemory.h

S3E_API void* s3eReallocBase | ( | void * | item,
 |  | int | newSize
 | ) |  |

Re-allocates memory (bypassing callbacks)

Parameters:
item | Pointer to memory region to reallocate. May be NULL
newSize | New size of memory region
Returns:
  • A pointer to a memory area of at least newSize bytes if no error occurred
  • NULL if the operation failed.
    Call s3eMemoryGetError() to retrieve an error code. This will return one of:
    • S3E_MEMORY_ERR_NO_MEM if the heap was unable to re-allocate the block to the requested size
    • S3E_MEMORY_ERR_INVALID_STATE if the current heap has been destroyed or is not yet been created
    • S3E_MEMORY_ERR_INVALID_PTR if item in non-NULL does not belong to any s3e heap
Remarks:
item must be a pointer returned from s3eMallocBase or s3eReallocBase or NULL. This reallocates memory from the heap that allocated item, (irrespective of the current heap setting) and behaves exactly as s3eReallocBase. If memory cannot be allocated then an error dialog will be shown, unless the flag S3E_MEMORY_NO_MSG_ON_FAIL has been set on the current heap.
Required Header Files
s3eMemory.h


Airplay API Reference: S3E Memory Examples

Airplay API Reference > S3E API Documentation > S3E Memory > S3E Memory Examples >

S3E Memory Examples

This section illustrates how you can use the Memory functionality provided by S3E. This section contains one example application:

  • S3E Memory Example

Note: For more information on the S3E Memory functionality, see the S3E Memory Overview.


Airplay API Reference: S3E Memory Example

Airplay API Reference > S3E API Documentation > S3E Memory > S3E Memory Examples > S3E Memory Example >

S3E Memory Example

The example application allows you to create up to two memory heaps by pressing s3eKey1. The application also allows you to upload a file multiple times to fill each heap, this can be done by pressing s3eKey3. You can swap between heaps by pressing s3eKey4. Finally, you can destroy each heap and free up the memory it uses by pressing s3eKey2.

The main functions used to achieve this are:

  • s3eMemoryHeapCreate()
  • s3eMemoryHeapDestroy()
  • s3eFree()
  • s3eMalloc()
  • s3eMemorySetInt()

This example application does not rely on the icf file to initialise a memory heap. Instead the icf file is used to define two memory heaps that will be created by the example application and used to allocate memory dynmaically. The possible heaps are listed in the ICF file as 0 and 1.

Each heap is defined using the MemSize<x> = <size> icf setting, which is placed under the [S3E] configuration group in the icf file. <x> defines the heap number, and <size> defines the size of the specified heap. The following is used in this examples icf:

 [S3E]
 MemSize0 = 6000000
 MemFlags0 = INACTIVE
 MemSize1 = 2000000
 MemFlags1 = INACTIVE

Note:
There can be a maximum of eight memory heaps.
In the example application the INACTIVE flag is attached to each heap, using the MemFlags<x> = <flag>..., to indicate that the heap should not be initialised on startup, but should only be created when the application makes a call to s3eMemoryHeapCreate().

It is good practice to free all the pointers that are present in a non-empty heap before you destroy it.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

char            g_ResultString[256];    // Stores operation results for displaying
int32           g_CurrentHeap;          // Keeps track which heap is currently used for operating on
int8            g_NumHeap;              // Keeps track of the number of created heaps

s3eMemoryError  g_MemError;             // Checks errors for displaying information

// list of pointers which are used for uploading files
void*           g_PtrList0[10];
void*           g_PtrList1[10];

// Indices into the pointer lists for uploading files
int16 g_Index0 = 0;
int16 g_Index1 = 0;

// File handle for file upload.
s3eFile* g_FileHandle;

Button* g_ButtonCreate = NULL;
Button* g_ButtonDelete = NULL;
Button* g_ButtonUpload = NULL;
Button* g_ButtonSwap = NULL;

void ExampleInit()
{
    g_CurrentHeap = 0;
    g_NumHeap = 0;
    g_MemError = S3E_MEMORY_ERR_NONE;

    g_FileHandle = s3eFileOpen("test.mp3", "rb");

    g_ButtonCreate  = NewButton("Create a new heap");
    g_ButtonDelete  = NewButton("Delete heap");
    g_ButtonUpload  = NewButton("Upload file");
    g_ButtonSwap    = NewButton("Swap heap");
}

void ExampleShutDown()
{
    s3eFileClose(g_FileHandle);
}

//-----------------------------------------------------------------------------
// The following function, based on which button was pressed, creates a new heap,
// destroys a heap, swaps between heaps, uploads a file
// to the selected heap.
//
// When the contents of a file are uploaded
// to a heap, the pointer to the position in memory where the file was
// loaded is stored in an array, which is kept so that the memory can be freed
// upon calling of s3eMemoryHeapDestroy().
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    // Reset error, so old errors don't get displayed any more
    g_MemError = S3E_MEMORY_ERR_NONE;

    //----------------------------
    // create a new heap
    //----------------------------
    if (pressed == g_ButtonCreate)
    {
        // In this example only one extra heap can be created
        if (g_NumHeap != 0)
        {
            sprintf(g_ResultString, "`x666666Maximum heap number reached");
            return true;
        }

        if (s3eMemoryHeapCreate (g_NumHeap+1) == S3E_RESULT_ERROR)
        {
            sprintf(g_ResultString, "`x666666Creating a new heap failed");
            g_MemError = s3eMemoryGetError();
        }
        else
        {
            g_NumHeap++;
            sprintf(g_ResultString, "`x666666Heap successfully created");
        }

        return true;
    }

    //----------------------------
    // destroy a heap
    //----------------------------
    if (pressed == g_ButtonDelete)
    {
        if (g_CurrentHeap == 0)
        {
            sprintf(g_ResultString, "`x666666Can't destroy heap 0");
            return true;
        }

        // In destroying a heap, each pointer in the relevant pointer
        // array and the memory it points to is freed using s3eFree().
        if (g_CurrentHeap == 1 && g_Index1 > 0)
        {
            while(g_Index1)
            {
                s3eFree(g_PtrList1[g_Index1]);
                g_Index1--;
            }
        }

        if (s3eMemoryHeapDestroy (g_CurrentHeap, true) == S3E_RESULT_SUCCESS)
        {
            sprintf(g_ResultString, "`x666666Heap destroying successful");
            g_NumHeap--;

            //Change displaying of active heap
            s3eMemorySetInt(S3E_MEMORY_HEAP, g_NumHeap);
        }
        else
        {
            sprintf(g_ResultString, "`x666666Error destroying Heap");
            g_MemError = s3eMemoryGetError();
        }
    }

    //----------------------------
    // upload a file
    //----------------------------
    if (pressed == g_ButtonUpload)
    {
        // Prepare data for uploading
        int32 fileSize = s3eFileGetSize(g_FileHandle);

        // Check for free heap space
        if (s3eMemoryGetInt (S3E_MEMORY_FREE) < fileSize)
        {
            sprintf(g_ResultString, "`x666666Not enough memory left");
            return true;
        }

        // Reserve memory for storing data
        void *ptr = s3eMalloc(fileSize);
        s3eFileRead (ptr, fileSize, 1, g_FileHandle);

        // Store data in heap
        if (g_CurrentHeap == 0)
        {
            g_Index0++;
            g_PtrList0[g_Index0] = ptr;
        }

        if (g_CurrentHeap == 1)
        {
            g_Index1++;
            g_PtrList1[g_Index1] = ptr;
        }

        sprintf(g_ResultString, "`x666666File uploaded correctly");
        return true;
    }

    //----------------------------
    // Press button to swap heap
    //----------------------------
    if (pressed == g_ButtonSwap)
    {
        if (g_NumHeap != 0)
            s3eMemorySetInt(S3E_MEMORY_HEAP, !g_CurrentHeap);
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs a set of strings describing the state of
// the heaps that have been created and the amount of memory that is free as
// well as the amount of memory that is in use.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    // Displaying Heap information
    g_CurrentHeap = s3eMemoryGetInt(S3E_MEMORY_HEAP);  // Current Heap
    int32 heapSize = s3eMemoryGetInt(S3E_MEMORY_SIZE); // Total size of the current heap
    int32 heapFree = s3eMemoryGetInt(S3E_MEMORY_FREE); // Total amount of free space left on the current heap
    int32 heapUsed = s3eMemoryGetInt(S3E_MEMORY_USED); // Free memory minus heap size
    int ypos = GetYBelowButtons() + 4 * textHeight;

    if (g_NumHeap != 0)
    {
        g_ButtonCreate->m_Enabled = false;
        g_ButtonDelete->m_Enabled = true;
        g_ButtonUpload->m_Enabled = true;
        g_ButtonSwap->m_Enabled = true;
    }
    else
    {
        g_ButtonCreate->m_Enabled = true;
        g_ButtonDelete->m_Enabled = false;
        g_ButtonUpload->m_Enabled = true;
        g_ButtonSwap->m_Enabled = false;
    }

    s3eDebugPrintf(10, ypos, 0, "`x666666Number Heaps : %i\nCurrent Heap : %ld\nHeap size    : %ld\nFree memory  : %ld\nUsed memory  : %ld",
                   g_NumHeap, g_CurrentHeap, heapSize, heapFree, heapUsed);

    ypos += 6 * textHeight;

    // Displaying error status
    s3eDebugPrint(10, ypos, g_ResultString, 1);

    ypos += 2 * textHeight;

    if (g_MemError != S3E_MEMORY_ERR_NONE)
    {
        switch (g_MemError)
        {
            case S3E_MEMORY_ERR_PARAM:          s3eDebugPrint(10, ypos, "`x666666S3E_MEMORY_ERR_PARAM", 0);         break;
            case S3E_MEMORY_ERR_INVALID_PTR:    s3eDebugPrint(10, ypos, "`x666666S3E_MEMORY_ERR_INVALID_PTR", 0);   break;
            case S3E_MEMORY_ERR_NO_MEM:         s3eDebugPrint(10, ypos, "`x666666S3E_MEMORY_ERR_NO_MEM", 0);            break;
            case S3E_MEMORY_ERR_INVALID_STATE:  s3eDebugPrint(10, ypos, "`x666666S3E_MEMORY_ERR_INVALID_STATE", 0); break;
            default:                            s3eDebugPrint(10, ypos, "`x666666S3E_MEMORY_ERR_UNKNOWN", 0);       break;
        }
    }
}


Airplay API Reference: S3E Pointer

Airplay API Reference > S3E API Documentation > S3E Pointer >

S3E Pointer

The S3E Pointer documentation contains the following sections:

  • S3E Pointer Overview
  • Pointer API Reference


Airplay API Reference: S3E Pointer Overview

Airplay API Reference > S3E API Documentation > S3E Pointer > S3E Pointer Overview >

S3E Pointer Overview

The Pointer Module provides the functionality to get and set pointer state information. The information that can be gained using the Pointer Module includes error feedback and pointer positioning.

Note: For more information on the functionality outlined in this section, see the Pointer API Reference.


Airplay API Reference: Pointer API Reference

Airplay API Reference > S3E API Documentation > S3E Pointer > Pointer API Reference >

Pointer API Reference
[S3E]

Data Structures

struct | s3ePointerEvent
struct | s3ePointerMotionEvent
struct | s3ePointerTouchEvent
struct | s3ePointerTouchMotionEvent

Enumerations

enum | s3ePointerButton
enum s3ePointerCallback {
S3E_POINTER_BUTTON_EVENT,
S3E_POINTER_MOTION_EVENT,
S3E_POINTER_TOUCH_EVENT,
S3E_POINTER_TOUCH_MOTION_EVENT
}
enum | s3ePointerError
enum s3ePointerProperty {
S3E_POINTER_AVAILABLE = 0,
S3E_POINTER_HIDE_CURSOR = 1,
S3E_POINTER_TYPE = 2,
S3E_POINTER_STYLUS_TYPE = 3,
S3E_POINTER_MULTI_TOUCH_AVAILABLE = 4
}
enum | s3ePointerState
enum | s3ePointerType
enum | s3eStylusType

Functions

S3E_API s3ePointerError | s3ePointerGetError ()
S3E_API const char * | s3ePointerGetErrorString ()
S3E_API int32 | s3ePointerGetInt (s3ePointerProperty property)
S3E_API s3ePointerState | s3ePointerGetState (s3ePointerButton button)
S3E_API int32 | s3ePointerGetX ()
S3E_API int32 | s3ePointerGetY ()
S3E_API s3eResult | s3ePointerRegister (s3ePointerCallback cbid, s3eCallback fn, void *userData)
S3E_API s3eResult | s3ePointerSetInt (s3ePointerProperty property, int32 value)
S3E_API s3eResult | s3ePointerUnRegister (s3ePointerCallback cbid, s3eCallback fn)
S3E_API s3eResult | s3ePointerUpdate ()

Detailed Description

For more information on the Pointer functionality provided by the S3E module, see the S3E Pointer section of the S3E API Documentation.

Enumeration Type Documentation

enum s3ePointerButton

Pointer buttons that can be queried via s3ePointerGetState.

Required Header Files
s3ePointer.h
Enumerator:
S3E_POINTER_BUTTON_SELECT | Tap on a touchpad, same as left mouse click.
S3E_POINTER_BUTTON_LEFTMOUSE | Left mouse click, same as tap on touchpad.
S3E_POINTER_BUTTON_RIGHTMOUSE | Right mouse click.
S3E_POINTER_BUTTON_MIDDLEMOUSE | Middle mouse click.
S3E_POINTER_BUTTON_MOUSEWHEELUP | Mouse wheel up.
S3E_POINTER_BUTTON_MOUSEWHEELDOWN | Mouse wheel down.
S3E_POINTER_BUTTON_MAX | Max number of buttons, keep as the last item.

enum s3ePointerCallback

Pointer Callbacks. The following callback types can be registered to enable user notification of pointer events.

See also:
s3ePointerRegister, s3ePointerUnRegister
Required Header Files
s3ePointer.h
Enumerator:
S3E_POINTER_BUTTON_EVENT This allows you to create callback is called whenever a pointer button event occurs.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData is a pointer to an s3ePointerEvent struct.
Returns:
No return value is expected from a callback registered using this enumeration.
S3E_POINTER_MOTION_EVENT | This event is triggered each time the underlying OS generates a pointer motions event.
S3E_POINTER_TOUCH_EVENT | Similar to S3E_POINTER_BUTTON_EVENT but only generated on multi-touch devices. Even on a multi-touch device regular S3E_POINTER_BUTTON_EVENT events are still generated for the first touch.
S3E_POINTER_TOUCH_MOTION_EVENT | Similar to S3E_POINTER_MOTION_EVENT but only generated on multi-touch devices. Even on a multi-touch device regular S3E_POINTER_MOTION_EVENT events are still generated for the first touch.

enum s3ePointerError

Pointer Errors.

See also:
s3ePointerGetError

s3ePointerGetErrorString

Required Header Files
s3ePointer.h
Enumerator:
S3E_POINTER_ERR_NONE | No Error.
S3E_POINTER_ERR_PARAM | Invalid parameter.
S3E_POINTER_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_POINTER_ERR_ALREADY_REG | The specified callback is already registered.
S3E_POINTER_ERR_NOT_FOUND | The specified callback was not found for removal.
S3E_POINTER_ERR_UNAVAIL | POINTER is unavailable.

enum s3ePointerProperty

Pointer Properties.

See also:
s3ePointerGetInt
Required Header Files:
s3ePointer.h
Enumerator:
S3E_POINTER_AVAILABLE | [read,int] Pointer is available on device
S3E_POINTER_HIDE_CURSOR | [read,write,int] Setting this to 1 will disable the cursor on system that have an OS/hardware cursor. Default is 0.
S3E_POINTER_TYPE | [read, int] Returns the type of pointer, one of s3ePointerType.
S3E_POINTER_STYLUS_TYPE | [read, int] If the pointer is a stylus, returns the type of stylus, one of s3eStylusType.
S3E_POINTER_MULTI_TOUCH_AVAILABLE | [read, int] Returns true if multitouch is avaliable.

enum s3ePointerState

All possible pointer button states.

Required Header Files
s3ePointer.h
Enumerator:
S3E_POINTER_STATE_UP | Pointer is up.
S3E_POINTER_STATE_DOWN | Pointer is down.
S3E_POINTER_STATE_PRESSED | Pointer was pressed between the last 2 calls to update states.
S3E_POINTER_STATE_RELEASED | Pointer was released between the last 2 calls to update states.
S3E_POINTER_STATE_UNKNOWN | Pointer's status is unknown , keep as the last item.

enum s3ePointerType

Describes the type of pointer used by the device.

See also:
s3ePointerProperty
Required Header Files:
s3ePointer.h

enum s3eStylusType

Describes the type of stylus.

See also:
s3ePointerProperty
Required Header Files:
s3ePointer.h

Function Documentation

S3E_API s3ePointerError s3ePointerGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3ePointerGetErrorString
Required Header Files
s3ePointer.h

S3E_API const char* s3ePointerGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3ePointerGetError
Required Header Files
s3ePointer.h

S3E_API int32 s3ePointerGetInt ( s3ePointerProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3ePointerGetError() to retrieve an error code. This will return:
    • S3E_POINTER_ERR_PARAM if property is not valid.
Required Header Files:
s3ePointer.h

S3E_API s3ePointerState s3ePointerGetState ( s3ePointerButton button )

Gets the current pointer state.

Required Header Files
s3ePointer.h

S3E_API int32 s3ePointerGetX ( )

Gets the current x position.

Required Header Files
s3ePointer.h

S3E_API int32 s3ePointerGetY ( )

Gets the current y position.

Required Header Files
s3ePointer.h

S3E_API s3eResult s3ePointerRegister | ( | s3ePointerCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Register a callback for a given event.

The available callback types are listed in s3ePointerCallback.

Parameters:
cbid | ID of the callback to unregister.
fn | Callback function.
userData | Value to pass to the userData parameter of fn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3ePointerGetError() to retrieve an error code. This will return one of:
    • S3E_POINTER_ERR_PARAM if cbid is not a valid member of s3ePointerCallback or fn is NULL.
    • S3E_POINTER_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
      • S3E_POINTER_ERR_ALREADY_REG If (cbid, fn) has already been registered.
See also:
s3ePointerUnRegister
Note:
It is not necessary to define a return value for any registered callback.
Required Header Files
s3ePointer.h

S3E_API s3eResult s3ePointerSetInt | ( | s3ePointerProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | property to set.
value | New value for property.
See also:
s3ePointerGetInt
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3ePointerGetError() to retrieve an error code. This will return:
    • S3E_FILE_ERR_PARAM if property is invalid or value is invalid.
Required Header Files
s3ePointer.h

S3E_API s3eResult s3ePointerUnRegister | ( | s3ePointerCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback to unregister.
fn | Callback function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3ePointerGetError() to retrieve an error code. This will return one of:
    • S3E_POINTER_ERR_PARAM if cbid is not a valid member of s3ePointerCallback, or fn is NULL.
      • S3E_POINTER_ERR_NOT_FOUND if fn is not registered for callback cbid.
See also:
s3ePointerRegister
Required Header Files
s3ePointer.h

S3E_API s3eResult s3ePointerUpdate ( )

Updates the pointer state and latches it.

Required Header Files
s3ePointer.h


Airplay API Reference: S3E Pointer Multi-Touch Example

Airplay API Reference > S3E API Documentation > S3E Pointer > S3E Pointer Examples > S3E Pointer Multi-Touch Example >

S3E Pointer Multi-Touch Example

The following example uses the S3E pointer functionality to display multiple touches to the screen if supported by the device.

The functions used to achieve this are:

  • s3ePointerRegister()
  • s3ePointerUnRegister()

A device with multi-touch support is required to take full advanctage of this example. The app draws a coloured circle under each contact point. If the device supports only one touch point at a time, then just one circle will be drawn.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "algorithm"

//Simple structure to track touches
struct CTouch
{
    int32 x; // position x
    int32 y; // position y
    bool active; // is touch active (currently down)
    int32 id; // touch's unique identifier
};

#define MAX_TOUCHES 10
CTouch g_Touches[MAX_TOUCHES];

//Colour to render touch in
uint8 g_TouchColours[3*MAX_TOUCHES] =
{
    0xff, 0x00, 0x00,
    0x00, 0xff, 0x00,
    0x00, 0x00, 0xff,
    0xff, 0x00, 0xff,
    0x00, 0xff, 0xff,
    0xff, 0xff, 0x00,
    0x80, 0x00, 0x00,
    0x00, 0x80, 0x00,
    0x00, 0x00, 0x80,
    0x80, 0x00, 0x80,
};

//Find an active touch with the specified id, or allocate a free one from the list
CTouch* GetTouch(int32 id)
{
    CTouch* pInActive = NULL;

    for(uint32 i = 0; i < MAX_TOUCHES; i++)
    {
        if( id == g_Touches[i].id )
            return &g_Touches[i];
        if( !g_Touches[i].active )
            pInActive = &g_Touches[i];
    }

    //Return first inactive touch
    if( pInActive )
    {
        pInActive->id = id;
        return pInActive;
    }

    //No more touches, give up.
    return NULL;
}

void MultiTouchButtonCB(s3ePointerTouchEvent* event)
{
    CTouch* pTouch = GetTouch(event->m_TouchID);
    if( pTouch )
    {
        pTouch->active = event->m_Pressed != 0;
        pTouch->x = event->m_x;
        pTouch->y = event->m_y;
    }
}

void MultiTouchMotionCB(s3ePointerTouchMotionEvent* event)
{
    CTouch* pTouch = GetTouch(event->m_TouchID);
    if( pTouch )
    {
        pTouch->x = event->m_x;
        pTouch->y = event->m_y;
    }
}

void SingleTouchButtonCB(s3ePointerEvent* event)
{
    g_Touches[0].active = event->m_Pressed != 0;
    g_Touches[0].x = event->m_x;
    g_Touches[0].y = event->m_y;
}

void SingleTouchMotionCB(s3ePointerMotionEvent* event)
{
    g_Touches[0].x = event->m_x;
    g_Touches[0].y = event->m_y;
}

void ExampleInit()
{
    // An OS which supports multi-touch will return TOUCH_EVENTs if they are registered for.
    // An OS which does not will only raise standard pointer events.
    if( s3ePointerGetInt(S3E_POINTER_MULTI_TOUCH_AVAILABLE) )
    {
        //Register for multi touch events on platforms where the functionality is available.
        s3ePointerRegister(S3E_POINTER_TOUCH_EVENT, (s3eCallback)MultiTouchButtonCB, NULL);
        s3ePointerRegister(S3E_POINTER_TOUCH_MOTION_EVENT, (s3eCallback)MultiTouchMotionCB, NULL);
    }
    else
    {
        //Register for standard pointer events
        s3ePointerRegister(S3E_POINTER_BUTTON_EVENT, (s3eCallback)SingleTouchButtonCB, NULL);
        s3ePointerRegister(S3E_POINTER_MOTION_EVENT, (s3eCallback)SingleTouchMotionCB, NULL);
    }
}

void ExampleShutDown()
{
    //Clear up
    if( s3ePointerGetInt(S3E_POINTER_MULTI_TOUCH_AVAILABLE) )
    {
        s3ePointerUnRegister(S3E_POINTER_TOUCH_EVENT, (s3eCallback)MultiTouchButtonCB);
        s3ePointerUnRegister(S3E_POINTER_TOUCH_MOTION_EVENT, (s3eCallback)MultiTouchMotionCB);
    }
    else
    {
        s3ePointerUnRegister(S3E_POINTER_BUTTON_EVENT, (s3eCallback)SingleTouchButtonCB);
        s3ePointerUnRegister(S3E_POINTER_MOTION_EVENT, (s3eCallback)SingleTouchMotionCB);
    }
}

bool ExampleUpdate()
{
    return true;
}

//-----------------------------------------------------------------------------
//  Render a coloured circle at the specified coordinates
//-----------------------------------------------------------------------------
void RenderTouch(int32 x, int32 y, uint16 col)
{
    const int32 radius = 40;
    uint16* surfaceData = (uint16*)s3eSurfacePtr();
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    int32 height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);
    int32 pitch = s3eSurfaceGetInt(S3E_SURFACE_PITCH)/2;

    // clip circular region
    uint32 startx = std::max(x - radius, 0l);
    uint32 endx = std::min(width, x + radius);
    uint32 starty = std::max(0l, y - radius);
    uint32 endy = std::min(height, y + radius);

    const int32 radiusSq = radius * radius;

    for(uint32 iy = starty; iy < endy; iy++)
    {
        uint16* out = surfaceData + iy * pitch + startx;
        for(uint32 ix = startx; ix < endx; ix++)
        {
            int32 distx = x - ix;
            int32 disty = y - iy;
            // if length of this line is under the radius paint the pixel
            if( distx * distx + disty * disty < radiusSq )
                *out = col;

            out++;
        }
    }
}

void ExampleRender()
{
    for(uint32 i = 0; i < MAX_TOUCHES; i++)
    {
        // For each active touch
        if( g_Touches[i].active )
        {
            // Render a circle
            uint16 col = (uint16)s3eSurfaceConvertRGB(g_TouchColours[i*3], g_TouchColours[i*3+1], g_TouchColours[i*3+2]);
            RenderTouch(g_Touches[i].x, g_Touches[i].y, col);
        }
    }
}


Airplay API Reference: S3E Secure Storage

Airplay API Reference > S3E API Documentation > S3E Secure Storage >

S3E Secure Storage

The S3E Secure Storage documentation contains the following sections:

  • S3E Secure Storage Overview
  • Secure Storage API Reference


Airplay API Reference: S3E Secure Storage Overview

Airplay API Reference > S3E API Documentation > S3E Secure Storage > S3E Secure Storage Overview >

S3E Secure Storage Overview

The Secure Storage Module allows you to read and write to a persistent block of data that is stored as securely as is possible on the platform.

The Secure Storage functionality stores data in a location that is unique to the current S3E application. This data is saved in permanent storage and can only be retrieved by the same S3E application.

Support is given for only one block of data, so it is the caller's responsibility to concatenate all needed settings into one block.

Secure Storage is useful for storing application state, player profiles, etc. for easy recall when the application is next loaded.

Note: For more information on the functionality outlined in this section, see the Secure Storage API Reference.


Airplay API Reference: Secure Storage API Reference

Airplay API Reference > S3E API Documentation > S3E Secure Storage > Secure Storage API Reference >

Secure Storage API Reference
[S3E]

Enumerations

enum | s3eSecureStorageError

Functions

S3E_API s3eResult | s3eSecureStorageGet (void *data, uint16 size)
S3E_API s3eSecureStorageError | s3eSecureStorageGetError ()
S3E_API const char * | s3eSecureStorageGetErrorString ()
S3E_API s3eResult | s3eSecureStoragePut (void *data, uint16 size)

Detailed Description

For more information on the Secure Storage functionality provided by the S3E module, see the S3E Secure Storage section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eSecureStorageError

SecureStorage Errors.

See also:
s3eSecureStorageGetError

s3eSecureStorageGetErrorString

Required Header Files
s3eSecureStorage.h
Enumerator:
S3E_SECURESTORAGE_ERR_NONE | No Error.
S3E_SECURESTORAGE_ERR_PARAM | Invalid parameter.
S3E_SECURESTORAGE_ERR_NOT_FOUND | File not found.
S3E_SECURESTORAGE_ERR_DEVICE | The underlying file device failed.
S3E_SECURESTORAGE_ERR_INSUFF | Size of buffer in insufficient for data record.
S3E_SECURESTORAGE_ERR_CORRUPT | Data corruption detected in secure storage.

Function Documentation

S3E_API s3eResult s3eSecureStorageGet | ( | void * | data,
 |  | uint16 | size
 | ) |  |

Reads a block of data with a given size from secure storage.

Parameters:
data | Location to write data from storage.
size | Byte size of data to read.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSecureStorageGetError() to retrieve an error code. This will return:
    • S3E_SECURESTORAGE_ERR_PARAM if data is NULL or size is zero.
    • S3E_SECURESTORAGE_ERR_NOT_FOUND if no stored data exists.
    • S3E_SECURESTORAGE_ERR_DEVICE if the underlying secure storage device failed.
    • S3E_SECURESTORAGE_ERR_INSUFF if size is not large enough for the secure storage record.
    • S3E_SECURESTORAGE_ERR_CORRUPT if data corruption was detected.
Remarks:
s3eSecureStoragePut() must have been called by the current S3E application (possibly in a previous instance).
See also:
s3eSecureStoragePut
Required Header Files
s3eSecureStorage.h

S3E_API s3eSecureStorageError s3eSecureStorageGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eSecureStorageGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eSecureStorage.h

S3E_API const char* s3eSecureStorageGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eSecureStorageGetError
Remarks:
This function, as opposed to s3eSecureStorageGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eSecureStorage.h

S3E_API s3eResult s3eSecureStoragePut | ( | void * | data,
 |  | uint16 | size
 | ) |  |

Writes a block of data with a given size to secure storage.

Parameters:
data | Location of data to be written to storage.
size | Byte size of data to write.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSecureStorageGetError() to retrieve an error code. This will return:
    • S3E_SECURESTORAGE_ERR_PARAM if size is zero and data is not NULL.
    • S3E_SECURESTORAGE_ERR_DEVICE if the underlying secure storage device failed.
Remarks:
The data is saved in a location that is unique to the current S3E application. This data is saved in permanent storage and can only be retrieved by the same S3E application. This data is useful for storing application state, player profiles etc. for easy recall when the application is next loaded.
See also:
s3eSecureStorageGet
Required Header Files
s3eSecureStorage.h


Airplay API Reference: S3E Socket

Airplay API Reference > S3E API Documentation > S3E Socket >

S3E Socket

The S3E Socket documentation contains the following sections:

  • S3E Socket Overview
  • Socket API Reference
  • S3E Socket Examples


Airplay API Reference: S3E Socket Overview

Airplay API Reference > S3E API Documentation > S3E Socket > S3E Socket Overview >

S3E Socket Overview

The Socket Module provides BSD-style socket creation and management. This module provides access to low level network functionality, in the form of UDP and TCP sockets.

The module also provides basic functionality for working with Internet addresses, including name/address resolution and address format conversion.

Note: Many sockets can be used simultaneously, but on some systems the maximum number is limited. The S3E_SOCKET_MAX_SOCKETS property can be queried to discover the limit.

The typical order in which the S3E is used to create a socket is as follows:

  • Create the new socket using the s3eSocketConnect() function.
  • Create an address structure of type s3eInetAddress.
  • Pass the internet address and the port number into the address structure. This may require that you format the address correctly using on of the address conversion functions.
  • Call the s3eSocketConnect() function passing it the created socket, the populated address structure and a callback function to be called when the connection is made.
  • Wait for the callback function to inform you that the socket has connected successfully before sending or receiving information.

Note: For an example of how the Socket functionality can be used, see the S3E Sockets Examples.

For more information on the functionality outlined in this section, see the Socket API Reference.


Airplay API Reference: Socket API Reference

Airplay API Reference > S3E API Documentation > S3E Socket > Socket API Reference >

Socket API Reference
[S3E]

Data Structures

struct | s3eInetAddress

Defines

#define | S3E_SOCKET_LOCAL (1 << 0)
#define | S3E_SOCKET_MORE (1 << 0)

Typedefs

typedef uint32 | s3eInetIPAddress
typedef struct s3eSocket | s3eSocket
typedef int32(* | s3eSocketCallbackFn )(s3eSocket *s, void *systemData, void *userData)

Enumerations

enum | s3eSocketError { , S3E_SOCKET_ERR_TOO_MANY = 2 }
enum s3eSocketProperty {
S3E_SOCKET_MAX_SOCKETS,
S3E_SOCKET_NETWORK_AVAILABLE,
S3E_SOCKET_NETWORK_TYPE,
S3E_SOCKET_DOMAINNAME,
S3E_SOCKET_HOSTNAME,
S3E_SOCKET_HTTP_PROXY,
S3E_SOCKET_UDP_AVAILABLE
}
enum | s3eSocketType

Functions

S3E_API s3eResult | s3eInetAton (s3eInetIPAddress *result, const char *addr)
S3E_API uint32 | s3eInetHtonl (uint32 addr)
S3E_API uint16 | s3eInetHtons (uint16 addr)
S3E_API s3eResult | s3eInetLookup (const char *hostname, s3eInetAddress *addr, s3eCallback func, void *userData)
S3E_API void | s3eInetLookupCancel ()
S3E_API char * | s3eInetNtoa (s3eInetIPAddress addr, char *buf, int len)
S3E_API uint32 | s3eInetNtohl (uint32 addr)
S3E_API uint16 | s3eInetNtohs (uint16 addr)
S3E_API const char * | s3eInetToString (const s3eInetAddress *s)
S3E_API s3eSocket * | s3eSocketAccept (s3eSocket *s, s3eInetAddress *addr, s3eSocketCallbackFn callback, void *userdata)
S3E_API s3eResult | s3eSocketBind (s3eSocket *sock, const s3eInetAddress *addr, uint8 reuseAddress)
S3E_API s3eResult | s3eSocketClose (s3eSocket *socket)
S3E_API s3eResult | s3eSocketConnect (s3eSocket *sock, const s3eInetAddress *addr, s3eSocketCallbackFn func, void *userdata)
S3E_API s3eSocket * | s3eSocketCreate (s3eSocketType type, uint32 flags=0)
S3E_API s3eSocketErrors | s3eSocketGetError ()
S3E_API const char * | s3eSocketGetErrorString ()
S3E_API int32 | s3eSocketGetInt (s3eSocketProperty socketProperty)
S3E_API s3eResult | s3eSocketGetLocalName (s3eSocket *sock, s3eInetAddress *addr)
S3E_API s3eResult | s3eSocketGetPeerName (s3eSocket *sock, s3eInetAddress *addr)
S3E_API const char * | s3eSocketGetString (s3eSocketProperty socketProperty)
S3E_API s3eResult | s3eSocketListen (s3eSocket *s, uint16 backlog)
S3E_API s3eResult | s3eSocketReadable (s3eSocket *s, s3eSocketCallbackFn readable, void *userData)
S3E_API int32 | s3eSocketRecv (s3eSocket *sock, char *buf, uint32 len, int flags)
S3E_API int32 | s3eSocketRecvFrom (s3eSocket *s, char *buf, uint32 len, int flags, s3eInetAddress *from)
S3E_API int32 | s3eSocketSend (s3eSocket *sock, const char *buf, uint32 len, int flags)
S3E_API int32 | s3eSocketSendTo (s3eSocket *s, const char *buf, uint32 len, int flags, const s3eInetAddress *to)
S3E_API s3eResult | s3eSocketWritable (s3eSocket *s, s3eSocketCallbackFn writable, void *data)

Detailed Description

For more information on the Socket functionality provided by the S3E module, see the S3E Socket section of the S3E API Documentation.

Define Documentation

#define S3E_SOCKET_LOCAL (1 << 0)

The flags that can be passed to s3eSocketCreate. S3E_SOCKET_LOCAL: attempt to create a local socket. This is not supported on all systems.

See also:
s3eSocketCreate

#define S3E_SOCKET_MORE (1 << 0)

Flags that can be passed to the send and/or recv functions. S3E_SOCKET_MORE: This flag acts as an indication to the send function that more data is about to follow. For TCP this should delay the sending of the data packet pending a further call to send.

See also:
s3eSocketSend

s3eSocketSendTo

Typedef Documentation

typedef uint32 s3eInetIPAddress

32-bit IP address in network byte order.

typedef struct s3eSocket s3eSocket

Opaque struct representing a network socket.

typedef int32(* s3eSocketCallbackFn)(s3eSocket *s, void *systemData, void *userData)

Socket specific callback types.

Parameters:
systemData | callback-specific system supplied data.
userData | data supplied by user at callback registration.
Required Header Files
s3eSocket.h

Enumeration Type Documentation

enum s3eSocketError

Socket Errors.

See also:
s3eSocketGetError

s3eSocketGetErrorString

Required Header Files
s3eSocket.h
Enumerator:
S3E_SOCKET_ERR_NONE | No Error.
S3E_SOCKET_ERR_PARAM | Invalid parameter.
S3E_SOCKET_ERR_TOO_MANY | Maximum number of callbacks exceeded, or maximum number of sockets reached.
S3E_SOCKET_ERR_ALREADY_REG | The specified callback is already registered.
S3E_SOCKET_ERR_NOT_FOUND | The specified callback was not found for removal.
S3E_SOCKET_ERR_UNAVAIL | SOCKET is unavailable or feature is not supported.
S3E_SOCKET_ERR_UNSUPPORTED | The action requested is not supported.
S3E_SOCKET_ERR_WOULDBLOCK | The operation would block, please try again later.
S3E_SOCKET_ERR_INPROGRESS | The operation is now in progress.
S3E_SOCKET_ERR_ALREADY | The operation was already in progress.
S3E_SOCKET_ERR_NOTSOCK | That object passed in is not a socket object.
S3E_SOCKET_ERR_MSGSIZE | The UDP message is to long for the underlying layer.
S3E_SOCKET_ERR_ADDRINUSE | The requested address is already in use.
S3E_SOCKET_ERR_NETDOWN | The network is down.
S3E_SOCKET_ERR_CONNRESET | The connection with the peer was reset.
S3E_SOCKET_ERR_ISCONN | The socket is connected and the requestion operation requires an unconnected socket.
S3E_SOCKET_ERR_NOTCONN | The socket is not connected and the requested operation requires a connected socket.
S3E_SOCKET_ERR_SHUTDOWN | The socket has been shutdown.
S3E_SOCKET_ERR_TIMEDOUT | The requested operation timed out.
S3E_SOCKET_ERR_CONNREFUSED | The connection was refused.
S3E_SOCKET_ERR_UNKNOWN_HOST | The DNS system failed to lookup the hostname.

enum s3eSocketProperty

Socket Properties. S3E_SOCKET_MAX_SOCKETS: indicates the maximum number of sockets that the system supports.

See also:
s3eSocketGetInt
Enumerator:
S3E_SOCKET_MAX_SOCKETS | [read, int] the maximum number of sockets that the system supports.
S3E_SOCKET_NETWORK_AVAILABLE | [read, int] 1 if the networking is currently available, 0 if not.
S3E_SOCKET_NETWORK_TYPE | [read, int] the current network type, if known
S3E_SOCKET_DOMAINNAME | [read, string] the domain name the device is in, if any.
S3E_SOCKET_HOSTNAME | [read, string] the hostname of the device, if any.
S3E_SOCKET_HTTP_PROXY | [read, string] the proxy setup for the device, if any.
S3E_SOCKET_UDP_AVAILABLE | [read, int] 1 if the udp is currently available over the network connection, 0 if not.

enum s3eSocketType

Socket types to be passed into s3eSocketCreate.

See also:
s3eSocketCreate
Required Header Files
s3eSocket.h

Function Documentation

S3E_API s3eResult s3eInetAton | ( | s3eInetIPAddress * | result,
 |  | const char * | addr
 | ) |  |

Converts an IPV4 address in number-and-dots notation to a 32bit integer in network byte order.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the string is not in valid number-and-dots notation.
Required Header Files
s3eSocket.h

S3E_API uint32 s3eInetHtonl ( uint32 addr )

Converts a 32bit integer from host byte order to network byte order.

Returns:
The integer in network order.
Required Header Files
s3eSocket.h

S3E_API uint16 s3eInetHtons ( uint16 addr )

Converts a 16bit integer host byte order to network byte order.

Returns:
The integer in network order.
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eInetLookup | ( | const char * | hostname,
 |  | s3eInetAddress * | addr,
 |  | s3eCallback | func,
 |  | void * | userData
 | ) |  |

Initiates a DNS lookup. This call can be synchronous or asynchronous, depending on the whether a callback function is provided. Only one lookup can be active at once.

Parameters:
hostname | The name to lookup.
addr | The address structure to be filled in with the result.
func | A callback function that is called back when the lookup is complete, or NULL if the operation is to be done synchronously.
userData | Argument to func.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    • S3E_SOCKET_ERR_ALREADY if a lookup is already in progress.
    • S3E_SOCKET_ERR_UNKNOWN_HOST if host could not be found using DNS.
Note:
The systemData passed to the callback registered with this function is a pointer to s3eInetAddress, and will be the same as the addr param passed into this function (which will have been filled in with the address) if the lookup succeeded, or NULL otherwise.

S3E_API void s3eInetLookupCancel ( )

Cancel an outstanding lookup.

S3E_API char* s3eInetNtoa | ( | s3eInetIPAddress | addr,
 |  | char * | buf,
 |  | int | len
 | ) |  |

Converts a 32bit integer in network byte order into a string in standard numbers-and-dots notation.

Parameters:
buf | the buffer to write to.
len | the length of buf, in bytes.
Returns:
the buf pointer, if one was passed in, otherwise a pointer to a string allocated by s3eMalloc(). If buf is supplied and not long enough NULL is returned.
Required Header Files
s3eSocket.h

S3E_API uint32 s3eInetNtohl ( uint32 addr )

Converts a 32bit integer from network byte order to host byte order.

Returns:
The integer in host order.
Required Header Files
s3eSocket.h

S3E_API uint16 s3eInetNtohs ( uint16 addr )

Converts a 16bit integer from network byte order to host byte order.

Returns:
The integer in host order.
Required Header Files
s3eSocket.h

S3E_API const char* s3eInetToString ( const s3eInetAddress * s )

Convert an s3eInetAddress into string form. The string returned is part of the s3eInetAddress structure so no allocation is needed.

Returns:
the string representaion of the address.
Required Header Files
s3eSocket.h

S3E_API s3eSocket* s3eSocketAccept | ( | s3eSocket * | s,
 |  | s3eInetAddress * | addr,
 |  | s3eSocketCallbackFn | callback,
 |  | void * | userdata
 | ) |  |

Accepts an incoming connection attempt on a socket.

Parameters:
s | The socket which is in a listening state.
addr | [out] The network address of the connecting entity. This may be NULL.
userdata | Userdata to accociate with callbacks.
callback | Function to called when the operation completes. This may be NULL and is only used when this function returns NULL and sets the S3E_SOCKET_ERR_WOULDBLOCK error. The callback is involked when a new connection arrived and a subsequent call to s3eSocketAccept would then succeed. The system data passed to the callback is NULL.
Returns:
On success, a new s3eSocket handle for the connection, otherwise s3eSocketAccept() returns NULL
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_WOULDBLOCK there are new connections waiting to be accepted.
    • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle, or the socket is not a listening socket.
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketBind | ( | s3eSocket * | sock,
 |  | const s3eInetAddress * | addr,
 |  | uint8 | reuseAddress
 | ) |  |

Bind a socket to a particular local address. If the address passed in to this function is NULL then the socket is bound to an arbitrary available port and address. Likewise, if the port or ipaddress specified within the address is 0 then the socket is bound to an arbitrary free port or address respectively. If this function is not called prior to s3eSocketConnect(), s3eSocketListen() or s3eSocketSendTo() then the socket will be bound to an arbitrary free address upon calling one of these functions.

Parameters:
sock | The socket to bind.
addr | The address to bind to.
reuseAddress | Pass non-zero uint8 to allow address reuse.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle, or the socket is already bound, or the address requested does not match any of the current device.
    • S3E_SOCKET_ERR_INPROGRESS if the bind operation is currently active but has not yet completed. Further calls to s3eSocketBind() will return S3E_SOCKET_ERR_INPROGRESS until the bind operation has completed.
See also:
s3eSocketGetLocalName
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketClose ( s3eSocket * socket )

Closes a socket and frees all associated resources. Once this function returns, the socket handle is not longer valid.

Parameters:
socket The socket to close and delete.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the socket is not a valid socket handle.
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketConnect | ( | s3eSocket * | sock,
 |  | const s3eInetAddress * | addr,
 |  | s3eSocketCallbackFn | func,
 |  | void * | userdata
 | ) |  |

Connects a socket to a given peer. For TCP sockets this initiates the connection process (sends a SYN). For UDP sockets this allows s3eSocketSend() and s3eSocketRecv() to be called by binding to the given peer address. For TCP sockets the initial call to connect will generate S3E_SOCKET_ERR_INPROGRESS, as will further calls until the operation completes at which point the actual error will be indicated or S3E_SOCKET_ERR_ALREADY will be generated if the connection was successful. If a callback function is specified then it will be called once the connection operation completes. If the callback is called with S3E_RESULT_ERROR then s3eSocketGetError() can be used to retrieve the error code as usual.

Parameters:
sock | The socket to connect.
addr | The address to connect to.
func | Function to be called on completion of the connect.
userdata | Parameter to be used when callback is called.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the socket is not a valid socket handle.
    • S3E_SOCKET_ERR_ALREADY if a connection operation is already in progress.
    • S3E_SOCKET_ERR_NETDOWN if there is no network connection available.
    • S3E_SOCKET_ERR_TIMEDOUT if the connection attempt timed out.
    • S3E_SOCKET_ERR_INPROGRESS if the connection operation is currently in progress.
    • S3E_SOCKET_ERR_CONNREFUSED if the connection was refused by the peer.
Note:
The systemData passed to the callback registered with this function is a pointer to an s3eResult indicating whether the connection succeeded.

It is not necessary to define a return value for any registered callback.

S3E_API s3eSocket* s3eSocketCreate | ( | s3eSocketType | type,
 |  | uint32 | flags = 0
 | ) |  |

Creates a new socket.

Parameters:
type | The type of socket requested.
flags | The bitwise OR of zero of more socket creation flags.
Returns:
  • a valid pointer if no error occurred.
  • NULL if the operation failed. Call s3eSocketGetError() to retrieve the error code. This will return one of:
    • S3E_SOCKET_ERR_PARAM if the socket type given is not valid.
    • S3E_SOCKET_ERR_UNSUPPORTED if the socket type, or flags given are are not supported on the current platform.
Required Header Files
s3eSocket.h

S3E_API s3eSocketErrors s3eSocketGetError ( )

Retrieves the last socket error, if any, for this subdevice.

See also:
s3eSocketGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eSocket.h

S3E_API const char* s3eSocketGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eSocketGetError
Remarks:
This function, as opposed to s3eSocketGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eSocket.h

S3E_API int32 s3eSocketGetInt ( s3eSocketProperty socketProperty )

Retrieves an integer property for this subdevice.

Parameters:
socketProperty property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eSocketGetError() to retrieve an error code. This will return:
    • S3E_SOCKET_ERR_PARAM if socketProperty is not valid.
See also:
s3eSocketGetString
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketGetLocalName | ( | s3eSocket * | sock,
 |  | s3eInetAddress * | addr
 | ) |  |

Get the local address of a socket.

Parameters:
sock | The socket.
addr | A pointer to an s3eInetAddress, which will be filled with the local address of the socket.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle.
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketGetPeerName | ( | s3eSocket * | sock,
 |  | s3eInetAddress * | addr
 | ) |  |

Get the address of the remote peer to which the socket is connected. This will only work for connected sockets.

Parameters:
sock The socket.
addr A pointer to an s3eInetAddress, which will be filled with the local address of the socket.
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle.

S3E_API const char* s3eSocketGetString ( s3eSocketProperty socketProperty )

Retrieves a string property for this subdevice.

Parameters:
S3E_SOCKET_DOMAINNAME | the domain name the device is in, if any.
S3E_SOCKET_HOSTNAME | the hostname of the device, if any. will return S3E_SOCKET_ERR_PARAM if socketProperty is not valid
See also:
s3eSocketGetInt
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketListen | ( | s3eSocket * | s,
 |  | uint16 | backlog
 | ) |  |

Puts a socket in a state where it is listening for an incoming connection.

Parameters:
s | A bound, unconnected socket.
backlog | The maximum length of the queue of pending connections.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSocketGetError() to retrieve the error code.
    • S3E_SOCKET_ERR_PARAM if the socket is not a valid socket handle, or the socket is not bound.
    • S3E_SOCKET_ERR_ADDRINUSE if another socket is already listening on address s is bound to.
    • S3E_SOCKET_ERR_UNSUPPORTED if listening sockets are not supported by the system.
Required Header Files
s3eSocket.h

S3E_API s3eResult s3eSocketReadable | ( | s3eSocket * | s,
 |  | s3eSocketCallbackFn | readable,
 |  | void * | userData
 | ) |  |

Schedule a callback to be called when the socket becomes readable. This is a one-shot callback. Setting to NULL will cancel any existing callback.

Parameters:
s | The Socket.
readable | Callback. The systemData passed to this callback will be of type s3eSocket*, and will be equal to s. The userData passed to the callback will be the userData passed here
userData | callback parameter.
Required Header Files
s3eSocket.h

S3E_API int32 s3eSocketRecv | ( | s3eSocket * | sock,
 |  | char * | buf,
 |  | uint32 | len,
 |  | int | flags
 | ) |  |

Receives data on a connected socket. s3eSocketConnect() must have been called before calling this function. If no data is waiting, -1 will be returned and S3E_SOCKET_ERR_WOULDBLOCK is set as the current error. In the case of failure s3eSocketGetError() can be used to retrieve error which will be one of the following:

  • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle.
  • S3E_SOCKET_ERR_SHUTDOWN the peer shutdown the connection.
  • S3E_SOCKET_ERR_WOULDBLOCK there is currently no data available to be received.
  • S3E_SOCKET_ERR_NOTCONN the given socket is not connected.
    Parameters:
    sock | the socket to receivce data on.
    buf | pointer to a buffer to fill with data.
    len | the number of bytes to read.
    flags | The bitwise OR of zero or more socket receive flags.
    Returns:
    number of bytes read from socket or -1 on failure.
    See also:
    s3eSocketConnect

S3E_API int32 s3eSocketRecvFrom | ( | s3eSocket * | s,
 |  | char * | buf,
 |  | uint32 | len,
 |  | int | flags,
 |  | s3eInetAddress * | from
 | ) |  |

Receives a datagram from an unconnected UDP socket.

Parameters:
s | the socket to receivce data on.
buf | pointer to a buffer to fill with data.
len | the number of bytes to read.
flags | The bitwise OR of zero or more socket receive flags.
from | pointer to an address to be set to source address of the datagram.
Returns:
If no datagram is waiting -1 will be returned and S3E_SOCKET_ERR_WOULDBLOCK is set as the current error on the socket. In the case of failure s3eSocketGetError() can be used to retrieve error which will be one of the following:
  • S3E_SOCKET_ERR_PARAM if s is not a valid socket handle, or the socket is not bound.
  • S3E_SOCKET_ERR_WOULDBLOCK there is currently no data available to be received.
  • S3E_SOCKET_ERR_ISCONN the given socket is connected and s3eSocketRecv() should therefore be used.

the size in bytes of the datagram, or -1 on failure.

S3E_API int32 s3eSocketSend | ( | s3eSocket * | sock,
 |  | const char * | buf,
 |  | uint32 | len,
 |  | int | flags
 | ) |  |

Sends data on a connected socket. s3eSocketConnect() must have been called before calling this function. If none of the data can be sent the function will return -1 and S3E_SOCKET_ERR_WOULDBLOCK is set. In the case of failure s3eSocketGetError() can be used to retrieve error which will be one of the following:

  • S3E_SOCKET_ERR_PARAM if the sock is not a valid socket handle.
  • S3E_SOCKET_ERR_SHUTDOWN the peer shutdown the connection.
  • S3E_SOCKET_ERR_WOULDBLOCK there is currently no space in the output buffer.
  • S3E_SOCKET_ERR_NOTCONN the given socket is not connected.
  • S3E_SOCKET_ERR_MSGSIZE the socket type is UDP and the length of the buffer exceeds the maximum UDP packet size.
    Parameters:
    sock | The socket to use.
    buf | The data to send
    len | The number of bytes to send
    flags | The bitwise OR of zero or more socket send flags.
    Returns:
    The number of bytes sent, or -1 on failure.
    See also:
    s3eSocketConnect

S3E_API int32 s3eSocketSendTo | ( | s3eSocket * | s,
 |  | const char * | buf,
 |  | uint32 | len,
 |  | int | flags,
 |  | const s3eInetAddress * | to
 | ) |  |

Sends a datagram on an unconnected UDP socket. If the datagram cannot be currently be sent, -1 will be returned and S3E_SOCKET_ERR_WOULDBLOCK is set as the current error on the socket. If the socket is not already bound when this function is first called it will be bound to an arbitrary local address automatically before sending any data.

Parameters:
s | The socket to receivce data on.
buf | A Pointer to the datagram which to send.
len | The length of the datagram. flags The bitwise OR of zero or more socket send flags.
to | The address send the datagram to.
Returns:
the number of bytes sent if no error occurred, or -1 on failure. s3eSocketGetError() can be used to retrieve error which will be one of the following:
  • S3E_SOCKET_ERR_PARAM s is not a valid socket handle.
  • S3E_SOCKET_ERR_WOULDBLOCK there is currently no space in the output buffer.
  • S3E_SOCKET_ERR_ISCONN the given socket is connected and s3eSocketSend() should therefore be used.
  • S3E_SOCKET_ERR_MSGSIZE the length of the buffer exceeds the maximum UDP packet size.

S3E_API s3eResult s3eSocketWritable | ( | s3eSocket * | s,
 |  | s3eSocketCallbackFn | writable,
 |  | void * | data
 | ) |  |

Schedule a callback to be called when the socket becomes writable. This is a one-shot callback. Setting to NULL will cancel any existing callback.

Parameters:
s | The Socket.
writable | Callback. The systemData passed to this callback will be of type s3eSocket*, and will be equal to s. the userData passed to the callback will be the data passed here.
data | Callback parameter.
Required Header Files
s3eSocket.h


Airplay API Reference: S3E Socket Examples

Airplay API Reference > S3E API Documentation > S3E Socket > S3E Socket Examples >

S3E Socket Examples

This section illustrates how you can use the Socket functionality provided by S3E. This section contains one example application:

  • S3E Socket Example

Note: For more information on the S3E Socket functionality, see the S3E Socket Overview.


Airplay API Reference: S3E Socket Example

Airplay API Reference > S3E API Documentation > S3E Socket > S3E Socket Examples > S3E Socket Example >

S3E Socket Example

The following example uses S3E's socket functionality to send a string to blackcurrant and then to receive an echo of that string in return.

The main functions used to achieve this are:

  • s3eInetAton()
  • s3eSocketConnect()
  • s3eSocketSend()
  • s3eSocketRecv()

The ExampleUpdate() tests for keyboard input. The key options are as follows:

  • s3eKey1: pressing this button calls our connect() application function. This function creates a socket and attempts to establish a connection. Once the socket is created the s3eInetAton() function is used to convert the IPV4 address set in IP_ADDRESS to a 32bit integer in network byte order. The address integer and the port set in ECHO_PORT are entered in a s3eInetAddress structure. This structure, the created socket and a callback function are all passed to the s3eSocketConnect() function. A wait is then performed for a minute while the connect is attempted. When connection succeeds the callback sets the connect_done bool to true.
  • s3eKey2: pressing this button calls our sendAndReceive() application function. This function attempts to send and receive information over the established connection. The s3eSocketSend() function is called till all bytes in the string are sent. The s3eSocketRecv() function is then used to receive the echo of the sent string.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "Logo.h"

//-----------------------------------------------------------------------------
#define ECHO_HOST  "echo.ideaworks3d.com"
#define ECHO_PORT  7
#define SOCKET_TIMEOUT (30000)
//-----------------------------------------------------------------------------

char        g_ErrorString[256];             //Contains operation results for display
bool        g_SocketIsConnected;            //Flag that keeps track of connect status
s3eSocket*  g_Sock;                         //Socket for send/receive operation
Button*     g_ButtonCreate = 0;
Button*     g_ButtonSend = 0;
Button*     g_ButtonClose = 0;

// Connect callback
static int32 ConnectCB(s3eSocket* g_Sock, void* sys, void* data)
{
    s3eResult res = *(s3eResult*)sys;

    if (res == S3E_RESULT_SUCCESS)
        g_SocketIsConnected = true;
    else
        g_SocketIsConnected = false;

    return 0;
}

//-----------------------------------------------------------------------------
// The following function creates a socket and attempts to establish a connection.
// Once the socket is created the s3eInetAton() function is used to convert the
// IPV4 address set in IP_ADDRESS to a 32bit integer in network byte order. The
// address integer and the port set in ECHO_PORT are entered in a s3eInetAddress
// structure. This structure, the created socket and a callback function are all
// passed to the s3eSocketConnect() function. A wait is performed for a minute
// while the connect is attempted. When connection succeeds the callback sets
// the <code>g_SocketIsConnected</code> bool to true.
//-----------------------------------------------------------------------------
void Connect()
{
    //Creating new socket
    g_Sock = s3eSocketCreate(S3E_SOCKET_TCP, 0);

    if (g_Sock == NULL)
    {
        strcpy(g_ErrorString,"`x666666Creation of socket failed");
        return;
    }

    g_SocketIsConnected = false;

    // look up address
    s3eInetAddress addr;
    memset(&addr, 0, sizeof(addr));

    if (s3eInetLookup(ECHO_HOST, &addr, NULL, NULL) == S3E_RESULT_ERROR)
    {
        sprintf(g_ErrorString,"`x666666s3eInetLookup failed: %s", ECHO_HOST);
        return;
    }

    addr.m_Port = s3eInetHtons(ECHO_PORT);

    int32 counter = 0;
    // Using the created socket, address structure and set callback function the Connect is called.
    // A wait is performed for a minute while the connect is attempted. When connection succeeds the
    // callback sets the g_SocketIsConnected bool to true causing the waiting to stop
    if (s3eSocketConnect(g_Sock, &addr, &ConnectCB, NULL) != S3E_RESULT_SUCCESS)
    {
        switch (s3eSocketGetError())
        {
            // These errors are 'OK', because they mean,
            // that a connect is in progress
            case S3E_SOCKET_ERR_INPROGRESS:
            case S3E_SOCKET_ERR_ALREADY:
            case S3E_SOCKET_ERR_WOULDBLOCK:
                break;
            default:
                // A 'real' error happened
                sprintf(g_ErrorString,"`x666666Connecting failed:\n%s", s3eSocketGetErrorString());
                s3eSocketClose(g_Sock);
                g_Sock = NULL;
                return;
        }

        // Try to connect, but wait a maximum time of SOCKET_TIMEOUT
        uint64 testStartTime = s3eTimerGetMs();
        while (!ExampleCheckQuit() && s3eTimerGetMs()-testStartTime < SOCKET_TIMEOUT)
        {
            // Stop waiting since socket is now connected
            if (g_SocketIsConnected)
                break;

            // Press key 4 in order to cancel connect operation
            s3eKeyboardUpdate();
            if (s3eKeyboardGetState(s3eKey4) & S3E_KEY_STATE_PRESSED)
            {
                s3eSocketClose(g_Sock);
                g_Sock = NULL;
                strcpy(g_ErrorString,"");
                return;
            }

            //Update screen during connect operation
            s3eDebugPrint(10, 120, g_ErrorString, 1);
            sprintf(g_ErrorString,"`x666666 Trying to connect");
            s3eDebugPrint(10, 80, "`x666666Press 4 to cancel connect", 0);

            switch (++counter%8)
            {
                case 0 :
                case 4 :
                    strcat(g_ErrorString, " |");break;
                case 1 :
                case 5:
                    strcat(g_ErrorString, " /");break;
                case 2 :
                case 6 :
                    strcat(g_ErrorString, " -");break;
                case 3 :
                case 7 :
                    strcat(g_ErrorString, " \\");break;
            }

            LogoRender();
            ExampleRender();
            s3eSurfaceShow();
            s3eDeviceYield(30);
        }
    }

    if (g_SocketIsConnected == false)
    {
        strcpy(g_ErrorString,"`x666666Socket connecting timed out");
        s3eSocketClose(g_Sock);
        g_Sock = NULL;
    }
    else
    {
        strcpy(g_ErrorString,"");
    }
}

//-----------------------------------------------------------------------------
// This function attempts to send and receive information over the established
// connection. The s3eSocketSend() function is called till all bytes in the
// string are sent. The s3eSocketRecv() function is then used to receive the
// echo of the sent string.
//-----------------------------------------------------------------------------
void SendAndReceive()
{
    //---------------------------------------------
    // Sending data
    //---------------------------------------------
    const char* messageToSend = "hello server!";
    int32       messageLength = strlen(messageToSend);
    int32       messageSent = 0;
    int32       retValue;

    // Loop until the full message has been send
    do
    {
        // returns the number of bytes sent, or -1 on failure.
        retValue = s3eSocketSend(g_Sock, messageToSend+messageSent, messageLength-messageSent, 0);

        // sending has been successfull, see how many bytes are left to send
        if (retValue > 0)
            messageSent += retValue;

        // an error occurred while sending
        if (retValue < 0)
        {
            // This error is OK, since S3E_SOCKET_ERR_AGAIN means, that
            // a function is in process right now
            if (s3eSocketGetError() == S3E_SOCKET_ERR_AGAIN)
            {
                s3eDeviceYield(50);
                continue;
            }

            // Any other error should be treated as "sending failed"
            sprintf(g_ErrorString, "`x666666send failed: %s", s3eSocketGetErrorString());
            return;
        }

    } while(messageSent < messageLength);

    //---------------------------------------------
    // Receiving data
    //---------------------------------------------
    char messageReceived[0x200];            //Buffer for answer from server

    //Wait for answer for a maximum of SOCKET_TIMEOUT
    uint64 testStartTime = s3eTimerGetMs();
    while (s3eTimerGetMs()-testStartTime < SOCKET_TIMEOUT)
    {
        //return number of bytes read from socket or -1 on failure.
        retValue = s3eSocketRecv(g_Sock, messageReceived, 0x200, 0);

        //We received an amount of data
        if (retValue != -1)
            break;
        s3eDeviceYield(50);
    }

    // An error occurred
    if (retValue == -1)
    {
        sprintf(g_ErrorString, "`x666666Receive failed: %d", s3eSocketGetError());
        return;
    }

    messageReceived[messageLength] = '\0';

    // Compare sent and received data
    if (strcmp(messageReceived, messageToSend) != 0)
        sprintf(g_ErrorString, "`x666666Reply: '%s'\nis not correct", messageReceived);
    else
        sprintf(g_ErrorString, "`x666666Reply: '%s'\nis correct", messageReceived);

    return;
}

void ExampleInit()
{
    g_SocketIsConnected = false;
    g_Sock = NULL;

    g_ButtonCreate  = NewButton("Create A Socket");
    g_ButtonSend    = NewButton("Send & Receive Data");
    g_ButtonClose   = NewButton("Close Socket");
}

void ExampleShutDown()
{
    if (g_Sock)
    {
        s3eSocketClose(g_Sock);
        g_Sock = NULL;
    }
}

//-----------------------------------------------------------------------------
// This function waits for keyboard input to start the echo. By pressing s3eKey1
// the connect() function is called. By pressing s3eKey2
// the sendAndReceive() function is called.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if ((pressed == g_ButtonCreate) && g_SocketIsConnected == false)
        Connect();

    if ((pressed == g_ButtonSend) && g_SocketIsConnected == true)
        SendAndReceive();

    if ((pressed == g_ButtonClose) && g_SocketIsConnected == true)
    {
        g_SocketIsConnected = false;
        s3eSocketClose(g_Sock);
        g_Sock = NULL;
        strcpy(g_ErrorString, "");
    }

    return true;
}

void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int ypos = GetYBelowButtons() + 2 * textHeight;

    g_ButtonCreate->m_Enabled = !g_SocketIsConnected;
    g_ButtonSend->m_Enabled = g_SocketIsConnected;
    g_ButtonClose->m_Enabled = g_SocketIsConnected;

    // Display info
    if (g_SocketIsConnected)
        s3eDebugPrint(10, ypos, "`x666666Socket connected", 1);
    else
        s3eDebugPrint(10, ypos, "`x666666Socket not connected", 1);

    ypos += 2 * textHeight;

    // Display error information
    s3eDebugPrint(10, ypos, g_ErrorString, 1);

    ypos += 4 * textHeight;
    s3eDebugPrintf(10, ypos, 1, "`x666666Domain: %s", s3eSocketGetString(S3E_SOCKET_DOMAINNAME));
    ypos += textHeight;
    s3eDebugPrintf(10, ypos, 1, "`x666666Hostname: %s", s3eSocketGetString(S3E_SOCKET_HOSTNAME));
    ypos += textHeight;
    s3eDebugPrintf(10, ypos, 1, "`x666666Network Available: %ld", s3eSocketGetInt(S3E_SOCKET_NETWORK_AVAILABLE));
    ypos += textHeight;
    s3eDebugPrintf(10, ypos, 1, "`x666666Network Type: %ld", s3eSocketGetInt(S3E_SOCKET_NETWORK_TYPE));
}


Airplay API Reference: S3E Sound

Airplay API Reference > S3E API Documentation > S3E Sound >

S3E Sound

The S3E Sound documentation contains the following sections:

  • S3E Sound Overview
  • Sound API Reference
  • S3E Sound Examples


Airplay API Reference: S3E Sound Overview

Airplay API Reference > S3E API Documentation > S3E Sound > S3E Sound Overview >

S3E Sound Overview

The Sound Module allows you to control how and what sound is played. The API is split into two groups:

  • functions that apply to the sound device
  • functions that apply to individual sound channels.

Sound is implemented via a number of individual channels, each of which can be individually controlled to play, pause, resume and stop sound (s3eSoundChannelPlay(), s3eSoundChannelPause(), etc.), at different frequencies and volumes. The sound device will then mix the output of all the channels, allowing several separate sounds, for example, sound effects, to be played at once. To select a channel on which to play sound, use the s3eSoundGetFreeChannel() function to find a free channel.

Note: Currently there are a maximum of 24 channels available. The sound device functions allow you control over all channels simultaneously, for example, s3eSoundStopAllChannels(), as well as setting global sound output parameters, such as Volume via s3eSoundSetInt().

Both the Sound API and the channel-specific Sound Channel API have accompanying callback sets:

  • s3eSoundCallback
  • s3eSoundChannelCallback

The s3eSoundChannelCallback mechanism handles functions you would like called when channel specific events take place. Each callback that is registered, is registered for a specific channel, and only one callback can be registered for each channel event. Callbacks can be set for this mechanism using the s3eSoundChannelRegister() function. If a function is registered for the S3E_CHANNEL_GEN_AUDIO callback, then complete control of the sound channel is handed to the registered function; that is, the sound channel is no longer controlled using the sound channel API. This enables the user to generate audio 'on the fly' directly into the output device, and provides a mechanism for implementing sound channels that can play compressed audio or mathematically generated sound. Once a callback for S3E_CHANNEL_GEN_AUDIO is registered, the S3E_CHANNEL_STATE_CHANGE callback should also be registered in order to respond to the sound channel API. For more information on the S3E_CHANNEL_GEN_AUDIO sound channel callback, as well as all other sound channel callbacks, see s3eSoundChannelCallback.

Note: For an example of how the Sound functionality can be used, see the S3E Sound Examples.

For more information on the functionality outlined in this section, see the Sound API Reference.


Airplay API Reference: Sound API Reference

Airplay API Reference > S3E API Documentation > S3E Sound > Sound API Reference >

Sound API Reference
[S3E]

Data Structures

struct | s3eSoundEndSampleInfo
struct | s3eSoundGenAudioInfo

Defines

#define | S3E_SOUND_MAX_FREQ 0x40000
#define | S3E_SOUND_MAX_VOLUME 0x100

Enumerations

enum s3eSoundChannelCallback {
S3E_CHANNEL_END_SAMPLE = 0,
S3E_CHANNEL_GEN_AUDIO = 1,
S3E_CHANNEL_STOP_AUDIO = 2,
S3E_CHANNEL_GEN_AUDIO_STEREO = 3
}
enum s3eSoundChannelProperty {
S3E_CHANNEL_PITCH = 0,
S3E_CHANNEL_RATE = 1,
S3E_CHANNEL_USERVAR = 2,
S3E_CHANNEL_VOLUME = 3,
S3E_CHANNEL_STATUS = 4,
S3E_CHANNEL_PAUSED = 5
}
enum | s3eSoundError
enum s3eSoundProperty {
S3E_SOUND_VOLUME = 0,
S3E_SOUND_OUTPUT_FREQ = 1,
S3E_SOUND_DEFAULT_FREQ = 2,
S3E_SOUND_NUM_CHANNELS = 3,
S3E_SOUND_USED_CHANNELS = 4,
S3E_SOUND_AVAILABLE = 5,
S3E_SOUND_VOLUME_DEFAULT = 6,
S3E_SOUND_STEREO_ENABLED = 7
}

Functions

S3E_API int32 | s3eSoundChannelGetInt (int channel, s3eSoundChannelProperty property)
S3E_API s3eResult | s3eSoundChannelPause (int channel)
S3E_API s3eResult | s3eSoundChannelPlay (int channel, int16 *start, uint32 numSamples, int32 repeat, int32 loopfrom)
S3E_API s3eResult | s3eSoundChannelRegister (int channel, s3eSoundChannelCallback cbid, s3eCallback func, void *userData)
S3E_API s3eResult | s3eSoundChannelResume (int channel)
S3E_API s3eResult | s3eSoundChannelSetInt (int channel, s3eSoundChannelProperty property, int32 value)
S3E_API s3eResult | s3eSoundChannelStop (int channel)
S3E_API s3eResult | s3eSoundChannelUnRegister (int channel, s3eSoundChannelCallback cbid)
S3E_API s3eSoundError | s3eSoundGetError ()
S3E_API const char * | s3eSoundGetErrorString ()
S3E_API int | s3eSoundGetFreeChannel ()
S3E_API int32 | s3eSoundGetInt (s3eSoundProperty property)
S3E_API void | s3eSoundPauseAllChannels ()
S3E_API void | s3eSoundResumeAllChannels ()
S3E_API s3eResult | s3eSoundSetInt (s3eSoundProperty property, int32 value)
S3E_API void | s3eSoundStopAllChannels ()

Detailed Description

For more information on the Sound functionality provided by the S3E module, see the S3E Sound section of the S3E API Documentation.

Define Documentation

#define S3E_SOUND_MAX_FREQ 0x40000

The maximum frequency for any frequency reference in this module.

Required Header Files
s3eSound.h

#define S3E_SOUND_MAX_VOLUME 0x100

The maximum volume for any volume reference in this module.

Required Header Files
s3eSound.h

Enumeration Type Documentation

enum s3eSoundChannelCallback

Sound channel callbacks.

Remarks:
There are three sound channel callbacks. A handling function for each callback can be registered using the s3eSoundChannelRegister() function. Channel callbacks only apply to the channel for which they are registered. Each of the handling functions is passed a data structure when it is called. Each structure allows the registered callback function to augment the behaviour of the associated channel.

These callbacks are usually called by system-level sound devices, which may be in a separate thread to normal S3E application execution. The S3E API is not thread-safe so no S3E API functions should be called from within any of these callbacks, with the exception of s3eSoundChannelGetInt and s3eSoundGetInt.

Required Header Files
s3eSound.h
Enumerator:
S3E_CHANNEL_END_SAMPLE A handler function registered for this callback will be called when a sample has finished playing.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to s3eSoundEndSampleInfo.
Returns:
If the registered callback returns a non-zero value, the sample will be played again.
S3E_CHANNEL_GEN_AUDIO The generate audio callback allows you to implement custom audio generation.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to s3eSoundGenAudioInfo.
Returns:
The callback should return the number of samples it wrote.
S3E_CHANNEL_STOP_AUDIO This callback will be called when the channel is stopped.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to s3eSoundEndSampleInfo.
Returns:
No return value is expected from a callback registered using this enumeration.
S3E_CHANNEL_GEN_AUDIO_STEREO The generate audio callback allows you to implement custom audio generation.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is a pointer to s3eSoundGenAudioInfo.
Returns:
The callback should return the number of samples it wrote.

enum s3eSoundChannelProperty

Sound channel properties.

Required Header Files
s3eSound.h
Enumerator:
S3E_CHANNEL_PITCH | [read, write] Sound channel pitch (channel frequency/default frequency) in .16 fixed point format. 0x10000 represents normal pitch, 0x20000 represents +1 octave, 0x8000 represents -1 octave, etc. This sets the channel rate to (S3E_CHANNEL_PITCH * S3E_SOUND_DEFAULT_FREQ)/0x10000 Attempting to set the channel rate above S3E_SOUND_MAX_FREQ will cause the rate to be capped to S3E_SOUND_MAX_FREQ, and the pitch will be capped accordingly.
S3E_CHANNEL_RATE | [read, write] Sound channel frequency in Hz. Attempting to set a rate above S3E_SOUND_MAX_FREQ will set the rate to S3E_SOUND_MAX_FREQ. This defaults to the sound property S3E_SOUND_DEFAULT_FREQ, which in turn defaults to 11000. This has no effect of channels that use callbacks to generate audio data.
S3E_CHANNEL_USERVAR | [read, write] Sound channel user variable. This is provided for use by the user as a convient place to store per-channel data and is not read or written by the system. This has no effect of channels that use callbacks to generate audio data.
S3E_CHANNEL_VOLUME | [read, write] Sound channel volume, in .8 fixed point format, S3E_SOUND_MAX_VOLUME(0x100) represents maximum volume. An attempt to set a volume greater than this will set a volume of S3E_SOUND_MAX_VOLUME. This has no effect of channels that use callbacks to generate audio data.
S3E_CHANNEL_STATUS | [read] returns channel playing status. This is 1 if channel is playing, otherwise 0.
S3E_CHANNEL_PAUSED | [read] returns channel paused status. This is 1 if channel is paused, otherwise 0 (playing or stopped).

enum s3eSoundError

Sound Errors.

See also:
s3eSoundGetError

s3eSoundGetErrorString

Required Header Files
s3eSound.h
Enumerator:
S3E_SOUND_ERR_NONE | No Error.
S3E_SOUND_ERR_PARAM | Invalid parameter.
S3E_SOUND_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_SOUND_ERR_ALREADY_REG | The specified callback is already registered.
S3E_SOUND_ERR_NOT_FOUND | No free sound channel exists / The specified callback was not found for removal.
S3E_SOUND_ERR_UNAVAIL | Sound is unavailable.

enum s3eSoundProperty

Sound Properties.

See also:
s3eSoundGetInt

s3eSoundSetInt

Required Header Files
s3eSound.h
Enumerator:
S3E_SOUND_VOLUME | [read, write] Master sound volume. In .8 fixed point format, 0x100 (S3E_SOUND_MAX_VOLUME) repesents maximum volume. Initially this will return the same value as the S3E_SOUND_VOLUME_DEFAULT property
S3E_SOUND_OUTPUT_FREQ | [read, int] The frequency at which the output device is running. This is only of concern when using the generate audio callbacks.
S3E_SOUND_DEFAULT_FREQ | [read, write, int] Default frequency at which all channels will play at, in Hz. This defaults to 11000. This has no effect of channels that play sound using the audio generation callbacks.
S3E_SOUND_NUM_CHANNELS | [read,int] The number of (software) channels available to the user.
S3E_SOUND_USED_CHANNELS | [read,int] A 32-bit mask where 0 in bit n indicates channel n is free. Any invalid channel will be marked with a '1'.
S3E_SOUND_AVAILABLE | [read, int] Returns 1 if sound device is available, 0 otherwise.
S3E_SOUND_VOLUME_DEFAULT [read,int] Default sound volume. The property S3E_SOUND_VOLUME is set to this value on startup.

This value is in .8 fixed point format, 0x100 (S3E_SOUND_MAX_VOLUME) is the maximum possible default volume.

This value is device-dependent, so that the result of playing sound at default volume produces the same audible result across all devices.

S3E_SOUND_STEREO_ENABLED | [read,int] Return 1 is the sound device is in stereo mode. This is enabled by setting the [S3E] StereoSound option in your ICF. If the hardware does not support stereo this will always return 0. In order to generate stereo sound you must register the S3E_CHANNEL_GEN_AUDIO_STEREO callback on your channel(s).

Function Documentation

S3E_API int32 s3eSoundChannelGetInt | ( | int | channel,
 |  | s3eSoundChannelProperty | property
 | ) |  |

Retrieve an integer property for this channel.

Parameters:
channel | Channel to get property from.
property | property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if property is not valid or channel is not valid
See also:
s3eSoundGetInt

s3eSoundSetInt

s3eSoundChannelSetInt

s3eSoundChannelProperty

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelPause ( int channel )

Pause a specified channel.

Parameters:
channel The ID of the channel to pause.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid.
Remarks:
This function does not fail if channel is already paused or is stopped.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundResumeChannel

s3eSoundPauseAllChannels

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelPlay | ( | int | channel,
 |  | int16 * | start,
 |  | uint32 | numSamples,
 |  | int32 | repeat,
 |  | int32 | loopfrom
 | ) |  |

Plays a sound sample on a specified channel.

Parameters:
start | Pointer to the start of the sound data, in memory.
numSamples | Number of 16-bit samples to play.
repeat | one of the following values: 0 = Play forever, 1 = Play once, >1 = Play a certain number of times.
channel | The ID of the channel on which to play.
loopfrom | If a repeat (loop) is specified for this sample, playback for the repeat will begin from this index.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid, start is NULL or numSamples is 0
Remarks:
Channel channel will begin playing the sound effect. Use s3eSoundChannelSetInt() to change channel volume and pitch properties. If channel is already playing, it will begin playing the new sample data without any call to S3E_CHANNEL_END_SAMPLE or S3E_CHANNEL_STOP_AUDIO callbacks
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelRegister | ( | int | channel,
 |  | s3eSoundChannelCallback | cbid,
 |  | s3eCallback | func,
 |  | void * | userData
 | ) |  |

Register a callback for a given event on a specific channel. The available callback types are listed in s3eSoundChannelCallback.

Parameters:
channel | Channel ID of channel to register for.
cbid | ID of the callback to register.
func | Pointer to callback function.
userData | User pointer that will be passed to func when it is called.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid, cbid is invalid or func is NULL.
Remarks:
Only one function may be associated with each event on a particular channel. Once a callback is established for a particular channel and event, subsequent calls to s3eSoundChannelRegister() with the same channel and event as parameters will replace the callback.

Sound channel callbacks do not cause s3eDeviceYieldUntilEvent to return.

Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eSoundChannelCallback enum.

It is not necessary to define a return value for any registered callback.

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelResume ( int channel )

Resume a specified channel.

Parameters:
channel The ID of the channel to resume.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid.
Remarks:
This function does not fail if channel is not in paused state.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundPauseChannel

s3eSoundResumeAllChannels

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelSetInt | ( | int | channel,
 |  | s3eSoundChannelProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this channel.

Parameters:
channel | Channel on which to set property.
property | Property to set.
value | The new value for the stated property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid, property is invalid or value is invalid
Remarks:
This can be used to set
  • pitch via S3E_CHANNEL_PITCH.
  • rate via S3E_CHANNEL_RATE.
  • user variable via S3E_CHANNEL_USERVAR.
  • volume via S3E_CHANNEL_VOLUME. Note that unlike changes to channel playing state, changes to properties are synchronous and effective immediately.
See also:
s3eSoundGetInt

s3eSoundSetInt

s3eSoundChannelGetInt

s3eSoundChannelProperty

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelStop ( int channel )

Stop a specified channel.

Parameters:
channel The ID of the channel to stop.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid.
Remarks:
This function does not fail if channel is already stopped.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundStopAllChannels

s3eSoundPauseChannel

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundChannelUnRegister | ( | int | channel,
 |  | s3eSoundChannelCallback | cbid
 | ) |  |

Unregister a callback for a given event on a specific channel.

Parameters:
channel | ID of channel to register for.
cbid | ID of callback to un-register.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if channel is invalid or cbid is invalid.
Remarks:
Note that this function is asynchronous and works via sending a message to the playing sound channel. Therefore, it is possible that the unregistered callback may be called in a short period after s3eSoundChannelUnRegister() has been called. The user should be aware of this and not make assumptions about order of events.
Calling s3eSoundChannelUnRegister() on a callback that has not been registered for does not cause an error.
Required Header Files
s3eSound.h

S3E_API s3eSoundError s3eSoundGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eSoundGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files
s3eSound.h

S3E_API const char* s3eSoundGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eSoundGetError
Remarks:
This function, as opposed to s3eSoundGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files
s3eSound.h

S3E_API int s3eSoundGetFreeChannel ( )

Gets the ID of the first available free channel.

Returns:
  • ID of a free channel if a free channel exists.
  • -1 if no channel is free. The next call to s3eSoundGetError() will return S3E_SOUND_ERR_NOT_FOUND.
Remarks:
A channel is free if it is not playing and not paused. Use this function to find a channel that is free, for example s3eSoundChannelPlay(s3eSoundGetFreeChannel(), sampleData, sampleDataLen, 1, 0);

S3E_API int32 s3eSoundGetInt ( s3eSoundProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if property is not valid.
See also:
s3eSoundSetInt

S3E_API void s3eSoundPauseAllChannels ( )

Pauses sound on all channels.

Remarks:
This is equivalent to calling s3eSoundChannelPause(i) for i = 0 ... S3E_SOUND_NUM_CHANNELS. All sound channels will go into paused state.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundResumeAllChannels

s3eSoundPauseChannel

Required Header Files
s3eSound.h

S3E_API void s3eSoundResumeAllChannels ( )

Resumes sound on all channels.

Remarks:
Any sound channels that are paused will resume playing. Any sound channels that are not paused will be unaffected.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundPauseAllChannels

s3eSoundResumeChannel

Required Header Files
s3eSound.h

S3E_API s3eResult s3eSoundSetInt | ( | s3eSoundProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSoundGetError() to retrieve an error code. This will return:
    • S3E_SOUND_ERR_PARAM if property is invalid or value is invalid.
Remarks:
This can be used with S3E_SOUND_VOLUME or S3E_SOUND_DEFAULT_FREQ to set the master sound volume and default channel frequency respectively. Setting volume higher than S3E_SOUND_MAX_VOLUME will cause the volume to be clipped to S3E_SOUND_MAX_VOLUME. However setting default frequency above S3E_SOUND_MAX_FREQ will cause a failure with error S3E_SOUND_ERR_PARAM.
See also:
s3eSoundGetInt
Required Header Files
s3eSound.h

S3E_API void s3eSoundStopAllChannels ( )

Stops sound on all channels.

Remarks:
Any sound channels that are paused or playing will go into stopped state. After this call, all sound channels are guaranteed to be in stopped state.
Note:
Changing the playing status of sound channels is an asynchronous operation, and the status may not change until 10's of milliseconds (and possibly a call to s3eDeviceYield()) after the call.
See also:
s3eSoundStopChannel

s3eSoundPauseChannel

Required Header Files
s3eSound.h


Airplay API Reference: S3E Sound Examples

Airplay API Reference > S3E API Documentation > S3E Sound > S3E Sound Examples >

S3E Sound Examples

This section illustrates how you can use the sound functionality provided by S3E. This section contains three example applications:

  • S3E Sound Basic Example
  • S3E Sound Advanced Example
  • S3E Sound Streaming Example

Note: For more information on the S3E Sound functionality, see the S3E Sound Overview.


Airplay API Reference: S3E Sound Basic Example

Airplay API Reference > S3E API Documentation > S3E Sound > S3E Sound Examples > S3E Sound Basic Example >

S3E Sound Basic Example

The following example uses S3E's sound functionality to play a raw file and allow you to control the volume using the keyboard.

The main functions used to achieve this are:

  • s3eFileOpen()
  • s3eFileGetSize()
  • s3eMallocBase()
  • s3eFileRead()
  • s3eSoundGetFreeChannel()
  • s3eSoundSetInt()
  • s3eSoundChannelPlay()
  • s3eSoundChannelStop()
  • s3eSoundGetInt()
  • s3eSoundSetInt()

This example loads a sound file and reserves a sound channel for playback. Based on which buttons are pressed you can change playback and the volume.

The volume is changed by first getting the value representing the volume using the s3eSoundGetInt() function and passing it the S3E_SOUND_VOLUME value, and then changing the value by the required amount and passing it to the s3eSoundSetInt() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

static int16*   g_SoundBuffer;
static char     g_VolumeString[256];
static int32    g_FileSize;
static int      g_Channel;
static bool     g_IsPlaying; // True if we're playing a sample
static Button*  g_ButtonPlay = 0;
static Button*  g_ButtonStop = 0;
static Button*  g_ButtonVolumeUp = 0;
static Button*  g_ButtonVolumeDown = 0;

//-----------------------------------------------------------------------------
//This function increases the volume.
//-----------------------------------------------------------------------------
void VolumeUp()
{
    int32 temp = s3eSoundGetInt(S3E_SOUND_VOLUME);

    temp += 10;

    if (temp >S3E_SOUND_MAX_VOLUME)
        temp = S3E_SOUND_MAX_VOLUME;

    s3eSoundSetInt(S3E_SOUND_VOLUME, temp);

    sprintf(g_VolumeString, "`x666666Volume level: %ld", temp);
}

//-----------------------------------------------------------------------------
// This function decreases the volume.
//-----------------------------------------------------------------------------
void VolumeDown()
{
    int32 temp = s3eSoundGetInt(S3E_SOUND_VOLUME);

    temp -= 10;

    if(temp < 0)
        temp = 0;

    s3eSoundSetInt(S3E_SOUND_VOLUME, temp);

    sprintf(g_VolumeString, "`x666666Volume level: %ld", temp);
}

//-----------------------------------------------------------------------------
// The following function opens and reads the specified file into memory. It
// also reserves a channel on which to play sound and sets the frequency at
// which the sound will be played.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Read in sound data
    s3eFile *fileHandle = s3eFileOpen("test.raw", "rb");

    g_FileSize = s3eFileGetSize(fileHandle);
    g_SoundBuffer = (int16*)s3eMallocBase(g_FileSize);
    memset(g_SoundBuffer, 0, g_FileSize);
    s3eFileRead(g_SoundBuffer, g_FileSize, 1, fileHandle);
    s3eFileClose(fileHandle);

    // Finds a free channel that we can use to play our raw file on.
    g_Channel = s3eSoundGetFreeChannel();

    // Setting default frequency at which all channels will play at, in Hz.
    s3eSoundSetInt(S3E_SOUND_DEFAULT_FREQ, 8000);

    g_ButtonPlay                = NewButton("Play");
    g_ButtonStop                = NewButton("Stop");
    g_ButtonVolumeUp            = NewButton("Volume Up");
    g_ButtonVolumeDown          = NewButton("Volume Down");
}

void ExampleShutDown()
{
}

//-----------------------------------------------------------------------------
// The following function checks which buttons are pressed and changes sound playback
// and the volume accordingly. The volume is controlled using the volumeUp()
// and volumeDown() functions.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (pressed == g_ButtonPlay && !g_IsPlaying)
    {
        // Play the sound. Note that the 3rd paramater needs to be the number of samples to play, which
        // is the number of bytes divided by 2. A repeat count of 0 means 'play forever'.
        if (s3eSoundChannelPlay(g_Channel, g_SoundBuffer, g_FileSize/2, 0, 0) == S3E_RESULT_ERROR)
            sprintf(g_VolumeString, "Error in s3eSoundChannelPlay");
        else
            g_IsPlaying = true;
    }

    if (pressed == g_ButtonStop && g_IsPlaying)
    {
        if (s3eSoundChannelStop(g_Channel) == S3E_RESULT_ERROR)
            sprintf(g_VolumeString, "Error in s3eSoundChannelStop");
        else
            g_IsPlaying = false;
    }

    // Press up to increase volume
    if (pressed == g_ButtonVolumeUp && g_IsPlaying)
        VolumeUp();

    // Press down to decrease volume
    if (pressed == g_ButtonVolumeDown && g_IsPlaying)
        VolumeDown();

    return true;
}

//-----------------------------------------------------------------------------
// The following function displays the details of sound playback on screen by
// indicating the controls that can be used to change the state of playback
// and volume.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    // Display menu
    int y = GetYBelowButtons() + 2 * textHeight;
    int x = 10;

    g_ButtonPlay->m_Enabled = !g_IsPlaying;
    g_ButtonStop->m_Enabled = g_IsPlaying;
    g_ButtonVolumeUp->m_Enabled = g_IsPlaying;
    g_ButtonVolumeDown->m_Enabled = g_IsPlaying;

    // Display info
    s3eDebugPrint(x, y, g_VolumeString, 0);
    y += 2 * textHeight;

    if (g_IsPlaying)
        s3eDebugPrint(10, y, "`x666666Sound is playing", 0);
}


Airplay API Reference: S3E Sound Advanced Example

Airplay API Reference > S3E API Documentation > S3E Sound > S3E Sound Examples > S3E Sound Advanced Example >

S3E Sound Advanced Example

The following example uses S3E's sound functionality to play a raw file and allow you to change its volume as in the S3E Basic Sound Example. It also allows you to change the pitch of the sound playing using the keys or by invoking an automatic pitch shifter.

The functions used to achieve this are:

  • s3eSoundChannelGetInt()
  • s3eSoundChannelSetInt()
  • s3eSoundGetInt()
  • s3eSoundSetInt()
  • s3eSoundChannelRegister()
  • s3eSoundGetFreeChannel()

The ExampleInit() function finds a free channel on which to play sound and reads in a .raw file so that it can be played. It also sets up callback function thats a global value indicating that a message should be displayed saying playback has ended.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

#define PITCH_SHIFT_DELAY       50
#define PITCH_SHIFT_RANGE       19

void*   g_SoundData;                    // Buffer that holds the sound data

char    g_VolumeString[50];             // Contains info about the volume for displaying
char    g_PitchString[50];              // Contains info about the pitch for displaying

int32   g_FileSize;                     // Size of the sound file

uint64  g_PitchUpdateTime = 0;          // Timer for auto-wahwah effect
int32   g_StartingPitch;                // Remember starting pitch for reset

int     g_Channel;               // Free channel which is being used for the playing of the sample

bool    g_IsPlaying;                    // True if we're playing a sample

bool    g_UseWhaWha = false;            // Use auto-pitch shifting yes/no?
bool    g_DisplayEndofSample = false;   // SIplay end-of-sample message yes/no?
uint64  g_EndofSampleTime = 0;          // Make sure end-of-sample message is only displayed a set amount of time

Button* g_ButtonPlay = 0;
Button* g_ButtonStop = 0;
Button* g_ButtonToggleWaaWaa = 0;
Button* g_ButtonVolumeUp = 0;
Button* g_ButtonVolumeDown = 0;
Button* g_ButtonPitchUp = 0;
Button* g_ButtonPitchDown = 0;

bool    g_NeverPlayed = true;           // True if we've never played a sound

//-----------------------------------------------------------------------------
// The following function increases the volume in increments of ten. It uses
// the s3eSoundGetInt() function to first get the current volume and then it
// uses the s3eSoundSetIn() function to set the volume to a level of ten above
// the original.
//-----------------------------------------------------------------------------
void VolumeUp()
{
    int32 TempVolume = s3eSoundGetInt(S3E_SOUND_VOLUME);

    TempVolume += 10;

    if (TempVolume >S3E_SOUND_MAX_VOLUME)
        TempVolume = S3E_SOUND_MAX_VOLUME;

    s3eSoundSetInt(S3E_SOUND_VOLUME, TempVolume);

    sprintf(g_VolumeString, "`x666666Volume level: %ld", TempVolume);
}

//-----------------------------------------------------------------------------
// This function decreases the volume in increments of ten. It uses
// the s3eSoundGetInt() function to first get the current volume and then it
// uses the s3eSoundSetIn() function to set the volume to a level of ten below
// the original.
//-----------------------------------------------------------------------------
void VolumeDown()
{
    int32 TempVolume = s3eSoundGetInt(S3E_SOUND_VOLUME);

    TempVolume -= 10;

    if (TempVolume < 0)
        TempVolume = 0;

    s3eSoundSetInt (S3E_SOUND_VOLUME, TempVolume);
    sprintf(g_VolumeString, "`x666666Volume level: %ld", TempVolume);
}

//-----------------------------------------------------------------------------
// This function increases the pitch in increments of 0x400. It uses
// the s3eSoundChannelGetInt() function to first the current pitch and then it
// uses the s3eSoundChannelSetInt() function to set the pitch to a level of
// 0x400 above the original.
//-----------------------------------------------------------------------------
void PitchUp()
{
    int32 TempPitch = s3eSoundChannelGetInt (g_Channel, S3E_CHANNEL_PITCH);
    s3eSoundChannelSetInt(g_Channel, S3E_CHANNEL_PITCH, TempPitch+0x400);
    sprintf(g_PitchString, "`x666666Pitch level is: %ld", s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH));
}

//-----------------------------------------------------------------------------
// This function decrements the pitch by 0x400. It uses
// the s3eSoundChannelGetInt() function to first the current pitch and then it
// uses the s3eSoundChannelSetInt() function to set the pitch to a level of
// 0x400 above the original.
//-----------------------------------------------------------------------------
void PitchDown()
{
    int32 TempPitch = s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH);
    s3eSoundChannelSetInt(g_Channel, S3E_CHANNEL_PITCH, TempPitch-0x400);
    sprintf(g_PitchString, "`x666666Pitch level is: %ld", s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH));
}

//-----------------------------------------------------------------------------
// The following function cycles the pitch up and down using a timer.
//-----------------------------------------------------------------------------
void WhaWha()
{
    static int  counter = 0;
    static bool shiftUp = false;

    if ((s3eTimerGetMs() - g_PitchUpdateTime) > PITCH_SHIFT_DELAY)
    {
        if (shiftUp == true)
            PitchUp();
        else
            PitchDown();

        g_PitchUpdateTime = s3eTimerGetMs();
        counter++;

        // After PITCH_SHIFT_RANGE reverse pitch changing direction
        if (counter > PITCH_SHIFT_RANGE)
        {
            counter = 0;
            shiftUp = !shiftUp;
        }
    }
}

//-----------------------------------------------------------------------------
// The following function is registered as a callback function to be called
// when the S3E_CHANNEL_END_SAMPLE event has occurred.
//-----------------------------------------------------------------------------
int32 OnEndOfSample(void * _systemData, void* userData)
{
    // When the end of the sample is reached, set a global variable to cause
    // a message to be displayed.
    g_DisplayEndofSample = true;

    // ExampleUpdate will start a timer to make sure that the sample is just
    // being displayed for a set period of time
    g_EndofSampleTime = 0;

    // Return 1 to indicate to the sound system that the sample should repeat
    return 1;
}

//-----------------------------------------------------------------------------
// The following function opens the sample raw file and loads it into memory.
// It also finds a free channel on which the sound can be played using
// s3eSoundGetFreeChannel(). A callback for the S3E_CHANNEL_END_SAMPLE event
// is set using the s3eSoundChannelRegister() function.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Read in sound data
    s3eFile *fileHandle = s3eFileOpen("test.raw", "rb");

    g_FileSize = s3eFileGetSize(fileHandle);
    g_SoundData = s3eMallocBase(g_FileSize);
    memset(g_SoundData, 0, g_FileSize);
    s3eFileRead(g_SoundData, g_FileSize, 1, fileHandle);
    s3eFileClose(fileHandle);

    // Finds a free channel that we can use to play our raw file on.
    g_Channel = s3eSoundGetFreeChannel();

    // Remember original pitch
    g_StartingPitch = s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH);

    // Register callback for detecting end of sample
    s3eSoundChannelRegister(g_Channel, S3E_CHANNEL_END_SAMPLE, &OnEndOfSample, NULL);

    s3eSoundSetInt(S3E_SOUND_DEFAULT_FREQ, 8000);

    // Initializing output strings
    sprintf(g_VolumeString, "`x666666Volume level: %ld", s3eSoundGetInt(S3E_SOUND_VOLUME));
    sprintf(g_PitchString, "`x666666Pitch level is: %ld", s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH));

    g_ButtonPlay                = NewButton("Play");
    g_ButtonStop                = NewButton("Stop");
    g_ButtonToggleWaaWaa        = NewButton("Toggle WaaWaa");
    g_ButtonVolumeUp            = NewButton("Volume Up");
    g_ButtonVolumeDown          = NewButton("Volume Down");
    g_ButtonPitchUp             = NewButton("Pitch Up");
    g_ButtonPitchDown           = NewButton("Pitch Down");

    if (g_DeviceHasKeyboard)
    {
        g_ButtonVolumeUp->m_Display     = false;
        g_ButtonVolumeDown->m_Display   = false;
        g_ButtonPitchUp->m_Display      = false;
        g_ButtonPitchDown->m_Display    = false;
    }
}

void ExampleShutDown()
{
}

//-----------------------------------------------------------------------------
// The following function checks which buttons where pressed and changes the state
// of sound playback, the volume and the pitch based on it. Playback is
// started using the s3eSoundChannelPlay() function and stopped using the
// s3eSoundChannelStop() function.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    // work out which button was pressed
    if (g_DeviceHasKeyboard)
    {
        if (s3eKeyboardGetState(s3eKeyUp) & S3E_KEY_STATE_PRESSED)
            pressed = g_ButtonVolumeUp;

        if (s3eKeyboardGetState(s3eKeyDown) & S3E_KEY_STATE_PRESSED)
            pressed = g_ButtonVolumeDown;

        if (s3eKeyboardGetState(s3eKeyRight) & S3E_KEY_STATE_PRESSED)
            pressed = g_ButtonPitchUp;

        if (s3eKeyboardGetState(s3eKeyLeft) & S3E_KEY_STATE_PRESSED)
            pressed = g_ButtonPitchDown;
    }

    if (pressed == g_ButtonPlay && !g_IsPlaying)
    {
        // Play the sound. Note that the 3rd paramater needs to be the number of samples to play, which
        // is the number of bytes divided by 2. A repeat count of 0 means 'play forever'.
        s3eSoundChannelPlay(g_Channel, (int16 *)g_SoundData, g_FileSize/2, 0, 0);
        g_IsPlaying = true;
        g_NeverPlayed = false;
    }

    if (pressed == g_ButtonStop && g_IsPlaying)
    {
        s3eSoundChannelStop(g_Channel);
        g_IsPlaying = false;
    }

    if (pressed == g_ButtonToggleWaaWaa)
    {
        // Start WahwahTimer
        g_PitchUpdateTime = s3eTimerGetMs();
        g_UseWhaWha = !g_UseWhaWha;

        // On stopping whawha effect reset to original value
        s3eSoundChannelSetInt(g_Channel, S3E_CHANNEL_PITCH, g_StartingPitch);
        sprintf(g_PitchString, "`x666666Pitch level is: %ld", s3eSoundChannelGetInt(g_Channel, S3E_CHANNEL_PITCH));
    }

    if (pressed == g_ButtonVolumeUp && g_IsPlaying)
        VolumeUp();

    if (pressed == g_ButtonVolumeDown && g_IsPlaying)
        VolumeDown();

    if (pressed == g_ButtonPitchUp && g_IsPlaying)
        PitchUp();

    if (pressed == g_ButtonPitchDown && g_IsPlaying)
        PitchDown();

    if (g_UseWhaWha == true && g_IsPlaying)
        WhaWha();

    // Start the timer in order to make sure that the sample is just being displayed
    // for a set periodof time. Cannot use s3e API (e.g. s3eTimerGetMs) within the
    // callback as it is not thread-safe
    if (g_DisplayEndofSample == true && g_EndofSampleTime == 0)
        g_EndofSampleTime = s3eTimerGetMs();

    // Make sure the displaying of the "end-of-sample" message lasts only for a set amount of time
    if (s3eTimerGetMs() - g_EndofSampleTime > 2000)
    {
        g_DisplayEndofSample = false;
        g_EndofSampleTime = 0;
    }

    return true;
}

const char* GetKeyName(s3eKey key)
{
    static char name[64];
    s3eKeyboardGetDisplayName(name, key, 1);
    return name;
}

//-----------------------------------------------------------------------------
// The following function displays the controls that can be used to change
// the state of playback and the current values for the pitch and the volume.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    // Display menu
    int x = 10;

    g_ButtonPlay->m_Enabled = !g_IsPlaying;
    g_ButtonStop->m_Enabled = g_IsPlaying;
    g_ButtonToggleWaaWaa->m_Enabled = g_IsPlaying;
    g_ButtonVolumeUp->m_Enabled = g_IsPlaying;
    g_ButtonVolumeDown->m_Enabled = g_IsPlaying;
    g_ButtonPitchUp->m_Enabled = g_IsPlaying;
    g_ButtonPitchDown->m_Enabled = g_IsPlaying;

    // get a safe Y location below all the buttons
    int y = GetYBelowButtons();

    if (g_DeviceHasKeyboard)
    {
        y += textHeight;

        if (g_IsPlaying)
        {
            s3eDebugPrint(x, y, "`x666666Up/Down: Change volume", 0);
            y += textHeight;
            s3eDebugPrint(x, y, "`x666666Left/Right: Change pitch", 0);
        }
        else
        {
            s3eDebugPrint(x, y, "`xa0a0a0Up/Down: Change volume", 0);
            y += textHeight;
            s3eDebugPrint(x, y, "`xa0a0a0Left/Right: Change pitch", 0);
        }

        y += 2 * textHeight;
    }

    // Display info
    s3eDebugPrint(x, y, g_VolumeString, 0);
    y += textHeight;
    s3eDebugPrint(x, y, g_PitchString, 0);
    y += 2 * textHeight;

    if (g_DisplayEndofSample)
    {
        s3eDebugPrint(x, y, "`x666666End of sample!", 0);
    }
}


Airplay API Reference: S3E Sound Streaming Example

Airplay API Reference > S3E API Documentation > S3E Sound > S3E Sound Examples > S3E Sound Streaming Example >

S3E Sound Streaming Example

The following example uses S3E's sound functionality to play audio using a custom generator through callbacks. It also demonstrates the use of stereo functionality.

The functions used to achieve this are:

  • s3eSoundGetInt()
  • s3eSoundChannelRegister()
  • s3eSoundChannelPlay()
  • s3eSoundChannelStop()

The ExampleInit() function finds a free channel on which to play sound, reads in a .raw file to play and registers callback functions for S3E_CHANNEL_END_SAMPLE and S3E_CHANNEL_GEN_AUDIO. Once a function is registered for S3E_CHANNEL_GEN_AUDIO - in this case AudioCallback() - Airplay will now call this function in order to generate and mix audio for the given channel rather than using the default mixer functionality. The systemData parameter passed to this function provides information on the channel being played (see s3eSoundGenAudioInfo).

ExampleUpdate() checks for button presses to stop/start audio and switch between mono and sterio sound, which is done by registering/unregistering our AudioCallback() function for S3E_CHANNEL_GEN_AUDIO_STEREO. The user can also switch between left/right/both audio channels when in sterio mode, which is handled by this custom mixing function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include <stdlib.h>

int16*  g_SoundData;        // Buffer that holds the sound data
int     g_SoundLen;         // Length of sound data
int     g_SoundPos;         // Current playback position
int     g_PlayingChannel;   // Free channel being used for playing of the sample
bool    g_Playing = false;  // True if we're playing a sample
int     g_Mode = 0;         // Stereo channel mode: 0 Both, 1 Left, 2 Right
Button* g_PlayButton;
Button* g_StopButton;
Button* g_StereoButton;
Button* g_PlayStereoButton;

//-----------------------------------------------------------------------------
// The following function is registered as a callback function to be called
// when the S3E_CHANNEL_END_SAMPLE event has occurred.
//-----------------------------------------------------------------------------
int32 EndSampleCallback(void* sys, void* user)
{
    s3eSoundEndSampleInfo* info = (s3eSoundEndSampleInfo*)sys;
    g_SoundPos = 0;
    return info->m_RepsRemaining;
}

INLINE int16 ClipToInt16(int32 sval)
{
    enum
    {
        minval =  INT16_MIN,
        maxval =  INT16_MAX,
        allbits = UINT16_MAX
    };

    // quick overflow test, the addition moves valid range to 0-allbits
    if ((sval-minval) & ~allbits)
    {
        // we overflowed.
        if (sval > maxval)
            sval = maxval;
        else
            if (sval < minval)
                sval = minval;
    }

    return (int16)sval;
}

//-----------------------------------------------------------------------------
// The following function is registered as a callback function to be called
// when the S3E_CHANNEL_GEN_AUDIO or S3E_CHANNEL_GEN_AUDIO_STEREO events occur.
// It is called whenever more audio data is required and processes the raw
// data loaded in ExampleInit(), mixing for mono/stereo depending on user
// input from ExampleUpdate(). The function receives sample information as the
// sys parameter and returns the number of samples generated.
//-----------------------------------------------------------------------------
int32 AudioCallback(void* sys, void* user)
{
    s3eSoundGenAudioInfo* info = (s3eSoundGenAudioInfo*)sys;
    int* pos = (int*)user;
    info->m_EndSample = 0;
    int samples_played = 0;
    int16* target = (int16*)info->m_Target;
    int16* src = info->m_OrigStart+*pos;
    int16* end = info->m_OrigStart+info->m_OrigNumSamples;

    for (uint i = 0; i < info->m_NumSamples; i++)
    {
        if (src >= end)// || src >= info->m_OrigStart + 10000)
        {
            //s3eDebugTraceLine("end of sound reached");
            info->m_EndSample = 1;
            *pos = 0;
            g_Playing = false;
            break;
        }

        int16 orig = 0;

        if (info->m_Mix)
            orig = *target;

        if (info->m_Stereo)
        {
            switch (g_Mode)
            {
                case 0:
                    *target++ = ClipToInt16(*src + orig);
                    *target++ = ClipToInt16(*src + orig);
                    break;
                case 1:
                    *target++ = ClipToInt16(*src + orig);
                    *target++ = ClipToInt16(orig);
                    break;
                case 2:
                    *target++ = ClipToInt16(orig);
                    *target++ = ClipToInt16(*src + orig);
                    break;
            }
        }
        else
        {
            *target++ = ClipToInt16(*src + orig);
        }

        samples_played++;
        src++;
    }

    *pos += samples_played;
    return samples_played;
}

//-----------------------------------------------------------------------------
// The following function opens the sample raw file and loads it into memory.
// It also finds a free channel on which the sound can be played using
// s3eSoundGetFreeChannel() and registers callbacks for the
// S3E_CHANNEL_END_SAMPLE and S3E_CHANNEL_GEN_AUDIO events using the
// s3eSoundChannelRegister() function.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    g_PlayButton = NewButton("Play");
    g_StopButton = NewButton("Stop");
    g_PlayStereoButton = NewButton("Play Stereo");
    g_StereoButton = NewButton("Change Stereo Mode");

    if (s3eSoundGetInt(S3E_SOUND_STEREO_ENABLED))
    {
        g_PlayStereoButton->m_Enabled = false;
        g_StopButton->m_Enabled = false;
    }

    // Read in sound data
    s3eFile *fileHandle = s3eFileOpen("test.raw", "rb");
    g_SoundPos = 0;
    g_SoundLen = s3eFileGetSize(fileHandle);
    g_SoundData = (int16*)malloc(g_SoundLen);
    memset(g_SoundData, 0, g_SoundLen);
    s3eFileRead(g_SoundData, g_SoundLen, 1, fileHandle);
    s3eFileClose(fileHandle);

    // Finds a free channel that we can use to play our raw file on.
    g_PlayingChannel = s3eSoundGetFreeChannel();
    s3eSoundChannelRegister(g_PlayingChannel, S3E_CHANNEL_GEN_AUDIO, AudioCallback, &g_SoundPos);
    s3eSoundChannelRegister(g_PlayingChannel, S3E_CHANNEL_END_SAMPLE, EndSampleCallback, NULL);
}

//-----------------------------------------------------------------------------
// Do cleanup work
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    free(g_SoundData);
}

//-----------------------------------------------------------------------------
// The following function checks which buttons where pressed and changes
// between mono and sterio sound playback - by registering/unregistering
// AudioCallback() as the S3E_CHANNEL_GEN_AUDIO_STEREO function - or
// cycles through left/right/both stereo channels.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (!g_Playing)
    {
        if (pressed == g_PlayButton)
        {
            g_SoundPos = 0;
            s3eSoundChannelUnRegister(g_PlayingChannel, S3E_CHANNEL_GEN_AUDIO_STEREO);
            s3eSoundChannelPlay(g_PlayingChannel, g_SoundData, g_SoundLen, 10, 0);
            g_Playing = true;
        }
        else if (pressed == g_PlayStereoButton)
        {
            g_SoundPos = 0;
            s3eSoundChannelRegister(g_PlayingChannel, S3E_CHANNEL_GEN_AUDIO_STEREO, AudioCallback, &g_SoundPos);
            s3eSoundChannelPlay(g_PlayingChannel, g_SoundData, g_SoundLen, 10, 0);
            g_Playing = true;
        }
    }
    else if (pressed == g_StopButton)
    {
        s3eSoundChannelStop(g_PlayingChannel);
        g_Playing = false;
    }
    if (pressed == g_StereoButton)
    {
        g_Mode = (g_Mode + 1) % 3;
    }
    return true;
}

const char* GetKeyName(s3eKey key)
{
    static char name[64];
    s3eKeyboardGetDisplayName(name, key, 1);
    return name;
}

//-----------------------------------------------------------------------------
// The following function displays the current playback type and state plus
// controls that can be used to change it.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    if (g_Playing)
    {
        g_PlayButton->m_Enabled = false;
        g_StopButton->m_Enabled = true;
    }
    else
    {
        g_PlayButton->m_Enabled = true;
        g_StopButton->m_Enabled = false;
    }

    int y = GetYBelowButtons() + 3 * textHeight;
    int x = 10;

    if (s3eSoundGetInt(S3E_SOUND_STEREO_ENABLED))
    {
        g_PlayStereoButton->m_Enabled = !g_Playing;

        // get a safe Y location below all the buttons
        switch (g_Mode)
        {
            case 0:
                s3eDebugPrintf(x, y, 0, "`x666666Stereo mode: BOTH");
                break;
            case 1:
                s3eDebugPrintf(x, y, 0, "`x666666Stereo mode: LEFT");
                break;
            case 2:
                s3eDebugPrintf(x, y, 0, "`x666666Stereo mode: RIGHT");
                break;
        }
        y += textHeight;
    }

    int freq = s3eSoundGetInt(S3E_SOUND_OUTPUT_FREQ);
    s3eDebugPrintf(x, y, 0, "`x666666Sound freq : 8000");
    y += textHeight;
    s3eDebugPrintf(x, y, 0, "`x666666Output freq: %d", freq);
}


Airplay API Reference: S3E Surface

Airplay API Reference > S3E API Documentation > S3E Surface >

S3E Surface

The S3E Surface documentation contains the following sections:

  • S3E Surface Overview
  • Surface API Reference
  • S3E Surface Examples


Airplay API Reference: S3E Surface Overview

Airplay API Reference > S3E API Documentation > S3E Surface > S3E Surface Overview >

S3E Surface Overview

The device screen in S3E is represented as a 'Surface' of bitmap data. The Surface Module allows you to change the surface data via s3eSurfacePtr(), then display it on the screen. You can also change the format of the surface data from the native format of the device to any format you would like to work with. Changing the format of the surface data is achieved using the s3eSurfaceSetup() function, and displaying the surface on the device screen is achieved using the s3eSurfaceShow() function. The callback mechanism in the Surface Module to allows you to register a function that is called when the system is about to update the display. This is useful for providing post-processing effects such as blurring or fading. The callback can be registered and unregistered using the s3eSurfaceRegister() and s3eSurfaceUnRegister() functions respectively.

It is possible to increase performance by indicating the surface section which is invalid and therefore needs updating. With this information the application can save time by updating only the indicated section of the surface. The invalid section can be identified using thes3eSurfaceInvalidate() function and then a call to s3eSurfaceShow() will update the screen according to the cumulative area indicated by calls to s3eSurfaceInvalidate().

Note: For an example of how the Surface functionality can be used, see the S3E Surface Examples.

For more information on the functionality outlined in this section, see the Surface API Reference.


Airplay API Reference: Surface API Reference

Airplay API Reference > S3E API Documentation > S3E Surface > Surface API Reference >

Surface API Reference
[S3E]

Data Structures

struct | s3eSurfaceCopyupInfo
struct | s3eSurfaceInfo
struct | s3eSurfaceOrientation

Defines

#define | S3E_SURFACE_PIXEL_SIZE_8 0x0010

Enumerations

enum | s3eSurfaceBlitDirection { , S3E_SURFACE_BLIT_DIR_NATIVE = 4 }
enum s3eSurfaceCallback {
S3E_SURFACE_COPYUP = 0,
S3E_SURFACE_SCREENSIZE = 1
}
enum | s3eSurfaceError
enum | s3eSurfacePixelType
enum s3eSurfaceProperty {
S3E_SURFACE_WIDTH = 0,
S3E_SURFACE_HEIGHT = 1 ,
S3E_SURFACE_BLIT_DIRECTION = 8 ,
S3E_SURFACE_NUM_DISPLAYS = 10,
S3E_SURFACE_DEVICE_BLIT_DIRECTION = 11,
S3E_SURFACE_DEVICE_WIDTH_QUANTISED = 12,
S3E_SURFACE_DEVICE_HEIGHT_QUANTISED = 13
}

Functions

S3E_API uint32 | s3eSurfaceConvertRGB (uint8 r, uint8 g, uint8 b)
S3E_API s3eSurfaceError | s3eSurfaceGetError ()
S3E_API const char * | s3eSurfaceGetErrorString ()
S3E_API int32 | s3eSurfaceGetInt (s3eSurfaceProperty property)
S3E_API void | s3eSurfaceInvalidate (int32 x, int32 y, int32 dx, int32 dy)
S3E_API void * | s3eSurfacePtr ()
S3E_API s3eResult | s3eSurfaceRegister (s3eSurfaceCallback cbid, s3eCallback fn, void *userData)
S3E_API s3eResult | s3eSurfaceSetDisplayID (uint32 id)
S3E_API s3eResult | s3eSurfaceSetup (s3eSurfacePixelType pixelType, uint32 pitch, void *ptr, s3eSurfaceBlitDirection blitDirection)
S3E_API s3eResult | s3eSurfaceShow ()
S3E_API s3eResult | s3eSurfaceUnRegister (s3eSurfaceCallback cbid, s3eCallback fn)

Detailed Description

For more information on the Surface functionality provided by the S3E module, see the S3E Surface section of the S3E API Documentation.

Define Documentation

#define S3E_SURFACE_PIXEL_ORDER_BGR 0x00800

Pixel data is stored with the red colour comoponent in the least signficant bits, and blue in the most significant bits.

#define S3E_SURFACE_PIXEL_ORDER_RGB 0x00400

Pixel data is stored with the red colour comoponent in the most signficant bits, and blue in the least significant bits.

#define S3E_SURFACE_PIXEL_SIZE_16 0x0020

Pixel size is two bytes.

#define S3E_SURFACE_PIXEL_SIZE_24 0x0030

Pixel size is three bytes.

#define S3E_SURFACE_PIXEL_SIZE_32 0x0040

Pixel size is four bytes.

#define S3E_SURFACE_PIXEL_SIZE_8 0x0010

Pixel size is one byte.

Surface pixel types.

Required Header Files
s3eSurface.h

#define S3E_SURFACE_PIXEL_TYPE_444 0x0001

Pixel data is 4 bits per colour, RRRRGGGGBBBB or BBBBGGGGRRRR.

#define S3E_SURFACE_PIXEL_TYPE_555 0x0003

Pixel data is 5 bits per colour channel, RRRRRGGGGGBBBBB or BBBBBGGGGGRRRRR.

#define S3E_SURFACE_PIXEL_TYPE_5551 0x0006

Pixel data is 5 bits red, 6 bits green, 5 bits blue and 1 bit ignored, RRRRRGGGGGGBBBBBX or BBBBBGGGGGGRRRRRX.

#define S3E_SURFACE_PIXEL_TYPE_565 0x0002

Pixel data is 5 bits red, 6 bits green, 5 bits blue, RRRRRGGGGGGBBBBB or BBBBBGGGGGGRRRRR.

#define S3E_SURFACE_PIXEL_TYPE_666 0x0004

Pixel data is 6 bits per colour channel, RRRRRRGGGGGGBBBBBB or BBBBBBGGGGGGRRRRRR.

#define S3E_SURFACE_PIXEL_TYPE_888 0x0005

Pixel data is 8 bits per colour channel, RRRRRRRRGGGGGGGGBBBBBBBB or BBBBBBBBGGGGGGGGRRRRRRRR.

Enumeration Type Documentation

enum s3eSurfaceBlitDirection

Surface blit directions.

Required Header Files:
s3eSurface.h
Enumerator:
S3E_SURFACE_BLIT_DIR_NORMAL | No rotation.
S3E_SURFACE_BLIT_DIR_ROT90 | 90 degrees clockwise rotation copying from source to destination.
S3E_SURFACE_BLIT_DIR_ROT180 | 180 degrees rotation copying from source to destination.
S3E_SURFACE_BLIT_DIR_ROT270 | 270 degrees clockwise rotation copying from source to destination.
S3E_SURFACE_BLIT_DIR_NATIVE | For use with s3eSurfaceSetup; This prevents any rotated copy occurring during s3eSurfaceShow

enum s3eSurfaceCallback

Surface Callbacks. The following callback types can be registered to enable user notification of surface events.

See also:
s3eSurfaceRegister, s3eSurfaceUnRegister
Required Header Files:
s3eSurface.h
Enumerator:
S3E_SURFACE_COPYUP Copyup callback. This callback is called from s3eSurfaceShow.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is an instance of s3eSurfaceCopyupInfo.
Returns:
The callback function should return 1 if copy was performed, and 0 if copy did not occur and system copyup should take place. For more information, see s3eSurfaceCopyupInfo.
S3E_SURFACE_SCREENSIZE Called when screen size or orientation has changed. This callback is called from within s3eDeviceYield.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData This is an instance of s3eSurfaceOrientation.
Returns:
No return value is expected from a callback registered using this enumeration.

enum s3eSurfaceError

Surface Errors.

See also:
s3eSurfaceGetError

s3eSurfaceGetErrorString

Required Header Files:
s3eSurface.h
Enumerator:
S3E_SURFACE_ERR_NONE | No Error.
S3E_SURFACE_ERR_PARAM | Invalid parameter.
S3E_SURFACE_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_SURFACE_ERR_ALREADY_REG | The specified callback is already registered.
S3E_SURFACE_ERR_NOT_FOUND | The specified callback was not found for removal.
S3E_SURFACE_ERR_DEVICE | The underlying file device failed.
S3E_SURFACE_ERR_MEM | Out of operating system memory during operation.

enum s3eSurfacePixelType

Surface pixel types.

Required Header Files:
s3eSurface.h

enum s3eSurfaceProperty

Surface Properties.

See also:
s3eSurfaceGetInt
Required Header Files:
s3eSurface.h
Enumerator:
S3E_SURFACE_WIDTH | [read] The width of the surface for this s3e application. Only differs from S3E_SURFACE_DEVICE_WIDTH if a rotation is required for a normal display. This value may change on a call to s3eSurfaceShow, so it should not be permanently cached by the application.
S3E_SURFACE_HEIGHT | [read] The height of the surface for this s3e application. Only differs from S3E_SURFACE_DEVICE_HEIGHT if a rotation is required for a normal display. This value may change on a call to s3eSurfaceShow, so it should not be permanently cached by the application.
S3E_SURFACE_PITCH | [read] The number of bytes between the start of one pixel row and the next for the current surface. This defaults to S3E_SURFACE_DEVICE_PITCH.
S3E_SURFACE_PIXEL_TYPE | [read] An s3eSurfacePixelType specifying the current surface pixel type, this defaults to S3E_SURFACE_DEVICE_PIXEL_TYPE.
S3E_SURFACE_DEVICE_WIDTH | [read] The width of the native display for this s3e application.
S3E_SURFACE_DEVICE_HEIGHT | [read] The height of the native display for this s3e application.
S3E_SURFACE_DEVICE_PIXEL_TYPE | [read] An s3eSurfacePixelType specifying the native device pixel type.
S3E_SURFACE_DEVICE_PITCH | [read] The number of bytes between the start of one pixel row and the next for the device's native display.
S3E_SURFACE_BLIT_DIRECTION | [read] Returns one of s3eSurfaceBlitDirection specifying the current display orientation of the surface. This is the last value passed as the blitDirection parameter to s3eSurfaceSetup, and will always be set to S3E_SURFACE_BLIT_DIR_NORMAL on startup.
S3E_SURFACE_DISPLAY | [read] Return the id of the current display. Default value is 0.
S3E_SURFACE_NUM_DISPLAYS | [read] Return the number of available displays. s3eSurfaceSetDisplayID() will succeed with values from 0 to S3E_SURFACE_NUM_DISPLAYS.
S3E_SURFACE_DEVICE_BLIT_DIRECTION | [read] Returns the s3eSurfaceBlitDirection which should be applied when copying directly to the device surface, in order for the application to be displayed with the correct screen rotation. This is useful if S3E_SURFACE_BLIT_DIR_NATIVE has been passed to s3eSurfaceSetup whereupon the application should apply this rotation to its graphics in order to achieve a normal upright display. This property will change if the device screen rotates (e.g. flipping between 'landscape' or 'portrait' modes). See s3eSurfaceSetup for more information on handling screen rotation.
S3E_SURFACE_DEVICE_WIDTH_QUANTISED [read] The width of the native display for this s3e application, quantised.

This will return the the first value in the following list that is greater than or equal to the current device width:- 128, 176, 208, 220, 240, 288, 320, 352, 416, 480, 512, 540, 600, 640, 768, 800, 960, 1024, 1152, 1280.

A device width higher than 1280 will not be quantised - this property will return the device width in this case.

S3E_SURFACE_DEVICE_HEIGHT_QUANTISED [read] The height of the native display for this s3e application, quantised.

This will return the the first value in the following list that is greater than or equal to the current device height:- 128, 176, 208, 220, 240, 288, 320, 352, 416, 480, 512, 540, 600, 640, 768, 800, 960, 1024, 1152, 1280.

A device height higher than 1280 will not be quantised - this property will return the device height in this case.

Function Documentation

S3E_API uint32 s3eSurfaceConvertRGB | ( | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b
 | ) |  |

Converts RGB value to surface native pixel format.

Parameters:
r | R component of colour to convert in the range 0-255.
g | G component of colour to convert in the range 0-255.
b | B component of colour to convert in the range 0-255.
Returns:
Colour value in current surface native pixel format, 0-extended to 32 bits.
Remarks:
This function converts a RGB value to data that can be be written to the frame buffer returned by s3eSurfacePtr()
Required Header Files:
s3eSurface.h

S3E_API s3eSurfaceError s3eSurfaceGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eSurfaceGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files:
s3eSurface.h

S3E_API const char* s3eSurfaceGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eSurfaceGetError
Remarks:
This function, as opposed to s3eSurfaceGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files:
s3eSurface.h

S3E_API int32 s3eSurfaceGetInt ( s3eSurfaceProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eSurfaceGetError() to retrieve an error code. This will return:
    • S3E_SURFACE_ERR_PARAM if property is not valid.
Required Header Files:
s3eSurface.h

S3E_API void s3eSurfaceInvalidate | ( | int32 | x,
 |  | int32 | y,
 |  | int32 | dx,
 |  | int32 | dy
 | ) |  |

Invalidates a given area of the display surface.

Parameters:
x | Left coordinate of invalidation rectangle.
y | Top coordinate of invalidation rectangle.
dx | Invalidation rectangle width.
dy | Invalidation rectangle height.
Remarks:
This function serves as a hint to the system that only the specified surface rectangle requires updating. This can potentially provide performance increases on some platforms.

If s3eSurfaceInvalidate() is not called before s3eSurfaceShow(), then s3eSurfaceShow() will always update the entire screen. If s3eSurfaceInvalidate() is called before s3eSurfaceShow(), s3eSurfaceShow() will update the screen according to the cumulative area indicated by calls to s3eSurfaceInvalidate(). The invalid area of the screen is reset when s3eSurfaceShow() is called.

Note:
This function is only a hint; therefore, there is no guarantee that the rest of the screen will not be updated at the same time as the invalidated rectangle. This function should only be used to increase performance and not to control the screen display. It is expected that the screen outside the rectangle specified is not changed.
Required Header Files:
s3eSurface.h

S3E_API void* s3eSurfacePtr ( )

Gets the current surface data pointer.

Returns:
Pointer to the surface data. This is guaranteed to be non-NULL.
Remarks:
The pointer returned is in the format as defined by the surface properties: S3E_SURFACE_PITCH, S3E_SURFACE_WIDTH, S3E_SURFACE_HEIGHT and S3E_SURFACE_PIXELTYPE.

If a surface pointer in a different pixel format or pitch is desired, then call s3eSurfaceSetup() before calling s3eSurfacePtr(). This pointer will remain constant between the current point of execution and s3eSurfaceShow().

Note:
After s3eSurfaceShow(), the result returned by s3eSurfacePtr() may change, so the result of s3eSurfacePtr() should never be stored by the user application across a call to s3eSurfaceShow().
Required Header Files:
s3eSurface.h

S3E_API s3eResult s3eSurfaceRegister | ( | s3eSurfaceCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Registers a callback for a given event. The available callback types are listed in s3eSurfaceCallback.

Parameters:
cbid | ID of the callback for which to register.
fn | callback function.
userData | Value to pass to the userData paramater of fn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSurfaceGetError() to retrieve an error code. This will return one of:
    • S3E_SURFACE_ERR_PARAM if cbid is not a valid member of s3eSurfaceCallback or fn is NULL.
    • S3E_SURFACE_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_SURFACE_ERR_ALREADY_REG If a function has already been registered for the S3E_SURFACE_COPYUP callback.
Remarks:
This can be used to register a function for the S3E_SURFACE_COPYUP or S3E_SURFACE_SCREENSIZE callback.
See also:
s3eSurfaceUnRegister
Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eSurfaceCallback enum.

A callback return value is only expected from a S3E_SURFACE_COPYUP callback function.

Required Header Files:
s3eSurface.h

S3E_API s3eResult s3eSurfaceSetDisplayID ( uint32 id )

Support for multiple displays. This function sets the screen to which surfaces are output.

Parameters:
id Display ID (0 = primary, 1 = secondary etc)
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSurfaceGetError() to retrieve an error code. This will return:
    • S3E_SURFACE_ERR_PARAM if id is invalid.
Remarks:
id is valid from 0 to s3eSurfaceGetInt(S3E_SURFACE_NUM_DISPLAYS) - 1. Calling this function will switch the surface interface to using the specified display. All the surface properties will return the properties of the new display, and the value returned by s3eSurfacePtr() will change.
Required Header Files:
s3eSurface.h

S3E_API s3eResult s3eSurfaceSetup | ( | s3eSurfacePixelType | pixelType,
 |  | uint32 | pitch,
 |  | void * | ptr,
 |  | s3eSurfaceBlitDirection | blitDirection
 | ) |  |

Reformats the current surface to the specified format.

Parameters:
pixelType | New surface format or pixel type ((s3eSurfacePixelType)-1 for default).
pitch | New surface pitch (0 for any default pitch).
ptr | New surface pixel store (NULL for device display pixel store).
blitDirection | Desired rotation to apply to surface before display.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSurfaceGetError() to retrieve an error code. This will return:
    • S3E_SURFACE_ERR_PARAM if pixelType is invalid, if pitch is nonzero but less than surface width * pixelType byte size, if pitch is not a multiple of the pixelType byte size or if blitDirection is invalid
    • S3E_SURFACE_ERR_MEM if S3E could not allocate memory from the underlying OS to create a surface.
    • S3E_SURFACE_ERR_DEVICE if the underlying graphics facilities from the host OS failed during surface creation.
Remarks:
This creates a new surface and changes the format of the data returned by s3eSurfacePtr() to the new format specified. By default the surface provided via s3eSurfacePtr() is a 565 format surface This function provides a way of creating different format surfaces from the default.

If ptr == NULL then S3E attempts to use any existing device-level surface to match the pixel format and pitch specified. If a device-level surface is used then s3eSurfaceShow() will not require an extra copying stage, improving performance. Therefore calling s3eSurfaceSetup(pixelType, 0, NULL, S3E_SURFACE_BLIT_DIR_NORMAL) will provide the optimimum surface with the specified pixel format, for example, s3eSurfaceSetup(S3E_SURFACE_PIXEL_TYPE_RGB565, 0, NULL, S3E_SURFACE_BLIT_DIR_NORMAL) will guarantee a surface that has 565 pixel format. In this case if the device does not support rendering an 565 screen natively, S3E will create an off-screen surface and perform an extra copying step when s3eSurfaceShow() is called to convert the pixel format from 565 to the native type.

If ptr != NULL then s3e will always copy and, if necessary, format-convert between the surface pointed to by ptr and the display whenever s3eSurfaceShow() is called. This can be useful if the user wishes to override the copying stage via the S3E_SURFACE_COPYUP callback.

If blitDirection != S3E_SURFACE_BLIT_DIR_NORMAL then the surface will be rotated so that it appears on the screen at the angle specified by blitDirection. Note that changing blitDirection may affect the dimensions of the surface, as for 90 and 270 degree rotations, width and height will be swapped.

Some devices require a surface rotation in order to produce an upright display. e.g. in cases where the LCD screen is mounted 'sideways' on the device. S3E handles this automatically so that the surface is always displayed according to blitDirection.

However performing the rotation is time-consuming and the user application may wish to handle the rotation itself (e.g. by drawing rotated polygons). To do this, specify S3E_SURFACE_BLIT_DIR_NATIVE for blitDirection. This will guarantee that S3E performs no surface rotation during s3eSurfaceShow.

The application will then wish to know what rotation to apply to its graphics. This can be obtained through calling s3eSurfaceGetInt(S3E_SURFACE_DEVICE_BLIT_DIRECTION) which will return a s3eSurfaceBlitDirection.

Some devices can change the rotation required for an upright display by e.g. flipping from 'portrait' mode to 'landscape' mode. Normally S3E will handle this by default and cause an orientation (and possibly surface dimension) change on the next call to s3eSurfaceShow.

However this behaviour is disabled if S3E_SURFACE_BLIT_DIR_NATIVE has been used for blitDirection. In this case the user should have registered a callback to be notified about changes in surface orientation, via s3eSurfaceRegister(S3E_SURFACE_SCREEN_SIZE) The user then should read the new required rotation (the m_DeviceBlitDirection passed in he callback data) and apply it to the application graphics.

Remarks:
s3eSurfaceSetup() does not affect the video, which will be played in the native (default) view.
Note:
Although S3E guarantees the ability to create and display a surface of any pixel format and orientation, it does not guarantee high performance copying routines for all pixel formats. Hence use of some pixel types will incur a significant performance penalty during s3eSurfaceShow(). S3E_SURFACE_PIXEL_TYPE_RGB565 is the only pixel type that is guaranteed to have a high-performace copying routine, so if the native pixel format is not desired it is recommended that S3E_SURFACE_PIXEL_TYPE_RGB565 is used.
Required Header Files:
s3eSurface.h

S3E_API s3eResult s3eSurfaceShow ( )

Displays the current surface to the device screen.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSurfaceGetError() to retrieve an error code. This will return one of:
    • S3E_SURFACE_ERR_DEVICE if displaying the surface failed due to operating system specific reasons
Remarks:
The display surface is written to screen quickest when it has not been converted from its native format to another, using the s3eSurfaceSetup() function. If s3eSurfaceSetup() has established a surface of a different format away from the display area, either via a user surface pointer or by specifying a pixel format different to that of the display, then s3eSurfaceShow() will perform an additional copying step.
If the device changes display orientation then s3eSurfaceShow will cause a surface rotation to be imposed, possibly swapping the width and height of the surface. Thus screen dimensions should not be stored over a call to s3eSurfaceShow. The same rule applies to the pointer returned by s3eSurfacePtr(). See s3eSurfaceSetup for more information on handling surface rotation.

Remarks:
The S3E_SURFACE_COPYUP callback will always be called, and it provides the user with the ability to change the copying stage if desired.
See also:
s3eSurfaceSetup

s3eCopyupCB

s3eSurfacePtr

Required Header Files:
s3eSurface.h

S3E_API s3eResult s3eSurfaceUnRegister | ( | s3eSurfaceCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eSurfaceGetError() to retrieve an error code. This will return one of:
    • S3E_SURFACE_ERR_PARAM if cbid is not a valid member of s3eSurfaceCallback.
    • S3E_SURFACE_ERR_NOT_FOUND if fn is not registered for callback cbid.
Remarks:
This can be used to unregister functions for the S3E_SURFACE_COPYUP callback.
See also:
s3eSurfaceRegister
Required Header Files:
s3eSurface.h


Airplay API Reference: S3E Surface Examples

Airplay API Reference > S3E API Documentation > S3E Surface > S3E Surface Examples >

S3E Surface Examples

This section illustrates how you can use the File IO functionality provided by S3E. This section contains one example application:

  • S3E Surface Example

Note: For more information on the S3E Surface functionality, see the S3E Surface Overview.


Airplay API Reference: S3E Surface Example

Airplay API Reference > S3E API Documentation > S3E Surface > S3E Surface Examples > S3E Surface Example >

S3E Surface Example

The following example uses the S3E surface functionality to manipulate screen orientation.

The functions used to achieve this are:

  • s3eSurfaceGetInt()
  • s3eSurfaceSetup()

Based on user input the screen orientation is turned clockwise or anit- clockwise.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

Button* g_ButtonRotateCW = 0;
Button* g_ButtonRotateCCW = 0;

void ExampleInit()
{
    g_ButtonRotateCW    = NewButton("Rotate cw");
    g_ButtonRotateCCW   = NewButton("Rotate ccw");

    if (!g_DeviceHasKeyboard)
        SetButtonScale(4);
}

void ExampleShutDown()
{
}

//-----------------------------------------------------------------------------
// The following function checks for a button to be pressed and based on this
// manipulates the orientation of what is displayed on screen. The function
// uses the s3eSurfaceGetInt() function to find out the surface blit direction,
// which is identified by S3E_SURFACE_BLIT_DIRECTION. When the user presses
// s3eKey1 the s3eSurfaceBlitDirection is incremented, and when the user
// presses s3eKey2 the s3eSurfaceBlitDirection is decremented.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (pressed == g_ButtonRotateCW)
    {
        // Get actual screen orientation
        int32 surfaceRot = s3eSurfaceGetInt(S3E_SURFACE_BLIT_DIRECTION);

        // Change to next clockwise orientation
        surfaceRot++;

        // Make sure we stay in range
        if (surfaceRot > S3E_SURFACE_BLIT_DIR_ROT270)
            surfaceRot = S3E_SURFACE_BLIT_DIR_NORMAL;

        // Set new orientation
        s3eSurfaceSetup(S3E_SURFACE_PIXEL_TYPE_RGB565, 0, NULL, (s3eSurfaceBlitDirection) surfaceRot);
    }

    if (pressed == g_ButtonRotateCCW)
    {
        // Get actual screen orientation
        int32 surfaceRot = s3eSurfaceGetInt(S3E_SURFACE_BLIT_DIRECTION);

        // Change to next counter clockwise orientation
        surfaceRot--;

        // Make sure we stay in range
        if (surfaceRot < S3E_SURFACE_BLIT_DIR_NORMAL)
            surfaceRot = S3E_SURFACE_BLIT_DIR_ROT270;

        // Set new orientation
        s3eSurfaceSetup(S3E_SURFACE_PIXEL_TYPE_RGB565, 0, NULL, (s3eSurfaceBlitDirection) surfaceRot);
    }

    return true;
}

//-----------------------------------------------------------------------------
//  Render the current state to the display.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    int y = GetYBelowButtons() + 2 * textHeight;

    // Display screen dimensions
    s3eDebugPrintf(10, y, 1, "`x666666Screenwidth  :%ld\nScreenHeight :%ld",
                    s3eSurfaceGetInt(S3E_SURFACE_WIDTH),s3eSurfaceGetInt(S3E_SURFACE_HEIGHT));

    // Display screen orientation
    s3eDebugPrint(10, y + 3 * textHeight, "`x666666Current screen orientation:", 1);
    switch (s3eSurfaceGetInt(S3E_SURFACE_BLIT_DIRECTION))
    {
        case S3E_SURFACE_BLIT_DIR_NORMAL:   s3eDebugPrint(10, y + 4 * textHeight, "`x666666 Normal", 1); break;
        case S3E_SURFACE_BLIT_DIR_ROT90:    s3eDebugPrint(10, y + 4 * textHeight, "`x666666 90 Degree rotated", 1); break;
        case S3E_SURFACE_BLIT_DIR_ROT180:   s3eDebugPrint(10, y + 4 * textHeight, "`x666666 180 Degree rotated", 1); break;
        case S3E_SURFACE_BLIT_DIR_ROT270:   s3eDebugPrint(10, y + 4 * textHeight, "`x666666 270 Degree rotated", 1); break;
    }
}


Airplay API Reference: S3E Timer

Airplay API Reference > S3E API Documentation > S3E Timer >

S3E Timer

The S3E Timer documentation contains the following sections:

  • S3E Timer Overview
  • Timer API Reference
  • S3E Timer Examples


Airplay API Reference: S3E Timer Overview

Airplay API Reference > S3E API Documentation > S3E Timer > S3E Timer Overview >

S3E Timer Overview

The Timer module provides a timer accurate to the millisecond using s3eTimerGetMs(). The Timer Module also allows you to set up timers that can execute a callback function when they time out. A timer can be set up using the s3eTimerSetTimer() function, and it can be cancelled using the s3eTimerCancelTimer() function. Interoperation with s3eDeviceYield is guaranteed; that is, timers will time-out and callback in the middle of a call to s3eDeviceYield. This is useful in a number of instances, for example, when waiting for external events.

Note: For an example of how the Timer functionality can be used, see the S3E Timer Examples.

For more information on the functionality outlined in this section, see the Timer API Reference.


Airplay API Reference: Timer API Reference

Airplay API Reference > S3E API Documentation > S3E Timer > Timer API Reference >

Timer API Reference
[S3E]

Enumerations

enum | s3eTimerError
enum | s3eTimerProperty

Functions

S3E_API s3eResult | s3eTimerCancelTimer (s3eCallback fn, void *userData)
S3E_API s3eTimerError | s3eTimerGetError ()
S3E_API const char * | s3eTimerGetErrorString ()
S3E_API int32 | s3eTimerGetInt (s3eTimerProperty property)
S3E_API int64 | s3eTimerGetLocaltimeOffset ()
S3E_API uint64 | s3eTimerGetMs ()
S3E_API int64 | s3eTimerGetUST ()
S3E_EAPI int64 | s3eTimerGetUSTNanoseconds ()
S3E_API int64 | s3eTimerGetUTC ()
S3E_API s3eResult | s3eTimerSetTimer (uint32 ms, s3eCallback fn, void *userData)

Detailed Description

For more information on the Timer functionality provided by the S3E module, see the S3E Timer section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eTimerError

Timer Errors.

See also:
s3eTimerGetError

s3eTimerGetErrorString

Required Header Files:
s3eTimer.h
Enumerator:
S3E_TIMER_ERR_NONE | No error.
S3E_TIMER_ERR_PARAM | Invalid parameter.
S3E_TIMER_ERR_TOO_MANY | Maximum number of timers (32) or callbacks exceeded .
S3E_TIMER_ERR_ALREADY_REG | The specified callback is already registered.
S3E_TIMER_ERR_NOT_FOUND | The specified timer or callback was not found for removal.
S3E_TIMER_ERR_UNAVAIL | The timer subdevice is unavailable or disabled.

enum s3eTimerProperty

Timer Properties.

Required Header Files
s3eTimer.h
Enumerator:
S3E_TIMER_RESOLUTION [Read, int] Timer resolution, in milliseconds.

Function Documentation

S3E_API s3eResult s3eTimerCancelTimer | ( | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Cancels a timer that was previously registered with s3eTimerSetTimer().

Parameters:
fn | Callback function that was passed to s3eTimerSetTimer().
userData | userData that was passed to s3eTimerSetTimer().
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eTimerGetError() to retrieve an error code. This will return one of:
  • S3E_TIMER_ERR_PARAM if fn is NULL.
  • S3E_TIMER_ERR_NOT_FOUND if (fn, userData)
    is not in the list of active timers.
Remarks:
Timers are uniquely identified by (fn, userData) so both the fn and userData passed to s3eTimerSetTimer() must be passed to s3eTimerCancelTimer().
Required Header Files:
s3eTimer.h

S3E_API s3eTimerError s3eTimerGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eTimerGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files:
s3eTimer.h

S3E_API const char* s3eTimerGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This is only available in debug builds.

See also:
s3eTimerGetError
Remarks:
This function, as opposed to s3eTimerGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files:
s3eTimer.h

S3E_API int32 s3eTimerGetInt ( s3eTimerProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eTimerGetError() to retrieve an error code. This will return:
    • S3E_TIMER_ERR_PARAM if property is not valid.
Remarks:
This can be used to read the timer resolution via S3E_TIMER_RESOLUTION.
Required Header Files:
s3eTimer.h

S3E_API int64 s3eTimerGetLocaltimeOffset ( )

Returns the offset from UTC of the current timezone, measured in milliseconds.

S3E_API uint64 s3eTimerGetMs ( )

An alias for s3eTimerGetUST

S3E_API int64 s3eTimerGetUST ( )

Return the uninterrupted system time. This is a monotonic system clock that represents time since the S3E runtime started, measured in milliseconds. This clock is unaffected by chages to the devices wallclock time, or timezone.

Returns:
the time, measured in milliseconds since S3E startup.
Remarks:
This timer is accurrate to at least 1/64 second (about 15ms) on all devices, so is useful for performing timing measurements. On some platforms the time returned by this function will be accurate to 1ms, but this is not guaranteed. Use s3eTimerGetInt(S3E_TIMER_RESOLUTION) to obtain the timer accuracy.

S3E_EAPI int64 s3eTimerGetUSTNanoseconds ( )

Similar to s3eTimerGetUST() but the returned time is in nanoseconds rather than milliseconds. This function is only available of certain platforms that support sub-millisecond timing. On all other platforms this function will return -1. WARNING: This function can wrap around to zero before getting to INT64_MAX. On iphone for example this is implemented in terms mach_absolute_time which on some devices wrapps every 50 minutes or so.

S3E_API int64 s3eTimerGetUTC ( )

Returns the time since the Epoch (00:00:00 UTC, January 1, 1970), measured in milliseconds.

S3E_API s3eResult s3eTimerSetTimer | ( | uint32 | ms,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Sets a timer.

Parameters:
ms | Time in milliseconds until timer is activated.
fn | Callback function to call when timer is activated.
userData | User specified data that will be passed to the userData paramater of the callback.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eTimerGetError() to retrieve an error code. This will return one of:
    • S3E_TIMER_ERR_PARAM if fn is NULL.
    • S3E_TIMER_ERR_TOO_MANY if the maximum number of timers(32) has been exceeded.
Remarks:
The callback function fn will be called at least ms after the present time. The systemData paramater in the call to fn will be NULL and the userData paramater to fn will be set to the userData in the call to s3eTimerSetTimer().

Timers are only activated on calls to s3eDeviceYield(), and they can interrupt a long yield period.

Timers only activate once - to implement a repeating timer additional calls to s3eTimerSetTimer must be made.

Timer are identified by (fn, userData). If s3eTimerSetTimer is called more than once with the same (fn, userData) the previous timer will be replaced. Up to 32 timers may be registered at any one time.

Required Header Files:
s3eTimer.h


Airplay API Reference: S3E Timer Examples

Airplay API Reference > S3E API Documentation > S3E Timer > S3E Timer Examples >

S3E Timer Examples

This section illustrates how you can use the timer functionality provided by S3E. This section contains two example applications:

  • S3E Timer Basic Example
  • S3E Timer Advanced Example

Note: For more information on the S3E Timer functionality, see the S3E Timer Overview.


Airplay API Reference: S3E Timer Basic Example

Airplay API Reference > S3E API Documentation > S3E Timer > S3E Timer Examples > S3E Timer Basic Example >

S3E Timer Basic Example

The following example uses S3E's Time functionality to get the current time in milliseconds since midnight January 1st 1970 and convert it into the current time in hours, minutes and seconds.

The main function used to achieve this is:

  • s3eTimerGetUTC()

The ExampleUpdate function uses a simple calculation to find the amount of milliseconds that have happened today and to split them up into relevant hours minutes and seconds.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include <time.h>

//-----------------------------------------------------------------------------
// Time Constants
//-----------------------------------------------------------------------------
#define MS_PER_DAY      86400000
#define MS_PER_HOUR     3600000
#define MS_PER_MINUTE   60000
#define MS_PER_SECOND   1000

void ExampleInit()
{
}

void ExampleShutDown()
{
}

bool ExampleUpdate()
{
    return true;
}

//-----------------------------------------------------------------------------
// The following function displays the current time using various
// different methods.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    const int height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);

    // Returns the time since the Epoch (00:00:00 UTC, January 1, 1970),
    // measured in milliseconds.
    uint64 timeMilli = s3eTimerGetUTC() % MS_PER_DAY;

    // Assemble string for displaying of time.
    uint8 hr =  (uint8)  (timeMilli / MS_PER_HOUR);
    uint8 min = (uint8) ((timeMilli / MS_PER_MINUTE) % 60);
    uint8 sec = (uint8) ((timeMilli / MS_PER_SECOND) % 60);
    uint  ms = (uint)(timeMilli % 1000);

    int y = height/3;
    // Displaying clock centered vertically and horizontally.
    s3eDebugPrintf(20, y, 1, "`x666666%02d:%02d:%02d:%03u", hr, min, sec, ms);

    time_t now = time(NULL);
    struct tm* gm_tm = gmtime(&now);
    int64 offset = s3eTimerGetLocaltimeOffset()/1000;

    y += 2 * textHeight;
    s3eDebugPrintf(20, y, 1, "`x666666time      : %u", now);
    y += 2 * textHeight;
    s3eDebugPrintf(20, y, 1, "`x666666GMT offset: %llds (%lld hours)", offset, offset/60/60);
    y += 2 * textHeight;
    s3eDebugPrintf(20, y, 1, "`x666666gmtime    : %s", asctime(gm_tm));
    y += 2 * textHeight;
    s3eDebugPrintf(20, y, 1, "`x666666ctime     : %s", ctime(&now));
    y += 2 * textHeight;
    struct tm* local_tm = localtime(&now);
    s3eDebugPrintf(20, y, 1, "`x666666localtime : %s", asctime(local_tm));
}


Airplay API Reference: S3E Timer Advanced Example

Airplay API Reference > S3E API Documentation > S3E Timer > S3E Timer Examples > S3E Timer Advanced Example >

S3E Timer Advanced Example

The following example uses S3E's timer functionality to create an alarm clock. The alarm clock has a snooze function that, when called, turns the alarm off for ten seconds before it is turned back on again.

The functions used to achieve this are:

  • s3eTimerGetMs()
  • s3eTimerSetTimer()
  • s3eAudioPlay()
  • s3eAudioStop()
The ExampleInit() function sets the Alarm() function as a callback function, which will be called after the period specified by ALARM_DELAY. This is done using the s3eTimerSetTimer() function. The ExampleUpdate() function calculates the current time in hours, minutes and seconds and compares that time with the time you have set for the alarm, thus enabling it to print to screen the amount of time left till the alarm goes off. When the alarm sounds you can hit the s3eKey0 button to call the snooze function to stop the alarm for a further ten seconds. The snooze function uses the s3eTimerSetTimer() function, which, once again, sets the alarm function as a callback that will be called after the period specified by ALARM_DELAY.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

#define ALARM_DELAY 10000

char    g_TimeString[64];
bool    g_AlarmOn = false;
uint64  g_AlarmStart = 0;

//-----------------------------------------------------------------------------
// The following function plays the loaded wav file on a free channel 100 times,
// or until you quit the application.
// It is a callback function passed to s3eTimerSetTimer (see Snooze()).
//-----------------------------------------------------------------------------
long Alarm(void *systemData, void *userData)
{
    s3eAudioPlay("siren.wav",1);
    g_AlarmStart = s3eTimerGetMs()+ALARM_DELAY;
    s3eTimerSetTimer(ALARM_DELAY, &Alarm, NULL);
    g_AlarmOn = true;
    return 0;
}

//-----------------------------------------------------------------------------
// The following function, when called, stops the alarm using the s3eAudioStop()
// function. It resets the callback to the alarm function using the
// s3eTimerSetTimer(). This will restart the alarm after the amount of time
// after the period specified by <i>ALARM_DELAY</i>.
//-----------------------------------------------------------------------------
void Snooze()
{
    s3eAudioStop();
    g_AlarmStart = s3eTimerGetMs()+ALARM_DELAY;
    s3eTimerSetTimer(ALARM_DELAY, &Alarm, NULL);
    g_AlarmOn = false;
}

//-----------------------------------------------------------------------------
// The following function sets the time at which the alarm by using the
// s3eTimerSetTimer() function to call Alarm() after after the period specified
// by <i>ALARM_DELAY</i>.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    g_AlarmStart = s3eTimerGetMs()+ALARM_DELAY;
    s3eTimerSetTimer(ALARM_DELAY, &Alarm, NULL);
}

void ExampleShutDown()
{
}

//-----------------------------------------------------------------------------
// The following function gets the current time and converts it to hours,
// minutes and seconds. It also checks the keyboard state to see if you have
// pressed a key to snooze.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    int16 timeTillAlarm = (int16) (g_AlarmStart - s3eTimerGetMs());

    if (g_AlarmOn)
        snprintf(g_TimeString, 63, "`x666666ALARM!!!");
    else
        snprintf(g_TimeString, 63, "`x666666Time till Alarm %i", timeTillAlarm);

    bool userTrigger = false;

    // Press 1 to start decompression
    if (s3eKeyboardGetState(s3eKey0) & S3E_KEY_STATE_PRESSED)
        userTrigger = true;

    // touch the screen to start decompression
    if (s3ePointerGetState(S3E_POINTER_BUTTON_SELECT) & S3E_POINTER_STATE_RELEASED)
        userTrigger = true;

    if (userTrigger && (g_AlarmOn == true))
        Snooze();

    return true;
}

//-----------------------------------------------------------------------------
// The following function displays the current state of the alarm and
// instructions on how to turn on the snooze function.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textWidth = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_WIDTH);
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    const int width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    const int height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);

    // Displaying clock centered vertically and horizontally
    s3eDebugPrint((width-(strlen(g_TimeString)-8)*textWidth)/2,
                  (height/2) - textHeight, g_TimeString, 1);

    static int64 sprintf_speed = -1;

    if (s3eTimerGetUSTNanoseconds() == -1)
    {
        s3eDebugPrint(10, height-100, "`x666666High resolution timer is not present", 1);
    }
    else
    {
        if (sprintf_speed == -1)
        {
            char test[100];
            uint64 start = s3eTimerGetUSTNanoseconds();
            sprintf(test, "just a %d test", 430);
            uint64 end = s3eTimerGetUSTNanoseconds();
            sprintf_speed = end - start;
        }
        s3eDebugPrintf(10, height-100, 1, "`x666666High res timer measured speed of sprintf: %lldns", sprintf_speed);
    }

    if (g_AlarmOn)
    {
        if (g_DeviceHasKeyboard)
            s3eDebugPrint((width-strlen("Press zero to snooze")*textWidth)/2,
                          (height/2) + textHeight, "`x666666Press zero to snooze", 1);
        else
            s3eDebugPrint((width-strlen("Touch screen to snooze")*textWidth)/2,
                          (height/2) + textHeight, "`x666666Touch screen to snooze", 1);
    }
}


Airplay API Reference: S3E Types

Airplay API Reference > S3E API Documentation > S3E Types >

S3E Types

The S3E Types documentation contains the following sections:

  • S3E Types Overview
  • Types API Reference


Airplay API Reference: S3E Types Overview

Airplay API Reference > S3E API Documentation > S3E Types > S3E Types Overview >

S3E Types Overview

This file defines standard types and definitions used in S3E.

Note: For more information on the functionality outlined in this section, see the Types API Reference.


Airplay API Reference: Types API Reference

Airplay API Reference > S3E API Documentation > S3E Types > Types API Reference >

Types API Reference
[S3E]

Typedefs

typedef int32(* | s3eCallback )(void *systemData, void *userData)
typedef int32(* | s3eCallback )(void *systemData, void *userData)
typedef wchar_t | s3eWChar

Enumerations

enum | s3eResult
enum | s3eResult

Detailed Description

For more information on the Types functionality provided by the S3E module, see the S3E Types section of the S3E API Documentation.

Typedef Documentation

typedef int32(* s3eCallback)(void *systemData, void *userData)

Callback function type.

Parameters:
systemData | callback-specific system supplied data.
userData | data supplied by user at callback registration.
Required Header Files
s3eTypes.h

typedef int32(* s3eCallback)(void *systemData, void *userData)

Callback function type.

Parameters:
systemData | callback-specific system supplied data.
userData | data supplied by user at callback registration.
Required Header Files
s3eTypes.h

typedef wchar_t s3eWChar

s3eWChar is defined to be interchangable with the wchar_t buildin type. Under airplay sizeof(wchar_t) is always 2.

Enumeration Type Documentation

enum s3eResult

Generic S3E Result Type.

Required Header Files
s3eTypes.h
Enumerator:
S3E_RESULT_SUCCESS | The operation completed successfully.
S3E_RESULT_ERROR | An error occurred during the operation.
S3E_RESULT_SUCCESS | The operation completed successfully.
S3E_RESULT_ERROR | An error occurred during the operation.

enum s3eResult

Generic S3E Result Type.

Required Header Files
s3eTypes.h
Enumerator:
S3E_RESULT_SUCCESS | The operation completed successfully.
S3E_RESULT_ERROR | An error occurred during the operation.
S3E_RESULT_SUCCESS | The operation completed successfully.
S3E_RESULT_ERROR | An error occurred during the operation.


Airplay API Reference: S3E Vibra

Airplay API Reference > S3E API Documentation > S3E Vibra >

S3E Vibra

The S3E Vibra Storage documentation contains the following sections:

  • S3E Vibra Overview
  • Vibra API Reference
  • S3E Vibra Examples


Airplay API Reference: S3E Vibra Overview

Airplay API Reference > S3E API Documentation > S3E Vibra > S3E Vibra Overview >

S3E Vibra Overview

The Vibra Module provides functionality to manage device vibration. The module allows you to gain feedback on a devices vibration settings and start and stop vibration should it be enabled.

Note: For more information on the functionality outlined in this section, see the Vibra API Reference.


Airplay API Reference: Vibra API Reference

Airplay API Reference > S3E API Documentation > S3E Vibra > Vibra API Reference >

Vibra API Reference
[S3E]

Enumerations

enum | s3eVibraError
enum s3eVibraProperty {
S3E_VIBRA_AVAILABLE = 0,
S3E_VIBRA_ENABLED = 1,
S3E_VIBRA_THRESHOLD = 2
}

Functions

S3E_API s3eVibraError | s3eVibraGetError ()
S3E_API const char * | s3eVibraGetErrorString ()
S3E_API int32 | s3eVibraGetInt (s3eVibraProperty property)
S3E_API s3eResult | s3eVibraSetInt (s3eVibraProperty property, int32 value)
S3E_API void | s3eVibraStop ()
S3E_API s3eResult | s3eVibraVibrate (uint8 level, uint32 ms)

Detailed Description

For more information on the Vibra functionality provided by the S3E module, see the S3E Vibra section of the S3E API Documentation.

Enumeration Type Documentation

enum s3eVibraError

Vibra Errors.

See also:
s3eVibraGetError

s3eVibraGetErrorString

Required Header Files:
s3eVibra.h
Enumerator:
S3E_VIBRA_ERR_NONE | No Error.
S3E_VIBRA_ERR_PARAM | Invalid parameter.
S3E_VIBRA_ERR_UNAVAIL | Vibra is unavailable.
S3E_VIBRA_ERR_DEVICE | Underlying vibra device failure.
S3E_VIBRA_ERR_DISABLED | Vibra is disabled or threshold is too low to vibrate.

enum s3eVibraProperty

Vibra Properties.

See also:
s3eVibraGetInt

s3eVibraSetInt

Required Header Files:
s3eVibra.h
Enumerator:
S3E_VIBRA_AVAILABLE | [read] Returns 1 if the device currently supports vibration, 0 if not. This may change at runtime if vibration is disabled through the OS, for example if the device profile is set to a non-vibrating mode.
S3E_VIBRA_ENABLED | [read, write] Enable/Disable vibration. 1 indicates that the application desires vibration functionality, 0 that it does not. The device will only vibrate on calls to s3eVibraVibrate() if S3E_VIBRA_ENABLED and S3E_VIBRA_AVAILABLE both return 1.
S3E_VIBRA_THRESHOLD | [read, write] Level threshold above which vibrations will be acted upon. Calls to vibrate below this level will be ignored.

Function Documentation

S3E_API s3eVibraError s3eVibraGetError ( )

Retrieves the last error, if any, for this Vibra.

See also:
s3eVibraGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files:
s3eVibra.h

S3E_API const char* s3eVibraGetErrorString ( )

Retrieve the last error as a string, if any, for this Vibra. This is only available in debug builds.

See also:
s3eVibraGetError
Remarks:
This function, as opposed to s3eVibraGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files:
s3eVibra.h

S3E_API int32 s3eVibraGetInt ( s3eVibraProperty property )

Retrieves an integer property for this subdevice.

Parameters:
property property to get.
Returns:
  • The value of the requested property if property is valid.
  • -1 otherwise.
    Call s3eVibraGetError() to retrieve an error code. This will return:
    • S3E_VIBRA_ERR_PARAM if property is not valid.
See also:
s3eVibraSetInt
Required Header Files:
s3eVibra.h

S3E_API s3eResult s3eVibraSetInt | ( | s3eVibraProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | property to set.
value | New value for property.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVibraGetError() to retrieve an error code. This will return:
    • S3E_VIBRA_ERR_PARAM if property is invalid or value is invalid.
    • S3E_VIBRA_ERR_UNAVAIL if the vibra device is not available.
See also:
s3eVibraGetInt
Required Header Files:
s3eVibra.h

S3E_API void s3eVibraStop ( )

Stops Vibrating, if the device is currently vibrating.

Required Header Files:
s3eVibra.h

S3E_API s3eResult s3eVibraVibrate | ( | uint8 | level,
 |  | uint32 | ms
 | ) |  |

Starts Vibrating.

Parameters:
level | Specifies the priority of the vibration (0 => low priority, 255 => high priority).
ms | Specifies how long to vibrate for.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVibraGetError() to retrieve an error code. This will return:
    • S3E_VIBRA_ERR_UNAVAIL if vibra is not available.
    • S3E_VIBRA_ERR_DISABLED if vibra is disabled or level is below the vibration threshold.
Required Header Files:
s3eVibra.h


Airplay API Reference: S3E Vibra Examples

Airplay API Reference > S3E API Documentation > S3E Vibra > S3E Vibra Examples >

S3E Vibra Examples

This section illustrates how you can use the Vibra functionality provided by S3E. This section contains one example application:

  • S3E Vibra Example

Note: For more information on the S3E Vibra functionality, see the S3E Vibra Overview


Airplay API Reference: S3E Vibra Example

Airplay API Reference > S3E API Documentation > S3E Vibra > S3E Vibra Examples > S3E Vibra Example >

S3E Vibra Example

The following example causes the device to vibrate using S3E's vibra functionality.

The main functions used to achieve this are:

  • s3eKeyboardAnyKey()
  • s3ePointerGetState()
  • s3eVibraVibrate()
  • s3eVibraStop()

The application waits for the user to press any key or touch the screen and then causes the device to start/stop it's vibration motor.

Instructions to change the vibration state are output to screen using the s3eDebugPrint() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//----------------------------------------------------------------------------
// ExampleS3EAudioBasic
//----------------------------------------------------------------------------

#include "ExamplesMain.h"

enum PlayerState
{
    kPlaying,
    kPaused,
    kStopped
};

static PlayerState g_Status = kStopped;        //player status information
static Button* g_ButtonPlay = 0;
static Button* g_ButtonPause = 0;
static Button* g_ButtonResume = 0;
static Button* g_ButtonStop = 0;
static s3eBool g_MP3Supported = S3E_FALSE;

void ExampleInit()
{
    g_ButtonPlay    = NewButton("Play");
    g_ButtonPause   = NewButton("Pause");
    g_ButtonResume  = NewButton("Resume");
    g_ButtonStop    = NewButton("Stop");

    g_MP3Supported = s3eAudioIsCodecSupported(S3E_AUDIO_CODEC_MP3);
}

void ExampleShutDown()
{
    s3eAudioStop();
}

//-----------------------------------------------------------------------------
// If a button has been pressed then start/pause/resume/stop playback.
//
// The other code in the function is in place to make sure the application
// exits cleanly once the escape or "left shoulder" button has been pressed.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    Button* pressed = GetSelectedButton();

    if (!g_MP3Supported)
        return true;

    if (pressed == g_ButtonPlay && (g_Status == kStopped))
    {
        if (s3eAudioPlay("test.mp3", 0) == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    if (pressed == g_ButtonPause && (g_Status == kPlaying))
    {
        if (s3eAudioPause() == S3E_RESULT_SUCCESS)
            g_Status = kPaused;
    }

    if (pressed == g_ButtonResume && (g_Status == kPaused))
    {
        if (s3eAudioResume() == S3E_RESULT_SUCCESS)
            g_Status = kPlaying;
    }

    if (pressed == g_ButtonStop)
    {
        s3eAudioStop();
        g_Status = kStopped;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function outputs a set of strings. A switch is used to
// output a string indicating the status. Each string is output using the
// s3eDebugPrint() function.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);

    g_ButtonPlay->m_Enabled = (g_Status == kStopped);
    g_ButtonPause->m_Enabled = (g_Status == kPlaying);
    g_ButtonResume->m_Enabled = (g_Status == kPaused);
    g_ButtonStop->m_Enabled = (g_Status == kPlaying);

    int ypos = GetYBelowButtons() + textHeight * 2;

    //Displaying status
    if (g_MP3Supported)
    {
        switch (g_Status)
        {
            case kPlaying:
                s3eDebugPrint(10, ypos, "`x666666Music Playing", 0);
                break;
            case kPaused:
                s3eDebugPrint(10, ypos, "`x666666Music Paused", 0);
                break;
            case kStopped:
                s3eDebugPrint(10, ypos, "`x666666Music Stopped", 0);
                break;
        }
    }
    else
    {
        s3eDebugPrint(10, ypos, "`x666666Device does not support mp3 playback", 0);
    }
}


Airplay API Reference: S3E Video

Airplay API Reference > S3E API Documentation > S3E Video >

S3E Video

The S3E Video documentation contains the following sections:

  • S3E Video Overview
  • Video API Documentation
  • S3E Video Examples


Airplay API Reference: S3E Video Overview

Airplay API Reference > S3E API Documentation > S3E Video > S3E Video Overview >

S3E Video Overview

The Video Module is an API for playing video. It plays an assortment of file types including 3GPP and MPEG4. Which file types are supported are device dependent, and can be queried at run-time via the s3eVideoIsCodecSupported() function. The functionality included allows you to play video from a buffer or from a file, it also lets you pause play, resume play, stop play, and query whether a certain video codec is supported. The Video callback mechanism allows you to register or unregister functions that should be called when video is started or stopped. Callbacks can be registered and unregistered using the s3eVideoRegister() and s3eVideoUnRegister() functions respectively.

Note: For an example of how the Video functionality can be used, see the S3E Video Examples.

For more information on the functionality outlined in this section, see the Video API Documentation.


Airplay API Reference: Video API Reference

Airplay API Reference > S3E API Documentation > S3E Video > Video API Reference >

Video API Reference
[S3E]

Defines

#define | S3E_VIDEO_MAX_VOLUME (0x100)

Enumerations

enum | s3eVideoCallback { S3E_VIDEO_STOP = 2 }
enum s3eVideoCodec {
S3E_VIDEO_CODEC_MPEG4 = 1,
S3E_VIDEO_CODEC_3GPP = 2,
S3E_VIDEO_CODEC_JPEG = 3,
S3E_VIDEO_CODEC_3GPP_VIDEO_H263 = 4,
S3E_VIDEO_CODEC_3GPP_VIDEO_H264 = 5,
S3E_VIDEO_CODEC_3GPP_AUDIO_AMR = 6,
S3E_VIDEO_CODEC_3GPP_AUDIO_AAC = 7,
S3E_VIDEO_CODEC_MPEG4_VIDEO_MPEG4 = 8,
S3E_VIDEO_CODEC_MPEG4_VIDEO_H264 = 9,
S3E_VIDEO_CODEC_MPEG4_AUDIO_AAC = 10,
S3E_VIDEO_CODEC_SWF = 11
}
enum | s3eVideoError
enum s3eVideoProperty {
S3E_VIDEO_VOLUME = 0,
S3E_VIDEO_STATUS = 1,
S3E_VIDEO_POSITION = 2,
S3E_VIDEO_VOLUME_DEFAULT = 3
}

Functions

S3E_API s3eVideoError | s3eVideoGetError ()
S3E_API const char * | s3eVideoGetErrorString ()
S3E_API int32 | s3eVideoGetInt (s3eVideoProperty property)
S3E_API s3eBool | s3eVideoIsCodecSupported (s3eVideoCodec codec)
S3E_API s3eBool | s3eVideoIsPlaying ()
S3E_API s3eResult | s3eVideoPause ()
S3E_API s3eResult | s3eVideoPlay (const char *filename, uint32 repeatCount, int32 x, int32 y, int32 width, int32 height)
S3E_API s3eResult | s3eVideoPlayFromBuffer (void *data, uint32 len, uint32 repeatCount, int32 x, int32 y, int32 width, int32 height)
S3E_API s3eResult | s3eVideoRegister (s3eVideoCallback cbid, s3eCallback fn, void *userData)
S3E_API s3eResult | s3eVideoResume ()
S3E_API s3eResult | s3eVideoSetInt (s3eVideoProperty property, int32 value)
S3E_API void | s3eVideoStop ()
S3E_API s3eResult | s3eVideoUnRegister (s3eVideoCallback cbid, s3eCallback fn)

Detailed Description

For more information on the Video functionality provided by the S3E module, see the S3E Video section of the S3E API Documentation.

Define Documentation

#define S3E_VIDEO_MAX_VOLUME (0x100)

Maximum video volume allowed (minimum is 0)

Enumeration Type Documentation

enum s3eVideoCallback

Video Callbacks. The following callback types can be registered to enable user notification of video events.

See also:
s3eVideoRegister, s3eVideoUnRegister
Required Header Files:
s3eVideo.h
Enumerator:
S3E_VIDEO_STOP This callback is called whenever video playing stops.

Any callback created to respond to this event should conform to the following:

Parameters:
systemData will always be NULL.
Returns:
No return value is expected from a callback registered using this enumeration.
Remarks:
This callback is not called between repetitions of a single track. It is called if video playback begins successfully but later fails due to an error. It will be called from within s3eVideoStop(), or within s3eVideoPlay() when images are 'played'. It may also be called by s3eVideoPlay(), or in s3eDeviceYield() if external events or data corruption cause video playback to fail.

enum s3eVideoCodec

Video system codecs.

Required Header Files:
s3eVideo.h
Enumerator:
S3E_VIDEO_CODEC_MPEG4 | MPEG4 (.mp4) Video. If this is passed to s3eVideoIsCodecSupported the result will be true if the MPEG4 container video format (MPEG4 Part 14) is supported. Note that there are different codecs available within the MPEG4 container video format, so the application should check which are supported before playing video files.
S3E_VIDEO_CODEC_3GPP | 3GPP (.3gp) Video.. If this is passed to s3eVideoIsCodecSupported the result will be true if any 3gpp container video formats are supported. Note that there are different codecs available within the 3gpp container video format, so the application should check which are supported before playing video files.
S3E_VIDEO_CODEC_JPEG | Single Frame JPEG. If this is passed to s3eVideoIsCodecSupported the result will be true if any jpeg display is supported
S3E_VIDEO_CODEC_3GPP_VIDEO_H263 | 3GPP H263 Video Support. If this is passed to s3eVideoIsCodecSupported the result will be true if H263 format video content is supported in 3gpp format files. The user should also check which 3gpp audio content is supported before choosing a video file to play.
S3E_VIDEO_CODEC_3GPP_VIDEO_H264 | 3GPP H.264 Video Support. If this is passed to s3eVideoIsCodecSupported the result will be true if H.264 format video content is supported in 3gpp format files. The user should also check which 3gpp audio content is supported before making a decision on which format video to play.
S3E_VIDEO_CODEC_3GPP_AUDIO_AMR | 3GPP AMR Audio Support. If this is passed to s3eVideoIsCodecSupported the result will be true if AMR format audio content is supported in 3gpp format files. The user should also check which 3gpp video content is supported before choosing a video file to play.
S3E_VIDEO_CODEC_3GPP_AUDIO_AAC | 3GPP AAC Support. If this is passed to s3eVideoIsCodecSupported the result will be true if AAC format audio content is supported in 3gpp format files. The user should also check which 3gpp video content is supported before making a decision on which format video to play.
S3E_VIDEO_CODEC_MPEG4_VIDEO_MPEG4 | MPEG4-Part 2 Video Support in the MPEG4 container format. If this is passed to s3eVideoIsCodecSupported the result will be true if MPEG4-Part 2 format video content is supported in mpeg4 format files. The user should also check which mpeg4 audio content is supported before choosing a video file to play.
S3E_VIDEO_CODEC_MPEG4_VIDEO_H264 | MPEG4-Part 10 (H.264) Video Support in the MPEG4 container format. If this is passed to s3eVideoIsCodecSupported the result will be true if MPEG4-Part 10 (H.264) format video content is supported in mpeg4 format files. The user should also check which mpeg4 audio content is supported before choosing a video file to play.
S3E_VIDEO_CODEC_MPEG4_AUDIO_AAC | MPEG4 AAC Support. If this is passed to s3eVideoIsCodecSupported the result will be true if AAC format audio content is supported in MPEG4 format files. The user should also check which MPEG4 video content is supported before making a decision on which format video to play.
S3E_VIDEO_CODEC_SWF | Shockwave Flash SWF Support. If this is passed to s3eVideoIsCodecSupported the result will be true if any Shockwave Lite format is supported

enum s3eVideoError

Video Errors.

See also:
s3eVideoGetError

s3eVideoGetErrorString

Required Header Files:
s3eVideo.h
Enumerator:
S3E_VIDEO_ERR_NONE | No error.
S3E_VIDEO_ERR_PARAM | Invalid parameter.
S3E_VIDEO_ERR_TOO_MANY | Maximum number of callbacks exceeded.
S3E_VIDEO_ERR_ALREADY_REG | The specified callback is already registered.
S3E_VIDEO_ERR_NOT_FOUND | File not found / The specified callback was not found for removal.
S3E_VIDEO_ERR_UNAVAIL | Video is unavailable.
S3E_VIDEO_ERR_DEVICE | Video device failed.
S3E_VIDEO_ERR_UNSUPPORTED | The action requested is not supported.
S3E_VIDEO_ERR_MEM | Out of operating system memory during operation.
S3E_VIDEO_ERR_INVALID_DRIVE | Invalid/unsupported drive specified in path.
S3E_VIDEO_ERR_INVALID_PATH | The path could not be resolved onto the device filesytem (e.g. opening ROM://../file).
S3E_VIDEO_ERR_FILEFORMAT | File format not supported.
S3E_VIDEO_ERR_WRONG_STATE | Attempting to pause video when its not playing, or resume video when its not paused.

enum s3eVideoProperty

Video Properties.

See also:
s3eVideoGetInt

s3eVideoSetInt

Required Header Files:
s3eVideo.h
Enumerator:
S3E_VIDEO_VOLUME | [read,write] Video device volume. This volume applies only to the video device, and can be set before or during video playback.
S3E_VIDEO_STATUS | [read] Status - returns one of s3eVideoStatus. This parameter cannot be set.
S3E_VIDEO_POSITION | [read] Position - Current playing position of the video track in milliseconds. Returns zero if no video is playing.
S3E_VIDEO_VOLUME_DEFAULT [read] Default video volume. The property S3E_VIDEO_VOLUME is set to this value on startup.

This value is in .8 fixed point format, 0x100 (S3E_VIDEO_MAX_VOLUME) is the maximum possible default volume.

This value is device-dependent, so that the result of playing video at default volume produces the same audible result across all devices.

enum s3eVideoStatus

Enumerator:
S3E_VIDEO_STOPPED | Stopped after playing or no play command issued yet. It is the initial status and does not gurantee the validity of the video device.
S3E_VIDEO_PLAYING | Video is playing.
S3E_VIDEO_PAUSED | Paused during play.
S3E_VIDEO_FAILED | Error occurred during play. Note, if the call to Play fails before video playback begins, the call to s3eVideoPlay() will fail and S3E_VIDEO_STATUS will be set to S3E_VIDEO_STOPPED rather than S3E_VIDEO_FAILED. The video status may change to failed only following an attempt to play an video.

Function Documentation

S3E_API s3eVideoError s3eVideoGetError ( )

Retrieves the last error, if any, for this subdevice.

See also:
s3eVideoGetErrorString
Remarks:
Calling this function will retrieve the last error and then remove it from memory; therefore, any further calls to this function will not return an error unless a subsequent error has occurred.
Required Header Files:
s3eVideo.h

S3E_API const char* s3eVideoGetErrorString ( )

Retrieves the last error as a string, if any, for this subdevice. This function is only available in debug builds.

See also:
s3eVideoGetError
Remarks:
This function, as opposed to s3eVideoGetError(), will always return the last error no matter how many times it is called. This function should not be relied upon to indicate whether an error has just occurred.
Required Header Files:
s3eVideo.h

S3E_API int32 s3eVideoGetInt ( s3eVideoProperty property )

Retrieves an integer value representing an video property on this subdevice.

Parameters:
property The video property to return.
Returns:
The value of the requested property if deviceProperty is valid.
  • -1 otherwise.
    Call s3eVideoGetError() to retrieve an error code. This will return:
    • S3E_VIDEO_ERR_PARAM if deviceProperty is not valid.
See also:
s3eVideoSetInt
Required Header Files:
s3eVideo.h

S3E_API s3eBool s3eVideoIsCodecSupported ( s3eVideoCodec codec )

Query whether or not the given codec is supported.

Parameters:
codec s3eVideoCodecs enumeration.
Returns:
S3E_TRUE if S3E is capable of playing files belonging to this codec, S3E_FALSE otherwise.
Remarks:
This gives the user application the ability to choose a media file that the device is capable of playing. The are many variations of file format for each codec and if s3eVideoIsCodecSupported() returns S3E_TRUE for a give codec, it is not guaranteed that every variation can be played.
Required Header Files:
s3eVideo.h

S3E_API s3eBool s3eVideoIsPlaying ( )

Query whether video is playing.

Returns:
S3E_TRUE if video is playing, S3E_FALSE otherwise.
Remarks:
This is equivalent to the expression s3eVideoGetInt(S3E_VIDEO_STATUS) == S3E_VIDEO_PLAYING, i.e. if video is stopped, paused or has failed, this will return S3E_FALSE.
Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoPause ( )

Pauses any currently playing video.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve the error code. This will return one of:
    • S3E_VIDEO_ERR_DEVICE if the underlying video device failed.
    • S3E_VIDEO_ERR_WRONG_STATE if video is not playing.
Remarks:
The sound device used by the s3eSound interface will remain silenced whilst the video file is in paused state. Note that any call to s3eVideoPlay(), s3eVideoPlayFromBuffer(), s3eVideoPlay() or s3eVideoPlayFromBuffer() will stop the video, even if it is in paused state. If the video successfully enters paused state, the S3E_VIDEO_PAUSED callback will be sent, and the status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will go to S3E_VIDEO_PAUSED.
See also:
s3eVideoResume

s3eVideoPlay

s3eVideoStop

Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoPlay | ( | const char * | filename,
 |  | uint32 | repeatCount,
 |  | int32 | x,
 |  | int32 | y,
 |  | int32 | width,
 |  | int32 | height
 | ) |  |

Plays video from a file.

Parameters:
filename | Name of file to play.
repeatCount One of the following values:
  • 0 = Play forever.
  • 1 = Play once.
  • >1 = Play a certain number of times.
x | x coordinate of top left of video window.
y | y coordinate of top left of video window.
width | Width of video window, in pixels.
height | Height of video window, in pixels.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve the error code. This will return one of:
    • S3E_VIDEO_ERR_PARAM if filename is NULL.
    • S3E_VIDEO_ERR_INVALID_DRIVE if filename specifies an invalid drive.
    • S3E_VIDEO_ERR_INVALID_PATH if filename could not be resolved onto a device-specific path.
    • S3E_VIDEO_ERR_NOT_FOUND if filename specifies a file that does not exist.
    • S3E_VIDEO_ERR_DEVICE if the underlying video device failed.
    • S3E_VIDEO_ERR_FILEFORMAT if the format of filename is not recognised by the device.
    • S3E_VIDEO_ERR_MEM if the operating system ran out of memory attempting to play the file.
    • S3E_VIDEO_ERR_UNAVAIL if no video playback functionality is available.
    • S3E_VIDEO_ERR_WRONG_STATE if s3eVideoPlay is called recursively. This can happen if you call s3eVideoPlay from a S3E_VIDEO_STOP callback which was itself generated by a call to s3eVideoPlay/s3eVideoPlayFromBuffer.
Remarks:
The video specified by filename will be displayed with the top-left of the video at (x, y) and will be clipped to the area specified by (x, y) - (x + width, y + height). This area itself will be clipped to the dimensions of the screen.

This function waits until video playback starts before returning. The video status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will return S3E_VIDEO_PLAYING immediately after s3eVideoPlay() returns.

s3eVideoPlay() can be used to 'play' JPEG images. When a JPEG image is played, it behaves as a video of zero length. In this case, s3eVideoPlay() will immediately issue both a a S3E_VIDEO_STOP callback. The image will be displayed on the screen will and remain on the surface returned by s3eSurfacePtr().

The name and extension of filename need not bear any relation to the format of the file; S3E will automatically use any available video codec.

s3eVideoPlay() will not succeed on files that exist on file systems registered by s3eFileAddUserFileSys().

Playing video will cause any currently playing audio tracks to be stopped, similar to calling s3eAudioStop() before s3eVideoPlay(). The exception to this is when JPEG images are 'played', whereupon audio is unaffected.

If video is already playing, this function behaves as if s3eVideoStop() were called just before the call to s3eVideoPlay.() This means the current video track will stopped and an S3E_VIDEO_STOP callback will be issued before the new track begins playing.

If the S3E_VIDEO_STOP callback attempts to play a video track, this track will be stopped without an additional S3E_VIDEO_STOP callback. If video is playing, the video will be stopped and a S3E_VIDEO_STOP callback will be sent.

If video playback fails at any stage after playback has started (for example, due to a corrupted file) the S3E_VIDEO_STOP callback will be sent and the status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will go to S3E_VIDEO_FAILED.

The sound device used by the s3eSound interface will be silenced whilst the video file is playing. The sound device will however keep playing and continue issuing callbacks etc.

See also:
s3eVideoPlayFromBuffer

s3eVideoPause

s3eVideoResume

s3eVideoStop

Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoPlayFromBuffer | ( | void * | data,
 |  | uint32 | len,
 |  | uint32 | repeatCount,
 |  | int32 | x,
 |  | int32 | y,
 |  | int32 | width,
 |  | int32 | height
 | ) |  |

Plays video from a buffer.

Parameters:
data | Buffer holding video data. This data must remain valid until video play is complete.
len | Length of buffer, in bytes.
x | x coordinate of top left of video window.
y | y coordinate of top left of video window.
height | Height of video window, in pixels.
width | Width of video window, in pixels.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve the error code. This will return one of:
    • S3E_VIDEO_ERR_PARAM if data is NULL or len is 0.
    • S3E_VIDEO_ERR_DEVICE if the underlying video device failed.
    • S3E_VIDEO_ERR_FILEFORMAT if the format of data is not recognised by the device.
    • S3E_VIDEO_ERR_MEM if the operating system ran out of memory attempting to play the buffer.
    • S3E_VIDEO_ERR_UNAVAIL if no video playback functionality is available.
    • S3E_VIDEO_ERR_WRONG_STATE if s3eVideoPlay is called recursively. This can happen if you call s3eVideoPlay from a S3E_VIDEO_STOP callback which was itself generated by a call to s3eVideoPlay/s3eVideoPlayFromBuffer.
Remarks:
The video specified by (data, len) will be displayed with the top-left of the video at (x, y) and will be clipped to the area specified by (x, y) - (x + width, y + height). This area itself will be clipped to the dimensions of the screen.

s3eVideoPlayFromBuffer() can be used to 'play' JPEG images. When a JPEG image is played, it behaves as a video of zero length. In this case, s3eVideoPlayFromBuffer() will immediately issue both a a S3E_VIDEO_STOP callback. The image will be displayed on the screen will and remain on the surface returned by s3eSurfacePtr().

The contents of the buffer supplied in data must not be overwritten until video play is complete.

This function waits until video playback starts before returning. The video status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will return S3E_VIDEO_PLAYING immediately after s3eVideoPlayFromBuffer() returns. S3E will automatically use any available video codec to play the data in data.

If video is already playing, this function behaves as if s3eVideoStop() were called just before the call to s3eVideoPlayFromBuffer.() This means the current video track will stopped and an S3E_VIDEO_STOP callback will be issued before the new track begins playing.

If the S3E_VIDEO_STOP callback attempts to play a video track, this track will be stopped without an additional S3E_VIDEO_STOP callback. If video is playing, the video will be stopped and a S3E_VIDEO_STOP callback will be sent.

If video playback fails at any stage after playback has started (for example, due to corrupted data) the S3E_VIDEO_STOP callback will be sent and the status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will go to S3E_VIDEO_FAILED.

The sound device used by the s3eSound interface will be silenced whilst the video file is playing. The sound device will however keep playing and continue issuing callbacks etc.

See also:
s3eVideoPlay

s3eVideoPause

s3eVideoResume

s3eVideoStop

Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoRegister | ( | s3eVideoCallback | cbid,
 |  | s3eCallback | fn,
 |  | void * | userData
 | ) |  |

Registers a callback for a given event. The available callback types are listed in s3eVideoCallback.

Parameters:
cbid | ID of the callback for which to register.
fn | callback function.
userData | Value to pass to the userData paramater of fn.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve an error code. This will return one of:
    • S3E_VIDEO_ERR_PARAM if cbid is not a valid member of s3eVideoCallback or fn is NULL.
    • S3E_VIDEO_ERR_TOO_MANY If the maximum number of callbacks for this device has been exceeded.
    • S3E_VIDEO_ERR_ALREADY_REG If (cbid, fn) has already been registered.
Note:
For more information on the systemData passed as a parameter to the callback registered using this function, see the s3eVideoCallback enum.

It is not necessary to define a return value for any registered callback.

Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoResume ( )

Resumes the currently paused video track.

Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve the error code. This will return one of:
    • S3E_VIDEO_ERR_DEVICE if the underlying video device failed.
    • S3E_VIDEO_ERR_WRONG_STATE if video is not paused.
Remarks:
If the video successfully resumes playing the S3E_VIDEO_RESUME callback will be sent, and the status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will go to S3E_VIDEO_PLAYING.
See also:
s3eVideoPause

s3eVideoPlay

s3eVideoStop

Required Header Files:
s3eVideo.h

S3E_API s3eResult s3eVideoSetInt | ( | s3eVideoProperty | property,
 |  | int32 | value
 | ) |  |

Sets an integer property for this subdevice.

Parameters:
property | The video property to set.
value | The value to set the property too.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve an error code. This will return:
    • S3E_VIDEO_ERR_PARAM if deviceProperty is invalid or value is invalid.
Remarks:
Note that when setting volume via the S3E_VIDEO_VOLUME property, the volume will be clipped to the range [0, S3E_VIDEO_MAX_VOLUME (0x100)].
See also:
s3eVideoGetInt
Required Header Files:
s3eVideo.h

S3E_API void s3eVideoStop ( )

Stops the current video.

Remarks:
If video is playing, this will stop video playback and then send the S3E_VIDEO_STOP callback. The video status returned by s3eVideoGetInt(S3E_VIDEO_STATUS) will go to S3E_VIDEO_STOPPED. The sound device used by the s3eSound interface will be un-muted.
See also:
s3eVideoPlay

s3eVideoPause

s3eVideoResume

Required Header Files:
s3eVideo.h
Remarks:
If video is playing when a screen rotation event happens, it is stopped as if s3eVideoStop was called.

S3E_API s3eResult s3eVideoUnRegister | ( | s3eVideoCallback | cbid,
 |  | s3eCallback | fn
 | ) |  |

Unregister a callback for a given event.

Parameters:
cbid | ID of the callback for which to register.
fn | Callback Function.
Returns:
  • S3E_RESULT_SUCCESS if no error occurred.
  • S3E_RESULT_ERROR if the operation failed.
    Call s3eVideoGetError() to retrieve an error code. This will return one of:
    • S3E_VIDEO_ERR_PARAM if cbid is not a valid member of s3eVideoCallback, or fn is NULL.
    • S3E_VIDEO_ERR_NOT_FOUND if fn is not registered for callback cbid.
Required Header Files:
s3eVideo.h


Airplay API Reference: S3E Video Examples

Airplay API Reference > S3E API Documentation > S3E Video > S3E Video Examples >

S3E Video Examples

This section illustrates how you can use the Video functionality provided by S3E. This section contains one example application:

  • S3E Video Example

Note: For more information on the S3E Video functionality, see the S3E Video Overview


Airplay API Reference: S3E Video Example

Airplay API Reference > S3E API Documentation > S3E Video > S3E Video Examples > S3E Video Example >

S3E Video Example

The following example uses S3E's video functionality to play a video file from buffer.

The following functions are used to achieve this:

  • s3eFileOpen()
  • s3eFileGetSize()
  • s3eMallocBase()
  • s3eFree()
  • s3eFileRead()
  • s3eVideoRegister()
  • s3eVideoPlayFromBuffer()
  • s3eVideoPause()
  • s3eVideoResume()
  • s3eVideoStop()

This example uses the s3eFileOpen(), s3eMallocBase() and s3eFileRead() functions to open, allocate memory for, and read a file. The keyboard is used to control the state of playback:

  • pressing s3eKey1 will call the s3eVideoPlayFromBuffer() function to play the video from buffer.
  • pressing s3eKey2 will call the s3eVideoPause() function to pause video playback.
  • pressing s3eKey3 will call the s3eVideoResume() function to resume video playback.
  • pressing s3eKey4 will call the s3eVideoStop() function to stop video playback.
The example registers a callback function using the s3eVideoRegister() function. This callback is called when the S3E_VIDEO_STOP event occurs. The registered callback function, EndOfTrack() changes the playback status to be eot.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"

#define TEST_VIDEO "testvideo2.3gp"

enum Player
{
    play,
    pause,
    resume,
    stop,
    eot
};  //Actual state of player

static Button* g_ButtonPlay = 0;
static Button* g_ButtonPause = 0;
static Button* g_ButtonResume = 0;
static Button* g_ButtonStop = 0;
static s3eResult g_RegisterRes = S3E_RESULT_ERROR;     //Result of Registering end of track callback
static Player g_Status;

//-----------------------------------------------------------------------------
// The following function is called when a video file has been played in its
// entirety. The function sets the state of playback to be the end of track, or
// eot.
//-----------------------------------------------------------------------------
int32 EndOfTrack(void* systemData, void* userData)
{
    g_Status = eot;
    return true;
}

//-----------------------------------------------------------------------------
// The following function reads a file into memory and registers an EndOfTrack
// callback function to be called when the S3E_VIDEO_STOP event occurs.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    g_ButtonPlay    = NewButton("Play");
    g_ButtonPause   = NewButton("Pause");
    g_ButtonResume  = NewButton("Resume");
    g_ButtonStop    = NewButton("Stop");

    s3eVideoPlay(TEST_VIDEO, 1, GetYBelowButtons(), GetYBelowButtons(), (s3eSurfaceGetInt (S3E_SURFACE_WIDTH)-20),
                        (s3eSurfaceGetInt (S3E_SURFACE_HEIGHT)-GetYBelowButtons() - 10));

    //Register a callback function for when a track has finished playing.
    g_RegisterRes = s3eVideoRegister(S3E_VIDEO_STOP, &EndOfTrack, NULL);
}

//-----------------------------------------------------------------------------
// The following function frees the memory allocated by the example code.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
}

//-----------------------------------------------------------------------------
// The following function checks the state of the keyboard and calls the
// relevant keyboard functionality.
// Press s3eKey1 to play; s3eKey2 to pause; s3eKey3 to resume; and s3eKey4,
// s3eKeyEsc or s3eKeyLS to stop.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    if (!s3eVideoIsCodecSupported(S3E_VIDEO_CODEC_3GPP))
    {
        s3eVideoStop();
        return true;
    }

    Button* pressed = GetSelectedButton();

    //Press 1 to play.
    if ((pressed == g_ButtonPlay) && (g_Status == stop || g_Status == eot))
    {
        //play from buffer setting display size and position.
        s3eVideoPlay(TEST_VIDEO, 1, 10, 35, (s3eSurfaceGetInt (S3E_SURFACE_WIDTH)-20),
                (s3eSurfaceGetInt (S3E_SURFACE_HEIGHT)-70));

        g_Status = play;
    }

    //Press 2 to pause.
    if ((pressed == g_ButtonPause) && (g_Status == play || g_Status == resume))
    {
        s3eVideoPause();
        g_Status = pause;
    }

    //Press 3 to resume.
    if ((pressed == g_ButtonResume) && g_Status == pause)
    {
        s3eVideoResume();
        g_Status = resume;
    }

    //Press 4 to stop.
    if (pressed == g_ButtonStop)
    {
        s3eVideoStop();
        g_Status = stop;
    }

    //Press Esc/LS to Exit
    if ((s3eKeyboardGetState(s3eKeyEsc) & S3E_KEY_STATE_PRESSED) ||
        (s3eKeyboardGetState(s3eKeyLS) & S3E_KEY_STATE_PRESSED))
    {
        s3eVideoStop();
        return false;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function prints out the current state of video playback.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    int32 width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
    int32 height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);

    if (g_RegisterRes == S3E_RESULT_ERROR)
        s3eDebugPrint((width - (strlen("EndOfTrack Failed to register"))*6)/2,
                height-50, "`xfb0b0cEndOfTrack Failed to register", 0);

    if (s3eVideoIsCodecSupported(S3E_VIDEO_CODEC_3GPP))
    {
        switch (g_Status)
        {
            case play:
                s3eDebugPrint((width - (strlen("Video Playing:"))*6)/2,
                    height-20,  "`x666666Video Playing", 1);
                s3eDebugPrint((width - (strlen("Press 2 to pause, 4 to stop"))*6)/2,
                    height-30, "`x666666Press 2 to pause, 4 to stop", 1);
                break;
            case pause:
                s3eDebugPrint((width - (strlen("Video Paused:"))*6)/2,
                    (height-20), "`x666666Video Paused", 1);
                s3eDebugPrint((width - (strlen("Press 3 to resume, 4 to stop"))*6)/2,
                    height-30, "`x666666Press 3 to resume, 4 to stop", 1);
                break;
            case resume:
                s3eDebugPrint((width - (strlen("Video Resumed"))*6)/2,
                    (height-20), "`x666666Video Resumed", 1);
                s3eDebugPrint((width - (strlen("Press 2 to pause, 4 to stop"))*6)/2,
                    (height-30), "`x666666Press 2 to pause, 4 to stop", 1);
                break;
            case stop:
                s3eDebugPrint((width - strlen("Video Stopped")*6)/2, height-20,
                    "`x666666Video Stopped", 1);
                s3eDebugPrint((width - strlen("Press 1 to play")*6)/2, height-30,
                    "`x666666Press 1 to play", 1);
                break;
            case eot:
                s3eDebugPrint(((s3eSurfaceGetInt (S3E_SURFACE_WIDTH) - (strlen("Press 1 to play Video again"))*6)/2),
                    height-30, "`x666666Press 1 to play Video again", 1);
                break;
        }
    }
    else
    {
        g_Status = stop;

        s3eDebugPrint((width - (strlen("3GPP not supported."))*6)/2,
                height-50, "`x6666663GPP not supported.", 0);
    }
}


Airplay API Reference: Derbh API Documentation

Airplay API Reference > Derbh API Documentation >

Derbh API Documentation

The Derbh documentation contains the following sections:

  • Derbh API Overview
  • Derbh API Reference
  • Derbh Examples


Airplay API Reference: Derbh API Overview

Airplay API Reference > Derbh API Documentation > Derbh API Overview >

Derbh API Overview

The Derbh API allows you to create or read compressed Derbh archives (DZ files). These archives are similar to ZIP files, but typically achieve a higher compression ratio than ZIP when applied to collections of game assets.

To use Derbh functionality, you must include "derbh.h" in your source and derbh as a subproject in your project's MKB file:

  • subprojects
  • {
    • derbh
  • }

The Derbh system can be accessed via two distinct interfaces.

Derbh Low-level API

The DZFILE interface allows Derbh archive access through a set stdio-like functions. This interface is relatively low-level and is therefore better suited to advanced users who wish to write their own access functions.

Note:For more information on the Derbh Low-level API, see the Derbh Low-level API section of the Derbh module overview.

Derbh High-level Archive API

The Archive Access System allows single or multiple Derbh archives to be accessed using the s3eFile interface as a single logical drive. Initializing an archive via this interface mounts a custom file system which abstracts file operations. From the users point of view, accessing files from within .dz archives has the same 'look and feel' as default file access. Multiple archives can be initialized and automatically overlaid in a single logical file-system; this can easily be probed for file contents and directory structure in exactly the same fashion as probing a physical disk. This interface allows easy operations to be performed on Derbh archives using the familiar s3eFile interface without needing to know any details about the underlying DZ implementation.

Note: For more information on the Derbh High-level Archive API, see the Derbh High-level Archive API section of the Derbh module overview.


Airplay API Reference: Derbh API Reference

Airplay API Reference > Derbh API Documentation > Derbh API Reference >

Derbh API Reference

Modules

Derbh Low-level API
Derbh High-level Archive API

Detailed Description

Derbh is an interface for creating and reading compressed Derbh archives (DZ files). These archives are similar to ZIP files, but typically achieve a higher compression ratio than ZIP when applied to collections of game assets.


Airplay API Reference: Derbh Low-level API

Airplay API Reference > Derbh API Documentation > Derbh API Reference > Derbh Low-level API >

Derbh Low-level API
[Derbh API Reference]

Data Structures

struct | DZFILE

Typedefs

typedef void *(* | dzAllocCallback )(uint32)
typedef void(* | dzFreeCallback )(void *)

Functions

int32 | dzclose (DZFILE *dzFile)
int32 | dzcloseall ()
s3eBool | dzeof (DZFILE *dzFile)
int32 | dzerror (DZFILE *dzFile)
DZFILE * | dzopen (const char *filename, const char *mode)
uint32 | dzread (void *pBuffer, uint32 size, uint32 count, DZFILE *dzFile)
int32 | dzseek (DZFILE *dzFile, int32 offset, int32 origin)
void | dzSetAllocFreeCallbacks (dzAllocCallback fnAlloc, dzFreeCallback fnFree)
int32 | dztell (DZFILE *dzFile)

Detailed Description

For more information on the Derbh Low-level API, see the Derbh Low-level API section of the Derbh API Documentation.

Typedef Documentation

typedef void*(* dzAllocCallback)(uint32)

Typedef for callback function to allocate memory.

See also:
dzFreeCallback, dzSetAllocFreeCallbacks

typedef void(* dzFreeCallback)(void *)

Typedef for callback function to allocate memory.

See also:
dzFreeCallback, dzSetAllocFreeCallbacks

Function Documentation

int32 dzclose ( DZFILE * dzFile )

Close an open Derbh file.

Parameters:
dzFile Pointer to the s3eFile object to close.
Returns:
0 if successful.
See also:
dzopen

int32 dzcloseall ( )

Close all open Derbh files.

Returns:
0 if successful.
See also:
dzclose

s3eBool dzeof ( DZFILE * dzFile )

Query end-of-dile on a Derbh file.

Parameters:
dzFile Pointer to the Derbh file object to read from.
Returns:
true only if eof is reached.

int32 dzerror ( DZFILE * dzFile )

Retrieve the last error on a Derbh file.

Parameters:
dzFile Pointer to the Derbh file object to read from.
Returns:
0 indicates no error.

DZFILE* dzopen | ( | const char * | filename,
 |  | const char * | mode
 | ) |  |

Open a Derbh file.

Parameters:
filename | Full pathname of file.
pMode | stdio-type string defining the mode in which to open the file.
Returns:
Pointer to a Derbh file object, or NULL if failed.
See also:
s3eFileOpen, s3eFileOpenFromMemory

uint32 dzread | ( | void * | pBuffer,
 |  | uint32 | size,
 |  | uint32 | count,
 |  | DZFILE * | dzFile
 | ) |  |

Read some data from an open Derbh file.

Parameters:
pBuffer | Pointer to the area in memory at which to start reading.
size | Size in bytes of a single data element to be read.
count | Number of data elements to read, in bytes.
dzFile | Pointer to the Derbh file object to read from.
Returns:
The full number of items actually read (same caveats as fread). The total number of bytes read is (size * count).
See also:
s3eFileWrite, s3eFileOpen, s3eFileClose

int32 dzseek | ( | DZFILE * | dzFile,
 |  | int32 | offset,
 |  | int32 | origin
 | ) |  |

Move the file pointer to a specified location.

Parameters:
dzFile | Pointer to the Derbh file object.
offset | Number of bytes from specified origin to seek to.
origin | Origin type to use.
Returns:
0 if successful. Behaves exactly the same as fseek.

void dzSetAllocFreeCallbacks | ( | dzAllocCallback | fnAlloc,
 |  | dzFreeCallback | fnFree
 | ) |  |

Set callbacks for Derbh to use your own memory alloc() and free() functions.

Parameters:
fnAlloc | Function pointer to use for allocating memory.
fnFree | Function pointer to use for deallocating memory .

int32 dztell ( DZFILE * dzFile )

Get the current position of a file pointer.

Parameters:
dzFile Pointer to the Derbh file object.
Returns:
The current file pointer offset, in bytes. Behaves exactly the same as ftell.
See also:
dztell


Airplay API Reference: Derbh High-level Archive API

Airplay API Reference > Derbh API Documentation > Derbh API Reference > Derbh High-level Archive API >

Derbh High-level Archive API
[Derbh API Reference]

Functions

int32 | dzArchiveAttach (const char *pArchiveName)
int32 | dzArchiveAttachFromMem (void *pMem, uint32 size)
void | dzArchiveDetach ()
void | dzArchiveDetachFromMem (void *pMem)
void | dzArchiveDetachNamed (const char *pArchiveName)

Detailed Description

For more information on the Derbh High-level Archive API, see the Derbh High-level Archive API section of the Derbh API Documentation.

Function Documentation

int32 dzArchiveAttach ( const char * pArchiveName )

Attach an archive file to the archiving system. This should be the main .dz file output by the compressor. All other sub-archives specified in this main dz file will be loaded automatically.

This stage mounts the Derbh custom s3eFile system. Subsequent calls to s3eFile functions will operate on the full archive as a logical drive.

You can attach multiple archives with this function. The files in additional archives are added to the logical drive. Should a file already exist, the newer version replaces it.

Parameters:
pArchiveName Archive name.
Returns:
Standard s3eResult enumeration.
See also:
dzArchiveDetach, dzArchiveDetachNamed

int32 dzArchiveAttachFromMem | ( | void * | pMem,
 |  | uint32 | size
 | ) |  |

Attach an archive file to the archiving system, from memory.

Parameters:
pMem | Pointer to file in memory.
size | File sizee in bytes.
Returns:
Standard s3eResult enumeration.
See also:
dzArchiveDetach, dzArchiveDetachFromMem

void dzArchiveDetach ( )

Detach the last archive file which was attached. The files of the last initialised archives are removed from the logical file system. If there are no more archives remaining then the custom filesystem is un-mounted. s3e file functionality returns to default.

See also:
dzArchiveAttach

void dzArchiveDetachFromMem ( void * pMem )

Detach a given memory block that has previously been attached as a derbh file.

Parameters:
pMem Pointer to memory block
See also:
dzArchiveAttachFromMem

void dzArchiveDetachNamed ( const char * pArchiveName )

Detach a named archive file. The files in this archive are removed from the logical file system. If there are no more archives remaining then the custom filesystem is un-mounted. s3e file functionality returns to default.

Parameters:
pArchiveName Archive name.
See also:
dzArchiveAttach


Airplay API Reference: Derbh Examples

Airplay API Reference > Derbh API Documentation > Derbh Examples >

Derbh Examples

The Derbh documentation contains the following example:

  • Derbh Basic Example


Airplay API Reference: Derbh Basic Example

Airplay API Reference > Derbh API Documentation > Derbh Examples > Derbh Basic Example >

Derbh Basic Example

This program illustrates how to use the S3E file system to read a file from a compressed Derbh archive. S3E allows the user to mount their own custom file systems which override many of the S3E file functions. Here this functionality is utilised to access a compressed archive as a logical drive.

The important functions required to achieve this are:

  • dzArchiveAttach()
  • dzArchiveDetach()
  • s3eFileOpen()
  • s3eFileRead()

The Derbh interface (dzio.h) allows an archive to be "attached" from a pathname; this automatically mounts the custom file system.

The archive "archive1.dz" contains three files: "TestTexture.bmp", "TextFile.txt" and "testvideo2.3gp".

Pressing 0 will attach the archive "archive.dz". Pressing 1 will, having attached the archive, decompress it and read the file "TextFile.txt". The contents of this file are then displayed on the screen.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleDerbhBasic
//-----------------------------------------------------------------------------

#include "derbh.h"
#include "s3e.h"
#include "IwArray.h"
#include "IwString.h"
#include "IwGx.h"
#include "ExamplesMain.h"

//-----------------------------------------------------------------------------

enum states { mounted, read, reset, error}; //State enumerations
states status;              //Statemachine for file operation
char ErrorString[0x100];    //Contains info about errors for displaying purposes
char* ReadBuffer;           //Data which is being read from the file

void CreateButtonsUI(int w, int h)
{
    // Create the UI
    switch (status)
    {
    case reset:
            AddButton("Attach archive", 10, 200, w/2, 30, s3eKey0);
            break;
    case mounted:
            AddButton("Read archive", 10, 200, w/2, 30, s3eKey1);
            break;
    default:
        break;
    }
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise file status
    status = reset;
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Detach the archive.
    dzArchiveDetach();

    // Free the read buffer.
    delete [] ReadBuffer;

    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}

//-----------------------------------------------------------------------------
// The following function checks the keyboard state and performs a number of
// operations based on it. The options are:
// <ul>
//  <li>If s3eKey0 is pressed, the archive "archive1.dz" is attached.
//  <li>If s3eKey1 is pressed, the attached archive is read using the s3e interface,
//      the contents are then displayed on the screen.
// </ul>
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Pressing 0 attaches an archive and automatically mounts the Derbh custom file system.
    if ((CheckButton("Attach archive") & S3E_KEY_STATE_PRESSED)
        && (status == reset))
    {
        // Attach archive.
        int32 result = dzArchiveAttach("archive/archive1.dz");
        if (result == S3E_RESULT_ERROR)
        {
            // An error occurred.
            strcpy(ErrorString, "Error attaching archive");
            status = error;
        }
        else
        {
            // The filesystem was mounted with no errors.
            status = mounted;
        }
        DeleteButtons();
        CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
    }

    //Press 1 to read the text file from the compressed archive
    //then display the contents on the screen.
    if ((CheckButton("Read archive") & S3E_KEY_STATE_PRESSED)
        && (status == mounted))
    {
        //All of the s3eFile calls from this point map to the versions
        //in the mounted Derbh file system.

        //Open file for reading.

        s3eFile* handle = s3eFileOpen("TextFile.txt","rb");

        //Get the size of the file in its uncompressed state.

        uint32 filesize = s3eFileGetSize(handle);

        //Allocate a read buffer, the extra space is for a formatting string
        //so that s3eDebugPrint will display the text slightly faded.

        ReadBuffer = new char[filesize + 8];

        //Copy the formatting string.

        strcpy(ReadBuffer,"`x666666");

        //Initialise a pointer to the buffer after the formatting string.

        char* buff = ReadBuffer + 8;

        //Read the file into the buffer.

        int result = s3eFileRead(buff, filesize, 1, handle);

        //Close the file.
        s3eFileClose(handle);

        if (result != 0)
        {
            //No error has occurred
            status = read;
        }
        else
        {
            //Something went wrong during opening of the file
            //retrieve error for display
            status = error;
            s3eFileGetError();
            strcpy(ErrorString, s3eFileGetErrorString());
        }
        DeleteButtons();
        CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function constitutes the UI rendering.
//-----------------------------------------------------------------------------

void ExampleRender()
{
    IwGxFlush();

    //Display permanent explanatory text at the top of the window.
    int32 y = 60;
    IwGxPrintString(10, y, "Access to compressed Derbh archive via S3E interface.", true);
    y+=20;
    IwGxPrintString(10, y, "Illustrates the use of mounting a custom file system.", true);
    y+=20;
    IwGxPrintString(10, y, "Press escape at any time to exit.", true);
    y+=20;

    switch (status)
    {
    case reset:
            IwGxPrintString(10, y, "`x666666Press 0 or the Attach button to attach archive",true);
            break;

    case mounted:
            IwGxPrintString(10, y, "File system mounted.", true);
            y+=10;
            IwGxPrintString(10, y, "`x666666Press 1 or the Read button to read TextFile.txt from archive and display the contents.", true);
            break;

    case read:
            IwGxPrintString(10, y, ReadBuffer, true);
            break;

    case error:
            IwGxPrintString(10, y, ErrorString, true);
            break;
    }

    //Show the surface, then clear it for next time round.
    IwGxSwapBuffers();
}


Airplay API Reference: IwUtil API Documentation

Airplay API Reference > IwUtil API Documentation >

IwUtil API Documentation

The IwUtil documentation contains the following sections:

  • IwUtil API Overview
  • IwUtil API Reference
  • IwUtil Examples


Airplay API Reference: IwUtil API Overview

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview >

IwUtil API Overview

IwUtil is a collection of utility APIs. These are used extensively by all higher-level modules, including IwGx and IwGraphics. They can also be made use of directly, and provide some very useful low-level functionality.

To use IwUtil functionality, you must include "IwUtil.h" in your source and iwutil as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwutil
  • }

The IwUtil subproject is automatically included by all other higher level modules in their MKFs.

The following subjects are covered in this section:

  • IwUtil Initialisation and Termination
  • Memory Management
  • String Hashing
  • Class Factory
  • Image Manipulation
  • Key Mapping
  • Managed Objects
  • Serialisation
  • Text Parsing
  • Callstack
  • Debug Menus
  • Array
  • Debug
  • Random


Airplay API Reference: IwUtil Initialisation and Termination

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > IwUtil Initialisation and Termination >

IwUtil Initialisation and Termination

The user must initialise IwUtil and terminate IwUtil as follows:

  • // Begin application
  • IwUtilInit();

    • ...rest of application

  • // End application
  • IwUtilTerminate();

It is illegal to call any IwUtil API function or create an IwUtil class before calling IwUtilInit().

IwUtilInit() initialises the memory management system for Airplay Studio. For this reason, it is advisable for the application to avoid any dynamic memory allocations before calling IwUtilInit().

Note: Static memory allocations are acceptable, but be aware that any static memory allocation subject to re-allocation (for instance, a static instance of CIwArray, which can by dynamically resized through re-allocation) may cause problems if the re-allocation occurs whilst the current memory bucket is not the main heap. See Memory Management for more details.


Airplay API Reference: Memory Management

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Memory Management >

Memory Management

IwUtil provides a useful memory management API based around the concept of buckets. Buckets are used to reduce memory fragmentation by isolating memory allocation. Memory fragmentation can become a problem for applications that have a limited amount of memory and frequently make memory allocations, for example, mobile games.

The bucket system allows the user to do the following:

  • The user can allocate multiple buckets, of known fixed sizes, at the start of an application. Memory allocations are then made from within these buckets.
  • The user can change the current bucket at any time, thus controlling the bucket from which specific allocations are made. In this way, it is possible to drastically reduce memory fragmentation.

The total amount of heap memory available to the application is set within the ICF file, as follows:

  • [S3E]
  • MemSize=2000000 # set total heap of almost 2Mb

If we do not create any buckets, the default behaviour is for all memory allocations/deallocations to happen from within this main heap.

How memory is used is discussed in the following section:

  • Using Buckets
  • Debugging Memory Behaviour Using Buckets
  • Keeping Memory Allocation Uniform Between Debug And Release Builds


Airplay API Reference: Using Buckets

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Memory Management > Using Buckets >

Using Buckets

Generally at the start of your application you would create your memory buckets. This can be done using the following code:

  • enum
  • {
    • FIXED = IW_MEM_BUCKET_ID_USER,
    • LEVEL,
  • };
  • IwMemBucketCreate(FIXED, "Fixed", 0x80 * 0x400); // 128k
  • IwMemBucketCreate(LEVEL, "Level", 0x400 * 0x400); // 1024k

Note: You must start you enumerated list of bucket IDs from IW_MEM_BUCKET_ID_USER, as IDs below this may be used by the SDK.

You can then set the current bucket before making memory allocations using the following code:

  • IwMemBucketSet(FIXED);
  • uint32* pDataFixed0 = new uint32[0x100];
  • uint32* pDataFixed1 = new uint32[0x200];

These allocations have now come from a bucket other than the default main heap (defined by the SDK as bucket 0). Now let's change the current bucket and make some more allocations:

  • IwMemBucketPush(LEVEL);
  • uint32* pDataLevel0 = new uint32[0x100];
  • uint32* pDataLevel1 = new uint32[0x80];

This time we have used IwMemBucketPush() rather than IwMemBucketSet(), this will allow us easily to return to the previous current bucket, using IwMemBucketPop()

We can check the amount of used and free memory within a bucket as follows:

  • uint32 used = IwMemBucketGetUsed(FIXED);
  • uint32 free = IwMemBucketGetFree(FIXED);

Now to free the allocations we have made:

  • delete[] pDataLevel0;
  • delete[] pDataLevel1;
  • IwMemBucketPop().
  • delete[] pDataFixed0;
  • delete[] pDataFixed1;

Note: It is not necessary, when freeing an allocation, for the current bucket to be set to the same bucket as when the allocation was made.

At any time, we can switch back to using the main heap, rather than our fixed buckets, simply by switching to IW_MEM_BUCKET_ID_SYSTEM:

  • IwMemBucketSet(IW_MEM_BUCKET_ID_SYSTEM);

The memory bucket API also contains useful debug functions which can, for example, trace details of all bucket allocations to a text file.

Note: For an example of how the IwUtil functionality is used to manage memory, see the MemoryUtility Example" in the 'Getting Started with IwUtil' documentation.


Airplay API Reference: Debugging Memory Behaviour Using Buckets

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Memory Management > Debugging Memory Behaviour Using Buckets >

Debugging Memory Behaviour Using Buckets

The memory bucket requires some overhead (approximately 920 bytes) which is reserved from the bucket's memory, so not the whole space asked for will be usable. You can use IwMemBucketGetLargestFreeBlock() to determine the largest allocation you can make.The memory bucket API also contains allocation tracking support that can massively simplify debugging memory behaviour (especially memory leaks). In debug builds, each allocation is given a sequential unique ID which can be used to identify allocations.

For example, to test a section of code for memory leaks:

  • IW_CALLSTACK("LeakArray");
  • int32 checkpoint = IwMemBucketCheckpoint();
  • uint8* leakedArray = >new uint8[100]; //This array is leaked
  • IwMemBucketDebugCheck(FIXED, checkpoint, "myLeakedArrays.txt");

A file "myLeakedArrays.txt" will be written, containing a list of leaked allocations (by function) in the specified bucket (i.e. allocations with a higher ID than 'checkpoint'). The identity of an allocating function is determined using IW_CALLSTACK macros. In this example you might see:

  • L
  • bucket
  • Fixed
  • allocated
  • 100
  • num
  • [1]
  • w/children
  • 100
  • num
  • [1]
  • FirstID
  • 1
  • Callstack of allocation
  • IwMain, LeakArray

  • The 'L' indicates that this is a 'leaf' allocation; there are no allocations in this functions children (i.e. functions called by this function, and functions called by them, etc.).
  • Bucket is the bucket the allocation was made in.
  • Allocated is the total size of allocations made by this function.
  • Num is the number of allocations.
  • W/Children is the total size of allocations made by this function and any child functions.
  • Num is the number of those allocations.
  • FirstID is the ID of the first allocation from this function.
  • Callstack of allocation is the callstack of the function.

You can get a list of everything allocated in a bucket at any time by calling IwMemBucketDebugCheck with a checkpoint of zero, e.g:

  • IwMemBucketDebugCheck(FIXED, 0, myLeakedArrays.txt");

If your application makes allocations in the same order on its next run (this is normally the case for at least the initialisation of most applications) then each allocation will have the same ID.

You can use this property to easily identify large or leaking allocations. In this case we would add this line to the start of the program:

  • IwMemBucketDebugSetBreakpoint(1);

On the next run, the debugger would break when it makes allocation 1 (which would be underneath the line that allocates the array).


Airplay API Reference: Keeping Memory Allocation Uniform Between Debug And Release Builds

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Memory Management > Keeping Memory Allocation Uniform Between Debug And Release Builds >

Keeping Memory Allocation Uniform Between Debug And Release Builds

One of the most important aspects of making a program behave reliably across multiple platforms and configurations is keeping behaviour as uniform as possible. This applies to memory allocation as much as anything else: Problems caused by heap fragmentation can be very hard to track down.

Generally a debug build is behaving differently to a release build (especially if resources are being built). To avoid disrupting memory allocation patterns Airplay Studio uses the debug bucket for any allocations that are made only in debug builds.

Airplay applications should follow this pattern - the debug bucket can be used in the same way as any other bucket, using IW_MEM_BUCKET_ID_SYSTEM_DEBUG. If this pattern is followed then the memory behaviour of debug and release builds should match exactly, reducing the amount of time spent debugging release-only issues.

The size of this bucket can be set from the icf and can be set differently for ARM and X86 builds. The default for X86 builds in 5mb (5242880 bytes), while for ARM builds it is 1mb (1048576 bytes). To change these values, use the icf settings [s3e] MemSizeDebug (X86) and MemSizeDebugDevice (ARM).

Note: See S3E ICF Settings for a detailed listing of memory allocation and other icf settings.


Airplay API Reference: String Hashing

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > String Hashing >

String Hashing

Frequently, it is useful to generate a unique integer value from a string. IwHashString() uses a fast algorithm to generate 32-bit hash values that have a statistically-negligible probability of ever being equal for non-equal strings. For example, the following code should never assert, regardless of the two non-equal strings used:

  • uint32 hash0 = IwHashString("A string");
  • uint32 hash1 = IwHashString("Another string");
  • IwAssertMsg(USER, hash0 != hash1, ("IwHashString failed!"));

String inputs are effectively converted to lower case before the hashing algorithm is applied. This is the most "forgiving" implementation, as it allows, for example, scripts to reference art assets without requiring the correct capitalisation. For example, the following code will not assert because the strings differ only in their capitalisation:

  • uint32 hash0 = IwHashString("A string");
  • uint32 hash1 = IwHashString("A STRING");
  • IwAssertMsg(USER, hash0 == hash1, ("IwHashString failed!"));

CIwManaged makes use of IwHashString for its naming of instances; given that this is the base C++ class for almost all SDK classes, the feature is a foundation of the entire SDK.

Note: For an example of how the IwUtil functionality is used to create hash strings, see the Hash Example.


Airplay API Reference: Class Factory

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Class Factory >

Class Factory

The SDK class factory system maps string names to user defined factory functions. Typically a "classname" is mapped to a "factory" which returns a new instance of that class, this is the default behaviour.

This mapping is typically bijective, but it is possible to associate multiple strings with the same factory function if desired.

This feature has great utility when performing parsing operations as it allows instances to be created by name.

Additionally the user can define their own custom factory functions with more complicated behaviour. For example, a factory may return a pointer to a cached object rather than create a new instance.

The implementation consists of a set of (hash,factory) ordered pairs where each hash is unique.

The default behaviour of a class factory function is to create an instance of an appropriate class, and return a pointer to that instance. If the user passes a class name string into IwClassFactoryCreate(), a hash of the classname is used as a key to lookup the associated factory. If one is found, the corresponding function is called, and a pointer to the new instance is returned. If no matching hash is found, NULL is returned.

Macros are provided to ease the set-up of the string-function pairs.

To implement the default factory function for 'MyClass' add the following to your source:

  • IW_CLASS_FACTORY(MyClass);

To register this default factory function with the class factory system, use:

  • IW_CLASS_REGISTER(MyClass);

These are all that is required to add support for "MyClass" to the global class factory. The macros are generally implemented at the top of an appropriate CPP file.

To implement a custom class factory for 'MyClass' instead of using the default one omit the IW_CLASS_FACTORY(MyClass).

Instead define a function in your source with the prototype void * _MyClassFactory() {}; and fill out your custom implementation. Register the factory function as normal.

The class factory is used extensively by the text parser, resource manager and the serialisation of managed objects.

Note: For an example of how the class factory is used, see the Class Factory Example.


Airplay API Reference: Image Manipulation

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Image Manipulation >

Image Manipulation

The SDK supports loading of BMP, GIF, PNG and TGA files into memory. Supported file types are detailed in the table below.

CIwImage is the class used to load and manipulate images. Reading an image file from disk is simple:

  • CIwImage image;
  • s3eFile* pFile = s3eFileOpen("./images/MyImage.bmp");
  • image.ReadFile(pFile);
  • s3eFileClose(pFile);

You can then get access to the image texels and palette (if the image was read from a palettised format) using:

  • uint8* pTexels = image.GetTexels();
  • uint8* pPalette = image.GetPalette();

CIwImage also provides accessors to query the width, height, bit-depth etc.

Once a CIwImage has been constructed in a certain format, it can be converted into any other supported format. Below, we load an image from disk and convert to a new image of format RGBA_5551:

  • CIwImage image;
  • s3eFile* pFile = s3eFileOpen("./images/MyImage.bmp");
  • image.ReadFile(pFile);
  • s3eFileClose(pFile);
  • CIwImage imageNew;
  • imageNew.SetFormat(CIwImage::RGBA_5551);
  • image.ConvertToImage(imageNew);

In this code 'image' is the source image. 'imageNew' is the destination image of the new desired format.

Note: The source image remains unchanged; the destination image is a new image of the desired format.

Supported File Types

The following formats can be read:

  • File Type
  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • BMP
  • GIF
  • GIF
  • GIF
  • GIF
  • PNG
  • PNG
  • PNG
  • TGA
  • TGA
  • TGA
  • TGA
  • TGA
  • TGA
  • Bits Per Pixel
  • 4
  • 4
  • 8
  • 8
  • 16
  • 24
  • 32
  • 4
  • 5
  • 6
  • 8
  • 4
  • 8
  • 24
  • 16
  • 16
  • 24
  • 24
  • 32
  • 32
  • Palettised
  • yes
  • yes
  • yes
  • yes
  • no
  • no
  • no
  • yes
  • yes
  • yes
  • yes
  • yes
  • yes
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • Run-length Encoded
  • no
  • yes
  • no
  • yes
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • no
  • yes
  • no
  • yes
  • no
  • yes

Supported Image Types

The following internal image formats are supported (i.e., an image can be converted to any of these formats):

  • Type
  • RGB_332
  • BGR_332
  • RGB_565
  • BGR_565
  • RGBA_4444
  • ABGR_4444
  • RGBA_5551
  • ABGR_1555
  • RGB_888
  • BGR_888
  • RGBA_6666
  • ABGR_6666
  • RGBA_8888
  • ABGR_8888
  • RGBA_AAA2
  • ABGR_2AAA
  • PALETTE4_RGB_888
  • PALETTE4_RGBA_8888
  • PALETTE4_RGB_565
  • PALETTE4_RGBA_4444
  • PALETTE4_RGBA_5551
  • PALETTE4_ABGR_1555
  • PALETTE8_RGB_888
  • PALETTE8_RGBA_8888
  • PALETTE8_RGB_565
  • PALETTE8_RGBA_4444
  • PALETTE8_RGBA_5551
  • PALETTE8_ABGR_1555
  • Description
  • Unpalettised, 8-bits per texel.
  • Unpalettised, 8-bits per texel.
  • Unpalettised, 16-bits per texel.
  • Unpalettised, 16-bits per texel.
  • Unpalettised, 16-bits per texel, 4-bit alpha.
  • Unpalettised, 16-bits per texel, 4-bit alpha.
  • Unpalettised, 16-bits per texel, 1-bit alpha.
  • Unpalettised, 16-bits per texel, 1-bit alpha.
  • Unpalettised, 24-bits per texel.
  • Unpalettised, 24-bits per texel.
  • Unpalettised, 24-bits per texel, 6-bit alpha.
  • Unpalettised, 24-bits per texel, 6-bit alpha.
  • Unpalettised, 32-bits per texel, 8-bit alpha.
  • Unpalettised, 32-bits per texel, 8-bit alpha.
  • Unpalettised, 32-bits per texel, 2-bit alpha.
  • Unpalettised, 32-bits per texel, 2-bit alpha.
  • 16-colour palettised, 24-bit palette entries.
  • 16-colour palettised, 32-bit palette entries with 8-bit alpha.
  • 16-colour palettised, 16-bit palette entries.
  • 16-colour palettised, 16-bit palette entries with 4-bit alpha.
  • 16-colour palettised, 16-bit palette entries with 1-bit alpha.
  • 16-colour palettised, 32-bit palette entries with 1-bit alpha.
  • 256-colour palettised, 24-bit palette entries.
  • 256-colour palettised, 32-bit palette entries with 8-bit alpha.
  • 256-colour palettised, 16-bit palette entries.
  • 256-colour palettised, 16-bit palette entries with 4-bit alpha.
  • 256-colour palettised, 16-bit palette entries with 1-bit alpha.
  • 256-colour palettised, 16-bit palette entries with 1-bit alpha.

Note: For an example of how the IwUtil functionality is used to format an image, see the Image Format Example.


Airplay API Reference: Key Mapping

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Key Mapping >

Key Mapping

When checking for input within your application, it is sensible to employ a level of indirection, which allows you to change the key mapping at a later date.

The IwKeymap API provides such a mapping. The user first enumerates a list of application keys, for example:

  • enum
  • {
    • LEFT,
    • RIGHT,
    • UP,
    • DOWN,
    • FIRE,
    • ACTION,
  • }

These are then mapped to system keys, for example:

  • IwKeymapMapKey(LEFT, s3eKeyLeft);
  • IwKeymapMapKey(RIGHT, s3eKeyRight);
  • IwKeymapMapKey(UP, s3eKeyUp);
  • IwKeymapMapKey(DOWN, s3eKeyDown);
  • IwKeymapMapKey(FIRE, s3eKey1);
  • IwKeymapMapKey(ACTION, s3eKey2);

When checking for input within the application, the user should use the IwKeymap methods rather than the s3eKeyboard methods, as follows:

  • // Check for "LEFT"
  • if (IwKeymapGetState(LEFT) & s3eKeyStateDown)
  • {

    • ...

  • }

The advantage of this system is, of course, that the mapping of application keys to system keys can be changed at any time, and the code which checks for input can remain untouched.

Note: For an example of how the IwUtil functionality is used to map keys, see the Key Mapping Example.


Airplay API Reference: Managed Objects

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Managed Objects >

Managed Objects

The S3D SDK is a C++ API which uses single class inheritance to provide useful class hierarchies. Most of the classes used within the API share a common base class - CIwManaged.

CIwManaged is a lightweight class which contains several useful virtual functions and essentially one data member - a class instance name. A member function allows each class instance (object) to be given a string name. For Debug builds, the full string name is stored on the object, together with a 32-bit hashed value of the string name. For Release builds, only the hashed value is stored.

The user sets the instance name with the SetName() method. Conceptually, this method does the following:

  • void CIwManaged::SetName(const char* name)
  • {
  • #ifdef IW_DEBUG
    • m_DebugName = name;
  • #endif
    • m_Hash = IwHashString(name);
  • }

Instances of classes derived from CIwManaged do not have to be given names - but often it is useful, especially as objects are commonly added to a CIwManagedList, which can then be searched for a given object by name.

The string name of the object can be retrieved using 'DebugGetName()'. This method makes clear that the full string name is only available in Debug builds - in Release builds, this method will return an empty string.

User classes derived from CIwManaged must implement two macros; one within the class declaration, and one within an associated source file. The macro IW_MANAGED_DECLARE(<classname>) must be implemented within the class declaration; this macro declares, amongst other things, the GetClassName() method, which returns a string version of the classname. The macro IW_MANAGED_IMPLEMENT(<classname>) must be implemented in some source file. This macro implements the GetClassName() method which returns a string version of the classname.

For example:

In MyClass.h

  • class CMyClass : public CIwManaged
  • {
  • public:
    • IW_MANAGED_DECLARE(CMyClass);
    • // Other class method and member declarations
    • int32 m_Value0;
    • uint16 m_Array[4];
    • CiwStringS m_UserName;
  • };

In MyClass.cpp

  • IW_MANAGED_IMPLEMENT(CMyClass);
  • // Other class method implementations

The virtual functions provided by CIwManaged are covered in the following section:

  • CIwManaged Virtual Functions

Note: For an example of how the IwUtil functionality is used to create managed objects, see the Managed Object Example.


Airplay API Reference: CIwManaged Virtual Functions

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Managed Objects > CIwManaged Virtual Functions >

CIwManaged Virtual Functions

This section gives a brief overview of some of the virtual functions provided by CIwManaged.

Serialise()

This method is used to read or write a binary version of the class instance to a file. For this method, the user can assume that a binary file has been opened for either reading or writing. The implementation of Serialise() generally does not need to know whether we are reading or writing, as it makes use of lower-level serialisation methods which check the serialisation context and act accordingly.

Note: See the Serialisation documentation for a description of how serialisation works.

For example, we could implement the Serialise() method of CMyClass, as declared above, as follows:

  • void CMyClass::Serialise()
  • {
    • IwSerialiseInt32(m_Value);
    • IwSerialiseInt16(m_Array, 4);
    • m_UserName.Serialise();
  • }

IwSerialiseInt32() is an SDK method that checks whether we have opened the binary file for reading or writing; if reading, it reads 4 bytes from the file and stores them in the specified member; if writing, it writes 4 bytes from the member to the file.

Sometimes the implementation of Serialise() will need to check whether we are reading or writing; it can do this by checking the boolean member g_IwSerialiseContext.read, which is true if we are reading and false if we are writing.

ParseOpen(), ParseAttribute(), ParseClose(), ParseCloseChild()

These methods allow a class instance to be parsed from a text file. A full description of how to use this system is given in the Text Parsing documentation.

DebugAddMenuItems()

This method allows the class instance to add items to the debug menu system. A full description of how to use this system is given in the Debug Menu documentation.


Airplay API Reference: Serialisation

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Serialisation >

Serialisation

Serialisation is the process of reading or writing application data to binary files. Within the SDK, serialisation is build around the concept of a single state object which holds the current binary filename and read/write state, together with many low-level functions that check the state object and read or write data accordingly. In this way, the same code is used both to write object data to a binary file and to read that data back into an object. This reduces the amount of code required and most importantly ensures that the reading and writing code paths are always completely synchronised.

For example, suppose we have two classes as follows:

  • class CMyClassA
  • {
  • public:
    • int16 m_Flags;
    • void Serialise();
  • };
  • class CMyClassB
  • {
  • public:
    • uint32 m_Value0;
    • uint8 m_Buffer[32];
    • CMyClassA* m_ClassA;
    • void Serialise();
  • };

The serialisation of CMyClassA is trivial, as follows:

  • void CMyClassA::Serialise()
  • {
    • IwSerialiseInt16(m_Flags);
  • }

The serialisation of CMyClassB is more interesting, as it makes use of the serialisation of CMyClassA, as follows:

  • void CMyClassB::Serialise()
  • {
    • IwSerialiseUInt32(m_Value0);
    • IwSerialiseUInt8(m_Buffer, 32);
    • m_ClassA->Serialise();
  • }

These methods can be called either to read or to write data; the lower-level serialisation functions (such as IwSerialiseInt16() ) check the current serialisation state, and either read or write data accordingly.

In the serialisation of CMyClassB, we have assumed that m_ClassA is already pointing to a valid object, both when writing and when reading. This, however, may not be the case; because of this you may need to check the status of the member variable when writing, and instantiate the object when reading. We could modify the serialisation of CMyClassB as follows:

  • void CMyClassB::Serialise()
  • {
    • IwSerialiseUInt32(m_Value0);
    • IwSerialiseUInt8(m_Buffer, 32);
    • uint8 isObject;
    • If (IwSerialiseWriting())
    • {
      • // Writing
      • // Write a single byte to say whether or not a
      • // serialisation of a CMyClassA object follows
      • isObject = m_ClassA ? 1 : 0;
      • IwSerialiseUInt8(isObject);
      • // Write the object, if it exists
      • if (m_ClassA)
        • m_ClassA->Serialise();
    • }
    • else
    • {
      • // Reading
      • /* Read a single byte to determine whether or not a serialisation of a CMyClassA object follows */
      • IwSerialiseUInt8(isObject);
      • // If required, instantiate and read the object
      • if (isObject)
      • {
        • m_ClassA = new CMyClassA;
        • m_ClassA->Serialise();
      • }
    • }
  • }

Note: For an example of how the IwUtil functionality is used to serialise, see the SerialisingExample".


Airplay API Reference: Text Parsing

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Text Parsing >

Text Parsing

The SDK employs a powerful text parser which makes use of the CIwManaged base class and the Class Factory concept.

User classes derived from CIwManaged can make use of the text parser, thus allowing objects of the user class to be instantiated and read from text files.

The text files are constructed in a format somewhere between C++ code and XML. White space (spaces, tabs and carriage returns) are used to separate tokens in the text file. C style comments and C++ style comments are both permitted.

Text files constructed in this way are deemed to be "ITX" files. ITX stands for "Ideaworks TeXt". Such files do not need an .ITX extension, but for the purposes of documentation, files formatted in this way may be referred to as ITX files.

ITX files can only be parsed by deriving a class from CIwManaged, and implementing the >ParseOpen(), ParseAttribute() and ParseClose() methods. The act of parsing the ITX file will instantiate the derived class(es), then call the relevant virtual parsing methods on the instantiated object(s) to read data into them.

For example, say we have a user class CMyClassA which is derived from CIwManaged as follows:

  • class CMyClassA : public CIwManaged
  • {
    • IW_MANAGED_DECLARE(CMyClassA);
    • int32 m_Value0;
    • int32 m_Value1;
    • CIwStringS m_UserName;
    • virtual bool ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName);
    • virtual void ParseClose();
  • };

Taking for granted that we have already added it to the class factory using the IW_CLASS_FACTORY() and IW_CLASS_REGISTER() macros (see the Class Factory documentation). We could then write an ITX file as follows:

File MyClass.itx

  • // Instantiate an object of class CMyClassA
  • CMyClassA
  • {
    • value0 100
    • value1 200
    • username "fred"
  • }

To parse this file, do the following:

  • Instantiate the text parser singleton. Generally this is done at application start up time using the following code:
    • new CIwTextParserITX();
  • Parse the file using the following code:
    • IwGetTextParserITX()->ParseFile("MyClass.itx");

When parsing the file, the text parser reads each "token" one at a time. A token is a section of text before any white space. In our example, the first token read is "//". The parser then checks this against its list of known tokens. In this case, it recognises this as a C++ comment, and skips the rest of the line, up to and including the next carriage return.

The next token read is "CMyClassA". The parser does not recognise this as a known token; therefore, it checks to see if the token is a known classname by passing it into the method. Since we have registered CMyClassA with the global class factory, an object of class CMyClassA is instantiated, which the parser maintains a pointer to; in fact, the parser adds it to its object stack. The stack will now contain a single object pointer.

The next token read is "{". This is a known token, and triggers the calling of the ParseOpen() method on the recently-created CMyClassA object. Generally the user does not need to implement this method, but it could be used to perform some initialisation of the object which is not done within the class constructor.

The next token read is "value0". This is not a known token. Because the parser has a pointer to the CMyClassA object, it tries calling the object's ParseAttribute() method to see if the class itself recognises the token as an "attribute". The ParseAttribute() method of CMyClassA is responsible for recognising and parsing any text data which we may want that class to understand. It should return true only if the attribute was recognised.

We would want to implement ParseAttribute() for CMyClassA as follows:

  • bool CMyClassA::ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
  • {
    • if (!strcmp(pAttrName, "value0"))
      • pParser->ReadUInt32(&m_Value0);
    • else
    • if (!strcmp(pAttrName, "value1"))
      • pParser->ReadUInt32(&m_Value1);
    • else
    • if (!strcmp(pAttrName, "username"))
    • {
      • char line[32];
      • pParser->ReadString(line, 32);
      • m_UserName = line;
    • }
    • else
      • return CIwManaged::ParseAttribute(pParser, pAttrName);
    • return true;
  • }

This method checks for any attribute strings understood by the class, but not any parent classes; if found, it reads any expected value data and then returns true. If not found, it passes the attribute on to its parent class, and returns the result received from the parent class's ParseAttribute() method.

Finally, we should implement ParseClose() for CMyClassA to do something useful with the object we have instantiated; otherwise, it will be left "hanging" and not be accessible outside the text parser. Usually, we implement ParseClose()to add the object to a list of some sort.

Returning to the parsing of our example file:

The text parser has just parsed the token "value0". This is passed to the ParseAttribute() method of top item on the parser's object stack; that is, the object that was instantiated by parsing the previous classname string. In our example, ParseAttribute() does indeed recognise the attribute string "value0", and expects it to be followed by an integer value, which it also parses into the correct member of the object.

Next, the parser reads the token "value1". The same process applies - the attribute string is understood by the ParseAttribute() method of the object on top of the parser's object stack, which again expects an integer value to follow, and it reads that value.

Next, the parser reads the token "username". ParseAttribute() again recognises that attribute string, and expects it to be followed by a string; the subsequent string value is then parsed.

Note: Strings in ITX files can optionally be bounded by quotation marks; it is strongly suggested that ALL string values in ITX files be bounded by quotation marks; otherwise the use of white space within a string value would confuse the parser completely.

Finally, the parser reads the token "}". This is a known token, and triggers the calling of the ParseClose() method on the object on top of the parser's object stack. The object is then "popped" from the parser's object stack.

Note: Generally, the user implements ParseClose() to add the created object to some sort of list.

GEO, MTL and GROUP files are all examples of text files in ITX format. It is recommended that you look at some of the SDK examples to get a better feeling for how the text parser works.

Note: For an example of how the IwUtil functionality is used to parse text, see the Text ParsingExample".


Airplay API Reference: Callstack

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Callstack >

Callstack

Assertion dialogs are useful for checking the validity of your application logic. Often, when displaying an assertion dialog, it is useful to see the function callstack history (especially if the application is being run outside of a debugging environment).

The SDK provides a macro, which you should place at the top of every non-trivial function, to keep track of the function callstack. For example:

  • void> CMyClass:Foo()
  • {
    • IW_CALLSTACK("CMyClass::Foo")
    • // Rest of function...
  • }

In addition, two more macros allow the user to simulate a new function scope for debugging purposes, as follows:

  • void CMyClass:Foo()
  • {
    • IW_CALLSTACK("CMyClass::Foo")
    • // Some code...
    • IW_CALLSTACK_ENTER("SubSection1")
    • // Some more code...
    • IW_CALLSTACK_LEAVE()
    • // Some more code...
  • }


Airplay API Reference: Debug Menus

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Debug Menus >

Debug Menus

The SDK contains a powerful object-oriented debug menu system which allows runtime inspection and modification of application data.

Note: For rendering the Debug Menus, IwGx must be included. See IwGx for information on using this module.

To start using the debug menu system, do the following.

  • Create the menu manager singleton. This is done using the following code:
    • new CIwMenuManager;
  • Specify a text-printing callback function, which the menu manager will use when displaying menus. The user is free to implement their own text-printing function; however, IwGx provides a default one, which should suffice for most purposes. Set the default IwGx text-printing callback function as follows:
    • IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
  • Specify a callback function which the menu manager will use to create the top level menu. The menu manager itself polls for input, and creates/destroys the top level menu accordingly. The following is an example of a top level menu callback function, which makes use of the default top level menu items for the IwGx and IwResManager modules:
    • CIwMenu* DebugCreateMainMenu()
    • {
      • CIwMenu* pMenu = new CIwMenu;
      • #ifdef IW_DEBUG
        • pMenu->AddItem(new CIwMenuItemResManager);
        • pMenu->AddItem(new CIwMenuItemGx);
      • #endif
      • return pMenu;
    • }
  • Set the pointer to the top level menu callback function as follows:
    • IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);

We have now done everything we need to initialise the debug menu system. All we need to do now is call the menu manager's >Update() and Render() methods within our own application update and render sections. For example:

  • void CMyApp::Update()
  • {
    • ...
    • IwGetMenuManager()->Update();
    • ...
  • }
  • void CMyApp::Render()
  • {
    • ...
    • IwGetMenuManager()->Render();
    • ...
  • }

How does the debug menu system work? Give it a try - run your application in Windows and press F6 - this is the default key to toggle the menu system on/off. The menu manager will now call our top-level menu callback function. As you can see, this function creates a single menu containing two items. Each item is derived from the CIwMenuItem base class, and becomes a "row" of the menu. CIwMenuItem contains virtual methods which are used to render the item and react when the menu receives input to that item (for example, when directional keys are pressed whilst that menu item is selected).

Experiment with the menu you have just created. Press up/down arrows to change the highlighted item in the menu. Press the right arrow to select a menu item. Selecting an item will often cause a new menu to be created. In this case, the new menu is displayed, and the old menu is effectively "underneath" it, on a stack of menus. Press the left arrow to move back to the previous menu (that is, pop the current menu from the stack).

If you have highlighted a menu item which contains a modifiable field, use NumPad+ and NumPad- to modify the field. Additionally, you can hold SHIFT to modify the field in steps of 10, or hold CTRL to modify the field in steps of 100. (The same applies when using the up/down arrows to navigate the menu - hold SHIFT to move up and down the menu 10 items at a time, etc.)

When you are done, press F6 again to turn off the menu system.

The menu system provides many low-level menu item classes which allow inspection/modification of data members. For example, say we have the following class:

  • class CMyClassA : public CIwManaged
  • {
    • enum
    • {
      • FLAG_0 = (1 << 0),
      • FLAG_1 = (1 << 1),
    • };
    • IW_MANAGED_DECLARE(CMyClassA);
    • int32 m_Value0;
    • int32 m_Value1;
    • uint8 m_Value2;
    • uint32 m_Flags;
  • };

We would use the following code to allow access to the class members through a debug menu:

  • pMenu->AddItem(new CIwMenuItemEditInt32("Value0", &m_Value0));
  • pMenu->AddItem(new CIwMenuItemEditInt32("Value1", &m_Value1));
  • pMenu->AddItem(new CIwMenuItemEditUInt8("Value2", &m_Value2));
  • // Allow inspection of entries in uint32 flags
  • // fieldpMenu->AddItem(new CIwMenuItemEditFlags("FLAG_0", &m_Flags,FLAG_O);
  • pMenu->AddItem(new CIwMenuItemEditFlags("FLAG_1", &m_Flags,FLAG_1);

Note: For an example of using the Debug Menu functionality, see the IwUtil Debug Menu Example.


Airplay API Reference: Array

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Array >

Array

The SDK makes no use of the STL(Standard Template Library) internally. However, it does contain some functionality that replicates useful sections of the STL.

CIwArray is a templated class that aims to mimic >std::vector. It contains many of the same methods, for example:

  • push_back()
  • size()
  • clear()

CIwArray implements an allocator scheme that dynamically allocates memory as the array grows. It deallocates memory only when destroyed or when the user requests it to do so.

An example of using CIwArray:

    CIwArray<uint32> ids;
  • ids.push_back(5); // adds the value 5 to the end of the array
  • ids.push_back(7); // adds the value 7 to the end of the array
  • ids.push_back(2); // adds the value 2 to the end of the array
  • uint32 val0 = ids[0]; // gets the value 5
  • uint32 val1 = ids[1]; // gets the value 7
  • uint32 val2 = ids[2]; // gets the value 2
  • uint32 size = ids.size(); // gets the value 3
  • ids.clear(); // removes all elements from the array

Note: For an example of how the Array functionality can be used, see the Array Example.


Airplay API Reference: Debug

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Debug >

Debug

The SDK contains two very useful and familiar elements of debugging functionality:

  • Assertions
  • Tracing

Both of these will only produce output when using a debug loader or application. The debug loader will write trace to file and fire assertions whenever noteworthy events occur. The application can use assertions and tracing via the IwUtil Debug functions outlined here. It is possible to mix a debug loader with a release application build and vice-versa, in which case only the relevant trace and assertions will be output.

Note: For an example of how the Debug functionality can be used, see the Debug Example.


Airplay API Reference: Assertions

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Debug > Assertions >

Assertions

Assertions allow the code to perform some kind of run-time checking and pause execution with a dialog box if the check fails. The SDK allows assertions to be grouped into channels, which can be individually enabled or disabled.

Assertion Channels

Each SDK module defines its own assertion channels; for example, GX, GRAPHICS, RESMANAGER. If an error occurs within a Debug build of the IwGx runtime, it will display an assertion only if the GX assertion channel is enabled.

An assertion dialog will look similar to the one below:

"IwAssert failure (<channel>, <ID>)" tells the user which channel the assertion has fired on, and also provides a unique ID for the assertion which can be provided to Ideaworks Labs support if necessary.

"Message:" gives an explanation of why the assertion has fired.

"Callstack:" gives a description of the entire functional callstack which has lead to the assertion. This always begins with "IwMain" and generally ends at the function within which the assertion has fired.

The user then has 3 options:

  • Break/Abort: Break execution. If in the debugger, the debugger should highlight the line containing the assertion. If the assertion has fired within an SDK library, the user can scroll down the debugger call stack to see the last user function which was called.
  • Retry/Continue: Continue execution. This may be possible if the assertion failure has not resulted in an inability for the code to continue sensibly. Note that the same assertion will still fire the next time the same conditions arise.
  • Ignore (All): Ignore this assertion forever. Again, this may be possible if the assertion failure has not resulted in an inability for the code to continue sensibly. Note that the same assertion will never fire again within the lifetime of the application.

All SDK assertion channels are enabled by default. However, the user can choose to turn any of them off simply be editing the app.icf file. For example, to disable the GX assertion channel, add the following to the app.icf file:

  • [ASSERT]
  • GX=0

In this case, no assertions will appear on the GX channel.

User Assertion Channels

The user can also define their own assertion channels simply by specifying a new channel name in the code in place of one of the default ones.

All user assertion channels are enabled by default. Again, they can easily be turned off within the app.icf file. For example:

  • [ASSERT]
  • MYAPP=0 # disables the app's MYAPP assertion channel

Creating Assertions

Application code can then assert using this channel:

  • uint32 val = 1;
  • IwAssertMsg(MYAPP, val == 1, ("Illegal value"));

IwAssertMsg() takes three inputs: the assertion channel name, the boolean test condition, and the error string to display if the condition is found to be false.

The error string is enclosed within brackets. This is because the string can take standard printf-style arguments. For example:

  • uint32 val = 1;
  • IwAssertMsg(MYAPP, val == 1, ("Illegal value of %s - value should be %d", "val", 1));

A second function, IwAssert(), is provided that will halt execution, but it will not display any message within the dialog box. For example:

  • uint32 val = 1;
  • IwAssert(MYAPP, val == 1);

Note: Much of the Airplay Studio SDK is designed to be tolerant of assertion failures. For instance - a drawing function which takes pointer inputs will not crash if those inputs are null. Instead, it will fire an assertion, and then exit the function without performing any drawing. In this way, the user can decide whether to "Abort" execution and look into why the assertion occurred; or they can "Ignore", and continue running the application, albeit without the desired drawing.


Airplay API Reference: Tracing

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Debug > Tracing >

Tracing

Tracing (or logging) is the act of writing strings to a text file. This can be a helpful way of debugging, especially on device. On Windows X86 builds, the trace file is written to the application build directory (i.e. the same directory as the VisualStudio workspace). The location of this file when run on device will vary 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 due to platform restrictions on which parts of memory are user-accessible. On most platforms, the output file is named IwTrace.txt. Exceptions are Symbian 9, which uses s3eDebugTrace.txt, and BREW, which uses iwtrace.txt.

Note: For an overview of Airplay tracing and other debug functionality plus a detailed listing of trace file output location by platform, see the Debugging section of 'Airplay Concepts'.

Trace Channels

Each SDK module defines its own trace channels; for example, GX, GRAPHICS, RESMANAGER. Tracing only occurs if the relevant trace channel is enabled.

All SDK trace channels are enabled by default. However, the user can choose to turn any of them off simply be editing the app.icf file. For example, to disable the GX trace channel, add the following to the app.icf file:

  • [TRACE]
  • GX=0

In this case, no tracing will appear on the GX channel.

Creating Trace

Application code can trace to one of the default channels, if it is enabled, using IwTrace. For example, to trace to the AUDIO channel, the following can be used:

  • IwTrace(AUDIO, ("Audio code block">));

IwTrace() takes two inputs: the trace channel name and the string to be written to the text file.

The input string is enclosed within brackets. This is because the string can take standard printf-style arguments. For example:

  • IwTrace(AUDIO, ("Code block %s, input %d", "1", 5));

User Trace Channels

The user can also define their own custom channels. This is done simply by calling IwTrace() with a user-created identifier that does not match any of those already used by Airplay. For example, to trace to a channel called "MYAPP" simply call:

  • IwTrace(MYAPP, ("Code block 1"));

    • All user trace channels are enabled by default. Again, they can easily be turned off within the app.icf file. For example:

  • @code
  • [TRACE]
  • MYAPP=0 # disables the app's MYAPP trace channel


Airplay API Reference: Random

Airplay API Reference > IwUtil API Documentation > IwUtil API Overview > Random >

Random

The SDK provides basic random number generation functionality. The basic function is a mirror of the C standard library functionality:

  • // Obtain a random number in the range 0..0x7fff
  • int16 val = IwRand();

The random number generator can be seeded with a user value. For example, if the desired behaviour is to generate a different sequence of random numbers each time the application is run, we could seed the random number generator from the device timer, as follows:

  • int32 ms = (int32)s3eTimerGetMs();
  • IwRandSeed(ms);

Utility functions provide random numbers within a specified range.

Note: For an example of how the functionality for generating random numbers can be used, see the Random Number Example.


Airplay API Reference: IwUtil API Reference

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference >

IwUtil API Reference

Modules

IwClassFactory
IwHashString
IwImage
IwImageFixedBuffer
IwKeymap
IwManaged
IwManagedList
IwMemory
IwMenu
IwCallstack
IwSerialise
IwTextParserITX
IwArray
IwAutoFile
IwDebug
IwList
IwOptimiseARM
IwOptimiseSize
IwOptimiseSpeed
IwFileString
IwRandom
IwTypes
IwUTF8
IwUtil
IwOptimiseThumb
IwString

Data Structures

class | CIwManaged
class | CIwMenuItemManaged

Defines

#define | IW_MANAGED_DECLARE(a)
#define | IW_MANAGED_DECLARE_NOCOPY(a)
#define | IW_MANAGED_IMPLEMENT(a) const char* a::GetClassName() const {return #a;}
#define | IW_MANAGED_IMPLEMENT_FACTORY(a)

Functions

CIwAutoFile::CIwAutoFile (void *pBuffer, uint32 size)
CIwAutoFile::CIwAutoFile (const char *filename, const char *mode="rb")
s3eResult | IwFileCopy (const char *dest, const char *src)
int64 | IwFileGetDirSize (const char *path, bool bDoRecursive)
s3eResult | IwFileMakeDirs (const char *path)
s3eResult | IwFileRmTree (const char *path)
int32 | IwFileSubCopy (s3eFile *pSrc, s3eFile *pDst, int32 size)
CIwAutoFile::operator s3eFile * ()
s3eFile * CIwAutoFile::s3eFile ()
CIwAutoFile::~CIwAutoFile ()

Define Documentation

#define IW_MANAGED_DECLARE ( a )

Value:

typedef CIwArray<a*>    Array; \
    typedef Array::iterator ArrayIt; \
    const char* GetClassName() const;
Declares essential functionality that is required within the public definition of any class derived from CIwManaged.
Required Header Files
IwManaged.h

#define IW_MANAGED_DECLARE_NOCOPY ( a )

Value:

typedef CIwArray<a*>    Array; \
    typedef Array::iterator ArrayIt; \
    const char* GetClassName() const; \
private: \
    a(const a &copy) { IwAssertMsgN(1376,UTIL, false, (#a " copy constructor (does nothing) called. Define the copy constructor in a derived class or use IW_MANAGED_DECLARE")); } \
    const a& operator= (const a &rhs) { IwAssertMsgN(1377,UTIL, false, (#a " operator= (does nothing) called. Define operator= in a derived class or use IW_MANAGED_DECLARE")); return *this; } \
public:
Declares essential functionality that is required within the public definition of any class derived from CIwManaged. Forbids the use of operator= and the copy constructor on derivatives. If this macro is used, a default constructor must also be defined.
Required Header Files
IwManaged.h

#define IW_MANAGED_IMPLEMENT ( a ) const char* a::GetClassName() const {return #a;}

This macro is required within some source file for every class derived from CIwManaged. It implements essential functionality.

Required Header Files
IwManaged.h

#define IW_MANAGED_IMPLEMENT_FACTORY ( a )

Value:

IW_MANAGED_IMPLEMENT(a) \
    IW_CLASS_FACTORY(a)
This macro is equivalent to IW_MANAGED_IMPLEMENT(classname) followed by IW_CLASS_FACTORY(classname).
Required Header Files
IwManaged.h

#define IW_STRING_LEN_L 160

Helper type for "long" strings (e.g. pathnames).

#define IW_STRING_LEN_S 32

Helper type for "short" strings (e.g. entity names).

Function Documentation

CIwAutoFile::CIwAutoFile | ( | void * | pBuffer,
 |  | uint32 | size |
 | ) |  |  | [inline, inherited]

CIwAutoFile constructor. This function takes the same arguments as s3eFileOpenFromMemory() (i.e., similar to fopen).

CIwAutoFile::CIwAutoFile | ( | const char * | filename,
 |  | const char * | mode = "rb" |
 | ) |  |  | [inline, inherited]

CIwAutoFile constructor. This funtion takes the same arguments as s3eFileOpen() (i.e., similar to fopen).

s3eResult IwFileCopy | ( | const char * | dest,
 |  | const char * | src
 | ) |  |

Copy a file. This is performed using fread/fwrite 1024 bytes at a time.

Returns:
S3E_RESULT_SUCCESS if the file was copied successfuly, S3E_RESULT_ERROR if the source file, or the target directory doesn't exist or if there was not enough disk space to complete the operation.

int64 IwFileGetDirSize | ( | const char * | path,
 |  | bool | bDoRecursive
 | ) |  |

Calculate the size of all the files in a folder. If bDoRecursive is set to true, it calculates the size of the internal folders as well. Directory name to examine. If true recurse the inside folders.

Returns:
-1 if the folder doesn't exists or there was an error else is the size of all the files.
Required Header Files
IwFile.h

s3eResult IwFileMakeDirs ( const char * path )

Create a directory, including all its path components. Directory name to create.

Returns:
S3E_RESULT_SUCCESS, if all path components were successfully created, or if the path already existed. S3E_RESULT_ERROR if any one of the paths failed to be created.
Required Header Files
IwFile.h

s3eResult IwFileRmTree ( const char * path )

Recursively remove a folder and all its contents. Directory name to remove.

Returns:
S3E_RESULT_ERROR if the folder doesn't exists or there was an error removing one of the files within it.
Note:
it uses STL internaly
Required Header Files
IwFile.h

int32 IwFileSubCopy | ( | s3eFile * | pSrc,
 |  | s3eFile * | pDst,
 |  | int32 | size
 | ) |  |

Copy a section size bytes long from pSrc to pDst Source File Destination File Bytes to copy

Returns:
Number of bytes copied

CIwAutoFile::operator s3eFile * ( ) [inline, inherited]

This function is a cast operator. It allows CIwAutoFile objects to be used as parameters to s3eFile functions which expect s3eFile* (No checking).

s3eFile* CIwAutoFile::s3eFileGet ( ) [inline, inherited]

Gets the controlled s3eFile* (No checking).

Required Header Files
IwAutoFile.h

CIwAutoFile::~CIwAutoFile ( ) [inline, inherited]

CIwAutoFile destructor closes the owned file handle.


Airplay API Reference: IwClassFactory

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwClassFactory >

IwClassFactory
[IwUtil API Reference]

Defines

#define | IW_CLASS_FACTORY(a)
#define | IW_CLASS_FACTORY_MODIFY(a, b)
#define | IW_CLASS_POINTER(a, b) void* _##a##Factory() {return b;}
#define | IW_CLASS_REGISTER(a)
#define | IW_CLASS_REGISTER_AB(a, b)
#define | IW_CLASS_REMOVE(a) IwClassFactoryRemove(IwHashString(#a))

Typedefs

typedef void *(* | IwClassFactoryFn )()

Functions

void | IwClassFactoryAdd (const char *name, IwClassFactoryFn fn)
void | IwClassFactoryAdd (uint32 hash, IwClassFactoryFn fn)
void * | IwClassFactoryCreate (const char *name)
void * | IwClassFactoryCreate (uint32 hash)
bool | IwClassFactoryExists (uint32 hash)
IwClassFactoryFn | IwClassFactoryGet (uint32 hash)
void | IwClassFactoryModify (uint32 hash, IwClassFactoryFn fn)
void | IwClassFactoryRemove (uint32 hash)
void | IwClassFactoryReserve (int number)

Detailed Description

Note:
For more information, see the Class Factory section of the IwUtil API Documentation.

Define Documentation

#define IW_CLASS_FACTORY ( a )

Value:

void* _##a##Factory() \
{ \
    IW_CALLSTACK("_"#a"Factory"); \
    return new a; \
}
A macro that instantiates the default factory function for a named class (i.e., creates an instance of the class).
Required Header Files
IwClassFactory.h

#define IW_CLASS_FACTORY_MODIFY | ( | a,
 |  | b | )

Value:

void* _##b##Factory(); \
IwClassFactoryModify(IwHashString(#a), _##b##Factory)
A macro that changes the factory from classname a to the function for classname b.
Required Header Files
IwClassFactory.h

#define IW_CLASS_POINTER | ( | a,
 |  | b | ) | void* _##a##Factory() {return b;}

A macro that instantiates a factory function for a named class, and returns the specified pointer.

Required Header Files
IwClassFactory.h

#define IW_CLASS_REGISTER ( a )

Value:

void* _##a##Factory(); \
IwTrace(UTIL, ("Added class factory for %s (hash 0x%08lx)", #a, IwHashString(#a))); \
IwClassFactoryAdd(#a, _##a##Factory)
A macro that registers the default factory for a named class.
Required Header Files
IwClassFactory.h

#define IW_CLASS_REGISTER_AB | ( | a,
 |  | b | )

Value:

void* _##b##Factory(); \
IwTrace(UTIL, ("Added class factory for %s (hash %08lx)", #a, IwHashString(#a))); \
IwClassFactoryAdd(#a, _##b##Factory)
A macro that registers a specified factory for a named class.
Required Header Files
IwClassFactory.h

#define IW_CLASS_REMOVE ( a ) IwClassFactoryRemove(IwHashString(#a))

A macro that removes the factory for the named class.

Required Header Files
IwClassFactory.h

Typedef Documentation

typedef void*(* IwClassFactoryFn)()

A function typedef, which creates a class instance.

Function Documentation

void IwClassFactoryAdd | ( | const char * | name,
 |  | IwClassFactoryFn | fn
 | ) |  |

Adds a factory function and associate it with a name.

Parameters:
name | name for new function entry.
fn | pointer to class factory function
See also:
IwClassFactoryFn
Required Header Files
IwClassFactory.h

void IwClassFactoryAdd | ( | uint32 | hash,
 |  | IwClassFactoryFn | fn
 | ) |  |

Adds a factory function and associate it with a hash.

Parameters:
hash | Hash value for new function entry.
fn | pointer to class factory function
See also:
IwClassFactoryFn
Required Header Files
IwClassFactory.h

void* IwClassFactoryCreate ( const char * name )

Creates a class instance from a string classname.

Parameters:
The stringname of the class to create.
Returns:
The pointer to the new object. NULL if no factory avaliable.
Required Header Files
IwClassFactory.h

void* IwClassFactoryCreate ( uint32 hash )

Creates a class instance from a hashed classname.

Parameters:
A hash identifying the class.
Returns:
A pointer to the new object. NULL if no factory function avaliable.
Required Header Files
IwClassFactory.h

bool IwClassFactoryExists ( uint32 hash )

Checks that a factory function exists for the specified hash.

Parameters:
The hash identifying the class
Returns:
true if a factory exists for the class, false otherwise
Required Header Files
IwClassFactory.h

IwClassFactoryFn IwClassFactoryGet ( uint32 hash )

Gets the function associated with a particular hash.

Parameters:
hash The hash associated with the desired function.
Returns:
The factory function associated with the hash. NULL if no entry exists.
Required Header Files
IwClassFactory.h

void IwClassFactoryModify | ( | uint32 | hash,
 |  | IwClassFactoryFn | fn
 | ) |  |

Changes the factory function associated with a particular hash.

Parameters:
hash | The hash identifying the existing function entry.
fn | The new factory function to replace the old one
See also:
IwClassFactoryFn
Required Header Files
IwClassFactory.h

void IwClassFactoryRemove ( uint32 hash )

Removes the factory function associated with a hash.

Parameters:
hash hash of the factory to be removed
Required Header Files
IwClassFactory.h

void IwClassFactoryReserve ( int number )

Reserves memory for the specified number of factory functions.

Parameters:
number The number of reserved units
Required Header Files
IwClassFactory.h


Airplay API Reference: IwHashString

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwHashString >

IwHashString
[IwUtil API Reference]

Functions

uint32 | IwHashString (const char *pChar, uint32 hash)
template<int N>
uint32 | IwHashString (const CIwString< N > &sz)
uint32 | IwHashString (const char *pChar)

Detailed Description

See the String Hashing module overview for more information.

Function Documentation

uint32 IwHashString | ( | const char * | pChar,
 |  | uint32 | hash
 | ) |  |

Calculates a 32-bit hash value from a string, using a specified hash value as a starting point.

Parameters:
pChar | Pointer to the string to be hashed.
hash | The hash value to use as the starting point.
Returns:
The 32-bit hash of the supplied string, using the supplied starting value.
Required Header Files
IwHashString.h

template<int N>
uint32 IwHashString ( const CIwString< N > & sz ) [inline]

Calculates a 32-bit hash value from a string object.

Parameters:
sz Pointer to the string object to be hashed.
Returns:
The 32-bit hash of the supplied string.
Required Header Files
IwHashString.h

uint32 IwHashString ( const char * pChar )

Calculates a 32-bit hash value from a string.

Parameters:
pChar Pointer to the string to be hashed.
Returns:
The 32-bit hash of the supplied string.
Required Header Files
IwHashString.h


Airplay API Reference: IwImage

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwImage >

IwImage
[IwUtil API Reference]

Data Structures

class CIwImage

Detailed Description

See the Image Manipulation module overview for more information.


Airplay API Reference: IwImageFixedBuffer

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwImageFixedBuffer >

IwImageFixedBuffer
[IwUtil API Reference]

Functions

static bool | CIwImage::FixedBufferAvailable ()
static void | CIwImage::FixedBufferCheckOverflow ()
static void | CIwImage::FixedBufferFree ()
static void | CIwImage::FixedBufferSetSize (uint32 size)

Detailed Description

IwImage has the ability to use a fixed buffer for its texel/palette allocations. Any IwImage can be flagged to do this.

The advantage of using a fixed buffer is that it reduces fragmentation (Texels in particular are extremely large allocations that can seriously disrupt memory usage patterns) and can result in a smaller memory footprint.

Use of a fixed buffer will be copied along with other attributes if the image is copied, but it will not be serialised.

If a fixed buffer has been specified, IwGx will flag certain temporary images to allocate in this way.

Lifetime of a texture (in release build, i.e. from binaries):

1. Texture is loaded from binary representation.
2. Texture may be converted to appropriate format for the current rasteriser(s) if it is not already in that format.
3. Texture may be uploaded.
4. Source data (Any IwImage created in step 1,2) is usually freed.

Images created in steps 1,2 will be created in the fixed buffer if one has been specified.

If other textures share this texture's texels steps 2,3,4 will be delayed until all other textures in its group have been uploaded. Your fixed buffer will need to be large enough to accomodate all shared textures' texels.

In gl step 4 will not be performed for textures that share texels (The texels will be freed when the texture is deleted). These textures will not be marked for fixed buffer use in step 1.

If the texture has been marked with KEEP_DATA_AFTER_UPLOAD_F step 4 will not be performed. These textures will not be marked for fixed buffer use in step 1.

There will be an advantage to using a fixed buffer if:

1. You use texel sharing extensively.
2. You use a wide variety of texture sizes within a group.
3. You use many textures across different memory buckets - Without a fixed buffer you will need an extra 'overhead' in each bucket textures are loaded into (simply for loading the textures), whereas you only need one fixed buffer which will let all buckets share this overhead.

There is rarely a disadvantage to using the fixed buffer, but it does represent a chunk of memory that is not available for use elsewhere without explicit management - for example, with IwGx it can usually be collapsed outside loading. You may need quite large buffer if you use many texel shared textures within a group. HW Rasterisation builds are likely to require a good deal more space (since textures are converted before upload more frequently).

See also:
IwMemBucket, IwTexture

Function Documentation

static bool CIwImage::FixedBufferAvailable ( ) [inline, static, inherited]

Query the status of the fixed buffer.

Returns:
true if a fixed buffer is available.
Required Header Files
IwImage.h

static void CIwImage::FixedBufferCheckOverflow ( ) [static, inherited]

Checks to see that the fixed data buffer has not been overflowed.

Required Header Files
IwImage.h

static void CIwImage::FixedBufferFree ( ) [static, inherited]

Frees the fixed data buffer.

Required Header Files
IwImage.h

static void CIwImage::FixedBufferSetSize ( uint32 size ) [static, inherited]

Allocate a fixed data buffer of the specified size.

Parameters:
size The size of the fixed data buffer.
See also:
FixedBufferFree, UseFixedBuffer
Required Header Files
IwImage.h


Airplay API Reference: IwKeymap

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwKeymap >

IwKeymap
[IwUtil API Reference]

Functions

s3eBool | IwKeymapCanBind (s3eKey key)
int32 | IwKeymapGetKey (s3eKey sysKey)
int32 | IwKeymapGetState (uint32 gameKey)
s3eKey | IwKeymapGetSystemKey (uint32 gameKey)
void | IwKeymapMapKey (uint32 gameKey, s3eKey sysKey)

Detailed Description

IwKeymap.h

See the Key Mapping module overview for more information.

Function Documentation

s3eBool IwKeymapCanBind ( s3eKey key )

Determine whether it is legal to bind an s3eKey to an application action. IwKeymapCanBind is aware of vendor restrictions and device specific issues.

Parameters:
key s3eKey to bind.

int32 IwKeymapGetKey ( s3eKey sysKey )

Gets the (first) application key ID mapped to a specified system key.

Parameters:
sysKey System key ID (e.g., s3eKey1).
Returns:
Application key ID mapped to the specified system key, or -1 if not found.
Required Header Files
IwKeymap.h

int32 IwKeymapGetState ( uint32 gameKey )

Gets the state of the system key which the specified application key is mapped to.

Parameters:
gameKey Application key ID (0..31).
Returns:
State of the system key.
Note:
Use this in the same way you would use s3eKeyboardGetState(). In this case, you are specifying an indirect application key rather than an absolute system key.
Required Header Files
IwKeymap.h

s3eKey IwKeymapGetSystemKey ( uint32 gameKey )

Gets the system key that the specified application key is mapped to.

Parameters:
gameKey Application key ID (0..31).
Returns:
System key which the specified application key is mapped to.
Required Header Files
IwKeymap.h

void IwKeymapMapKey | ( | uint32 | gameKey,
 |  | s3eKey | sysKey
 | ) |  |

Maps an application key ID to a system key.

Parameters:
gameKey | Application key ID (0..31).
sysKey | System key ID (e.g. s3eKey1).
Required Header Files
IwKeymap.h


Airplay API Reference: IwManaged

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwManaged >

IwManaged
[IwUtil API Reference]

See the Managed Objects module overview for more information.


Airplay API Reference: IwManagedList

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwManagedList >

IwManagedList
[IwUtil API Reference]

Data Structures

class | CIwManagedList
class | CIwMenuItemManagedList
Debug menu: all items in a managed list. More...

Defines

#define | IW_MANAGED_LIST_ITERATE(a, b)

Typedefs

typedef void(* | IwManagedListSerialiseCallback )(CIwManaged *)

Detailed Description

The IwManagedList functionality is part of the IwUtil API. Interface for a list of managed objects.

Define Documentation

#define IW_MANAGED_LIST_ITERATE | ( | a,
 |  | b | )

Value:

CIwManaged::ArrayIt b; \
        for (b = (a).GetBegin(); (b) < (a).GetEnd(); ++(b))
Conveniennce macro to help with iteration over items in a managed list.
Required Header Files
IwManagedList.h

Typedef Documentation

typedef void(* IwManagedListSerialiseCallback)(CIwManaged *)

Typedef for serialisation callbacks

Required Header Files
IwManagedList.h

Function Documentation

void IwResolveManagedHash | ( | void * | pptr,
 |  | const CIwManagedList & | list
 | ) |  |

Resolve hash from managed list.


Airplay API Reference: IwMemory

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwMemory >

IwMemory
[IwUtil API Reference]

IwMemory Debugging

Note:
These functions only work on x86 debug builds.

enum | IwMemBucketDebugFlag
uint32 | IwMemBucketCheckpoint ()
uint32 | IwMemBucketDebugCheck (uint32 bucketID, uint32 checkpoint, const char *filename)
void | IwMemBucketDebugClearFlags (uint32 bucketID, uint32 flags)
uint32 | IwMemBucketDebugGetID (void *item)
void | IwMemBucketDebugSetBreakpoint (uint32 allocationID)
void | IwMemBucketDebugSetFlags (uint32 bucketID, uint32 flags)
void | IwMemBucketVisualDump (const char *filename, int32 bucketID=-1)

IwMemory Querying

uint32 | IwMemBucketGetFree (uint32 bucketID)
uint32 | IwMemBucketGetLargestFreeBlock (uint32 bucketID)
uint32 | IwMemBucketGetUsed (uint32 bucketID)

Enumerations

enum | IwMemBucketAllocFailBehaviour
enum | IwMemBucketID

Functions

void | IwMemBucketCreate (uint32 bucketID, const char *name, uint32 size)
void | IwMemBucketFree (uint32 bucketID)
CIwMemBucket * | IwMemBucketGet ()
IwMemBucketAllocFailBehaviour IwMemBucketGetAllocFailBehaviour ()
int32 | IwMemBucketGetFreeID (uint32 afterID=0)
uint32 | IwMemBucketGetID ()
void | IwMemBucketPop ()
void | IwMemBucketPush (uint32 bucketID)
void | IwMemBucketRegister (uint32 bucketID, const char *name, CIwMemBucket *bucket, void *data=NULL)
void | IwMemBucketSet (uint32 bucketID)
void | IwMemBucketSetAllocFailBehaviour (IwMemBucketAllocFailBehaviour behaviour)

Detailed Description

See the Memory Management module overview for more information.

Enumeration Type Documentation

enum IwMemBucketAllocFailBehaviour

Behaviour when an allocation fails - Error is default.

Required Header Files
IwMemory.h
Enumerator:
IW_MEM_BUCKET_ALLOC_FAIL_ERROR | An IwError is raised when an allocation fails. In debug builds a memory dump is generated.
IW_MEM_BUCKET_ALLOC_FAIL_ASSERT | An IwAssert is fired when an allocation fails. In debug builds a memory dump is generated.
IW_MEM_BUCKET_ALLOC_FAIL_SILENT | Allocations fail silently, no memory dump is generated.

enum IwMemBucketDebugFlag

Debug flags, used for IwMemBucketDebugSetFlag and IwMemBucketDebugClearFlag.

Required Header Files
IwMemory.h
Enumerator:
IW_MEM_BUCKET_LOCK_FREE | Assert when something is freed from this bucket (including reallocations).
IW_MEM_BUCKET_LOCK_ALLOC | Assert when something is allocated from this bucket (including reallocations).
IW_MEM_BUCKET_LOCK_SELECT | Assert when this bucket becomes the active bucket.
IW_MEM_BUCKET_TRACE | Trace details of all allocations/deallocations from this bucket.
IW_MEM_BUCKET_LOCK_REALLOC | Assert when something is reallocated from this bucket.
IW_MEM_BUCKET_REUSE_IDS_FOR_REALLOC | Maintain allocation IDs across reallocations, rather than treating them as a new allocation with a new ID.

enum IwMemBucketID

Fixed memory bucket names.

Required Header Files
IwMemory.h
Enumerator:
IW_MEM_BUCKET_ID_SYSTEM | Always indicates a bucket which allocates from the current s3e heap.
IW_MEM_BUCKET_ID_SYSTEM_DEBUG | Always indicates a bucket which allocates from the debug heap. NB. This bucket is not available in release builds.
IW_MEM_BUCKET_ID_USER | First ID free for user buckets.

Function Documentation

uint32 IwMemBucketCheckpoint ( )

Returns an integer representing the next allocation.

Returns:
uint32 ID of next allocation.
Required Header Files
IwMemory.h

void IwMemBucketCreate | ( | uint32 | bucketID,
 |  | const char * | name,
 |  | uint32 | size
 | ) |  |

Creates bucket of given ID, name and size.

Parameters:
bucketID | User ID of bucket.
name | String name of bucket.
size | Size of bucket in bytes.
Note:
The size of the bucket includes the size of the bucket object (~920 bytes). Allocations will be padded to 8-byte alignment (including a 4-byte overhead). If the padded size is less than 16 bytes, 16 bytes will still be consumed.
Required Header Files
IwMemory.h

uint32 IwMemBucketDebugCheck | ( | uint32 | bucketID,
 |  | uint32 | checkpoint,
 |  | const char * | filename
 | ) |  |

Checks a bucket for any allocations left in it since the specified point.

Parameters:
bucketID | Bucket to use.
checkpoint | ID of first allocation to check. Pass 0 to check the bucket is completely empty.
filename | Name of a file to dump allocations since checkpoint into. If NULL, they are written to trace.
Returns:
uint32 0 if no allocations since checkpoint remain in this bucket. Otherwise, the allocation ID of the first allocation left.
Required Header Files
IwMemory.h

void IwMemBucketDebugClearFlags | ( | uint32 | bucketID,
 |  | uint32 | flags
 | ) |  |

Clears debug flags for a specified bucket.

Parameters:
bucketID | Bucket to use.
flag | Flag to set.
Required Header Files
IwMemory.h

uint32 IwMemBucketDebugGetID ( void * item )

Returns an integer representing the specified allocation. Returns 0 if the specified address isn't recognised as a known allocation.

Returns:
uint32 ID of specified allocation.
Required Header Files
IwMemory.h

void IwMemBucketDebugSetBreakpoint ( uint32 allocationID )

Sets a breakpoint such that an assertion fires when the specified allocation ID is allocated or freed.

Note:
Only one breakpoint may be set at any time.
Parameters:
allocationID ID of allocation to break on. Passing 0 clears the current breakpoint.
Returns:
uint32 ID of marker set.
Required Header Files
IwMemory.h

void IwMemBucketDebugSetFlags | ( | uint32 | bucketID,
 |  | uint32 | flags
 | ) |  |

Sets debug flags for a specified bucket.

Parameters:
bucketID | Bucket to use.
flag | Flag to set.
Required Header Files
IwMemory.h

void IwMemBucketFree ( uint32 bucketID )

Frees a bucket's memory.

Parameters:
bucketID Bucket to free.
Required Header Files
IwMemory.h

CIwMemBucket* IwMemBucketGet ( )

Get the current bucket

Returns:
Pointer to the current bucket
Required Header Files
IwMemory.h

IwMemBucketAllocFailBehaviour IwMemBucketGetAllocFailBehaviour ( )

Get the current behaviour when a bucket allocation fails.

See also:
IwMemBucketSetAllocFailBehaviour
Returns:
The current behaviour.
Required Header Files
IwMemory.h

uint32 IwMemBucketGetFree ( uint32 bucketID )

Gets a bucket's free memory.

Parameters:
bucketID Bucket to query.
Returns:
Number of free bytes.
Required Header Files
IwMemory.h

int32 IwMemBucketGetFreeID ( uint32 afterID = 0 )

Get an ID for a free bucket

Parameters:
afterID Free slots under this id will be ignored. It is important that buckets inside other buckets have an ID greater than their parent.
Returns:
The next available free bucket ID after (inclusive) afterID
Required Header Files
IwMemory.h

uint32 IwMemBucketGetID ( )

Get the current bucket

Returns:
The ID of the current bucket
Required Header Files
IwMemory.h

uint32 IwMemBucketGetLargestFreeBlock ( uint32 bucketID )

Gets a bucket's largest free block.

Parameters:
bucketID Bucket to query.
Returns:
Number of bytes in largest free block.
Required Header Files
IwMemory.h

uint32 IwMemBucketGetUsed ( uint32 bucketID )

Gets a bucket's used memory.

Parameters:
bucketID Bucket to query.
Returns:
Number of used bytes.
Required Header Files
IwMemory.h

void IwMemBucketPop ( )

Pops the bucket to use.

Required Header Files
IwMemory.h

void IwMemBucketPush ( uint32 bucketID )

Pushes the bucket to use.

Parameters:
bucketID Bucket to use.
Required Header Files
IwMemory.h

void IwMemBucketRegister | ( | uint32 | bucketID,
 |  | const char * | name,
 |  | CIwMemBucket * | bucket,
 |  | void * | data = NULL
 | ) |  |

Registers a user-created bucket with the IwMemory system.

Parameters:
bucketID | User ID of bucket.
name | String name of bucket.
bucket | pointer to user-created CIwMemBucket derived object. This should have been allocated from the currently active bucket. It will be deleted when IwMemBucketFree is called on this bucket.
data | pointer to user-created data. This will be deleted when IwMemBucketFree is called, and is provided only for convenience. Leave it as NULL if the bucket passed in is responsible for deleting its data.
Note:
The size of the bucket includes the size of the bucket object (~920 bytes). Allocations will be padded to 8-byte alignment (including a 4-byte overhead). If the padded size is less than 16 bytes, 16 bytes will still be consumed.
Required Header Files
IwMemory.h

void IwMemBucketSet ( uint32 bucketID )

Sets the bucket to use.

Parameters:
bucketID Bucket to use.
Required Header Files
IwMemory.h

void IwMemBucketSetAllocFailBehaviour ( IwMemBucketAllocFailBehaviour behaviour )

Set the behaviour when a bucket allocation fails. There are three types of behaviour:

IW_MEM_BUCKET_ALLOC_FAIL_ERROR - A runtime error will be generated, and (in debug builds) a memory dump output. This behaviour is provided for the usual case: where out of memory is catastrophic, the ultimate result of the failure will be a crash. NB. The runtime error will also fire in release builds.

IW_MEM_BUCKET_ALLOC_FAIL_ASSERT - An assert will fire and (in debug builds) a memory dump output. This behaviour is provided so failure can be visible in debug builds but silent in release builds.

IW_MEM_BUCKET_ALLOC_FAIL_SILENT - No warning will occur and no memory dump will be generated. This behaviour is provided for when you expect allocations to fail and are prepared to deal with the consequences.

The default is IW_MEM_BUCKET_ALLOC_FAIL_ERROR.

See also:
IwMemBucketGetAllocFailBehaviour
Parameters:
behaviour The desired behaviour.
Required Header Files
IwMemory.h

void IwMemBucketVisualDump | ( | const char * | filename,
 |  | int32 | bucketID = -1
 | ) |  |

Dumps a html file containing a detailed picture of the current memory state of a bucket (or all buckets).

Parameters:
filename | File to output to.
bucketID | Bucket to dump (-1) for all.


Airplay API Reference: IwMenu

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwMenu >

IwMenu
[IwUtil API Reference]

Data Structures

class | CIwMenu
class | CIwMenuItem
class | CIwMenuItemDisplayBool
class | CIwMenuItemDisplayFloat
class | CIwMenuItemDisplayInt16
class | CIwMenuItemDisplayInt32
class | CIwMenuItemDisplayInt8
class | CIwMenuItemDisplayUInt16
class | CIwMenuItemDisplayUInt32
class | CIwMenuItemDisplayUInt8
class | CIwMenuItemDisplayValue
class | CIwMenuItemEditBool
class | CIwMenuItemEditEnum
class | CIwMenuItemEditFlags
class | CIwMenuItemEditFloat
class | CIwMenuItemEditInt16
class | CIwMenuItemEditInt32
class | CIwMenuItemEditInt8
class | CIwMenuItemEditUInt16
class | CIwMenuItemEditUInt32
class | CIwMenuItemEditUInt8
class | CIwMenuItemEditValue
class | CIwMenuItemString
class | CIwMenuItemTitle
class | CIwMenuManager

Typedefs

typedef CIwStringS | CIwMenuString

Functions

CIwMenuManager * IwGetMenuManager ()

Detailed Description

See the Debug Menus module overview for more information.

Typedef Documentation

typedef CIwStringS CIwMenuString

String type to use for CIwMenuItem text strings.

Function Documentation

CIwMenuManager* IwGetMenuManager ( ) [inline]

Get the IwMenuManager singleton.

Returns:
Pointer to the IwMenuManager singleton.


Airplay API Reference: IwCallstack

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwCallstack >

IwCallstack
[IwUtil API Reference]

Data Structures

class | CIwProfileIterator
class | CIwProfileManager
class | CIwProfileNode
class | CIwProfileSample

Defines

#define | IW_CALLSTACK(name)
#define | IW_CALLSTACK_ENTER(a)
#define | IW_CALLSTACK_LEAVE()
#define | IW_PROFILE(name)
#define | IW_PROFILE_START(name)
#define | IW_PROFILE_STOP()

Detailed Description

See the Callstack module overview for more information.

Define Documentation

#define IW_CALLSTACK ( name )

Use this macro at the top of a function to keep a track of the function callstack at runtime. Assertion dialogs will display the current function callstack, so make use of this function to ensure you have verbose debugging information.

Note:
For example:
 Example: void Foo()
 {
    IW_CALLSTACK("Foo")
    ...
 }
Required Header Files
IwRuntime.h

#define IW_CALLSTACK_ENTER ( a )

Use this macro to simulate entering a new function scope, for callstack debugging purposes.

Note:
For example:
 void Foo()
 {
    IW_CALLSTACK("Foo")
    ...
    IW_CALLSTACK_ENTER("SubSection1")
    ...
    IW_CALLSTACK_LEAVE()
    ...
 }
Required Header Files
IwRuntime.h
Required Header Files
IwRuntime.h

#define IW_CALLSTACK_LEAVE ( )

Use this macro to simulate entering a new function scope, for callstack debugging purposes.

Note:
For example:
 void Foo()
 {
    IW_CALLSTACK("Foo")
    ...
    IW_CALLSTACK_ENTER("SubSection1")
    ...
    IW_CALLSTACK_LEAVE()
    ...
 }
Required Header Files
IwRuntime.h
Required Header Files
IwRuntime.h

#define IW_PROFILE ( name )

Use this at the top of a scope to start a profile block - end of scope will stop it.

Example: void Foo()
{
    IW_PROFILE("Foo")
    ...
}

#define IW_PROFILE_INIT ( )

Use this before any other profiling defines.

#define IW_PROFILE_START ( name )

Use this with IW_PROFILE_STOP to explicitly specify a profile block.

Example: void Foo()
{
    IW_PROFILE_START("Foo")
    ...
    IW_PROFILE_STOP()
}

#define IW_PROFILE_STOP ( )

Use this with IW_PROFILE_START to explicitly specify a profile block.

Example: void Foo()
{
    IW_PROFILE_START("Foo")
    ...
    IW_PROFILE_STOP()
}

#define IW_PROFILE_TERM ( )

Use this after all other profiling defines.


Airplay API Reference: IwSerialise

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwSerialise >

IwSerialise
[IwUtil API Reference]

Data Structures

struct | IwSerialiseContext

Typedefs

typedef void(* | IwSerialiseUserCallback )()

Enumerations

enum | IwSerialiseMode

Functions

INLINE void | _SerialiseScalarType (IwSerialiseContext &c, void *var, uint32 itemSize, uint32 numItems)
INLINE bool | IwIsSerialiseOpen ()
void | IwSerialiseBool (bool &var, uint32 n=1, uint32 numBits=1, uint32 stride=sizeof(bool))
void | IwSerialiseBool8Bits (bool &var, uint32 n=1)
void | IwSerialiseChar (char &var, uint32 n=1, uint32 numBits=sizeof(int8)*8-1, uint32 stride=sizeof(char))
INLINE void | IwSerialiseCharBitDepthRequired (char &var, uint32 n=1, uint32 stride=sizeof(char))
void | IwSerialiseClose ()
void | IwSerialiseDouble (double &var, uint32 n=1, uint32 numBits=sizeof(double)*8, uint32 stride=sizeof(double))
void | IwSerialiseEnum (void *pVar)
bool | IwSerialiseEOF ()
bool | IwSerialiseExists (const char *filename, bool ram=false)
INLINE void | IwSerialiseFile (CIwTextParserITX *pParser, char const *filename, void *pptr, bool read)
void | IwSerialiseFile (CIwTextParserITX *pParser, char const *filename, void *pptr, IwSerialiseMode mode)
void | IwSerialiseFloat (float &var, uint32 n=1, uint32 numBits=sizeof(float)*8, uint32 stride=sizeof(float))
INLINE uint16 | IwSerialiseGetUserVersion ()
void | IwSerialiseInt16 (int16 &var, uint32 n=1, uint32 numBits=sizeof(int16)*8-1, uint32 stride=sizeof(int16))
INLINE void | IwSerialiseInt16BitDepthRequired (int16 &var, uint32 n=1, uint32 stride=sizeof(int16))
void | IwSerialiseInt32 (int32 &var, uint32 n=1, uint32 numBits=sizeof(int32)*8-1, uint32 stride=sizeof(int32))
INLINE void | IwSerialiseInt32BitDepthRequired (int32 &var, uint32 n=1, uint32 stride=sizeof(int32))
void | IwSerialiseInt8 (int8 &var, uint32 n=1, uint32 numBits=sizeof(int8)*8-1, uint32 stride=sizeof(int8))
INLINE void | IwSerialiseInt8BitDepthRequired (int8 &var, uint32 n=1, uint32 stride=sizeof(int8))
INLINE bool | IwSerialiseIsReading ()
INLINE bool | IwSerialiseIsWriting ()
void | IwSerialiseManagedHash (void *pptr)
void | IwSerialiseManagedObject (CIwManaged *&pObj)
void | IwSerialiseMappedData (const uint16 *pMap, void *_pData, uint32 numStructs, uint32 stride)
INLINE void | IwSerialiseOpen (const char *filename, bool read, bool ram=false)
void | IwSerialiseOpen (const char *filename, IwSerialiseMode mode, bool ram=false)
INLINE void | IwSerialiseOpenFromMemory (void *pBuffer, uint32 size, bool read)
void | IwSerialiseOpenFromMemory (void *pBuffer, uint32 size, IwSerialiseMode mode)
void | IwSerialiseResetCallbackCount ()
void | IwSerialiseSetCallback (IwSerialiseUserCallback cb)
void | IwSerialiseSetCallbackPeriod (uint32 p)
INLINE void | IwSerialiseSetUserVersion (uint16 v)
void | IwSerialiseString (char *text, uint32 maxLen=0)
void | IwSerialiseUInt16 (uint16 &var, uint32 n=1, uint32 numBits=sizeof(uint16)*8, uint32 stride=sizeof(uint16))
INLINE void | IwSerialiseUInt16BitDepthRequired (uint16 &var, uint32 n=1, uint32 stride=sizeof(uint16))
void | IwSerialiseUInt32 (uint32 &var, uint32 n=1, uint32 numBits=sizeof(uint32)*8, uint32 stride=sizeof(uint32))
INLINE void | IwSerialiseUInt32BitDepthRequired (uint32 &var, uint32 n=1, uint32 stride=sizeof(uint32))
void | IwSerialiseUInt8 (uint8 &var, uint32 n=1, uint32 numBits=sizeof(uint8)*8, uint32 stride=sizeof(uint8))
INLINE void | IwSerialiseUInt8BitDepthRequired (uint8 &var, uint32 n=1, uint32 stride=sizeof(uint8))

Detailed Description

See the Serialisation module overview for more information.

Typedef Documentation

typedef void(* IwSerialiseUserCallback)()

Typedef for callback.

Required Header Files
IwSerialise.h

Enumeration Type Documentation

enum IwSerialiseMode

Serialising mode enumeration, used for a few serialising functions

Required Header Files
IwSerialise.h

Function Documentation

INLINE void _SerialiseScalarType | ( | IwSerialiseContext & | c,
 |  | void * | var,
 |  | uint32 | itemSize,
 |  | uint32 | numItems
 | ) |  |

Macro used to serialise scalar type. Don't use directly, instead use the function interface.

Required Header Files
IwSerialise.h

INLINE bool IwIsSerialiseOpen ( )

Check if IwSerialise global is open.

Returns:
True id IwSerialise state is between an Open() and Close() call
Required Header Files
IwSerialise.h

void IwSerialiseBool | ( | bool & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = 1,
 |  | uint32 | stride = sizeof(bool)
 | ) |  |

Serialises a bool, or array of bools, potentially with a byte stride between values. The bit-depth MUST be 1.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

void IwSerialiseBool8Bits | ( | bool & | var,
 |  | uint32 | n = 1
 | ) |  |

Serialises a bool, or array of bools, using 8-bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1)
Note:
This is not cross platform consistent yet.
Required Header Files
IwSerialise.h

void IwSerialiseChar | ( | char & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(int8)*8-1,
 |  | uint32 | stride = sizeof(char)
 | ) |  |

Serialises a char, or array of chars, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseCharBitDepthRequired | ( | char & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(char)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

void IwSerialiseClose ( )

Close the current file.

Required Header Files
IwSerialise.h

void IwSerialiseDouble | ( | double & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(double)*8,
 |  | uint32 | stride = sizeof(double)
 | ) |  |

Serialises a double, or array of doubles, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

void IwSerialiseEnum ( void * pVar )

Serialises a enum for sdevice dependence of enum size.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1)
Note:
This is not cross platform consistent yet.
Required Header Files
IwSerialise.h

bool IwSerialiseEOF ( )

Has the end of the current file been reached?

Required Header Files
IwSerialise.h

bool IwSerialiseExists | ( | const char * | filename,
 |  | bool | ram = false
 | ) |  |

Does this file exist?

Required Header Files
IwSerialise.h

INLINE void IwSerialiseFile | ( | CIwTextParserITX * | pParser,
 |  | char const * | filename,
 |  | void * | pptr,
 |  | bool | read
 | ) |  |

Serialise managed ptr into/from a file.

void IwSerialiseFile | ( | CIwTextParserITX * | pParser,
 |  | char const * | filename,
 |  | void * | pptr,
 |  | IwSerialiseMode | mode
 | ) |  |

Serialise managed ptr into/from a file.

Parameters:
pParser | if serialising out, CIwTextParserITX object used for parsing
filename | name of file to serialise
pptr | address of CIwManaged pointer
mode | IW_SERIALISE_READ if opening for read and IW_SERIALISE_WRITE if opening for write
Required Header Files
IwSerialise.h

void IwSerialiseFloat | ( | float & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(float)*8,
 |  | uint32 | stride = sizeof(float)
 | ) |  |

Serialises a float, or array of floats, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE uint16 IwSerialiseGetUserVersion ( )

Get the current serialisation user version.

Returns:
Two-byte user version ID.
See also:
IwSerialiseSetUserVersion
Required Header Files
IwSerialise.h

void IwSerialiseInt16 | ( | int16 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(int16)*8-1,
 |  | uint32 | stride = sizeof(int16)
 | ) |  |

Serialises a int16, or array of int16s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseInt16BitDepthRequired | ( | int16 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(int16)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

void IwSerialiseInt32 | ( | int32 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(int32)*8-1,
 |  | uint32 | stride = sizeof(int32)
 | ) |  |

Serialises a int32, or array of int32s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseInt32BitDepthRequired | ( | int32 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(int32)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

void IwSerialiseInt8 | ( | int8 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(int8)*8-1,
 |  | uint32 | stride = sizeof(int8)
 | ) |  |

Serialises a int8, or array of int8s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseInt8BitDepthRequired | ( | int8 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(int8)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

INLINE bool IwSerialiseIsReading ( )

Is the current serialisation mode reading?

Returns:
True only if the current serialisation mode is IW_SERIALISE_READ.
See also:
IwSerialiseIsWriting
Required Header Files
IwSerialise.h

INLINE bool IwSerialiseIsWriting ( )

Is the current serialisation mode writing?

Returns:
True only if the current serialisation mode is IW_SERIALISE_WRITE.
See also:
IwSerialiseIsReading
Required Header Files
IwSerialise.h

void IwSerialiseManagedHash ( void * pptr )

Serialises the uint32 hash from a CIwManaged instance using a ** ptr. Note that CIwManaged instances are typically stored using a CIwArray of pointers, therefore this functions takes an iterator to such a list directly. Otherwise you should pass the address of a CIwManaged pointer.

Parameters:
pptr double indirect pointer to CIwManaged instance
See also:
CIwManaged
Required Header Files
IwSerialise.h

void IwSerialiseManagedObject ( CIwManaged *& pObj )

Serialises a CIwManaged object, by serialising the classname hash followed by the object itself.

Required Header Files
IwSerialise.h

void IwSerialiseMappedData | ( | const uint16 * | pMap,
 |  | void * | _pData,
 |  | uint32 | numStructs,
 |  | uint32 | stride
 | ) |  |

Serialises an array of structures.

Parameters:
pMap | pointer to the descriptor array, describing a structure.
_pData | pointer to the array of structures.
numStructs | the number of structures in the array.
stride | the byte stride between successive structures. The descriptor array must be constituted by one or more of the following types:
  • IW_TYPE_CHAR
  • IW_TYPE_BOOL
  • IW_TYPE_INT8
  • IW_TYPE_UINT8
  • IW_TYPE_INT16
  • IW_TYPE_UINT16
  • IW_TYPE_INT32
  • IW_TYPE_UINT32
  • IW_TYPE_FLOAT
  • IW_TYPE_DOUBLE
  • IW_TYPE_STRING
  • IW_TYPE_PAD(X), where X is a basic type (above); this results in a padding equal to the size of X
  • IW_TYPE_ARRAY(X, n), where X is a basic type (above), n the count; this results in an array of n X's

For e.g.

 uint16 pMap[] =
 {
    IW_TYPE_UINT16,
    IW_TYPE_UINT32,
    IW_TYPE_FLOAT,
    IW_TYPE_ARRAY(IW_TYPE_CHAR, 8),
    IW_TYPE_NONE,
 };
could be used as the structure description for the following struct (which _pData would point to):
 struct Arb
 {
    int16   m_Int16;
    uint32  m_UInt32;
    float   m_Float;
    char    m_Chars[8];
 };
Required Header Files
IwSerialise.h

INLINE void IwSerialiseOpen | ( | const char * | filename,
 |  | bool | read,
 |  | bool | ram = false
 | ) |  |

Open binary file for reading or writing.

Parameters:
filename | a pointer to the filename as a string
read | true if opening for read and false if opening for write

void IwSerialiseOpen | ( | const char * | filename,
 |  | IwSerialiseMode | mode,
 |  | bool | ram = false
 | ) |  |

Open binary file for reading or writing.

Parameters:
filename | a pointer to the filename as a string
mode | IW_SERIALISE_READ if opening for read and IW_SERIALISE_WRITE if opening for write
Required Header Files
IwSerialise.h

INLINE void IwSerialiseOpenFromMemory | ( | void * | pBuffer,
 |  | uint32 | size,
 |  | bool | read
 | ) |  |

Open memory block for reading or writing.

void IwSerialiseOpenFromMemory | ( | void * | pBuffer,
 |  | uint32 | size,
 |  | IwSerialiseMode | mode
 | ) |  |

Open memory block for reading or writing.

Parameters:
pBuffer | memory address
size | number of bytes to serialise
mode | IW_SERIALISE_READ if opening for read and IW_SERIALISE_WRITE if opening for write
Required Header Files
IwSerialise.h

void IwSerialiseResetCallbackCount ( )

Reset the "bytes read" counter, which can be used to periodically trigger a user callback

Required Header Files
IwSerialise.h

void IwSerialiseSetCallback ( IwSerialiseUserCallback cb )

Set the user callback.

Required Header Files
IwSerialise.h

void IwSerialiseSetCallbackPeriod ( uint32 p )

Set the "callback period", i.e. the number of bytes read after which the user callback will be triggered.

Required Header Files
IwSerialise.h

INLINE void IwSerialiseSetUserVersion ( uint16 v )

Set the current serialisation user version. This a two-byte ID which can be written/read by the user. Airplay Studio includes this ID within its binary files, so user serialisation code can check the user version ID from the current Airplay Studio binary files. This is useful for making evolving serialisation code backwards-compatible.

Parameters:
v Two-byte user version ID.
See also:
IwSerialiseGetUserVersion
Required Header Files
IwSerialise.h

void IwSerialiseString | ( | char * | text,
 |  | uint32 | maxLen = 0
 | ) |  |

Serialise a string as a null-terminated array of chars. If a maximum length is provided, we assert on reading and writing that the string length (together with the terminator) does not equal or exceed the maximum length.

Parameters:
text | the pointer to the buffer of text
maxLen | the maximum length of the string ((together with the terminator), or 0 to ignore the check
Required Header Files
IwSerialise.h

void IwSerialiseUInt16 | ( | uint16 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(uint16)*8,
 |  | uint32 | stride = sizeof(uint16)
 | ) |  |

Serialises a uint16, or array of uint16s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseUInt16BitDepthRequired | ( | uint16 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(uint16)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

void IwSerialiseUInt32 | ( | uint32 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(uint32)*8,
 |  | uint32 | stride = sizeof(uint32)
 | ) |  |

Serialises a uint32, or array of uint32s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseUInt32BitDepthRequired | ( | uint32 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(uint32)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h

void IwSerialiseUInt8 | ( | uint8 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | numBits = sizeof(uint8)*8,
 |  | uint32 | stride = sizeof(uint8)
 | ) |  |

Serialises a uint8, or array of uint8s, potentially with user-specified bit depth and byte stride between values.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise (default 1).
numBits | the bit-depth to use, per value (defaults to the full bit-depth of the variable type).
stride | the byte stride between values (defaults to the full byte-width of the variable type).
Required Header Files
IwSerialise.h

INLINE void IwSerialiseUInt8BitDepthRequired | ( | uint8 & | var,
 |  | uint32 | n = 1,
 |  | uint32 | stride = sizeof(uint8)
 | ) |  |

Serialises an array at the required bit depth. First the array of value is analysed to calculate the min and max values. The number of bits required to store this range is calculated, and a single value equal to this number of bits is serialised. The array itself is then serialised, using this number of bits per value.

Parameters:
var | a reference to the source or destination scalar.
n | the number of scalars to serialise.
stride | the byte stride between successive values.
Required Header Files
IwSerialise.h


Airplay API Reference: IwTextParserITX

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwTextParserITX >

IwTextParserITX
[IwUtil API Reference]

Data Structures

class CIwTextParserITX

Detailed Description

See the Text Parsing module overview for more information.


Airplay API Reference: IwArray

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwArray >

IwArray
[IwUtil API Reference]

Data Structures

class | CIwArray< X, A, REALLOCATE >
class | CIwArray< bool, CIwAllocator< bool > >
class | ReallocateDefault< X, A >
class | ReallocateStandard< X, A >

Defines

#define | IW_ARRAY_ITERATE(type, vn, a)
#define | IW_ARRAY_ITERATE_INT(vn, a)

Detailed Description

CIwArray is an implementation of STL's std::vector augmented to provide more control over memory use and various utility functionality.

A bit-wise storage, bool-specific override is provided for reduced size in memory.

Note:
For more information on the array functionality, see the Array section of the IwUtil API Documentation.

Define Documentation

#define IW_ARRAY_ITERATE | ( | type,
 |  | vn,
 |  | a | )

Value:

CIwArray<type>::iterator vn;                \
for(vn=(a).begin(); vn!=(a).end(); vn++)
Convenience array iteration macro explicitly declares index outside for-loop scope for consistency with VC6

#define IW_ARRAY_ITERATE_INT | ( | vn,
 |  | a | )

Value:

uint32 vn;                                  \
for(vn=0; vn!=(a).size(); vn++)
Convenience array iteration macro explicitly declares index outside for-loop scope for consistency with VC6


Airplay API Reference: IwAutoFile

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwAutoFile >

IwAutoFile
[IwUtil API Reference]

Data Structures

class CIwAutoFile

Detailed Description

The IwAutoFile module defines the CIwAutoFile class, which enables easy file use. CIwAutoFile wraps an s3eFile. When a CIwAutoFile goes out of scope the related file handle is closed.

Note:
For more information on s3eFile, see the File System section of the S3E API Documentation.

For more information on IwUtil, see the IwUtil API Documentation.


Airplay API Reference: IwDebug

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwDebug >

IwDebug
[IwUtil API Reference]

Useful Debug Macros

#define | IW_TRACE_CHANNEL_DEFAULT 1
#define | IwDebugBreak() do {} while(0)
#define | IwError(args)
#define | IwTrace(chan, arg) ((void)0)

Defines

#define | IW_ASSERT_TEXT_LEN 512
#define | IwAssert(chan, expr) ((void)0)

Typedefs

typedef void(* | IwAssertTextCallback )(char *pBuffer)

Functions

IWCORE_API IwAssertCallback | IwAssertRegisterCallback (IwAssertCallback fn)
IWCORE_API IwAssertTextCallback | IwAssertRegisterTextCallback (IwAssertTextCallback fn)
IWCORE_API s3eBool | IwDebugAssertIsChannelOn (const char *channel)
IWCORE_API void | IwDebugAssertSetMessage (const char *fmt,...) PRINTFLIKE
IWCORE_API void | IwDebugAssertSetSolution (const char *fmt,...) PRINTFLIKE
IWCORE_API s3eErrorShowResult | IwDebugAssertShow (const char *pExpr, const char *pFilename, int32 line, uint8 ignorable)
IWCORE_API void | IwDebugClearConfigCache ()
IWCORE_API IwErrorCallback | IwDebugErrorRegisterCallback (IwErrorCallback fn)
IWCORE_API s3eErrorShowResult | IwDebugErrorShow (const char *Args,...) PRINTFLIKE
IWCORE_API s3eBool | IwDebugTraceChannelSwitch (const char *channel, s3eBool new_state)
void | IwDebugTraceDisable (s3eBool disable)
IWCORE_API s3eBool | IwDebugTraceIsChannelOn (const char *channel, s3eBool default_on)
IWCORE_API void | IwDebugTraceLinePrintf (const char *fmt,...) PRINTFLIKE
IWCORE_API void | IwDebugTraceLineVPrintf (const char *fmt, IW_VA_LIST args)

Detailed Description

The IwDebug module allows you to set Trace and Assert messages. The two important functions in this module are IwTrace() and IwAssert().

Note:
Fore more information on the IwDebug functionality, see the Debug section of the IwUtil API Documentation.

Define Documentation

#define IW_ASSERT_TEXT_LEN 512

IwSafeCast uses dynamic type checking in DEBUG version, static casts in RELEASE version. The behaviour is identical, but an assert will fire if a cast converts a non-NULL pointer to a NULL pointer.

#define IW_TRACE_CHANNEL_DEFAULT 1

The DEFAULT trace channel is always on so IwTrace(DEFAULT,...) will always produce output, provided IW_USE_TRACING is defined.

If IW_TRACE_ALL_CHANNELS is on, the trace channel will obey the configuration file setting for the trace channel. If there is no configuration setting, the trace channel will trace.

Otherwise, IW_TRACE_CHANNEL_<channel> must be defined. The value of the define has the following meaning:

  • 0 : The trace channel will never trace.
  • 1 : The trace channel will obey the configuration file setting for the trace channel. If there is no configuration setting, the trace channel will trace.
  • 2 : The trace channel will obey the configuration file setting for the trace channel. If there is no configuration setting, the trace channel will not trace.

#define IwAssert | ( | chan,
 |  | expr | ) | ((void)0)

IwAssert

Otherwise IW_ASSERT_CHANNEL_<channel> must be defined If it is defined to 0, the assert channel will never fire (and all checking code will be excluded) If it is defined to 1, the assert channel will fire unless the assertion channel is disabled in the config file. Public functions

#define IwDebugBreak ( ) do {} while(0)

Private functions

#define IwError ( args )

Value:

do {\
        IwDebugErrorShow args ; \
        IwDebugBreak(); \
    } while(0)
IwError - usage IwError(( format_string, args )) e.g. IwError(("Limit of %d files reached", num_files));
Required Header Files
IwDebug.h

#define IwStaticAssert ( expr ) do {typedef char IW_STATIC_ASSERTION_FAILURE[1-2*(!(expr))];} while(0)

Static assertion.

#define IwTrace | ( | chan,
 |  | arg | ) | ((void)0)

IwDebugTracePrintf relies on IwDebugTraceIsTraceChannelOn setting the current trace channel.

Typedef Documentation

typedef void(* IwAssertTextCallback)(char *pBuffer)

Typedef for user callback. This allows you to append text to the assertion string.

Required Header Files
IwDebug.h

Function Documentation

IWCORE_API IwAssertCallback IwAssertRegisterCallback ( IwAssertCallback fn )

Sets a user handle for all assertions.

Required Header Files
IwDebug.h

IWCORE_API IwAssertTextCallback IwAssertRegisterTextCallback ( IwAssertTextCallback fn )

Sets a callback to allow text to be appended to end of an assertion message.

Required Header Files
IwDebug.h

IWCORE_API s3eBool IwDebugAssertIsChannelOn ( const char * channel )

Returns whether [Assert] <channel>=x is set to on or off in the configuration files. If [Assert] <channel> is not found in the configuration files, the function retruns S3E_TRUE.

Required Header Files
IwDebug.h

IWCORE_API void IwDebugAssertSetMessage | ( | const char * | fmt,
 |  |  | ...
 | ) |  |

Sets the user-defined message for an upcoming assert.

Required Header Files
IwDebug.h

IWCORE_API void IwDebugAssertSetSolution | ( | const char * | fmt,
 |  |  | ...
 | ) |  |

Sets the user-defined solution for inclusion in the next assertion.

Required Header Files
IwDebug.h

IWCORE_API s3eErrorShowResult IwDebugAssertShow | ( | const char * | pExpr,
 |  | const char * | pFilename,
 |  | int32 | line,
 |  | uint8 | ignorable
 | ) |  |

Shows an assertion failure, to be used with the IwAssert macro.

Required Header Files
IwDebug.h

IWCORE_API void IwDebugClearConfigCache ( )

Clears the internal cache of which trace and assertion channels are on. This should be called after modifying the s3eConfig.

Required Header Files
IwDebug.h

IWCORE_API IwErrorCallback IwDebugErrorRegisterCallback ( IwErrorCallback fn )

Sets a user handle for all error messages.

Required Header Files
IwDebug.h

IWCORE_API s3eErrorShowResult IwDebugErrorShow | ( | const char * | Args,
 |  |  | ...
 | ) |  |

Displays an error message.

Required Header Files
IwDebug.h

IWCORE_API s3eBool IwDebugTraceChannelSwitch | ( | const char * | channel,
 |  | s3eBool | new_state
 | ) |  |

Change the state of [Trace] <channel>=x to on or off dynamically in the configuration files. If [Trace] <channel> is not found in the configuration files, the function adds the channel with the state <new_state> and returns the state of the channel new_state.

Required Header Files
IwDebug.h

void IwDebugTraceDisable ( s3eBool disable )

Dynamically disables all [Trace] channels if called with S3E_TRUE. Restore previous behaviour if called with S3E_FALSE.

Required Header Files
IwDebug.h

IWCORE_API s3eBool IwDebugTraceIsChannelOn | ( | const char * | channel,
 |  | s3eBool | default_on
 | ) |  |

Returns whether [Trace] <channel>=x is set to on or off in the configuration files. If [Trace] <channel> is not found in the configuration files, the function returns default_on.

Required Header Files
IwDebug.h

IWCORE_API void IwDebugTraceLinePrintf | ( | const char * | fmt,
 |  |  | ...
 | ) |  |

Writes a line to the trace output.

Required Header Files
IwDebug.h

IWCORE_API void IwDebugTraceLineVPrintf | ( | const char * | fmt,
 |  | IW_VA_LIST | args
 | ) |  |

Writes a line to the trace output.

Required Header Files
IwDebug.h


Airplay API Reference: IwList

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwList >

IwList
[IwUtil API Reference]

Data Structures

class | CIwList< X >
class | CIwListNode

Defines

#define | IW_LIST_ITERATE(a, b)
#define | IwListAddNodeStart IwListAddNode

Functions

void | IwListAddNode (CIwListNode *pRoot, CIwListNode *pNode)
INLINE void | IwListAddNodeEnd (CIwListNode *pRoot, CIwListNode *pNode)
void | IwListRemoveNode (CIwListNode *pRoot, CIwListNode *pNode)

Detailed Description

The IwList Module provides the functionality to create and manipulate a list.

Note:
For more information on IwUtil functionality, see the IwUtil API Documentation.

Define Documentation

#define IW_LIST_ITERATE | ( | a,
 |  | b | )

Value:

CIwListNode* a = b; \
        while((a = a->m_Next) != b)
Iterates over a list. Usually, you derive a class from CIwListNode, then you can iterate and cast the pointer, e.g.:
    IW_LIST_ITERATE(pNode, &m_ListRoot)
    {
        CIwTexture* pTex = (CIwTexture*)pNode;
        ...
    }
Required Header Files
IwList.h

#define IwListAddNodeStart IwListAddNode

Adds a node to the start of a list.

Required Header Files
IwList.h

Function Documentation

void IwListAddNode | ( | CIwListNode * | pRoot,
 |  | CIwListNode * | pNode
 | ) |  |

Adds a node to (the start of) a list.

Required Header Files
IwList.h

INLINE void IwListAddNodeEnd | ( | CIwListNode * | pRoot,
 |  | CIwListNode * | pNode
 | ) |  |

Adds a node to the end of a list.

Required Header Files
IwList.h

void IwListRemoveNode | ( | CIwListNode * | pRoot,
 |  | CIwListNode * | pNode
 | ) |  |

Removes a node from a list.

Required Header Files
IwList.h


Airplay API Reference: IwOptimiseARM

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwOptimiseARM >

IwOptimiseARM
[IwUtil API Reference]

The IwOptimiseARM module uses compiler settings to compile using arm.

Note:
For more information on how to optimise your application, see the whitepaper "Building Lean Applications using the Airplay".


Airplay API Reference: IwOptimiseSize

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwOptimiseSize >

IwOptimiseSize
[IwUtil API Reference]

The IwOptimiseSize module uses compiler settings to optimise for size.

Note:
For more information on how to optimise your application, see the whitepaper "Building Lean Applications using the Airplay".


Airplay API Reference: IwOptimiseSpeed

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwOptimiseSpeed >

IwOptimiseSpeed
[IwUtil API Reference]

The IwOptimiseSpeed module uses compiler settings to optimise for speed.

Note:
For more information on how to optimise your application, see the whitepaper "Building Lean Applications using the Airplay".


Airplay API Reference: IwFileString

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwFileString >

IwFileString
[IwUtil API Reference]

Functions

char * | IwPathGetDirname (const char *filename, char *path)
char * | IwPathGetDrive (const char *filename, char *drive)
S3E_BEGIN_C_DECL char * | IwPathGetExtension (const char *filename, char *pExt)
char * | IwPathGetFilename (const char *filename, char *leaf, uint8 withExt)
s3eBool | IwPathHasDrive (const char *filename)
char * | IwPathJoin (char *path, const char *file, int len=128)
char * | IwPathNorm (char *path)
char * | IwPathStripDrive (char *filename)

Detailed Description

The IwFileString module is a utility API for manipulating paths and filenames.

Note:
For more information on IwUtil functionality, see the IwUtil API Documentation.

Function Documentation

char* IwPathGetDirname | ( | const char * | filename,
 |  | char * | path
 | ) |  |

Retreives the path component from a file or directory name. If the directory component is not present, then path will be set to the empty string. It is possible for path and filename to be the same pointer, in which case filename with by truncated.

Parameters:
filename | The filename.
path | The buffer into which the direcotory name will be written.
Returns:
The pointer passed in as path.
Required Header Files
IwPath.h

char* IwPathGetDrive | ( | const char * | filename,
 |  | char * | drive
 | ) |  |

Retrieves the drive component from pathname. The result will be the drive with "<code>://</code>" appended, e.g., "<code>rom://</code>".

Parameters:
filename | The filename.
drive | The buffer into which the drive will be written.
Returns:
The pointer passed in as drive.

S3E_BEGIN_C_DECL char* IwPathGetExtension | ( | const char * | filename,
 |  | char * | pExt
 | ) |  |

Retreives the extention component of a filename, not including the '.'.

Parameters:
filename | The filename from which to retreive the extention.
ext | The buffer into which the extention will be written. This buffer should be at least as big a filename. If no extension is found ext will be set to the empty string.
Returns:
The pointer passed in as ext.
Required Header Files
IwPath.h

char* IwPathGetFilename | ( | const char * | filename,
 |  | char * | leaf,
 |  | uint8 | withExt
 | ) |  |

Retreives the final component from pathname, optionally including its extension. It is possible for filename and leaf to be the same pointer, in which case filename will be modified.

Parameters:
filename | The filename.
leaf | The buffer into which the leaf filename will be written.
withExt | If non-zero then leaf will also contain the extentions of the filename, if any.
Returns:
The pointer passed in as leaf.
Required Header Files
IwPath.h

s3eBool IwPathHasDrive ( const char * filename )

Returns whether a path contains a drive specification.

Parameters:
fileName The filename
Returns:
true if fileName starts with a drive (of the form "<code>drive://</code>"), false otherwise.

char* IwPathJoin | ( | char * | path,
 |  | const char * | file,
 |  | int | len = 128
 | ) |  |

Joins a filename and a pathname together to from a new pathname.

Parameters:
path | The path to be appended to.
file | The file or pathname to append.
len | The length of the path buffer.
Returns:
The pointer passed in as path.
Required Header Files
IwPath.h

char* IwPathNorm ( char * path )

Normalises a pathname by removing any "<code>.<code>", "</code>..</code>" components, reducing multiple consecutive directory seperators to a single one, and replacing "<code>\</code>" seperators with "<code>/</code>" ones.

Returns:
The pointer passed in as norm.

char* IwPathStripDrive ( char * filename )

Removes the drive specification from a path.

Parameters:
filename The filename from which to remove the drive specifier.
Note:
If filename does not contain a drive specifier, this function does nothing.
Returns:
filename The filename with the drive specifier removed.
Required Header Files
IwPath.h


Airplay API Reference: IwRandom

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwRandom >

IwRandom
[IwUtil API Reference]

Functions

int32 | IwRand ()
INLINE int32 | IwRandMinMax (int min, int max)
INLINE int32 | IwRandRange (int range)
void | IwRandSeed (int32 seed)

Detailed Description

The IwRandom module allows the generation of seeded random numbers.

Note:
Fore more information on the IwRandom functionality, see the Random section of the IwUtil API Documentation.

Function Documentation

int32 IwRand ( )

Returns a random number in the range 0..0x7fff.

Returns:
The random number.
See also:
IwRandSeed, IwRandRange, IwRandMinMax
Required Header Files
IwRandom.h

INLINE int32 IwRandMinMax | ( | int | min,
 |  | int | max
 | ) |  |

Returns a random number in the range min..max.

Parameters:
min | The lower bound on the random number.
max | The upper bound on the random number.
Returns:
The random number in the range min...max.
See also:
IwRand, IwRandRange
Required Header Files
IwRandom.h

INLINE int32 IwRandRange ( int range )

JZ: This stuff has to be included from C files...Sorry Returns a random number in the range 0..range.

Parameters:
range The upper bound on the random number.
Returns:
The random number in the range 0...range
See also:
IwRand, IwRandMinMax
Required Header Files
IwRandom.h

void IwRandSeed ( int32 seed )

Seeds the random number generator.

Parameters:
seed The seed for the generator.
See also:
IwRand
Required Header Files
IwRandom.h


Airplay API Reference: IwTypes

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwTypes >

IwTypes
[IwUtil API Reference]

Detailed Description

The IwTypes module extends the types defined in s3eTypes.h.

Note:
For more information on IwUtil functionality, see the IwUtil API Documentation.

For more information on the s3eTypes, see the S3E Types section of the S3E API Documentation.

Define Documentation

#define IW_TYPE_ARRAY | ( | type,
 |  | num | ) | ((type) | (num) << IW_TYPE_FREE_BIT)

Create uint16 value which represents an array of 'num' values of type 'type'.

#define IW_TYPE_PAD ( type ) ((type) | IW_TYPE_PAD_F)

Create uint16 value which represents a pad of type 'type'.


Airplay API Reference: IwUTF8

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwUTF8 >

IwUTF8
[IwUtil API Reference]

Functions

int | IwUTF8ToWideChar (const char *utf8String, int utf8StringSize, ucs2char *wideBuffer, unsigned int wideBufferSize)
int | IwWideCharToUTF8 (const ucs2char *wideString, int wideStringLength, char *utf8Buffer, unsigned int utf8BufferSize)

Detailed Description

IwUTF8

The IwUTF8 module contains functionality for converting between UTF-8 and UCS-2 text. These are intended as replacements for the Win32 functions WideCharToMultiByte() and MultiByteToWideChar() with CP_UTF8.

You can also refer to these functions as UCS2ToUTF8 and UTF8ToUCS2.

Note:
For more information on IwUtil functionality, see the IwUtil API Documentation.

Function Documentation

int IwUTF8ToWideChar | ( | const char * | utf8String,
 |  | int | utf8StringSize,
 |  | ucs2char * | wideBuffer,
 |  | unsigned int | wideBufferSize
 | ) |  |

Converts a UTF-8 encoded string into a Windows-style 16bit UCS-2 character string. This will write big endian wide characters.

Returns:
If the function fails, -1 is returned. Otherwise, the number of wide characters written into wideBuffer - possibly including a null terminator - is returned.
If utf8StringSize is >= 0, then that is taken to be the size of utf8String in bytes. If utf8StringSize is set to -1, then the size of the string is calculated as being the number of bytes at utf8String up to and including the first null character.

This function will convert null characters it comes across. This means that if the string contains internal null characters, it won't stop there. Also, it will not add a null terminator if one is not included as the last of the utf8StringSize characters. (This makes the function also useful for converting byte sequences into single characters.)

If wideBuffer is NULL, then the return value is the length of the string if it were to be converted.

The contents of wideBuffer may be altered even if the function fails. (e.g., if the buffer turns out not to be big enough.)

This is designed to look like the MultiByteToWideChar function in the Win32 API. However, it's genuinely cross platform.

See also:
WideCharToUTF8

UCS4ToUTF8

Required Header Files
IwUTF8.h

int IwWideCharToUTF8 | ( | const ucs2char * | wideString,
 |  | int | wideStringLength,
 |  | char * | utf8Buffer,
 |  | unsigned int | utf8BufferSize
 | ) |  |

Converts a Windows-style 16bit UCS-2 character string into a UTF-8 encoded string. This assumes that the wide characters are big endian.

Returns:
If the function fails, -1 is returned. Otherwise, the number of bytes written into utf8Buffer - possibly including a null terminator - is returned.
If wideStringLength is >= 0, then that is taken to be the number of characters to convert at wideString. If wideStringLength is set to -1, then the length of the string is calculated as being the length of wideString up to and including the first null character.

This function will convert null characters it comes across. This means that if the string contains internal null characters, it won't stop there, and it will not add a null terminator. (This makes the function also useful for converting single characters into byte sequences.)

If utf8Buffer is NULL, then the return value is the length of the string if it were to be converted.

The contents of utf8Buffer may be altered even if the function fails. (e.g., if the buffer turns out not to be big enough.)

This is designed to look like the WideCharToMultiByte function in the Win32 API, the only difference being that it won't destroy your will to live when you discover that CP_UTF8 only exists on certain versions of Windows.

See also:
UTF8ToWideChar()

UTF8ToUCS4

Required Header Files
IwUTF8.h


Airplay API Reference: IwUtil

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwUtil >

IwUtil
[IwUtil API Reference]

Functions

void | IwUtilInit ()
void | IwUtilTerminate ()

Detailed Description

Initialisation and termination.

Function Documentation

void IwUtilInit ( )

Initialise IwUtil module. Usually called implicitly through initialisation of a higher-level module, for example IwGxInit().

See also:
IwUtilTerminate
Required Header Files
IwUtilInitTerm.h

void IwUtilTerminate ( )

Terminate IwUtil module. Usually called implicitly through termination of a higher-level module, for example IwGxTerminate().

See also:
IwUtilInit
Required Header Files
IwUtilInitTerm.h


Airplay API Reference: IwOptimiseThumb

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwOptimiseThumb >

IwOptimiseThumb
[IwUtil API Reference]

The IwOptimiseThumb module uses compiler settings to compile using thumb if thumb is enabled.

Note:
For more information on how to optimise your application, see the whitepaper "Building Lean Applications using the Airplay".


Airplay API Reference: IwString

Airplay API Reference > IwUtil API Documentation > IwUtil API Reference > IwString >

IwString
[IwUtil API Reference]

Data Structures

class CIwString< N >

Detailed Description

IwString is a templated string class with fixed-length buffer and operator overloads. It allows you to be able to create strings of this type and perform operations on them. Fixed-length string buffer, with reduced functionality of std::string.

In most cases, when you want allocated string storage, you are able to specify a sensible maximum string length: for example, 32 for entity names, 128 for pathnames. CIwString is a replacement for std::string which does no dynamic resizing of the buffer - it merely contains a buffer of fixed size. Methods like size(), c_str() etc. are implemented, as are operator overloads such as +, +=, [] etc.

 Examples:
 typedef CIwString<32>	MyEntityName
 typedef CIwString<128>	MyPathName

Note:
Template argument is max permitted length of string including terminator (so actual permitted length is 1 less).

For more information on IwUtil functionality, see the IwUtil API Documentation.


Airplay API Reference: IwUtil Examples

Airplay API Reference > IwUtil API Documentation > IwUtil Examples >

IwUtil Examples

This document provides a set of examples that illustrate how to use the majority of functionality contained within IwUtil. Each example uses the functionality specific to one IwUtil module, and endeavours to illustrate the capabilities of each of these modules.

The following examples are contained within this section:

  • 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


Airplay API Reference: Class Factory Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Class Factory Example >

Class Factory Example

The following example creates classes from the class factory.

The main functions used to achieve this are:

  • IW_CLASS_FACTORY()

  • IW_CLASS_REGISTER()

  • IwClassFactoryCreate()

The example defines two classes MyClassOne and MyClassTwo using the IW_CLASS_FACTORY() function and then registers them with the class factory using the IW_CLASS_REGISTER() function. The classes are then instantiated using the IwClassFactoryCreate() function. Member functions from both instances are then called displaying the class name and the hash string equivalent.

The following graphics illustrates the example output.

Note:
For more information on class factories, see the Class Factory section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// dummy classes to be put in the class factory

//-----------------------------------------------------------------------------
class MyClassOne
{
private:
    CIwStringS m_Name;  // arbitrary member

public:
    MyClassOne()
        : m_Name("MyClassOne") {}

    // display state
    void Render(int32 x0, int32 y0)
    {
        char output[100];
        sprintf(output, "%s = %lu", m_Name.c_str(), IwHashString(m_Name));
        IwGxPrintString(x0, y0, output);
    }
};
//-----------------------------------------------------------------------------

// define the factory function for MyClassOne
IW_CLASS_FACTORY(MyClassOne);

//-----------------------------------------------------------------------------
class MyClassTwo
{
private:
    CIwStringS m_Name;  // arbitrary member

public:
    MyClassTwo()
        : m_Name("MyClassTwo") {}

    // display state
    void Render(int32 x0, int32 y0)
    {
        char output[100];
        sprintf(output, "%s = %lu", m_Name.c_str(), IwHashString(m_Name));
        IwGxPrintString(x0, y0, output);
    }
};
//-----------------------------------------------------------------------------

// define the factory function for MyClassTwo
IW_CLASS_FACTORY(MyClassTwo);

MyClassOne* myclassone;
MyClassTwo* myclasstwo;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // add classes to the class factory
    IW_CLASS_REGISTER(MyClassOne);
    IW_CLASS_REGISTER(MyClassTwo);

    // create instances of the classes from the class factory
    myclassone = (MyClassOne*)IwClassFactoryCreate("MyClassOne");
    myclasstwo = (MyClassTwo*)IwClassFactoryCreate("MyClassTwo");
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();

    // clean up
    delete myclassone;
    delete myclasstwo;
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    IwGxPrintString(0, 50, "Creating instance through class factories");

    // display object states
    myclassone->Render(0, 80);
    myclasstwo->Render(0, 90);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Hash Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Hash Example >

Hash Example

The following example demonstrates how to use the IwUtil hash functionality. The example outputs two strings and their hash values.

The functions used to achieve this are:

  • IwHashString()

The following graphics illustrates the example output.

Note:
For more information on hashing, see the String Hashing section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    IwGxPrintString(0, 50, "String to Hash Representation");

    // display hashes of (similar) strings
    const char *string1 = "a string";
    const char *string2 = "another string";
    char output[100];
    sprintf(output, "%s - %lu\n%s - %lu", string1, IwHashString(string1), string2, IwHashString(string2));
    IwGxPrintString(0, 100, output);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Image Format Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Image Format Example >

Image Format Example

The following example demonstrates how to use the IwUtil image functionality. The example loads an image from file and displays it using a number of different formats.

The important functions in this example are:

  • CIwImage::SetFormat()

  • CIwImage::ConvertToImage()

You can cycle through the available formats by pressing any button. When any key is pressed the example creates a new Image, Texture and Material and attaches the image in the new format using the SetFormat() function. The ConvertToImage() function is used to set the display image to be the newly created one.

The following graphic illustrates the example output.

Note:
For more information on Image Formatting, see the Image Manipulation section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

#include "IwImage.h"
#include "IwMaterial.h"
#include "IwTexture.h"
#include "s3eKeyboard.h"

//-----------------------------------------------------------------------------
#define NUM_FORMATS 10

// simple format + description pair
struct FormatDesc
{
    CIwImage::Format format;
    const char *desc;
};

#define FORMATDESC(x)   { CIwImage::x, #x }

// available formats
FormatDesc s_Formats[NUM_FORMATS] =
{
    FORMATDESC(RGB_332),
    FORMATDESC(BGR_332),

    FORMATDESC(RGB_565),
    FORMATDESC(BGR_565),

    FORMATDESC(RGB_888),
    FORMATDESC(BGR_888),

    FORMATDESC(PALETTE8_RGB_888),
    FORMATDESC(PALETTE8_RGB_565),

    FORMATDESC(PALETTE4_RGB_888),
    FORMATDESC(PALETTE4_RGB_565)
};

// index into available formats
int         s_FormatIdx = 0;

CIwImage    *s_Image = NULL;
CIwMaterial *s_Material = NULL;
CIwTexture  *s_Texture = NULL;

//-----------------------------------------------------------------------------
void LoadImage()
{
    // clean up
    if (s_Material)
        delete s_Material;

    if (s_Texture)
        delete s_Texture;

    if (s_Image)
        delete s_Image;

    s_Image = new CIwImage;
    s_Texture = new CIwTexture;
    s_Material = new CIwMaterial;

    // load image from file
    s3eFile* pFile = s3eFileOpen("textures/testTexture.bmp", "rb");
    s_Image->ReadFile(pFile);
    s3eFileClose(pFile);

    // to change the format, width, height or pitch of an image
    // call ConvertToImage on the source image;
    // the argument image must have the desired parameter values

    CIwImage* newImage = new CIwImage;

    // set the format of the new image
    newImage->SetFormat(s_Formats[s_FormatIdx].format);

    // NB: the result of the conversion lies in newImage, i.e., s_Image is unaltered.
    s_Image->ConvertToImage(newImage);

    // assign the new image to the texture and upload
    s_Texture->SetImage(newImage);
    s_Texture->Upload();

    // assign the texture to the material
    s_Material->SetColAmbient(IwGxGetColFixed(IW_GX_COLOUR_WHITE));
    s_Material->SetTexture(s_Texture);

    delete newImage;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // no lighting
    IwGxLightingOff();

    LoadImage();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_Image;
    delete s_Texture;
    delete s_Material;

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // convert between image formats when a key is pressed
    if (s3eKeyboardAnyKey())
    {
        s_FormatIdx = (s_FormatIdx + 1) % NUM_FORMATS;
        LoadImage();
    }

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // display the image

    // set the material
    IwGxSetMaterial(s_Material);

    // draw a screen space rectangle (using the material)
    CIwSVec2 XY = CIwSVec2(0, 0);
    CIwSVec2 WH = CIwSVec2((int16)IwGxGetDeviceWidth(), (int16)IwGxGetDeviceHeight());
    IwGxDrawRectScreenSpace(&XY, &WH);

    // display the format description
    IwGxPrintString(0, 0, s_Formats[s_FormatIdx].desc);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Managed Object Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Managed Object Example >

Managed Object Example

The following example demonstrates how to use IwUtil managed objects. This example creates instances of managed objects and outputs their names using a managed list. The important functions in this example are:

  • IW_MANAGED_DECLARE()

  • IW_MANAGED_IMPLEMENT()

  • IW_MANAGED_LIST_ITERATE()

The example derives two user classes from the CIwManaged class. Both derived classes use the IW_MANAGED_DECLARE(<classname>) macro to declare the essential methods and data. The IW_MANAGED_IMPLEMENT(<classname>) macro is then used to implement the declared functionality.

A list of managed objects is created using IwManagedList objects and objects are added using objects.Add(new CHappy).

The following graphic illustrates the example output.

Note:
For more information on managed objects, see the Managed Objects section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

// for screen rendering
#include "s3e.h"
#include "IwGx.h"
#include "IwGxPrint.h"

// simple pointless class
//-----------------------------------------------------------------------------
class CHappy : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CHappy);
};
//-----------------------------------------------------------------------------

// define the class name function
IW_MANAGED_IMPLEMENT(CHappy);

// simple pointless class
//-----------------------------------------------------------------------------
class CSad : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CSad);
};
//-----------------------------------------------------------------------------

// define the class name function
IW_MANAGED_IMPLEMENT(CSad);

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    if ( s3eKeyboardGetState(s3eKeyOk) & S3E_KEY_STATE_PRESSED )
    {
        return false;
    }

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    char display[1000], output[100];
    display[0] = 0;

    // create a list of objects
    CIwManagedList objects;

    // add to the list
    objects.Add(new CHappy);
    objects.Add(new CSad);

    // display the object names in the list
    IW_MANAGED_LIST_ITERATE(objects, it)
    {
        sprintf(output, "Found object named %s\n", (*it)->GetClassName());
        strcat(display, output);
    }

    //clear up objects
    objects.Delete();

    IwGxPrintString(0, 50, "MANAGED OBJECT EXAMPLE");
    IwGxPrintString(0, 80, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Text Parsing Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Text Parsing Example >

Text Parsing Example

The following example demonstrates the IwUtil text parsing functionality. The example parses the file ExamplesIwUtil_parser.itx, creating a singleton object that contains another object. The important functions in this example are:

  • IW_MANAGED_DECLARE()

  • IW_MANAGED_IMPLEMENT()

  • CIwManaged::ParseAttribute()

  • CIwManaged::ParseClose()

  • IW_CLASS_REGISTER()

  • IwGetTextParserITX()

  • CIwTextParserITX::ParseFile()

The file that is parsed "IwUtil_parser.itx" is made up of the following code:

 CSingleParent
  * {
  *     name    lonely
  *     CChild
  *     {
  *         age         72
  *     firstname   picklesworth
  *     }
  * }

Both example classes are registered with the class factory so they are recognised when parsing. This is done using the IW_CLASS_REGISTER() function. The text parser is then instantiated, using and passed the ITX file for parsing.

The parser will first encounters a class name which is checked by the class factory to see if it is a registered class, the class will be instantiated. The following tokens are passed to the derived ParseAttribute() function, setting each value as it is encountered.The CChild class has two values that are populated by the ITX file m_FirstName and m_Age.

Note:
For more information on Text Parsing, see the Text Parsing section in the IwUtil API Documention.
The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwTextParserITX.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// simple managed class - for this example, objects of this type
// can only exist within an object of type CSingleParent (see below)
//-----------------------------------------------------------------------------
class CChild : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CChild);

    CChild()
        : m_Age(0) {}

    // function invoked by the text parser when parsing attributes for objects of this type
    virtual bool ParseAttribute(CIwTextParserITX *pParser, const char *pAttrName);

    // function invoked by the text parser when the object definition end is encountered
    virtual void ParseClose(CIwTextParserITX *pParser);

    CIwStringS  m_FirstName;
    int32       m_Age;
};
//-----------------------------------------------------------------------------

// define class name function
IW_MANAGED_IMPLEMENT(CChild);

// managed class (singleton) that contains another managed class (CChild)
//-----------------------------------------------------------------------------
class CSingleParent : public CIwManaged
{
private:
    // singleton pointer
    static CSingleParent    *s_Singleton;

public:
    IW_MANAGED_DECLARE(CSingleParent);

    CSingleParent()
        : m_Child(NULL)
    {
        s_Singleton = this;
    }

    ~CSingleParent()
    {
        if (m_Child)
            delete m_Child;

        s_Singleton = NULL;
    }

    // public access to the singleton object
    static CSingleParent *Get()
    {
        return s_Singleton;
    }

    // CIwManaged::ParseAttribute is not overridden here - i.e. the only permitted attribute is 'name'

    // function invoked by the text parser when the object definition end is encountered
    virtual void ParseClose(CIwTextParserITX *pParser);

    CChild  *m_Child;

};
//-----------------------------------------------------------------------------

// define class name function
IW_MANAGED_IMPLEMENT(CSingleParent);

// CChild implementation

// function invoked by the text parser when parsing attributes for objects of this type
//-----------------------------------------------------------------------------
bool CChild::ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
{
    char line[0x100];
    if (!strcmp(pAttrName, "firstname"))
    {
        // read firstname
        pParser->ReadString(line, 0x100);
        m_FirstName = line;
    }
    else if (!strcmp(pAttrName, "age"))
    {
        // read age
        int32 age;
        pParser->ReadInt32(&age);
        m_Age = age;
    }
    else
    // call base function
        return CIwManaged::ParseAttribute(pParser, pAttrName);

    return true;
}
// function invoked by the text parser when the object definition end is encountered
//-----------------------------------------------------------------------------
void CChild::ParseClose(CIwTextParserITX* pParser)
{
    // we know that this object has been parsed in the context of a CSingleParent object
    CSingleParent *parent = (CSingleParent *)IwGetTextParserITX()->GetObject(-1);

    // set the child of parent to this
    parent->m_Child = this;
}

// CSingleParent implementation

// function invoked by the text parser when the object definition end is encountered
//-----------------------------------------------------------------------------
void CSingleParent::ParseClose(CIwTextParserITX* pParser)
{
    // if a CSingleParent block is encountered in the ITX file then set the singleton

    if (s_Singleton && (s_Singleton != this) )
        delete s_Singleton;

    s_Singleton = this;
}
//-----------------------------------------------------------------------------

// define class factory functions
IW_CLASS_FACTORY(CChild);
IW_CLASS_FACTORY(CSingleParent);

// CSingleParent singleton
CSingleParent *CSingleParent::s_Singleton = NULL;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // register the classes with the class factory - this is required for parsing
    IW_CLASS_REGISTER(CChild);
    IW_CLASS_REGISTER(CSingleParent);

    // create the text parser
    new CIwTextParserITX;

    // TIM TEST
    IwGetTextParserITX()->SetAssertOnUnrecognisedTokens(true);

    // parse the file
    IwGetTextParserITX()->ParseFile("IwUtilParser.itx");
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // clear up data
    delete CSingleParent::Get();

    // destroy the text parser
    delete IwGetTextParserITX();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    char display[1000], output[100];
    display[0] = 0;

    // the singleton exists at this point since it has been parsed
    CSingleParent *parent = CSingleParent::Get();

    // display the state of the singleton

#ifndef IW_DEBUG
    sprintf(display, "CSingleParent object name will be an empty string in release builds\n");
#endif

    sprintf(output, "CSingleParent object\nnamed %s:\n", parent->DebugGetName());
    strcat(display, output);

    sprintf(output, "m_Child->m_Age = %ld,\nm_Child->m_FirstName = %s\n", parent->m_Child->m_Age, parent->m_Child->m_FirstName.c_str());
    strcat(display, output);

    // display
    IwGxPrintString(0, 50, "Using the Text Parser");
    IwGxPrintString(0, 80, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Serialising Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Serialising Example >

Serialising Example

The following example demonstrates the IwUtil serialisation functionality. The example serialises a single managed object as well as a list of managed objects.

The important functions in this example are:

  • CIwManaged::IwSerialiseOpen()

  • CIwManaged::IwSerialiseClose()

  • CIwManaged::Serialise()

The managed objects are declared, and a file is open to serialise out to using the IwSerialiseOpen() function. The declared serialisation function is called to serialise back. The IwSerialiseClose()function is then called. The same actions are then carried out on a managed list.

Note:
For more information on Serialisation, see the Serialisation section in the IwUtil API Documention.
The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// simple managed class that contains an int32
//-----------------------------------------------------------------------------
class CHappy : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CHappy);

    CHappy()
        : m_Age(0) {}

    // simple serialisation - just an int32 member
    void Serialise()
    {
        IwSerialiseInt32(m_Age);
    }

    int32       m_Age;
};
//-----------------------------------------------------------------------------

// define class name function
IW_MANAGED_IMPLEMENT(CHappy);

// managed class that contains another managed class
//-----------------------------------------------------------------------------
class CBored : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CBored);

    CBored()
    {
        m_Happy = new CHappy;
    }

    ~CBored()
    {
        if (m_Happy)
            delete m_Happy;
    }

    // more complicated serialisation - need to serialise a member object
    void Serialise()
    {
        uint8 isObject;

        if (IwSerialiseIsWriting())
        // writing
        {
            // record whether m_Happy exists
            isObject = m_Happy ? 1 : 0;
            IwSerialiseUInt8(isObject);

            // serialise out m_Happy if it exists
            if (m_Happy)
                m_Happy->Serialise();
        }
        else
        // reading
        {
            IwSerialiseUInt8(isObject);

            // if an object was written out then read it in
            if (isObject)
            {
                // if m_Happy already exists then delete it
                if (m_Happy)
                    delete m_Happy;

                m_Happy = new CHappy;

                // serialise in m_Happy
                m_Happy->Serialise();
            }
        }
    }

    CHappy  *m_Happy;
};
//-----------------------------------------------------------------------------

// define class name function
IW_MANAGED_IMPLEMENT(CBored);

// define class factory functions
IW_CLASS_FACTORY(CHappy);
IW_CLASS_FACTORY(CBored);

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // register the classes with the class factory - this is required for serialisation of managed lists
    IW_CLASS_REGISTER(CHappy);
    IW_CLASS_REGISTER(CBored);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    char display[1000], output[100];
    display[0] = 0;

    // Serialising (out and then in) of a single managed object

    // create object
    CBored *obj0 = new CBored;
    obj0->m_Happy->m_Age = 99;

    strcat(display, "Before serialising in:\n");

    // display object state
    sprintf(output, "obj0->m_Happy->m_Age = %ld\n", obj0->m_Happy->m_Age);
    strcat(display, output);

    // open file for serialising out
    IwSerialiseOpen("objects.bin", false);

    // serialise the object out
    obj0->Serialise();

    // close the file
    IwSerialiseClose();

    // open file for serialising in
    IwSerialiseOpen("objects.bin", true);

    // serialise the object in
    obj0->Serialise();

    // close the file
    IwSerialiseClose();

    strcat(display, "\nAfter serialising in:\n");

    // display object state
    sprintf(output, "obj0->m_Happy->m_Age = %ld\n", obj0->m_Happy->m_Age);
    strcat(display, output);

    // Serialising (out and then in) of a list of managed objects
    CIwManagedList objects;

    // create stand alone CHappy object
    CHappy *obj1 = new CHappy;
    obj1->m_Age = -14;

    // add both objects to the list
    objects.Add(obj0);
    objects.Add(obj1);

    strcat(display, "\nBefore serialising in:\n");

    // display objects' states

    sprintf(output, "obj0->m_Happy->m_Age = %ld\n", ((CBored *)objects[0])->m_Happy->m_Age);
    strcat(display, output);

    sprintf(output, "obj1->m_Happy->m_Age = %ld\n", ((CHappy *)objects[1])->m_Age);
    strcat(display, output);

    // open file for serialising out
    IwSerialiseOpen("objects.bin", false);

    // when serialising out a managed list, hashes of the objects' class names are written
    objects.Serialise();

    // close the file
    IwSerialiseClose();

    // open file for serialising in
    IwSerialiseOpen("objects.bin", true);

    // when serialising in a managed list, the above-mentioned hashes are used to create objects and serialise them in
    objects.Serialise();

    // close the file
    IwSerialiseClose();

    strcat(display, "\nAfter serialising in:\n");

    // display objects' states

    sprintf(output, "obj0->m_Happy->m_Age = %ld\n", ((CBored *)objects[0])->m_Happy->m_Age);
    strcat(display, output);

    sprintf(output, "obj1->m_Happy->m_Age = %ld\n", ((CHappy *)objects[1])->m_Age);
    strcat(display, output);

    // display
    IwGxPrintString(0, 30, "Using the Serialising API");
    IwGxPrintString(0, 50, display);

    //clear serialised instances
    objects.Delete();

    //clear original instances
    delete obj0;
    delete obj1;

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Key Mapping Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Key Mapping Example >

Key Mapping Example

The following example demonstrates how to use the IwKeymap API. The example allows you to swap between a number of key mappings; illustrating how you can create functionality that can easily adapt to device type.

The important function in this example is:

  • IwKeymapMapKey()

The example declares an enumeration of four keys: Up, Down, Left, Right. By pressing "M" you can move through the key mappings set for each key using the IwKeymapMapKey() function. This mapping allows you to call the IwKeymapGetState(LEFT) function to determine whether that key (depending on the selected mapping) has been pressed.

The following graphics illustrates the example output.

Note:
For more information on Key Mapping, see the Key Mapping section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwKeymap.h"

int32 s_Mapping;

// App keys
enum
{
    LEFT,
    RIGHT,
    UP,
    DOWN,
};

static const char* s_MappingNames[] =
{
    "ARROW KEYS",
    "NUMPAD ARROW KEYS",
    "A, D, W, S",
    "1, 2, 3, 4",
};

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set initial mapping
    s_Mapping = -1;
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Press 'M' to move to the next mapping
    if  (
        (s3eKeyboardGetState(s3eKeyM) & S3E_KEY_STATE_PRESSED) ||
        (s_Mapping < 0)
        )
    {
        s_Mapping = (s_Mapping + 1) & 0x3;
        switch(s_Mapping)
        {
        case 0:
            IwKeymapMapKey(LEFT,    s3eKeyLeft);
            IwKeymapMapKey(RIGHT,   s3eKeyRight);
            IwKeymapMapKey(UP,      s3eKeyUp);
            IwKeymapMapKey(DOWN,    s3eKeyDown);
            break;

        case 1:
            IwKeymapMapKey(LEFT,    s3eKeyNumPad4);
            IwKeymapMapKey(RIGHT,   s3eKeyNumPad6);
            IwKeymapMapKey(UP,      s3eKeyNumPad8);
            IwKeymapMapKey(DOWN,    s3eKeyNumPad2);
            break;
        case 2:
            IwKeymapMapKey(LEFT,    s3eKeyA);
            IwKeymapMapKey(RIGHT,   s3eKeyD);
            IwKeymapMapKey(UP,      s3eKeyW);
            IwKeymapMapKey(DOWN,    s3eKeyS);
            break;

        case 3:
            IwKeymapMapKey(LEFT,    s3eKey1);
            IwKeymapMapKey(RIGHT,   s3eKey2);
            IwKeymapMapKey(UP,      s3eKey3);
            IwKeymapMapKey(DOWN,    s3eKey4);
            break;
        }
    }
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    IwGxClear(IW_GX_COLOUR_BUFFER_F);

    IwGxPrintString(0, 50, "Key Mapping Example");
    IwGxPrintString(0, 80, "'m' key: Change key mapping" );

    // Display the mapping we are currently using
    int16 x = 2;
    int16 y = 110;
    IwGxPrintString(x, y, s_MappingNames[s_Mapping]);

    x += 0x10;
    y += 0x10;
    if (IwKeymapGetState(LEFT) & S3E_KEY_STATE_DOWN)
        IwGxPrintString(x, y, "LEFT");

    y += 8;
    if (IwKeymapGetState(RIGHT) & S3E_KEY_STATE_DOWN)
        IwGxPrintString(x, y, "RIGHT");

    y += 8;
    if (IwKeymapGetState(UP) & S3E_KEY_STATE_DOWN)
        IwGxPrintString(x, y, "UP");

    y += 8;
    if (IwKeymapGetState(DOWN) & S3E_KEY_STATE_DOWN)
        IwGxPrintString(x, y, "DOWN");

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Memory Utility Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Memory Utility Example >

Memory Utility Example

The following example demonstrates how to use the IwUtil memory bucket system. The example allows you to create up to four memory buckets, allocate memory from them and then delete those memory buckets.

The main functions used to achieve this are:

  • IwUtilInit()

  • IwMemBucketCreate()

  • IwMemBucketSet()

  • IwMemBucketFree()

The example initialises the memory bucket functionality, as well as all other IwUtil functionality, using the IwUtilInit() function. Memory buckets are created using the the IwMemBucketCreate() function. It is possible to swap between buckets once they are created using the IwMemBucketSet() function. Finally, you can delete the buckets you have created using the IwMemBucketFree() function.

You can optimise the use of memory buckets using the following functions:

  • IwMemBucketGetUsed()

  • IwMemBucketGetFree()

The following controls are provided for the example:

  • Press left/right to cycle through the available buckets and the main heap.

  • Press Enter to create a new bucket from the heap memory.

  • Press up/down to call new/delete for the selected bucket/heap.

The following graphics illustrates the example output.

Note:
For more information on Memory Utility, see the Memory Management section in the IwUtil API Documention.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwUtil.h"
#include "IwMemory.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "ExamplesMain.h"

// Enumerate buckets
enum
{
    FIXED = IW_MEM_BUCKET_ID_USER,
    GUI,
    LEVEL,
    SOUND,
};

static const uint32 MEM_SIZE_32     = 32;       // 32
static const uint32 MEM_SIZE_128    = 128;      // 128
static const uint32 MEM_SIZE_512    = 512;      // 512
static const uint32 MEM_SIZE_1024   = 1024;     // 1024
static const uint32 MEM_SIZE_32K    = MEM_SIZE_32   * MEM_SIZE_1024; // 32k
static const uint32 MEM_SIZE_128K   = MEM_SIZE_128  * MEM_SIZE_1024; // 128k
static const uint32 MEM_SIZE_1024K  = MEM_SIZE_1024 * MEM_SIZE_1024; // 1024k
static const uint32 MEM_SIZE_512K   = MEM_SIZE_512  * MEM_SIZE_1024; // 512k
static const uint32 NUM_BUCKETS     = 4;
static const uint32 MAX_ALLOCATIONS = 10;

// Which is the active bucket in use
static uint32 s_ActiveBucket        = 0;

struct BucketInfo
{
    uint32      UniqueID;
    uint32      Capacity;
    const char* Name;
};

// Information about the bucket in use
static const BucketInfo s_BUCKET_INFO[NUM_BUCKETS] =
{
    { FIXED,    MEM_SIZE_128K,      "Fixed"},
    { GUI,      MEM_SIZE_1024 * 3,  "Gui" },
    { LEVEL,    MEM_SIZE_128K,      "Level" },
    { SOUND,    MEM_SIZE_32K,       "Sound" }
};

// Arrays containing the allocations made by each bucket.
static CIwArray<char*> s_Allocations[NUM_BUCKETS];

// Buffer containing a description of the last action taken by the user.
static char s_LastAction[256] = "\0";

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("1: Allocate 32 bytes", 5, 100, (w / 2) - 10 , 20, s3eKey1);
    AddButton("2: Allocate 128 bytes", w/2, 100, (w / 2) - 10, 20, s3eKey2);
    AddButton("3: Allocate 512 bytes", 5, 125, (w / 2) - 10, 20, s3eKey3);
    AddButton("4: Allocate 1024 bytes", w/2, 125, (w / 2) - 10, 20, s3eKey4);
    AddButton("5: Free last allocation", 5, 150, w-15, 20, s3eKey5);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise (indirectly) bucket system
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwUtilInit();
    IwGxInit();

    // Create buckets
    for (uint32 currentBucket = 0; currentBucket < NUM_BUCKETS; ++currentBucket)
    {
        IwMemBucketCreate(s_BUCKET_INFO[currentBucket].UniqueID,
                          s_BUCKET_INFO[currentBucket].Name,
                          s_BUCKET_INFO[currentBucket].Capacity);

        // Reserve space for allocations in the array now whilst the system memory bucket is active.
        s_Allocations[currentBucket].reserve( MAX_ALLOCATIONS );
    }

    IwGxSetColClear( 0x00, 0x00, 0x00, 0xff );

    // Turn all lighting off
    IwGxLightingOff();

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Free all user created memory buckets.
    for (uint32 currentBucket = 0; currentBucket < NUM_BUCKETS; ++currentBucket)
    {
        for (uint32 currentAlloc = 0; currentAlloc < s_Allocations[ currentBucket ].size(); ++currentAlloc)
        {
            // delete that last entry in the allocation array
            delete[]  s_Allocations[ currentBucket ][ currentAlloc ];
        }

        // Free the bucket now no allocations remain
        IwMemBucketFree(s_BUCKET_INFO[currentBucket].UniqueID);

        // Release storage for array
        s_Allocations[currentBucket].clear_optimised();
    }

    // Terminate (indirectly) bucket system
    IwGxTerminate();
    IwUtilTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Check if the user has selected a new memory bucket.
    if ( CheckCursorState() == EXCURSOR_LEFT )
    {
        s_ActiveBucket = (s_ActiveBucket == 0) ? ( NUM_BUCKETS - 1 ) : ( s_ActiveBucket - 1 );
    }
    else if ( CheckCursorState() == EXCURSOR_RIGHT )
    {
        s_ActiveBucket = ((s_ActiveBucket + 1) == NUM_BUCKETS) ? ( 0 ) : ( s_ActiveBucket + 1 );
    }

    // Set the active bucket before making any allocations.
    IwMemBucketPush( s_BUCKET_INFO[s_ActiveBucket].UniqueID );

    // Allow extra allocation only if we have not exceeded the maximum allowed for this bucket.
    if ( MAX_ALLOCATIONS > s_Allocations[ s_ActiveBucket ].size() )
    {

        if (CheckButton("1: Allocate 32 bytes") & S3E_KEY_STATE_PRESSED)
        {
            s_Allocations[s_ActiveBucket].push_back(new char[MEM_SIZE_32]);

            sprintf(s_LastAction, "%lu bytes allocated from %s", MEM_SIZE_32, s_BUCKET_INFO[s_ActiveBucket].Name);
        }
        else if (CheckButton("2: Allocate 128 bytes") & S3E_KEY_STATE_PRESSED )
        {
            s_Allocations[ s_ActiveBucket ].push_back( new char[ MEM_SIZE_128 ] );

            sprintf(s_LastAction, "%lu bytes allocated from %s", MEM_SIZE_128, s_BUCKET_INFO[s_ActiveBucket].Name);
        }
        else if (CheckButton("3: Allocate 512 bytes") & S3E_KEY_STATE_PRESSED )
        {
            s_Allocations[ s_ActiveBucket ].push_back( new char[ MEM_SIZE_512 ] );

            sprintf(s_LastAction, "%lu bytes allocated from %s", MEM_SIZE_512, s_BUCKET_INFO[s_ActiveBucket].Name);
        }
        else if ( CheckButton("4: Allocate 1024 bytes") & S3E_KEY_STATE_PRESSED )
        {
            s_Allocations[ s_ActiveBucket ].push_back( new char[ MEM_SIZE_1024 ] );

            sprintf(s_LastAction, "%lu bytes allocated from %s", MEM_SIZE_1024, s_BUCKET_INFO[s_ActiveBucket].Name);
        }

    }
    else
    {
        sprintf(s_LastAction, "Allocation limit reached");
    }

    if ( CheckButton("5: Free last allocation") & S3E_KEY_STATE_PRESSED )
    {

        // Only free an allocation if any allocations remain.
        if ( !s_Allocations[ s_ActiveBucket ].empty() )
        {
            // delete that last entry in the allocation array
            delete[]  ( s_Allocations[ s_ActiveBucket ].back() );

            // and remove the pointer from the back of the array.
            s_Allocations[ s_ActiveBucket ].pop_back();

            // Display the last action taken
            sprintf(s_LastAction, "Allocated free from %s", s_BUCKET_INFO[s_ActiveBucket].Name);
        }

    }

    // Note that we must pop any reference to these buckets from the ID stack first
    IwMemBucketPop();

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    IwGxClear( IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F );

    char textBuffer[256];

    // Even before any allocation occur from a memory bucket there will be a fixed overhead
    // associated with the initialisation of a memory bucket, the size of which will depend
    // upon the type of memory bucket used.  This effect of this is that new memory bucket
    // will not have 100% of its capacity available for use by a user.
    sprintf(textBuffer, "Active Bucket: %s", s_BUCKET_INFO[s_ActiveBucket].Name);
    IwGxPrintString(0, 40, textBuffer);
    sprintf(textBuffer, "Size: %lu", s_BUCKET_INFO[s_ActiveBucket].Capacity);
    IwGxPrintString(0, 48, textBuffer);
    sprintf(textBuffer, "Free Memory: %lu", IwMemBucketGetFree(s_BUCKET_INFO[s_ActiveBucket].UniqueID));
    IwGxPrintString(0, 56, textBuffer);
    sprintf(textBuffer, "Used Memory: %lu", IwMemBucketGetUsed(s_BUCKET_INFO[s_ActiveBucket].UniqueID));
    IwGxPrintString(0, 64, textBuffer);

    // Display the last action taken by the user.
    IwGxPrintString(0, 90, s_LastAction );

    // Control instruction
    IwGxPrintString(0, IwGxGetScreenHeight() - 70, "Left & Right: Select a bucket" );
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Swap buffers
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Array Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Array Example >

Array Example

The following example demonstrates how to use the IwUtil array functionality. The example creates an array, populates it and then performs a number of operations on it.

The main functions used to achieve this are:

  • CIwArray::push_back()

  • CIwArray::front()

  • CIwArray::back()

  • CIwArray::find()

  • CIwArray::erase()

  • CIwArray::size()

The array's contents are added to the output string, then the first element is found using numbers.front() and then decremented. The last element is found using numbers.back() and then incremented. A search is performed using numbers.find(2) and then that element is replaced. The new contents of the array are then displayed.

An array iterator is used to cycle through the array to display each element's value. The IW_ARRAY_ITERATE macro is used, and this is equivalent to, in this case:

 for (CIwArray<int>::iterator it = numbers.begin();
 it != numbers.end(); it++)

The following graphics illustrates the example output.

Note:
For more information on array manipulation functionality, see the Array section of the IwUtil API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    // create an empty array
    CIwArray<int> numbers;

    // populate the array
    numbers.push_back(1);
    numbers.push_back(2);
    numbers.push_back(3);
    numbers.push_back(4);

    char display[1000], output[100];
    display[0] = 0;

    sprintf(output, "Contents (size = %lu):\n", numbers.size());
    strcat(display, output);

    /*
     * navigate the array, displaying contents
     * the IW_ARRAY_ITERATE macro is equivalent to, in this case,
     * for (CIwArray<int>::iterator it = numbers.begin(); it != numbers.end(); it++)
     */

    uint32 count = 0;
    IW_ARRAY_ITERATE(int, it, numbers)
    {
        sprintf(output, "Element %lu = %d\n", count, *it);
        strcat(display, output);
        count++;
    }

    // decrement the first element
    numbers.front()--;

    // increment the last element
    numbers.back()++;

    // find the element equal to 2
    int searchIdx = numbers.find(2);

    // use operator[] to index into the array, and set this element to -1
    if (searchIdx != -1)
        numbers[searchIdx] = -1;

    // erase the second last element
    numbers.erase(numbers.end() - 2);

    sprintf(output, "Contents (size = %lu):\n", numbers.size());
    strcat(display, output);

    IW_ARRAY_ITERATE_INT(i, numbers)
    {
        sprintf(output, "Element %lu = %i\n", i, numbers[i]);
        strcat(display, output);
    }

    IwGxPrintString(10, 56, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Debug Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Debug Example >

Debug Example

The following example creates trace and assert messages.

The important functions in this example are:

  • IwAssertMsg()

  • IwTrace()

On startup this example will trace the message "MYAPP: val is set to 0". Trace output will appear in the dev studio's program output window. All of the Airplay Studio modules will trace information in their own channels. You can disable channels using the app.icf file - try changing the line "MYAPP=1" in the [Trace] section to "MYAPP=0" and notice that the MYAPP message no longer appears. Trace channels default to on.

The application will then assert that val == 0 and val == 2 in turn. Since val has been set to 1 in the ExampleUpdate function, the asserts will fail and pop up warning dialogues in turn:

Select 'abort' to stop at the line where the assert failed. Select 'retry' to continue. The other assert will immediately fire again as the program loops. Select 'ignore' to continue, ignoring further failings of the assert. Now only the other assert will fire. If you ignore the other one as well, then neither assert will fire and the program will spin silently.

Asserts are used to catch unexpected runtime behaviour. They are not compiled into release builds. Airplay Studio modules will also assert when unexpected runtime behaviour occurs. Asserts can be disabled like tracing - using an [Assert] icf section.

Note:
For more information on using the IwUtil functionality to create trace and assert messages, see the Debug section of the IwUtil API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwDebug.h"

// arbitrary int
int val = 0;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // trace to the MYAPP trace channel
    IwTrace(MYAPP, ("val is set to %i", val));
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    val = 1;

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // cause an assertion on the MYAPP assert channel
    IwAssertMsg(MYAPP, val == 0, ("Please don't set val to %i - it's best set to 0", val));
    IwAssertMsg(MYAPP, val == 2, ("Please don't set val to %i - it's best set to 2", val));
}
//-----------------------------------------------------------------------------


Airplay API Reference: Debug Menu Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Debug Menu Example >

Debug Menu Example

The following example demonstrates how to use the IwMenu API to display a menu system which can be used to view and alter custom parameters. This example is designed to work only in debug builds.

The important constructs in this example are:

  • CIwMenu
  • CIwMenuItem
  • CIwMenuManager
  • CIwManaged

This example delares a simple custom class, CHansol, and a matching menu class, CIwMenuItemHansol, which derive from CIwManaged and CIwMenuItem respectively. This allows the menu item object which is created to be part of the debug menu and to have access to the member variables of a CHansol object.

An object, s_Hansol, is instanciated and its members given some starting values. By pressing F6, the debug menu can be displayed. It will show the s_Hansol object. Press the right direction key to expand the object and display its members; left direction key collapses a menu item. Use the +/- keys to alter values which are writable.

The example also gets the member values directly and prints them to screen to demonstrate the effect changing values on the menu has on the actual object.

The following graphic illustrates the example output.

Note:
For more information on using the IwUtil functionality to create debug menus, see the Debug Menus section of the IwUtil API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUtilDMenu
//-----------------------------------------------------------------------------

#include "IwMenu.h"

// For screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// A simple class that we will inspect with the debug menu
//-----------------------------------------------------------------------------
class CHansol : public CIwManaged
{
public:
    IW_MANAGED_DECLARE(CHansol);

    CHansol() : m_Flags(0), m_Size(14), m_Character('b')
    {}

    enum
    {
        ON      = (1 << 0),
        BRIGHT  = (1 << 1)
    };

    // some arbitrary members
    uint32  m_Flags;
    int32   m_Size;
    char    m_Character;

};

//-----------------------------------------------------------------------------

IW_MANAGED_IMPLEMENT(CHansol);

// The CHansol object
CHansol *s_Hansol = NULL;

//-----------------------------------------------------------------------------

// A custom menu item used to display / edit s_Hansol's members
class CIwMenuItemHansol : public CIwMenuItem
{
public:
    CIwMenuItemHansol()
        : CIwMenuItem("", "s_Hansol", 0, CIwMenuItem::MENU) {};

    // Override the select function
    void Select()
    {
        CIwMenu *menu = new CIwMenu;

        // title string
        menu->AddItem(new CIwMenuItemTitle("s_Hansol"));

        // display read-only
        menu->AddItem(new CIwMenuItemDisplayValue("m_Character", s_Hansol->m_Character, IW_TYPE_STRING));

        // display writable
        menu->AddItem(new CIwMenuItemEditInt32("m_Size", &s_Hansol->m_Size));

        // display writable
        menu->AddItem(new CIwMenuItemEditFlags("ON", &s_Hansol->m_Flags, CHansol::ON));

        // display writable
        menu->AddItem(new CIwMenuItemEditFlags("BRIGHT", &s_Hansol->m_Flags, CHansol::BRIGHT));

        // set selection position
        menu->SetItemID(1);

        // add the new menu
        IwGetMenuManager()->AddMenu(menu);
    }
};

//-----------------------------------------------------------------------------

// Callback used to create the main menu
CIwMenu* DebugCreateMainMenu()
{
    CIwMenu* menu = new CIwMenu;

    // Create a menu item that leads to the CHansol object
    menu->AddItem(new CIwMenuItemHansol);

    // Set the start position to render the menu
    menu->SetXY(0, 100);

    return menu;
}

//-----------------------------------------------------------------------------

void ExampleInit()
{
    // Initialise GX
    IwGxInit();

    // Create the CHansol object
    s_Hansol = new CHansol;

    // Initialise menu manager
    new CIwMenuManager;

    // Set the debug menu text rendering callback
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);

    // Set the callback that creates the main menu
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}

//-----------------------------------------------------------------------------

void ExampleShutDown()
{
    // Destroy menu manager
    delete IwGetMenuManager();

    // Destroy the CHansol object
    delete s_Hansol;

    // Terminate GX
    IwGxTerminate();
}

//-----------------------------------------------------------------------------

bool ExampleUpdate()
{
    // Update menu
    IwGetMenuManager()->Update();

    return true;
}

//-----------------------------------------------------------------------------

void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    IwGxPrintString(0, 50, "Demonstrating the IwMenu API");

    // Display state of the CHansol object
    char display[1000];
    sprintf(display,    "s_Hansol has\nm_Character = %c,\nm_Size = %ld,\nON = %s,\nBRIGHT = %s",
                        s_Hansol->m_Character,
                        s_Hansol->m_Size,
                        (s_Hansol->m_Flags & CHansol::ON) ? "on" : "off",
                        (s_Hansol->m_Flags & CHansol::BRIGHT) ? "on" : "off");

    IwGxPrintString(0, IwGxGetDeviceHeight() - 120, display);

    IwGxPrintString(0, IwGxGetDeviceHeight() - 60, "F6: Bring up the Debug Menu");
    IwGxPrintString(0, IwGxGetDeviceHeight() - 50, "Arrow Keys: Navigate Setting");
    IwGxPrintString(0, IwGxGetDeviceHeight() - 40, "Num Pad +: Increment Setting");
    IwGxPrintString(0, IwGxGetDeviceHeight() - 30, "Num Pad -: Decrement Setting");

    // Display the menu
    IwGetMenuManager()->Render();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: Random Number Example

Airplay API Reference > IwUtil API Documentation > IwUtil Examples > Random Number Example >

Random Number Example

The following example generates random numbers. The important functions in this example are:

  • IwRandSeed()

  • s3eTimerGetMs()

  • IwRandMinMax()

Note:
For more information on generating random numbers, see the Random section of the IwUtil API Documentation.
The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

#include "IwRandom.h"

// used for random seeding
#include "s3eTimer.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    IwGxFlush();

    char display[1000], output[100];
    display[0] = 0;

    // set the seed to a constant - i.e. same sequence every time
    IwRandSeed(-1);

    // print out a random number in 0..0x7fff
    sprintf(output, "Constant seed gives: \n%ld (in [0,32767])\n\n", IwRand());
    strcat(display, output);

    // set the seed to time elapsed - i.e. different sequence every time
    IwRandSeed((int32)s3eTimerGetMs());

    // print out a random number in 10..20
    sprintf(output, "Time-based seed gives: \n%ld (in [10,20])", IwRandMinMax(10, 20));
    strcat(display, output);

    IwGxPrintString(10, 56, display);

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGeom API Documentation

Airplay API Reference > IwGeom API Documentation >

IwGeom API Documentation

The IwGeom Documentation contains the following sections:

  • IwGeom API Overview
  • IwGeom API Reference
  • IwGeom Examples


Airplay API Reference: IwGeom API Overview

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview >

IwGeom API Overview

IwGeom is fundamentally a 3D geometry library, offering support for both fixed-point and floating-point types. It also provides some useful general mathematical functionality and conversion functions.

To use IwGeom functionality in a project, you must include "IwGeom.h" in your source and iwgeom as a subproject in the project's MKB file:

  • subprojects
  • {
    • iwgeom
  • }

IwUtil is included implicitly as a subproject of IwGeom; it does does not need to be explicitly included in projects which include the IwGeom module.

It is assumed that floating-point variants will not be used in time-critical code; as such, they have not been heavily optimised for speed. For example, on ARM targets with no FPU, the use of "float" within the code may result in highly inefficient code being generated. Floating-point variants should be avoided in all time-critical code.

Within the Debug version of the library, fixed-point variants contain overflow-checking code. This is extremely useful, as an overflow in a fixed-point calculation will not trigger any kind of processor exception, but will almost certainly cause the application to behave in an unintended manner. Any assertions caused by fixed-point overflows should be dealt with before making a Release build for the target device.

Many of the IwGeom methods are implemented using inline operator overloads. This provides maximum speed of execution together with maximum ease of use for the application programmer.

The following subjects are covered in this section:

  • IwGeom Initialisation and Termination
  • Types
  • Vector
  • Matrix
  • Sphere
  • Bounding Box
  • Plane
  • Quaternion
  • Trigonometry and Square Root
  • Intersection


Airplay API Reference: IwGeom Initialisation and Termination

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > IwGeom Initialisation and Termination >

IwGeom Initialisation and Termination

The user must initialise IwGeom and terminate IwGeom as follows:

  • // Begin application
  • IwUtilInit();
  • IwGeomInit();

    • ...rest of application

  • // End application
  • IwGeomTerminate();
  • IwUtilTerminate();


Airplay API Reference: Types

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Types >

Types

IwGeom defines certain fixed-point variable types. The fundamental fixed-point type is defined as follows:

  • /* Typedef of signed 32-bit fixed point number, in 1.19.12 format. */
  • typedef int32 iwfixed;

This is a 32-bit type, which provides 1 sign bit, 19 integer bits, and 12 fractional bits. So, a value of 0x1000 corresponds to the integer one. This value is defined as follows:

  • // One as a fixed point number for use with .12 formats.
  • #define IW_GEOM_ONE (1 << IW_GEOM_POINT)

A fixed point of 12 is the standard used through the majority of the IwGeom API. For example, a short 16-bit type is also defined, but has the fixed point in the same place:

  • /* Typedef of signed 16-bit fixed point number, in 1.3.12 format.*/
  • typedef int16 iwsfixed;

This is a 16-bit type, which provides 1 sign bit, 3 integer bits, and 12 fractional bits. So, a value of 0x1000 still corresponds to the integer one.

An 'angle' type is also defined, which conceptually is identical to iwfixed, if you consider one to be 360 degrees:

  • /* Typedef of 32-bit fixed point angle, where 0x800 represents PI. */
  • typedef int32 iwangle;

Note: There are some exceptions to the 'fixed point of 12', but the user is rarely exposed to them; for example, CIwQuat has components that use a 'fixed point of 30', because increased accuracy is required and we know the components will never have a magnitude greater than one.

Macros are provided to convert between standard and fixed-point types. These macros can take either integer or floating-point inputs. For example:

  • // Converts a value to a iwfixed value.
  • #define IW_FIXED(x) ((iwfixed)((x) * IW_GEOM_ONE))

For a full list of types and low-level conversion macros/functions, see IwGeomCore.h.

Note: For an example of how the various types are used, see the Vectors Example.


Airplay API Reference: Vector

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Vector >

Vector

The vector object provided by IwGeom is essentially an n-dimensional array of components of some type, either fixed-point or floating-point.

The vector classes provided by IwGeom are:

  • Class
  • CIwSVec2
  • CIwSVec3
  • CIwSVec4
  • CIwVec2
  • CIwVec3
  • CIwVec4
  • CIwFVec2
  • CIwFVec3
  • CIwFVec4
  • Fixed or floating
  • FIXED
  • FIXED
  • FIXED
  • FIXED
  • FIXED
  • FIXED
  • FLOATING
  • FLOATING
  • FLOATING
  • Component type
  • iwsfixed (16-bit)
  • iwsfixed (16-bit)
  • iwsfixed (16-bit)
  • iwfixed (32-bit)
  • iwfixed (32-bit)
  • iwfixed (32-bit)
  • float (32-bit)
  • float (32-bit)
  • float (32-bit)
  • Description
  • 2D 16-bit fixed-point vector.
  • 3D 16-bit fixed-point vector.
  • 4D 16-bit fixed-point vector.
  • 2D 32-bit fixed-point vector.
  • 3D 32-bit fixed-point vector.
  • 4D 32-bit fixed-point vector.
  • 2D 32-bit floating-point vector.
  • 3D 32-bit floating-point vector.
  • 4D 32-bit floating-point vector.

The source code for these different types are all spawned from a single script; therefore the range of methods available is consistent across all types.

Vector components can be accessed directly as x, y, z, w (z available for 3- and 4-dimensional vectors, w available for 4-dimensional vectors).

Most useful vector operations are implemented using operator overloads. For example:

  • // Create two fixed-point vectors
  • CIwVec3 v0(0x400, 0x800, 0x1000);
  • CIwVec3 v1(0x200, 0x400, 0x800);
  • // Create a new vector by adding them
  • CIwVec3 v2 = v0 + v1;
  • // Get the dot product
  • int32 dot = v0 * v1;
  • // Multiply by a fixed-point scalar
  • iwfixed len = 2 * IW_GEOM_ONE;
  • CIwVec3 v3 = v0 * len;

Many vector methods are implemented using inline functions, as the implementations are small and they are often used in time-critical code. Inspect the relevant header files to see exactly what operations are taking place.

Note: For a full list of vector methods, see the IwGeom API Reference.


Airplay API Reference: Matrix

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Matrix >

Matrix

Matrices in IwGeom are effectively in 4x3 format, comprising a 3x3 rotation, and a 3-component vector translation.

The 3x3 rotation is accessed via member "m", and the translation via member "t".

Here are the abbreviated definitions of the fixed-point and floating-point objects:

  • // Fixed-point matrix
  • class CIwMat
  • {
  • public:
    • iwfixed m[3][3];
    • CIwVec3 t;
  • };
  • // Floating-point matrix
  • class CIwFMat
  • {
  • public:
    • float m[3][3];
    • CIwFVec3 t;
  • };

The rotation matrix is thus in 'row major' format, where successive 32-bit entries map to the rotation and translation components.

Multiplication of a vector by a matrix then happens as follows; suppose we have a vector, CIwVec3 v0, and matrix, CIwMat m0. Then:

  • m0.RotateVec(v0) = v0.x v0.y v0.z)
  • m0.m[0][0] m0.m[0][1] m0.m[0][2]
  • m0.m[1][0] m0.m[1][1] m0.m[1][2]
  • m0.m[2][0] m0.m[2][1] m0.m[2][2]

So if we consider m0 to be representing some local space, then the rows of the rotation matrix represent the axes of the local space.

Note that 'RotateVec()' does not add the matrix translation; to include the matrix translation, we should use:

  • CIwVec3 v1 = m0.TransformVec(v0);

Note: Many matrix methods are implemented using inline functions, as the implementations are small and they are often used in time-critical code. Inspect the relevant header files to see exactly what operations are taking place.

See the IwGeom API Reference for a full list of matrix methods, and for an example of how the matrix is used, see the Matrix Rotation Example.


Airplay API Reference: Sphere

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Sphere >

Sphere

The sphere classes provided by IwGeom are:

  • Class
  • CIwSphere
  • CIwSSphere
  • CIwFSphere

  • Fixed or floating
  • FIXED
  • FIXED
  • FLOATING
  • Component type
  • iwfixed (32-bit)
  • iwsfixed (16-bit)
  • float (32-bit)
  • Description
  • 32-bit fixed-point sphere.
  • 16-bit fixed-point sphere.
  • 32-bit floating-point sphere.

The sphere class contains origin and radius members, of the specified types (for example, CIwSSphere has an origin member of type CIwSVec3).

The sphere class also maintains a "radius squared" member. This is often useful when performing intersection tests such as sphere-sphere intersection. For this reason, the user should always set the sphere radius using the SetRadius() method, rather than writing directly to the radius member.

For example, here is the abbreviated effective definition of CIwSphere:

  • class CIwSphere
  • {
  • public:
    • CIwVec3 t;
    • iwfixed r;
    • uint32 r2;
  • };

Note: The header file definition is different, because IwGeom uses a templated class.

See the IwGeom API Reference for a full list of sphere methods.


Airplay API Reference: Bounding Box

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Bounding Box >

Bounding Box

The (axis-aligned) bounding box classes provided by IwGeom are:

  • Class
  • CIwBBox
  • CIwSBBox
  • CIwFBBox
  • Fixed or floating
  • FIXED
  • FIXED
  • FLOATING
  • Component type
  • iwfixed (32-bit)
  • iwsfixed (16-bit)
  • float (32-bit)
  • Description
  • 32-bit fixed-point bounding box
  • 16-bit fixed-point bounding box
  • 32-bit floating-point bounding box

The bounding box class contains "min" and "max" members, of the specified types (for example, CIwSBBox has members of type CIwSVec3).

For example, here is the abbreviated effective definition of CIwBBox:

  • class CIwBBox
  • {
  • public:
    • CIwVec3 m_Min;
    • CIwVec3 m_Max;
  • };

Note: The header file definition is different, because IwGeom uses a templated class.

Methods are provided to return the bounding box origin; find the bounding box, which encloses an array of points; check whether the bounding box contains a point; and more.

Note: See the IwGeom API Reference for a full list of bounding box methods, and for an example of how bounding boxes are used, see the Primitives Example.


Airplay API Reference: Plane

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Plane >

Plane

IwGeom provides only a fixed-point plane class, which is described by a normal and constant, as follows:

  • class CIwPlane
  • {
  • public:
    • CIwVec3 v;
    • int32 k;
  • };

These members then satisfy the standard plane equation, as follows:

  • Ax + By + Cz + D = 0
  • ...where A = v.x, B = v.y, C = v.z, D = -k.

Note: See the IwGeom API Reference for a full list of plane methods.


Airplay API Reference: Quaternion

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Quaternion >

Quaternion

A quaternion is a 4-dimensional vector with "real" and "imaginary" mathematical components. The set of 'unit quaternions' (i.e., those with unit magnitude) maps onto the set of 3-dimensional rotations. The unit quaternion thus provides an efficient alternative representation for 3-dimensional rotations. One particularly useful function of quaternions is that you can easily interpolate between them, which provides a nice way of interpolating between 3-dimensional rotations. This process is called "spherical linear interpolation", or "slerp".

The quaternion classes provided by IwGeom are:

  • Class
  • CIwQuat
  • CIwSQuat
  • CIwFQuat
  • Fixed or floating
  • FIXED
  • FIXED
  • FLOATING
  • Component type
  • iwqfixed (32-bit)
  • iwsfixed (16-bit)
  • float (32-bit)
  • Description
  • 32-bit fixed-point quaternion.
  • 16-bit fixed-point quaternion.
  • 32-bit floating-point quaternion.

Note: CIwQuat uses a 'fixed point of 30', and thus has higher accuracy than CIwSQuat, which uses the standard 'fixed point of 12'. CIwSQuat is generally sufficient for slerping between rotations; CIwQuat may be required for some physics algorithms, where there is repeated application of tiny rotations.

A quaternion may be converted to its matrix representation as follows:

  • CIwQuat q0;
  • CIwMat m0(q0);

A rotation matrix may be converted to a quaternion representation as follows:

  • CIwMat m0;
  • CIwQuat q0(m0);

Note: See the IwGeom API Reference for a full list of quaternion methods.


Airplay API Reference: Trigonometry and Square Root

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Trigonometry and Square Root >

Trigonometry and Square Root

IwGeom provides the following trigonometric functions, in both fixed-point and floating-point:

  • sin,
  • cos,
  • tan,
  • acos,
  • atan2

For example:

  • iwangle a = 0x200; // PI / 4
  • int32 c = IW_GEOM_COS(a);
  • // result will be one over root 2, in fixed-point

The fixed-point variants are implemented using table lookups, for maximum performance. The floating-point variants map to the standard library functions, for example:

  • double cos(double);

IwGeom also provides fixed-point square root and inverse square root functions. These are implemented using a combination of algorithmic and table lookup functions. For example:

  • // Fixed-point square root
  • iwfixed val = IW_GEOM_ONE * 4;
  • iwfixed sq = IW_GEOM_SQRT(val);
  • // result will be 2, in fixed-point
  • // Fixed-point inverse square root
  • iwfixed val2 = IW_GEOM_ONE * 4;
  • iwfixed sq2 = IW_GEOM_INVERSE_SQRT(val2);
  • // result will be 1/2, in fixed-point

Floating-point square root is available through the standard library function:

  • double sqrt(double);

Note: See the IwGeom API Reference for a full list of quaternion methods. for a full list of trigonometric and square root methods.


Airplay API Reference: Intersection

Airplay API Reference > IwGeom API Documentation > IwGeom API Overview > Intersection >

Intersection

IwGeom does not provide an exhaustive list of intersection methods between the various geometry object types (vector, sphere, bounding box, etc. ).

It does, however, provide a small number of useful functions for testing intersections between bounded lines, planes and spheres.

Note: See the IwGeom API Reference for a full list of intersection functions.


Airplay API Reference: IwGeom API Reference

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference >

IwGeom API Reference

Modules

IwGeomBBox
IwGeomCore
IwGeomFMat
IwGeomFMat2D
IwGeomFQuat
IwGeomFVec2
IwGeomFVec3
IwGeomFVec4
Intersect
IwGeomLegacy
IwGeomMat
IwGeomMat2D
IwGeomMenu
IwGeomPlane
IwGeomQuat
IwGeomSphere
IwGeomSQuat
IwGeomSVec2
IwGeomSVec3
IwGeomSVec4
IwGeomVec
IwGeomVec2
IwGeomVec3
IwGeomVec4

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwVec4 | CIwVec4::operator * (iwfixed l) const
CIwVec4 & | CIwVec4::operator *= (iwfixed l)
VALUE_IN_REGS CIwVec4 | CIwVec4::operator- () const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator<< (const int s) const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator<<= (const int s)
VALUE_IN_REGS CIwVec4 | CIwVec4::operator>> (const int s) const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator>>= (const int s)
VALUE_IN_REGS int32 | CIwVec4::operator[] (const int n) const
VALUE_IN_REGS int32 & | CIwVec4::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwVec4::operator * (CIwVec4 const &v) const
bool | CIwVec4::operator!= (CIwVec4 const &v) const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator+ (CIwVec4 const &v) const
CIwVec4 & | CIwVec4::operator+= (CIwVec4 const &v)
VALUE_IN_REGS CIwVec4 | CIwVec4::operator- (CIwVec4 const &v) const
CIwVec4 & | CIwVec4::operator-= (CIwVec4 const &v)
CIwVec4 & | CIwVec4::operator= (CIwVec4 const &v)
bool | CIwVec4::operator== (CIwVec4 const &v) const
VALUE_IN_REGS CIwVec4 | CIwVec4::operator^ (CIwVec4 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwVec3 | CIwVec3::operator * (iwfixed l) const
CIwVec3 & | CIwVec3::operator *= (iwfixed l)
VALUE_IN_REGS CIwVec3 | CIwVec3::operator- () const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator<< (const int s) const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator<<= (const int s)
VALUE_IN_REGS CIwVec3 | CIwVec3::operator>> (const int s) const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator>>= (const int s)
VALUE_IN_REGS int32 | CIwVec3::operator[] (const int n) const
VALUE_IN_REGS int32 & | CIwVec3::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwVec3::operator * (CIwVec3 const &v) const
bool | CIwVec3::operator!= (CIwVec3 const &v) const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator+ (CIwVec3 const &v) const
CIwVec3 & | CIwVec3::operator+= (CIwVec3 const &v)
VALUE_IN_REGS CIwVec3 | CIwVec3::operator- (CIwVec3 const &v) const
CIwVec3 & | CIwVec3::operator-= (CIwVec3 const &v)
CIwVec3 & | CIwVec3::operator= (CIwVec3 const &v)
bool | CIwVec3::operator== (CIwVec3 const &v) const
VALUE_IN_REGS CIwVec3 | CIwVec3::operator^ (CIwVec3 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwVec2 | CIwVec2::operator * (iwfixed l) const
CIwVec2 & | CIwVec2::operator *= (iwfixed l)
VALUE_IN_REGS CIwVec2 | CIwVec2::operator- () const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator<< (const int s) const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator<<= (const int s)
VALUE_IN_REGS CIwVec2 | CIwVec2::operator>> (const int s) const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator>>= (const int s)
VALUE_IN_REGS int32 | CIwVec2::operator[] (const int n) const
VALUE_IN_REGS int32 & | CIwVec2::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwVec2::operator * (CIwVec2 const &v) const
bool | CIwVec2::operator!= (CIwVec2 const &v) const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator+ (CIwVec2 const &v) const
CIwVec2 & | CIwVec2::operator+= (CIwVec2 const &v)
VALUE_IN_REGS CIwVec2 | CIwVec2::operator- (CIwVec2 const &v) const
CIwVec2 & | CIwVec2::operator-= (CIwVec2 const &v)
CIwVec2 & | CIwVec2::operator= (CIwVec2 const &v)
bool | CIwVec2::operator== (CIwVec2 const &v) const
VALUE_IN_REGS CIwVec2 | CIwVec2::operator^ (CIwVec2 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator * (iwfixed l) const
CIwSVec4 & | CIwSVec4::operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator- () const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator<< (const int s) const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator<<= (const int s)
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator>> (const int s) const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator>>= (const int s)
VALUE_IN_REGS int16 | CIwSVec4::operator[] (const int n) const
VALUE_IN_REGS int16 & | CIwSVec4::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwSVec4::operator * (CIwSVec4 const &v) const
bool | CIwSVec4::operator!= (CIwSVec4 const &v) const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator+ (CIwSVec4 const &v) const
CIwSVec4 & | CIwSVec4::operator+= (CIwSVec4 const &v)
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator- (CIwSVec4 const &v) const
CIwSVec4 & | CIwSVec4::operator-= (CIwSVec4 const &v)
CIwSVec4 & | CIwSVec4::operator= (CIwSVec4 const &v)
bool | CIwSVec4::operator== (CIwSVec4 const &v) const
VALUE_IN_REGS CIwSVec4 | CIwSVec4::operator^ (CIwSVec4 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator * (iwfixed l) const
CIwSVec3 & | CIwSVec3::operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator- () const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator<< (const int s) const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator<<= (const int s)
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator>> (const int s) const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator>>= (const int s)
VALUE_IN_REGS int16 | CIwSVec3::operator[] (const int n) const
VALUE_IN_REGS int16 & | CIwSVec3::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwSVec3::operator * (CIwSVec3 const &v) const
bool | CIwSVec3::operator!= (CIwSVec3 const &v) const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator+ (CIwSVec3 const &v) const
CIwSVec3 & | CIwSVec3::operator+= (CIwSVec3 const &v)
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator- (CIwSVec3 const &v) const
CIwSVec3 & | CIwSVec3::operator-= (CIwSVec3 const &v)
CIwSVec3 & | CIwSVec3::operator= (CIwSVec3 const &v)
bool | CIwSVec3::operator== (CIwSVec3 const &v) const
VALUE_IN_REGS CIwSVec3 | CIwSVec3::operator^ (CIwSVec3 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator * (iwfixed l) const
CIwSVec2 & | CIwSVec2::operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator- () const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator<< (const int s) const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator<<= (const int s)
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator>> (const int s) const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator>>= (const int s)
VALUE_IN_REGS int16 | CIwSVec2::operator[] (const int n) const
VALUE_IN_REGS int16 & | CIwSVec2::operator[] (const int n)

Operator overloads.

Using vectors as operators.

int32 | CIwSVec2::operator * (CIwSVec2 const &v) const
bool | CIwSVec2::operator!= (CIwSVec2 const &v) const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator+ (CIwSVec2 const &v) const
CIwSVec2 & | CIwSVec2::operator+= (CIwSVec2 const &v)
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator- (CIwSVec2 const &v) const
CIwSVec2 & | CIwSVec2::operator-= (CIwSVec2 const &v)
CIwSVec2 & | CIwSVec2::operator= (CIwSVec2 const &v)
bool | CIwSVec2::operator== (CIwSVec2 const &v) const
VALUE_IN_REGS CIwSVec2 | CIwSVec2::operator^ (CIwSVec2 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator * (float l) const
CIwFVec4 & | CIwFVec4::operator *= (float l)
VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator- () const
VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator/ (const float s) const
VALUE_IN_REGS float | CIwFVec4::operator[] (const int n) const
VALUE_IN_REGS float & | CIwFVec4::operator[] (const int n)

Operator overloads.

Using vectors as operators.

float | CIwFVec4::operator * (CIwFVec4 const &v) const
bool | CIwFVec4::operator!= (CIwFVec4 const &v) const
VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator+ (CIwFVec4 const &v) const
CIwFVec4 & | CIwFVec4::operator+= (CIwFVec4 const &v)
VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator- (CIwFVec4 const &v) const
CIwFVec4 & | CIwFVec4::operator-= (CIwFVec4 const &v)
CIwFVec4 & | CIwFVec4::operator= (CIwFVec4 const &v)
bool | CIwFVec4::operator== (CIwFVec4 const &v) const
VALUE_IN_REGS CIwFVec4 | CIwFVec4::operator^ (CIwFVec4 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator * (float l) const
CIwFVec3 & | CIwFVec3::operator *= (float l)
VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator- () const
VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator/ (const float s) const
VALUE_IN_REGS float | CIwFVec3::operator[] (const int n) const
VALUE_IN_REGS float & | CIwFVec3::operator[] (const int n)

Operator overloads.

Using vectors as operators.

float | CIwFVec3::operator * (CIwFVec3 const &v) const
bool | CIwFVec3::operator!= (CIwFVec3 const &v) const
VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator+ (CIwFVec3 const &v) const
CIwFVec3 & | CIwFVec3::operator+= (CIwFVec3 const &v)
VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator- (CIwFVec3 const &v) const
CIwFVec3 & | CIwFVec3::operator-= (CIwFVec3 const &v)
CIwFVec3 & | CIwFVec3::operator= (CIwFVec3 const &v)
bool | CIwFVec3::operator== (CIwFVec3 const &v) const
VALUE_IN_REGS CIwFVec3 | CIwFVec3::operator^ (CIwFVec3 const &v) const

Operator overloads

Using scalar values.

VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator * (float l) const
CIwFVec2 & | CIwFVec2::operator *= (float l)
VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator- () const
VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator/ (const float s) const
VALUE_IN_REGS float | CIwFVec2::operator[] (const int n) const
VALUE_IN_REGS float & | CIwFVec2::operator[] (const int n)

Operator overloads.

Using vectors as operators.

float | CIwFVec2::operator * (CIwFVec2 const &v) const
bool | CIwFVec2::operator!= (CIwFVec2 const &v) const
VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator+ (CIwFVec2 const &v) const
CIwFVec2 & | CIwFVec2::operator+= (CIwFVec2 const &v)
VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator- (CIwFVec2 const &v) const
CIwFVec2 & | CIwFVec2::operator-= (CIwFVec2 const &v)
CIwFVec2 & | CIwFVec2::operator= (CIwFVec2 const &v)
bool | CIwFVec2::operator== (CIwFVec2 const &v) const
VALUE_IN_REGS CIwFVec2 | CIwFVec2::operator^ (CIwFVec2 const &v) const

Defines

#define | INVERSE_SQRT_TABLE_BITS 12

Functions

INLINE iwfixed | IW_GEOM_INVERSE_SQRT (iwfixed x)
INLINE iwfixed | IW_GEOM_INVERSE_SQRT2 (iwfixed x)
iwqfixed | IW_GEOM_QSQRT (iwqfixed a)
iwfixed | IW_GEOM_SQRT (iwfixed a)
int32 | IW_GEOM_SQRT2 (int32 a)
INLINE iwfixed | IW_GEOM_SQRT2_FAST (iwfixed x)
INLINE iwfixed | IW_GEOM_SQRT_FAST (iwfixed x)

Define Documentation

#define INVERSE_SQRT_TABLE_BITS 12

Settings for the x -> 1 / Sqrt(x) lookup table

Function Documentation

INLINE iwfixed IW_GEOM_INVERSE_SQRT ( iwfixed x )

Maps x to 1 / sqrt(x) using a lookup table. The table must have been initialised by a call to IwInverseSqrtInit() or IwGeomInit()

This operation performas a lot better with the ARM 5 instruction set (using the clz instruction). It takes about 18 instructions using the ARM 5 instruction set, and about 33 otherwise.

INLINE iwfixed IW_GEOM_INVERSE_SQRT2 ( iwfixed x )

Maps x to 1 / sqrt(x) using a lookup table. The table must have been initialised by a call to IwInverseSqrtInit() or IwGeomInit()

Takes as its input a value which has 24 bit decimal precision and outputs a normal iwfixed with 12 bit decimal precision.

This operation performas a lot better with the ARM 5 instruction set (using the clz instruction). It takes about 18 instructions using the ARM 5 instruction set, and about 33 otherwise.

iwqfixed IW_GEOM_QSQRT ( iwqfixed a )

Square root of a iwqfixed number.

Required Header Files
IwGeomSqrt.h

iwfixed IW_GEOM_SQRT ( iwfixed a )

Square root of a iwfixed number.

Required Header Files
IwGeomSqrt.h

int32 IW_GEOM_SQRT2 ( int32 a )

Square root of a number with fixed point position twice IW_GEOM_POINT

Parameters:
a value to take square root of
Returns:
square root of given value with fixed point position twice IW_GEOM_POINT
Required Header Files
IwGeomSqrt.h

INLINE iwfixed IW_GEOM_SQRT2_FAST ( iwfixed x )

get the square root of x using the lookup table

Parameters:
x value to get the square root of
Required Header Files
IwGeomSqrt.h
Required Header Files
IwGeomSqrt.h

INLINE iwfixed IW_GEOM_SQRT_FAST ( iwfixed x )

get the square root of x using the lookup table

Parameters:
x value to get the square root of
Required Header Files
IwGeomSqrt.h
Required Header Files
IwGeomSqrt.h

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwVec4::operator * ( CIwVec4 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwVec3::operator * ( CIwVec3 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwVec2::operator * ( CIwVec2 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwSVec4::operator * ( CIwSVec4 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwSVec3::operator * ( CIwSVec3 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator * ( iwfixed l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwSVec2::operator * ( CIwSVec2 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwFVec4 CIwFVec4::operator * ( float l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER float CIwFVec4::operator * ( CIwFVec4 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator * ( float l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER float CIwFVec3::operator * ( CIwFVec3 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER VALUE_IN_REGS CIwFVec2 CIwFVec2::operator * ( float l ) const [inherited]

Multiplication : Component wise multiplication with a scalar

Parameters:
l scalar value to be multiplied with
Returns:
Resulting vector.

INLINE_MEMBER float CIwFVec2::operator * ( CIwFVec2 const & v ) const [inherited]

Dot product.

Parameters:
Vector to dot product with.
Returns:
Resulting scalar value .

INLINE_MEMBER CIwVec4 & CIwVec4::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec3 & CIwVec3::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec2 & CIwVec2::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec4 & CIwSVec4::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec3 & CIwSVec3::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec2 & CIwSVec2::operator *= ( iwfixed l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec4 & CIwFVec4::operator *= ( float l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec3 & CIwFVec3::operator *= ( float l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec2 & CIwFVec2::operator *= ( float l ) [inherited]

Multiplication assignment: Component wise multiplication with a scalar with an assignment afterwards.

Parameters:
l Scalar value to be multiplied with and assigned aftwerwards.
Returns:
Resulting vector.

INLINE_MEMBER bool CIwVec4::operator!= ( CIwVec4 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwVec3::operator!= ( CIwVec3 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwVec2::operator!= ( CIwVec2 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwSVec4::operator!= ( CIwSVec4 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwSVec3::operator!= ( CIwSVec3 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwSVec2::operator!= ( CIwSVec2 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwFVec4::operator!= ( CIwFVec4 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwFVec3::operator!= ( CIwFVec3 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER bool CIwFVec2::operator!= ( CIwFVec2 const & v ) const [inherited]

Inequality.

Parameters:
v Vector to compare with.
Returns:
true if unequal, false otherwise.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator+ ( CIwVec4 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator+ ( CIwVec3 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator+ ( CIwVec2 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator+ ( CIwSVec4 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator+ ( CIwSVec3 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator+ ( CIwSVec2 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec4 CIwFVec4::operator+ ( CIwFVec4 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator+ ( CIwFVec3 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec2 CIwFVec2::operator+ ( CIwFVec2 const & v ) const [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec4 & CIwVec4::operator+= ( CIwVec4 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec3 & CIwVec3::operator+= ( CIwVec3 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec2 & CIwVec2::operator+= ( CIwVec2 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec4 & CIwSVec4::operator+= ( CIwSVec4 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec3 & CIwSVec3::operator+= ( CIwSVec3 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec2 & CIwSVec2::operator+= ( CIwSVec2 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec4 & CIwFVec4::operator+= ( CIwFVec4 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec3 & CIwFVec3::operator+= ( CIwFVec3 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec2 & CIwFVec2::operator+= ( CIwFVec2 const & v ) [inherited]

Addition.

Parameters:
v Vector to add.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator- ( CIwVec4 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator- ( CIwVec3 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator- ( CIwVec2 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator- ( CIwSVec4 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator- ( CIwSVec3 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator- ( CIwSVec2 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec4 CIwFVec4::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec4 CIwFVec4::operator- ( CIwFVec4 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator- ( CIwFVec3 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec2 CIwFVec2::operator- ( ) const [inherited]

Unary negation : Component wise unary negation.

Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec2 CIwFVec2::operator- ( CIwFVec2 const & v ) const [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec4 & CIwVec4::operator-= ( CIwVec4 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec3 & CIwVec3::operator-= ( CIwVec3 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec2 & CIwVec2::operator-= ( CIwVec2 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec4 & CIwSVec4::operator-= ( CIwSVec4 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec3 & CIwSVec3::operator-= ( CIwSVec3 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec2 & CIwSVec2::operator-= ( CIwSVec2 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec4 & CIwFVec4::operator-= ( CIwFVec4 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec3 & CIwFVec3::operator-= ( CIwFVec3 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec2 & CIwFVec2::operator-= ( CIwFVec2 const & v ) [inherited]

Subtraction.

Parameters:
v Vector to subtract.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator/ ( const iwfixed s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec4 CIwFVec4::operator/ ( const float s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator/ ( const float s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec2 CIwFVec2::operator/ ( const float s ) const [inherited]

Division : Component wise division by a scalar.

Parameters:
s Scalar value to divide by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator<< ( const int s ) const [inherited]

Left shift Assignment: Component-wise left shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator<<= ( const int s ) [inherited]

Left shift Assignment: Component-wise left shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec4 & CIwVec4::operator= ( CIwVec4 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec3 & CIwVec3::operator= ( CIwVec3 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwVec2 & CIwVec2::operator= ( CIwVec2 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec4 & CIwSVec4::operator= ( CIwSVec4 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec3 & CIwSVec3::operator= ( CIwSVec3 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwSVec2 & CIwSVec2::operator= ( CIwSVec2 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec4 & CIwFVec4::operator= ( CIwFVec4 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec3 & CIwFVec3::operator= ( CIwFVec3 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER CIwFVec2 & CIwFVec2::operator= ( CIwFVec2 const & v ) [inherited]

Simple assignment.

Parameters:
v Vector to assign from.
Returns:
Resulting vector.

INLINE_MEMBER bool CIwVec4::operator== ( CIwVec4 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwVec3::operator== ( CIwVec3 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwVec2::operator== ( CIwVec2 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwSVec4::operator== ( CIwSVec4 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwSVec3::operator== ( CIwSVec3 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwSVec2::operator== ( CIwSVec2 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwFVec4::operator== ( CIwFVec4 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwFVec3::operator== ( CIwFVec3 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER bool CIwFVec2::operator== ( CIwFVec2 const & v ) const [inherited]

Equalilty.

Parameters:
v Vector to compare with.
Returns:
true if equal, false otherwise.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator>> ( const int s ) const [inherited]

Right shift : Component-wise right shift by a scalar value.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec4 CIwVec4::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec2 CIwVec2::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec4 CIwSVec4::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec2 CIwSVec2::operator>>= ( const int s ) [inherited]

Right shift Assignment: Component-wise right shift by a scalar value with an assignment afterwards.

Parameters:
s Scalar value to shift by.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS int32 CIwVec4::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int32 & CIwVec4::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int32 CIwVec3::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int32 & CIwVec3::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int32 CIwVec2::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int32 & CIwVec2::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 CIwSVec4::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 & CIwSVec4::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 CIwSVec3::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 & CIwSVec3::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 CIwSVec2::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS int16 & CIwSVec2::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float CIwFVec4::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float & CIwFVec4::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float CIwFVec3::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float & CIwFVec3::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float CIwFVec2::operator[] ( const int n ) const [inherited]

Const member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

INLINE_MEMBER VALUE_IN_REGS float & CIwFVec2::operator[] ( const int n ) [inherited]

Member access by index

Parameters:
n Member to get
Returns:
Reference to nth member

VALUE_IN_REGS CIwVec4 CIwVec4::operator^ ( CIwVec4 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

VALUE_IN_REGS CIwVec2 CIwVec2::operator^ ( CIwVec2 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

VALUE_IN_REGS CIwSVec4 CIwSVec4::operator^ ( CIwSVec4 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

VALUE_IN_REGS CIwSVec2 CIwSVec2::operator^ ( CIwSVec2 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

VALUE_IN_REGS CIwFVec4 CIwFVec4::operator^ ( CIwFVec4 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

VALUE_IN_REGS CIwFVec2 CIwFVec2::operator^ ( CIwFVec2 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwVec3 CIwVec3::operator^ ( CIwVec3 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwSVec3 CIwSVec3::operator^ ( CIwSVec3 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.

INLINE_MEMBER VALUE_IN_REGS CIwFVec3 CIwFVec3::operator^ ( CIwFVec3 const & v ) const [inherited]

Cross product.

Parameters:
Vector to cross product with.
Returns:
Resulting vector.


Airplay API Reference: IwGeomBBox

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomBBox >

IwGeomBBox
[IwGeom API Reference]

Data Structures

class | CIwBBoxT< V >

Typedefs

typedef CIwBBoxT< CIwVec3 > | CIwBBox
typedef CIwBBoxT< CIwSVec3 > | CIwSBBox

Detailed Description

IwGeomBBox module defines an axis-aligned bounding box class template and two standard instances of this template. IwGeomBBox.h - This functionality is part of the IwGeom API.

Typedef Documentation

typedef CIwBBoxT<CIwVec3> CIwBBox

Typedef for bounding box where bounds are of type CIwVec3.

typedef CIwBBoxT<CIwSVec3> CIwSBBox

Typedef for bounding box where bounds are of type CIwSVec3.


Airplay API Reference: IwGeomCore

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomCore >

IwGeomCore
[IwGeom API Reference]

Defines

#define | IW_ANGLE_2PI ((iwangle)IW_GEOM_ONE)
#define | IW_ANGLE_FROM_DEGREES(x) ((iwangle)(((x) * IW_ANGLE_2PI) / 360.0))
#define | IW_ANGLE_FROM_RADIANS(x) ((iwangle)(((x) * IW_ANGLE_2PI) / (2 * PI)))
#define | IW_ANGLE_MASK_PHASE(x) ((iwangle)((x) & (IW_ANGLE_2PI - 1)))
#define | IW_ANGLE_PI ((iwangle)IW_GEOM_HALF)
#define | IW_ANGLE_Q2PI ((iwangle)IW_GEOM_QONE)
#define | IW_ANGLE_TO_DEGREES(x) ((int32)(((x) * 360 + (IW_ANGLE_2PI>>1)) / IW_ANGLE_2PI))
#define | IW_ANGLE_TO_RADIANS(x) ((float)(((x) * PI) / IW_ANGLE_PI))
#define | IW_FIXED(x) ((iwfixed)((x) * IW_GEOM_ONE))
#define | IW_FIXED_FROM_FLOAT_SHIFTED(a, s) ((iwfixed)((a) * (float)(1 << (s))))
#define | IW_FIXED_TO_FLOAT(a) ((float)(a) / (float)IW_GEOM_ONE)
#define | IW_GEOM_HALF (1 << (IW_GEOM_POINT - 1))
#define | IW_GEOM_ONE (1 << IW_GEOM_POINT)
#define | IW_GEOM_ONE2 (1 << (IW_GEOM_POINT << 1))
#define | IW_GEOM_POINT 12
#define | IW_GEOM_QEPSILON 0x200000
#define | IW_GEOM_QHALF (1 << (IW_GEOM_QPOINT - 1))
#define | IW_GEOM_QONE (1 << IW_GEOM_QPOINT)
#define | IW_GEOM_QONE2 ((int64)1 << (IW_GEOM_QPOINT << 1))
#define | IW_GEOM_QPOINT 30
#define | IW_GEOM_QPOINT_TO_GEOM_POINT (IW_GEOM_QPOINT - IW_GEOM_POINT)
#define | IW_GEOM_ROUND(a) (((a) + IW_GEOM_HALF) >> IW_GEOM_POINT)
#define | IW_QFIXED(x) ((iwqfixed)((x) * IW_GEOM_QONE))
#define | IW_SFIXED(x) ((iwsfixed)((x) * IW_GEOM_ONE))
#define | IW_SFIXED_FROM_FLOAT(a) IW_SFIXED_FROM_FIXED(IW_FIXED_FROM_FLOAT(a))
#define | IW_UFIXED(x) ((iwufixed)((x) * IW_GEOM_ONE))
#define | IW_USFIXED(x) ((iwusfixed)((x) * IW_GEOM_ONE))
#define | PI 3.141592653589793f

Typedefs

typedef int32 | iwangle
typedef int32 | iwfixed
typedef int32 | iwqangle
typedef int32 | iwqfixed
typedef int16 | iwsfixed
typedef uint32 | iwufixed
typedef uint16 | iwusfixed

Functions

INLINE iwangle | IW_ANGLE_DIFFERENCE (iwangle x, iwangle y)
INLINE iwfixed | IW_FIXED_DIV (iwfixed a, iwfixed b)
INLINE iwfixed | IW_FIXED_DIV_SAFE (iwfixed a, iwfixed b)
INLINE iwfixed | IW_FIXED_FROM_FLOAT (float a)
INLINE iwfixed | IW_FIXED_MUL (iwfixed a, iwfixed b)
INLINE iwfixed | IW_FIXED_MUL2 (iwfixed a, iwfixed b, iwfixed d, iwfixed e)
INLINE iwfixed | IW_FIXED_MUL2_SAFE (iwfixed a, iwfixed b, iwfixed d, iwfixed e)
INLINE iwfixed | IW_FIXED_MUL3 (iwfixed a, iwfixed b, iwfixed c, iwfixed d, iwfixed e, iwfixed f)
INLINE iwfixed | IW_FIXED_MUL3_SAFE (iwfixed a, iwfixed b, iwfixed c, iwfixed d, iwfixed e, iwfixed f)
INLINE iwfixed | IW_FIXED_MUL_SAFE (iwfixed a, iwfixed b)
INLINE int32 | IW_MUL64_3_SHIFT (int32 a, int32 b, int32 c, int32 d, int32 e, int32 f, int32 shift)
INLINE int32 | IW_MUL64_SHIFT (int32 a, int32 b, int32 shift)
INLINE int32 | IW_MUL_2_SHIFT (int32 a, int32 b, int32 d, int32 e, int32 shift)
INLINE int32 | IW_MUL_3_SHIFT (int32 a, int32 b, int32 c, int32 d, int32 e, int32 f, int32 shift)
INLINE int32 | IW_MULCHECK (const int32 a, const int32 b)
INLINE iwqfixed | IW_QFIXED_MUL (iwqfixed a, iwqfixed b)
INLINE iwqfixed | IW_QFIXED_MUL_SAFE (iwqfixed a, iwqfixed b)
INLINE iwsfixed | IW_SFIXED_FROM_FIXED (iwfixed a)
INLINE iwsfixed | IW_SFIXED_MUL (iwfixed a, iwfixed b)
iwfixed | IwGeomACos (iwfixed v)
iwfixed | IwGeomASin (iwfixed v)
iwangle | IwGeomAtan2 (int y, int x)
iwfixed | IwGeomCos (iwangle x)
void | IwGeomInit ()
iwqfixed | IwGeomQACos (iwqfixed v)
iwqfixed | IwGeomQASin (iwqfixed v)
iwqfixed | IwGeomQATan2 (iwqfixed u, iwqfixed v)
iwqfixed | IwGeomQCos (iwqangle x)
iwqfixed | IwGeomQSin (iwqangle x)
iwfixed | IwGeomSin (iwangle x)
iwfixed | IwGeomTan (iwangle x)
void | IwGeomTerminate ()

Detailed Description

The IwGeomCore module is part of the IwGeom API and contains basic type definitions and mathematical operators.

Define Documentation

#define IW_ANGLE_2PI ((iwangle)IW_GEOM_ONE)

(2 * PI) as an iwangle.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_FROM_DEGREES ( x ) ((iwangle)(((x) * IW_ANGLE_2PI) / 360.0))

Converts an angle from degrees to iwangle.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_FROM_RADIANS ( x ) ((iwangle)(((x) * IW_ANGLE_2PI) / (2 * PI)))

Converts an angle from radians to iwangle.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_MASK_PHASE ( x ) ((iwangle)((x) & (IW_ANGLE_2PI - 1)))

Restricts an iwangle to the range 0 <= x < 2PI.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_PI ((iwangle)IW_GEOM_HALF)

PI as an iwangle.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_Q2PI ((iwangle)IW_GEOM_QONE)

(2 * PI) as an iwqangle.

Required Header Files
IwGeomCore.h

#define IW_ANGLE_TO_DEGREES ( x ) ((int32)(((x) * 360 + (IW_ANGLE_2PI>>1)) / IW_ANGLE_2PI))

Converts an angle from iwangle to degrees.

Parameters:
x Angle stored as an iwangle.
Returns:
The angle as an integer, rounded to the nearest degree.
Required Header Files
IwGeomCore.h

#define IW_ANGLE_TO_RADIANS ( x ) ((float)(((x) * PI) / IW_ANGLE_PI))

Converts an angle from iwangle to radians.

Required Header Files
IwGeomCore.h

#define IW_FIXED ( x ) ((iwfixed)((x) * IW_GEOM_ONE))

Converts a value to a iwfixed value.

Required Header Files
IwGeomCore.h

#define IW_FIXED_FROM_FLOAT_SHIFTED | ( | a,
 |  | s | ) | ((iwfixed)((a) * (float)(1 << (s))))

Convert a floating point number to a fixed point number with s bits of precision.

Parameters:
a | The floating point number to convert.
s | The number of bits in the fractional part of the fixed point representation.
Required Header Files
IwGeomCore.h

#define IW_FIXED_TO_FLOAT ( a ) ((float)(a) / (float)IW_GEOM_ONE)

Converts a 32 bit fixed point number to the nearest floating point number.

Parameters:
a The 32 bit fixed point number to convert.
Required Header Files
IwGeomCore.h

#define IW_GEOM_HALF (1 << (IW_GEOM_POINT - 1))

One half (1/2) as a fixed point number for use with .12 formats.

#define IW_GEOM_ONE (1 << IW_GEOM_POINT)

One as a fixed point number for use with .12 formats.

Required Header Files
IwGeomCore.h

#define IW_GEOM_ONE2 (1 << (IW_GEOM_POINT << 1))

Same value as IW_GEOM_ONE * IW_GEOM_ONE

Required Header Files
IwGeomCore.h

#define IW_GEOM_POINT 12

Default position of fixed point, used with iwfixed and iwsfixed.

Required Header Files
IwGeomCore.h

#define IW_GEOM_QEPSILON 0x200000

Small delta for high-resolution fixed point calculations.

Required Header Files
IwGeomCore.h

#define IW_GEOM_QHALF (1 << (IW_GEOM_QPOINT - 1))

One half (1/2) as a fixed point number for use with .30 formats.

#define IW_GEOM_QONE (1 << IW_GEOM_QPOINT)

One as a fixed point number for use with .30 formats.

Required Header Files
IwGeomCore.h

#define IW_GEOM_QONE2 ((int64)1 << (IW_GEOM_QPOINT << 1))

Same value as IW_GEOM_QONE * IW_GEOM_QONE

Required Header Files
IwGeomCore.h

#define IW_GEOM_QPOINT 30

Default position of fixed point, used with CIwQuat.

Required Header Files
IwGeomCore.h

#define IW_GEOM_QPOINT_TO_GEOM_POINT (IW_GEOM_QPOINT - IW_GEOM_POINT)

Right shift used to convert quaternion fixed point to that of iwfixed.

Required Header Files
IwGeomCore.h

#define IW_GEOM_ROUND ( a ) (((a) + IW_GEOM_HALF) >> IW_GEOM_POINT)

Rounds a 32 bit fixed point number to the nearest integer.

Required Header Files
IwGeomCore.h

#define IW_QFIXED ( x ) ((iwqfixed)((x) * IW_GEOM_QONE))

Converts a value to an iwqfixed value.

Required Header Files
IwGeomCore.h

#define IW_SFIXED ( x ) ((iwsfixed)((x) * IW_GEOM_ONE))

Converts a value to a iwsfixed value.

Required Header Files
IwGeomCore.h

#define IW_SFIXED_FROM_FLOAT ( a ) IW_SFIXED_FROM_FIXED(IW_FIXED_FROM_FLOAT(a))

Convert a floating point number to the nearest 16 bit fixed point number.

Parameters:
a The floating point number to convert.
Required Header Files
IwGeomCore.h

#define IW_UFIXED ( x ) ((iwufixed)((x) * IW_GEOM_ONE))

Converts a value to a iwufixed value.

Required Header Files
IwGeomCore.h

#define IW_USFIXED ( x ) ((iwusfixed)((x) * IW_GEOM_ONE))

Converts a value to a iwusfixed value.

Required Header Files
IwGeomCore.h

#define PI 3.141592653589793f

Value of pi as a floating point number.

Required Header Files
IwGeomCore.h

Typedef Documentation

typedef int32 iwangle

Typedef of char fixed point number. Typedef of 32-bit fixed point angle, where 0x800 represents PI.

typedef int32 iwfixed

Typedef of signed 32-bit fixed point number, in 1.19.12 format.

typedef int32 iwqangle

Typedef of 32-bit fixed point angle, where 0x8000 represents PI.

typedef int32 iwqfixed

Typedef of signed 32-bit high-resolution fixed point number, in 1.1.30 format.

typedef int16 iwsfixed

Typedef of signed 16-bit fixed point number, in 1.3.12 format.

typedef uint32 iwufixed

Typedef of unsigned 32-bit fixed point number, in 0.20.12 format.

typedef uint16 iwusfixed

Typedef of unsigned 16-bit fixed point number, in 0.4.12 format.

Function Documentation

INLINE iwangle IW_ANGLE_DIFFERENCE | ( | iwangle | x,
 |  | iwangle | y
 | ) |  |

Gets the difference between two angles in the range -IW_ANGLE_PI < (x - y) <= IW_ANGLE_PI.

Note:
The smaller of the two angles is chosen.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_DIV | ( | iwfixed | a,
 |  | iwfixed | b
 | ) |  |

Divides two iwfixed numbers in fixed point.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Quotient of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_DIV_SAFE | ( | iwfixed | a,
 |  | iwfixed | b
 | ) |  |

Divides two iwfixed numbers in fixed point, promoting the divident to a 64 bit number, if necessary.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Quotient of operands, correctly shifted.
Note:
This will run much slower than IW_FIXED_DIV if the absolute value of the dividend is larger than or equal to 1<<19.

Debug version provides overflow checking of the result.

Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_FROM_FLOAT ( float a )

Convert a floating point number to the nearest 32 bit fixed point number. Checks for overflows in debug builds.

Parameters:
a The floating point number to convert.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL | ( | iwfixed | a,
 |  | iwfixed | b
 | ) |  |

Multiplies two iwfixed numbers in fixed point.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Product of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL2 | ( | iwfixed | a,
 |  | iwfixed | b,
 |  | iwfixed | d,
 |  | iwfixed | e
 | ) |  |

Dot product of two two-coordinate, iwfixed vectors (a,b) and (d,e), in fixed point.

Parameters:
a,b | First long fixed point vector.
d,e | Second long fixed point vector.
Returns:
a*d + b*e correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL2_SAFE | ( | iwfixed | a,
 |  | iwfixed | b,
 |  | iwfixed | d,
 |  | iwfixed | e
 | ) |  |

Dot product of two two-coordinate, iwfixed vectors (a,b) and (d,e), in fixed point. Calculations are made using int64 numbers.

Parameters:
a,b | First long fixed point vector.
d,e | Second long fixed point vector.
Returns:
a*d + b*e correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL3 | ( | iwfixed | a,
 |  | iwfixed | b,
 |  | iwfixed | c,
 |  | iwfixed | d,
 |  | iwfixed | e,
 |  | iwfixed | f
 | ) |  |

Dot product of two three-coordinate, iwfixed vectors (a,b,c) and (d,e,f), in fixed point.

Parameters:
a,b,c | First long fixed point vector.
d,e,f | Second long fixed point vector.
Returns:
a*d + b*e + c*f correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL3_SAFE | ( | iwfixed | a,
 |  | iwfixed | b,
 |  | iwfixed | c,
 |  | iwfixed | d,
 |  | iwfixed | e,
 |  | iwfixed | f
 | ) |  |

Dot product of two three-coordinate, iwfixed vectors (a,b,c) and (d,e,f), in fixed point. Calculations are made using int64 numbers.

Parameters:
a,b,c | First long fixed point vector.
d,e,f | Second long fixed point vector.
Returns:
a*d + b*e + c*f correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwfixed IW_FIXED_MUL_SAFE | ( | iwfixed | a,
 |  | iwfixed | b
 | ) |  |

Multiplies two iwfixed numbers, in fixed point, using int64 numbers.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Product of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE int32 IW_MUL64_3_SHIFT | ( | int32 | a,
 |  | int32 | b,
 |  | int32 | c,
 |  | int32 | d,
 |  | int32 | e,
 |  | int32 | f,
 |  | int32 | shift
 | ) |  |

Dot product of two three-coordinate, int32 vectors (a,b,c) and (d,e,f), in fixed point. Accumulates in 64bit with a specified shift down

Parameters:
a,b,c | First long fixed point vector.
d,e,f | Second long fixed point vector.
Returns:
a*d + b*e + c*f shifted accordingly.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE int32 IW_MUL64_SHIFT | ( | int32 | a,
 |  | int32 | b,
 |  | int32 | shift
 | ) |  |

Multiply two int32 values Accumulates in 64bit with a specified shift down

Parameters:
a | First long fixed point value.
b | Second long fixed point value.
Returns:
a*b shifted accordingly.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE int32 IW_MUL_2_SHIFT | ( | int32 | a,
 |  | int32 | b,
 |  | int32 | d,
 |  | int32 | e,
 |  | int32 | shift
 | ) |  |

Dot product of two two-coordinate, int32 vectors (a,b) and (d,e), in fixed point.

Parameters:
a,b | First long fixed point vector.
d,e | Second long fixed point vector.
shift | Amount to shift down by
Returns:
a*d + b*e shifted accordingly.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE int32 IW_MUL_3_SHIFT | ( | int32 | a,
 |  | int32 | b,
 |  | int32 | c,
 |  | int32 | d,
 |  | int32 | e,
 |  | int32 | f,
 |  | int32 | shift
 | ) |  |

Dot product of two three-coordinate, int32 vectors (a,b,c) and (d,e,f), in fixed point.

Parameters:
a,b,c | First long fixed point vector.
d,e,f | Second long fixed point vector.
shift | Amount to shift down by
Returns:
a*d + b*e + c*f shifted accordingly.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE int32 IW_MULCHECK | ( | const int32 | a,
 |  | const int32 | b
 | ) |  |

Multiplies two 32 bit integers, asserting if there is overflow

INLINE iwqfixed IW_QFIXED_MUL | ( | iwqfixed | a,
 |  | iwqfixed | b
 | ) |  |

Multiplies two iwqfixed numbers in fixed point.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Product of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwqfixed IW_QFIXED_MUL_SAFE | ( | iwqfixed | a,
 |  | iwqfixed | b
 | ) |  |

Multiplies two iwqfixed numbers, in fixed point, using int64 numbers.

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Product of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

INLINE iwsfixed IW_SFIXED_FROM_FIXED ( iwfixed a )

Converts a iwfixed value to a iwsfixed value. Checks for overflows in debug builds.

Required Header Files
IwGeomCore.h

INLINE iwsfixed IW_SFIXED_MUL | ( | iwfixed | a,
 |  | iwfixed | b
 | ) |  |

Multiplies two iwfixed numbers, in fixed point, casting the result to iwsfixed. Debug includes a test that the result will fit in an iwsfixed

Parameters:
a | First long operand.
b | Second long operand.
Returns:
Product of operands, correctly shifted.
Note:
Debug version provides overflow checking.
Required Header Files
IwGeomCore.h

iwfixed IwGeomACos ( iwfixed v )

acos function for iwfixed

Required Header Files
IwGeomCore.h

iwfixed IwGeomASin ( iwfixed v )

asin function for iwfixed

Required Header Files
IwGeomCore.h

iwangle IwGeomAtan2 | ( | int | y,
 |  | int | x
 | ) |  |

If we consider a standard graph with +ve x to the right, +ve y up, and theta measured anticlockwise from +ve x, this returns the angle in the range 0..0xfff

Parameters:
y | sin
x | cos
Returns:
Anticlockwise angle vector (x,y) makes with the X-axis.
Required Header Files
IwGeomCore.h

iwfixed IwGeomCos ( iwangle x )

cos function for fixed point angle.

Required Header Files
IwGeomCore.h

void IwGeomInit ( )

Initialises the IwGeom module.

Note:
This is done automatically by IwGxInit().
Required Header Files
IwGeomCore.h

iwqfixed IwGeomQACos ( iwqfixed v )

acos function for iwqfixed

Required Header Files
IwGeomCore.h

iwqfixed IwGeomQASin ( iwqfixed v )

asin function for iwqfixed

Required Header Files
IwGeomCore.h

iwqfixed IwGeomQATan2 | ( | iwqfixed | u,
 |  | iwqfixed | v
 | ) |  |

atan2 function for iwqfixed

Required Header Files
IwGeomCore.h

iwqfixed IwGeomQCos ( iwqangle x )

cos function for iwqfixed angle.

Required Header Files
IwGeomCore.h

iwqfixed IwGeomQSin ( iwqangle x )

sin function for iwqfixed angle.

Required Header Files
IwGeomCore.h

iwfixed IwGeomSin ( iwangle x )

sin function for fixed point angle.

Required Header Files
IwGeomCore.h

iwfixed IwGeomTan ( iwangle x )

tan function for fixed point angle.

Required Header Files
IwGeomCore.h

void IwGeomTerminate ( )

Terminate IwGeom module. This is done automatically by IwGxTerminate().

Required Header Files
IwGeomCore.h


Airplay API Reference: IwGeomFMat

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFMat >

IwGeomFMat
[IwGeom API Reference]

Data Structures

class | CIwFMat

Functions

INLINE_MEMBER CIwMat | CIwFMat::ConvertToCIwMat ()

Detailed Description

The IwGeomFMat module is part of the IwGeom API. IwGeomFMat.h Floating point matrix

for use with CIwFVec3.

Function Documentation

INLINE_MEMBER CIwMat CIwFMat::ConvertToCIwMat ( ) [inherited]

Creates a CIwMat matrix from this one.

See also:
CIwMat


Airplay API Reference: IwGeomFMat2D

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFMat2D >

IwGeomFMat2D
[IwGeom API Reference]

Data Structures

class | CIwFMat2D

Functions

INLINE_MEMBER CIwMat2D | CIwFMat2D::ConvertToCIwMat2D ()

Detailed Description

The IwGeomFMat2D module is part of the IwGeom API. IwGeomFMat2D.h Floating point matrix

for use with CIwFVec2.

Function Documentation

INLINE_MEMBER CIwMat2D CIwFMat2D::ConvertToCIwMat2D ( ) [inherited]

Creates a CIwMat2D matrix from this one.

See also:
CIwMat2D


Airplay API Reference: IwGeomFQuat

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFQuat >

IwGeomFQuat
[IwGeom API Reference]

Data Structures

class CIwFQuat

Detailed Description

The IwGeomFQuat module is part of the IwGeom API. IwGeomFQuat defines fixed-point quaternion and specialised vector functionality.


Airplay API Reference: IwGeomFVec2

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFVec2 >

IwGeomFVec2
[IwGeom API Reference]

Data Structures

class CIwFVec2

Detailed Description

The IwGeomFVec2 module is part of the IwGeom API.


Airplay API Reference: IwGeomFVec3

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFVec3 >

IwGeomFVec3
[IwGeom API Reference]

Data Structures

class CIwFVec3

Detailed Description

The IwGeomFVec3 module is part of the IwGeom API.


Airplay API Reference: IwGeomFVec4

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomFVec4 >

IwGeomFVec4
[IwGeom API Reference]

Data Structures

class CIwFVec4

Detailed Description

The IwGeomFVec4 module is part of the IwGeom API.


Airplay API Reference: Intersect

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > Intersect >

Intersect
[IwGeom API Reference]

Functions

bool | IwIntersectLineLine2D (const CIwVec2 &p1, const CIwVec2 &dir1, const CIwVec2 &p2, const CIwVec2 &dir2, CIwVec2 &collpt, iwfixed &t1, iwfixed &t2)
bool | IwIntersectLinePlane (const CIwVec3 &vFrom, const CIwVec3 &vFromTo, const CIwPlane &plane, int32 &f)
bool | IwIntersectLineSegPlaneOneSided (const CIwVec3 &vOrg, const CIwVec3 &vDirn, const CIwPlane &plane, int32 &f)
bool | IwIntersectLineSphere (const CIwVec3 &vOrg, const CIwVec3 &vDirn, const CIwSphere &sphere)
bool | IwIntersectLineTriNorm (const CIwVec3 &vOrg, const CIwVec3 &vDirn, const CIwVec3 &v0, const CIwVec3 &v1, const CIwVec3 &v2, const CIwSVec3 &norm, int32 &f)
bool | IwIntersectSphereSphere (const CIwSphere &s0, const CIwSphere &s1)

Detailed Description

IwGeomIntersect Module is part of the IwGeom API and contains fixed-point primitive intersection functions.

Function Documentation

bool IwIntersectLineLine2D | ( | const CIwVec2 & | p1,
 |  | const CIwVec2 & | dir1,
 |  | const CIwVec2 & | p2,
 |  | const CIwVec2 & | dir2,
 |  | CIwVec2 & | collpt,
 |  | iwfixed & | t1,
 |  | iwfixed & | t2
 | ) |  |

Intersect two lines in two dimensions. If intersect: return true, and collpt = p1 + t1* dir1 = p2 + t2* dir2.

Parameters:
p1 | Point on the first line.
dir1 | Direction of the first line (does not have to be normalised).
p2 | Point on the second line.
dir2 | Direction of the second line (does not have to be normalised).
collpt | Contains the collision point if the function returns true.
t1 | Contains the first intersection parameter if the function returns true.
t2 | Contains the second intersection parameter if the function returns true.
Returns:
true if the two lines intersect.
Required Header Files
IwGeomIntersect.h

bool IwIntersectLinePlane | ( | const CIwVec3 & | vFrom,
 |  | const CIwVec3 & | vFromTo,
 |  | const CIwPlane & | plane,
 |  | int32 & | f
 | ) |  |

Tests if a finite line segment intersects with a plane. f is set to the intersection parameter along the line (fixed point).

Parameters:
vFrom | A point on the line.
vFromTo | Vector from the start to the end of the line segment.
plane | The plane.
f | Parameter of the intersection. vOrg + vDirn * f is the intersection point.
Returns:
true if the line and the plane intersect.
Remarks:
This function tests whether a line segment intersects a plane, and not whether a infinite line intersets a plane.
Required Header Files
IwGeomIntersect.h

bool IwIntersectLineSegPlaneOneSided | ( | const CIwVec3 & | vOrg,
 |  | const CIwVec3 & | vDirn,
 |  | const CIwPlane & | plane,
 |  | int32 & | f
 | ) |  |

Do a line-segment intersection with a plane. If intersection: return true, and set f to (fixed-point) param along line. Only returns collisions if vDirn is in the opposite direction to the plane's normal.

Parameters:
vOrg | Start of the line segment.
vDirn | Direction and length of the line segment.
plane | The plane to intersect with.
f | Parameter of the intersection. vOrg + vDirn * f is the intersection point.
Returns:
true if the line segment intersects with the plane, false otherwise.
Required Header Files
IwGeomIntersect.h

bool IwIntersectLineSphere | ( | const CIwVec3 & | vOrg,
 |  | const CIwVec3 & | vDirn,
 |  | const CIwSphere & | sphere
 | ) |  |

Intersect a ray starting at vOrg pointing in direction vDirn with a sphere.

Parameters:
vOrg | Start of the ray.
vDirn | Direction of the ray (normalised).
sphere | The sphere to intersect with.
Returns:
true if the ray intersects with the sphere.
Required Header Files
IwGeomIntersect.h

bool IwIntersectLineTriNorm | ( | const CIwVec3 & | vOrg,
 |  | const CIwVec3 & | vDirn,
 |  | const CIwVec3 & | v0,
 |  | const CIwVec3 & | v1,
 |  | const CIwVec3 & | v2,
 |  | const CIwSVec3 & | norm,
 |  | int32 & | f
 | ) |  |

Do a line-segment intersection with a triangle . If intersection: return true, and set f to (fixed-point) param along line. Line-segment is specified as an origin and UNNORMALISED direction.

Parameters:
vOrg | Origin of the line.
vDirn | Direction of the line.
v0 | First vertex of the triangle.
v1 | Second vertex of the triangle.
v2 | Third vertex of the triangle.
norm | Normal of the triangle.
f | Parameter of the intersection. vOrg + vDirn * f is the intersection point.
Returns:
true if line intersects the triangle, false otherwise.
Required Header Files
IwGeomIntersect.h

bool IwIntersectSphereSphere | ( | const CIwSphere & | s0,
 |  | const CIwSphere & | s1
 | ) |  |

Detect intersection between two spheres.

Parameters:
s0 | First sphere.
s1 | Second sphere.
Returns:
true if the two spheres intersect.
Required Header Files
IwGeomIntersect.h


Airplay API Reference: IwGeomLegacy

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomLegacy >

IwGeomLegacy
[IwGeom API Reference]

Detailed Description

Legacy definitions for API changes since sdk 0.96.


Airplay API Reference: IwGeomMat

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomMat >

IwGeomMat
[IwGeom API Reference]

Data Structures

class | CIwMat

Functions

INLINE_MEMBER CIwFMat | CIwMat::ConvertToCIwFMat ()

Detailed Description

The IwGeomMat module is part of the IwGeom API. IwGeomMat.h Fixed point matrix

for use with CIwSVec3 and CIwVec3.

Function Documentation

INLINE_MEMBER CIwFMat CIwMat::ConvertToCIwFMat ( ) [inherited]

Creates a CIwFMat matrix from this one.

See also:
CIwFMat


Airplay API Reference: IwGeomMat2D

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomMat2D >

IwGeomMat2D
[IwGeom API Reference]

Data Structures

class | CIwMat2D

Functions

INLINE_MEMBER CIwFMat2D | CIwMat2D::ConvertToCIwFMat2D ()

Detailed Description

The IwGeomMat2D module is part of the IwGeom API. IwGeomMat2D.h Fixed point matrix

for use with CIwSVec2 and CIwVec2.

Function Documentation

INLINE_MEMBER CIwFMat2D CIwMat2D::ConvertToCIwFMat2D ( ) [inherited]

Creates a CIwFMat2D matrix from this one.

See also:
CIwFMat2D


Airplay API Reference: IwGeomMenu

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomMenu >

IwGeomMenu
[IwGeom API Reference]

Data Structures

class | CIwMenuItemEditAngle
class | CIwMenuItemEditFixed

Detailed Description

Objects dervied from CIwMenuItem, to allow inspection/modification of IwGeom types.


Airplay API Reference: IwGeomPlane

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomPlane >

IwGeomPlane
[IwGeom API Reference]

Data Structures

class CIwPlane
Fixed-point plane: 3-vector normal and constant. More...

Detailed Description

The IwGeomPlane module is part of the IwGeom API and defines a fixed-point plane.


Airplay API Reference: IwGeomQuat

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomQuat >

IwGeomQuat
[IwGeom API Reference]

Data Structures

class CIwQuat

Detailed Description

The IwGeomQuat module is part of the IwGeom API. IwGeomQuat defines fixed-point quaternion and specialised vector functionality.


Airplay API Reference: IwGeomSphere

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomSphere >

IwGeomSphere
[IwGeom API Reference]

Data Structures

class CIwSphereT< V, R >
Fixed-point sphere: templated origin and radius types. More...

Typedefs

typedef CIwSphereT< CIwVec3,
iwfixed > 		CIwSphere
typedef CIwSphereT< CIwSVec3,
iwsfixed > 		CIwSSphere

Detailed Description

The IwGeomSphere module is part of the IwGeom API and defines a sphere class template and two standards instances. of this template.

Typedef Documentation

typedef CIwSphereT<CIwVec3, iwfixed> CIwSphere

Typedef for sphere with origin of type CIwVec3 and radius of type iwfixed

typedef CIwSphereT<CIwSVec3, iwsfixed> CIwSSphere

Typedef for sphere with origin of type CIwSVec3 and radius of type iwsfixed


Airplay API Reference: IwGeomSQuat

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomSQuat >

IwGeomSQuat
[IwGeom API Reference]

Data Structures

class CIwSQuat

Detailed Description

The IwGeomSQuat module is part of the IwGeom API. IwGeomSQuat defines fixed-point quaternion and specialised vector functionality.


Airplay API Reference: IwGeomSVec2

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomSVec2 >

IwGeomSVec2
[IwGeom API Reference]

Data Structures

class CIwSVec2

Detailed Description

The IwGeomSVec2 module is part of the IwGeom API.


Airplay API Reference: IwGeomSVec3

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomSVec3 >

IwGeomSVec3
[IwGeom API Reference]

Data Structures

class CIwSVec3

Detailed Description

The IwGeomSVec3 module is part of the IwGeom API.


Airplay API Reference: IwGeomSVec4

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomSVec4 >

IwGeomSVec4
[IwGeom API Reference]

Data Structures

class CIwSVec4

Detailed Description

The IwGeomSVec4 module is part of the IwGeom API.


Airplay API Reference: IwGeomVec

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomVec >

IwGeomVec
[IwGeom API Reference]

The IwGeomVec module is part of the IwGeom API and includes various Vector Classes and methods for vector operations.


Airplay API Reference: IwGeomVec2

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomVec2 >

IwGeomVec2
[IwGeom API Reference]

Data Structures

class CIwVec2

Detailed Description

The IwGeomVec2 module is part of the IwGeom API.


Airplay API Reference: IwGeomVec3

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomVec3 >

IwGeomVec3
[IwGeom API Reference]

Data Structures

class CIwVec3

Detailed Description

The IwGeomVec3 module is part of the IwGeom API.


Airplay API Reference: IwGeomVec4

Airplay API Reference > IwGeom API Documentation > IwGeom API Reference > IwGeomVec4 >

IwGeomVec4
[IwGeom API Reference]

Data Structures

class CIwVec4

Detailed Description

The IwGeomVec4 module is part of the IwGeom API.


Airplay API Reference: IwGeom Examples

Airplay API Reference > IwGeom API Documentation > IwGeom Examples >

IwGeom Examples

This document provides a set of examples that illustrate how to use the functionality contained within IwGeom. Each example uses the functionality specific to IwGeom, and endeavours to illustrate the capabilities of each of these modules. The following examples are contained within this section:

  • Primitives Example
  • Matrix Rotation Example
  • Vectors Example
  • Ray Picking Example


Airplay API Reference: Primitives Example

Airplay API Reference > IwGeom API Documentation > IwGeom Examples > Primitives Example >

Primitives Example

The following example demonstrates how to use the IwGeom bounding box functionality. The example renders a sphere, a triangle and a bounding box which bounds the entire triangle and the centre of the sphere.

The main classes used to achieve this are:

  • CIwVec3

  • CIwMat

  • CIwSphere

  • CIwBBox

The main functions used to achieve this are:

  • CIwSphere::SetRadius

  • CIwBBox::BoundVec

  • CIwMat::SetIdentity

  • IwGxDebugPrimSphere

  • IwGxDebugPrimTri

  • IwGxDebugPrimBBox

  • IwGxSetViewMatrix

The example creates a sphere primitive and a triangle primitive, and then bounds these items using the CIwBBox::BoundVec to set the bounding box values. To display these items the example sets the view matrix and renders the sphere, triangle and bounding box using the IwGxDebugPrimSphere(), IwGxDebugPrimTri() and IwGxDebugPrimBBox() functions.

Note:
For more information on using bounding boxes, see the Bounding Box section in the IwGeom API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwGeom.h"

// for primitive rendering
#include "IwGx.h"
#include "IwDebugPrim.h"

//-----------------------------------------------------------------------------
struct Triangle
{
    // vertices
    CIwVec3 m_V0, m_V1, m_V2;
};
//-----------------------------------------------------------------------------

// primitives:

// 32-bit fixed point sphere
CIwSphere   s_Sphere;

// 32-bit fixed point triangle
Triangle    s_Triangle;

// 32-bit fixed point bounding box
// initialise the bounding box with the zero vector
CIwBBox     s_BoundingBox(CIwVec3::g_Zero, CIwVec3::g_Zero);

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // initialise sphere:

    // as below, the IW_FIXED macro is used throughout this example to convert
    // floating point values to fixed point
    s_Sphere.SetRadius(IW_FIXED(0.2));
    s_Sphere.t = CIwVec3(IW_FIXED(0.1), IW_FIXED(0.1), IW_FIXED(0.3));

    // initialise triangle
    s_Triangle.m_V0 = CIwVec3(0, 0, 0);
    s_Triangle.m_V1 = CIwVec3(0, IW_FIXED(-0.3), 0);
    s_Triangle.m_V2 = CIwVec3(IW_FIXED(-0.3), 0, 0);

    // setup bounding box:

    // bound the centre of the sphere
    s_BoundingBox.BoundVec(&s_Sphere.GetTrans());

    // bound the triangle
    s_BoundingBox.BoundVec(&s_Triangle.m_V0);
    s_BoundingBox.BoundVec(&s_Triangle.m_V1);
    s_BoundingBox.BoundVec(&s_Triangle.m_V2);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // start with no lighting
    IwGxLightingOff();

    // the IwGxDebugPrim* functions are used to render primitives in wireframe
    // (only available in debug builds)

    // when rendering we translate the view so that the primitives are visible:

    CIwMat view;

    // set to the identity rotation matrix with zero translation component
    view.SetIdentity();

    // set the translation vector of the matrix such that the primitives are visible
    view.t.z = IW_FIXED(-0.7);

    // set the view matrix
    IwGxSetViewMatrix(&view);

    // render the sphere
    IwGxDebugPrimSphere(s_Sphere, IwGxGetColFixed(IW_GX_COLOUR_BLUE));

    // render the triangle
    IwGxDebugPrimTri(s_Triangle.m_V0, s_Triangle.m_V1, s_Triangle.m_V2, IwGxGetColFixed(IW_GX_COLOUR_RED));

    // render the bounding box
    IwGxDebugPrimBBox(s_BoundingBox, IwGxGetColFixed(IW_GX_COLOUR_YELLOW));

    IwGxFlush();

    // swap buffers
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: Matrix Rotation Example

Airplay API Reference > IwGeom API Documentation > IwGeom Examples > Matrix Rotation Example >

Matrix Rotation Example

The following example demonstrates how to use the IwGeom Matrix functionality. The example renders a triangle and a bounding box, rotating the triangle.

The main classes used to achieve this are:

  • CIwVec3

  • CIwMat

  • CIwSphere

  • CIwBBox

The main functions used to achieve this are:

  • CIwSphere::SetRadius()

  • CIwBBox::BoundVec()

  • CIwVec3::Normalise()

  • CIwVec3::GetNormalised()

  • CIwVec3::operator - [binary minus]

  • CIwMat::SetIdentity()

  • CIwMat::SetAxisAngle()

  • CIwMat::RotateVec()

  • IwGxDebugPrimSphere()

  • IwGxDebugPrimTri()

  • IwGxDebugPrimBBox()

  • IwGxSetViewMatrix()

The example creates a triangle primitive and a bounding box. The example then sets the view matrix and renders the triangle and its bounding box using the IwGxDebugPrimSphere(), IwGxDebugPrimTri() and IwGxDebugPrimBBox() functions. For each render loop the triangle is rotated by a rotation matrix calculated by CIwMat::RotateVec(), and the bounding box is reconstructed to contain the rotated triangle.

Note:
For more information on using matrices, see the Matrix section in the IwGeom API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwGeom.h"

// for primitive rendering
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwDebugPrim.h"

//-----------------------------------------------------------------------------
struct Triangle
{
    // vertices
    CIwVec3 m_V0, m_V1, m_V2;
};
//-----------------------------------------------------------------------------

// primitives:

// 32-bit fixed point triangle
Triangle    s_Triangle;

// the angular speed of the triangle
#define TRIANGLE_ROT    0x40

// 32-bit fixed point bounding box
CIwBBox     s_BoundingBox(CIwVec3::g_Zero, CIwVec3::g_Zero);

//-----------------------------------------------------------------------------
// Bound the vertices of the triangle with the bounding box
void BoundTriangle()
{
    s_BoundingBox = CIwBBox(CIwVec3::g_Zero, CIwVec3::g_Zero);
    s_BoundingBox.BoundVec(&s_Triangle.m_V0);
    s_BoundingBox.BoundVec(&s_Triangle.m_V1);
    s_BoundingBox.BoundVec(&s_Triangle.m_V2);
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // initialise triangle
    s_Triangle.m_V0 = CIwVec3(0, 0, 0);
    s_Triangle.m_V1 = CIwVec3(0, IW_FIXED(-0.3), 0);
    s_Triangle.m_V2 = CIwVec3(IW_FIXED(-0.3), 0, 0);

    // bound the triangle with the bounding box
    BoundTriangle();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // (arbitrarily) rotate the triangle vertices:

    // define the rotation axis
    CIwVec3 rotationAxis(IW_FIXED(1), IW_FIXED(-1), 0);
    // ensure the axis is normal
    rotationAxis.Normalise();

    // create a rotation matrix, defined by rotationAxis and TRIANGLE_ROT:
    CIwMat rot;
    rot.SetAxisAngle(rotationAxis, TRIANGLE_ROT);

    s_Triangle.m_V0 = rot.RotateVec(s_Triangle.m_V0);
    s_Triangle.m_V1 = rot.RotateVec(s_Triangle.m_V1);
    s_Triangle.m_V2 = rot.RotateVec(s_Triangle.m_V2);

    // bound the triangle with the bounding box
    BoundTriangle();

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // start with no lighting
    IwGxLightingOff();

    // the IwGxDebugPrim* functions are used to render primitives in wireframe
    // (only available in debug builds)

    // when rendering we translate the view so that the primitives are visible:

    CIwMat view;

    // set to the identity rotation matrix with zero translation component
    view.SetIdentity();

    // set the translation vector of the matrix such that the primitives are visible
    view.t.z = IW_FIXED(-0.7);

    // set the view matrix
    IwGxSetViewMatrix(&view);

    // render the triangle
    IwGxDebugPrimTri(s_Triangle.m_V0, s_Triangle.m_V1, s_Triangle.m_V2, IwGxGetColFixed(IW_GX_COLOUR_RED));

    // render the bounding box
    IwGxDebugPrimBBox(s_BoundingBox, IwGxGetColFixed(IW_GX_COLOUR_YELLOW));

    IwGxFlush();

    // swap buffers
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: Vectors Example

Airplay API Reference > IwGeom API Documentation > IwGeom Examples > Vectors Example >

Vectors Example

The following example demonstrates how to use the IwGeom Types functionality. The example renders a rotating triangle and its normal. The colour of the triangle depends on the angle its normal makes with the eye.

The main classes used to achieve this are:

  • CIwVec3

  • CIwMat

  • CIwColour

The main functions used to achieve this are:

  • CIwVec3::Normalise()

  • CIwVec3::GetNormalised()

  • CIwVec3::operator +

  • CIwVec3::operator /(iwfixed) [scale]

  • CIwVec3::operator *(iwfixed) [scale]

  • CIwVec3::operator *(CIwVec3) [dot product]

  • CIwVec3::operator ^ [cross product]

  • CIwColour::Set()

  • CIwMat::SetIdentity()

  • CIwMat::SetAxisAngle()

  • CIwMat::RotateVec()

  • IwGxDebugPrimTri()

  • IwGxSetViewMatrix()

The example creates a triangle structure containing a number of CIwVec3 objects to hold the three points of the triangle as well as the triangle normal and the centre point. The structure is used to create the triangle and for every render loop the triangle is rotated and has its normal calculated.

Note:
For more information on the various types, see the Types section in the IwGeom API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwGeom.h"

// for primitive rendering
#include "IwGx.h"
#include "IwDebugPrim.h"

//-----------------------------------------------------------------------------
struct Triangle
{
    // vertices
    CIwVec3     m_V0, m_V1, m_V2;

    // normal of the triangle
    CIwSVec3    m_Normal;

    // centre of the triangle
    CIwVec3     m_Centre;

    CIwColour   m_Colour;
};
//-----------------------------------------------------------------------------

Triangle s_Triangle;

// the angular speed of the triangle
#define TRIANGLE_ROT    0x40

//-----------------------------------------------------------------------------
// calculate and set the normal, centre and colour of the triangle
void UpdateTriangle()
{
    // the normal of the triangle is the normal of the result of the cross
    // product of two of its edges (the order of the cross product determines
    // the orientation of the triangle)
    CIwVec3 edge1 = s_Triangle.m_V1 - s_Triangle.m_V0;
    CIwVec3 edge2 = s_Triangle.m_V2 - s_Triangle.m_V0;
    s_Triangle.m_Normal = (edge1 ^ edge2).GetNormalised();

    // the centre of the triangle is the average of the sum of its vertices
    s_Triangle.m_Centre = (s_Triangle.m_V0 + s_Triangle.m_V1 + s_Triangle.m_V2) / IW_FIXED(3);

    // viewVector is a normal vector pointing along the positive z axis
    CIwVec3 viewVector(0, 0, IW_GEOM_ONE);

    // calculate the dot product of the triangle normal and viewVector;
    // since both vectors are normal, the result will be the cosine of the
    // angle between them; the absolute value of this will be in the
    // interval [0,0x1000] and can be used to scale the red component of the triangle colour
    iwfixed dot = s_Triangle.m_Normal * viewVector;

    // set the triangle colour; note that the absolute value of the product of the dot product
    // and 255 must be shifted by IW_GEOM_POINT in order to give a result in [0,255]
    s_Triangle.m_Colour.Set(255 - (uint8)((abs(dot) * 255) >> IW_GEOM_POINT), 255, 255);
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // initialise triangle
    s_Triangle.m_V0 = CIwVec3(0, 0, 0);
    s_Triangle.m_V1 = CIwVec3(0, IW_FIXED(-0.3), 0);
    s_Triangle.m_V2 = CIwVec3(IW_FIXED(-0.3), 0, 0);

    UpdateTriangle();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // (arbitrarily) rotate the triangle vertices:

    // define the rotation axis
    CIwVec3 rotationAxis(IW_FIXED(1), IW_FIXED(-1), 0);
    // ensure the axis is normal
    rotationAxis.Normalise();

    // create a rotation matrix, defined by rotationAxis and TRIANGLE_ROT:
    CIwMat rot;
    rot.SetAxisAngle(rotationAxis, TRIANGLE_ROT);

    s_Triangle.m_V0 = rot.RotateVec(s_Triangle.m_V0);
    s_Triangle.m_V1 = rot.RotateVec(s_Triangle.m_V1);
    s_Triangle.m_V2 = rot.RotateVec(s_Triangle.m_V2);

    UpdateTriangle();

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // start with no lighting
    IwGxLightingOff();

    // the IwGxDebugPrim* functions are used to render primitives in wireframe
    // (only available in debug builds)

    // when rendering we translate the view so that the primitives are visible:

    CIwMat view;

    // set to the identity rotation matrix with zero translation component
    view.SetIdentity();

    // set the translation vector of the matrix such that the primitives are visible
    view.t.z = IW_FIXED(-0.7);

    // set the view matrix
    IwGxSetViewMatrix(&view);

    // render the triangle
    IwGxDebugPrimTri(s_Triangle.m_V0, s_Triangle.m_V1, s_Triangle.m_V2, s_Triangle.m_Colour);

    // render the triangle normal
    IwGxDebugPrimLine(s_Triangle.m_Centre, s_Triangle.m_Centre + (s_Triangle.m_Normal * IW_FIXED(0.1)));

    IwGxFlush();

    // swap buffers
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: Ray Picking Example

Airplay API Reference > IwGeom API Documentation > IwGeom Examples > Ray Picking Example >

Ray Picking Example

The following example demonstrates how to use the IwGeom primitives to intersect with a ray from the camera into the frustrum passing though a given pixel position.

The example renders a number of 3D spheres which will change colour when the pointer moves over them.

The main classes used to achieve this are:

  • CIwVec3

  • CIwSphere

  • CIwMat

The main functions used to achieve this are:

  • CIwVec3::Normalise()

  • CIwVec3::operator +

  • CIwVec3::operator *(iwfixed) [scale]

  • CIwVec3::operator *(CIwVec3) [dot product]

  • CIwVec3::operator ^ [cross product]

  • CIwMat::SetIdentity()

  • CIwMat::RotateVec()

  • IwIntersectLineSphere()

  • IwGxSetViewMatrix()

The example creates a number of randomly placed spheres and allows the user to change their colour by moving the cursor over them.

The main principle being demonstrated here is the creation of a world-space ray which passes down the pixel currently under the cursor.

The origin of this ray is the camera position.

The direction of the ray is towards a point at the current x/y cursor position offset relative to the centre of the screen and on the view plane.

The view plane (at perspmul z) is the plane where the cross-section of the frustrum has the same dimensions as the screen (in pixels).

The direction is then rotated by the camera's transformation matrix.

The generated ray can be used with any of IwGeom's intersection functions.

Note:
For more information on the various types, see the Types section in the IwGeom API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwGeom.h"

// for primitive rendering
#include "IwGx.h"
#include "IwDebugPrim.h"
#include "s3ePointer.h"

//-----------------------------------------------------------------------------

// Spheres to use
#define NUMBER_SPHERES (10)
CIwSphere s_Spheres[NUMBER_SPHERES];

// The index of the currently selected sphere
int32 s_SelectedSphere = -1;

// The view matrix
CIwMat s_ViewMatrix;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise GX
    IwGxInit();

    // Generate spheres
    for(uint32 i = 0; i < NUMBER_SPHERES; i++)
    {
        CIwVec3 pos;
        pos.x = IwRand() % 1000;
        pos.y = IwRand() % 1000;
        pos.z = IwRand() % 1000;

        iwfixed radius = IwRand() % 100;

        s_Spheres[i] = CIwSphere(pos, radius);
    }

    // Set to the identity rotation matrix with zero translation component
    s_ViewMatrix.SetIdentity();

    // Set the translation vector of the matrix such that the spheres are visible
    s_ViewMatrix.t.x = 500;
    s_ViewMatrix.t.y = 700;
    s_ViewMatrix.t.z = -500;
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Select "no sphere"
    s_SelectedSphere = -1;

    // Generate a ray pointing to the view plane from the camera
    CIwVec3 dir(s3ePointerGetX() - IwGxGetScreenWidth()/2,
        s3ePointerGetY() - IwGxGetScreenHeight()/2,
        IwGxGetPerspMul());

    // Rotate into camera space
    dir = s_ViewMatrix.RotateVec(dir);

    // Normalise
    dir.Normalise();

    for(uint32 i = 0; i < NUMBER_SPHERES; i++)
    {
        // Test each sphere for intersection
        if( IwIntersectLineSphere(s_ViewMatrix.t, dir, s_Spheres[i]) )
        {
            //If this sphere intersects, set it as selected.
            s_SelectedSphere = i;
        }
    }

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    // Set the view matrix
    IwGxSetViewMatrix(&s_ViewMatrix);

    for(int32 i = 0; i < NUMBER_SPHERES; i++)
    {
        // The IwGxDebugPrim* functions are used to render primitives in wireframe
        if( i == s_SelectedSphere )
            IwGxDebugPrimSphere(s_Spheres[i], g_IwGxColours[IW_GX_COLOUR_RED]);
        else
            IwGxDebugPrimSphere(s_Spheres[i], g_IwGxColours[IW_GX_COLOUR_BLUE]);
    }

    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: IwGx API Documentation

Airplay API Reference > IwGx API Documentation >

IwGx API Documentation

The IwGx documentation contains the following sections:

  • IwGx API Overview
  • IwGx API Reference
  • IwGx Examples


Airplay API Reference: IwGx API Overview

Airplay API Reference > IwGx API Documentation > IwGx API Overview >

IwGx API Overview

IwGx is a stream-based API for 2D and 3D drawing, which provides abstraction from the underlying low-level renderer. The renderer may be the Airplay software renderer, OpenGL ES, or a rendering API for a proprietary platform, such as a handheld games console.

To use IwGx functionality, you must include "IwGx.h" in your source and iwgx as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwgx
  • }

When using IwGx, the following modules do not need to be specified in your project's MKB as they will be implicitly included as subprojects of this module:

  • IwUtil
  • IwGeom
  • IwResManager

IwGx is based around geometry streams, transform state, lighting state, textures and materials (similar to OpenGL or DirectX).

Geometry streams are fed into IwGx to construct each object in a scene. IwGx handles the transformation of each object as well as the supply of colour, texture and lighting information. It also handles the rasterisation of the derived view to the screen.

It is possible to draw to the device display using only the S3E interface, and without ever initialising IwGx. However, you would be limited to copying memory direct to the underlying surface, or low-level usage of the OpenGL ES API. You would also have to re-write your entire application engine rendering pipeline for each underlying low-level renderer; e.g. OpenGL ES, each handheld games console, etc.

All drawing within Airplay Studio uses the IwGx API.

The following sections are covered in this chapter:

  • IwGx Initialisation and Pipeline
  • IwGx State
  • Selective Linking
  • Drawing Primitives
  • Material
  • Texture
  • Streams
  • Colour
  • Transform
  • Lighting
  • Rasterisation
  • Using IwGx with OpenGL ES
  • Using IwGx with OpenGL ES 2.x
  • Data Cache
  • Screen Manipulation
  • Clipping
  • Z-depth
  • IwGx Metrics
  • Debug Drawing
  • Miscellaneous


Airplay API Reference: IwGx Initialisation and Pipeline

Airplay API Reference > IwGx API Documentation > IwGx API Overview > IwGx Initialisation and Pipeline >

IwGx Initialisation and Pipeline

IwGx as follows:

  • // Begin application

  • IwGxInit();

    ...rest of application

  • // End application

  • IwGxTerminate();

If using IwGx, the user does not need to initialise or terminate IwUtil or IwGeom, as this is done automatically by IwGxInit() and IwGxTerminate()

The IwGx "pipeline" consists of three stages; transform, lighting (TnL) and rasterisation. Each of these stages is initialised separately, and each stage can support a pure software (SW) and a hardware-accelerated (HW) code path. Moreover, each stage can be switched between the SW and HW code path at runtime. In this way, a single version of the application can be deployed to all devices, and the IwGx pipeline can be configured (usually at application start-up) optimally for that device. So if the device has some sort of graphics acceleration (e.g. a GPU) then the rasterisation stage would almost certainly be switched to HW. The transform and lighting stages might remain switched to SW, depending on the efficiency of the device's graphics drivers.

When IwGxInit() is called, IwGx will initialise pipelines appropriate for the device. For example, on a GLES 1.x capable device rasterisation will initialise to the HW pipeline while on a non-HW accelerated device the rasteriser will initialise to SW. Note that SW rasterising typically requires many IwGx parameters to be fine-tuned, so errors may be produced if an application has not been tested in SW previously.

The ICF can be used to restrict or extend the modes available. Effectively, the default settings are:

  • [GX]

  • Rasterisation=HW

  • Transform=SW

  • Lighting=SW

This means use HW rasterisation if available (SW rasterisation is implicitly supported) but transform and light vertices in SW. SW TnL allows IwGx the greatest freedom to optimise driver access, so these settings are usually best on current devices.

To test the SW renderer, the following settings would be used:

  • [GX]

  • Rasterisation=SW

IwGx also supports TnL in HW where available. This support must be explicitly enabled. HW TnL can be significantly faster on some hardware architectures (e.g. IwGx can use VBOs to eliminate data transfers), but features which require transformed vertices will not be available - these include geometry merging, early clipping and early culling. Some IwGx parameters (like DataCacheSize) may need fine tuning to run in both SW and HW TnL modes. For example:

  • [GX]

  • Transform=SW

  • Lighting=SW/HW

  • Rasterisation=HW

Now, the lighting stage will support both SW and HW.

In the Windows Simulator, the pipeline specified first will be the default.

In this case lighting will default to SW but at any point after calling IwGxInit(), we are free to switch the lighting stage to HW by calling:

  • IwGxSetLightingHW();

Now, all lighting calculations will happen through calls to the OpenGL ES drivers. If we had set "Lighting=HW/SW", the stage would have by default been switched to HW.

On device, IwGx will decide which pipeline is most appropriate at startup. The application can use IwGxSetLightingHW etc. or per-device icf settings to override IwGx's choice.

Applications can also mix SW and HW pipelines within one frame if required. This can be useful if IwGx's geometry merging functionality is required for some elements (for example, the gui) while other parts of the scene are in a more optimal GLES format. An implicit flush will accompany each pipeline switch.

Furthermore, we can also initialise IwGx to support both SW and HW rasterisation. This is typically used for development purposes, when we want to check parity between a build of an application using the Airplay software renderer and a build using OpenGL ES. We can initialise IwGx to support both by using the settings:

  • [GX]

  • Rasterisation=SW/HW

Here, we have initialised the rasterisation stage to support both SW and HW, and to start in SW. Initialising the rasterisation stage to support HW will also automatically initialise the transform and lighting stages to support HW. So we have now initialised IwGx to allow us to switch each stage between SW and HW at will. For example, you can switch rasterisation to HW as follows:

  • IwGxSetRasterisationHW();

You can then switch transform to HW as follows:

  • IwGxSetTransformSW();

You can then switch rasterisation back to SW as follows:

  • IwGxSetRasterisationSW();

Note: When rasterisation is switched to SW, transform and lighting are both automatically switched to SW. (It makes no sense to have hardware-accelerated transform or lighting with software rasterisation - there would be no way of getting the transformed data back from the GPU to feed the software rasteriser).

This degree of flexibility within the pipeline is necessary to achieve maximum performance across the widest possible range of devices. For any device with no hardware graphics acceleration, we would switch all stages to SW. For a device with simple DSP-accelerated graphics, and poor drivers, we would switch rasterisation to HW, but leave transform and lighting in SW. For a device with a current-generation mobile GPU, we would additionally switch transform to HW, but still leave lighting in SW - the OpenGL ES drivers for such chip sets will still implement all GL lighting calls in SW, and we can do the job ourselves more optimally. For next-generation mobile GPUs, it is expected that we would switch all stages to HW.

IwGxInit() implicitly initialises IwUtil and IwGeom, and creates the CIwGxState object. IwGxTerminate() implicitly terminates IwUtil and IwGeom, and destroys the CIwGxState object. It is illegal to call any IwGx function or create any IwGx class before calling IwGxInit().


Airplay API Reference: IwGx State

Airplay API Reference > IwGx API Documentation > IwGx API Overview > IwGx State >

IwGx State

The entire IwGx state is contained within the IwGxState object. This object is hidden from the user. Documentation refers to this object when it is useful for the user to know that information is being copied to or from it.

This state object includes information on screen size, screen orientation, model transform, view transform, vertex cache, colour cache, frustrum description, scene lights, etc.

IwGx API calls are used to write to and read from the state.


Airplay API Reference: Selective Linking

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Selective Linking >

Selective Linking

IwGx can be initialised in a number of different configurations to help the linker eliminate unused code. Instead of calling IwGxInit(), which includes all of IwGx's functionality within your code, you can call IwGxInit_Base(), which will allow you to include a subset of that functionality. You can see the code reduce in size if you remove any of the IwGxInit calls following IwGxInit_Base.

The IwGxInit_Base() function can be called followed by an instantiation of the required renderer type. It is by including only the required renderer type that you can reduce the code size. It is also possible to choose whether environment mapping or RGB lighting is available with the selected renderer, therefore further optimising your code.

There are three renderer types that can be used, and each of these types also have a number variants:

  • The Standard Renderer:
    • The Standard Renderer with all features.
    • The Standard Renderer with no environment mapping.
    • The Standard Renderer with no RGB lighting.
    • The Standard Renderer with no environment mapping or RGB lighting.
  • The Scanline Renderer:
    • The Scanline Renderer with all features.
    • The Scanline Renderer with no environment mapping.
    • The Scanline Renderer with no RGB lighting.
    • The Scanline Renderer with no environment mapping or RGB lighting.
  • The Open GL ES 1.x Renderer:
    • The Open GL ES 1.x Renderer including software transform and lighting pipeline.
    • The Open GL ES 1.x Renderer with no software pipeline.
  • The Open GL ES 2.x Renderer:
    • The Open GL ES 2.x Renderer including software transform and lighting pipeline.
    • The Open GL ES 2.x Renderer with no software pipeline.

Both the Standard Renderer and the Scanline Renderer can be instantiated with environment mapping disabled, RGB Lighting disabled, or both disabled. The GL renderer can be instantiated so that it will not use the software pipeline, i.e., it will use hardware for all transform, lighting, and rasterisation operations.

To reduce your code by the largest amount it is recommended that you instantiate only one of the renderers. It might, however, be of advantage to instantiate the GL renderer with the chosen software renderer.

Note: If you are instantiating the GL renderer along with one of the software renderers, you must instantiate the GL renderer Last.

The following piece of code illustrates how you might instantiate a renderer.

  • IwGxInit_Base();
  • //optionally run in the scanline renderer based on an icf parameter
  • int useScanLineRend = 0;
  • s3eConfigGetInt("GX", "UseScanLineSWRenderer", &useScanLineRend);
  • if(useScanLineRend)
  • {
    • IwGxInit_SWRenderScanLine();
  • }
  • else
  • {
    • IwGxInit_SWRenderStandard();
  • }
  • IwGxInit_GLRender();


Airplay API Reference: Drawing Primitives

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Drawing Primitives >

Drawing Primitives

Each object rendered by IwGx is created in three stages:

  • Set the geometry streams.
  • Set the material for the geometry.
  • Draw the primitives.

The basics of drawing primitives are covered in more detail in the following sections:

  • Drawing a Polygon
  • Drawing Modes


Airplay API Reference: Drawing a Polygon

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Drawing Primitives > Drawing a Polygon >

Drawing a Polygon

The geometry for any object is entered as a vertex stream. IwGx Polgon Display Example demonstrates how you can use IwGx to draw a polygon to the screen. In the ExampleRender section of our example application, three points of type CIwSVec2 are entered as an array and passed using a pointer to the IwGxSetVertStreamScreenSpace() function. The IwGxSetVertStreamScreenSpace() function allows you to specify two dimensional coordinates directly in screen space.

Before a polygon can be drawn, it must have a material set on it. A material is initialised using the CIwMaterial::Init() function. The material set using the IwGxSetMaterial() function is used for any drawing until another material is set using the same function.

Note: For more information on material options, see the CIwMaterial class documented in the IwGx API Reference.

The next step is to draw the polygon. This is achieved using the IwGxDrawPrims() function. IwGxDrawPrims() combines the material and the vertex stream with a drawing mode and an index stream to produce a rendered surface.

  • // Draw the primitives, specifying draw mode.
  • IwGxDrawPrims(IW_GX_TRI_LIST, NULL, 3);

If an index stream is not supplied, as is the case with our example, then a default stream of 0, 1, 2, 3.... is used.

Note: For more information on how to draw to screen, see the Streams and Rasterisation sections.


Airplay API Reference: Drawing Modes

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Drawing Primitives > Drawing Modes >

Drawing Modes

Imagine we are looking down the camera, at our geometry: positive x is right, positive y is down, positive z is into the screen. The diagrams below show how to define polys which are visible when using back-face culling.

The use of indexing with drawing allows you to specify an objects geometry without the need to repeat any points in the vertex stream. The indexing conventions for each of the drawing modes is outlined in the drawing mode description. An index stream should be entered as an array of uint16s.

IW_GX_TRI_LIST

The number of drawn triangles is ni (number of indices) / 3.

  • 0---2 3---5
  • | / | /
  • | / | /
  • |/ |/
  • 1 4

Indexing IW_GX_TRI_LIST

The number of indices (ni) must be a multiple of three. Each group of three indices specifies a tri.

IW_GX_TRI_STRIP

The number of drawn tris is ni - 2.

  • 0---2---4
  • | /| /|
  • | / | / |
  • |/ |/ |
  • 1---3---5

Indexing IW_GX_TRI_STRIP

The number of indices (ni) must be greater than two. The first three indices specifies the first tri, then each successive index specifies a new tri (together with the previous two indices). Winding order is automatically reversed for every other tri.

IW_GX_QUAD_LIST

Number of drawn quads is (ni / 4).

  • 0---3 4---7
  • | | | |
  • | | | |
  • | | | |
  • 1---2 5---6

Indexing IW_GX_QUAD_LIST

The number of indices (ni) must be a multiple of four. Each group of four indices specifies a quad.

IW_GX_QUAD_STRIP

The number of drawn quads is ((ni + 2) / 2).

  • 0---2---4---6
  • | | | |
  • | | | |
  • | | | |
  • 1---3---5---7

Indexing IW_GX_QUAD_STRIP

The number of indices (ni) must be greater than three, and a multiple of two. First four indices specifies first quad, then each successive index pair specifies a new quad (together with the previous two indices).

IW_GX_TRI_FAN

The number of drawn tris is ni -2.

  • 3---4---5
  • |\ | /|
  • | \ | / |
  • | \|/ |
  • 2---1---6

Indexing IW_GX_TRI_FAN

The number of indices (ni) must be greater than two. The first three indices specifies first tri, then each successive index specifies a new tri (together with the previous index and the first index).

IW_GX_LINE_LIST

This mode draws lines. The number of drawn lines is ni / 2.

  • 0 3 3--4 4
  • | | |
  • | | |
  • | | |
  • 1 1--2 2 5

Indexing IW_GX_LINE_LIST

The number of indices (ni) must be greater than two. Each set of two indices specifies a new line.

IW_GX_LINE_STRIP

This mode draws lines. The number of drawn lines is ni - 1.

  • 0 3---4
  • | | |
  • | | |
  • | | |
  • 1---2 5

Indexing IW_GX_LINE_STRIP

The number of indices (ni) must be greater than two. Each index, together with the previous index, specifies a new line.

IW_GX_SPRITE_LIST

The number of drawn sprites is ni. A sprite is a camera facing quad with one pixel per texel. Sprites are the fastest primitive for the Airplay software renderer.

  • 0---* 1---*
  • | | | |
  • | | | |
  • | | | |
  • *---* *---*

Indexing IW_GX_SPRITE_LIST

A sprite is emitted with a top-left corner for each index from the vertex stream. The UV stream should be twice the length of the vertex stream and is indexed as pairs of UV coordinates, with a pair of UV coordinates for each vertex. The size of each sprite is determined by the pair of UV coordinates - with exactly one pixel per texel.

IW_GX_NPOLY_LIST

An N-Poly is a surface defined by a maximum of 63 points. The n-poly is the Airplay software renderer's native primitive, so n-polys are somewhat more efficient. N-polys are best avoided for hardware renderers because they require these polys to be triangulated.

  • 0---1 6---7
  • | \ / \
  • | 2 11 8
  • | / \ /
  • 5 4---3 10--9

Indexing IW_GX_NPOLY_LIST

Each index adds a point to the current n-poly. A poly is terminated if the same index is encountered twice.

Note: For more information on using the various drawing modes, see the IwGx Drawing Modes Example


Airplay API Reference: Material

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material >

Material

IwGx does not allow the user to change each individual render state or texture state at will. Instead, it wraps up the entire rendering state within a single material class called CIwMaterial.

The material class contains details of shading mode, modulation mode, alpha blending mode, textures to set on available texture stages, emissive, ambient and diffuse colour responses, etc. Each time you set a new material to draw with, you are in effect defining the entire rendering state.

For example:

  • CIwMaterial* pMat = new CIwMaterial;
  • pMat->SetShadeMode(CIwMaterial::SHADE_FLAT);
  • pMat->SetAlphaMode(CIwMaterial::ALPHA_ADD);
  • pMat->SetTexture(myTexture);
  • IwGxSetMaterial(pMat);

This code creates a material, sets it to be flat shaded and use pure additive alpha blending, and sets a texture for the material (on the default first texture stage).

When we call IwGxSetMaterial(), we are specifying that all future drawing should use this material (until we change it). Internally, IwGxSetMaterial() copies data from the material object onto the IwGxState.

Once a material has been used within a scene (i.e., some geometry has been drawn using that material), it is illegal to modify certain members of the material. For example, it is illegal to modify the texture stages. This is because IwGx supports a mode whereby all geometry is sorted by material before being submitted for drawing - this mode can be the most efficient for some GPUs. Obviously it makes no sense to sort a scene by material if the material is not constant across the scene.

However, some members of the material object are not affected by the sorting process. For example, the emissive, ambient and diffuse colours are used by the lighting stage, but do not have an impact on the rasterisation stage. Also, it can be useful to have multiple instances of geometry use the same material but with different colours (for example, several fireball models glowing at different rates). For this reason, it is permitted to modify certain members of the IwGxState after calling IwGxSetMaterial() and before drawing. Recall that IwGxSetMaterial() copies data from the material object onto the IwGxState, and consider the following:

  • IwGxSetMaterial(pMat);
  • ...now draw some geometry
  • // Use the same material, but change the IwGxState emissive colour
  • IwGxSetColEmissive(myColour0);
  • ...now draw some geometry
  • // Use the same material, but change the IwGxState emissive colour
  • IwGxSetColEmissive(myColour1);
  • ...now draw some geometry

In this case, all three pieces of geometry will be grouped under the same material, but will use different colour settings.

Materials are often loaded indirectly through the resource manager. For more information on the resource manager, see the IwResManager documentation.

Note: For an example of how the different alpha modes are used, see the IwGx Texture Examples. For an example of how to use material colours, see the IwGx Lighting Examples (see also "Lighting"). For an example of how UV animation can be performed, see the IwGx UV Animation Example.

The main components of the material object are as follows:

  • Material Shade Mode
  • Material Cull Mode
  • Material Modulation Mode
  • Material Alpha Mode
  • Material Blend Mode
  • Material Colours
  • Material Textures
  • Material UV Animation
  • Template Material

Note: See the CIwMaterial class documentation for an exhaustive list of methods.


Airplay API Reference: Material Shade Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Shade Mode >

Material Shade Mode

A material can be either flat-shaded or gouraud-shaded. Flat-shaded materials result in a single colour being applied to each triangle. Gouraud-shaded materials result in vertex colours being interpolated across the triangle. For example, set a flat-shaded material as follows:

  • pMaterial->SetShadeMode(CIwMaterial::SHADE_FLAT);


Airplay API Reference: Material Cull Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Cull Mode >

Material Cull Mode

A material can be either single-sided or double-sided. If single-sided, the material can be set to back-face cull clockwise-ordered polygons, or to back-face cull anti-clockwise-ordered polygons. For example, set a double-sided material as follows:

  • pMaterial->SetCullMode(CIwMaterial::CULL_NONE);


Airplay API Reference: Material Modulation Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Modulation Mode >

Material Modulation Mode

If a material is textured, we can determine how the texture (texel) colour is modified by the vertex colour(s) to determine the "source" colour for writing to the backbuffer.

MODULATE_RGB

The standard way to do this is to perform a component-wise multiplication of the interpolated vertex colour by the texel colour, as follows:

  • Rsource = Rtexel * R colour
  • Gsource = Gtexel * G colour
  • Bsource = Btexel * B colour
  • Asource = Atexel * A colour

We can set this modulation mode on a material as follows:

  • pMaterial->SetModulateMode(CIwMaterial::MODULATE_RGB);

MODULATE_R

However, the Airplay software renderer can perform much faster rendering if we choose to modulate all components by a single value, as follows:

  • Rsource = Rtexel * R colour
  • Gsource = Gtexel * R colour
  • Bsource = Btexel * R colour
  • Asource = Atexel * R colour

Using this mode, we can only achieve "white lighting" on the texture; i.e. we are always modulating the texel value by a greyscale value.

We can set this modulation mode on a material as follows:

  • pMaterial->SetModulateMode(CIwMaterial::MODULATE_R);

Note: The Template Material modulation mode defaults to this setting.

MODULATE_NONE

The final modulation mode is one whereby the texel value is never modified; i.e. any vertex colours are ignored. This is often the desired appearance of items such as UI elements, backgrounds, etc. Setting this modulation mode will ensure that the Airplay software renderer performs as little work as possible when processing the associated polygons.

We can set this modulation mode on a material as follows:

  • pMaterial->SetModulateMode(CIwMaterial::MODULATE_NONE);


Airplay API Reference: Material Alpha Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Alpha Mode >

Material Alpha Mode

All materials are either opaque or transparent. Opaque materials write their "source" pixels directly to the backbuffer. Transparent materials consider the backbuffer (the "destination"), and write some combination of the "source" and "destination" values to the backbuffer.

When discussing materials, we refer to transparency as "alpha". We set a material as opaque as follows:

  • pMaterial->SetAlphaMode(CIwMaterial::ALPHA_NONE);

Four other alpha modes exist. We describe their effects below, where "back" refers to the value written to the backbuffer, "source" refers to the value as calculated by the modulation stage, and "dest" refers to the existing value in the backbuffer. Note that the calculated values are always clamped to the valid range.

ALPHA_HALF

  • Rback = (Rsource + Rdest) / 2
  • Gback = (Gsource + Rdest) / 2
  • Bback = (Bsource + Rdest) / 2
  • Aback = (Asource + Rdest) / 2

ALPHA_ADD

  • Rback = Rsource + Rdest
  • Gback = Gsource + Rdest
  • Bback = Bsource + Rdest
  • Aback = Asource + Rdest

ALPHA_SUB

  • Rback = Rsource - Rdest
  • Gback = Gsource - Rdest
  • Bback = Bsource - Rdest
  • Aback = Asource - Rdest

ALPHA_BLEND

  • Rback = (Rsource * Ralpha) + (Rdest * (1 - Ralpha))
  • Gback = (Gsource * Galpha) + (Rdest * (1 - Galpha))
  • Bback = (Bsource * Balpha) + (Rdest * (1 - Balpha))
  • Aback = (Asource * Aalpha) + (Rdest * (1 - Aalpha))


Airplay API Reference: Material Blend Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Blend Mode >

Material Blend Mode

For materials which have two textures (i.e., textures on stages 0 and 1), we can determine how the two textures are combined before being used as the "source" colour.

Note: Material blend mode is only ever used when rasterising using OpenGL ES.


Airplay API Reference: Material Colours

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Colours >

Material Colours

Each material has an emissive, ambient and diffuse colour. Actually, the ambient and diffuse value are better thought of as "colour responses", as they are generally modulated by scene light colours. Each of the material colours can be modified by the user.

Note: See Lighting: The Lighting Model for a complete description of how material colours and scene lights are used to calculate vertex colours.


Airplay API Reference: Material Textures

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material Textures >

Material Textures

Each material has a number of texture stages. Different rasterisers support different numbers of textures, and they will ignore any extra textures beyond that number.

The Airplay software renderer supports only stage 0.

OpenGL ES 1.x supports Stage 0 and Stage 1

OpenGL ES 2.x supports Stages 0,1,2 and 3

For this reason it is best to use the stages for the following uses:

  • Stage 0 as the "diffuse map" which gives the basic textured appearance to the object.
  • Stage 1 as the "effect map" for input to IwGx's effect presets and blending modes (normal maps, reflection maps, etc.)
  • Stages 2+ as custom shader input

The user can set the textures on each stage, and query the textures on each stage.

Note: IwGx will ignore textures in later stages if the lower one is not set. For example, if only texture stage 1 is set, no textures will be used. If a material is textured, then we must submit a UV stream for Stage 0 before attempting to draw any polygons using the material. If no UV stream is specified for Stage 1 the UV stream for Stage 0 will be used.

See the CIwMaterial API documentation for more details.


Airplay API Reference: Material UV Animation

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Material UV Animation >

Material UV Animation

A textured material can automatically animate the UV coordinates of any polygons drawn. This is often a very "cheap" way of achieving some animation in a scene. UV animation can be used to achieve both "flipbook" style cel animation effects and UV-scrolling effects.

UV animation can be specified within the text-file description of a CIwMaterial - for example, an MTL file. See the CIwMaterial API documentation for a complete list of the relevant text-file attributes.

The easiest way to explain how UV animation works is to describe how the user might set up the animation in code. There are two types of animation described in this section: cel animation and scroll animation.

Cel Animation

For example, say we have a "flipbook" or cel style animation, consisting of 16 "cels", each cel being 32x32 pixels, arranged in a 4x4 fashion within a single texture of size 128x128 pixels as illustrated below".

Key:

  • A - Cell width.
  • B - Cell height
  • C - Anim Cell Num Across
  • D - Path of animation.
  • Blue Square - Representation of the cell.

We would set up the animation as follows:

  • // First, set the texture to use
  • pMaterial->SetTexture(pTexture);
  • // Enable UV animation on the material
  • pMaterial->CreateAnim();
  • // Set the width of a single cel. The system assumes that
  • // cells will span the entire width of the texture
  • pMaterial->SetAnimCelW(32);
  • // Set the height of a single cel. The system assumes that
  • // cels will span the entire height of the texture
  • pMaterial->SetAnimCelH(32);

This is all that is required to set up a UV animation. By default, the system assumes that the total number of cels in the animation is equal to (number of cels across texture) * (number of cels down texture).

In this case, the artist generally would ensure that only the top-left portion of the texture is mapped to the polygons. At each call to IwGxFlush(), a UV offset is calculated for the material. When drawing with the material, this offset is then applied to the current UV stream.

Before drawing, a vertex stream must still be supplied to indicate the starting point for an animation using IwGxSetUVStream().

Scroll Animation

This is very similar to the Cell Animation example, except that the settings ensure that the UVs scroll evenly across the texture.

Key:

  • A - Anim Cell Width
  • B - Anim Cell Height
  • C - Anim Cell Num Across
  • D - Anim Cell Num
  • Blue Square - Representation of the Cell.

The example above shows the texture sheet of a glow effect. To simulate a glow, this texture is animated so that a small area of UVs are scrolled across it, repeating when it gets to the end. Unlike the previous example of Cell Animation, C and D will be the same, so that A is moved along after each delay of E. The UV animation will repeat from the start and not use B.

We could set up a UV animation to scroll in across the glow by 1 pixel per frame, as follows:

  • pMaterial->CreateAnim();
  • pMaterial->SetAnimCelH(1);

In this case, the system assumes that , at each call to IwGxFlush(), we should increase the U offset by 0 (as we have not set the "cel width"), and we should increase the V offset by 1. Because textures wrap by default in both U and V directions, this will have the effect of "scrolling" the glow texture horizontally across the polygons.

Before drawing, a vertex stream must still be supplied to indicate the starting point for an animation using IwGxSetUVStream().

Note: "cel width" is simply the U offset which will be applied at each call to IwGxFlush(). Once a complete "row" of cels has been traversed, we reset the U offset, and apply the V offset ("cel height").

For an example of how UV Animation is used in practice, see the IwGx UV Animation Example in the 'Getting Started with IwGx' section.


Airplay API Reference: Template Material

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Material > Template Material >

Template Material

IwGx maintains a single global material, called the "template material". Whenever a CIwMaterial object is constructed, it is set up to be identical to the template material.

A pointer to the template material is returned by IwGxGetMaterialTemplate(), and the material can be modified by the user. In this way, the user can determine the "default" setting of all materials constructed within the application. Note that this also applies to material objects loaded from text files, serialised from binary files, or constructed on the IwGx Data Cache (for example, using IW_GX_ALLOC_MATERIAL()).

This is very useful, as different applications may have different requirements for what they consider a "default" material. Should the default modulation mode be MODULATE_R or MODULATE_RGB? What should the default material colours be?

The default setting of the template material is equivalent to the following:

  • SetShadeMode(SHADE_GOURAUD);
  • SetModulateMode(MODULATE_RGB);
  • SetCullMode(CULL_BACK);
  • SetAlphaMode(ALPHA_NONE);
  • SetBlendMode(BLEND_MODULATE);
  • SetFiltering(false);
  • SetColEmissive(0);
  • SetColAmbient(0xff808080);
  • SetColDiffuse(0);

Then, for example, consider the following:

  • CIwMaterial* pMat0 = new CIwMaterial;
  • // pMat0 has modulate mode of MODULATE_RGB
  • IwGxGetMaterialTemplate()->SetModulateMode(CIwMaterial::MODULATE_R);
  • CIwMaterial* pMat1 = new CIwMaterial;
  • // pMat1 has modulate mode of MODULATE_R

Materials in material resource templates will get their default values when they instantiated.


Airplay API Reference: Texture

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Texture >

Texture

IwGx supports both palettised and unpalettised textures. At source, the image may be of type BMP, GIF, PNG or TGA, in any of the formats supported by CIwImage. When loaded from disk, the image will be converted into a suitable format for the underlying low-level renderer, for example, the Airplay software renderer or OpenGL ES.

The Airplay software renderer supports only the following texture formats internally:

  • 4-bit (16 colour) palettised textures, palette format ABGR_1555.
  • 8-bit (256 colour) palettised textures, palette format ABGR_1555.
  • 16-bit unpalettised textures, texel format ABGR_1555.
  • 4-bit (16 colour) palettised textures, palette format ABGR_4444.
  • 16-bit unpalettised textures, texel format ABGR_4444.
  • 16-bit unpalettised textures, texel format RGB_565.
  • 32-bit unpalettised textures, texel format ARGB_8888.

All ABGR_1555 (and RGB_565) formats support 1-bit alpha, or "chromakey". Chromakeying is supported through the use of a custom colour in the image, namely pure magenta, or (r,g,b)=(255,0,255). Any image pixel of this colour will become transparent in the texture.

Maximum texture size varies across target devices, and large textures sometimes carry a penalty. For best results across the largest number of target devices textures should be kept 256x256 or smaller. In SW, the size of a texture affects how often it can be tiled. The absolute maximum size is 2048x2048 for SW, and implementation defined for OpenGL ES (the standard guarantees at least 64 - in practice, 1024 is the normal lower limit).

Non-power-of-2 textures are supported in all renderers with some caveats, mainly that tiling (i.e. UVs outsize 0...1) is not supported. Additionally, in OpenGL ES 1.x, images may appear clipped due to lack of precision in the texture matrix.

Textures are usually loaded indirectly through the resource manager. For more information on loading using the Resource Manager, see the IwResManager API Documentation. A texture can be loaded explicitly as follows:

  • CIwTexture* pTex = new CIwTexture;
  • pTex->LoadFromFile("test.bmp");
  • pTex->Upload();

Note: For examples of how to use textures, see the IwGx Texture Examples. Before calling Upload(), the texture image data is in the same format as the image on disk. During Upload(), if SW rasterisation is supported, the image data will be converted to the appropriate format for the Airplay software renderer, if HW rasterisation is supported, the image data will be converted to the appropriate format for any underlying graphics hardware. After upload, it is important to distinguish between the three potential image formats, as follows:

  • pTex->Upload();
  • // Get the format of the original image on disk
  • CIwImage::Format fDisk = pTex->GetFormat();
  • // Get the format of image uploaded to the SW rasterizer
  • CIwImage::Format fSW = pTex->GetFormatSW();
  • // Get the format of image uploaded to the HW rasterizer
  • CIwImage::Format fHW = pTex->GetFormatHW();

After upload, the original texel and palette data will no longer be available, unless the user has explicitly requested for it to remain in client-side memory. Methods such as CIwTexture::ChangePalette() can only be called if the texture has retained its texels and palette in client-side memory. To enable this, the user must call CIwTexture::MakeModifiable(true), prior to calling CIwTexture::Upload().

Two wrapping modes are supported for UV coordinates outside the range [0,1] - "wrapping" and "clamping". The default is "wrapping"; a texture can wrap up to 16 times, and UV coordinates in the range [-8,8] are supported (note that UV coordinates are always supplied in 1.3.12 fixed-point format, so what we are saying is that the full range of this format provides for the equivalent floating-point range [-8,8]). "Clamping" mode can be set with CIwTexture::SetClamping(true). Currently this mode is only supported for OpenGL ES rasterisation.

Two filtering modes are supported - "none" and "bilinear". The default is "bilinear". Bilinear filtering can be turned off with CIwTexture::SetFiltering(false). Currently bilinear filtering is only supported for OpenGL ES rasterisation.

Mipmaps are, by default, generated automatically for all textures. Mipmaps can be turned off with CIwTexture::SetMipMapping(false).

Using hardware texture compression

Most hardware accelerated devices support some kind of hardware texture compression. It is recommended that applications use texture compression where available for the memory and performance gains. This will typically involve maintaining multiple asset sets.

A texture can be compressed by setting its formatHW to a compressed format. Note that compression occurs when the texture is serialised out (compression is typically cpu and memory intensive), so textures must be serialised in order to take advantage of texture compression.

Resource build styles can be used to mark all textures for compression using build styles. See building multiple data sets for more details.

If a texture is uploaded on a platform that does not support the compression format an assert will be raised and a checkerboard pattern will be uploaded instead.

Not all textures can be compressed in all schemes, and Airplay includes some rules for avoiding compression where results are generally unacceptable even though it is technically possible. The compression types currently supported by the Airplay SDK are summarised in the following table.

IwImage format | Description | Windows Simulator availability | Device availability | Caveats
PVRTC_2 | PVR Texture compression 2 bit encoding | Available in all OpenGL ES modes | Available in imagination hardware. Nokia N95, Apple iPhone, etc. | The 2 bit version of PVRTC is generally very low quality, so Airplay will never select it automatically. Apart from that, the caveats are the same as PVRTC_4.
PVRTC_4 | PVR Texture compression 4 bit encoding | Available in all OpenGL ES modes | Available in imagination hardware. Nokia N95, Apple iPhone, etc. | The 4 bit version of PVRTC generally produces good results for opaque textures, where it will be used automatically in PVRTC build styles. Although it technically supports textures with alpha channels, the quality is typically sub-par with silouettes being particularly disrupted. Therefore applications must opt-in to compression of alpha textures using the "allowLowQualityCompression" image template parameter. PVRTC only supports square textures. If the aspect ratio of a texture is not more extreme that 4:1 gx will tile the texture to a square and scale UVs appropriately using the texture matrix. This is wasteful, but generally uses less texture memory than the uncompressed texture.
ATITC | ATI Texture compression 4 bit/8 bit encoding | Not available | Available in ATI/Qualcomm hardware. HTC Hero devices, HTC Touch pro, etc. | ATITC generally produces good results for most textures, so will be used automatically in ATITC build styles. An 8bit version is supported (and used automatically) for textures with alpha channels. Note that ATITC textures have a significant performance advantage (which can be profound on the earlier devices with MSM7x00 chipsets).
ETC | Ericsson Texture compression 4 bit encoding | Available in OpenGL ES 2.x | Available in ATI/Qualcomm hardware (e.g. Toshiba TG-01) and some Imagination hardware (Samsung Omnia HD, although not Apple iPhone 3GS). Expected to be generally supported for GLES 2.x. | ETC has no support for alpha channels, so will only be used for opaque textures. Some chipset manufacturers recommend encoding the alpha channel in a seperate texture and combining them in the fragment shader. Airplay does not perform this optimisation automatically.


Airplay API Reference: Streams

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Streams >

Streams

IwGx follows the OpenGL ES specification in that it ONLY supports a stream-based, rather than primitive-based, drawing API. There are four types of "geometry streams" used:

  • Vertex stream: always required for any drawing. Stream entries are always of type CIwSVec3 for 3D drawing and CIwSVec2 for 2D drawing.
  • Normal stream: required only if using diffuse lighting. Stream entries are always of type CIwSVec3. Vector components should be considered to be in the 1.3.12 fixed point format.
  • Colour stream: required only if supplying per-vertex colours. Stream entries are always of type CIwColour. If supplying a colour stream, the vertex colour overrides both the material ambient and material diffuse colours in the lighting calculation.
  • UV stream: always required if the current material has associated textures. Stream entries are always of type CIwSVec2. Vector components should be considered to be in the 1.3.12 fixed point format. This means that texture coordinates can "wrap" in the range (-8, +8).

Having passed the required streams of geometry data to IwGx, the user then makes a final drawing call, which involves passing in an "index stream", to stitch the previous streams together into a series of triangles ("tris") or quadrilaterals ("quads").

For example:

  • static int16 s = 0x40;
  • static CIwVec3 s_Vecs[4] =
  • {
    • CIwVec3(-s, -s, 0),
    • CIwVec3(-s, s, 0),
    • CIwVec3( s, -s, 0),
    • CIwVec3( s, s, 0),
  • };
  • IwGxSetVertStream(s_Vecs, 4);

Here we are supplying a vertex stream of 4 points, representing a square in the XY plane. We are also supplying the vertex stream in "model space" - so we must consider what our current view and model transforms are.

Note: For more information on view and model transforms, see the Transform section.

For an example of how to use a stream to draw a single polygon, see IwGx Polygon Display Example.

We could then set an untextured material to use, and draw the square as follows:

  • CIwMaterial* pMat = new CIwMaterial;
  • IwGxSetMaterial(pMat);
  • static uint16 s_Inds[4] = {0, 1, 2, 3};
  • IwGxDrawPrims(IW_GX_QUAD_LIST, s_Inds, 4);

In this example, we have decided to draw the geometry using a "quad list". This requires successive vertices to be specified in a "Z" shape - see the API documentation for a complete list of supported of "drawing modes", also known as "primitive types".

Note also that in this case, the vertices in the stream are already in the correct order for drawing - that is why the supplied index stream is simply a series of ascending integers, starting from 0. When this is the case, it is sufficient to pass in a NULL index stream, as follows:

  • IwGxDrawPrims(IW_GX_QUAD_LIST, NULL, 4);

Note: You must always tell IwGxDrawPrims() how many indices to use, which determines how many tris or quads actually get drawn. See the IwGx examples for more involved usage of streams.


Airplay API Reference: Colour

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Colour >

Colour

All colours in IwGx use the following structure:

  • class CIwColour
  • {
  • public:
    • uint8 r;
    • uint8 g;
    • uint8 b;
    • uint8 a;
  • };

These structures are always 32-bit aligned, so it is legal to read/write a colour value as a single 32-bit operation. Many colour functions take three variations of inputs, for example:

  • INLINE void IwGxSetColEmissive(const CIwColour& col);
  • INLINE void IwGxSetColEmissive(uint8 _r, uint8 _g, uint8 _b, uint8 _a);
  • INLINE void IwGxSetColEmissive(uint32 col);

In the latter case, the uint32 value is in ABGR format, so for example (r,g,b,a)=(0x20,0x40,0x80,0xff) would be passed in as the value 0xff804020.

Note: The Airplay software renderer currently makes no use of the alpha component of colour calculations.

To ensure that other rasterisers behave correctly, the user should always be sure to initialise the alpha component of a CIwColour. For example, be very wary of the following:

  • CIwColour myRGB = {0x20, 0x40, 0x80};

This has left the alpha component uninitialised, which may cause unexpected rendering artefacts when using HW rasterisation. Instead, you should use the following:

  • CIwColour myRGB = {0x20, 0x40, 0x80, 0xff};

Within the lighting pipeline, colours may be multiplied together; for example, the scene ambient light colour may be multiplied by the material ambient response. In this case, the "unitary" colour value is taken to be 0xff. So conceptually:

  • (0xff, 0xff, 0xff) * (0xff, 0xff, 0xff) = (0xff, 0xff, 0xff).

The following fixed colours are provided:

  • typedef enum IwGxColourFixed
  • {
    • IW_GX_COLOUR_BLACK,
    • IW_GX_COLOUR_WHITE,
    • IW_GX_COLOUR_GREY,
    • IW_GX_COLOUR_RED,
    • IW_GX_COLOUR_GREEN,
    • IW_GX_COLOUR_BLUE,
    • IW_GX_COLOUR_MAGENTA,
    • IW_GX_COLOUR_CYAN,
    • IW_GX_COLOUR_YELLOW,
    • IW_GX_COLOUR_MAX,
  • } IwGxColourFixed;

These can be accessed using:

  • INLINE const CIwColour& IwGxGetColFixed(IwGxColourFixed colID);

So, for example, we could initialise a material to have yellow emissive colour, but no ambient or diffuse response, as follows:

  • CIwMaterial* pMat = new CIwMaterial;
  • pMat->SetColEmissive(IwGxGetColFixed(IW_GX_COLOUR_YELLOW));
  • pMat->SetColAmbient(0);
  • pMat->SetColDiffuse(0);

When drawing primitive, we can optionally supply a per-vertex colour stream to be used by the lighting stage. For example:

  • static CIwColour s_Cols[4] =
  • {
    • {0x00, 0x00, 0x00},
    • {0x00, 0x00, 0xff},
    • {0x00, 0xff, 0x00},
    • {0x00, 0xff, 0xff},
  • };
  • IwGxSetColStream(s_Cols, 4);

We would clear the stream (i.e., turn off the per-vertex colour stream) by using:

  • IwGxSetColStream(NULL);

See Lighting for a complete description of the IwGx Lighting Model; i.e., how IwGx uses scene lights, material colours and per-vertex colour streams to determine the actual vertex colours used by the rasterisation stage.


Airplay API Reference: Transform

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Transform >

Transform

The transform stage of the IwGx pipeline behaves differently in its SW and HW states. The work performed is as follows:

If Transform=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 Transform=HW:

  • Prepare perspective transform and model-view transform appropriately for HW rasterisation.
  • Pass vertex and normal streams to the rasterisation stage.

The transform stage can be switched between SW and HW as follows:

  • // Set transform stage to SW:
  • IwGxSetTransformSW();
  • // Set transform stage to HW:
  • IwGxSetTransformHW();

The IwGxState holds the following information relating to the transform stage:

  • Screen width, height and orientation.
  • Frustrum near plane, far plane, and field-of-view.
  • Current view transform (camera position and orientation).
  • Current model transform (object position and orientation).
  • Helper variables derived from the above.

User interaction with the transform stage is generally limited to setting the frustrum and setting the view transform. The frustrum is generally initialised at the start of the application. The near and far plane clipping plane distances should be set as conservatively as possible; that is, choose the largest near plane value which does not result in polygons disappearing close to the camera, and choose the smallest far plane value which still gives an acceptable draw-distance. For example:

  • IwGxSetFarZNearZ(0x4000, 0x20);

The frustrum field-of-view is not specified directly; instead, the user specifies the "perspective multiple". This is the distance from the camera (the "eye point") to the viewing plane. Note that the viewing plane is the conceptual 2D plane onto which we are projecting our 3D world; it is NOT the same as the near plane. For example, to obtain a horizontal field-of-view of 90 degrees, our perspective multiple would have to be equal to half the screen width, as follows:

  • IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

Every frame, before rendering the scene, the user should set the view transform (camera position and orientation) as follows:

  • IwGxSetViewMatrix(myCamMatrix);

Generally, the user will have their own application camera class, which will have near plane, far plane, perspective multiple, position and orientation members. Before rendering the scene, these members should be used to set the frustrum and view transform. For example:

  • // Application camera class
  • class CCamera : public CIwManaged
  • {
  • public:
    • CIwMat m_XForm;
    • uint32 m_NearPlane;
    • uint32 m_FarPlane;
    • uint32 m_PerspMul;
  • };
  • // Code to set frustrum and view transform from application camera
  • object:
  • CCamera* pCam;
  • IwGxSetFarZNearZ(pCam->m_FarPlane, pCam->m_NearPlane);
  • IwGxSetPerspMul(pCam->m_PerspMul);
  • IwGxSetViewMatrix(&pCam->m_XForm);

Once the frustrum and view transform have been set up, we are ready to submit vertex streams. Vertex streams can be submitted in four modes, or "spaces":

  • Modelspace
  • Worldspace
  • Viewspace
  • Screenspace

Note:See the IwGx Coordinate Spaces Example for an example of using each of the four spaces.


Airplay API Reference: Modelspace

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Transform > Modelspace >

Modelspace

The vertices are specified within the local space of an application object or "model". The local space of the model should be specified as follows:

  • CIwMat* pModelMatrix = ?;
  • IwGxSetModelMatrix(pModelMatrix);

This function call will also use the current view matrix to calculate a combined "model-view" matrix, which is stored internally on the IwGxState object. For this reason, you should always set the view matrix before setting the model matrix; IwGxSetModelMatrix() must be called before IwGxSetVertStream(). IwGxSetModelMatrix() triggers a recalculation of the model view. Once you have set the model matrix, the vertex stream can be submitted as follows:

  • CIwSVec3* pVerts = ?;
  • uint32 numVerts = ?;
  • IwGxSetVertStreamModelSpace(pVerts, numVerts);

This function call is identical to calling:

  • CIwSVec3* pVerts = ?;
  • uint32 numVerts = ?;
  • IwGxSetVertStream(pVerts, numVerts);


Airplay API Reference: Worldspace

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Transform > Worldspace >

Worldspace

The vertices are specified within the application world. Therefore, there is no concept of a "model transform" - only the view transform is used to calculate the screen position of each vertex. To submit a vertex stream in worldspace, use:

  • CIwSVec3* pVerts = ?;
  • uint32 numVerts = ?;
  • IwGxSetVertStreamWorldSpace(pVerts, numVerts);


Airplay API Reference: Viewspace

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Transform > Viewspace >

Viewspace

The vertices are specified within the camera frustrum. Therefore, there is no concept of a "model transform" or a "view transform"; only the frustrum description itself is used to calculate the screen position of each vertex. The scale of this space is the same as the world scale - the space is simply aligned with the camera. You should also specify a position in viewspace to serve as an origin; your vertex stream is considered to be relative to this origin:

  • // Set the origin within viewspace
  • CIwSVec3 org(10, 10, 0);
  • IwGxSetViewSpaceOrg(&org);

Note: The specified viewspace origin is invalidated by calling IwGxSetModelMatrix() or IwGxSetScreenSpaceOrg().

To submit a vertex stream in viewspace, use:

  • CIwSVec3* pVerts = ?;
  • uint32 numVerts = ?;
  • IwGxSetVertStreamViewSpace(pVerts, numVerts);

It is often convenient to submit vertices in viewspace, for example when rendering "billboarded" effects (2D effects parallel to the viewing plane, which scale with distance).

Note: For an example of how to use billboarded effects, see the IwGx Billboards Example.

For the SW transform pipeline, viewspace vertices are slightly more efficient to transform than modelspace or worldspace vertices.


Airplay API Reference: Screenspace

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Transform > Screenspace >

Screenspace

In screenspace, vertices are specified as pixel coordinates relative to the top-left of the screen. In this case, the vertices must be supplied as CIwSVec2 objects, as follows:

  • CIwSVec2* pVerts = ?;
  • uint32 numVerts = ?;
  • IwGxSetVertStreamScreenSpace(pVerts, numVerts);

Screenspace pixel coordinates, by default, are taken to be relative to the top-left of the current "application screen". This means that a coordinate of (0, 0) will appear at the top-left of the screen, and a coordinate of (IwGxGetScreenWidth()-1, IwGxGetScreenHeight()-1) will appear at the bottom-right of the screen, irrespective of your current screen rotation (portrait or landscape).

You can specify a screenspace origin, which your vertices are considered relative to. For example:

  • // Set the origin within screenspace
  • CIwSVec2 org(10, 10);
  • IwGxSetScreenSpaceOrg(&org);

All screenspace drawing must appear in front of or behind the main frustrum; i.e. it cannot be "embedded" within the frustrum. IwGx provides several "front slots" and "back slots" for you to layer your screenspace drawing. By default, there are 32 front slots and 4 back slots (these numbers can be changed via the ICF file).

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 slots, and negative values refer to back slots. The two's-complement of a negative value is the back slot ID. If we have n front slots, and m back slots, then the visual layering is performed from as follows:

  • 0,1,2...n-1 / Main 3D frustrum / -m,-(m-1),-(m-2),...-1

...where the left-hand side represents the front-most drawing, and the right-hand side represents the back-most drawing.

So IwGxSetScreenSpaceSlot(0) will set the front-most drawing, and IwGxSetScreenSpaceSlot(-1) will set the back-most drawing. Within a single slot, calls to IwGxDrawPrims() will be drawn in the order they are specified. For example:

  • IwGxSetScreenSpaceSlot(1);
  • // Set up some streams for geometry A
  • IwGxDrawPrims(...);
  • // Set up some streams for geometry B
  • IwGxDrawPrims(...);

Geometry A will be drawn before geometry B (i.e. geometry B will appear in front of geometry A).

To submit a vertex stream in screenspace, use:

  • // Set the vertex stream - vertices are in screenspace,
  • // relative to our origin
  • IwGxSetVertStreamScreenSpace(pVecs, numVerts);

IwGx provides several helper functions for converting coordinates between worldspace, viewspace and screenspace. For example, to convert a point from viewspace to screenspace, use:

  • CIwVec3 viewPos; // assume this is our point in viewspace
  • int16 sx, sy;
  • IwGxViewToScreenXY(sx, sy, viewPos);

Note: See the IwGx API Reference for a complete list of screenspace helpers.


Airplay API Reference: Lighting

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Lighting >

Lighting

The lighting stage of the IwGx pipeline behaves differently in its SW and HW states. The output of the lighting stage is always a per-vertex colour which is used when rasterising the primitives. The work performed by the lighting stage in each state is as follows:

  • If Lighting=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=HW: Material emissive, ambient and diffuse colours, together with any scene lights, are passed to the underlying HW (for example, the OpenGL ES drivers). Any submitted colour stream is also passed to the HW. The HW rasterisation will then perform any necessary colour calculations internally. Note that, depending on the underlying HW, various factors will affect the efficiency of this calculation; for example, many OpenGL ES drivers will perform poorly if scene lights are created.

The lighting stage can be switched between SW and HW as follows:

  • // Set lighting stage to SW:
  • IwGxSetLightingSW();
  • // Set lighting stage to HW:
  • IwGxSetLightingHW();

The following topics are covered in this section:

  • Lighting: The Lighting Model
  • Lighting: Scene Lights


Airplay API Reference: Lighting: The Lighting Model

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Lighting > Lighting: The Lighting Model >

Lighting: The Lighting Model

The key to making use of the lighting stage is to understand the Lighting Model; this is a description of how the final per-vertex colours are calculated from the material colours, scene lights, and any submitted colour stream. The calculation is as follows:

Cv = Me + (Ma * Sa) + (Md * Sd * falloff) + (Ms * Ss * specularFalloff)

Where:

  • Cv = per-vertex colour, the output of the calculation
  • Me = material emissive colour
  • Ma = material ambient colour
  • Md = material diffuse colour
  • Ms = material specular colour
  • Sa = scene ambient light colour
  • Sd = scene diffuse light colour
  • Ss = scene specular light colour
  • falloff = dot product of scene diffuse light direction with vertex normal
  • specularFalloff = is the dot product falloff calculated from the half vector between the camera direction and the single diffuse light direction with the vertex normal.

The Lighting Model supports a single ambient scene light and a single diffuse scene light only (see "Lighting: Scene Lights");

We can break this calculation down into four terms:

Lighting: Emissive contribution

The "emissive contribution" is 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(true or false);

Note: The default material emissive colour is zero (black).

Lighting: Ambient contribution

The "ambient contribution" is 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(true or false);

Lighting: Diffuse contribution

The "diffuse contribution" is 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(true or false);

Lighting: Specular contribution

The "specular contribution" is the term + "(Ms * Ss * specularFalloff)". If specular lighting is enabled, this term is equal to the material specular colour multiplied by any scene specular light colour, modified by the specular falloff term (the dot product of the half vector between the scene diffuse light direction and camera direction with the vertex normal). In this sense, the "specular diffuse colour" is better thought of as the "material specular lighting response". Note that if no scene diffuse light has been created, this term will be zero. Note also that specular lighting requires a normal stream to be submitted; otherwise the term will be zero.

If specular lighting is disabled, this term is zero. Specular lighting is enabled and disabled as follows:

  • IwGxLightingSpecular(true or false);

Additionally, emissive, ambient, diffuse and specular lighting can all be enabled and disabled together, using:

  • // Turn emissive, ambient and diffuse lighting on
  • IwGxLightingOn();
  • // Turn emissive, ambient and diffuse lighting off
  • IwGxLightingOff();

To repeat, if all lighting is turned off, the only contribution to the per-vertex colour will be the material ambient colour.


Airplay API Reference: Lighting: Scene Lights

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Lighting > Lighting: Scene Lights >

Lighting: Scene Lights

The Lighting Model supports a single ambient scene light and a single diffuse scene light only. These lights are usually created at the application 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 the Lighting Model only supports up to one of each type.

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: For an example of using the Lighting Model, see the IwGx Lighting Examples.


Airplay API Reference: Rasterisation

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Rasterisation >

Rasterisation

The rasterisation stage is responsible for actually drawing the primitives to the backbuffer. The rasterisation stage behaves differently in its SW and HW states. The work performed is as follows:

  • If Rasterisation=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 Airplay software renderer.
  • If Rasterisation=HW: Call the underlying HW functions required to rasterise the primitives.

The rasterisation stage can be switched between SW and HW as follows:

  • // Set rasterisation stage to SW:
  • IwGxSetRasterisationSW();
  • // Set rasterisation stage to HW:
  • IwGxSetRasterisationHW();

Note: Switching the rasterisation stage to SW will automatically switch both the transform and lighting stages to SW also.

The rasterisation stage essentially consists of just two functions; IwGxDrawPrims() and IwGxFlush().

The following topics are covered in this section:

  • Rasterisation: IwGxDrawPrims()
  • Rasterisation: IwGxFlush()
  • Rasterisation: Sorting Mode
  • Rasterisation: Swapping Buffers


Airplay API Reference: Rasterisation: IwGxDrawPrims()

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Rasterisation > Rasterisation: IwGxDrawPrims() >

Rasterisation: IwGxDrawPrims()

This function is used to "stitch together" the submitted vertex, normal, colour and UV streams into actual tris/quads. An "index stream" is submitted, which indexes identically into each submitted stream, effectively pushing data one vertex at a time to the rasteriser. The way the rasteriser interprets these successive vertices is dependent on the specified "primitive type" or "drawing mode" (see "Drawing Modes"). A common primitive type is the triangle list, where each successive vertex results in a new triangle being rasterised. For example:

  • CIwSVec3* pVerts; // pointer to an existing vertex stream
  • (100 verts)
  • IwGxSetVertStream(pVerts, 100);
  • uint16* pInds; // pointer to an existing index stream
  • // Draw 100 indices, which will result in 98 tris
  • IwGxDrawPrims(IW_GX_TRI_STRIP, pInds, 100);

Note: The current material is always used to shade the primitives. Note also that a call to IwGxDrawPrims may not actually result in anything being drawn to the backbuffer; the data may simply be cached for later use. See the description of IwGxFlush() below.


Airplay API Reference: Rasterisation: IwGxFlush()

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Rasterisation > Rasterisation: IwGxFlush() >

Rasterisation: IwGxFlush()

This function forces the underlying rasteriser to actually draw all primitives to the backbuffer. Usually, a call to IwGxDrawPrims() will simply cache the required inputs for later use. Each call to IwGxDrawPrims() results in a "geometry packet" being created and stored in a list. IwGxFlush() is required to force the cached data to be rasterised; it traverses the list and rasterises each packet of geometry. When the rasterisation stage is set to HW, IwGxFlush() may have to do extra work related to each packet; for example, it may have to modify the HW render states and texture states to ensure the correct material settings before each packet is drawn.


Airplay API Reference: Rasterisation: Sorting Mode

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Rasterisation > Rasterisation: Sorting Mode >

Rasterisation: Sorting Mode

The rasterisation stage allows the user to select how they want the geometry packets to be sorted on hardware rasterisers. Irrespective of the order in which the calls to IwGxDrawPrims() are made, the sorting mode ensures that geometry packets are submitted to the underlying rasteriser in the specified order. The default settings are optimal for performance, but applications may want to change sorting to reduce artifacts.

By default, submissions are sorted differently according to type. First opaque geometry is rendered, followed by back slot screenspace polys, the alpha geometry and finally front slot screenspace polys. This will be the order when IW_GX_SORT_BY_SLOT is set as the primary sort mode. This seperation of draw calls can be overridden by setting a different sort mode as the primary mode. For example, if IwGxSetSortMode is called with IW_GX_SORT_NONE all draw calls will be submitted to the rasteriser in the order they are made.

If IW_GX_SORT_BY_SLOT is set the sorting within each slot can be set using IwGxSetSortModeOpaque, IwGxSetSortModeAlpha and IwGxSetSortModeScreenSpace.

The sort modes are:
IW_GX_SORT_NONE | Render in the order of submission
IW_GX_SORT_BY_MATERIAL | Render batched by material. This is optimal for hardware where state changes are expensive.
IW_GX_SORT_BY_Z | Render sorted by modelspace origin Z. This will make alpha polys sort more correctly, but in practice IW_GX_SORT_BY_MATERIAL is normally faster and artifacts are few. For this reason that is the default.

The software renderer always sorts polys back-to-front on a poly-by-poly basis.


Airplay API Reference: Rasterisation: Swapping Buffers

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Rasterisation > Rasterisation: Swapping Buffers >

Rasterisation: Swapping Buffers

It is assumed that the underlying rasteriser is not single-buffered; i.e., we are always rasterising to a surface that is different to the one which is currently being displayed by the device. Such an implementation provides for much smoother animation that flickers less. In this case, once rasterising the scene is complete, it is necessary to swap the buffers so that the scene just rasterised becomes the scene displayed by the device. The underlying buffers are swapped as follows:

  • IwGxSwapBuffers();

Typically, the user calls this directly after the call to IwGxFlush(). So a typical application scene render looks something like:

  • // Begin scene render by clearing the backbuffer
  • // (and z-buffer, if one exists)
  • IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);
  • // Render all objects in the scene
  • // IwGxSetMaterial(), IwGxSetVertStream(), IwGxDrawPrims(), etc.
  • // Rasterise all primitives
  • IwGxFlush();
  • // Swap the buffers
  • IwGxSwapBuffers():


Airplay API Reference: Using IwGx with OpenGL ES

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Using IwGx with OpenGL ES >

Using IwGx with OpenGL ES

OpenGL ES portability

IwGx will seamlessly handle many small incompatibilities between various devices. Unfortunately, there are a number of things that application authors do need to be aware of.

Obviously, GL devices differ in performance and the amount of memory available for textures and buffers. To maximise portability there are several things applications should do:

  • Appropriate texture compression should be used. By default, IwResManager outputs resource sets with uncompressed textures. This means a default data set will work on any GL target (with enough texture memory available). While this is convenient, texture memory is often restricted and many devices suffer a significant performance hit when using uncompressed textures (especially very large ones). Therefore assets including compressed textures should generally be deployed with final builds. See building multiple data sets.
  • Try and minimise the number of unique materials in the scene. IwGx batching works by pointer-comparison of CIwMaterials, so the application should try and ensure that all draw calls with the same settings are instances of a single CIwMaterial object. Changes of material state are cheap in the SW renderer, but can be very expensive on GL hardware.
  • Submit large batches of primitives per IwDrawPrims call. IwGx supports after-the-fact batching using 'MergeGeoms', but this can get expensive with many small draw calls so it is generally best to maximise the size of submissions upfront.

Debugging HW device issues

If the application executes in the Windows Simulator but crashes (or freezes) on device without any error message you may be encountering a GL driver that is incompatible with IwGx in some respect.

Before jumping to this conclusion it's worth double-checking that the application/data bundle is valid by running it in the ARM emulator directly from the deployment directory. It can also be useful to get a 'second opinion' from another device.

IwGx provides a number of ICF settings to help diagnose GL issues:

Setting | Effect
DisableSurfaces=1 | Disable GL surfaces. Surface implementations are a common cause of GL problems. This setting will make all calls to CreateSurface fail. Obviously this will affect the output of the application, but can be used to establish whether surfaces are causing crashes.
DisableCustomShaders =1 | Disable all custom shader techniques. [Open GL ES 2.x only]
NoTextureUpload=1 | Ignore incoming texture uploads. Instead IwGx will upload a 1x1 texture. This can be used to establish whether running out of texture memory is causing a crash (sadly, this can affect some devices).
UploadStreams=0 | Don't use VBOs for any attribute streams. VBO implementation bugs are often visible as 'exploded' geometry or corrupted UVs.
GLMipmapOffset=x | Ignore the first x mipmap levels when uploading. This can be used as a rough-and-ready dynamic texture down-sizer. Obviously a custom data set is a better alternative for a shipping product!

Don't forget that running a debug build will give more information (including gl errors). The GX_VERBOSE trace channel can be enabled for even more information.

Mixing native gl calls with IwGx.

IwGx has no priviledged access to gl functions - the application can make its own gl function calls. These can be used to access platform specific functionality which IwGx does not expose. Applications do this at their own risk.

It is a good idea to call IwGxFlush before doing any gl calls to ensure that any queued drawing commands are executed in the correct order. The application should also check that IwGxGetHWType() is set to the appropriate GL api.

IwGx keeps a local record of what the current gl state is (to avoid needlessly resetting state, which can sometimes be expensive). For this reason the application should reset any gl properties it has changed before calling IwGxFlush again.


Airplay API Reference: Using IwGx with OpenGL ES 2.x

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Using IwGx with OpenGL ES 2.x >

Using IwGx with OpenGL ES 2.x

What is OpenGL ES 2.x?

OpenGL ES 2.x is a standard 3D graphics API that exchanges the fixed function pipeline of OpenGL ES 1.x for a flexible programmable pipeline. OpenGL ES 2.x allows far more fine control over the final appearance of rendered polygons by allowing short programmes called shaders to run within the GPU itself. A shader is run for each vertex and for each fragment. For more details see the Khronos OpenGL ES 2.x website

IwGx and OpenGL ES 2.x

IwGx eases the transition to OpenGL ES 2.x by including the standard fixed function pipeline. All code and assets from OpenGL ES 1.x will appear exactly the same in OpenGL ES 2.x.

To start IwGx in OpenGL ES 2.x mode make sure HW rasterisation is set and start the windows simulator with the GL API set to 'GLES 2.0' in the GL configuration menu. Note that OpenGL ES 2.x support relies on OpenGL 2.x desktop drivers which may not be functional on all PCs.

On device, use the icf setting [s3e] GLESVersion=2 to initialise in OpenGL ES 2.x where available.

Custom shaders in IwGx

IwGx allows entirely bespoke shaders to be added to materials. These are wrapped up in CIwGxShaderTechnique resources.

A CIwGxShaderTechnique is a standard CIwResource, instantiated from an itx file.

A very simple shader would look like:

  • CIwGxShaderTechnique
  • {
    • name "SimpleShader"
    • shader "vertex"
    • {
      • attribute highp vec4 inVert; //vertex stream
      • uniform highp mat4 inPMVMat; //transform to projected space
      • void main(void)
      • {
        • //set vertex position in projected space
        • gl_Position = inPMVMat * inVert;
      • }
    • }
    • shader "fragment"
    • {
      • void main(void)
      • {
        • gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
      • }
    • }
  • }

This shader simply transforms the vertices and renders the polygons in red.

IwGx can provide the shader with a number of standard uniforms and attributes from the fixed function pipeline. By convention, these are prefixed with 'in'. In this example the vertex shader consumes the vertex stream ('inVert') and the Projected Model-View Matrix ('inPMVMat').

The attribute stream on 'inVert' is simply the stream of vertices set using IwGxSetVertStream*. These will still be in fixed point for the HW transform pipeline.

The uniform 'inPMVMat' is the full transform from the original vertex space into post-projected view space. Note that this includes the scale from fixed space to float space for the HW transform pipeline.

gl_Position is set to the transformed position. gl_Position is a standard varying parameter which must be set by the vertex shader.

The fragment shader is called for each fragment on each poly. Here it is extremely simple - it just sets the gl_FragColor to opaque red (1.0, 0.0, 0.0, 1.0).

Exposing shader uniform parameters

As well as the standard IwGx uniforms, shader techniques can also expose custom uniform parameters to the code.

To extend the above:

  • CIwGxShaderTechnique
  • {
    • name "SimpleShader"
    • param "colour" vec4 1 { 1.0, 0.0, 0.0, 1.0 }
    • shader "vertex"
    • {
      • attribute highp vec4 inVert; //vertex stream
      • uniform highp mat4 inPMVMat; //transform to projected space
      • void main(void)
      • {
        • //set vertex position in projected space
        • gl_Position = inPMVMat * inVert;
      • }
    • }
    • shader "fragment"
    • {
      • uniform mediump vec4 colour;
      • void main(void)
      • {
        • gl_FragColor = colour;
      • }
    • }
  • }

This shader exposes a uniform called 'colour' to the code and uses it to set the fragment colour. The initial output of this shader is identical to that above, since the default value of 'colour' is still opaque red.

Now the colour of the fragments can be altered from code:

  • CIwGxShaderTechnique* technique =
    • (CIwGxShaderTechnique*)IwGetResManager()->GetResNamed("SimpleShader", "CIwGxShaderTechnique");
  • // Get the parameter we're interested in
  • CIwGxShaderUniform* param = technique->GetParam("colour");
  • if( param )
  • {
    • float val[4] = { 0.0, 1.0, 0.0, 1.0 };
    • param->Set(CIwGxShaderUniform::VEC4, 0, val);
  • }

Each parameter is exposed in a CIwGxShaderUniform object which tracks the expected type and provides some convenient setters.

After running this code the polys will appear green (0.0, 1.0, 0.0, 1.0).

It's good practise to test for the existence of a parameter before setting it so shader changes cannot cause the game to crash.

Uniforms exposed using 'param' will act as globals - changing the parameter will affect all materials using the technique. 'instanceParam' can be used to make uniforms that can vary with individual draw calls. This has slightly more overhead, so should be avoided unless neccessary.

Specifying a default for some parameters may be rather long-winded, so the placeholder 'no_default' can be used.

  • param "colour" vec4 1 no_default

If this uniform is used without being set the value will be all zeros.

OpenGL ES 2.x enabled assets in other rasterisers

If an asset with a shader technique is used with the SW or OpenGL ES 1.x rasterisers it will act as if the shader technique was not set. This means the normal fixed function properties will be adhered to.

The material effect preset "EFFECT_TEXTURE0_ONLY" can be used to make materials with shaders ignore additional texture stages in non-OpenGL ES 2.x modes. For this reason it's a good idea to use texture stage 0 as the diffuse texture in shader techniques.

Mixing OpenGL ES 2.x with SW TnL

Shaders can also be used with SW TnL which can be beneficial for load-balancing and geometry merging. For example, in SW transform vertex shaders for hidden vertices will not be executed.

Many shaders can be used with either SW or HW pipelines, since standard uniforms will generally compensate for changes in attribute format.

For example, in SW transform 'inVerts' will be vertices in view space and 'inPMVMat' will contain only the projection matrix.

The uniform 'inPipelineConfig' and be used to detect the current pipeline settings.

SW transform should not be used with shaders that significantly alter vertex positions, since polys will be clipped and culled based on the IwGx matrix stack before they get to the shader.


Airplay API Reference: Data Cache

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Data Cache >

Data Cache

Often, the data you are submitting to IwGx is being rewritten at every call to your render function. You might want to create a stream or material on the stack. This is not permitted, as the data submitted to IwGx must persist until IwGxFlush() is called at the end of your application render loop.

IwGx has a data cache which is reset at the end of each call to IwGxFlush(). You can freely allocate data from this cache during the render loop, and submit it to IwGx. You do not need to delete it, it is effectively lost when the cache is reset at the next call to IwGxFlush().

Use IW_GX_ALLOC() to allocate data from the cache. For example:

  • CIwSVec3* pVecs = IW_GX_ALLOC(CIwSVec3, 10);
  • // Fill out the array of verts, then:
  • IwGxSetVertStream(pVecs, 10);
  • CIwSVec2* pUVs = IW_GX_ALLOC(CIwSVec2, 10);
  • // Fill out the array of UVs, then:
  • IwGxSetUVStream(pUV, 10);
  • uint16* pInds = IW_GX_ALLOC(uint16, 20);
  • // Fill out the array of indices, then:
  • IwGxDrawPrims(IW_GX_TRI_LIST, pInds, 20);

Objects allocated from the data cache using IW_GX_ALLOC() will not have gone any initialisation; for example, class constructors will not have been called. It is therefore suitable only for classes with default constructors.

To allocate and initialise (call the constructors for) an array of objects, use IW_GX_ALLOC_OBJECTS(). Pass in "1" if allocating and initialising only a single object.

Note: Objects allocated on the data cache will never have any destructors called. CIwMaterial knows whether it has been allocated on the cache, and ensures that any further allocations attached to the object are also allocated from the data cache. Be very careful when allocating other types of object from the data cache.

Materials and geometry streams sent to IwGx must persist to the end of the render loop (when IwGxFlush() is called). To re-iterate: it is not permitted to create geometry streams on the stack, as the data may be destroyed before IwGxFlush() is called.

The size of the data cache can be set within the ICF file, for example:

  • [GX]
  • DataCacheSize=32768 # 32k of data cache

Note: If the user overflows the data cache (tries to allocate too much data from the cache between calls to IwGxFlush()), an assertion will fire.


Airplay API Reference: Screen Manipulation

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Screen Manipulation >

Screen Manipulation

An application will automatically be displayed in the size of the device screen. When developing an application in Windows, the user can modify the screen size through the surface configuration menu.

All rendering code should be size independent, thus ensuring that the application is formatted correctly across all possible device screen sizes. This often means that calculations of frustrum and screenspace coordinates should take the current screen width and height into account. The current device screen width and height can be read as follows:

  • uint32 dw = IwGxGetDeviceWidth();
  • uint32 dh = IwGxGetDeviceHeight();

IwGx supports the changing of both portrait and landscape aspect ratios dynamically. This means the application display can be rotated at runtime into either portrait or landscape orientations (in fact, it can be rotated into each of the possible 90 degree orientations). The display orientation can be modified as follows:

  • IwGxSetScreenOrient(IW_GX_ORIENT_NONE or IW_GX_ORIENT_90 or ...);

The following example explains what happens when this function is called.

Suppose we run the application as normal on a device with a 176x208 display. The application starts in portrait orientation. The "device" width and height are identical to the "application" width and height:

  • uint32 dw = IwGxGetDeviceWidth(); // returns 176
  • uint32 dh = IwGxGetDeviceHeight(); // returns 208
  • uint32 sw = IwGxGetScreenWidth(); // returns 176
  • uint32 sh = IwGxGetScreenHeight(); // returns 208

Rotate the screen into landscape orientation, and observe how these values change:

  • IwGxSetScreenOrient(IW_GX_ORIENT_90);
  • uint32 dw = IwGxGetDeviceWidth(); // returns 176
  • uint32 dh = IwGxGetDeviceHeight(); // returns 208
  • uint32 sw = IwGxGetScreenWidth(); // returns 208
  • uint32 sh = IwGxGetScreenHeight(); // returns 176

The "screen" width and height values become flipped, whilst the "device" width and height values remain fixed. The view frustrum is also rotated by 90 degrees (internally within the transform stage) to ensure that all geometry is drawn correctly in the new landscape orientation. Screenspace coordinates are also rotated, so that (0, 0) still refers to the top-left of the application screen.

To ensure that the application is independent of device screen size, and independent of orientation, the user should respect the values of IwGxGetScreenWidth() and IwGxGetScreenHeight(). For example, suppose we wish to display a screenspace icon at the top-right of the application screen. We know the icon is 32x32 pixels, and we want a 2-pixel border between the icon and the edge of the screen. We would set up the screenspace vertex stream as follows:

  • int16 sw = (int16)IwGxGetScreenWidth();
  • int16 sh = (int16)IwGxGetScreenHeight();
  • CIwSVec2 sc[4] =
  • {
    • CIwSVec2(sw - 32 - 2, 0),
    • CIwSVec2(sw - 32 - 2, 32),
    • CIwSVec2(sw - 2, 0),
    • CIwSVec2(sw - 2, 32),
  • };
  • IwGxSetVertStreamScreenSpace(sc, 4);

The icon will appear in the correct place irrespective of the device screen size and the application screen orientation.


Airplay API Reference: Clipping

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Clipping >

Clipping

The transform stage, if switched to SW, performs all necessary clipping and backface culling of primitives before sending them to the rasteriser. However, the user should perform high-level clipping of application objects to the view frustrum, to ensure that objects outside the frustrum are not processed at all.

Internally, the transform stage has a concept of "clipspace". This is aligned to viewspace, but with each axis scaled differently, so that software clipping calculations can be performed as efficiently as possible.

IwGx provides several clipping functions which allow the user to perform their own clip calculations for points and spheres against the view frustrum. Most of these functions take inputs in clipspace.

The IwGxState maintains matrices which take points from worldspace to clipspace, and from modelspace to clipspace. These matrices can be used to calculate the required inputs to the clipping functions.

For example, say we have a point in the world, and we want to check if it is within the view frustrum. We could do this as follows:

  • // Assume this is the point in the world
  • CIwVec3 vp;
  • // Transform the point from worldspace to clipspace
  • CIwVec3 cp = IwGxGetWorldViewClipMatrix.TransformVec(vp);
  • // Clip the point against the view frustrum
  • uint16 flags = IwGxClipVec(cp);
  • // Returns 0 only if the point is within the view frustrum

Alternatively, suppose we have an object bounding sphere in the world, and we want to check if it is behind the camera near plane. We could do this as follows:

  • // Assume this is the bounding sphere in the world
  • CIwSphere s;
  • // Clip the sphere against the near plane only
  • uint16 flags = IwGxClipSphere(s, IW_GX_CLIP_NEAR_F);
  • // Returns 0 only if the sphere is in front of the near plane


Airplay API Reference: Z-depth

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Z-depth >

Z-depth

Every drawn primitive has a "z-depth". For rasterisers using a z-buffer, each pixel of each primitive gets a different z-depth according to the z-coordinates of the primitive vertices in viewspace (i.e. within the view frustrum). For rasterisers not using a z-buffer, each primitive may get a single z-depth according to some function of the primitive vertices.

The z-depth dictates where in the (back, front) range the primitive gets drawn. Obviously by default things at the back of the frustrum get drawn behind things that are further forward in the frustrum. This all happens (thankfully!) without concerning the user.

However, sometimes it is useful for the user to tweak the z-depth values to ensure that certain pieces of geometry are not obscured by others, or to ensure they are ALWAYS obscured. For example, it would be desirable if a billboarded glow effect superimposed on top of a lamppost model always appeared in front of the lamppost model. With the default settings, this might be hard to achieve from all viewing angles. To solve the problem, we could give the glow effect a slight "shove forward", so that its z-depth value is lower. Note that this would not affect where on screen the glow is drawn; it would simply ensure that the glow is always in front of the lamppost model. We can do this using the concept of a "z-depth offset", as follows:

  • CIwMaterial* pMat; // assume this points to the glow material
  • pMat->SetZDepthOfs(-20);
  • IwGxSetMaterial(pMat);
  • // Now draw the glow...

Note that the material object can store a z-depth offset; this value is copied onto the IwGxState, during IwGxSetMaterial(). We can if we wish modify the state variable directly, as follows:

  • CIwMaterial* pMat; // assume this points to the glow material
  • IwGxSetMaterial(pMat);
  • IwGxSetZDepthOfs(-20);
  • // Now draw the glow...

Note that any z-depth offset on the IwGxState will persist until it is set back to zero (either directly, or via IwGxSetMaterial()).

Another z-depth example might be a skydome model; although this model is of finite radius, we might want to fix things so that it is always drawn behind all application objects in the world, irrespective of how far away those application objects are. In this case, we use the concept of a "fixed z-depth", as follows:

  • CIwMaterial* pMat;
  • // assume this points to the skydome material
  • IwGxSetMaterial(pMat);
  • IwGxSetZDepthFixed(IwGxGetFarZ() - 1);
  • // Now draw the skydome...

All geometry will now be drawn at the furthest possible z-depth. Note that the material can NOT store a fixed z-depth; a fixed z-depth must be set directly as in the example. Note also that any fixed z-depth on the IwGxState will persist until it is set back to -1, as follows:

  • // Clear any fixed z-depth
  • IwGxSetZDepthFixed(-1);

A fixed z-depth will take priority over a z-depth offset; i.e. any z-depth offset will NOT be added to the fixed z-depth value.

Uniform z-depth offsets are generally difficult to achieve in hardware renderers. In hardware, the offsets are specified in window space Z, meaning that offsets will have a much larger effect near the back of the frustrum. For this reason hardware offsets are specified seperately to software offsets.


Airplay API Reference: IwGx Metrics

Airplay API Reference > IwGx API Documentation > IwGx API Overview > IwGx Metrics >

IwGx Metrics

For Debug builds, IwGx maintains many useful metrics which can be inspected by the user. For example, the user can track the amount of data cache used, the number of triangles clipped, the number of triangles drawn, etc.

IwGx metrics are visible within the Windows Simulator metrics dialog in "Airplay Studio/IwGx"

There are two other ways of inspecting the metrics from code:

  • Using the debug menu system See the IwUtil documentation for details of using the debug menu system. Add the main IwGx debug menu to your top-level menu, as follows:
    • // Assume pMenu is the top-level debug menu
    • pMenu->AddItem(new CIwMenuItemGx);

    You will have access to a menu of all the IwGx metrics.

    There are two main ways of inspecting the metrics:

    Note: See the IwGx API Reference for a full list of the IwGx metrics.

  • Explicitly interrogating specific metrics: Use the IW_GX_METRIC_GET macro to return the current value of a named IwGx metric.

    • Note: The input to the macro is the full IwGx metric name, but without the IW_GX_METRIC_ prefix.


Airplay API Reference: Debug Drawing

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Debug Drawing >

Debug Drawing

The following topics are discussed in this section:

  • Text
  • Helpers


Airplay API Reference: Text

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Debug Drawing > Text >

Text

IwGx contains a simple debug text drawing function, which allows text to be drawn using a default debug font, to any screen position. For example:

  • int32 sx = 2;
  • int32 sy = 2;
  • char line[80];
  • IwGxPrintString(sx, sy, "Objects");
  • sy += 8;
  • sprintf(line, "x = %d", myObject->x);
  • IwGxPrintString(sx, sy, line);
  • sy += 8;
  • sprintf(line, "y = %d", myObject->y);
  • IwGxPrintString(sx, sy, line);


Airplay API Reference: Helpers

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Debug Drawing > Helpers >

Helpers

IwGx contains many useful debug functions for drawing simple geometric helper objects. The functions can be called at any point during application rendering. Each function takes a colour object as an input. Note that IwGx provides a simple list of fixed colours which can be accessed using IwGxGetColFixed().

For example, say we wish to track the origin of an application object by displaying a cross at the object's origin. We could do this as follows:

  • CIwMat* pMat;
  • // assume this points to the application object's transform
  • IwGxDebugPrimCross(pMat->t, 10);
  • // Displays a cross in the default colour

Alternatively, we may wish to display the bounding sphere of the object, in red. We could do this as follows:

  • CIwMat* pMat;
  • // assume this points to the application object's transform
  • int32 rad; // assume this is the application object's bounding
  • radius
  • CIwSphere s;
  • s.t = pMat->t;
  • s.SetRadius(rad);
  • IwGxDebugPrimSphere(s, IwGxGetColFixed(IW_GX_COLOUR_RED));

Note: See the IwGx API Reference for a full list of debug drawing functions.


Airplay API Reference: Miscellaneous

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Miscellaneous >

Miscellaneous

The following miscellaneous items are discussed in this section:

  • IwGxTickUpdate()
  • Motion Blur


Airplay API Reference: IwGxTickUpdate()

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Miscellaneous > IwGxTickUpdate() >

IwGxTickUpdate()

The user is responsible for telling IwGx when the application has performed an update cycle. This information is required by IwGx in order to correctly perform some functions which should be synchronised with application time. For example, all UV animations will advance one frame for each call to IwGxTickUpdate. A typical appflow would be:

  • if( !paused ) // don't advance the application state when
  • paused
  • {
    • // Perform application update
    • ...
    • // Tell IwGx
    • IwGxTickUpdate();
  • }
  • // Perform application render


Airplay API Reference: Motion Blur

Airplay API Reference > IwGx API Documentation > IwGx API Overview > Miscellaneous > Motion Blur >

Motion Blur

Motion blur is only available when using SW rasterisation. It allows blurring of the entire application screen, by blending between the current and previous backbuffers. The weighting of the current and previous backbuffers can be modified in various fixed steps. For example:

  • // At application initialisation
  • IwGxMotionBlurInit();
  • // To turn motion blur on, with a non-accumulating 50:50 weighting:
  • IwGxMotionBlurSetType(IW_GX_MOTION_BLUR_5050_NOACCUM);
  • // To turn motion blur off
  • IwGxMotionBlurSetType(IW_GX_MOTION_BLUR_NONE);
  • // At application shutdown
  • IwGxMotionBlurTerminate();

Turning on motion blur does reduce performance, although not critically, as the blur operation is done at the same time as the backbuffer is copied across to the underlying OS surface.


Airplay API Reference: IwGx API Reference

Airplay API Reference > IwGx API Documentation > IwGx API Reference >

IwGx API Reference

Modules

Clipping
Colours
Debug Drawing
Data Cache
Initialisation and Termination
Screen Manipulation
Flag Functions
Pipeline Switching
Selective Linking
Z-Depth Control
Fog Control
Vertex Streams
Normal Streams
Colour Streams
UV Streams
Rasterisation Pipeline
Transform Pipeline
Lighting Pipeline
Textures
Materials
Miscellaneous Functions
IwGx Error
IwGxMotionBlur
Printing
OpenGL ES 2.x Shader Techniques
IwGxState
Stream Objects
Surfaces and Render Targets
IwGxTransformSW
IwGxTypes


Airplay API Reference: Clipping

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Clipping >

Clipping
[IwGx API Reference]

Enumerations

enum | IwGxClipFlag { , IW_GX_CLIP_ALL = (1 << 6) - 1 }
enum | IwGxClipPlane

Functions

INLINE uint16 | IwGxClip2dVecX (int32 x)
INLINE uint16 | IwGxClip2dVecY (int32 y)
INLINE uint16 | IwGxClipSphere (const CIwSphere &sphere, uint32 clipFlags=IW_GX_CLIP_ALL)
INLINE uint16 | IwGxClipSphereModelSpace (const CIwSphere &sphere, uint32 clipFlags=IW_GX_CLIP_ALL)
INLINE uint16 | IwGxClipSphereViewSpace (const CIwSphere &sphere, uint32 clipFlags=IW_GX_CLIP_ALL)
INLINE uint16 | IwGxClipSphereWorldSpace (const CIwSphere &sphere, uint32 clipFlags=IW_GX_CLIP_ALL)
INLINE uint16 | IwGxClipVec (const CIwVec3 &vt)
INLINE uint16 | IwGxClipVecX (const CIwVec3 &vt)
INLINE uint16 | IwGxClipVecXY (const CIwVec3 &vt)
INLINE uint16 | IwGxClipVecY (const CIwVec3 &vt)

Detailed Description

This module defines clipping flags, and contains functions to test clipping of clipspace vertices and spheres against frustrum planes.

Note:
For more information on how clipping works, see the Clipping section of the IwGx API Documentation.

Enumeration Type Documentation

enum IwGxClipFlag

Clipping flags. Use these when clipping a point or sphere against the view frustrum. Some flags are used as function inputs, some as return values.

Required Header Files
IwClip.h
Enumerator:
IW_GX_CLIP_XNEG_F | input: test right plane. output: clipped off right plane.
IW_GX_CLIP_NEAR_F | input: test left plane. output: clipped off left plane.
IW_GX_CLIP_FAR_F | input: test near plane. output: clipped off near plane.
IW_GX_CLIP_YPOS_F | input: test far plane. output: clipped off far plane.
IW_GX_CLIP_YNEG_F | input: test bottom plane. output: clipped off bottom plane.
IW_GX_CLIP_NOT_OK_F | input: test top plane. output: clipped off top plane.
IW_GX_CLIP_NOT_DONE_SXY_F | output: point is invalid.
IW_GX_CLIP_EXTRA_F | output: screenspace xy not yet calculated.
IW_GX_CLIP_ALL input: perform 2D clip only

input: test all 6 planes. output: clipped off some plane.

IW_GX_CLIP_X | input: test both X planes. output: clipped off some X plane.
IW_GX_CLIP_Y | input: test both Y planes. output: clipped off some Y plane.
IW_GX_CLIP_Z | input: test both Z planes. output: clipped off some Z plane.
IW_GX_CLIP_XY | input: test all X and Y planes. output: clipped off some X or Y plane.
IW_GX_CLIP_XF | input: test both X planes and the far plane. output: clipped off some X plane or the far plane.
IW_GX_CLIP_YF | input: test both Y planes and the far plane. output: clipped off some Y plane or the far plane.
IW_GX_CLIP_XYF | input: test all X and Y planes and the far plane. output: clipped off some X or Y plane or the far plane.
IW_GX_CLIP_XN | input: test both X planes and the near plane. output: clipped off some X plane or the near plane.
IW_GX_CLIP_YN | input: test both Y planes and the near plane. output: clipped off some Y plane or the near plane.
IW_GX_CLIP_XYN | input: test all X and Y planes and the near plane. output: clipped off some X or Y plane or the near plane.

enum IwGxClipPlane

Clipping planes.

Required Header Files
IwClip.h
Enumerator:
IW_GX_CLIP_PLANE_NEAR | near plane
IW_GX_CLIP_PLANE_FAR | far plane
IW_GX_CLIP_PLANE_XPOS | positive x plane
IW_GX_CLIP_PLANE_XNEG | negative x plane
IW_GX_CLIP_PLANE_YPOS | positive y plane
IW_GX_CLIP_PLANE_YNEG | negative y plane

Function Documentation

INLINE uint16 IwGxClip2dVecX ( int32 x )

Calculate the clipping flags for a screenspace vertex, testing only the X clip planes (2 planes).

Parameters:
x The screenspace x coordinate.
Returns:
The clip flags (result of testing the point against the 2 clipping planes).
See also:
IwGxClip2dVecY

INLINE uint16 IwGxClip2dVecY ( int32 y )

Calculate the clipping flags for a screenspace vertex, testing only the Y clip planes (2 planes).

Parameters:
y The screenspace y coordinate.
Returns:
The clip flags (result of testing the point against the 2 clipping planes).
See also:
IwGxClip2dVecX

INLINE uint16 IwGxClipSphere | ( | const CIwSphere & | sphere,
 |  | uint32 | clipFlags = IW_GX_CLIP_ALL
 | ) |  |

Test whether a sphere in world space is within the frustrum (or subset of frustrum planes).

See also:
IwGxClipSphereWorldSpace

INLINE uint16 IwGxClipSphereModelSpace | ( | const CIwSphere & | sphere,
 |  | uint32 | clipFlags = IW_GX_CLIP_ALL
 | ) |  |

Test whether a sphere in model space is within the frustrum (or subset of frustrum planes).

Parameters:
sphere | The sphere to test.
clipFlags | A flags field describing the planes to test against. Default IW_GX_CLIP_ALL will test the entire frustrum.
Returns:
IW_GX_CLIP_NOT_OK_F if the sphere is not within the is not within the relevant planes, otherwise 0

INLINE uint16 IwGxClipSphereViewSpace | ( | const CIwSphere & | sphere,
 |  | uint32 | clipFlags = IW_GX_CLIP_ALL
 | ) |  |

Test whether a sphere in view space is within the frustrum (or subset of frustrum planes).

Parameters:
sphere | The sphere to test.
clipFlags | A flags field describing the planes to test against. Default IW_GX_CLIP_ALL will test the entire frustrum.
Returns:
IW_GX_CLIP_NOT_OK_F if the sphere is not within the is not within the relevant planes, otherwise 0

INLINE uint16 IwGxClipSphereWorldSpace | ( | const CIwSphere & | sphere,
 |  | uint32 | clipFlags = IW_GX_CLIP_ALL
 | ) |  |

Test whether a sphere in world space is within the frustrum (or subset of frustrum planes).

Parameters:
sphere | The sphere to test.
clipFlags | A flags field describing the planes to test against. Default IW_GX_CLIP_ALL will test the entire frustrum.
Returns:
IW_GX_CLIP_NOT_OK_F if the sphere is not within the is not within the relevant planes, otherwise 0

INLINE uint16 IwGxClipVec ( const CIwVec3 & vt )

Calculate the clipping flags for a clipspace vertex. All frustrum information is taken from the IwGx state.

Parameters:
vt Clipspace vertex.
Returns:
The clip flags (result of testing the clipspace vertex against the 6 clipping planes).
See also:
IwGxClipVecXY, IwGxClipVecX, IwGxClipVecY

INLINE uint16 IwGxClipVecX ( const CIwVec3 & vt )

Calculate the clipping flags for a clipspace vertex, testing only the X clip planes (2 planes).

Parameters:
vt Clipspace vertex.
Returns:
The clip flags (result of testing the clipspace vertex against the 2 clipping planes).
See also:
IwGxClipVec, IwGxClipVecXY, IwGxClipVecY

INLINE uint16 IwGxClipVecXY ( const CIwVec3 & vt )

Calculate the clipping flags for a clipspace vertex, testing only the X and Y clip planes (4 planes).

Parameters:
vt Clipspace vertex.
Returns:
The clip flags (result of testing the clipspace vertex against the 4 clipping planes).
See also:
IwGxClipVec, IwGxClipVecX, IwGxClipVecY

INLINE uint16 IwGxClipVecY ( const CIwVec3 & vt )

Calculate the clipping flags for a clipspace vertex, testing only the Y clip planes (2 planes).

Parameters:
vt Clipspace vertex.
Returns:
The clip flags (result of testing the clipspace vertex against the 2 clipping planes).
See also:
IwGxClipVec, IwGxClipVecXY, IwGxClipVecX


Airplay API Reference: Colours

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Colours >

Colours
[IwGx API Reference]

Data Structures

class | CIwColour

Enumerations

enum | IwGxColourFixed

Functions

INLINE CIwColour & | IwGxGetColAmbient ()
INLINE CIwColour & | IwGxGetColDiffuse ()
INLINE CIwColour & | IwGxGetColEmissive ()
INLINE const CIwColour & | IwGxGetColFixed (IwGxColourFixed colID)
INLINE void | IwGxSetColAmbient (const CIwColour &col)
INLINE void | IwGxSetColAmbient (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
INLINE void | IwGxSetColAmbient (uint32 col)
INLINE void | IwGxSetColDiffuse (const CIwColour &col)
INLINE void | IwGxSetColDiffuse (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
INLINE void | IwGxSetColDiffuse (uint32 col)
INLINE void | IwGxSetColEmissive (const CIwColour &col)
INLINE void | IwGxSetColEmissive (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
INLINE void | IwGxSetColEmissive (uint32 col)

Detailed Description

Note:
For more information on IwGx Colour, see the Colour section of the IwGx API Documentation.

Enumeration Type Documentation

enum IwGxColourFixed

Enumeration values for fixed colours.

Required Header Files
IwColour.h
Enumerator:
IW_GX_COLOUR_BLACK | black
IW_GX_COLOUR_WHITE | white
IW_GX_COLOUR_GREY | grey
IW_GX_COLOUR_RED | red
IW_GX_COLOUR_GREEN | green
IW_GX_COLOUR_BLUE | blue
IW_GX_COLOUR_MAGENTA | magenta
IW_GX_COLOUR_CYAN | cyan
IW_GX_COLOUR_YELLOW | yellow

Function Documentation

INLINE CIwColour& IwGxGetColAmbient ( )

Gets the current ambient colour.

Returns:
The current ambient colour.
See also:
IwSetColAmbient
Required Header Files
IwGx.h

INLINE CIwColour& IwGxGetColDiffuse ( )

Gets the current diffuse colour.

Returns:
The current diffuse colour.
See also:
IwSetColDiffuse
Required Header Files
IwGx.h

INLINE CIwColour& IwGxGetColEmissive ( )

Gets the current emissive colour.

Returns:
The current emissive colour.
See also:
IwSetColEmissive
Required Header Files
IwGx.h

INLINE const CIwColour& IwGxGetColFixed ( IwGxColourFixed colID )

Gets a fixed colour, using the IwGxColourFixed enumeration list.

Parameters:
colID Fixed colour ID from the IwGxColourFixed enumeration list.
Returns:
Reference to the fixed colour.
Required Header Files
IwColour.h

INLINE void IwGxSetColAmbient ( const CIwColour & col )

Sets the current ambient colour.

Parameters:
col Colour structure.
See also:
IwGxSetColEmissive, IwGxSetColDiffuse
Required Header Files
IwGx.h

INLINE void IwGxSetColAmbient | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a
 | ) |  |

Sets the current ambient colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
See also:
IwGxSetColEmissive, IwGxSetColDiffuse
Required Header Files
IwGx.h

INLINE void IwGxSetColAmbient ( uint32 col )

Sets the current ambient colour.

Parameters:
col Colour, as 32-bit ABGR value.
See also:
IwGxSetColEmissive, IwGxSetColDiffuse
Required Header Files
IwGx.h

INLINE void IwGxSetColDiffuse ( const CIwColour & col )

Sets the current diffuse colour.

Parameters:
col Colour structure.
See also:
IwGxSetColAmbient, IwGxSetColEmissive
Required Header Files
IwGx.h

INLINE void IwGxSetColDiffuse | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a
 | ) |  |

Sets the current diffuse colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
See also:
IwGxSetColAmbient, IwGxSetColEmissive
Required Header Files
IwGx.h

INLINE void IwGxSetColDiffuse ( uint32 col )

Sets the current diffuse colour.

Parameters:
col Colour, as 32-bit ABGR value.
See also:
IwGxSetColAmbient, IwGxSetColEmissive
Required Header Files
IwGx.h

INLINE void IwGxSetColEmissive ( const CIwColour & col )

Sets the current emissive colour.

Parameters:
col Colour structure.
See also:
IwGxSetColAmbient, IwGxSetColDiffuse
Required Header Files
IwGx.h

INLINE void IwGxSetColEmissive | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a
 | ) |  |

Sets the current emissive colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
See also:
IwGxSetColAmbient, IwGxSetColDiffuse
Required Header Files
IwGx.h

INLINE void IwGxSetColEmissive ( uint32 col )

Sets the current emissive colour.

Parameters:
col Colour, as 32-bit ABGR value.
See also:
IwGxSetColAmbient, IwGxSetColDiffuse
Required Header Files
IwGx.h


Airplay API Reference: Debug Drawing

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Debug Drawing >

Debug Drawing
[IwGx API Reference]

Functions

void | IwGxDebugPrimAxes (const CIwMat &m0, int32 len)
void | IwGxDebugPrimBBox (const CIwBBox &s, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT))
void | IwGxDebugPrimCircle (const CIwMat &m0, int32 r, uint32 axis, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT), bool drawRadialLines=false)
void | IwGxDebugPrimCross (const CIwVec3 &v, int16 size=20, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT))
void | IwGxDebugPrimLine (const CIwVec3 &v0, const CIwVec3 &v1, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT))
void | IwGxDebugPrimLineList (CIwVec3 *pVec, int32 n, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT), bool closed=false)
void | IwGxDebugPrimLineStrip (CIwVec3 *pVec, int32 n, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT), bool closed=false)
void | IwGxDebugPrimSBBox (const CIwSBBox &s, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT))
void | IwGxDebugPrimSphere (const CIwSphere &s, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT), bool drawRadialLines=false)
void | IwGxDebugPrimTri (const CIwVec3 &v0, const CIwVec3 &v1, const CIwVec3 &v2, const CIwColour &col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT), bool solid=false)

Detailed Description

This module contains functionality to facilitate debug drawing.

Note:
For more information on how debug drawing works, see the Debug Drawing section of the IwGx API Documentation.

Function Documentation

void IwGxDebugPrimAxes | ( | const CIwMat & | m0,
 |  | int32 | len
 | ) |  |

Displays a debug primitive: a set of local axes. X, Y, Z axes are drawn in red, green, blue respectively.

Parameters:
m0 | The local transform of the axes.
len | The length of the axes.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimBBox | ( | const CIwBBox & | s,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT)
 | ) |  |

Displays a debug primitive: an axis-aligned bounding box in worldspace.

Parameters:
s | The axis-aligned bounding box in worldspace.
col | Colour value.
Required Header Files
IwDebugPrim.h
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimCircle | ( | const CIwMat & | m0,
 |  | int32 | r,
 |  | uint32 | axis,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT),
 |  | bool | drawRadialLines = false
 | ) |  |

Displays a debug primitive: a circle.

Parameters:
m0 | The local transform of the circle.
r | The radius of the circle.
axis | ID of the local axes normal to the circle; X, Y, Z = 0, 1, 2.
col | Colour value.
drawRadialLines | true to draw extra radial lines, else false.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimCross | ( | const CIwVec3 & | v,
 |  | int16 | size = 20,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT)
 | ) |  |

Displays a debug primitive: a billboard cross centred on a point in worldspace.

Parameters:
v | Point in worldspace.
size | Size of cross (default = 20).
col | Colour value.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimLine | ( | const CIwVec3 & | v0,
 |  | const CIwVec3 & | v1,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT)
 | ) |  |

Displays a debug primitive: a line between two points in worldspace.

Parameters:
v0 | Start point in worldspace.
v1 | End point in worldspace.
col | Colour value.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimLineList | ( | CIwVec3 * | pVec,
 |  | int32 | n,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT),
 |  | bool | closed = false
 | ) |  |

Displays a debug primitive: an open or closed line list in worldspace.

Parameters:
pVec | Pointer to array of n points in worldspace.
n | Number of points in line list.
col | Colour value.
closed | true if the line list is closed, else false.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimLineStrip | ( | CIwVec3 * | pVec,
 |  | int32 | n,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT),
 |  | bool | closed = false
 | ) |  |

Displays a debug primitive: an open or closed line strip in worldspace.

Parameters:
pVec | Pointer to array of n points in worldspace.
n | Number of points in line strip.
col | Colour value.
closed | true if the line strip is closed, else false.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimSBBox | ( | const CIwSBBox & | s,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT)
 | ) |  |

Displays a debug primitive: an axis-aligned bounding box in worldspace.

Parameters:
s | The axis-aligned bounding box in worldspace.
col | Colour value.
Required Header Files
IwDebugPrim.h
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimSphere | ( | const CIwSphere & | s,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT),
 |  | bool | drawRadialLines = false
 | ) |  |

Displays a debug primitive: a sphere in worldspace.

Parameters:
s | The sphere in worldspace.
col | Colour value.
drawRadialLines | true to draw extra radial lines, else false.
Required Header Files
IwDebugPrim.h

void IwGxDebugPrimTri | ( | const CIwVec3 & | v0,
 |  | const CIwVec3 & | v1,
 |  | const CIwVec3 & | v2,
 |  | const CIwColour & | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT),
 |  | bool | solid = false
 | ) |  |

Displays a debug primitive: a triangle in worldspace.

Parameters:
v0 | Point 0 of the triangle in worldspace.
v1 | Point 1 of the triangle in worldspace.
v2 | Point 2 of the triangle in worldspace.
col | Colour value.
solid | true if the triangle is to be filled, or false for wireframe.
Required Header Files
IwDebugPrim.h


Airplay API Reference: Data Cache

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Data Cache >

Data Cache
[IwGx API Reference]

Defines

#define | IW_GX_ALLOC(c, n) (c*)IwGxDataAlloc(sizeof(c) * (n))
#define | IW_GX_ALLOC_OBJECTS(c, n) (n > 1 ? new (IwGxDataAlloc(4 + sizeof(c) * (n))) c[n] : new (IwGxDataAlloc(sizeof(c))) c)

Functions

INLINE uint8 * | IwGxDataAlloc (uint32 n)
INLINE int32 | IwGxDataCacheGetFree ()
void | IwGxDataCacheReset ()

Detailed Description

This module provides functionality to allow you to control the data cache.

Note:
For more information on how to use the data cache, see the Data Cache section of the IwGx API Documentation.

Define Documentation

#define IW_GX_ALLOC | ( | c,
 |  | n | ) | (c*)IwGxDataAlloc(sizeof(c) * (n))

Allocates a number of items from the IwGx global data cache.

Parameters:
c | Item type to allocate.
n | Number of items to allocate.
Returns:
Pointer to the allocated block.
See also:
IW_GX_ALLOC_OBJECTS, IwGxDataAlloc, IwGxDataCacheReset, IwGxReset
Note:
This macro should only be used when allocating "dumb" structures which need no initialisation. For example, all types contained within the IwGeom module are valid. For objects which require initialisation (for example, CIwMaterial) you should use IW_GX_ALLOC_OBJECTS.
Required Header Files
IwGx.h

#define IW_GX_ALLOC_OBJECTS | ( | c,
 |  | n | ) | (n > 1 ? new (IwGxDataAlloc(4 + sizeof(c) * (n))) c[n] : new (IwGxDataAlloc(sizeof(c))) c)

Allocates a number of class objects from the IwGx global data cache, and initialises each object.

Parameters:
c | Item type to allocate.
n | Number of items to allocate.
Returns:
Pointer to the allocated block.
See also:
IW_GX_ALLOC, IwGxDataAlloc, IwGxDataCacheReset, IwGxReset
Note:
This macro will call the class constructor on each object. If the object is a "dumb" object which requires no initialisation (for example, CIwSVec3), it is faster to call IW_GX_ALLOC.

Function Documentation

INLINE uint8* IwGxDataAlloc ( uint32 n )

Allocates a block of data from the IwGx global data cache.

Parameters:
n Number of bytes to allocate.
Returns:
Pointer to the allocated block.
See also:
IwGxDataCacheSetSize, IwGxDataCacheReset, IwGxReset
Required Header Files
IwGx.h

INLINE int32 IwGxDataCacheGetFree ( )

Get the number of free bytes remaining in the data cache.

Returns:
Number of free bytes remaining in the data cache.
Required Header Files
IwGx.h

void IwGxDataCacheReset ( )

Resets the IwGx global data cache pointer. This should be done immediately before or after rendering the entire scene. This is called by IwGxReset (and thus IwGxFlush) so there is normally no need to call it explicitly.

See also:
IwGxReset, IwGxDataCacheSetSize
Required Header Files
IwGx.h


Airplay API Reference: Initialisation and Termination

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Initialisation and Termination >

Initialisation and Termination
[IwGx API Reference]

Functions

int | IwGxContextShadowResume ()
int | IwGxContextShadowSuspend ()
void | IwGxInit ()
void | IwGxRegister (IwGxCallback cbid, IwGxCallbackFn fn)
void | IwGxReset ()
INLINE void | IwGxSetContextRestoreCallback (IwGxProgressCallbackFn fn)
void | IwGxTerminate ()
void | IwGxTickUpdate ()
void | IwGxUnRegister (IwGxCallback cbid, IwGxCallbackFn fn)

Detailed Description

This module controls the initialisation and termination of the IwGx module.

Note:
For more information on the initialisation and termination of the IwGx module, see the IwGx Initialisation and Pipeline section of the IwGx API Documentation.

Function Documentation

int IwGxContextShadowResume ( )

If [Gx] UseGLContextShadow is set this function can be used to restore GL. Apps should not make any IwGx or native gl calls between IwGxContextShadowSuspend and IwGxContextShadowResume. IwGxContextShadowSuspend should be called prior to IwGxContextShadowResume to suspend GL. This function will have no effect if [Gx] UseGLContextShadow is not set

Note:
When [Gx] UseGLContextShadow is set Gx will automatically call this function on resume, unless the app has explictly asked to suspend gl
Returns:
value is always 0 and can be ignored.
Required Header Files
IwGx.h

int IwGxContextShadowSuspend ( )

If [Gx] UseGLContextShadow is set this function can be used to suspend GL. Apps should not make any IwGx or native gl calls between IwGxContextShadowSuspend and IwGxContextShadowResume. IwGxContextShadowResume should be called to restore GL. This function will have no effect if [Gx] UseGLContextShadow is not set

Note:
When useGLContextShadow is set Gx will automatically call this function on suspend
Returns:
value is always 0 and can be ignored.
Required Header Files
IwGx.h

void IwGxInit ( )

Initialises IwGx and all subsystems. IwGxInit will initialise IwGx with 'normal' settings. When initialised with this call IwGx will support rendering with the standard SW renderer and with GL HW/SW pipelines (depending on icf settings). See Selective Linking for other initialisation options.

See also:
Selective Linking

IwGxTerminate

Required Header Files
IwGx.h

void IwGxRegister | ( | IwGxCallback | cbid,
 |  | IwGxCallbackFn | fn
 | ) |  |

Register for an IwGx callback. Callbacks are raised for various events.

Parameters:
cbid | The event to recieve a callback for.
fn | The function to callback.
Required Header Files
IwGx.h

void IwGxReset ( )

Resets IwGx caches etc. Should be called prior to rendering any frame. This is called implicitly by IwGxFlush, which is normally sufficient for most applications. This function can be called to 'flush' IwGx without rendering anything.

Required Header Files
IwGx.h

INLINE void IwGxSetContextRestoreCallback ( IwGxProgressCallbackFn fn )

If [Gx] UseGLContextShadow is set this callback will be called during restoration of the context. By default a simple progress bar will display. From the first time the callback is called, any IwGx functionality can be used. However, not all textures will be restored. The application should check the UPLOADED_F flag of any texture is set prior to use. The callback will be called once per texture uploaded, but it is advisable to only update the screen periodically from the callback for maximum speed.

Parameters:
fn IwGxProgressCallbackFn to call
See also:
CIwTexture::GetFlags
Required Header Files
IwGx.h

void IwGxTerminate ( )

Shuts down IwGx and all subsystems.

See also:
IwGxInit
Required Header Files
IwGx.h

void IwGxTickUpdate ( )

Tells IwGx we have performed an application update. This is required for UV animation and some other advanced features.

Required Header Files
IwGx.h

void IwGxUnRegister | ( | IwGxCallback | cbid,
 |  | IwGxCallbackFn | fn
 | ) |  |

Remove an IwGx callback.

Parameters:
cbid | The event to remove a callback for.
fn | The function to remove.
Required Header Files
IwGx.h


Airplay API Reference: Screen Manipulation

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Screen Manipulation >

Screen Manipulation
[IwGx API Reference]

Functions

void | _IwGxSetScreenOrient (IwGxScreenOrient i)
INLINE void | IwGxClear (uint32 clearFlags)
INLINE CIwColour & | IwGxGetColClear ()
INLINE uint32 | IwGxGetDeviceHeight ()
INLINE uint32 | IwGxGetDeviceWidth ()
INLINE uint32 | IwGxGetDisplayHeight ()
INLINE uint32 | IwGxGetDisplayWidth ()
INLINE uint32 | IwGxGetScreenHeight ()
INLINE IwGxScreenOrient | IwGxGetScreenOrient ()
INLINE uint32 | IwGxGetScreenWidth ()
void | IwGxSetColClear (uint8 r, uint8 g, uint8 b, uint8 a)
void | IwGxSetScreenOrient (IwGxScreenOrient i)

Detailed Description

Functions for manipulating screen size, screen orientation, screen clear colour, etc.

Note:
For more information on the screen manipulation, see the Screen Manipulation section of the IwGx API Documentation.

Function Documentation

void _IwGxSetScreenOrient ( IwGxScreenOrient i )

Sets the internal application screen orientation, in 90 degree increments. Do not use directly.

Parameters:
i IwGxScreenOrient enumeration.
See also:
IwGxGetScreenOrient, IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight
Required Header Files
IwGx.h

INLINE void IwGxClear ( uint32 clearFlags )

Clears the screen.

Parameters:
clearFlags Flags specifying which buffers to clear. Currently, should always be IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F.
See also:
IwGxSetColClear
Required Header Files
IwGx.h

INLINE CIwColour& IwGxGetColClear ( )

Gets the current screen clear colour.

Returns:
The current screen clear colour.
See also:
IwSetColClear, IwGxClear
Required Header Files
IwGx.h

INLINE uint32 IwGxGetDeviceHeight ( )

Gets the current device screen height.

Returns:
The current device screen height, in pixels.
See also:
IwGxGetDeviceWidth, IwGxGetScreenWidth, IwGxGetScreenHeight, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

INLINE uint32 IwGxGetDeviceWidth ( )

Gets the current device screen width.

Returns:
The current device screen width, in pixels.
See also:
IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

INLINE uint32 IwGxGetDisplayHeight ( )

Gets the current draw display height.

Note:
that this may differ from the screen height, when a viewport is set.
Returns:
The current display height, in pixels.
See also:
IwGxGetDisplayWidth, IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

INLINE uint32 IwGxGetDisplayWidth ( )

Gets the current draw display width.

Note:
that this may differ from the screen width, when a viewport is set.
Returns:
The current display width, in pixels.
See also:
IwGxGetDisplayHeight, IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

INLINE uint32 IwGxGetScreenHeight ( )

Gets the current application screen height.

Note:
that this may differ from the device screen height, depending on the screen orientation.
Returns:
The current application screen height, in pixels.
See also:
IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

INLINE IwGxScreenOrient IwGxGetScreenOrient ( )

Gets the application screen orientation, in 90 degree increments.

Returns:
IwGxScreenOrient enumeration.
See also:
IwGxSetScreenOrient, IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight
Required Header Files
IwGx.h

INLINE uint32 IwGxGetScreenWidth ( )

Gets the current application screen width.

Note:
This may differ from the device screen width, depending on the screen orientation.
Returns:
The current application screen width, in pixels.
See also:
IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenHeight, IwGxSetScreenOrient, IwGxGetScreenOrient
Required Header Files
IwGx.h

void IwGxSetColClear | ( | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b,
 |  | uint8 | a
 | ) |  |

Sets the screen clear colour.

Parameters:
r | 8-bit red component.
g | 8-bit green component.
b | 8-bit blue component.
a | 8-bit alpha component.
See also:
IwGxGetColClear, IwGxClear
Required Header Files
IwGx.h

void IwGxSetScreenOrient ( IwGxScreenOrient i )

Sets the application screen orientation, in 90 degree increments.

Parameters:
i IwGxScreenOrient enumeration.
See also:
IwGxGetScreenOrient, IwGxGetDeviceWidth, IwGxGetDeviceHeight, IwGxGetScreenWidth, IwGxGetScreenHeight
Required Header Files
IwGx.h


Airplay API Reference: Flag Functions

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Flag Functions >

Flag Functions
[IwGx API Reference]

Functions

INLINE void | IwGxClearDebugFlags (uint32 flags)
INLINE uint32 | IwGxGetDebugFlags ()
INLINE uint32 | IwGxGetFlags ()
INLINE void | IwGxSetDebugFlags (uint32 flags)

Detailed Description

Functions for manipulating the global IwGx flags, or global IwGx debug flags.

Function Documentation

INLINE void IwGxClearDebugFlags ( uint32 flags )

Clears debug flags.

Parameters:
flags Flags to clear.
Required Header Files
IwGx.h

INLINE uint32 IwGxGetDebugFlags ( )

Gets debug flags.

Returns:
Debug flags.
Required Header Files
IwGx.h

INLINE uint32 IwGxGetFlags ( )

Gets general flags.

Returns:
General flags.
Required Header Files
IwGx.h

INLINE void IwGxSetDebugFlags ( uint32 flags )

Sets debug flags.

Parameters:
flags Flags to set.
Required Header Files
IwGx.h


Airplay API Reference: Pipeline Switching

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Pipeline Switching >

Pipeline Switching
[IwGx API Reference]

Functions

INLINE IwGxHWType IwGxGetHWType ()

Detailed Description

IwGx provides custom software implementations for geometry transform, lighting and rasterisation.

Note:
These functions should be called before doing any drawing, otherwise behaviour is undefined.

For more information on the pipeline switching, see the IwGx Initialisation and Pipeline section of the IwGx API Documentation.

Function Documentation

INLINE IwGxHWType IwGxGetHWType ( )

Get the underlying HW platform.

Returns:
IwGxHWType, for example IW_GX_HWTYPE_GL1

void IwGxSetLightingHW ( )

Sets the lighting pipeline to HW.

void IwGxSetLightingSW ( )

Sets the lighting pipeline to SW.

void IwGxSetRasterisationHW ( )

Sets the rasterisation pipeline to HW.

void IwGxSetRasterisationSW ( )

Sets the rasterisation pipeline to SW.

void IwGxSetTransformHW ( )

Sets the transform pipeline to HW.

void IwGxSetTransformSW ( )

Sets the transform pipeline to SW.


Airplay API Reference: Selective Linking

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Selective Linking >

Selective Linking
[IwGx API Reference]

Functions

void | IwGxInit_Base ()
void | IwGxInit_SWRenderEnableBilinearFiltering ()

Detailed Description

IwGx provides smaller builds when not using some features of IwGx. IwGxInit_Base should be called once and once only prior to all other init functions, if called more than once selective link calls following the second call will have no effect. IwGxInit_Base should be followed by at least one SW render or GL render init call. Usually only one SW renderer should be linked in this way. Any SW init call should precede the GL init call (The GL init will exit the application if GL is not available and SW has not been inited).

IwGxInit_Base These functions should be called only once (and after a call to IwGxInit_Base()) before doing any drawing, otherwise behaviour is undefined.

Function Documentation

void IwGxInit_Base ( )

Initialise IwGx's core functionality. This allows smaller builds if you are not using some features of IwGx.

See also:
IwGxInit

IwGxTerminate

Required Header Files
IwGx.h

void IwGxInit_DSRender ( )

Initialises the DS renderer.

void IwGxInit_GL2Render ( )

Initialises the GLES2 renderer with dynamic load balancing (on some platforms transforms will be done by GX).

void IwGxInit_GL2RenderNoSWPipeline ( )

Initialises the GLES2 renderer without load balancing (all transforms done by GLES2 shaders). This option produces a smaller code size.

void IwGxInit_GLRender ( )

Initialises the GL renderer with dynamic load balancing (on some platforms transforms will be done by GX).

void IwGxInit_GLRenderNoSWPipeline ( )

Initialises the GL renderer without load balancing (all transforms done by GL). This option produces a smaller code size.

void IwGxInit_SWRenderEnableBilinearFiltering ( )

Initialises the Scanline SW renderer to enable bilinear texture filtering This must only be called after all other IwGxInit_SW pipeline calls.

void IwGxInit_SWRenderScanLine ( )

Initialises the Scanline SW renderer with all options.

void IwGxInit_SWRenderScanLineNoEnvMap ( )

Initialises the Scanline SW renderer with Rgb lighting.

void IwGxInit_SWRenderScanLineNoRgb ( )

Initialises the Scanline SW renderer with R only intensity lighting and EnvMaping.

void IwGxInit_SWRenderScanLineNoRgbNoEnvMap ( )

Initialises the Scanline SW renderer with R only intensity lighting.

void IwGxInit_SWRenderStandard ( )

Initialises the Standard SW renderer with all options.

void IwGxInit_SWRenderStandardNoEnvMap ( )

Initialises the Standard SW renderer with Rgb lighting.

void IwGxInit_SWRenderStandardNoRgb ( )

Initialises the Standard SW renderer with R only intensity lighting and EnvMaping.

void IwGxInit_SWRenderStandardNoRgbNoEnvMap ( )

Initialises the Standard SW renderer with R only intensity lighting.

void IwGxInit_SWRenderStandardZBuffered ( )

Initialises the Standard ZBuffered SW renderer with all options.

void IwGxInit_SWRenderStandardZBufferedNoEnvMap ( )

Initialises the Standard ZBuffered SW renderer with Rgb lighting.

void IwGxInit_SWRenderStandardZBufferedNoRgb ( )

Initialises the Standard ZBuffered SW renderer with R only intensity lighting and EnvMaping.

void IwGxInit_SWRenderStandardZBufferedNoRgbNoEnvMap ( )

Initialises the Standard ZBuffered SW renderer with R only intensity lighting.


Airplay API Reference: Z-Depth Control

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Z-Depth Control >

Z-Depth Control
[IwGx API Reference]

Functions

INLINE int32 | IwGxGetZDepthFixed ()
INLINE int32 | IwGxGetZDepthOfs ()
INLINE int32 | IwGxGetZDepthOfsBase ()
INLINE void | IwGxSetZDepthFixed (int32 val)
INLINE void | IwGxSetZDepthOfs (int32 ofs)
INLINE void | IwGxSetZDepthOfsBase (int32 ofs)

Detailed Description

This module allows you to specify a z-depth offset, or fixed z-depth value, to be used for all primitives at the next call to IwGxDrawPrims().

Note:
For more information on Z-Depth Control, see the Z-Depth section of the IwGx API Documentation.

Function Documentation

INLINE int32 IwGxGetZDepthFixed ( )

Gets the geometry z-depth value. A value of -1 indicates not to use a fixed z-depth.

Returns:
Fixed value to use as geometry's z-depth position.
See also:
IwGxGetZDepthFixed, IwGxSetZDepthOfs, IwGxGetZDepthOfs
Required Header Files
IwGx.h

INLINE int32 IwGxGetZDepthOfs ( )

Gets the geometry z-depth offset. A value of 0 indicates no offset.

Returns:
Offset to add to geometry's z-depth position.
See also:
IwGxSetZDepthOfs, IwGxSetZDepthFixed, IwGxGetZDepthFixed
Required Header Files
IwGx.h

INLINE int32 IwGxGetZDepthOfsBase ( )

Gets the geometry z-depth offset base. A value of 0 indicates no offset.

Returns:
Offset to add to all z-depth offsets, in viewspace.
See also:
IwGxSetZDepthOfs, IwGxGetZDepthOfs, IwGxSetZDepthOfsBase, IwGxSetZDepthFixed, IwGxGetzDepthFixed
Required Header Files
IwGx.h

INLINE void IwGxSetZDepthFixed ( int32 val )

Sets the geometry fixed z-depth value. A value of -1 indicates not to use a fixed z-depth.

Parameters:
ofs Fixed value to use as geometry's z-depth position.
See also:
IwGxGetZDepthOfs, IwGxSetZDepthOfs, IwGxGetZDepthFixed
Required Header Files
IwGx.h

INLINE void IwGxSetZDepthOfs ( int32 ofs )

Sets the geometry z-depth offset. A value of 0 indicates no offset.

Parameters:
ofs Offset to add to geometry's z-depth position, in viewspace.
See also:
IwGxGetZDepthOfs, IwGxSetZDepthFixed, IwGxGetzDepthFixed
Required Header Files
IwGx.h

INLINE void IwGxSetZDepthOfsBase ( int32 ofs )

Sets the geometry z-depth offset base. A value of 0 indicates no offset.

Parameters:
ofs Offset to add to all z-depth offsets, in viewspace.
See also:
IwGxSetZDepthOfs, IwGxGetZDepthOfs, IwGxGetZDepthOfsBase, IwGxSetZDepthFixed, IwGxGetzDepthFixed
Required Header Files
IwGx.h


Airplay API Reference: Fog Control

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Fog Control >

Fog Control
[IwGx API Reference]

Functions

void | IwGxFogOff ()
void | IwGxFogOn ()
INLINE CIwColour & | IwGxGetFogColour ()
INLINE int32 | IwGxGetFogFarZ ()
INLINE int32 | IwGxGetFogNearZ ()
void | IwGxSetFogCol (const CIwColour &col)
void | IwGxSetFogFarZNearZ (int32 fz, int32 nz)

Detailed Description

Certain custom hardware may allow polygons to be affected by fog. Currently these functions have no effect when using software rasterisation.

Note:
For more information on the IwGx API, see the IwGx API Documentation.

Function Documentation

void IwGxFogOff ( )

Turns fog off. This can be set per piece of geometry.

Note:
Fogging does not affect screenspace geometry
See also:
IwGxFogOn
Required Header Files
IwGx.h

void IwGxFogOn ( )

Turns fog on. This can be set per piece of geometry.

Note:
Fogging does not affect screenspace geometry
See also:
IwGxFogOff
Required Header Files
IwGx.h

INLINE CIwColour& IwGxGetFogColour ( )

Gets the fog colour.

Returns:
The current fog colour.
See also:
IwGxSetFogColour
Required Header Files
IwGx.h

INLINE int32 IwGxGetFogFarZ ( )

Gets the viewspace z at which fog ends.

Returns:
The current viewspace z value at which fog ends.
See also:
IwGxSetFogFarZNearZ
Required Header Files
IwGx.h

INLINE int32 IwGxGetFogNearZ ( )

Gets the viewspace z at which fog starts.

Returns:
The current viewspace z value at which fog starts.
See also:
IwGxSetFogFarZNearZ
Required Header Files
IwGx.h

void IwGxSetFogCol ( const CIwColour & col )

Set fog colour.

Sets the fog colour. This setting affects the scene as a whole and cannot be set on a per geometry basis

Parameters:
col Fog colour value.
See also:
IwGxSetFogStartZ, IwGxSetFogEndZ, IwGxFogOn, IwGxFogOff

void IwGxSetFogFarZNearZ | ( | int32 | fz,
 |  | int32 | nz
 | ) |  |

Sets the viewspace z at which fog starts and ends. This setting affects the scene as a whole and cannot be set on a per geometry basis

Parameters:
fz | Viewspace z value at which fog ends.
nz | Viewspace z value at which fog starts.
See also:
IwGxGetFogNearZ, IwGxGetFogFarZ
Required Header Files
IwGx.h


Airplay API Reference: Vertex Streams

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Vertex Streams >

Vertex Streams
[IwGx API Reference]

Functions

INLINE int32 | IwGxGetScreenSpaceSlot ()
INLINE const CIwVec3 & | IwGxGetViewSpaceOrg ()
INLINE void | IwGxSetScreenSpaceOrg (const CIwSVec2 *pOrg)
INLINE void | IwGxSetScreenSpaceSlot (int32 slotID)
INLINE void | IwGxSetVertStream (CIwSVec3 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamModelSpace (CIwSVec3 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamScreenSpace (CIwSVec2 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamScreenSpaceSubPixel (CIwSVec2 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamViewSpace (CIwVec3 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamViewSpace (CIwSVec3 *pVec, uint32 numVerts)
INLINE void | IwGxSetVertStreamWorldSpace (CIwSVec3 *pVec, uint32 numVerts)
INLINE void | IwGxSetViewSpaceOrg (const CIwVec3 *pOrg)
INLINE void | IwGxSetViewSpaceOrg (const CIwSVec3 *pOrg)

Detailed Description

There are 4 different coordinate systems in which you can specify the vertex stream: WorldSpace, ModelSpace, ViewSpace and ScreenSpace.

Note:
For more information on vertex streams, see the Streams section of the IwGx API Documentation.

Function Documentation

INLINE int32 IwGxGetScreenSpaceSlot ( )

Gets the slot for screenspace drawing. Positive values refer to the "front" slots - negative values refer to the "back" slots (the two's complement of a negative value is the "back" slot ID).

Returns:
The screenspace slot ID to draw to.
See also:
IwGxSetScreenSpaceSlot, IwGxSetScreenSpaceOrg, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE const CIwVec3& IwGxGetViewSpaceOrg ( )

Gets the viewspace origin for viewspace vertex streams.

Returns:
The current viewspace origin.
See also:
IwGxSetViewSpaceOrg, IwGxSetVertStreamViewSpace
Required Header Files
IwGx.h

INLINE void IwGxSetScreenSpaceOrg ( const CIwSVec2 * pOrg )

Sets the screenspace origin for screenspace vertex streams.

Parameters:
pOrg Pointer to the screenspace origin.
See also:
IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetScreenSpaceSlot ( int32 slotID )

Sets the slot for screenspace drawing. Positive values refer to the "front" slots - negative values refer to the "back" slots (the two's complement of a negative value is the "back" slot ID).

Parameters:
slotID The screenspace slot ID to draw to.
See also:
IwGxGetScreenSpaceSlot, IwGxSetScreenSpaceOrg, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStream | ( | CIwSVec3 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Equivalent to IwGxSetVertStreamModelSpace. Sets the geometry vertex stream, in modelspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamViewSpace, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamModelSpace | ( | CIwSVec3 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in modelspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamViewSpace, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamScreenSpace | ( | CIwSVec2 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in screenspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamModelSpace, IwGxSetVertStreamViewSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamScreenSpaceSubPixel | ( | CIwSVec2 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in sub pixel screenspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamModelSpace, IwGxSetVertStreamViewSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamViewSpace | ( | CIwVec3 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in viewspace, using 32-bit vertices (1.19.12 format).

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamModelSpace, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamViewSpace | ( | CIwSVec3 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in viewspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamWorldSpace, IwGxSetVertStreamModelSpace, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetVertStreamWorldSpace | ( | CIwSVec3 * | pVec,
 |  | uint32 | numVerts
 | ) |  |

Sets the geometry vertex stream, in worldspace.

Parameters:
pVec | Pointer to the vertex stream.
numVerts | Number of vertices in the stream.
See also:
IwGxSetVertStreamModelSpace, IwGxSetVertStreamViewSpace, IwGxSetVertStreamScreenSpace
Required Header Files
IwGx.h

INLINE void IwGxSetViewSpaceOrg ( const CIwVec3 * pOrg )

Sets the viewspace origin for viewspace vertex streams.

Parameters:
pOrg Pointer to the viewspace origin.
See also:
IwGxGetViewSpaceOrg, IwGxSetVertStreamViewSpace
Required Header Files
IwGx.h

INLINE void IwGxSetViewSpaceOrg ( const CIwSVec3 * pOrg )

Sets the viewspace origin for viewspace vertex streams.

Parameters:
pOrg Pointer to the viewspace origin.
See also:
IwGxGetViewSpaceOrg, IwGxSetVertStreamViewSpace
Required Header Files
IwGx.h


Airplay API Reference: Normal Streams

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Normal Streams >

Normal Streams
[IwGx API Reference]

Functions

void IwGxSetNormStream (CIwSVec3 *pVec, uint32 numNorms=0)

Detailed Description

Note:
For more information on normal streams, see the Streams section of the IwGx API Documentation.

Function Documentation

void IwGxSetNormStream | ( | CIwSVec3 * | pVec,
 |  | uint32 | numNorms = 0
 | ) |  |

Sets the geometry vertex normal stream, in modelspace.

Parameters:
pVec | Pointer to the vertex normal stream, or NULL to clear the stream.
numVerts | Number of vertex normals in the stream.
Note:
To disable diffuse lighting, clear the normal stream by passing in NULL.
Required Header Files
IwGx.h


Airplay API Reference: Colour Streams

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Colour Streams >

Colour Streams
[IwGx API Reference]

Functions

void IwGxSetColStream (CIwColour *pCol, uint32 numCols=0)

Detailed Description

Note:
For more information on colour streams, see the Streams section of the IwGx API Documentation.

Function Documentation

void IwGxSetColStream | ( | CIwColour * | pCol,
 |  | uint32 | numCols = 0
 | ) |  |

Sets the geometry vertex colour stream.

Parameters:
pCol | Pointer to the vertex colour stream, or NULL to clear the stream.
numCols | Number of vertex colours in the stream.
Required Header Files
Note:
To disable the vertex colour stream, pass in NULL. IwGx.h


Airplay API Reference: UV Streams

Airplay API Reference > IwGx API Documentation > IwGx API Reference > UV Streams >

UV Streams
[IwGx API Reference]

Functions

INLINE CIwSVec2 & | _IwGxGetUVOfs ()
INLINE void | IwGxSetUVOfs (const CIwSVec2 *pOfs)
void | IwGxSetUVStream (CIwSVec2 *pUV, int32 stream_id=0)

Detailed Description

Note:
For more information on UV streams, see the Streams section of the IwGx API Documentation.

Function Documentation

INLINE CIwSVec2& _IwGxGetUVOfs ( )

Gets the current IV offset.

Returns:
A reference to the current UV offset, held by the CIwGxState.
Required Header Files
IwGx.h

INLINE void IwGxSetUVOfs ( const CIwSVec2 * pOfs )

Sets the current UV offset.

Parameters:
pOfs Pointer to a UV offset to set.
Required Header Files
IwGx.h

void IwGxSetUVStream | ( | CIwSVec2 * | pUV,
 |  | int32 | stream_id = 0
 | ) |  |

Sets the geometry UV stream.

Parameters:
pUV Pointer to the geometry UV stream.
Required Header Files
IwGx.h


Airplay API Reference: Rasterisation Pipeline

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Rasterisation Pipeline >

Rasterisation Pipeline
[IwGx API Reference]

Functions

INLINE void | IwGxDrawPrims (IwGxPrimType primType, uint16 *pInds, uint32 numInds)
void | IwGxDrawRectScreenSpace (const CIwSVec2 *pXY, const CIwSVec2 *pDXY, const CIwSVec2 *pUV, const CIwSVec2 *pDUV, const CIwColour *pCols)
void | IwGxDrawRectScreenSpace (const CIwSVec2 *pXY, const CIwSVec2 *pWH, const CIwColour *pCols)
void | IwGxDrawRectScreenSpace (const CIwSVec2 *pXY, const CIwSVec2 *pWH, const CIwSVec2 *pUV, const CIwSVec2 *pDUV)
void | IwGxDrawRectScreenSpace (const CIwSVec2 *pXY, const CIwSVec2 *pWH)
void | IwGxFlush ()
INLINE uint32 | IwGxGetFrameRate ()
INLINE void | IwGxSetSortMode (IwGxSortMode type)
void | IwGxSwapBuffers ()

Detailed Description

Note:
For more information on Rasterisation, see the Rasterisation section of the IwGx API Documentation.

Function Documentation

INLINE void IwGxDrawPrims | ( | IwGxPrimType | primType,
 |  | uint16 * | pInds,
 |  | uint32 | numInds
 | ) |  |

Draws geometry by stiching together geometry streams, in various ways, from a supplied index stream.

Parameters:
primType | Enumerated type specifying whether to create triangles, quads, lines, etc.
pInds | Pointer to index stream.
numInds | Number of indices in stream.
See also:
IwGxFlush, IwGxSwapBuffers
Required Header Files
IwGx.h

void IwGxDrawRectScreenSpace | ( | const CIwSVec2 * | pXY,
 |  | const CIwSVec2 * | pDXY,
 |  | const CIwSVec2 * | pUV,
 |  | const CIwSVec2 * | pDUV,
 |  | const CIwColour * | pCols
 | ) |  |

Draws a screenspace rectangle, specifying shape, UVs and vertex colours. Colours should be defined in the order topleft, bottomleft, topright, bottomright.

void IwGxDrawRectScreenSpace | ( | const CIwSVec2 * | pXY,
 |  | const CIwSVec2 * | pWH,
 |  | const CIwColour * | pCols
 | ) |  |

Draws a screenspace rectangle, specifying shape and vertex colours.

Parameters:
pXY | Pointer to a 2D screenspace coordinate specifying the rectangle top left.
pWH | Pointer to a 2D screenspace coordinate specifying the rectangle width and height.
pCols | Pointer to 4 vertex colours, defined in the order top-left, bottom-left, top-right, bottom-right.
Required Header Files
IwGx.h

void IwGxDrawRectScreenSpace | ( | const CIwSVec2 * | pXY,
 |  | const CIwSVec2 * | pWH,
 |  | const CIwSVec2 * | pUV,
 |  | const CIwSVec2 * | pDUV
 | ) |  |

Draws a screenspace rectangle, specifying shape and UV span.

Parameters:
pXY | Pointer to a 2D screenspace coordinate specifying the rectangle top left.
pWH | Pointer to a 2D screenspace coordinate specifying the rectangle width and height.
pUV | Pointer to the UV coordinate at the top left.
pDUV | Pointer to the UV span.
Required Header Files
IwGx.h

void IwGxDrawRectScreenSpace | ( | const CIwSVec2 * | pXY,
 |  | const CIwSVec2 * | pWH
 | ) |  |

Draws a screenspace rectangle, specifying shape only.

Parameters:
pXY | Pointer to a 2D screenspace coordinate specifying the rectangle top left.
pWH | Pointer to a 2D screenspace coordinate specifying the rectangle width and height.
Required Header Files
IwGx.h

void IwGxFlush ( )

Flushes any cached geometry to the surface.

See also:
IwGxDrawPrims, IwGxSwapBuffers
Required Header Files
IwGx.h

INLINE uint32 IwGxGetFrameRate ( )

Gets Frames per Second This value is smoothed over several frames For a more accurate measure of rendering speed use IwGetGxState()->m_MsPerFrame

Required Header Files
IwGx.h

INLINE void IwGxSetSortMode ( IwGxSortMode type )

Sets geometry sorting type.

Required Header Files
IwGx.h

void IwGxSwapBuffers ( )

Flips the double-buffers.

See also:
IwGxFlush, IwGxSwapBuffers
Required Header Files
IwGx.h


Airplay API Reference: Transform Pipeline

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Transform Pipeline >

Transform Pipeline
[IwGx API Reference]

Functions

void | IwGxClearScissorScreenSpace ()
INLINE int32 | IwGxGetFarZ ()
INLINE CIwMat & | IwGxGetModelMatrix ()
INLINE CIwMat & | IwGxGetModelViewClipMatrix ()
INLINE CIwMat & | IwGxGetModelViewMatrix ()
INLINE int32 | IwGxGetNearZ ()
INLINE int32 | IwGxGetPerspMul ()
CIwRect IwGxGetScissorScreenSpace ()
INLINE CIwMat & | IwGxGetViewMatrix ()
INLINE CIwMat & | IwGxGetWorldViewClipMatrix ()
INLINE CIwMat & | IwGxGetWorldViewMatrix ()
void | IwGxSetFarZNearZ (int32 ifar, int32 inear)
void | IwGxSetModelMatrix (const CIwMat *pMat, bool rotationIsIdentity=false)
void | IwGxSetPerspMul (int32 pm)
void | IwGxSetScissorScreenSpace (int32 x, int32 y, int32 w, int32 h)
void | IwGxSetViewMatrix (const CIwMat *pMat)
void | IwGxUpdateModelViewMatrix ()
void | IwGxUpdateWorldViewMatrix ()
INLINE void | IwGxWorldToViewXYZ (int16 &vx, int16 &vy, int16 &vz, const CIwVec3 &worldPos)

Detailed Description

Note:
For more information on Transforms, see the Transform section of the IwGx API Documentation.

Function Documentation

void IwGxClearScissorScreenSpace ( )

Reset the screen space scissor rectangle to default (the entire screen).

Required Header Files
IwGx.h

INLINE int32 IwGxGetFarZ ( )

Gets the current far plane distance.

Returns:
The current distance from camera to the far clipping plane.
See also:
IwGxSetFarZNearZ
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetModelMatrix ( )

Gets the current model transform.

Returns:
A reference to the current model transform, held by the CIwGxState.
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetModelViewClipMatrix ( )

Gets the current ModelViewClip transform.

Returns:
A reference to the current ModelViewClip transform, held by the CIwGxState.
Note:
The ModelViewClip matrix can be used to transform points from modelspace to clipspace. Clipping functions such as IwGxClipVec() take inputs in clipspace.
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetModelViewMatrix ( )

Gets the current ModelView transform.

Returns:
A reference to the current ModelView transform, held by the CIwGxState.
Note:
The ModelView matrix can be used to transform points from modelspace to viewspace. It is the transpose (inverse) of the view transform, multiplied by the model transform.
Required Header Files
IwGx.h

INLINE int32 IwGxGetNearZ ( )

Gets the current near plane distance.

Returns:
The current distance from camera to the near clipping plane.
See also:
IwGxSetFarZNearZ
Required Header Files
IwGx.h

INLINE int32 IwGxGetPerspMul ( )

Gets the current perspective multiple (the distance from the camera to the viewing plane).

Returns:
The current distance from camera to the near clipping plane.
See also:
IwGxSetPerspMul
Required Header Files
IwGx.h

CIwRect IwGxGetScissorScreenSpace ( )

Get the current screen space scissor rectangle

Returns:
The current screen space scissor rectangle
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetViewMatrix ( )

Gets the current view transform.

Returns:
A reference to the current view transform, held by the CIwGxState.
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetWorldViewClipMatrix ( )

Gets the current WorldViewClip transform.

Returns:
A reference to the current WorldViewClip transform, held by the CIwGxState.
Note:
The WorldViewClip matrix can be used to transform points from worldspace to clipspace. Clipping functions such as IwGxClipVec() take inputs in clipspace.
Required Header Files
IwGx.h

INLINE CIwMat& IwGxGetWorldViewMatrix ( )

Gets the current WorldView transform.

Returns:
A reference to the current WorldView transform, held by the CIwGxState.
Note:
The WorldView matrix can be used to transform points from worldspace to viewspace. It is the transpose (inverse) of the view transform.
Required Header Files
IwGx.h

void IwGxSetFarZNearZ | ( | int32 | ifar,
 |  | int32 | inear
 | ) |  |

Sets the far and near plane distances.

Parameters:
ifar | The distance from camera to the far clipping plane.
inear | The distance from camera to the near clipping plane.
See also:
IwGxSetPerspMul
Required Header Files
IwGx.h

void IwGxSetModelMatrix | ( | const CIwMat * | pMat,
 |  | bool | rotationIsIdentity = false
 | ) |  |

Sets the model transform. Implicitly calls IwGxUpdateModelViewMatrix to update the internal ModelView transform.

Parameters:
pMat | Pointer to the model transform to set.
rotationIsIdentity | true only if the model transform is identity.
See also:
IwGxSetViewMatrix, IwGxUpdateModelViewMatrix
Required Header Files
IwGx.h

void IwGxSetPerspMul ( int32 pm )

Sets the perspective multiple (the distance from the camera to the viewing plane). This is one way of setting the camera field of view.

Parameters:
pm The distance from the camera to the viewing plane.
See also:
IwGxSetFarZNearZ, IwGxGetPerspMul
Required Header Files
IwGx.h

void IwGxSetScissorScreenSpace | ( | int32 | x,
 |  | int32 | y,
 |  | int32 | w,
 |  | int32 | h
 | ) |  |

Specify a scissor rectangle for use with screen space primitives. Pixels falling outside the rectangle will be discarded.

Parameters:
x | The x-coordinate of the top left-hand corner of the scissor rectangle (in screen space coordinates)
y | The y-coordinate of the bottom right-hand corner of the scissor rectangle (in screen space coordinates)
w | The width of the scissor rectangle.
h | The height of the scissor rectangle.
Required Header Files
IwGx.h

void IwGxSetViewMatrix ( const CIwMat * pMat )

Sets the view (camera) transform. Implicitly calls IwGxUpdateWorldViewMatrix to update the internal WorldView transform.

Parameters:
pMat Pointer to the view transform to set.
See also:
IwGxUpdateWorldViewMatrix
Required Header Files
IwGx.h

void IwGxUpdateModelViewMatrix ( )

Explicitly updates the internal ModelView transform.

See also:
IwGxSetViewMatrix, IwGxSetModelMatrix
Required Header Files
IwGx.h

void IwGxUpdateWorldViewMatrix ( )

Explicitly updates the internal WorldView transform.

See also:
IwGxSetViewMatrix
Required Header Files
IwGx.h

INLINE void IwGxWorldToViewXYZ | ( | int16 & | vx,
 |  | int16 & | vy,
 |  | int16 & | vz,
 |  | const CIwVec3 & | worldPos
 | ) |  |

Translates a vector from worldspace to three 16-bit fixed point coordinates in viewspace.

Parameters:
vx | Reference to the resulting x-coordinate.
vy | Reference to the resulting y-coordinate.
vz | Reference to the resulting z-coordinate.
worldPos | Vector in worldspace.
Note:
Does overflow checking in debug mode.
Required Header Files
IwGx.h


Airplay API Reference: Lighting Pipeline

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Lighting Pipeline >

Lighting Pipeline
[IwGx API Reference]

Functions

INLINE CIwColour & | IwGxGetLightCol (uint32 id)
INLINE CIwSVec3 & | IwGxGetLightDirn (uint32 id)
INLINE CIwSVec3 & | IwGxGetLightPos (uint32 id)
INLINE IwGxLightType | IwGxGetLightType (uint32 id)
INLINE void | IwGxLightingAmbient (bool state)
INLINE void | IwGxLightingDiffuse (bool state)
INLINE void | IwGxLightingEmissive (bool state)
INLINE void | IwGxLightingOff ()
INLINE void | IwGxLightingOn ()
INLINE void | IwGxLightingSpecular (bool state)
void | IwGxSetLightCol (uint32 id, const CIwColour *pCol)
void | IwGxSetLightCol (uint32 id, uint8 r, uint8 g, uint8 b)
void | IwGxSetLightDirn (uint32 id, const CIwSVec3 *pVec)
INLINE void | IwGxSetLightPos (uint32 id, const CIwSVec3 *pVec)
void | IwGxSetLightSpecularCol (uint32 id, const CIwColour *pCol)
void | IwGxSetLightSpecularCol (uint32 id, uint8 r, uint8 g, uint8 b, uint8 a)
INLINE void | IwGxSetLightType (uint32 id, IwGxLightType type)

Detailed Description

Note:
For more information on Lighting, see the Lighting section of the IwGx API Documentation.
Remarks:
For a full description of the IwGx lighting model, see CIwMaterial.

Function Documentation

INLINE CIwColour& IwGxGetLightCol ( uint32 id )

Gets a light colour.

Parameters:
id ID of the light.
Returns:
The light colour.
See also:
IwGxSetLightCol
Required Header Files
IwGx.h

INLINE CIwSVec3& IwGxGetLightDirn ( uint32 id )

Gets a light direction.

Parameters:
id ID of the light.
Returns:
Direction of light, in worldspace.
See also:
IwGxSetLightDirn
Required Header Files
IwGx.h

INLINE CIwSVec3& IwGxGetLightPos ( uint32 id )

Gets a light position.

Parameters:
id ID of the light.
Returns:
Position of light, in worldspace.
See also:
IwGxSetLightPos
Required Header Files
IwGx.h

INLINE IwGxLightType IwGxGetLightType ( uint32 id )

Gets a light type.

Parameters:
id ID of the light.
Returns:
The light type.
See also:
IwGxSetLightType
Required Header Files
IwGx.h

INLINE void IwGxLightingAmbient ( bool state )

Enables or disables use of ambient colours in lighting calculations.

See also:
IwGxLightingEmissive, IwGxLightingDiffuse
Required Header Files
IwGx.h

INLINE void IwGxLightingDiffuse ( bool state )

Enables or disables use of diffuse colours in lighting calculations.

See also:
IwGxLightingEmissive, IwGxLightingAmbient
Required Header Files
IwGx.h

INLINE void IwGxLightingEmissive ( bool state )

Enables or disables use of emissive colours in lighting calculations.

See also:
IwGxLightingAmbient, IwGxLightingDiffuse
Required Header Files
IwGx.h

INLINE void IwGxLightingOff ( )

Disables emissive, ambient and diffuse lighting calculations.

See also:
IwGxLightingOn, IwGxLightingEmissive, IwGxLightingAmbient, IwGxLightingDiffuse
Required Header Files
IwGx.h

INLINE void IwGxLightingOn ( )

Enables emissive, ambient and diffuse lighting calculations.

See also:
IwGxLightingOff, IwGxLightingEmissive, IwGxLightingAmbient, IwGxLightingDiffuse
Required Header Files
IwGx.h

INLINE void IwGxLightingSpecular ( bool state )

Enables or disables use of specular colours in lighting calculations. Specular lighting is only available in HW lighting mode.

See also:
IwGxLightingEmissive, IwGxLightingAmbient
Required Header Files
IwGx.h

void IwGxSetLightCol | ( | uint32 | id,
 |  | const CIwColour * | pCol
 | ) |  |

Sets a light colour.

Parameters:
id | ID of the light.
col | Colour to set.
See also:
IwGxGetLightCol, IwGxSetLightType, IwGxSetLightPos, IwGxSetLightDirn
Required Header Files
IwGx.h

void IwGxSetLightCol | ( | uint32 | id,
 |  | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b
 | ) |  |

Sets a light colour.

Parameters:
id | ID of the light.
r | 8-bit red component.
g | 8-bit green component.
b | 8-bit blue component.
See also:
IwGxGetLightCol, IwGxSetLightType, IwGxSetLightPos, IwGxSetLightDirn
Required Header Files
IwGx.h

void IwGxSetLightDirn | ( | uint32 | id,
 |  | const CIwSVec3 * | pVec
 | ) |  |

Sets a light direction.

Parameters:
id | ID of the light.
pVec | Pointer to normalised light direction, in worldspace.
See also:
IwGxGetLightDirn, IwGxSetLightType, IwGxSetLightCol, IwGxSetLightPos
Required Header Files
IwGx.h

INLINE void IwGxSetLightPos | ( | uint32 | id,
 |  | const CIwSVec3 * | pVec
 | ) |  |

Sets a light position.

Parameters:
id | ID of the light.
pVec | Pointer to position of light, in worldspace.
See also:
IwGxGetLightPos, IwGxSetLightType, IwGxSetLightCol, IwGxSetLightDirn
Required Header Files
IwGx.h

void IwGxSetLightSpecularCol | ( | uint32 | id,
 |  | const CIwColour * | pCol
 | ) |  |

Sets a light specular colour. Specular colour will only take effect for IW_GX_LIGHT_DIFFUSE. Default is white.

Parameters:
id | ID of the light.
col | Colour to set.
See also:
IwGxGetLightCol, IwGxSetLightType, IwGxSetLightPos, IwGxSetLightDirn
Required Header Files
IwGx.h

void IwGxSetLightSpecularCol | ( | uint32 | id,
 |  | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b,
 |  | uint8 | a
 | ) |  |

Sets a light specular colour. Specular colour will only take effect for IW_GX_LIGHT_DIFFUSE. Default is white.

Parameters:
id | ID of the light.
r | 8-bit red component.
g | 8-bit green component.
b | 8-bit blue component.
a | 8-bit alpha component.
See also:
IwGxGetLightCol, IwGxSetLightType, IwGxSetLightPos, IwGxSetLightDirn
Required Header Files
IwGx.h

INLINE void IwGxSetLightType | ( | uint32 | id,
 |  | IwGxLightType | type
 | ) |  |

Sets a light type.

Parameters:
id ID of the light.
type Type of the light, which can be one of the following:
  • IW_GX_LIGHT_UNUSED Slot is unused.
  • IW_GX_LIGHT_AMBIENT Ambient light.
  • IW_GX_LIGHT_DIFFUSE Diffuse light.
See also:
IwGxGetLightType, IwGxSetLightCol, IwGxSetLightPos, IwGxSetLightDirn
Required Header Files
IwGx.h


Airplay API Reference: Textures

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Textures >

Textures
[IwGx API Reference]

Data Structures

class | CIwTexture

Functions

void | IwGxAddPaletteSharing (uint32 flags)
void | IwGxGetVRAMPointer (char *&ptr)
uint32 | IwGxGetVRAMSize ()
void | IwGxMipMappingOff ()
void | IwGxMipMappingOn ()
void | IwGxRemovePaletteSharing (uint32 flags)
void | IwGxSetPalette16Tint (uint8 r, uint8 g, uint8 b, bool noClear)

Detailed Description

Note:
For more information on Textures, see the Texture section of the IwGx API Documentation.

Function Documentation

void IwGxAddPaletteSharing ( uint32 flags )

Turns on palette sharing for 4-bit or 8-bit palettised textures. Palette sharing allows textures that share identical palettes to reference the same palette.

Parameters:
flags Specify either IW_GX_SHARE_4BIT_PALS or IW_GX_SHARE_8BIT_PALS
See also:
IwGxRemovePaletteSharing
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

void IwGxGetVRAMPointer ( char *& ptr )

Sets a pointer to the start of contiguous texture memory 'VRAM'.

Warning:
This feature should never be used to try to access or change texture images; for this use the existing GX interface.

Never call this function until IwGxInit has been called or the address will be invalid.

Always check to make sure that the VRAM size is greater than 0 if you plan to use this feature.
Provided there are no currently uploaded textures, VRAM contains no useful/critical information and can be temporarily re-claimed. If there are remaining textures then writing over VRAM will trash the image data, overunning the bounds will also have undefined effects.

Parameters:
ptr the pointer to set with the adress of VRAM
Note:
Only affects software rasterisation.

uint32 IwGxGetVRAMSize ( )

Gets the number of bytes avaliable in VRAM.

Returns:
number of bytes
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

void IwGxMipMappingOff ( )

Disables use of mipmaps across the entire scene.

See also:
IwGxMipMappingOn
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

void IwGxMipMappingOn ( )

Enables use of mipmaps across the entire scene.

See also:
IwGxMipMappingOff
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

void IwGxRemovePaletteSharing ( uint32 flags )

Turns off palette sharing for 4-bit or 8-bit palettised textures. Palette sharing allows textures that share identical palettes to reference the same palette.

Parameters:
flags Specify either IW_GX_SHARE_4BIT_PALS or IW_GX_SHARE_8BIT_PALS
See also:
IwGxAddPaletteSharing
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

void IwGxSetPalette16Tint | ( | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b,
 |  | bool | noClear
 | ) |  |

Sets the lighting colour on the palettes of the 16 colour textures.

Parameters:
r | red component of coloured light.
g | green component of coloured light.
b | blue component of coloured light.
noClear | Clear the cached palettes.
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h


Airplay API Reference: Materials

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Materials >

Materials
[IwGx API Reference]

Data Structures

class | CIwMatAnim
class | CIwMaterial

Functions

CIwMaterial * IW_GX_ALLOC_MATERIAL ()
INLINE void | IwGxClearMaterialCopyState (IwGxMaterialCopyState cs)
INLINE CIwMaterial * | IwGxGetMaterial ()
INLINE CIwMaterial * | IwGxGetMaterialFixed ()
INLINE CIwMaterial * | IwGxGetMaterialTemplate ()
void | IwGxSetMaterial (CIwMaterial *pMat)
INLINE void | IwGxSetMaterialCopyState (IwGxMaterialCopyState cs)
void | IwGxSetMaterialFixed (CIwMaterial *pMat)

Detailed Description

Note:
For more information on Materials, see the Material section of the IwGx API Documentation.

Define Documentation

#define NUM_UV_SETS 2

Maximum number of UV sets per model.

Function Documentation

CIwMaterial* IW_GX_ALLOC_MATERIAL ( ) [inline]

Allocates a material from the IwGx global cache.

Returns:
The allocated material.
Required Header Files
IwMaterial.h

INLINE void IwGxClearMaterialCopyState ( IwGxMaterialCopyState cs )

Set the material NOT to copy some members onto the IwGxState, when IwGxSetMaterial() is called.

Parameters:
cs Identifier for the member(s) NOT to copy.
Required Header Files
IwGx.h

INLINE CIwMaterial* IwGxGetMaterial ( )

Gets the current material.

Returns:
Pointer to the material currently set.
See also:
IwGxSetMaterial
Required Header Files
IwGx.h

INLINE CIwMaterial* IwGxGetMaterialFixed ( )

Gets the current fixed material.

Returns:
Pointer to the material currently set, or NULL if none is set.
See also:
IwGxSetMaterialFixed
Required Header Files
IwGx.h

INLINE CIwMaterial* IwGxGetMaterialTemplate ( )

Gets a pointer to the global template material.

Returns:
Pointer to the global template material.
Note:
This material is used as the "template" for all materials created by the application. Whenever a CIwMaterial is constructed, all members are copied from the template material. By modifying the template material, the user can modify the default settings for all created materials.

Do not confuse the "template" material with the material resource template (CIwResTemplateMTL).

Required Header Files
IwGx.h

void IwGxSetMaterial ( CIwMaterial * pMat )

Sets the current material. This defines the entire render state.

Parameters:
pMat Pointer to the material the set.
See also:
IwGxGetMaterial, IwGxSetMaterialFixed
Note:
This function has no effect if a fixed material has been set using IwGxSetMaterialFixed().
Required Header Files
IwGx.h

INLINE void IwGxSetMaterialCopyState ( IwGxMaterialCopyState cs )

Set the material to copy some members onto the IwGxState, when IwGxSetMaterial() is called.

Parameters:
cs Identifier for the member(s) to copy.
Required Header Files
IwGx.h

void IwGxSetMaterialFixed ( CIwMaterial * pMat )

Sets the fixed material. If non-NULL, this will set the material as usual, but then effectively "lock" it so that subsequent calls to IwGxSetMaterial() have no effect. If NULL, the fixed material is cleared, so that subsequent calls to IwGxSetMaterial() behave as normal.

Parameters:
pMat Pointer to the fixed material the set, or NULL to clear the fixed material.
See also:
IwGxGetMaterialFixed, IwGxSetMaterial
Required Header Files
IwGx.h


Airplay API Reference: Miscellaneous Functions

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Miscellaneous Functions >

Miscellaneous Functions
[IwGx API Reference]

Functions

int32 | IwGxGetGamma ()
int32 | IwGxGetPixelsDrawnBeforeYield ()
bool | IwGxIsGLExtensionSupported (IwGxGLExtension extEnumVal)
bool | IwGxIsHWSkinningSupported ()
bool | IwGxIsNormalMappingSupported ()
INLINE int32 | IwGxPolyBufferGetFree ()
void | IwGxSetGamma (int32 g)
int32 | IwGxSetPixelsDrawnBeforeYield (int32 pdby)

Function Documentation

int32 IwGxGetGamma ( )

Gets the gamma value of the display.

Returns:
Value of gamma from 0-15, where 10 is neutral.
Note:
In GL, a slight performance penalty may be incurred if gamma is not set to 8 (the default)
Required Header Files
IwGx.h

int32 IwGxGetPixelsDrawnBeforeYield ( )

Gets the PixelsDrawnBeforeYield value for the SW renderer.

Returns:
Value of PixelsDrawnBeforeYield.
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h

bool IwGxIsGLExtensionSupported ( IwGxGLExtension extEnumVal )

Check if a specified OpenGL ES extension is supported by the platform.

Parameters:
extEnumVal Enumerated OpenGL ES extension supported by IwGx.
Returns:
true only if the specified OpenGL ES extension is supported by the platform.

bool IwGxIsHWSkinningSupported ( )

Is HW skinning supported.

Returns:
True if HW skinning is supported.
Required Header Files
IwGx.h

bool IwGxIsNormalMappingSupported ( )

Is normal mapping supported for materials using EFFECT_NORMAL_MAPPING.

Returns:
True if normal mapping will be visible.
Required Header Files
IwGx.h

INLINE int32 IwGxPolyBufferGetFree ( )

Get the number of free bytes remaining in the poly buffer.

Returns:
Number of free bytes remaining in the poly buffer.
Required Header Files
IwGx.h

void IwGxSetGamma ( int32 g )

Sets the gamma value of the display.

Parameters:
g Value of Gamma from 0-15, where 10 is neutral.
Note:
In GL, a slight performance penalty may be incurred if gamma is not set to 8 (the default)
Required Header Files
IwGx.h

int32 IwGxSetPixelsDrawnBeforeYield ( int32 pdby )

Sets the PixelsDrawnBeforeYield value for the SW renderer. This is a count equivalent to simple pixels drawn and is weighted for other overhead processing.

Returns:
Value of PixelsDrawnBeforeYield.
Note:
Only affects software rasterisation.
Required Header Files
IwGx.h


Airplay API Reference: IwGx Error

Airplay API Reference > IwGx API Documentation > IwGx API Reference > IwGx Error >

IwGx Error
[IwGx API Reference]

Defines

#define | IwGxCheckErrors()

Functions

void | IwGxAssertError (unsigned int error, const char *file, int line)
void | IwGxClearErrors ()

Detailed Description

The IwGx Error module is part of the IwGx API.

Note:
For more information on IwGx, see the IwGx API Documentation.

Define Documentation

#define IwGxCheckErrors ( )

Checks for current error.

Note:
Debug versions of the IwGx library will throw assertions for most types of error. However, when using hardware-accelerated targets such as OpenGL ES, there are often errors raised by the underlying graphics sub-system. This function will throw an assertion if any such error has been raised by the underlying graphics sub-system.
See also:
IwGxCheckErrors, IwGxClearErrors
Required Header Files
IwGxError.h

Function Documentation

void IwGxAssertError | ( | unsigned int | error,
 |  | const char * | file,
 |  | int | line
 | ) |  |

Checks if the given value in an error and fires an assertion in debug builds.

Parameters:
error Value returned by glGetError to test for error.
See also:
IwGxCheckErrors, IwGxClearErrors
Required Header Files
IwGxError.h

void IwGxClearErrors ( )

Clears any errors raised by the underlying graphics sub-system.

See also:
IwGxCheckErrors, IwGxAssertError
Required Header Files
IwGxError.h


Airplay API Reference: IwGxMotionBlur

Airplay API Reference > IwGx API Documentation > IwGx API Reference > IwGxMotionBlur >

IwGxMotionBlur
[IwGx API Reference]

Enumerations

enum | IwGxMotionBlurTypes_

Functions

IwGxMotionBlurTypes | IwGxMotionBlurGetType ()
void | IwGxMotionBlurInit ()
uint32 | IwGxMotionBlurPrevFramePitch ()
uint8 * | IwGxMotionBlurPrevFramePtr ()
void | IwGxMotionBlurSetType (IwGxMotionBlurTypes type)
void | IwGxMotionBlurTerminate ()

Detailed Description

This module facilitates Motion Blur features and optimisations.

Note:
For more information on Motion Blur, see the Motion Blur section of the IwGx API Documentation.

Enumeration Type Documentation

enum IwGxMotionBlurTypes_

Types of motion blur supported:

dest is the last frame (optionally includes cumulative blur buildup). src is the frame we've just rendered.

Required Header Files
IwGxMotionBlur.h
Enumerator:
IW_GX_MOTION_BLUR_NONE | No blur (default);.
IW_GX_MOTION_BLUR_5050 | 50% src 50% dest (accumulating);
IW_GX_MOTION_BLUR_2575 | 25% src 75% dest (accumulating);
IW_GX_MOTION_BLUR_7525 | 75% src 25% dest (accumulating);
IW_GX_MOTION_BLUR_5050_NOACCUM | 50% src 50% dest (non-accumulating);
IW_GX_MOTION_BLUR_2575_NOACCUM | 25% src 75% dest (non-accumulating);
IW_GX_MOTION_BLUR_7525_NOACCUM | 75% src 25% dest (non-accumulating);
IW_GX_MOTION_BLUR_DOUBLE_BUFFER | Internal use only;.
IW_GX_MOTION_BLUR_DISABLE | no motion blur, ignore type changes until...
IW_GX_MOTION_BLUR_ENABLE | re-enables motion blur;

Function Documentation

IwGxMotionBlurTypes IwGxMotionBlurGetType ( )

Gets the type of motion blur current being used.

Returns:
One of IwGxMotionBlurTypes
Required Header Files
IwGxMotionBlur.h

void IwGxMotionBlurInit ( )

Initialises motion blur. Must be called before any other motion blur functions.

Required Header Files
IwGxMotionBlur.h

uint32 IwGxMotionBlurPrevFramePitch ( )

Retrieves the pitch of the buffer containing the previous frame.

Returns:
Pitch of the previous frame
Required Header Files
IwGxMotionBlur.h

uint8* IwGxMotionBlurPrevFramePtr ( )

Retrieves the ptr to the buffer containing the previous frame.

Returns:
A ptr to the previous frame
Required Header Files
IwGxMotionBlur.h

void IwGxMotionBlurSetType ( IwGxMotionBlurTypes type )

Sets the type of motion blur. Default type is IW_GX_MOTION_BLUR_NONE.

Parameters:
type One of IwGxMotionBlurTypes
Required Header Files
IwGxMotionBlur.h

void IwGxMotionBlurTerminate ( )

Terminate motion blur. Must be called if IwGxMotionBlurInit() was called.

Required Header Files
IwGxMotionBlur.h


Airplay API Reference: Printing

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Printing >

Printing
[IwGx API Reference]

Functions

void | IwGxPrintFrameRate (int32 x0, int32 y0)
void | IwGxPrintMenuCallback (const char *line, int32 x, int32 y, CIwMenuItem::ColourID colID)
void | IwGxPrintSetColour (uint8 r, uint8 g, uint8 b)
void | IwGxPrintString (int32 x0, int32 y0, const char *txt, bool wrap=true)

Detailed Description

This module facilitates debug printing to Segundo surface.

Note:
For more information on IwGx Print, see the Text section of the IwGx API Documentation.

Function Documentation

void IwGxPrintFrameRate | ( | int32 | x0,
 |  | int32 | y0
 | ) |  |

Draws Frames/Second to Screen

void IwGxPrintMenuCallback | ( | const char * | line,
 |  | int32 | x,
 |  | int32 | y,
 |  | CIwMenuItem::ColourID | colID
 | ) |  |

Standard printing callback to use with IwMenu

Required Header Files
IwGxPrint.h

void IwGxPrintSetColour | ( | uint8 | r,
 |  | uint8 | g,
 |  | uint8 | b
 | ) |  |

Set the default print colour

Parameters:
r | Red component
g | Green component
b | Blue component

void IwGxPrintString | ( | int32 | x0,
 |  | int32 | y0,
 |  | const char * | txt,
 |  | bool | wrap = true
 | ) |  |

Draws debug text directly to the surface.

Parameters:
x0 | Screen x coordinate.
y0 | Screen y coordinate.
txt | Text to print.
wrap | False only if we do not want to wrap text when we hit the right of the screen.
Note:
The text can contain format tags, a tag being a ` (backtick) followed by a character (tags cannot be stacked):
  • `x - The next 6 characters specify a text colour. The format of the specification is BBGGRR where BB, GG, RR are hex values ranging from 00 to ff for the blue, green, and red channel respectively, e.g "`x0000ffThis is red"
  • `1 - Brighten subsequent text, e.g. "`1This is bright"
  • `i - Swap the background colour with the text colour (invert), e.g. "`iInverted text"
  • `a - No alpha, write background as black, e.g. "`aNo alpha"
  • `` - A literal backtick, e.g. "This is a backtick: ``"
Escape characters are also considered, i.e.
  • \n - Line break, e.g. "First line\nSecond line"
  • \t - Horizontal tab, e.g. "Tab1\tTab2\tTab3"
  • \\ - A backslash
Required Header Files
IwGxPrint.h


Airplay API Reference: OpenGL ES 2.x Shader Techniques

Airplay API Reference > IwGx API Documentation > IwGx API Reference > OpenGL ES 2.x Shader Techniques >

OpenGL ES 2.x Shader Techniques
[IwGx API Reference]

Data Structures

class | CIwGxShaderTechnique
class | CIwGxShaderUniform

Detailed Description

IwGxShaderTechnique encapsulates a single shader effect for OpenGL ES 2.x

Shader techniques are CIwResource objects created from an itx file.

The format of a shader itx is as follows:

        CIwGxShaderTechnique
        {
            [param "name" type components default_value]
            [instanceParam "name" type components default_value]
            shader "vertex"
            {
                <GLSL code block>
            }
            shader "fragment"
            {
                <GLSL code block>
            }
        }

The shader technique is then attached to a material using the 'shaderTechnique' material property.

Shaders are only available in OpenGL ES 2.x mode. To access this in the windows simulator ensure HW rasterisation is enabled and use the gl configuration menu to select the GLES 2.0 API.

For device builds applications can indicate they want to run GLES 2.0 using the [s3e] GLESVersion icf parameter.

Most features of the fixed function pipeline are exposed to shaders via the following attributes and uniforms:

IwGx streams are available as the following attributes:
Attribute | Description | Format | Standard pipeline function | GLSL declaration
inVert | Vertex stream set by IwGxSetVertStream*. | HW transform: raw fixed values cast to float SW transform: post-transform view space vertices (fixed cast to float) | Multiplied by 'inPMVMat' to produce projected vertex. | attribute highp vec4 inVert;
inUV0 | UV stream 0 set by IwGxSetUVStream. | Raw fixed values cast to float. | Multiplied by 'inUVScale' and offset by 'inUVOffset' | attribute mediump vec2 inUV0;
inUV1 | UV stream 1 set by IwGxSetUVStream. | Raw fixed values cast to float. | Multiplied by 'inUV1Scale' | attribute mediump vec2 inUV1;
inCol | Colour stream set by IwGxSetColStream. | HW Lighting: Raw colour stream values normalised to float. SW Lighting: lit colour values normalised to float. | HW Lighting: Lit in shader and passed to fragment shader. SW Lighting: passed to fragment shader. | attribute lowp vec4 inCol;
inNorm | Normal stream set by IwGxSetNormStream. | Raw fixed values cast to float. | HW Lighting: Used to light colour values and/or generate tangent space for normal mapping. SW Lighting: Used to generate tangent space for normal mapping. | attribute mediump vec3 inNorm;
inTangent | Tangent stream set by IwGxSetTangentStream. | Raw fixed values cast to float. | Used to generate tangent space for normal mapping. | attribute mediump vec3 inTangent;
inBiTangent | BiTangent stream set by IwGxSetBiTangentStream. | Raw fixed values cast to float. | Used to generate tangent space for normal mapping. | attribute mediump vec3 inBiTangent;
inSkinWeights | Set of 4 skin weights that match the matrices specified by inSkinIndices. | Floating point. | Used to skin vertices. Only available in HW transform. | attribute mediump vec4 inSkinWeights;
inSkinIndices | Set of 4 indexes into 'inSkinMats'. | Int cast to floating point. | Used to skin vertices. Only available in HW transform. | attribute mediump vec4 inSkinIndices;

Other features of the fixed function pipeline and convenience uniforms are available:

Uniform | Description | Format | Standard pipeline function | GLSL declaration
inPMVMat | Projected model-view matrix. The full transform from vertex coordinate space to clip space | 4x4 floating point matrix | Transforms vertices to clip space | uniform highp mat4 inPMVMat;
inMVMat | Model-view matrix. The transform to view space. | 4x4 floating point matrix | Not used | uniform highp mat4 inMVMat;
inMVRotMat | Rotation/scale part of model-view matrix. Can be used to orient coordinate space directions (like normals) to view space. | 3x3 floating point matrix | Not used | uniform highp mat3 inMVRotMat;
inModelRotMat | Rotation/scale part of model matrix. Can be used to orient coordinate space directions (like normals) to world space. | 3x3 floating point matrix | Not used | uniform highp mat3 inModelRotMat;
inModelPos | Translation of the model matrix. Can be used with 'inModelRotMat' to move position between model space and world space. | 3 component vector. Fixed cast to float. | Not used | uniform mediump vec3 inModelPos
inCamPos | Translation of the view matrix. | 3 component vector. Fixed cast to float. | Not used | uniform mediump vec3 inCamPos
inSampler0 | Texture sampler for texture stage 0 | Texture sampler | Texture sampler for texture stage 0 | uniform sampler2D inSampler0;
inSampler1 | Texture sampler for texture stage 1 | Texture sampler | Texture sampler for texture stage 1 | uniform sampler2D inSampler1;
inSampler2 | Texture sampler for texture stage 2 | Texture sampler | Texture sampler for texture stage 2 | uniform sampler2D inSampler2;
inSampler3 | Texture sampler for texture stage 3 | Texture sampler | Texture sampler for texture stage 3 | uniform sampler2D inSampler3;
inAlphaTestValue | Alpha test value. | Normalised floating point | Used for alpha testing | uniform mediump float inAlphaTestValue;
inMaterialAmbient | Material ambient colour value | Normalised floating point vector | Used for lighting vertices | uniform lowp vec4 inMaterialAmbient;
inMaterialDiffuse | Material diffuse colour value | Normalised floating point vector | Used for lighting vertices | uniform lowp vec4 inMaterialDiffuse;
inEmissive | Material emissive light colour value | Normalised floating point vector | Used for lighting vertices | uniform lowp vec4 inEmissive;
inAmbient | Ambient light colour value | Normalised floating point vector | Used for lighting vertices | uniform lowp vec4 inAmbient;
inDiffuse | Diffuse light colour value | Normalised floating point vector | Used for lighting vertices | uniform lowp vec4 inDiffuse;
inDiffuseDir | Direction of diffuse light transformed into local coordinate space. | Floating point vector | Used for lighting vertices | uniform lowp vec3 inDiffuseDir;
inFogNear | Fog near value in clip space. | Floating point value. | Used for fogging | uniform mediump float inFogNear;
inFogRange | Fog range value in clip space. | Floating point value. | Used for fogging | uniform mediump float inFogRange;
inFogColour | Fog colour | Normalised floating point vector | Used for fogging | uniform mediump vec4 inFogColour;
inSkinMats | Array of matrices which contain transforms from bind-pose space to view space | Array 4x4 matrices | Used for skinning | uniform highp mat4 inSkinMats[32];
inUVOffset | Offset for UV stream 0. inUV0 should be multiplied by inUVScale before applying the offset. | Floating point value | Used for UV animation | uniform mediump vec2 inUVOffset;
inUVScale | Scale for UV stream 0. | Floating point value | Primarily used to transform fixed coords into floating coords. UV scale is also used for non-power-of-2 textures and in some cases of texture atlassing. | uniform mediump vec2 inUVScale;
inUV1Scale | Scale for UV stream 1. | Floating point value | Primarily used to transform fixed coords into floating coords. UV scale is also used for non-power-of-2 textures and in some cases of texture atlassing. | uniform mediump vec2 inUV1Scale;
inUV2Scale | Scale for UV stream 2. | Floating point value | Primarily used to transform fixed coords into floating coords. UV scale is also used for non-power-of-2 textures and in some cases of texture atlassing. | uniform mediump vec2 inUV2Scale;
inUV3Scale | Scale for UV stream 3. | Floating point value | Primarily used to transform fixed coords into floating coords. UV scale is also used for non-power-of-2 textures and in some cases of texture atlassing. | uniform mediump vec2 inUV3Scale;
inTextureSize | Texel dimensions of texture in stage 0 | Floating point vector | Not used | uniform mediump vec2 inTextureSize;
inTextureSize1 | Texel dimensions of texture in stage 1 | Floating point vector | Not used | uniform mediump vec2 inTextureSize;
inTextureSize2 | Texel dimensions of texture in stage 2 | Floating point vector | Not used | uniform mediump vec2 inTextureSize;
inTextureSize3 | Texel dimensions of texture in stage 3 | Floating point vector | Not used | uniform mediump vec2 inTextureSize;
inOOTextureSize | One over texel dimensions of texture in stage 0 | Floating point vector | Not used | uniform mediump vec2 inOOTextureSize;
inOOTextureSize1 | One over texel dimensions of texture in stage 1 | Floating point vector | Not used | uniform mediump vec2 inOOTextureSize;
inOOTextureSize2 | One over texel dimensions of texture in stage 2 | Floating point vector | Not used | uniform mediump vec2 inOOTextureSize;
inOOTextureSize3 | One over texel dimensions of texture in stage 3 | Floating point vector | Not used | uniform mediump vec2 inOOTextureSize;
inDisplaySize | Size of IwGx display - equivalent to (IwGxGetDisplayWidth(), IwGxGetDisplayHeight()) | Floating point vector | Not used | uniform mediump vec2 inDisplaySize;
inDeviceSize | Size of IwGx device - equivalent to (IwGxGetDeviceWidth(), IwGxGetDeviceHeight()) | Floating point vector | Not used | uniform mediump vec2 inDeviceSize;
inDisplayRotScaleMat | Transformation from window space to IwGx screen space. This can be useful for effects on rotated displays. If IwGx is rendering rotated then window coordinates are not orientated the same way as the 'logical' screen. Multiplying gl_FragCoord by this matrix produces a vector with extents 0.0-1.0 which is orientated the same way as the logical screen. | 3x3 floating point matrix | Not used | uniform mediump mat3 inDisplayRotScaleMat;
inPipelineConfig | 2 component vector describing the current pipeline config. If the first element is 1, transform is set to HW, if the second element is 1 lighting is set to HW. | Integer vector | Not used | uniform mediump ivec2 inPipelineConfig; note For more information on IwGx, see the ref iwgxapidocumentation "IwGx API Documentation".


Airplay API Reference: IwGxState

Airplay API Reference > IwGx API Documentation > IwGx API Reference > IwGxState >

IwGxState
[IwGx API Reference]

Data Structures

class | CIwGxState
class | CIwGxStateBase
struct | EnvCoords
class | IwMatUsed
struct | OTScissorRects
struct | ScissorRect

Enumerations

enum | IwGxDebugFlags
enum | IwGxFlags

Detailed Description

IwGxState is a private system singleton that holds all information about the current drawing state, including all current transforms, stream pointers, colours, etc.

Note:
For more information on IwGx State, see the IwGx State section of the IwGx API Documentation.

Enumeration Type Documentation

enum IwGxDebugFlags

Global debug flags. These may be read and written directly.

Required Header Files
IwGxState.h
Enumerator:
IW_GX_DEBUG_DISPLAY_METRICS_F | Display all metrics.
IW_GX_DEBUG_WIREFRAME_F | Display edges only of all polys.
IW_GX_DEBUG_DUMP_GEOM_INFO_F | At next call to IwGxFlush(), dump cached geometry info to text file.
IW_GX_DEBUG_NO_TEXTURES_F | Bind no textures.
IW_GX_DEBUG_NO_MULTITEXTURES_F | Bind no textures above stage 0.
IW_GX_DEBUG_NO_ALPHA_F | Set no alpha blending.
IW_GX_DEBUG_FORCE_ALPHA_BLEND_TO_ADD_F | Alpha geometry of type BLEND is forced to ADD.
IW_GX_DEBUG_FORCE_SMOOTH_F | All shading is forced to smooth (no flat).
IW_GX_DEBUG_FORCE_TEXTURE_F | All textures are bound to IwGetGxState()->m_DebugTexture.
IW_GX_DEBUG_OVERDRAW_F | All textures faint additive.
IW_GX_DEBUG_DRAWCALLS_F | Unique colour per draw call.

enum IwGxFlags

Global state flags. These may be read but not written directly.

Required Header Files
IwGxState.h
Enumerator:
IW_GX_SHARE_8BIT_PALS | Share 8bit palettes.
IW_GX_SHARE_4BIT_PALS | Share 4bit palettes.
IW_GX_SUPPORT_TRANSFORM_SW_F | Initialised to be able to switch to SW transform.
IW_GX_SUPPORT_LIGHTING_SW_F | Initialised to be able to switch to SW lighting.
IW_GX_SUPPORT_RASTERISATION_SW_F | Initialised to be able to switch to SW rasterisation.
IW_GX_SUPPORT_TRANSFORM_HW_F | Initialised to be able to switch to HW transform.
IW_GX_SUPPORT_LIGHTING_HW_F | Initialised to be able to switch to HW lighting.
IW_GX_SUPPORT_RASTERISATION_HW_F | Initialised to be able to switch to HW rasterisation.
IW_GX_TRANSFORM_HW_F | Use HW transform pipeline, if available.
IW_GX_LIGHTING_HW_F | Use HW lighting pipeline, if available.
IW_GX_RASTERISATION_HW_F | Use HW rasterisation, if available.
IW_GX_LIGHTING_EMISSIVE_F | Enable/disable use of emissive colours in lighting calculations. If off, value used is 0.
IW_GX_LIGHTING_AMBIENT_F | Enable/disable use of ambient colours in lighting calculations. If off, value used is 1.
IW_GX_LIGHTING_DIFFUSE_F | Enable/disable use of diffuse colours in lighting calculations. If off, value used is 0.
IW_GX_LIGHTING_SPECULAR_F | Enable/disable use of specular colours in lighting calculations. If off, value used is 0.
IW_GX_FOG_F | Use fog.
IW_GX_PALETTE_SATURATION_F | Set to use PSX-style palette saturation..
IW_GX_MATERIAL_COPY_STATE_COLS_F | IwGxSetMaterial() should copy the material colours to the IwGxState.
IW_GX_MATERIAL_COPY_STATE_ZDEPTHOFS_F | IwGxSetMaterial() should copy the material z-depth offset to the IwGxState.
IW_GX_MATERIAL_COPY_STATE_UVOFS_F | IwGxSetMaterial() should copy the material UV offset to the IwGxState.
IW_GX_PALETTE_TINTING | Set to Tint all palettes by the material AmbientColour.
IW_GX_DISABLE_CUSTOM_SHADERS_F | Only use default shaders.
IW_GX_DISPLAY_FRAMERATE_F | Display framerate at the top left of every frame.
IW_GX_LEAVE_PREALLOCBUFFERS_F | Pre-allocated buffers are NOT cleared at end of SW lighting calculation.

enum IwGxInternalFlags

Enumerator:
IW_GX_INTERNAL_MODELMAT_ROT_IDENT_F | Model matrix has identity rotation.
IW_GX_INTERNAL_MATVIEWMODEL_ROT_IDENT_F | Identity rotation in model matrix is included in m_ModelViewMat.
IW_GX_INTERNAL_MATS_ANIMS_RESERVED_F | Animating material array has been reserved.


Airplay API Reference: Stream Objects

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Stream Objects >

Stream Objects
[IwGx API Reference]

Data Structures

class CIwGxStream

Detailed Description

CIwGxStream provides general access to retained stream objects. For example, stream objects may be uploaded to vertex buffer objects on OpenGL ES. For long streams, on some platforms, stream objects will perform better.

Generally, the benefit for shorter streams is less important.

Since IwGraphics will automatically use stream objects where appropriate, the application generally should not need to use stream objects unless it is rendering complex procedural geometry.

Applications can also use stream objects to send non-standard format streams (including interleaved formats) to the graphics hardware.

However, the format of streams passed to SW TnL must match the 'normal' format and the local version must still be available.

So, in general, stream use will complicate client code, so is best avoided for current hardware.

Typical stream usage is as follows.

The stream is created from client data:

 CIwSVec3* vertexData; //pointer to heap-allocated vertex stream
 CIwGxStream* stream = new CIwGxStream(vertexData, 200);

Then it is uploaded to the graphics hardware

 stream->Upload(true, true);

It can then be used as an argument to the usual IwGx stream functions (which are overloaded to take stream objects)

 IwGxSetVertStreamModelSpace(*stream);

Finally, when the application is finished with the stream, the storage must be explicitly freed prior to destruction.

 stream->Free();
 delete stream;

Note that when creating a stream from client data, ownership of the data passes to the stream object. When uploading a stream the application indicates whether the client version of the stream data can be freed. If it is freed the application can not refer to the data again. By default, the client data is never freed since this data is not generally large, and this is less likely to cause differences between SW/HW TnL builds. The icf setting [GX] FreeStreamData can be used to activate actual data freeing.

Uploading may reformat the stream for the HW, or do nothing at all.

The memory consumption in retained streams in HW can be viewed in the metrics dialogue.

The Open GL ES renderer also exposes metrics for how many draw calls and attribute streams are being made using retained buffers (VBOs).


Airplay API Reference: Surfaces and Render Targets

Airplay API Reference > IwGx API Documentation > IwGx API Reference > Surfaces and Render Targets >

Surfaces and Render Targets
[IwGx API Reference]

Data Structures

class CIwGxSurface

Detailed Description

IwGxSurface class is used as an abstraction for surfaces in both HW and SW.

Typical surface usage is as follows:

Create the surface:

 CIwGxSurface* surface = new CIwGxSurface;
 if( !surface->CreateSurface(NULL, 256, 256, 0) )
     IwError(("Surface creation failed"));

Make the surface current:

 surface->MakeCurrent();

...Render some content...

Make the display current

 CIwGxSurface::MakeDisplayCurrent();

... Render some more content using the surface's texture...

 material->SetTexture(surface->GetTexture());

The performance and availability of render to texture varies greatly from device to device, so the application should be prepared to fallback if surface creation fails or performance is not acceptable. The icf setting [GX] DisableSurfaces can be used to disable all surfaces (all calls to CreateSurface will fail) and provides a convenient way to disable effects on a per-device basis.

If surface creation fails, the fallback mode will be used. In this mode MakeCurrent calls will fail silently (i.e. the draw commands will go to the main display) and any draw call using the surface's texture will be silently dropped. This will provide a reasonable result in some cases, but the application will usually be able to provide a more efficient fallback which provides more fidelity to the intended visuals.

note For more information on IwGx, see the ref iwgxapidocumentation "IwGx API Documentation".


Airplay API Reference: IwGxTransformSW

Airplay API Reference > IwGx API Documentation > IwGx API Reference > IwGxTransformSW >

IwGxTransformSW
[IwGx API Reference]

Functions

INLINE void | _IwGxViewToScreenXY (int16 &sx, int16 &sy, const CIwVec3 &viewPos)
INLINE void | IwGxViewToScreenDist (int32 &d, int32 viewD, int32 viewZ, int32 perspMul)
INLINE void | IwGxViewToScreenDist (int16 &d, int32 viewD, int32 viewZ, int32 perspMul)
INLINE void | IwGxViewToScreenXY (int32 &sx, int32 &sy, const CIwVec3 &viewPos)
INLINE void | IwGxViewToScreenXY (int16 &sx, int16 &sy, const CIwVec3 &viewPos)
INLINE void | IwGxViewToScreenXYSubPixel (int32 &sx, int32 &sy, const CIwVec3 &viewPos)
INLINE void | IwGxViewToScreenXYSubPixel (int16 &sx, int16 &sy, const CIwVec3 &viewPos)
INLINE void | IwGxWorldToScreenXY (int32 &sx, int32 &sy, const CIwVec3 &worldPos)
INLINE void | IwGxWorldToScreenXY (int16 &sx, int16 &sy, const CIwVec3 &worldPos)

Detailed Description

The IwGxTransform module is part of the IwGx API.

Note:
For more information on Transforms, see the Transform section of the IwGx API Documentation.

Function Documentation

INLINE void _IwGxViewToScreenXY | ( | int16 & | sx,
 |  | int16 & | sy,
 |  | const CIwVec3 & | viewPos
 | ) |  |

Transforms a viewspace point to screenspace.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
viewPos | Viewspace point to transform.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenDist | ( | int32 & | d,
 |  | int32 | viewD,
 |  | int32 | viewZ,
 |  | int32 | perspMul
 | ) |  |

Converts viewspace distance to screenspace distance.

Parameters:
d | Screenspace distance to convert to.
viewD | Viewspace distance to convert from.
viewZ | Viewspace z at which viewspace distance is considered.
perspMul | Perspective multiple to use (distance from camera to view plane).
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenDist | ( | int16 & | d,
 |  | int32 | viewD,
 |  | int32 | viewZ,
 |  | int32 | perspMul
 | ) |  |

Converts viewspace distance to screenspace distance.

Parameters:
d | Screenspace distance to convert to.
viewD | Viewspace distance to convert from.
viewZ | Viewspace z at which viewspace distance is considered.
perspMul | Perspective multiple to use (distance from camera to view plane).
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenXY | ( | int32 & | sx,
 |  | int32 & | sy,
 |  | const CIwVec3 & | viewPos
 | ) |  |

Transforms a viewspace point to screenspace.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
viewPos | Viewspace point to transform.
Note:
viewPos.z must be positive and non-zero for results to be meaningful.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenXY | ( | int16 & | sx,
 |  | int16 & | sy,
 |  | const CIwVec3 & | viewPos
 | ) |  |

Transforms a viewspace point to screenspace.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
viewPos | Viewspace point to transform.
Note:
viewPos.z must be positive and non-zero for results to be meaningful.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenXYSubPixel | ( | int32 & | sx,
 |  | int32 & | sy,
 |  | const CIwVec3 & | viewPos
 | ) |  |

Transforms a viewspace point to screenspace, with 3 bits of sub-pixel accuracy. For efficiency reasons the value of viewPos.z is not tested, so this function will throw a division by zero exception if viewPos.z is zero.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
viewPos | Viewspace point to transform.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxViewToScreenXYSubPixel | ( | int16 & | sx,
 |  | int16 & | sy,
 |  | const CIwVec3 & | viewPos
 | ) |  |

Transforms a viewspace point to screenspace, with 3 bits of sub-pixel accuracy. For efficiency reasons the value of viewPos.z is not tested, so this function will throw a division by zero exception if viewPos.z is zero.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
viewPos | Viewspace point to transform.
Note:
viewPos.z must be positive and non-zero for results to be meaningful.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxWorldToScreenXY | ( | int32 & | sx,
 |  | int32 & | sy,
 |  | const CIwVec3 & | worldPos
 | ) |  |

Transforms a worldspace point to screenspace.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
worldPos | Worldspace point to transform.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h

INLINE void IwGxWorldToScreenXY | ( | int16 & | sx,
 |  | int16 & | sy,
 |  | const CIwVec3 & | worldPos
 | ) |  |

Transforms a worldspace point to screenspace.

Parameters:
sx | Screenspace x to calculate.
sy | Screenspace y to calculate.
worldPos | Worldspace point to transform.
Required Header Files
IwGxTransformSW.h
Required Header Files
IwGxTransformSW.h


Airplay API Reference: IwGxTypes

Airplay API Reference > IwGx API Documentation > IwGx API Reference > IwGxTypes >

IwGxTypes
[IwGx API Reference]

Data Structures

struct | _IwGxCallbackRegistration
struct | CIwLight
struct | CIwPTVert
class | CIwRect
class | CIwRect32

Enumerations

enum | IwGxCoordSpace
enum | IwGxCullResult
enum | IwGxLightType
enum | IwGxPrimType
enum | IwGxScreenOrient

Detailed Description

Core types and enumerations used by the IwGx APIs.

Note:
For more information on IwGx, see the IwGx API Documentation.

Define Documentation

#define IW_GX_LIGHTS_MAX 2

Maximum number of lights supported.

Enumeration Type Documentation

enum IwGxCallback

Enumerator:
IW_GX_PRE_FLUSH | Raised before a non-empty flush.
IW_GX_SCREENSIZE | Raised after a screen size change (IwGxGetScreenWidth() etc. will return the new size).

enum IwGxClearBufferFlags

Enumerator:
IW_GX_COLOUR_BUFFER_F | clear colour buffer
IW_GX_DEPTH_BUFFER_F | clear depth buffer

enum IwGxCoordSpace

Coordinate spaces for geometry streams.

Required Header Files
IwGxTypes.h
Enumerator:
IW_GX_WORLDSPACE | worldspace.
IW_GX_MODELSPACE | modelspace.
IW_GX_VIEWSPACE | viewspace.
IW_GX_SCREENSPACE | screenspace.
IW_GX_VIEWSPACE_32 | viewspace (32-bit vertices).

enum IwGxCullResult

Enumerated results of viewspace backface culling, considering material settings.

Required Header Files
IwGxTypes.h
Enumerator:
IW_GX_CULL_RESULT_FAIL | cull failed - do not draw polygon.
IW_GX_CULL_RESULT_PASS | cull passed - draw polygon with default ordering.
IW_GX_CULL_RESULT_REVERSE | cull passed - draw polygon with reverse ordering.
IW_GX_CULL_RESULT_DRAW_BOTH | cull uncertain - draw polygon both ways around

enum IwGxLightType

Light types.

Required Header Files
IwGxTypes.h
Enumerator:
IW_GX_LIGHT_UNUSED | light type has not been set.
IW_GX_LIGHT_AMBIENT | ambient light.
IW_GX_LIGHT_DIFFUSE | diffuse light.

enum IwGxMaterialCopyState

Enumerator:
IW_GX_MATERIAL_COPY_STATE_COLS | Copy emissive, ambient and diffuse colours (from material to IwGxState).
IW_GX_MATERIAL_COPY_STATE_ZDEPTHOFS | Copy z-depth offset (from material to IwGxState).
IW_GX_MATERIAL_COPY_STATE_UVOFS | Copy UV offset (from material to IwGxState).

enum IwGxPrimType

Primitive types, as inputs to IwGxDrawPrims.

Required Header Files
IwGxTypes.h
Enumerator:
IW_GX_TRI_LIST | triangle list.
IW_GX_TRI_STRIP | triangle strip.
IW_GX_TRI_FAN | triangle fan.
IW_GX_QUAD_LIST | quadrilateral list.
IW_GX_QUAD_STRIP | quadrilateral strip.
IW_GX_LINE_LIST | line list.
IW_GX_LINE_STRIP | line strip.
IW_GX_SPRITE_LIST | sprite list.
IW_GX_NPOLY_LIST | N-poly list.

enum IwGxScreenOrient

Screen orientations, as inputs to IwGxSetScreenOrient.

Required Header Files
IwGxTypes.h
Enumerator:
IW_GX_ORIENT_NONE | no orientation.
IW_GX_ORIENT_90 | rotate 90 degrees.
IW_GX_ORIENT_180 | rotate 180 degrees.
IW_GX_ORIENT_270 | rotate 270 degrees.

enum IwGxSortMode

Enumerator:
IW_GX_SORT_NONE | cache all drawn geometry so that it is flushed in the order it was submitted.
IW_GX_SORT_BY_MATERIAL | cache all drawn geometry so that it is ordered by material when flushed.
IW_GX_SORT_BY_Z | cache all drawn geometry so that it is ordered by Z when flushed.
IW_GX_SORT_BY_SLOT | cache all drawn geometry and render in order specified by each material/coordinate space type


Airplay API Reference: IwGx Examples

Airplay API Reference > IwGx API Documentation > IwGx Examples >

IwGx Examples

IwGx is a stream-based API for 2D and 3D drawing, which provides abstraction from the underlying low-level renderer. The renderer may be the Airplay software renderer, OpenGL ES, or a rendering API for a proprietary platform, such as a handheld games console.

IwGx is based around geometry streams, transform state, lighting state, textures and materials (similar to OpenGL or DirectX).

Geometry streams are fed into IwGx to construct each object in a scene. IwGx handles the transformation of each object as well as the supply of colour, texture and lighting information. It also handles the rasterisation of the derived view to the screen.

The following sections explain this process in more detail. Examples accompany each section to further explain and illustrate the concepts being covered. Each example has been written using only the functionality essential to its operation; any extraneous code has been eliminated. Each example includes the standard application code functions:

  • ExampleInit(): Performs any important initialisation.
  • ExampleShutDown(): Tidies up when the application exits.
  • ExampleRender(): Draws to screen.
  • ExampleUpdate(): Carries out any development of the graphical objects.

The following examples are contained within this section:

  • IwGx Polygon Display Example
  • IwGx Drawing Modes Example
  • IwGx Coordinate Spaces Example
  • IwGx Texture Examples
  • IwGx Lighting Examples
  • IwGx Surface Examples
  • IwGx Billboards Example
  • IwGx DebugPrim Example
  • IwGx Resource Groups Example
  • IwGx Alpha Modes Example
  • IwGx UV Animation Example


Airplay API Reference: IwGx Polygon Display Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Polygon Display Example >

IwGx Polygon Display Example

This example demonstrates how to draw a single polygon on screen.

The main functions required to achieve this are:

  • IwGxGetScreenWidth()

  • IwGxGetScreenHeight()

  • IwGxSetMaterial()

  • IwGxSetVertStreamScreenSpace()

  • IwGxSetColStream()

  • IwGxDrawPrims()

  • IwGxFlush()

  • IwGxSwapBuffers()

The three main actions performed in this example are:

  1. Set a material to be used when drawing. This is done using the IwGxSetMaterial(), and this material will be used for all drawing until a new material is set.
  2. Take in a vertex stream of three vertices. This is done using IwGxSetVertStreamScreenSpace().
  3. Draw the polygon. This is done using the IwGxDrawPrims() function.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxPolygonDisplay
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwMaterial.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Turn all lighting off
    IwGxLightingOff();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate a material from the IwGx global cache
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set up screenspace vertex coords
    int16 x1 = (int16)IwGxGetScreenWidth() * 1 / 4;
    int16 x2 = (int16)IwGxGetScreenWidth() * 2 / 4;
    int16 x3 = (int16)IwGxGetScreenWidth() * 3 / 4;
    int16 y1 = (int16)IwGxGetScreenHeight() * 1 / 4;
    int16 y3 = (int16)IwGxGetScreenHeight() * 3 / 4;

    static CIwSVec2 xy3[3];
    xy3[0].x = x2, xy3[0].y = y1;
    xy3[1].x = x1, xy3[1].y = y3;
    xy3[2].x = x3, xy3[2].y = y3;
    IwGxSetVertStreamScreenSpace(xy3, 3);

    // Set up vertex colours
    static CIwColour cols[4] =
    {
        {0xff, 0x00, 0x00},
        {0x00, 0xff, 0x00},
        {0x00, 0x00, 0xff},
    };
    IwGxSetColStream(cols, 3);

    // Draw single triangle
    IwGxDrawPrims(IW_GX_TRI_LIST, NULL, 3);

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Drawing Modes Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Drawing Modes Example >

IwGx Drawing Modes Example

The example application draws a set of polygons to screen using a specific drawing mode.

The main functions used to achieve this are:

  • IwGxSetVertStreamScreenSpace()
  • IwGxDrawPrims()

The example demonstrates the following primitive types:

  • Tri list
  • Tri strip
  • Tri fan
  • Quad list
  • Quad strip
  • Line list
  • Line strip
The application allows you to toggle between drawing modes using the up and down arrow keys. Each type uses the index stream differently, so the fixed array of screenspace coords are effectively stitched together differently.

The IwGxSetVertStreamScreenSpace() function is used to feed in the coordinates as well as specifying the number of coordinates. And the IwGxDrawPrims() function lets you specify the primitive type, the indices and the number of indices being passed.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxDrawingModes
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "s3eKeyboard.h"
#include "s3ePointer.h"
#include "ExamplesMain.h"

// Screenspace vertex coords
CIwSVec2* g_Coords = NULL;

// Vertex colours
CIwColour g_Cols[10] =
{
    {0xff, 0x00, 0x00, 0x00},
    {0xff, 0xff, 0x00, 0x00},
    {0x00, 0xff, 0xff, 0x00},
    {0x00, 0x00, 0xff, 0x00},
    {0xff, 0x00, 0xff, 0x00},
    {0xff, 0x00, 0x00, 0x00},
    {0xff, 0xff, 0x00, 0x00},
    {0x00, 0xff, 0xff, 0x00},
    {0x00, 0x00, 0xff, 0x00},
    {0xff, 0x00, 0xff, 0x00},
};

// Primitive types to demonstrate
enum PrimType
{
    TRI_LIST,
    TRI_STRIP,
    TRI_FAN,
    QUAD_LIST,
    QUAD_STRIP,
    LINE_LIST,
    LINE_STRIP,
    MAX,
};
PrimType g_PrimType = TRI_LIST;

// Tri-list example: display every other triangle
uint16  g_IndsTriList[12] = {0, 5, 1, 1, 6, 2, 2, 7, 3, 3, 8, 4};

// Tri-strip example: display all triangles
uint16  g_IndsTriStrip[10] = {0, 5, 1, 6, 2, 7, 3, 8, 4, 9};

// Tri-fan example: 4 large triangles
uint16  g_IndsTriFan[6] = {7, 9, 4, 2, 0, 5};

// Quad-list example: display first and last quads
uint16  g_IndsQuadList[8] = {0, 5, 6, 1, 3, 8, 9, 4};

// Note.. for QUAD_STRIP, we can re-use the tri-strip inds!

// Line-list example: display all lines
uint16  g_IndsLineList[26] = {0, 1, 1, 2, 2, 3, 3, 4, 5, 6, 6, 7, 7, 8, 8, 9, 0, 5, 1, 6, 2, 7, 3, 8, 4, 9};

// Line-strip example: display continuous U shapes
uint16  g_IndsLineStrip[10] = {0, 5, 6, 1, 2, 7, 8, 3, 4, 9};

// Primitive type names to display
const char* g_PrimNames[] =
{
    "TRI_LIST",
    "TRI_STRIP",
    "TRI_FAN",
    "QUAD_LIST",
    "QUAD_STRIP",
    "LINE_LIST",
    "LINE_STRIP",
};

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Turn all lighting off
    IwGxLightingOff();

/*  Allocate and set up screenspace vertex coords in the following way:
    0--1--2--3--4
    |  |  |  |  |
    5--6--7--8--9
*/
    g_Coords = new CIwSVec2[10];
    int16 x0 = 0x8;
    int16 x1 = (int16)IwGxGetScreenWidth() - 0x8;
    int16 dx = (x1 - x0) / 4;
    int16 y0 = (int16)IwGxGetScreenHeight() / 2 - 0x10;
    CIwSVec2* pCoord = g_Coords;
    for (int16 y = 0; y < 2; y++)
    {
        for (int16 x = 0; x < 5; x++)
        {
            pCoord->x = x0 + dx * x;
            pCoord->y = y0 + y * 0x20;
            pCoord++;
        }
    }
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete[] g_Coords;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Press up/down to change displayed primitive type
    if ( CheckCursorState() == EXCURSOR_UP )
        g_PrimType = (PrimType)((g_PrimType == MAX - 1) ? 0 : (g_PrimType + 1));
    else
    if ( CheckCursorState() == EXCURSOR_DOWN )
        g_PrimType = (PrimType)((g_PrimType == 0) ? (MAX - 1) : (g_PrimType - 1));

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate a material from the IwGx global cache
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set screenspace vertex coords
    IwGxSetVertStreamScreenSpace(g_Coords, 10);

    // Set vertex colours
    IwGxSetColStream(g_Cols, 10);

    // Draw primitives
    switch(g_PrimType)
    {
    case TRI_LIST:
        IwGxDrawPrims(IW_GX_TRI_LIST, g_IndsTriList, 12);
        break;

    case TRI_STRIP:
        IwGxDrawPrims(IW_GX_TRI_STRIP, g_IndsTriStrip, 10);
        break;

    case TRI_FAN:
        IwGxDrawPrims(IW_GX_TRI_FAN, g_IndsTriFan, 6);
        break;

    case QUAD_LIST:
        IwGxDrawPrims(IW_GX_QUAD_LIST, g_IndsQuadList, 8);
        break;

    case QUAD_STRIP:
        // Note: we can re-use the tri-strip inds!
        IwGxDrawPrims(IW_GX_QUAD_STRIP, g_IndsTriStrip, 10);
        break;

    case LINE_LIST:
        IwGxDrawPrims(IW_GX_LINE_LIST, g_IndsLineList, 26);
        break;

    case LINE_STRIP:
        IwGxDrawPrims(IW_GX_LINE_STRIP, g_IndsLineStrip, 10);
        break;

    default:
        break;
    }

    // Display primitive type used
    IwGxPrintString(0x2, IwGxGetScreenHeight() - 80, g_PrimNames[g_PrimType]);
    IwGxPrintString(0x2, IwGxGetScreenHeight() - 70, "Use Up/Down to change mode");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Coordinate Spaces Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Coordinate Spaces Example >

IwGx Coordinate Spaces Example

This example demonstrates how to draw in all available coordinate spaces.

The functions required to achieve this are:

  • IwGxSetVertStreamScreenSpace()

  • IwGxSetVertStreamViewSpace()

  • IwGxSetModelMatrix()

  • IwGxSetVertStream()

  • IwGxSetVertStreamWorldSpace()

  • IwGxDrawPrims()

You can call IwGxDrawPrims() multiple times, changing only transform (model matrix), materials, or some streams in between. However, if you change the transform, you must call IwGxSetVertStream() again, even if the stream has not changed.

The example application demonstrates how to submit vertex streams in screenspace, viewspace, modelspace and worldspace, and how each coordinate space is affected by the view and model matrices.

The following graphics illustrates the example output.

Note:
For more information on the various coordinate spaces, see the Transform section of IwGx API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGx7
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwMenu.h"

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[8] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3(-s,  s,  s),
};

// Normal data
const int16 n = 0x93c;
CIwSVec3    s_Norms[8] =
{
    CIwSVec3(-n, -n, -n),
    CIwSVec3( n, -n, -n),
    CIwSVec3( n,  n, -n),
    CIwSVec3(-n,  n, -n),
    CIwSVec3(-n, -n,  n),
    CIwSVec3( n, -n,  n),
    CIwSVec3( n,  n,  n),
    CIwSVec3(-n,  n,  n),
};

// Vertex colours
CIwColour s_Cols[8] =
{
    {0xff, 0x00, 0x00, 0x00},
    {0xff, 0xff, 0x00, 0x00},
    {0x00, 0xff, 0xff, 0x00},
    {0x00, 0x00, 0xff, 0x00},
    {0xff, 0x00, 0xff, 0x00},
    {0xff, 0x00, 0x00, 0x00},
    {0xff, 0xff, 0x00, 0x00},
    {0x00, 0xff, 0xff, 0x00},
};

// Index stream
uint16      s_TriStrip[22] =
{
    1, 2, 5, 6, 4, 7, 0, 3, 1, 2,
    2, 4, // degenerates
    4, 0, 5, 1,
    1, 3, // degenerates
    3, 7, 2, 6,
};

// Angles
CIwSVec3     s_Angles;

// Matrices
CIwMat       s_ModelMatrix;
CIwMat       s_ViewMatrix;

// Materials
CIwMaterial *s_Material;

// Update timer
uint32       s_Timer = 0;

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemGx);
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Initialise view matrix - identity rotation, and slightly offset along the X and Y axes.
    s_ViewMatrix.SetIdentity();
    s_ViewMatrix.t.x = -0xc0;
    s_ViewMatrix.t.y = -0xc0;

    // Initialise model matrix - slightly offset along the X axis.
    s_ModelMatrix.SetIdentity();
    s_ModelMatrix.t.x = -0x180;
    s_ModelMatrix.t.y =  0x0;

    // Initialise material
    s_Material = new CIwMaterial;

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_Material;
    delete IwGetMenuManager();

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x24;
    s_Angles.z += 0x38;

    // Build model matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix.CopyRot(rotX * rotY * rotZ);

    // Set view matrix to zoom in and out along world Z axis
    s_ViewMatrix.t.z = -(IW_GEOM_COS(s_Timer << 6) + 0x3000) >> 4;
    IwGxSetViewMatrix(&s_ViewMatrix);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Set material to use for all drawing
    IwGxSetMaterial(s_Material);

    //-------------------------------------------------------------------------
    // Render screenspace quad, top-left
    //-------------------------------------------------------------------------
    // Demonstrate use of the data cache - allocate and write 4 screenspace verts
    CIwSVec2* pCoord = IW_GX_ALLOC(CIwSVec2, 4);
    pCoord[0].x = 0x10; pCoord[0].y = 0x30;
    pCoord[1].x = 0x10; pCoord[1].y = 0x60;
    pCoord[2].x = 0x40; pCoord[2].y = 0x30;
    pCoord[3].x = 0x40; pCoord[3].y = 0x60;

    // Set screenspace origin and Z position
    IwGxSetScreenSpaceOrg(&CIwSVec2::g_Zero);
    IwGxSetScreenSpaceSlot(-1);

    // Set screenspace vertex stream
    // Note how the view and model matrices have no effect
    IwGxSetVertStreamScreenSpace(pCoord, 4);

    // Set colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw screenspace quad. Note that passing in a NULL index stream is equiavalent to passing in an index
    // stream of {0, 1, 2, 3}.
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);

    //-------------------------------------------------------------------------
    // Render viewspace cube, top-right
    //-------------------------------------------------------------------------
    // Set the viewspace origin
    CIwSVec3 vOrg(0xd0, -0x80, 0x300);
    IwGxSetViewSpaceOrg(&vOrg);

    // Set viewspace vertex stream
    // Note how the view and model matrices have no effect
    IwGxSetVertStreamViewSpace(s_Verts, 8);

    // Set colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the cube.
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    //-------------------------------------------------------------------------
    // Render modelspace cube, bottom-left
    //-------------------------------------------------------------------------
    // Set the model matrix
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Set modelspace vertex stream
    // Note how the view and model matrices both have an effect
    IwGxSetVertStream(s_Verts, 8);

    // Set colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the cube.
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    //-------------------------------------------------------------------------
    // Render worldspace cube
    //-------------------------------------------------------------------------
    // Set worldspace vertex stream
    // Note how the model matrix has no effect
    IwGxSetVertStreamWorldSpace(s_Verts, 8);

    // Set colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the cube.
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Texture Examples

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Texture Examples >

IwGx Texture Examples

This section contains the following texture examples:

  • IwGx Texture Example
  • IwGx CIwTexture Example


Airplay API Reference: IwGx Texture Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Texture Examples > IwGx Texture Example >

IwGx Texture Example

Textures can be set on a material. To display a texture on a material, you must:

  1. Load the texture.
  2. Set the texture on the material.
  3. Map the texture on the geometry using UV coordinates.

In this example we add a texture to a material using the following code:

 // Create empty texture object
 s_Texture = new CIwTexture;

 // Load image data from disk into texture
 s_Texture->LoadFromFile("./textures/testTexture_8bit.bmp");

 // "Upload" texture to VRAM
 s_Texture->Upload();

This code loads the file testTexture_8bit.bmp from the data/textures folder in your application directory. UV coordinates must be set for the texture in order to orientate it correctly on the geometry. To do this the UV coordinates are entered as 2D vectors in the ExampleUpdate section of the example code. The UV coordinates use the same indexing as the applied drawing mode; therefore, they must be arranged in the same order to ensure the texture displays correctly.

Note:
1 << 12, 1 bit shifted by 12, indicates a UV coordinate of 1.
The texture must then be set on the material, this is done in the ExampleRender section of our example using the following code:

 mpMatQuad->SetTexture(s_Texture);

Note:
For more information on how to implement materials and how to use textures in your application, see the Texture section of the IwGx API Documentation.
The example application demonstrates how to create a textured spinning cube. Two primitives are drawn - an untextured, vertex coloured tri list (5 faces of the cube); and a textured, uncoloured quad list (1 face of the cube).

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxTexture
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwMaterial.h"
#include "IwTexture.h"

// Texture object
CIwTexture* s_Texture = NULL;

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[8] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3(-s,  s,  s),
};

// Colour data
CIwColour   s_Cols[8] =
{
    {0x00, 0x00, 0x00},
    {0x00, 0x00, 0xff},
    {0x00, 0xff, 0x00},
    {0x00, 0xff, 0xff},
    {0xff, 0x00, 0x00},
    {0xff, 0x00, 0xff},
    {0xff, 0xff, 0x00},
    {0xff, 0xff, 0xff},
};

// UV data
CIwSVec2    s_UVs[4] =
{
    CIwSVec2(0 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 1 << 12),
    CIwSVec2(0 << 12, 1 << 12),
};

// Index stream for textured material
uint16      s_QuadStrip[4] =
{
    0, 3, 1, 2,
};

// Index stream for untextured material
uint16      s_TriStrip[20] =
{
    1, 2, 5, 6, 4, 7, 0, 3,
    3, 4, // degenerates
    4, 0, 5, 1,
    1, 3, // degenerates
    3, 7, 2, 6,
};

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Turn all lighting off
    IwGxLightingOff();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Create empty texture object
    s_Texture = new CIwTexture;

    // Load image data from disk into texture
    s_Texture->LoadFromFile("./textures/testTexture_8bit.bmp");

    // "Upload" texture to VRAM
    s_Texture->Upload();

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x200;
    IwGxSetViewMatrix(&view);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Destroy texture
    delete s_Texture;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x20;
    s_Angles.z += 0x30;

    // Build model matrix from angles
    CIwMat  rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix = rotX * rotY * rotZ;

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    CIwMaterial* pMat;

    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate and initialise material from the IwGx global cache
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the model matrix
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Set the (modelspace) vertex stream
    IwGxSetVertStreamModelSpace(s_Verts, 8);

    // Set the vertex colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the untextured primitives
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 20);

    // Allocate and initialise another material
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set the diffuse map
    pMat->SetTexture(s_Texture);

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the vertex UV stream
    IwGxSetUVStream(s_UVs);

    // Clear the vertex colour stream
    IwGxSetColStream(NULL);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, s_QuadStrip, 4);

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx CIwTexture Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Texture Examples > IwGx CIwTexture Example >

IwGx CIwTexture Example

The following example loads an image file and demonstrates texture operations.

The main classes used to achieve this are:

  • CIwTexture
  • CIwImage

The main functions used to achieve this are:

  • CIwTexture::LoadFromFile()
  • CIwTexture::Upload()
  • CIwTexture::CopyFromBuffer()
  • CIwTexture::SetImage()
  • CIwTexture::ExtractSubTexture()
  • CIwTexture::ChangePalette()
  • CIwTexture::SetModifiable()

By pressing s3eKey1 you can cycle through the list of texture operations this example demonstrates. The operations demonstrated are as follows:

  • LoadFromFile: loads a new texture from file if one does not already exist using the LoadFromFile() function and then the Upload() function is called to put the texture in VRAM.
  • CopyFromBuffer: creates a colour palette and texel set which are used by the CopyFromBuffer() function to create an image of size 0x4 x 0x4. The Upload() function is called to put the created texture in VRAM.
  • CopyFromImage: opens an image file and reads it. It then creates a new texture and copies the the texture from the loaded image. The Upload() function is used to load the texture into VRAM.
  • SetImage: creates a CIwImage object, opens a texture file and reads the texture into the CIwImage object. A texture object is created and the SetImage() function is used to transfer ownership of the image data to the newly created texture object. The Upload() function is then used to load the texture into VRAM.
  • ExtractSubTexture: creates a CIwTexture object and loads a texture from file using the LoadFromFile function. It then uses the ExtractSubTexture() function to create a new subtexture from the existing texture. The texture then loaded into VRAM using the Upload() function.
  • ChangePalette: creates a static palette and then loads a texture from file using the LoadFromFile() function. The ChangePalette() function is then used to change the palette used by the texture by supplying the new palette and the data format.
  • ChangeTexels: sets a texture palette and a set of 8 texels. The 4x4 texture displayed using the CopyFromBuffer() function. The textures is constructed by changing the texel settings for each render loop, which results in a different section of the palette being used.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxCIwTexture
//-----------------------------------------------------------------------------

#include "s3e.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwTexture.h"
#include "ExamplesMain.h"

// Main texture for test
// This should be uploaded by end of test update function
CIwTexture* g_Texture = NULL;

enum TEXTURE_TESTS
{
    LOADFROMFILE,
    COPYFROMBUFFER,
    COPYFROMIMAGE,
    SETIMAGE,
    EXTRACTSUBTEXTURE,
    CHANGEPALETTE,
    CHANGETEXELS,
    MAX_TEXTURE_TESTS,
};

const char* s_TestNames[]=
{
    "LoadFromFile",
    "CopyFromBuffer",
    "CopyFromImage",
    "SetImage",
    "ExtractSubTexture",
    "ChangePalette",
    "ChangeTexels",
};

//-----------------------------------------------------------------------------
// The following function loads a new texture from file if one does not already
// exist using the LoadFromFile() function and then the
// Upload() function is called to put the texture in VRAM.
//-----------------------------------------------------------------------------
void Update_LoadFromFile()
{
    // Skip update if texture already exists
    if(g_Texture) return;

    // Load texture from File
    g_Texture = new CIwTexture;

    g_Texture->LoadFromFile("textures/testTexture_4bit.bmp");

    g_Texture->Upload(); // Upload the result
}

//-----------------------------------------------------------------------------
// The following function creates a colour palette and texel set which are
// used by the CopyFromBuffer() function to create an image of size 0x4 x 0x4.
// The Upload() function is called to put the created texture in VRAM.
//-----------------------------------------------------------------------------
void Update_CopyFromBuffer()
{
    // Skip update if texture already exists
    if(g_Texture) return;

    //Copy from buffer
    uint8 palette[16 * 3] =
    {
        0x00, 0x00, 0x00,
        0x00, 0x00, 0x40,
        0x00, 0x00, 0x80,
        0x00, 0x00, 0xc0,
        0x00, 0x80, 0x00,
        0x00, 0x80, 0x40,
        0x00, 0x80, 0x80,
        0x00, 0x80, 0xc0,
        0x80, 0x80, 0x00,
        0x80, 0x80, 0x40,
        0x80, 0x80, 0x80,
        0x80, 0x80, 0xc0,
        0x80, 0x00, 0x00,
        0x80, 0x00, 0x40,
        0x80, 0x00, 0x80,
        0x80, 0x00, 0xc0,
    };
    uint8 texels[4 * 2] =
    {
        0x10, 0x32,
        0x54, 0x76,
        0x98, 0xba,
        0xdc, 0xfe,
    };

    g_Texture = new CIwTexture;

    g_Texture->CopyFromBuffer(0x4, 0x4, CIwImage::PALETTE4_RGB_888, 2, texels, (uint16*)palette);

    g_Texture->Upload(); // Upload the result
}

//-----------------------------------------------------------------------------
// The following function opens an image file and reads it. It then creates a
// new texture and copies the the texture from the loaded image. The Upload()
// function is used to load the texture into VRAM.
//-----------------------------------------------------------------------------
void Update_CopyFromImage()
{
    // Skip update if texture already exists
    if(g_Texture) return;

    // Copy from Image
    // Load an image directly then copy all the data to a new texture
    CIwImage image;
    s3eFile* pFile = s3eFileOpen("textures/testTexture_4bit.bmp", "rb");
    if (pFile)
    {
        image.ReadFile(pFile);
        s3eFileClose(pFile);

        // Create a new empty texture
        g_Texture = new CIwTexture;

        // Copy image data
        g_Texture->CopyFromImage(&image);

        // Upload the result
        g_Texture->Upload();
    }
}

//-----------------------------------------------------------------------------
// The following function creates a CIwImage object, opens a texture file and
// reads the texture into the CIwImage object. A texture object is created and
// the SetImage() function is used to transfer ownership of the image data
// to the newly created texture object. The Upload() function is then used to
// load the texture into VRAM.
//-----------------------------------------------------------------------------
void Update_SetImage()
{
    // Skip update if texture already exists
    if(g_Texture) return;

    // Copy from Image
    // Load an image directly then transfer buffers to a new texture
    // Ownership of buffers is transfered rather than copied, a faster operation than CopyFromImage.
    CIwImage image;
    s3eFile* pFile = s3eFileOpen("textures/testTexture_4bit.bmp", "rb");
    if (pFile)
    {
        image.ReadFile(pFile);
        s3eFileClose(pFile);

        // Create a new empty texture
        g_Texture = new CIwTexture;

        // Set image data
        // This transfers ownership of pImage's buffers to g_Texture
        g_Texture->SetImage(&image);

        // Upload the result
        g_Texture->Upload();
    }
}

//-----------------------------------------------------------------------------
// The following function creates a CIwTexture object and loads a texture from
// file using the LoadFromFile function. It then uses the ExtractSubTexture()
// function to create a new subtexture from the existing texture. The texture
// then loaded into VRAM using the Upload() function.
//-----------------------------------------------------------------------------
void Update_ExtractSubTexture()
{
    // Skip update if texture already exists
    if(g_Texture) return;

    // Load original texture
    CIwTexture whole_texture;
    whole_texture.LoadFromFile("textures/testTexture_4bit.bmp");

    // Extract Sub Texture - This will return a new texture with the reduced dimensions specified
    // eg: Numbers given will extract image of the number four from the test texture
    g_Texture = whole_texture.ExtractSubTexture(12, 50, 32, 32, "NumberFour");

    g_Texture->Upload(); // Upload the result
}

//-----------------------------------------------------------------------------
// The following function creates a static palette and then loads a texture
// from file using the LoadFromFile() function. The ChangePalette() function is
// then used to change the palette used by the texture by supplying the new
// palette and the data format.
//-----------------------------------------------------------------------------
void Update_ChangePalette()
{
    // Static palette data
    static uint16 pal[16] =
    {
        0x0000, 0x1111, 0x2222, 0x3333,
        0x4444, 0x5555, 0x6666, 0x7777,
        0x8888, 0x9999, 0xaaaa, 0xbbbb,
        0xcccc, 0xdddd, 0xeeee, 0xffff,
    };
    static uint16 pal_change(0);
    pal_change = (pal_change+1)%16;

    // Load texture first time only
    if(!g_Texture)
    {
        // Load texture from File
        g_Texture = new CIwTexture;
        g_Texture->LoadFromFile("textures/testTexture_4bit.bmp");

        // Palettes can be changed pre-upload
        // A copy of the new palette is made into the texture
        g_Texture->ChangePalette(pal, CIwImage::PALETTE4_RGBA_5551);

        // We need to keep the data for changing the palette
        g_Texture->SetModifiable( true );

        // Upload the result
        g_Texture->Upload();
    }
    else
    {
        // Post-Upload Change
        // Change palette entries with random effect
        pal[pal_change] = (uint16)(IwRand()%0xFFFF)|0x1;

        // Change for an animated palette
        g_Texture->ChangePalette(pal, CIwImage::PALETTE4_RGBA_5551 );
    }
}

//-----------------------------------------------------------------------------
// The following function sets a texture palette of 16 colours and a set of 8
// texels. The 4x4 texture displayed using the CopyFromBuffer() function. The
// textures is constructed by changing the texel settings for each
// render loop, which results in a different section of the palette being used.
//-----------------------------------------------------------------------------
void Update_ChangeTexels()
{
    // Static Data
    static uint8 palette[16 * 3] =
    {
        0x00, 0x00, 0x00,
        0x00, 0x00, 0x40,
        0x00, 0x00, 0x80,
        0x00, 0x00, 0xc0,
        0x00, 0x80, 0x00,
        0x00, 0x80, 0x40,
        0x00, 0x80, 0x80,
        0x00, 0x80, 0xc0,
        0x80, 0x80, 0x00,
        0x80, 0x80, 0x40,
        0x80, 0x80, 0x80,
        0x80, 0x80, 0xc0,
        0x80, 0x00, 0x00,
        0x80, 0x00, 0x40,
        0x80, 0x00, 0x80,
        0x80, 0x00, 0xc0,
    };

    // 4*4 image with 4bits per pixel
    static uint8 texels[4 * 2] =
    {
        0x10, 0x32,
        0x54, 0x76,
        0x98, 0xba,
        0xdc, 0xfe,
    };

    static uint16 texel_change(0);
    texel_change = (texel_change+1)%8;

    // Load texture first time only
    if(!g_Texture)
    {
        // Create new texture and copy data from buffers
        g_Texture = new CIwTexture;
        g_Texture->CopyFromBuffer(0x4, 0x4, CIwImage::PALETTE4_RGB_888, 2, texels, (uint16*)palette);

        // Texels can be changed pre-upload using a format given by g_Texture->GetFormat()
        // A copy of the new texel data is made into the texture
        g_Texture->ChangeTexels(texels);

        // We need to keep the data for changing the palette
        g_Texture->SetModifiable( true );

        // Upload the result
        g_Texture->Upload();
    }
    else
    {
        // In Software texels can be changed after upload - (Not in hardware)
        // Texel format for post-upload change is given by g_Texture->GetFormatSW()

        // Change texel entries with random effect
        texels[texel_change] = (uint8)(IwRand()%0xFF);

        // Change for an animated palette
        g_Texture->ChangeTexels(texels, CIwImage::PALETTE4_RGB_888);
    }
}

typedef void(*UpdateFN)(void);

UpdateFN g_TestUpdateFunctions[]=
{
    Update_LoadFromFile,
    Update_CopyFromBuffer,
    Update_CopyFromImage,
    Update_SetImage,
    Update_ExtractSubTexture,
    Update_ChangePalette,
    Update_ChangeTexels,
};

uint16 g_CurrentTest = 0;

#define min(_a,_b) ((_a)<(_b)?(_a):(_b))

void CreateButtonsUI(int w, int h)
{
    // Create button
    AddButton("Press 1 for next test", 2,h-50,w,30, s3eKey1);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
// The following function sets the screen colour and turns off the lighting.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();

    // Turn all lighting off
    IwGxLightingOff();

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
// The following function deletes g_texture if it still exists and termiates
// IwGx functionality.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    if(g_Texture)
        delete g_Texture;

    // Terminate
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
// The following function cycles through the list of tests that are available
// when s3eKey1 is pressed.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    if (CheckButton("Press 1 for next test") & S3E_KEY_STATE_PRESSED)
    {
        g_CurrentTest = (g_CurrentTest+1)%MAX_TEXTURE_TESTS;

        // Clear old assets
        if(g_Texture)
            delete g_Texture;
        g_Texture = NULL;
    }

    // Update current test
    g_TestUpdateFunctions[g_CurrentTest]();

    return true;
}
//-----------------------------------------------------------------------------
// The following function displays the updated texture.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    if(g_Texture)
    {
        // Allocate a material from the IwGx global cache
        CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
        pMat->SetModulateMode(CIwMaterial::MODULATE_NONE);

        // Use Texture on Material
        pMat->SetTexture(g_Texture);

        // Set this as the active material
        IwGxSetMaterial(pMat);

        // Set up screenspace vertex coords
        int16 size = (int16)min(IwGxGetScreenHeight(),IwGxGetScreenWidth()) / 3;
        int16 x1 = (int16)IwGxGetScreenWidth()/2 - size;
        int16 x2 = (int16)IwGxGetScreenWidth()/2 + size;
        int16 y1 = (int16)IwGxGetScreenHeight()/2 - size;
        int16 y2 = (int16)IwGxGetScreenHeight()/2 + size;

        static CIwSVec2 xy3[4];
        xy3[0].x = x1, xy3[0].y = y1;
        xy3[1].x = x1, xy3[1].y = y2;
        xy3[2].x = x2, xy3[2].y = y2;
        xy3[3].x = x2, xy3[3].y = y1;
        IwGxSetVertStreamScreenSpace(xy3, 4);

        static CIwSVec2 uvs[4] =
        {
            CIwSVec2(0 << 12, 0 << 12),
            CIwSVec2(0 << 12, 1 << 12),
            CIwSVec2(1 << 12, 1 << 12),
            CIwSVec2(1 << 12, 0 << 12),
        };
        IwGxSetUVStream(uvs);

        // Draw single triangle
        IwGxDrawPrims(IW_GX_QUAD_LIST, NULL, 4);
    }

    // Help Text
    IwGxPrintString(2,IwGxGetScreenHeight()-20, s_TestNames[g_CurrentTest], 0);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Lighting Examples

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Lighting Examples >

IwGx Lighting Examples

This section contains the following Lighting examples:

  • IwGx Basic Lighting Example
  • IwGx Lighting Example


Airplay API Reference: IwGx Basic Lighting Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Lighting Examples > IwGx Basic Lighting Example >

IwGx Basic Lighting Example

The following example demonstrates how to display a single textured spinning cube, with ambient and diffuse scene lighting. The example allows you to change the lighting values using the debug menu.

The main classes used to achieve this are:

  • CIwMenu
  • CIwMenuItemEditUInt8
  • CIwMenuManager
  • CIwMenuItemGx
  • CIwMaterial
  • CIwTexture

The main functions used to achieve this are:

  • CIwMenu::AddItem()
  • IwGxSetLightType()
  • IwGxSetLightDirn()
  • IwGxLightingOn()
  • CIwMenuManager::SetTextCallback();
  • CIwMenuManager::SetMainMenuFn()
  • CIwMenuManager::Update()

Toggle the pipeline transform, lighting and rasterisation settings, to see the effect of switching the pipeline stages between SW and GL.

The following graphics illustrates the example output.

Note:
For more information on IwGx Lighting, see the Lighting section.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxBasicLighting
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwMenu.h"
#include "IwTexture.h"

// Texture object
CIwTexture* s_Texture = NULL;

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[24] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),

    CIwSVec3( s, -s, -s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3( s,  s, -s),

    CIwSVec3( s, -s,  s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3(-s,  s,  s),
    CIwSVec3( s,  s,  s),

    CIwSVec3(-s, -s,  s),
    CIwSVec3(-s, -s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s,  s,  s),

    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s, -s,  s),
    CIwSVec3(-s, -s,  s),

    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s,  s,  s),
    CIwSVec3( s,  s,  s),
};

// Normal data
const int16 n = 0x93c;
CIwSVec3    s_Norms[24] =
{
    CIwSVec3(-n, -n, -n),
    CIwSVec3( n, -n, -n),
    CIwSVec3( n,  n, -n),
    CIwSVec3(-n,  n, -n),

    CIwSVec3( n, -n, -n),
    CIwSVec3( n, -n,  n),
    CIwSVec3( n,  n,  n),
    CIwSVec3( n,  n, -n),

    CIwSVec3( n, -n,  n),
    CIwSVec3(-n, -n,  n),
    CIwSVec3(-n,  n,  n),
    CIwSVec3( n,  n,  n),

    CIwSVec3(-n, -n,  n),
    CIwSVec3(-n, -n, -n),
    CIwSVec3(-n,  n, -n),
    CIwSVec3(-n,  n,  n),

    CIwSVec3(-n, -n, -n),
    CIwSVec3( n, -n, -n),
    CIwSVec3( n, -n,  n),
    CIwSVec3(-n, -n,  n),

    CIwSVec3( n,  n, -n),
    CIwSVec3(-n,  n, -n),
    CIwSVec3(-n,  n,  n),
    CIwSVec3( n,  n,  n),
};

// UV data
CIwSVec2    s_UVs[24] =
{
    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),
};

// Index stream for textured material
uint16      s_QuadList[24] =
{
    0, 3, 2, 1,
    4, 7, 6, 5,
    8, 11, 10, 9,
    12, 15, 14, 13,
    16, 17, 18, 19,
    20, 21, 22, 23,
};

// Angles
CIwSVec3     s_Angles;

// Local matrix
CIwMat       s_ModelMatrix;

// Materials
CIwMaterial *s_MaterialBG;
CIwMaterial *s_MaterialCube;

// Update timer
uint32       s_Timer = 0;

// Ambient scene light colour
CIwColour    s_ColSceneAmb = {0x20, 0x20, 0x20};

// Diffuse scene light colour
CIwColour    s_ColSceneDiff = {0xf0, 0xf0, 0xf0};

//--------------------------------------------------------------------------------
// The following code creates a new menu which can be accessed when the example
// is running by pressing F6.
//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemGx);
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.r", &s_ColSceneAmb.r));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.g", &s_ColSceneAmb.g));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.b", &s_ColSceneAmb.b));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.r", &s_ColSceneDiff.r));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.g", &s_ColSceneDiff.g));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.b", &s_ColSceneDiff.b));
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
// The following function creates a new material and loads a new texture to be
// used by the spinning cube. It also sets diffuse and ambient lighting for the
// scene using the IwGxSetLightType() function. The IwGxSetLightDirn() is used
// to set the direction of the Diffuse lighting.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Initialise materials
    s_MaterialBG = new CIwMaterial;

    s_MaterialCube = new CIwMaterial;
    s_Texture = new CIwTexture;
    s_Texture->LoadFromFile("./textures/testTexture.bmp");
    s_Texture->Upload();
    s_MaterialCube->SetTexture(s_Texture);

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x200;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}
//-----------------------------------------------------------------------------
// The following function destroys the various classes that have been created
// within the example.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_Texture;
    delete IwGetMenuManager();

    delete s_MaterialBG;
    delete s_MaterialCube;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
// The following function updates the view and the lighting values.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x24;
    s_Angles.z += 0x38;

    // Build model matrix from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix = rotX * rotY * rotZ;

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update scene light colours from user colours
    // Set single ambient light
    IwGxSetLightCol(0, &s_ColSceneAmb);
    IwGxSetLightCol(1, &s_ColSceneDiff);

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the spinning cube and any debug menu that has
// selected.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    //-------------------------------------------------------------------------
    // Render cube
    //-------------------------------------------------------------------------
    // Use all lighting
    IwGxLightingOn();

    // Set the model matrix
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Set vertex stream
    IwGxSetVertStreamModelSpace(s_Verts, 24);

    // Set normal stream
    IwGxSetNormStream(s_Norms, 24);

    // Clear colour stream
    IwGxSetColStream(NULL);

    // Set UV stream
    IwGxSetUVStream(s_UVs);

    // Set material
    IwGxSetMaterial(s_MaterialCube);

    // Draw 6 quads
    IwGxDrawPrims(IW_GX_QUAD_LIST, s_QuadList, 24);

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Lighting Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Lighting Examples > IwGx Lighting Example >

IwGx Lighting Example

IwGx uses the same lighting model as OpenGL ES. The lighting for a material is calculated using the following formula:

C_v = M_e + (M_a * S_a) + (M_d * S_d * Falloff) + (M_s * S_s * SpecularFalloff)

Where:

  • C_v is the calculated vertex colour.
  • M_e is the material emissive colour.
  • M_a is the material ambient colour (ambient response).
  • M_d is the material diffuse colour (diffuse response).
  • M_s is the material specular colour (specular response).
  • S_a is the scene ambient colour (colour of single ambient light).
  • S_d is the scene diffuse colour (colour of single diffuse light).
  • S_s is the scene specular colour (specular colour of single diffuse light).
  • Falloff is the dot product falloff calculated from vertex normal and single diffuse light direction.
  • SpecularFalloff is the dot product falloff calculated from the half vector between the camera direction and the single diffuse light direction.

Lighting is set using colour values. All possible lighting values are combined using the above formula and then applied to each vertex. If a colour stream is also supplied, then the supplied colour replaces both M_a and M_d at each vertex.

Note:
For a detailed description of how to implement Lighting Response in your application, see the Lighting section of the IwGx API Documentation
This example demonstrates use of the lighting model. An ambient scene light and diffuse scene light are created. The diffuse light points at 90 degrees to each axis. Each of the four cubes uses its own dynamically-modified material, and prior to rendering, enables or disables some components of the lighting equation as follows:
  • Cube 0 (top-left): enables emissive lighting only, and ramps its material emissive colour from black to white.
  • Cube 1 (top-right): enables ambient lighting only, and ramps its material ambient response from black to cyan.
  • Cube 2 (bottom-left): enables diffuse lighting only, and ramps its material diffuse response from black to magenta.
  • Cube 3 (bottom-right): enables all lighting, and ramps its material emissive colour from black to blue.
The example also demonstrates use of the debug menu manager: Hit F1 to toggle up the menu manager. Use up, down, right and left to navigate the menus. Use NumPad+ and NumPad- to modify values. Hold down SHIFT * or CONTROL to modify a value in steps of 10 and 100 respectively.

Try modifying the ambient and diffuse colours. Notice how the cube colours change, and think about how the lighting model is working.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxLighting
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwMenu.h"

#include "ExamplesMain.h"

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[8] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3(-s,  s,  s),
};

// Normal data
const int16 n = 0x93c;
CIwSVec3    s_Norms[8] =
{
    CIwSVec3(-n, -n, -n),
    CIwSVec3( n, -n, -n),
    CIwSVec3( n,  n, -n),
    CIwSVec3(-n,  n, -n),
    CIwSVec3(-n, -n,  n),
    CIwSVec3( n, -n,  n),
    CIwSVec3( n,  n,  n),
    CIwSVec3(-n,  n,  n),
};

// Index stream
uint16      s_TriStrip[22] =
{
    1, 2, 5, 6, 4, 7, 0, 3, 1, 2,
    2, 4, // degenerates
    4, 0, 5, 1,
    1, 3, // degenerates
    3, 7, 2, 6,
};

// Angles
CIwSVec3     s_Angles;

// Local matrix
CIwMat       s_ModelMatrix;

// Materials
CIwMaterial *s_MaterialBG;
CIwMaterial *s_MaterialCubes[4];

// Update timer
uint32       s_Timer = 0;

// Ambient scene light colour
CIwColour    s_ColSceneAmb = {0x80, 0x80, 0x80};

// Diffuse scene light colour
CIwColour    s_ColSceneDiff = {0x80, 0x80, 0x80};

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemGx);
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.r", &s_ColSceneAmb.r));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.g", &s_ColSceneAmb.g));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneAmb.b", &s_ColSceneAmb.b));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.r", &s_ColSceneDiff.r));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.g", &s_ColSceneDiff.g));
    pMenu->AddItem(new CIwMenuItemEditUInt8("ColSceneDiff.b", &s_ColSceneDiff.b));
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x400;
    IwGxSetViewMatrix(&view);

    s_MaterialBG = new CIwMaterial();
    s_MaterialCubes[0] = new CIwMaterial();
    s_MaterialCubes[1] = new CIwMaterial();
    s_MaterialCubes[2] = new CIwMaterial();
    s_MaterialCubes[3] = new CIwMaterial();

    // Note: If ambient light is not enabled, the material ambient is added without being modulated by an ambient light value
    // So set to black to remove all ambient contribution from these cubes
    s_MaterialCubes[0]->SetColAmbient(0x00000000);
    s_MaterialCubes[2]->SetColAmbient(0x00000000);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    IwGxSetLightCol(0, 0x80, 0x80, 0x80);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    IwGxSetLightCol(1, 0x80, 0x80, 0x80);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_MaterialBG;
    delete s_MaterialCubes[0];
    delete s_MaterialCubes[1];
    delete s_MaterialCubes[2];
    delete s_MaterialCubes[3];

    delete IwGetMenuManager();

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x24;
    s_Angles.z += 0x38;

    // Build model matrix from angles
    s_ModelMatrix.SetRotY(s_Angles.y);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update scene light colours from user colours
    // Set single ambient light
    IwGxSetLightCol(0, &s_ColSceneAmb);
    IwGxSetLightCol(1, &s_ColSceneDiff);
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render background
    //-------------------------------------------------------------------------
    // Set active material
    IwGxSetMaterial(s_MaterialBG);

    // Set colour stream
    static CIwColour bgCols[4] =
    {
        {0xff, 0x00, 0x00},
        {0x00, 0xff, 0x00},
        {0x00, 0x00, 0xff},
        {0x00, 0xff, 0xff},
    };
    IwGxSetColStream(bgCols, 4);

    // Set the (screenspace) vertex stream
    CIwSVec2* pCoords = AllocClientScreenRectangle();
    IwGxSetScreenSpaceOrg(&CIwSVec2::g_Zero);
    IwGxSetScreenSpaceSlot(-1);
    IwGxSetVertStreamScreenSpace(pCoords, 4);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);

    //-------------------------------------------------------------------------
    // Render cubes
    //-------------------------------------------------------------------------
    // Clear colour stream
    IwGxSetColStream(NULL);

    // Set normal stream once
    IwGxSetNormStream(s_Norms, 8);

    //-------------------------------------------------------------------------
    // Cube 0 (top-left)... use emissive only, ramp emissive colour from black to white
    //-------------------------------------------------------------------------
    s_MaterialCubes[0]->SetColEmissive(((s_Timer << 2) & 0xff) * 0x010101);
    IwGxSetMaterial(s_MaterialCubes[0]);
    IwGxLightingEmissive(true);

    s_ModelMatrix.t.x = -0x100;
    s_ModelMatrix.t.y = -0x0a0;
    IwGxSetModelMatrix(&s_ModelMatrix);
    IwGxSetVertStreamModelSpace(s_Verts, 16);
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    //-------------------------------------------------------------------------
    // Cube 1 (top-right)... use ambient only, ramp ambient response from black to cyan
    //-------------------------------------------------------------------------
    s_MaterialCubes[1]->SetColAmbient(((s_Timer << 2) & 0xff) * 0x010100);
    IwGxSetMaterial(s_MaterialCubes[1]);
    IwGxLightingEmissive(false);
    IwGxLightingAmbient(true);

    s_ModelMatrix.t.x =  0x100;
    s_ModelMatrix.t.y = -0x0a0;
    IwGxSetModelMatrix(&s_ModelMatrix);
    IwGxSetVertStreamModelSpace(s_Verts, 16);
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    //-------------------------------------------------------------------------
    // Cube 2 (bottom-left)... use diffuse and specular, ramp diffuse response from black to magenta
    //-------------------------------------------------------------------------
    s_MaterialCubes[2]->SetColDiffuse(((s_Timer << 2) & 0xff) * 0x010001);
    s_MaterialCubes[2]->SetColSpecular(0xff, 0xff, 0xff);
    s_MaterialCubes[2]->SetSpecularPower(2);
    IwGxSetMaterial(s_MaterialCubes[2]);
    IwGxLightingAmbient(false);
    IwGxLightingDiffuse(true);
    IwGxLightingSpecular(true);

    s_ModelMatrix.t.x = -0x100;
    s_ModelMatrix.t.y =  0x100;
    IwGxSetModelMatrix(&s_ModelMatrix);
    IwGxSetVertStreamModelSpace(s_Verts, 16);
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    //-------------------------------------------------------------------------
    // Cube 3 (bottom-right)... use emissive, ambient and diffuse. Ramp emissive from black to blue
    //-------------------------------------------------------------------------
    s_MaterialCubes[3]->SetColEmissive(((s_Timer << 2) & 0xff) * 0x010000);
    s_MaterialCubes[3]->SetColAmbient(0x404040);
    s_MaterialCubes[3]->SetColDiffuse(0xc0c0c0);
    IwGxSetMaterial(s_MaterialCubes[3]);
    IwGxLightingOn();

    s_ModelMatrix.t.x =  0x100;
    s_ModelMatrix.t.y =  0x100;
    IwGxSetModelMatrix(&s_ModelMatrix);
    IwGxSetVertStreamModelSpace(s_Verts, 16);
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 22);

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Surface Examples

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Surface Examples >

IwGx Surface Examples

This section contains the following surface examples:

  • IwGx Surface Offscreen Example
  • IwGx Surface Post Process Example


Airplay API Reference: IwGxSurface Offscreen Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Surface Examples > IwGxSurface Offscreen Example >

IwGxSurface Offscreen Example

Surfaces can be used to perform offscreen rendering. To use a surface you must:

  1. Create the destination surface.
  2. Select the destination surface as the current surface.
  3. Perform rendering as usual.
  4. Select the display as the current surface.
  5. Perform rendering using the surface's attached texture.

In this example we render a cube and then render the cube again using the previously rendered cube as one of the faces.

The code to create the surface is:

    // Create a 256x256 surface. A NULL texture pointer is passed
    // to indicate that the surface should create a texture.
    if( !s_Surface->CreateSurface(NULL, 256, 256, 0) )
        IwError(("Surface creation failed"));

This code creates an offscreen surface that can be rendered to.

The desired size of the surface is specified and default surface behaviour is requested.

This example does not handle the surface not being created. A real application should be prepared for this eventuality and fall back gracefully. The default fallback provides a reasonable compromise for this demo.

Note:
The resulting surface may not exactly match the requested size/capabilities depending on the requirements of the current renderer. Generally surfaces will be power-of-2 sizes up to some maximum.
In order to render to the offscreen surface it must be selected as the current surface.

    s_Surface->MakeCurrent();

All rendering will now go to s_Surface.

Once all render commands for the offscreen surface have been issued the display should be reselected.

    CIwGxSurface::MakeDisplayCurrent();

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxTexture
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwMaterial.h"
#include "IwTexture.h"

// Texture object
CIwTexture* s_Texture = NULL;

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[8] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3(-s,  s,  s),
};

// Colour data
CIwColour   s_Cols[8] =
{
    {0x00, 0x00, 0x00},
    {0x00, 0x00, 0xff},
    {0x00, 0xff, 0x00},
    {0x00, 0xff, 0xff},
    {0xff, 0x00, 0x00},
    {0xff, 0x00, 0xff},
    {0xff, 0xff, 0x00},
    {0xff, 0xff, 0xff},
};

// UV data
CIwSVec2    s_UVs[4] =
{
    CIwSVec2(0 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 1 << 12),
    CIwSVec2(0 << 12, 1 << 12),
};

// Index stream for textured material
uint16      s_QuadStrip[4] =
{
    0, 3, 1, 2,
};

// Index stream for untextured material
uint16      s_TriStrip[20] =
{
    1, 2, 5, 6, 4, 7, 0, 3,
    3, 4, // degenerates
    4, 0, 5, 1,
    1, 3, // degenerates
    3, 7, 2, 6,
};

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Turn all lighting off
    IwGxLightingOff();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Create empty texture object
    s_Texture = new CIwTexture;

    // Load image data from disk into texture
    s_Texture->LoadFromFile("./textures/testTexture_8bit.bmp");

    // "Upload" texture to VRAM
    s_Texture->Upload();

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x200;
    IwGxSetViewMatrix(&view);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Destroy texture
    delete s_Texture;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x20;
    s_Angles.z += 0x30;

    // Build model matrix from angles
    CIwMat  rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix = rotX * rotY * rotZ;

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    CIwMaterial* pMat;

    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate and initialise material from the IwGx global cache
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the model matrix
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Set the (modelspace) vertex stream
    IwGxSetVertStreamModelSpace(s_Verts, 8);

    // Set the vertex colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the untextured primitives
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 20);

    // Allocate and initialise another material
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set the diffuse map
    pMat->SetTexture(s_Texture);

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the vertex UV stream
    IwGxSetUVStream(s_UVs);

    // Clear the vertex colour stream
    IwGxSetColStream(NULL);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, s_QuadStrip, 4);

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxSurface PostProcess Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Surface Examples > IwGxSurface PostProcess Example >

IwGxSurface PostProcess Example

The IwGxSurface simplies post-process type effect work. Surfaces hold a "client window" rectangle that is automatically set as the active view rectangle when the surface is selected. This circumvents various limitations of the underlying surface implementations (like being restricted to non-power-2 textures).

In this example we use two surfaces to apply a motion blur to a flying cube. The frame is rendered to s_FrameSurface, then s_FrameSurface is blended with the contents of s_AccumulatingSurface. Finally s_AccumulatingSurface is copied to the display surface.

Extra flags are passed to surface creation:

    if( !s_AccumulatingSurface->CreateSurface(NULL,
        IwGxGetScreenWidth(), IwGxGetScreenHeight(),
        CIwGxSurface::EXACT_MATCH_F | CIwGxSurface::PERSISTENT_F) )
    {
        IwError(("Surface creation failed"));
    }

This code creates an offscreen surface the same size as the screen (i.e. the display surface).

The EXACT_MATCH_F flag requests a surface that is large enough to give an exact match to the dimensions requested (the actual surface will probably be larger). If a large enough surface cannot be provided the largest possible size will be used.

The PERSISTENT_F flag requires the surface to be persistent - that is, when the surface is switched to, it has the same contents it had last time it was selected. The accumulating buffer must be persistent, so the previous frame is still present.

Note:
Persistent surfaces can be considerably slower than non-persistent surfaces, so it's usually best to only request this if it's strictly necessary (as in this example).
The client window of the surface is selected when the surface is made current. IwGxGetDisplayWidth/IwGxGetDisplayHeight will contain the client window dimensions. When rendering from the surface's texture GetClientUVExtent() can be used to render the client portion of the texture.

    CIwSVec2 wh((int16)IwGxGetDisplayWidth(), (int16)IwGxGetDisplayHeight());
    IwGxDrawRectScreenSpace(&CIwSVec2::g_Zero, &wh, &CIwSVec2::g_Zero, &pSurface->GetClientUVExtent());

This example does not handle the surface(s) not being created. A real application should be prepared for this eventuality and fall back gracefully. The default fallback provides a reasonable compromise for this example.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxTexture
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwMaterial.h"
#include "IwTexture.h"

// Texture object
CIwTexture* s_Texture = NULL;

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[8] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3(-s,  s,  s),
};

// Colour data
CIwColour   s_Cols[8] =
{
    {0x00, 0x00, 0x00},
    {0x00, 0x00, 0xff},
    {0x00, 0xff, 0x00},
    {0x00, 0xff, 0xff},
    {0xff, 0x00, 0x00},
    {0xff, 0x00, 0xff},
    {0xff, 0xff, 0x00},
    {0xff, 0xff, 0xff},
};

// UV data
CIwSVec2    s_UVs[4] =
{
    CIwSVec2(0 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 1 << 12),
    CIwSVec2(0 << 12, 1 << 12),
};

// Index stream for textured material
uint16      s_QuadStrip[4] =
{
    0, 3, 1, 2,
};

// Index stream for untextured material
uint16      s_TriStrip[20] =
{
    1, 2, 5, 6, 4, 7, 0, 3,
    3, 4, // degenerates
    4, 0, 5, 1,
    1, 3, // degenerates
    3, 7, 2, 6,
};

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Turn all lighting off
    IwGxLightingOff();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Create empty texture object
    s_Texture = new CIwTexture;

    // Load image data from disk into texture
    s_Texture->LoadFromFile("./textures/testTexture_8bit.bmp");

    // "Upload" texture to VRAM
    s_Texture->Upload();

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x200;
    IwGxSetViewMatrix(&view);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Destroy texture
    delete s_Texture;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x20;
    s_Angles.z += 0x30;

    // Build model matrix from angles
    CIwMat  rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix = rotX * rotY * rotZ;

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    CIwMaterial* pMat;

    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate and initialise material from the IwGx global cache
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the model matrix
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Set the (modelspace) vertex stream
    IwGxSetVertStreamModelSpace(s_Verts, 8);

    // Set the vertex colour stream
    IwGxSetColStream(s_Cols, 8);

    // Draw the untextured primitives
    IwGxDrawPrims(IW_GX_TRI_STRIP, s_TriStrip, 20);

    // Allocate and initialise another material
    pMat = IW_GX_ALLOC_MATERIAL();

    // Set the diffuse map
    pMat->SetTexture(s_Texture);

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // Set the vertex UV stream
    IwGxSetUVStream(s_UVs);

    // Clear the vertex colour stream
    IwGxSetColStream(NULL);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, s_QuadStrip, 4);

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Billboards Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Billboards Example >

IwGx Billboards Example

The following example draws a cube surrounded on all six sides by viewspace billboards.

The main functions used to achieve this are:

  • CIwMat::SetTrans()
  • CIwMat::LookAt()
  • CIwMat::GetTrans()
  • CIwMat::RotateVec()
  • CIwMat::TransformVec()
  • IwGxSetModelMatrix()
  • IwGxSetNormStream();
  • IwGxSetColStream();
  • IwGxSetVertStream();
  • IwGxDrawPrims();
  • IwGxGetWorldViewMatrix()
  • IwGxSetViewSpaceOrg();
  • IwGxSetVertStreamViewSpace()

The cube coordinates are entered and then drawn in model space.

Each billboard position is gained by transforming the relevant static vector set in the array locations[] using the worldview transform. The billboards are drawn in a for loop, by first setting the origin to be the billboard position using the IwGxSetViewSpaceOrg() function, and then feeding the coordinates into viewspace using the IwGxSetVertStreamViewSpace().

The example uses the following keyboard controls:

Translation Controls

  • s3eKey8: Translates objects along the Z-Axis in a positive direction.
  • s3eKey2: Translates objects along the Z-Axis in a negative direction.
  • s3eKey4: Translates objects along the X-Axis in a positive direction.
  • s3eKey6: Translates objects along the X-Axis in a negative direction.
Rotation Controls
  • s3eKeyLeft: Rotates objects clockwise around the Y-Axis.
  • s3eKeyRight: Rotates objects anti-clockwise around the Y-Axis.
  • s3eKeyUp: Rotates objects clockwise around the X-Axis.
  • s3eKeyDown: Rotates objects anti-clockwise around the X-Axis.

Selecting one of the translation options results in the modification of the translation part of the view matrix. This modification is produced by transforming the relevant axis vector by the rotation part of the view matrix using the RotateVec() function. The resultant value is then multiplied by five and added back into the original translation part of the view matrix. The result is then applied to the view matrix using the SetTrans() function.

Selecting one of the rotation options results in the combination of the matrix rotation and the view matrix using the PreMult() function. Before they are combined, the matrix rotation is first rotated by a 5 degree angle around the relvant axis using the SetAxisAngle() function.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxBillboards
//-----------------------------------------------------------------------------

#include "s3e.h"
#include "IwGx.h"
#include "IwMaterial.h"
#include "IwDebugPrim.h"
#include "IwGxPrint.h"
#include "ExamplesMain.h"

// direction vectors used to navigate in this example.

CIwVec3 up, down, left, right, forward, backward;

// matrices

CIwMat viewMatrix;

// billboard locations

CIwVec3 locations[] = {
    CIwVec3(    0,     0, 0x80),
    CIwVec3(    0,     0,-0x80),
    CIwVec3(-0x80,     0, 0   ),
    CIwVec3( 0x80,     0, 0   ),
    CIwVec3(    0, -0x80, 0   ),
    CIwVec3(    0,  0x80, 0   )
};
int     num_locations = 6;

// material

CIwMaterial* defaultMaterial = NULL;

void CreateButtonsUI(int w, int h)
{
    // Create the UI
    AddButton("In: 8", 0, 70, 70, 30, s3eKey1);
    AddButton("Left: 4", 0, 110, 70, 30, s3eKey2);
    AddButton("Out: 2", w - 70, 70, 70, 30, s3eKey3);
    AddButton("Right: 6", w - 70, 110, 70, 30, s3eKey4);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
// The following function initialises the vectors that will be used in
// translation and rotation of objects.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();

    // Turn all lighting off
    IwGxLightingOff();

    // initialise vectors
    down     =  CIwVec3::g_AxisY;
    up       = -CIwVec3::g_AxisY;
    right    =  CIwVec3::g_AxisX;
    left     = -CIwVec3::g_AxisX;
    forward  =  CIwVec3::g_AxisZ;
    backward = -CIwVec3::g_AxisZ;

    // set view matrix
    viewMatrix.SetTrans(CIwVec3(0, 0, -0x1a0));
    viewMatrix.LookAt(
        viewMatrix.GetTrans(),
        CIwVec3(0, 0, 0),
        up);

    // default material
    defaultMaterial = new CIwMaterial;

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete defaultMaterial;

    // Terminate
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
// The following function observes keyboard state and sets the viewMatrix
// based on user input.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // control camera movement
    //

    // TRANSLATION
    if (CheckButton("In: 8") == S3E_KEY_STATE_DOWN){
        viewMatrix.SetTrans(
            viewMatrix.GetTrans() +
            viewMatrix.RotateVec(forward) * 0x5);
    }

    if (CheckButton("Out: 2") == S3E_KEY_STATE_DOWN){
        viewMatrix.SetTrans(viewMatrix.GetTrans() + viewMatrix.RotateVec(backward) * 0x5);
    }

    if (CheckButton("Left: 4") == S3E_KEY_STATE_DOWN){
        viewMatrix.SetTrans(
            viewMatrix.GetTrans() +
            viewMatrix.RotateVec(left) * 0x5);
    }

    if (CheckButton("Right: 6") == S3E_KEY_STATE_DOWN){
        viewMatrix.SetTrans(
            viewMatrix.GetTrans() -
            viewMatrix.RotateVec(left) * 0x5);
    }

    // ROTATION
    CIwMat rotation;
    if (CheckCursorState() == EXCURSOR_LEFT){
        rotation.SetAxisAngle(up, IW_ANGLE_FROM_DEGREES(5));
        viewMatrix.PreMult(rotation);
    }

    if (CheckCursorState() == EXCURSOR_RIGHT){
        rotation.SetAxisAngle(down, IW_ANGLE_FROM_DEGREES(5));
        viewMatrix.PreMult(rotation);
    }

    if (CheckCursorState() == EXCURSOR_UP){
        rotation.SetAxisAngle(right, IW_ANGLE_FROM_DEGREES(5));
        viewMatrix.PreMult(rotation);
    }

    if (CheckCursorState() == EXCURSOR_DOWN){
        rotation.SetAxisAngle(left, IW_ANGLE_FROM_DEGREES(5));
        viewMatrix.PreMult(rotation);
    }

    // update the view matrix
    IwGxSetViewMatrix(&viewMatrix);

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the cube and the billboards that surround it.
// The billboards are rendered using a for loop, which changes the view space
// origin to be the location of each billboard before they are rendered.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Set default material
    IwGxSetMaterial(defaultMaterial);

    // RENDER THE CUBE
    //
    static CIwSVec3 cubeVertices[] = {
        CIwSVec3(-0x40,-0x40,-0x40),
        CIwSVec3( 0x40,-0x40,-0x40),
        CIwSVec3(-0x40, 0x40,-0x40),
        CIwSVec3( 0x40, 0x40,-0x40),
        CIwSVec3(-0x40,-0x40, 0x40),
        CIwSVec3( 0x40,-0x40, 0x40),
        CIwSVec3(-0x40, 0x40, 0x40),
        CIwSVec3( 0x40, 0x40, 0x40)
    };

    static CIwColour cubeColours[] = {
        {0x00, 0x00, 0xff, 0xff},
        {0xff, 0xff, 0xff, 0xff},
        {0x00, 0xff, 0x00, 0xff},
        {0xff, 0x00, 0x00, 0xff},
        {0xff, 0x00, 0x00, 0xff},
        {0xff, 0xff, 0xff, 0xff},
        {0x00, 0xff, 0x00, 0xff},
        {0x00, 0x00, 0xff, 0xff}
    };

    static uint16 cubeIndices[] = {
        2, 3, 1, 0,
        1, 3, 7, 5,
        7, 6, 4, 5,
        6, 2, 0, 4,
        2, 6, 7, 3,
        1, 5, 4, 0
    };

    // Render the cube in model space.
    IwGxSetModelMatrix(&CIwMat::g_Identity);
    IwGxSetNormStream(NULL, 0);
    IwGxSetColStream(cubeColours, 8);
    IwGxSetVertStream(cubeVertices, 8);
    IwGxDrawPrims(IW_GX_QUAD_LIST, cubeIndices, 24);

    // RENDER THE BILLBOARDS
    //
    static CIwSVec3 billboardVertices[] = {
        CIwSVec3(-0x20, 0x10, 0),
        CIwSVec3( 0x20, 0x10, 0),
        CIwSVec3( 0x20,-0x10, 0),
        CIwSVec3(-0x20,-0x10, 0)
    };

    static CIwSVec3 billboardNormals[] = {
        CIwSVec3(0, 0, -IW_GEOM_ONE),
        CIwSVec3(0, 0, -IW_GEOM_ONE),
        CIwSVec3(0, 0, -IW_GEOM_ONE),
        CIwSVec3(0, 0, -IW_GEOM_ONE)
    };

    static CIwColour billboardColours[] = {
        {0xff, 0xff, 0xff, 0xff},
        {0xff, 0xff, 0xff, 0xff},
        {0xff, 0xff, 0xff, 0xff},
        {0xff, 0x00, 0x00, 0xff}
    };

    static uint16 billboardIndices[] = { 0, 1, 2, 3 };

    for (int i = 0; i < num_locations; i++){
        // get the billboard location in current viewspace
        CIwSVec3 viewSpaceLocation =
            (CIwSVec3)IwGxGetWorldViewMatrix().TransformVec(locations[i]);

        // set the viewspace origin to the billboard's
        // location in viewspace
        IwGxSetViewSpaceOrg(&viewSpaceLocation);

        // render the billboard in viewspace
        IwGxSetVertStreamViewSpace(billboardVertices, 4);
        IwGxSetColStream(billboardColours, 4);
        IwGxSetNormStream(billboardNormals, 4);
        IwGxDrawPrims(IW_GX_QUAD_LIST, billboardIndices, 4);
    }

    // Print all the text to the screen
    IwGxPrintString(2, 60, "Camera translate controls:");
    IwGxPrintString(2, IwGxGetScreenHeight() - 70, "Rotate Camera: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();
    IwGxPrintString(3, IwGxGetScreenHeight () - 80 - 2  * 0xa ,
        "cube in model space,", false);
    IwGxPrintString(4, IwGxGetScreenHeight () - 80 - 0xa, "billboards in viewspace");

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx DebugPrim Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx DebugPrim Example >

IwGx DebugPrim Example

The following example draws cross, sphere, box, axes, and circle debug primitives.

The main functions used to achieve this are:

  • IwGxDebugPrimAxes()
  • IwGxDebugPrimSBBox()
  • IwGxDebugPrimCircle()
  • IwGxDebugPrimCross()
  • IwGxDebugPrimSphere()

The key controls are as follows:

  • s3eKeyUp: Spins the view anti-clockwise on the X-Axis
  • s3eKeyDown: Spins the view clockwise on the X-Axis
  • s3eKeyRight: Spins the view anti-clockwise on the Y-Axis
  • s3eKeyLeft: Spins the view clockwise on the Y-Axis

The following debug primitives are drawn in this example:

  • The first primitive is a bounding box which is created by passing the IwGxDebugPrimSBBox() function a colour value and a CIwSBBox object
  • The second and third primitives are crosses. A cross is created by passing a single point and colour value to the IwGxDebugPrimCross() function. A string is printed next to each cross to indicate the points at which they are placed. The IwGxWorldToScreenXY() function is used to calculate that position and the IwGxPrintString() string is used to print the string at a slight offset from that point.
  • A sphere, which is created by passing the IwGxDebugPrimSphere() function a CIwSphere object. The Sphere object is defined by a point representing its origin and a radius length.
  • The fifth is a set of local axes, in our example this takes the identity matrix as its transform to indicate its origin and a value of 0x20 to indicate the axes indicators' length.
  • The sixth is a circle, which is placed on one face of the bounding box. It is defined by a local transform, radius, local axis normal and colour.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxDebugPrim
//-----------------------------------------------------------------------------

#include "s3e.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwDebugPrim.h"
#include "IwGxTransformSW.h"
#include "ExamplesMain.h"

CIwVec3 s_left, s_up, s_cameraPos;

CIwMat s_viewMatrix;

//-----------------------------------------------------------------------------
// The following function sets the required up, left and camera position
// vectors.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Turn all lighting off
    IwGxLightingOff();

    // Initialise vectors
    s_left      =  CIwVec3::g_AxisX;
    s_up        = -CIwVec3::g_AxisY;
    s_cameraPos =  CIwVec3(0, 0, -0x130);

    // Initialise view matrix
    s_viewMatrix = CIwMat::g_Identity;

    s_viewMatrix.SetTrans(s_cameraPos);
    s_viewMatrix.LookAt(
        s_viewMatrix.GetTrans(),
         CIwVec3::g_Zero,
        -CIwVec3::g_AxisY);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
// The following function observes the keyboard state and changes the values
// governing the view accordingly.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    CIwMat   rotation;
    CIwVec3  lookFrom(0,0,0);
    bool     bUpdateLookAt = false;

    // Up, Down, Left, Right keys
    //

    if ( CheckCursorState() == EXCURSOR_UP )
    {
        rotation.SetAxisAngle(
            s_viewMatrix.RotateVec(s_left),
            IW_ANGLE_FROM_DEGREES(-5));
        lookFrom = (s_viewMatrix * rotation).RotateVec(
            s_cameraPos);
        bUpdateLookAt = true;
    }

    if ( CheckCursorState() == EXCURSOR_DOWN )
    {
        rotation.SetAxisAngle(
            s_viewMatrix.RotateVec(s_left),
            IW_ANGLE_FROM_DEGREES(5));
        lookFrom = (s_viewMatrix * rotation).RotateVec(
            s_cameraPos);
        bUpdateLookAt = true;
    }

    if ( CheckCursorState() == EXCURSOR_RIGHT )
    {
        rotation.SetAxisAngle(
            s_viewMatrix.TransformVec(s_up),
            IW_ANGLE_FROM_DEGREES(5));
        lookFrom = (s_viewMatrix * rotation).RotateVec(
            s_cameraPos);
        bUpdateLookAt = true;
    }

    if ( CheckCursorState() == EXCURSOR_LEFT )
    {
        rotation.SetAxisAngle(
            s_viewMatrix.TransformVec(s_up),
            IW_ANGLE_FROM_DEGREES(-5));
        lookFrom = (s_viewMatrix * rotation).RotateVec(
            s_cameraPos);
        bUpdateLookAt = true;
    }

    // Do this so that we do not
    // lose accuracy when looking at
    // the target
    if (bUpdateLookAt){
        s_viewMatrix.SetTrans(lookFrom);
        s_viewMatrix.LookAt(
            s_viewMatrix.GetTrans(),
             CIwVec3::g_Zero,
            s_viewMatrix.RotateVec(-s_up));
    }

    IwGxSetViewMatrix(&s_viewMatrix);

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders each of the debug primitives. The debug
// primitives drawn are:
// <ul>
//  <li>bounding box
//  <li>crosses
//  <li>sphere
//  <li>set of axes
//  <li>circle
// </ul>
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Allocate a material from the IwGx global cache
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();

    // Set this as the active material
    IwGxSetMaterial(pMat);

    // BOX
    //
    // Draw the box around the origin
    IwGxDebugPrimSBBox(CIwSBBox(CIwSVec3(-0x40,-0x40,-0x40),
                                CIwSVec3(0x40,0x40,0x40)),
                       IwGxGetColFixed(IW_GX_COLOUR_WHITE));

    // CROSSES
    //
    int16 sx, sy;

    // green cross of length 0x4 at (-0x40, -0x40, -0x40)
    IwGxDebugPrimCross(CIwVec3(-0x40,-0x40,-0x40),
        0x4,
        IwGxGetColFixed(IW_GX_COLOUR_GREEN));
    // Label
    IwGxWorldToScreenXY(sx, sy, CIwVec3(-0x40,-0x40,-0x40));
    IwGxPrintString(sx + 1, sy + 1, "`xc0c0c0(-0x40,-0x40,-0x40)", false);

    // green cross of length 0x4 at (0x40, 0x40, 0x40)
    IwGxDebugPrimCross(CIwVec3(0x40,0x40,0x40),
        0x4,
        IwGxGetColFixed(IW_GX_COLOUR_GREEN));
    // Label
    IwGxWorldToScreenXY(sx, sy, CIwVec3(0x40,0x40,0x40));
    IwGxPrintString(sx + 1, sy + 1, "`xc0c0c0(0x40,0x40,0x40)", false);

    // SPHERE
    //
    IwGxDebugPrimSphere(
        CIwSphere(CIwVec3::g_Zero, 0x6E), // sphere around the box
        IwGxGetColFixed(IW_GX_COLOUR_BLUE),
        false);                           // do not draw radial lines

    // AXES
    //

    // Mark the origin using debug axes
    IwGxDebugPrimAxes(CIwMat::g_Identity, // axes at the origin
                      0x20);              // length 0x20
    // Label the origin
    IwGxWorldToScreenXY(sx, sy, CIwVec3::g_Zero);
    IwGxPrintString(sx + 1, sy + 1, "`x5050d0Origin", false);

    // CIRCLE
    //

    CIwMat circleTransform = CIwMat::g_Identity;

    circleTransform.SetTrans(CIwVec3(0, 0, 0x40));
    IwGxDebugPrimCircle(
        circleTransform, // circle's local transformation
        0x20,            // circle's radius
        2,               // z axis is normal to the circle
        IwGxGetColFixed(IW_GX_COLOUR_YELLOW),
        true);           // draw radial lines

    // Paint the cursor keys buttons
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Resource Groups Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Resource Groups Example >

IwGx Resource Groups Example

The following example demonstrates resource loading via GROUP files. The example is identical in appearance to IwGxUVAnimation - the difference being that the texture and material resources are loaded through a GROUP file.

The important functions required to achieve this are:

  • CIwResManager::LoadGroup()
  • CIwResManager::GetGroupNamed()
  • CIwResManager::GetResNamed()

The F6 debug menu now contains a submenu for the resource manager singleton - explore the named group and named resources.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxResourceGroups
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwMenu.h"
#include "IwResHandlerImage.h"
#include "IwResHandlerMTL.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"

// Vertex stream
const int16 s = 0x80;
const int16 p = 0xc0;
CIwSVec3    s_Verts[6] =
{
    CIwSVec3(0, 0, -p),
    CIwSVec3(-s, -s, 0),
    CIwSVec3( s, -s, 0),
    CIwSVec3( s,  s, 0),
    CIwSVec3(-s,  s, 0),
    CIwSVec3(0, 0,  p),
};

// UV stream
CIwSVec2        s_UVs[6] =
{
    CIwSVec2(0 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(1 << 12, 0 << 12),
    CIwSVec2(0 << 12, 0 << 12),
};

// Index streams
uint16      s_TriFan0[6] =
{
    0, 4, 3, 2, 1, 4,
};
uint16      s_TriFan1[6] =
{
    5, 1, 2, 3, 4, 1,
};

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Materials
CIwMaterial* s_MaterialCel;
CIwMaterial* s_MaterialScroll;

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemGx);
    pMenu->AddItem(new CIwMenuItemResManager);
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
// The following function sets the basic display settings and loads the
// required resource groups.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Create the resource manager singleton
    IwResManagerInit();

    // Parse the GROUP file, which will load the textures and materials
    IwGetResManager()->LoadGroup("IwGxResourceGroups.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointers to the material resources
    s_MaterialCel = (CIwMaterial*)pGroup->GetResNamed("cel", IW_GX_RESTYPE_MATERIAL);
    s_MaterialScroll = (CIwMaterial*)pGroup->GetResNamed("scroll", IW_GX_RESTYPE_MATERIAL);

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x200;
    IwGxSetViewMatrix(&view);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetMenuManager();

    // Destroy the resource manager singleton. This destroys all groups.
    IwResManagerTerminate();

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
// The following function updates the model matrix.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.x += 0x10;
    s_Angles.y += 0x24;
    s_Angles.z += 0x38;

    // Build model matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(s_Angles.z);
    s_ModelMatrix.CopyRot(rotX * rotY * rotZ);

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the screenspace cel animation and the scroll
// animation in modelspace.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render screenspace quad with cel animation
    //-------------------------------------------------------------------------
    IwGxSetMaterial(s_MaterialCel);

    static CIwSVec2 xy(0x08, 0x28);
    static CIwSVec2 wh(0x40, 0x40);
    static CIwSVec2 uv(0 << 12, 0 << 12);
    static CIwSVec2 duv(1 << 11, 1 << 11);
    IwGxSetScreenSpaceSlot(-1);
    IwGxDrawRectScreenSpace(&xy, &wh, &uv, &duv);

    //-------------------------------------------------------------------------
    // Render diamond shape with scroll animation
    //-------------------------------------------------------------------------
    IwGxSetMaterial(s_MaterialScroll);

    IwGxSetModelMatrix(&s_ModelMatrix);
    IwGxSetVertStream(s_Verts, 6);
    IwGxSetUVStream(s_UVs);
    IwGxDrawPrims(IW_GX_TRI_FAN, s_TriFan0, 6);
    IwGxDrawPrims(IW_GX_TRI_FAN, s_TriFan1, 6);

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx Alpha Modes Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx Alpha Modes Example >

IwGx Alpha Modes Example

The following example Demonstrates multiple spinning cubes, showing various alpha modes.

The SetAlphaMode() function is used to set the level of transparency applied to each texture.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxAlphaModes
//-----------------------------------------------------------------------------

#include "IwGx.h"
#include "IwMaterial.h"
#include "IwTexture.h"

#include "ExamplesMain.h"

// Texture object
CIwTexture* s_Texture = NULL;

// Vertex data
const int16 s = 0x80;
CIwSVec3    s_Verts[16] =
{
    CIwSVec3(-s, -s, -s),
    CIwSVec3( s, -s, -s),
    CIwSVec3( s,  s, -s),
    CIwSVec3(-s,  s, -s),

    CIwSVec3( s, -s, -s),
    CIwSVec3( s, -s,  s),
    CIwSVec3( s,  s,  s),
    CIwSVec3( s,  s, -s),

    CIwSVec3( s, -s,  s),
    CIwSVec3(-s, -s,  s),
    CIwSVec3(-s,  s,  s),
    CIwSVec3( s,  s,  s),

    CIwSVec3(-s, -s,  s),
    CIwSVec3(-s, -s, -s),
    CIwSVec3(-s,  s, -s),
    CIwSVec3(-s,  s,  s),
};

// UV data
CIwSVec2        s_UVs[16] =
{
    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),

    CIwSVec2(0,             0),
    CIwSVec2(IW_GEOM_ONE,   0),
    CIwSVec2(IW_GEOM_ONE,   IW_GEOM_ONE),
    CIwSVec2(0,             IW_GEOM_ONE),
};

// Index stream for textured material
uint16      s_QuadList[16] =
{
    0, 3, 2, 1,
    4, 7, 6, 5,
    8, 11, 10, 9,
    12, 15, 14, 13,
};

// Angles
CIwSVec3     s_Angles;

// Local matrix
CIwMat       s_ModelMatrix;

// Materials
CIwMaterial *s_MaterialBG;
CIwMaterial *s_MaterialCubes[4];

//-----------------------------------------------------------------------------
// The following function loads a texture from file and applies it to each of
// the rendered cubes. The important difference between each cube is the alpha
// mode. The SetAlphaMode() function is used to set the level of transparency
// applied to each texture.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Enable emissive lighting only
    IwGxLightingEmissive(true);
    IwGxLightingAmbient(false);
    IwGxLightingDiffuse(false);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x1000, 0x10);

    // Create empty texture object
    s_Texture = new CIwTexture;

    // Load image data from disk into texture
    s_Texture->LoadFromFile("./textures/testTexture_8bit.bmp");

    // "Upload" texture to VRAM
    s_Texture->Upload();

    // Initialise angles
    s_Angles = CIwSVec3::g_Zero;

    // Set the view matrix along the -ve z axis
    CIwMat view = CIwMat::g_Identity;
    view.t.z = -0x400;
    IwGxSetViewMatrix(&view);

    s_MaterialBG = new CIwMaterial;

    // Initialise materials
    s_MaterialCubes[0] = new CIwMaterial;
    s_MaterialCubes[0]->SetTexture(s_Texture);
    s_MaterialCubes[0]->SetAlphaMode(CIwMaterial::NONE);
    s_MaterialCubes[0]->SetColEmissive(0x808080);

    s_MaterialCubes[1] = new CIwMaterial;
    s_MaterialCubes[1]->SetTexture(s_Texture);
    s_MaterialCubes[1]->SetAlphaMode(CIwMaterial::ADD);
    s_MaterialCubes[1]->SetColEmissive(0x808080);

    s_MaterialCubes[2] = new CIwMaterial;
    s_MaterialCubes[2]->SetTexture(s_Texture);
    s_MaterialCubes[2]->SetAlphaMode(CIwMaterial::SUB);
    s_MaterialCubes[2]->SetColEmissive(0x808080);

    s_MaterialCubes[3] = new CIwMaterial;
    s_MaterialCubes[3]->SetTexture(s_Texture);
    s_MaterialCubes[3]->SetAlphaMode(CIwMaterial::HALF);
    s_MaterialCubes[3]->SetColEmissive(0x808080);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Destroy texture
    delete s_Texture;

    // Destroy materials
    delete s_MaterialCubes[0];
    delete s_MaterialCubes[1];
    delete s_MaterialCubes[2];
    delete s_MaterialCubes[3];
    delete s_MaterialBG;

    // Terminate
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles
    s_Angles.y += 0x40;

    // Build model matrix from angles
    s_ModelMatrix.SetRotY(s_Angles.y);
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //-------------------------------------------------------------------------
    // Render background
    //-------------------------------------------------------------------------
    // Set active material
    IwGxSetMaterial(s_MaterialBG);

    // Set colour stream
    static CIwColour bgCols[4] =
    {
        {0xff, 0x00, 0x00, 0xff},
        {0x00, 0xff, 0x00, 0xff},
        {0x00, 0x00, 0xff, 0xff},
        {0x00, 0xff, 0xff, 0xff},
    };
    IwGxSetColStream(bgCols, 4);

    // Set the (screenspace) vertex stream
    CIwSVec2* pCoords = AllocClientScreenRectangle();
    IwGxSetScreenSpaceOrg(&CIwSVec2::g_Zero);
    IwGxSetScreenSpaceSlot(-3);
    IwGxSetVertStreamScreenSpace(pCoords, 4);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);

    //-------------------------------------------------------------------------
    // Render cubes
    //-------------------------------------------------------------------------
    // Set UV stream
    IwGxSetUVStream(s_UVs);

    // Clear colour stream
    IwGxSetColStream(NULL);

    // Display 4 cubes
    for (uint32 y = 0; y < 2; y++)
    {
        for (uint32 x = 0; x < 2; x++)
        {
            s_ModelMatrix.t.x = -0x100 + (int32)(x * 0x200);
            s_ModelMatrix.t.y = -0x0c0 + (int32)(y * 0x200);

            // Set the model matrix
            IwGxSetModelMatrix(&s_ModelMatrix);

            // Set the (modelspace) vertex stream
            IwGxSetVertStreamModelSpace(s_Verts, 16);

            // Set active material
            IwGxSetMaterial(s_MaterialCubes[y * 2 + x]);

            // Draw the cube quad list
            IwGxDrawPrims(IW_GX_QUAD_LIST, s_QuadList, 16);
        }
    }

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGx UV Animation Example

Airplay API Reference > IwGx API Documentation > IwGx Examples > IwGx UV Animation Example >

IwGx UV Animation Example

The following example demonstrates how to create UV animation. The example illustrates two different types of animation, scroll and cel.

The main classes used to achieve this are:

  • CIwSVec2

  • CIwTexture

  • CIwMaterial

The main functions used to achieve this are:

  • CIwMaterial::SetName()
  • CIwTexture::LoadFromFile()
  • CIwTexture::Upload()
  • CIwMaterial::SetTexture()
  • CIwMaterial::CreateAnim()
  • CIwMaterial::SetAnimCelW()
  • CIwMaterial::SetAnimCelH()
  • CIwMaterial::SetAnimCelPeriod()
  • IwGxSetMaterial()
  • IwGxSetUVStream()
  • IwGxSetColStream()
  • IwGxDrawPrims()

This example first sets the vertices for the screenspace quad in which the animations will be played. It then sets the UVs, indicating the point at which the animation should start from. The cel UVs set the the starting point of the animation to be the first 1/16 (the 1/4 of the width and 1/4 of the height) of the texture at any one time. The scroll UVs will allow the animation to display 1/256 of the animation at any one time.

A material and texture is object is instantiated for each animation. A texture is then uploaded and set on the material using the LoadFromFile(), Upload() and SetTexture() functions.

Based on the Keyboard state only one animation is played, pressing 1 starts the scroll animation and pressing 2 returns to the cel animation.

The cel animation uses the CreateAnim() to create the animation. The SetAnimCelW() function sets the width of the cels, SetAnimCelH() sets the height of the cels and SetAnimCelPeriod() sets the amount of updates that must occur before the next cel is displayed.

The IwGxSetMaterial() function is used to set the appropriate material based on the keyboard input. The UVs for each animation are then set using the IwGxSetUVStream() function.

Note:
For more information on creating UV animation, see the Material UV Animation section in the IwGx API Documentation.
The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGxUVAnimation
//-----------------------------------------------------------------------------
#include "s3e.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwMaterial.h"
#include "IwMenu.h"
#include "IwTexture.h"
#include "ExamplesMain.h"

bool animSwitch;

// Texture objects
CIwTexture* s_Textures[2];

//Vertex data
CIwSVec2 anim_xy[4];

// UV data
CIwSVec2    cel_UVs[4];
CIwSVec2    scroll_UVs[4];

// Materials
CIwMaterial* s_MaterialCel;
CIwMaterial* s_MaterialScroll;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    // Print the program instruction.
    AddButton("Select scroll animation: 1", 2, h - 60, w, 20, s3eKey1);
    AddButton("Select cell animation: 2",  2, h - 30, w, 20, s3eKey2);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();

    animSwitch = false;

    int16 offset = 32;

    int16 midx = (int16)IwGxGetScreenWidth()/2;
    int16 midy = (int16)IwGxGetScreenHeight()/2;

// Vertex stream
// Set up screenspace vertex coords

    //cel animation screen coordinates
    int16 animXLeft = midx - offset;
    int16 animXRight = midx + offset;
    int16 animYTop = midy - offset;
    int16 animYBottom = midy + offset;

    anim_xy[0] = CIwSVec2(animXLeft, animYTop);
    anim_xy[2] = CIwSVec2(animXRight, animYTop);
    anim_xy[3] = CIwSVec2(animXRight, animYBottom);
    anim_xy[1] = CIwSVec2(animXLeft, animYBottom);

    //Set up the UVs for cel animation
    cel_UVs[0] = CIwSVec2(0 << 12, 0 << 12);
    cel_UVs[2] = CIwSVec2(1 << 10, 0 << 12);
    cel_UVs[3] = CIwSVec2(1 << 10, 1 << 10);
    cel_UVs[1] = CIwSVec2(0 << 12, 1 << 10);

    //Set up the UVs for scroll animation
    scroll_UVs[0] = CIwSVec2(0 << 12, 0 << 12);
    scroll_UVs[2] = CIwSVec2(1 << 4, 0 << 12);
    scroll_UVs[3] = CIwSVec2(1 << 4, 1 << 12);
    scroll_UVs[1] = CIwSVec2(0 << 12, 1 << 12);

    // Initialise material to use UV animation for "cel" animation
    s_MaterialCel = new CIwMaterial;
    s_MaterialCel->SetName("Cel");
    s_Textures[0] = new CIwTexture;
    s_Textures[0]->LoadFromFile("./textures/numbers.bmp");
    s_Textures[0]->Upload();
    s_MaterialCel->SetTexture(s_Textures[0]);
    s_MaterialCel->CreateAnim();
    s_MaterialCel->SetAnimCelW(0x20);
    s_MaterialCel->SetAnimCelH(0x20);
    s_MaterialCel->SetAnimCelPeriod(10);

    // Initialise material to use UV animation for "scrolling"
    s_MaterialScroll = new CIwMaterial;
    s_MaterialScroll->SetName("Scroll");
    s_Textures[1] = new CIwTexture;
    s_Textures[1]->LoadFromFile("./textures/glow.bmp");
    s_Textures[1]->Upload();
    s_MaterialScroll->SetTexture(s_Textures[1]);
    s_MaterialScroll->CreateAnim();

    // Note that this is equivalent to SetAnimCelW(0x1) - but the concept of a U or V offset makes more
    // sense when defining a scrolling animation
    s_MaterialScroll->SetAnimOfsU(0x1);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_Textures[0];
    delete s_Textures[1];
    delete s_MaterialCel;
    delete s_MaterialScroll;

    // Terminate
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Press 1 to play the scroll animation and 2 to reinstate the cel animation.
    if(CheckButton("Select scroll animation: 1") & S3E_KEY_STATE_PRESSED)
    {
            animSwitch = true;
    }
    else if (CheckButton("Select cell animation: 2") & S3E_KEY_STATE_PRESSED)
    {
            animSwitch = false;
    }

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render screenspace quad with cel animation
    //-------------------------------------------------------------------------
    if(animSwitch == false)
    {
        IwGxSetMaterial(s_MaterialCel);

        // Set the vertex UV stream
        IwGxSetUVStream(cel_UVs);
    }

    //-------------------------------------------------------------------------
    // Render screenspace quad with scroll animation
    //-------------------------------------------------------------------------
    if(animSwitch == true)
    {
        IwGxSetMaterial(s_MaterialScroll);

        // Set the vertex UV stream
        IwGxSetUVStream(scroll_UVs);
    }

    // Clear the vertex colour stream
    IwGxSetColStream(NULL);

    // Set Vertex Stream
    IwGxSetVertStreamScreenSpace(anim_xy, 4);

    // Draw the textured primitives
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: Iw2D API Documentation

Airplay API Reference > Iw2D API Documentation >

Iw2D API Documentation

The Iw2D documentation contains the following sections:

  • Iw2D API Overview
  • Iw2D API Reference
  • Iw2D Examples


Airplay API Reference: Iw2D API Overview

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview >

Iw2D API Overview

Iw2D provides a simple 2D drawing layer. Iw2D is a compact and familiar drawing API for rapid development of simple 2D applications.

To use Iw2D functionality, you must include "Iw2D.h" in your source and iw2d as a subproject in your project's MKB file:

  • subprojects
  • {
    • iw2d
  • }

Before any Iw2D function is called the module must first be initialised using Iw2DInit(). At the end of the program Iw2DTerminate() should be called to shutdown the module correctly.

Iw2DSurfaceShow() should be called instead of s3eSurfaceShow() (or IwGxSwapBuffers)

When using Iw2D, the following modules do not need to be specified in your project's MKB as they will be implicitly included as subprojects of this module:

  • IwUtil
  • IwGeom
  • IwResManager
  • IwGx
  • IwGxFont

Iw2D is build on top of IwGx so it supports all the usual software and hardware rendering features.

However, Airplay Studio also provides a lite version of Iw2D for extremely small target devices. Iw2D lite only supports a subset of the full Iw2D functionality, but has considerably less memory overhead.

The following topics are covered in this section:

  • Iw2D Context
  • Drawing Primitives
  • Drawing Images
  • Drawing Text
  • Using Surfaces
  • Iw2D Transform Pipeline
  • Mixing Iw2D With Other Rendering
  • Using Iw2D Lite version


Airplay API Reference: Iw2D Context

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Iw2D Context >

Iw2D Context

Iw2D uses a global context to control parameters that are unlikely to change per function call, like colour, alpha mode and transform.

On initialisation the global context will be in its default state.

Each global parameter has an associated getter and setter.

For example, to change the current drawing colour:

  • Iw2DSetColour(0xff0000ff); //set colour to red
  • Iw2DGetColour(); //now returns red

See Iw2D Drawing Context for a complete list of context functions.


Airplay API Reference: Drawing Images

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Drawing Images >

Drawing Images

Preparing a bitmap for drawing

Before Iw2D can use an image for drawing it must be conditioned by creating a CIw2DImage handle for it. CIw2DImage abstracts certain complexities of the underlying renderer.

For example, to create an image from "image.bmp":

  • CIw2DImage* img = Iw2DCreateImage("image.bmp");

You can create an image from a number of sources:

  • From an image file (see Image Manipulation for the list of supported formats)
  • From a CIwImage object
  • From a CIwTexture object held in the resource system (see below)
  • From a CIw2DSurface

A CIw2DImage should be deleted when you are finished with it.

Drawing with an image

Iw2D provides functions for drawing images (Iw2DDrawImage) and sub-images (Iw2DDrawImageRegion) at 1:1 scale or arbitrary scale.

To draw the image at 1:1 scale at (10, 10).

  • Iw2DDrawImage(img, CIwSVec2(10,10));

Iw2DSetImageTransform can be used to apply a number of simple transformations in place to image rendering.

To draw the image at the same location, but flipped:

  • Iw2DSetImageTransform(IW_2D_IMAGE_TRANSFORM_FLIP_X);
  • Iw2DDrawImage(img, CIwSVec2(10,10));

Iw2DImageTransformOp can also be used to perform an image transformation on an arbitrary transformed image.

Using images from IwResManager

For maximum efficiency it is recommended that image (CIwTexture) resources from IwResManager image are used. These can be binarised in prepared format, saving conversion time as the CIw2DImage is created.

See IwResManager for more details of the resource system.

See Iw2D Images for full details of the Iw2D image API.


Airplay API Reference: Drawing Primitives

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Drawing Primitives >

Drawing Primitives

Iw2D supports a number of primitives which can be rendered without any loaded resources. Primitives can be drawn as outlines or as solid shapes.

Primitives will respect the current Iw2D context - drawing with the current colour and the current alpha mode.

For example:

  • Iw2DSetColour(0xffff0000); // Set blue
  • Iw2DFillRect(CIwSVec2(0, 0), CIwSVec2(10,10)); // Fill blue
  • Iw2DSetColour(0xff0000ff); // Set red
  • Iw2DDrawRect(CIwSVec2(0, 0), CIwSVec2(10,10)); // Draw red outline

There are four supported primitives: Lines, Rectangles, Arcs and Polygons. The latter three support filled and outline versions. Filled versions include the same pixels as the outline versions.

See Iw2D Basic Primitives for full details.


Airplay API Reference: Drawing Text

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Drawing Text >

Drawing Text

Creating a font

Iw2D uses the same resources as IwGxFont. See the IwGxFont documentation for details of how to create a font and load it into IwResManager.

Like images, fonts must be turned into an Iw2D-specific object (a CIw2DFont) before use. This is done using Iw2DCreateFontResource(). These objects should be deleted when they are no longer needed.

  • CIw2DFont* font = Iw2DCreateFontResource("myfont");

Drawing Text Strings

Unlike images, the font to use for a string is a global context parameter. Use Iw2DSetFont to set the current font.

Iw2DDrawString() is used to render the string. A UTF-8 string or UCS-2 (2 byte unicode) string can be used.

Iw2DDrawString always draws into a rectangular region and will handle wrapping and alignment of text within that region.

For example, To render a string of text centred in a (100, 100) rectangle at (10, 10):

  • Iw2DSetFont(font);
  • Iw2DDrawString("UTF8 encoded text", CIwSVec2(10,10), CIwSVec2(100,100), IW_2D_FONT_ALIGN_CENTRE, IW_2D_FONT_ALIGN_CENTRE);

Font Properties

Fonts are considered to have a single height (all characters are notionally the height). This can be retrieved from the Iw2DFont object.

Iw2DGetStringWidth can be used to determine how wide a given string would be if drawn on a single line in the current font.

See Iw2D Fonts for full details.


Airplay API Reference: Using Surfaces

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Using Surfaces >

Using Surfaces

Iw2D supports surfaces for offscreen rendering. Note that support for surfaces may be very slow or severly restricted on some gl platforms. While these differences are abstracted by the framework it is recommended that surfaces are used sparingly, and not for real-time effects unless you are targetting devices that surfaces are fully supported on.

A 2D surface should be created using Iw2DCreateSurface. To create a surface with dimensions (128, 100):

  • CIw2DSurface* surface = Iw2DCreateSurface(128, 100);

This surface can then be set as the current drawing surface using Iw2DSetSurface. To switch back to the default surface (the screen) pass NULL to this function.

  • Iw2DSetSurface(surface);
  • //...Draw to surface using Iw2D api...
  • Iw2DSetSurface(NULL);

To draw the contents of a surface you need to make a CIw2DImage that represents it. This is done using Iw2DCreateImage with the surface as an argument. Note that typically the image will share the storage of the surface, so any changes to the surface will automatically appear in the image.

All the usual image drawing features can be used with a surface image.

Both the image and the surface should be deleted when finished with.

In standard Iw2D surfaces are implemented using IwGxSurface, so IwGx rendering will also go to the active Iw2D surface. In Iw2D_lite a surface is just a block of memory - the surface descriptor can be retrieved using Iw2DGetSurfaceInfo.


Airplay API Reference: Iw2D Transform Pipeline

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Iw2D Transform Pipeline >

Iw2D Transform Pipeline

By default, Iw2D drawing happens in normal 1:1 pixel space with the origin at the top left. For example an image drawn at (10, 10) will be 10 pixels across and 10 pixels down.

Iw2D provides two steps to transform the input positions, a transform matrix and a post-transform callback function. The two can be mixed freely (the function will act on the output of the matrix transformation).

Transform Matrix

Iw2D supports a 2D matrix transformation. This can be used as a simple offset, a rotation, a scale or a combination of all three. For example, to draw all subsequent objects rotated 45 degrees around (20, 20) you would first create a CIwMat2D that contains this transformation, and set the global context to use that matrix:

  • CIwMat2D rot;
  • rot.SetRot(IW_GEOM_ONE/8, CIwVec2(20, 20));
  • Iw2DSetTransformMatrix(rot);

The matrix should be set back to identity (the default) to return to untransformed rendering:

  • Iw2DSetTransformMatrix(CIwMat2D::g_Identity);

Post Transform Function

The most powerful transform option provided by Iw2D is the post-transform callback function. This can be used to apply non-linear transformation and arbitrary colouring to any Iw2D rendering. Iw2DSetPostTransformFn is used to set the current post-transformation (use NULL to disable any post-transform). By default, no post-transform is applied.

A simple transform function would look like this:

  • void MoveRight(CIwSVec2* v, CIwColour* c, int32 numberPoints)
  • {
  • while(numberPoints--)
  • {
  • v->x += 10 << 3;
  • v++;
  • }
  • }

This function moves all points 10 pixels to the right by modifying the v array in place.

Note that the 10 pixels must be shifted up into subpixel space because the vectors passed into this function are in subpixels, that is an 8x version of the screen. This allows for more precision in animations.

When transforming colours in this way you should note that the colour in the global context controls the modulation requirements for the objects being drawn. This detail is an optimisation usually abstracted by Iw2D.

3 levels of modulations are used internally, in reverse order of expense: no modulation (straight copy), R modulation (simple greyscale modulation based on R channel) and RGB modulation (full modulate by all channels).

For example if the global colour is set to full-white (0xffffffff) no modulation of any kind is usually required, so modulation will be turned off for maximum efficiency. If you then set a callback that pushes red (0xff0000ff) into all the colours you would not see the red modulation because the Iw2D framework would still be set to do no modulation. To see the red you would need to set the global context colour to be a non-greyscale colour (since this would enable RGB modulation).

While post-transform functions can simulate many 3D effects you should consider using iwgx directly if you want to do true 3D. For example, Iw2D drawing cannot do perspective correction on distorted images because there is no z coordinate.


Airplay API Reference: Mixing Iw2D With Other Rendering

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Mixing Iw2D With Other Rendering >

Mixing Iw2D With Other Rendering

Iw2D can be freely mixed with other rendering frameworks.

Iw2D drawing may be postponed until Iw2DSurfaceShow() (or Iw2DSetSurface). To guarantee order with other rendering systems use Iw2DFinishDrawing() to ensure that drawing has actually finished.

If Iw2DSurfaceShow() is not called, then Iw2DFinishDrawing() must be.

CIwTexture resources that have been wrapped into CIw2DImages using Iw2DCreateImageResource may not behave correctly if used in iwgx simultaneously.

Note that iw2d_lite cannot be mixed with iwgx.


Airplay API Reference: Using Iw2D Lite Version

Airplay API Reference > Iw2D API Documentation > Iw2D API Overview > Using Iw2D Lite Version >

Using Iw2D Lite Version

Functionality

Iw2D Lite has a smaller memory footprint at the expense of some features:

  • Alpha mode is ignored for primitives.
  • The non-translation part of the transform matrix is ignored, meaning arbitrary rotation/scaling cannot be used (The image transformation is still available).
  • Post-transformation callbacks are ignored.
  • No HW acceleration support.
  • Performance will be lower, particularly for modulated image drawing.

Linking Iw2D Lite Version

To use Iw2D Lite, the application should specify subproject 'iw2d_lite'. This cannot be used with iwgx, iwgxfont or iw2d.

Using IwResManager with Iw2D Lite

Iw2D Lite can still be used with IwResManager for managing and building binary resources. Regular resource binaries are compatible with Iw2D Lite, except only CIwGxFont and CIwTexture resource types can be included from the normal Airplay Studio set.

Differences Between Debug and Release builds

To provide resource building functionality Iw2D Lite must initialise IwGx and IwResManager. This means that the default win32 debug version of the application will behave somewhat differently to the default release build.

Disabling resource building using the [ResManager] ResBuild icf setting will make the debug build comparable to the release build.


Airplay API Reference: Iw2D API Reference

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference >

Iw2D API Reference

Modules

Drawing Context
Basic Primitives
Images
Fonts
Miscellaneous Functions

Data Structures

class | CIw2DFont
class | CIw2DImage
class | CIw2DSurface


Airplay API Reference: Drawing Context

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference > Drawing Context >

Drawing Context
[Iw2D API Reference]

Typedefs

typedef void(* | CIw2DPostTransformFn )(CIwSVec2 *pPoints, CIwColour *pCols, int32 numberPoints)

Functions

CIw2DAlphaMode Iw2DGetAlphaMode ()
CIwColour Iw2DGetColour ()
CIw2DFont * Iw2DGetFont ()
CIw2DImageTransform Iw2DGetImageTransform ()
CIw2DPostTransformFn Iw2DGetPostTransformFn ()
CIw2DSurface * Iw2DGetSurface ()
CIwMat2D Iw2DGetTransformMatrix ()
CIw2DImageTransform | Iw2DImageTransformOp (CIw2DImageTransform state, CIw2DImageTransform operation)
void | Iw2DSetAlphaMode (CIw2DAlphaMode mode)
void | Iw2DSetColour (uint32 colour)
void | Iw2DSetColour (CIwColour colour)
void | Iw2DSetFont (CIw2DFont *font)
void | Iw2DSetImageTransform (CIw2DImageTransform trans)
void | Iw2DSetPostTransformFn (CIw2DPostTransformFn fn)
void | Iw2DSetSurface (CIw2DSurface *surface)
void | Iw2DSetTransformMatrix (const CIwMat2D &matrix)

Detailed Description

The drawing context affects subsequent drawing operations. For example, once the 2D colour has been set, it will affect all primitive, image and font rendering. Not all context parameters affect all drawing operations, for example the Iw2DImageTransform will only affect images.

Typedef Documentation

typedef void(* CIw2DPostTransformFn)(CIwSVec2 *pPoints, CIwColour *pCols, int32 numberPoints)

A post-transformation callback. This callback can modify the colours and points passed in to do special effects like distortion and lighting.

Note:
Iw2D will not typically do more modulation work than required, but will not parse the contents of pCols after this function returns. For this reason, if you require full RGB modulation you should set a drawing colour with non-matching RGB values.

This functionality is not available in iw2d_lite.

Parameters:
pPoints | a pointer to a list of transformed points. Note that the points will be in sub-pixels (8*normal resolution).
pCols | a pointer to a list of colours.
numberPoints | the number of points/colours passed into the function.
Required Header Files
Iw2D.h

Enumeration Type Documentation

enum CIw2DAlphaMode

Enumerator:
IW_2D_ALPHA_NONE | Normal alpha (blend alpha channel if present in image).
IW_2D_ALPHA_HALF | Composite 50:50 with current target.
IW_2D_ALPHA_ADD | Straight additive with current target.
IW_2D_ALPHA_SUB | Straight subtractive with current target.

enum CIw2DImageTransform

Enumerator:
IW_2D_IMAGE_TRANSFORM_NONE | No transformation.
IW_2D_IMAGE_TRANSFORM_ROT90 | Rotate 90 degrees clockwise.
IW_2D_IMAGE_TRANSFORM_ROT180 | Rotate 180 degrees.
IW_2D_IMAGE_TRANSFORM_ROT270 | Rotate 270 degrees clockwise.
IW_2D_IMAGE_TRANSFORM_FLIP_X | Flip horizontally.
IW_2D_IMAGE_TRANSFORM_FLIP_Y | Flip vertically.

Function Documentation

CIw2DAlphaMode Iw2DGetAlphaMode ( )

Get the alpha mode for subsequent drawing operations.

Returns:
mode The alpha mode for subsequent drawing
Required Header Files
Iw2D.h

CIwColour Iw2DGetColour ( )

Get the current colour for drawing operations.

Returns:
The current colour for drawing operations.
Required Header Files
Iw2D.h

CIw2DFont* Iw2DGetFont ( )

Get the font for subsequent string drawing operations.

Returns:
The font to use for string drawing
See also:
Iw2DGetImageTransform
Required Header Files
Iw2D.h

CIw2DImageTransform Iw2DGetImageTransform ( )

Get the current transformation for image drawing operations.

Returns:
a member of CIw2DImageTransform that applies to current image drawing
See also:
Iw2DSetImageTransform
Required Header Files
Iw2D.h

CIw2DPostTransformFn Iw2DGetPostTransformFn ( )

Get the current post-transformation callback function

Note:
This functionality is not available in iw2d_lite.
Returns:
The current post-transformation callback function
Required Header Files
Iw2D.h

CIw2DSurface* Iw2DGetSurface ( )

Get the destination surface for subsequent drawing operations.

Returns:
surface The current surface to draw to (NULL for the default screen surface).
Required Header Files
Iw2D.h

CIwMat2D Iw2DGetTransformMatrix ( )

Get a 2D transform currently used for drawing operations.

Returns:
The 2D transform for all subsequent drawing operations.
Note:
This functionality is not available in iw2d_lite.
Required Header Files
Iw2D.h

CIw2DImageTransform Iw2DImageTransformOp | ( | CIw2DImageTransform | state,
 |  | CIw2DImageTransform | operation
 | ) |  |

Perform an image transformation on an arbitrary transformed image. Consecutive operations can be performed on the transform alone to yield some final desired transform.

Parameters:
state | a member of CIw2DImageTransform representing the current transformed state of an image
op | a member of CIw2DImageTransform to apply to the state in the first parameter
Returns:
a member of CIw2DImageTransform that represents the operation on the first parameter.
See also:
Iw2DGetImageTransform
Required Header Files
Iw2D.h

void Iw2DSetAlphaMode ( CIw2DAlphaMode mode )

Set the alpha mode for subsequent drawing operations. Default is IW_2D_ALPHA_NONE.

Note:
non-full alpha in the colour will activate normal opacity blending automatically.
Parameters:
mode The alpha mode for subsequent drawing
Required Header Files
Iw2D.h

void Iw2DSetColour ( uint32 colour )

Set the colour for subsequent drawing operations. Default is white.

Parameters:
colour The colour for subsequent drawing operations. This 32 bit number is in ABGR_8888 format, i.e. 0xff000000 is black with full alpha
See also:
Iw2DGetColour, Iw2DSetModulateMode
Required Header Files
Iw2D.h

void Iw2DSetColour ( CIwColour colour )

Set the colour for subsequent drawing operations. Default is white.

Parameters:
colour The colour for subsequent drawing operations
See also:
Iw2DGetColour, Iw2DSetModulateMode
Required Header Files
Iw2D.h

void Iw2DSetFont ( CIw2DFont * font )

Set the font for subsequent string drawing operations. Default is NULL (i.e. a font must be set prior to any string drawing).

Parameters:
font The font to use for string drawing
See also:
Iw2DGetImageTransform
Required Header Files
Iw2D.h

void Iw2DSetImageTransform ( CIw2DImageTransform trans )

Set the transformation for subsequent image drawing operations. Default is IW_2D_IMAGE_TRANSFORM_NONE.

Parameters:
trans a member of CIw2DImageTransform to apply to subsequent images
See also:
Iw2DGetImageTransform
Required Header Files
Iw2D.h

void Iw2DSetPostTransformFn ( CIw2DPostTransformFn fn )

Set a callback function to transform position/colour dynamically. Default is NULL (i.e. no post-transformation callback). The post-transformation acts on position/colours output by iw2D before they are rendered, and can be used for lighting/distortion effects.

Note:
This functionality is not available in iw2d_lite.
Parameters:
fn The post-transformation for all subsequent drawing operations.
Required Header Files
Iw2D.h

void Iw2DSetSurface ( CIw2DSurface * surface )

Set the destination surface for subsequent drawing operations. Pass NULL for the default screen surface. Default is NULL. It is not permitted to render from a surface to itself.

Parameters:
surface The surface to draw to.
Required Header Files
Iw2D.h

void Iw2DSetTransformMatrix ( const CIwMat2D & matrix )

Set a 2D transform to apply to all subsequent drawing operations. Default is CIwMat2D::g_Identity (i.e. no transformation).

Note:
This functionality is not available in iw2d_lite.
Parameters:
matrix The 2D transform for all subsequent drawing operations.
Required Header Files
Iw2D.h


Airplay API Reference: Basic Primitives

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference > Basic Primitives >

Basic Primitives
[Iw2D API Reference]

Functions

void | Iw2DDrawArc (CIwSVec2 centre, CIwSVec2 size, iwangle start, iwangle end, int32 numberSegments=0)
void | Iw2DDrawLine (CIwSVec2 start, CIwSVec2 end)
void | Iw2DDrawPolygon (CIwSVec2 *verts, int32 numberVerts, bool closed)
void | Iw2DDrawRect (CIwSVec2 topLeft, CIwSVec2 size)
void | Iw2DFillArc (CIwSVec2 centre, CIwSVec2 size, iwangle start, iwangle end, int32 numberSegments=0)
void | Iw2DFillPolygon (CIwSVec2 *verts, int32 numberVerts)
void | Iw2DFillRect (CIwSVec2 topLeft, CIwSVec2 size)

Detailed Description

These primitives do not require any loaded assets. Primitives are rendered to the current surface (usually the screen). They will be flat coloured with the current colour.

Function Documentation

void Iw2DDrawArc | ( | CIwSVec2 | centre,
 |  | CIwSVec2 | size,
 |  | iwangle | start,
 |  | iwangle | end,
 |  | int32 | numberSegments = 0
 | ) |  |

Draw a fraction of an arc flat-coloured with the current colour. An arc is rendered as a series of line segments.

Parameters:
centre | The centre of the arc
size | The horizontal/vertical radii of the arc
start | The beginning of the arc (clockwise from directly up)
end | The end of the arc (clockwise from directly up)
numberSegments | The number of lines to draw the arc with. By default a reasonable resolution will be chosen.
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DDrawLine | ( | CIwSVec2 | start,
 |  | CIwSVec2 | end
 | ) |  |

Draw a single line flat-coloured with the current colour.

Parameters:
start | The start of the line
end | The end of the line
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DDrawPolygon | ( | CIwSVec2 * | verts,
 |  | int32 | numberVerts,
 |  | bool | closed
 | ) |  |

Draw an arbitary polygon outline flat-coloured with the current colour.

Parameters:
verts | a pointer to a list of vertices
numberVerts | the number of vertices in the list
closed | whether a line is drawn from the final vertex to the first vertex.
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DDrawRect | ( | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size
 | ) |  |

Draw a rectangle outline flat-coloured with the current colour.

Parameters:
topLeft | The top left of the rectangle
size | The size of the rectangle
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DFillArc | ( | CIwSVec2 | centre,
 |  | CIwSVec2 | size,
 |  | iwangle | start,
 |  | iwangle | end,
 |  | int32 | numberSegments = 0
 | ) |  |

Draw a solid pie-segment flat-coloured with the current colour.

Parameters:
centre | The centre of the arc
size | The horizontal/vertical radii of the arc
start | The beginning of the arc (clockwise from directly up)
end | The end of the arc (clockwise from directly up)
numberSegments | The number of lines to draw the arc with. By default a reasonable resolution will be chosen.
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DFillPolygon | ( | CIwSVec2 * | verts,
 |  | int32 | numberVerts
 | ) |  |

Draw an arbitary solid polygon flat-coloured with the current colour.

Parameters:
verts | a pointer to a list of vertices
numberVerts | the number of vertices in the list
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DFillRect | ( | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size
 | ) |  |

Draw a solid rectangle flat-coloured with the current colour.

Parameters:
topLeft | The top left of the rectangle
size | The size of the rectangle
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h


Airplay API Reference: Images

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference > Images >

Images
[Iw2D API Reference]

Functions

CIw2DImage * | Iw2DCreateImage (CIw2DSurface *surface)
CIw2DImage * | Iw2DCreateImage (CIwImage &image)
CIw2DImage * | Iw2DCreateImage (const char *filename)
CIw2DImage * | Iw2DCreateImageResource (const char *resource)
void | Iw2DDrawImage (CIw2DImage *image, CIwSVec2 topLeft, CIwSVec2 size)
void | Iw2DDrawImage (CIw2DImage *image, CIwSVec2 topLeft)
void | Iw2DDrawImageRegion (CIw2DImage *image, CIwSVec2 topLeft, CIwSVec2 size, CIwSVec2 regionOffset, CIwSVec2 regionSize)
void | Iw2DDrawImageRegion (CIw2DImage *image, CIwSVec2 topLeft, CIwSVec2 regionOffset, CIwSVec2 regionSize)

Detailed Description

Images can be created from raw files, or held in the Airplay resource system for increased efficiency

Images should be deleted when finished with.

Function Documentation

CIw2DImage* Iw2DCreateImage ( CIw2DSurface * surface )

Make a CIw2DImage from an existing surface - note that this is a live window into the surface (the contents will be updated when the surface is).

Parameters:
surface the surface to use
Returns:
a CIw2DImage object
See also:
Iw2DCreateSurface
Required Header Files
Iw2D.h

CIw2DImage* Iw2DCreateImage ( CIwImage & image )

Create a CIw2DImage from an existing CIwImage resource

Parameters:
image the image to use
Returns:
a CIw2DImage object
See also:
IwResManager
Required Header Files
Iw2D.h

CIw2DImage* Iw2DCreateImage ( const char * filename )

Create a CIw2DImage from any standard image format file supported by CIwImage

Parameters:
filename the file to load
Returns:
a CIw2DImage object
See also:
CIwImage
Required Header Files
Iw2D.h

CIw2DImage* Iw2DCreateImageResource ( const char * resource )

Create a CIw2DImage from an existing image resource

Parameters:
resource the resource to use
Returns:
a CIw2DImage object
See also:
IwResManager
Required Header Files
Iw2D.h

void Iw2DDrawImage | ( | CIw2DImage * | image,
 |  | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size
 | ) |  |

Draw an image stretched to arbitrary size at the specified location, modulated by the current colour, using the current alphamode

Note:
This functionality is not available in iw2d_lite.
Parameters:
image | the image to draw
topLeft | the top left position of the image on the screen
size | the size of the image on the screen
See also:
Iw2DSetColour, Iw2DSetAlphaMode, Iw2DSetImageTransform
Required Header Files
Iw2D.h

void Iw2DDrawImage | ( | CIw2DImage * | image,
 |  | CIwSVec2 | topLeft
 | ) |  |

Draw an image at 1:1 size at the specified location, modulated by the current colour, using the current alphamode

Parameters:
image | the image to draw
topLeft | the top left position of the image on the screen
See also:
Iw2DSetColour, Iw2DSetAlphaMode, Iw2DSetImageTransform
Required Header Files
Iw2D.h

void Iw2DDrawImageRegion | ( | CIw2DImage * | image,
 |  | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size,
 |  | CIwSVec2 | regionOffset,
 |  | CIwSVec2 | regionSize
 | ) |  |

Draw a region of an image stretched to arbitrary size at the specified location, modulated by the current colour, using the current alphamode

Note:
This functionality is not available in iw2d_lite.
Parameters:
image | the image to draw
topLeft | the top left position of the image on the screen
size | the size of the image on the screen
regionOffset | the top left of the region within the image
regionSize | the size of the region within the image
See also:
Iw2DSetColour, Iw2DSetAlphaMode, Iw2DSetImageTransform
Required Header Files
Iw2D.h

void Iw2DDrawImageRegion | ( | CIw2DImage * | image,
 |  | CIwSVec2 | topLeft,
 |  | CIwSVec2 | regionOffset,
 |  | CIwSVec2 | regionSize
 | ) |  |

Draw a region of an image at 1:1 size at the specified location, modulated by the current colour, using the current alphamode

Parameters:
image | the image to draw
topLeft | the top left position of the image on the screen
regionOffset | the top left of the region within the image
regionSize | the size of the region within the image (and thus, on the screen)
See also:
Iw2DSetColour, Iw2DSetAlphaMode, Iw2DSetImageTransform
Required Header Files
Iw2D.h


Airplay API Reference: Fonts

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference > Fonts >

Fonts
[Iw2D API Reference]

Functions

CIw2DFont * | Iw2DCreateFont (const char *filename)
CIw2DFont * | Iw2DCreateFontResource (const char *resource)
void | Iw2DDrawString (uint16 *string, CIwSVec2 topLeft, CIwSVec2 size, CIw2DFontAlign horzAlign, CIw2DFontAlign vertAlign)
void | Iw2DDrawString (const char *string, CIwSVec2 topLeft, CIwSVec2 size, CIw2DFontAlign horzAlign, CIw2DFontAlign vertAlign)
int32 | Iw2DGetStringWidth (uint16 *string)
int32 | Iw2DGetStringWidth (const char *string)

Detailed Description

Iw2D supports font rendering based on IwGxFont resources.

Fonts must be created from the Airplay resource system.

See also:
IwGxFont, IwResManager

Function Documentation

CIw2DFont* Iw2DCreateFont ( const char * filename )

Create a CIw2DFont from a .GXFONT file. On Win32 debug builds this will produce a binary version of the font (a .GXFONT.BIN file) and load that. The ARM build will only use the GXFONT.BIN file.

Parameters:
filename the font to use
Returns:
a CIw2DFont object
See also:
IwResManager
Required Header Files
Iw2D.h

CIw2DFont* Iw2DCreateFontResource ( const char * resource )

Create a CIw2DFont from an existing font resource

Parameters:
resource the resource to use
Returns:
a CIw2DFont object
See also:
IwResManager
Required Header Files
Iw2D.h

void Iw2DDrawString | ( | uint16 * | string,
 |  | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size,
 |  | CIw2DFontAlign | horzAlign,
 |  | CIw2DFontAlign | vertAlign
 | ) |  |

Draw a (UCS-2 encoded) string in the specified rectangle

Parameters:
string | a UCS-2 encoded string to draw
topLeft | the top left corner of the text region
size | the size of the text region
horzAlign | the horizontal alignment of the text within the region
vertAlign | the vertical alignment of the text within the region
See also:
Iw2DSetFont, Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

void Iw2DDrawString | ( | const char * | string,
 |  | CIwSVec2 | topLeft,
 |  | CIwSVec2 | size,
 |  | CIw2DFontAlign | horzAlign,
 |  | CIw2DFontAlign | vertAlign
 | ) |  |

Draw a (utf8 encoded) string in the specified rectangle

Parameters:
string | a utf8 encoded string to draw
topLeft | the top left corner of the text region
size | the size of the text region
horzAlign | the horizontal alignment of the text within the region
vertAlign | the vertical alignment of the text within the region
See also:
Iw2DSetColour, Iw2DSetAlphaMode
Required Header Files
Iw2D.h

int32 Iw2DGetStringWidth ( uint16 * string )

Get the width of the specified string in the current font

Parameters:
string a UCS-2 encoded string to draw
Returns:
The width of the specified string in the current font
See also:
Iw2DSetFont
Required Header Files
Iw2D.h

int32 Iw2DGetStringWidth ( const char * string )

Get the width of the specified string in the current font

Parameters:
string a utf8 encoded string to draw
Returns:
The width of the specified string in the current font
See also:
Iw2DSetFont
Required Header Files
Iw2D.h


Airplay API Reference: Miscellaneous Functions

Airplay API Reference > Iw2D API Documentation > Iw2D API Reference > Miscellaneous Functions >

Miscellaneous Functions
[Iw2D API Reference]

Functions

CIw2DSurface * | Iw2DCreateSurface (int32 w, int32 h)
void | Iw2DFinishDrawing ()
int32 | Iw2DGetSurfaceHeight ()
void | Iw2DGetSurfaceInfo (s3eSurfaceInfo &outInfo)
int32 | Iw2DGetSurfaceWidth ()
void | Iw2DInit ()
void | Iw2DSurfaceClear (CIwColour c)
void | Iw2DSurfaceShow ()
void | Iw2DTerminate ()

Function Documentation

CIw2DSurface* Iw2DCreateSurface | ( | int32 | w,
 |  | int32 | h
 | ) |  |

Create a destination surface of the specified size

Parameters:
w | the width of the surface to create
h | the height of the surface to create
Returns:
a surface object. This should be deleted when the surface is finished with.
Required Header Files
Iw2D.h

void Iw2DFinishDrawing ( )

Finish any pending drawing. This can be used to guarantee drawing order between Iw2D and other modules.

Required Header Files
Iw2D.h

int32 Iw2DGetSurfaceHeight ( )

Get the height of the current surface

Returns:
The height of the current surface
Required Header Files
Iw2D.h

void Iw2DGetSurfaceInfo ( s3eSurfaceInfo & outInfo )

Retrieve details of the current surface

Parameters:
outInfo an s3eSurfaceInfo structure to receive the details. Note that in gl mode only the width and height will be filled out.
Required Header Files
Iw2D.h

int32 Iw2DGetSurfaceWidth ( )

Get the width of the current surface

Returns:
The width of the current surface
Required Header Files
Iw2D.h

void Iw2DInit ( )

Initialise the Iw2D module. This function must be called prior to any others.

Required Header Files
Iw2D.h

void Iw2DSurfaceClear ( CIwColour c )

Clear the current surface to the specified colour.

Parameters:
c the colour to clear to
Required Header Files
Iw2D.h

void Iw2DSurfaceShow ( )

Finish any pending drawing and present the surface. The default surface must be the current drawing surface. This function must be called instead of other Show() functions like s3eSurfaceShow() and IwGxSwapBuffers().

Required Header Files
Iw2D.h

void Iw2DTerminate ( )

Terminate the Iw2D module. This function must be called prior to shutdown.

Required Header Files
Iw2D.h


Airplay API Reference: Iw2D Examples

Airplay API Reference > Iw2D API Documentation > Iw2D Examples >

Iw2D Examples

This document provides a set of examples that illustrate how to use the functionality contained within Iw2D. Each example uses the functionality specific to Iw2D, and endeavours to illustrate the capabilities of each of these modules.

The following examples are contained within this section:

  • Iw2D Primitives Example
  • Iw2D Images Example
  • Iw2D Strings Example
  • Iw2D Transforms Example
  • Iw2D Advanced Transforms Example


Airplay API Reference: Iw2D Primitives Example

Airplay API Reference > Iw2D API Documentation > Iw2D Examples > Iw2D Primitives Example >

Iw2D Primitives Example

The following example demonstrates how to draw simple primitives using Iw2D

The main functions used to achieve this are:

  • Iw2DSetColour
  • Iw2DDrawArc
  • Iw2DDrawLine
  • Iw2DDrawPolygon
  • Iw2DDrawRect
  • Iw2DFillArc
  • Iw2DFillPolygon
  • Iw2DFillRect

Iw2D supports a number of primitives that can be rendered without any assets. This example demonstrates drawing using these primitives.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DPrimitives
//-----------------------------------------------------------------------------

#include "Iw2D.h"

int32 g_Frame = 0;

CIwColour g_Colours[] =
{
    { 0x00, 0x20, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x00, 0xa0, 0xff, 0xff },
    { 0x00, 0xc0, 0xff, 0xff },
    { 0x00, 0xe0, 0xff, 0xff },
    { 0x00, 0xff, 0xff, 0xff },
};

//-----------------------------------------------------------------------------
// The following function initialises the 2D module
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();
}
//-----------------------------------------------------------------------------
// The following function uninitialises the 2D module
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function increments the frame counter
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    g_Frame++;

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders a circle of rectangles, using the frame
// number to cycle the colours
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    const uint32 c_NumberCols = sizeof(g_Colours)/sizeof(g_Colours[0]);
    const uint32 c_NumberRects = 30;
    const uint32 c_RectSize = 40;

    //Calculate the centre of the circle to be the centre of the surface
    //Offset by half a rectangle width so the rectangles are centred on the calculate points
    CIwSVec2 centre = CIwSVec2((int16)(Iw2DGetSurfaceWidth() / 2 - c_RectSize / 2),
        (int16)(Iw2DGetSurfaceHeight() / 2 - c_RectSize / 2));

    for(uint32 i = 0; i < c_NumberRects; i++)
    {
        //Set the colour for each rectangle
        uint32 col = (i + g_Frame) % c_NumberCols;
        Iw2DSetColour(g_Colours[col]);

        //Calculate a rotated radius
        CIwSVec2 pos = CIwSVec2((int16)IwGeomSin(i * IW_GEOM_ONE / c_NumberRects),
            (int16)IwGeomCos(i * IW_GEOM_ONE / c_NumberRects));

        //Scale the radius to quarter surface width
        pos *= Iw2DGetSurfaceWidth() / 4;

        //Offset to centre
        pos += centre;

        //Draw a solid rectangle at that point
        Iw2DFillRect(pos, CIwSVec2(c_RectSize, c_RectSize));
    }

    // Show the surface
    Iw2DSurfaceShow();
}


Airplay API Reference: Iw2D Images Example

Airplay API Reference > Iw2D API Documentation > Iw2D Examples > Iw2D Images Example >

Iw2D Images Example

The following example demonstrates how to draw images using Iw2D

The main functions used to achieve this are:

  • Iw2DSetColour
  • Iw2DCreateImage
  • Iw2DDrawImageRegion

Iw2D provides a variety of simple image drawing. This example demonstrates drawing using an image.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DImages
//-----------------------------------------------------------------------------

#include "Iw2D.h"

int32 g_Frame = 0;

CIwColour g_Colours[] =
{
    { 0x00, 0x00, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0xc0, 0xe0, 0xff, 0xff },
    { 0xff, 0xff, 0xff, 0xff },
    { 0xcf, 0xef, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
};

CIw2DImage* g_AirplayLogo;

//-----------------------------------------------------------------------------
// The following function initialises the 2D module
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();

    // Create an iw2d compatible image
    g_AirplayLogo = Iw2DCreateImage("largeAirplayLogo.bmp");
}
//-----------------------------------------------------------------------------
// The following function uninitialises the 2D module
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete g_AirplayLogo;

    // Terminate
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function increments the frame counter
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    g_Frame++;

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the airplay logo cut up into tiles with a
// colours cycle
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    const uint32 c_NumberCols = sizeof(g_Colours)/sizeof(g_Colours[0]);
    const uint32 c_RegionSize = 30;

    //Calculate the top left of the logo
    //Offset by half a rectangle width so the rectangles are centred on the calculate points
    CIwSVec2 topLeft = CIwSVec2((int16)(Iw2DGetSurfaceWidth() / 2 - g_AirplayLogo->GetWidth() / 2),
        (int16)(Iw2DGetSurfaceHeight() / 2 - g_AirplayLogo->GetHeight() / 2));

    for(uint32 y = 0; y < g_AirplayLogo->GetHeight() / c_RegionSize; y++)
    {
        for(uint32 x = 0; x < g_AirplayLogo->GetWidth() / c_RegionSize; x++)
        {
            //Set the colour for each rectangle
            uint32 col = (x + y + g_Frame) % c_NumberCols;
            Iw2DSetColour(g_Colours[col]);

            //Calculate the top left of the region in the image
            CIwSVec2 pos = CIwSVec2((int16)(x * c_RegionSize), (int16)(y * c_RegionSize));

            //Draw a sub region of the image at the position (offset by the topLeft)
            Iw2DDrawImageRegion(g_AirplayLogo, topLeft + pos, pos, CIwSVec2(c_RegionSize, c_RegionSize));
        }
    }

    // Show the surface
    Iw2DSurfaceShow();
}

The following example demonstrates how to use surfaces using Iw2D

The main functions used to achieve this are:

  • Iw2DSetSurface

Iw2D supports the use of offscreen surfaces for special effects.

This example draws the airplay logo into a surface and adds a red rectangle to it.

It then draws using the surface in the same way as the Iw2DImages example.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DImages
//-----------------------------------------------------------------------------

#include "Iw2D.h"

int32 g_Frame = 0;

CIwColour g_Colours[] =
{
    { 0x00, 0x00, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0xc0, 0xe0, 0xff, 0xff },
    { 0xff, 0xff, 0xff, 0xff },
    { 0xcf, 0xef, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
};

CIw2DImage* g_AirplayLogo;

//-----------------------------------------------------------------------------
// The following function initialises the 2D module
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();

    // Create an iw2d compatible image
    g_AirplayLogo = Iw2DCreateImage("largeAirplayLogo.bmp");
}
//-----------------------------------------------------------------------------
// The following function uninitialises the 2D module
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete g_AirplayLogo;

    // Terminate
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function increments the frame counter
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    g_Frame++;

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the airplay logo cut up into tiles with a
// colours cycle
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    const uint32 c_NumberCols = sizeof(g_Colours)/sizeof(g_Colours[0]);
    const uint32 c_RegionSize = 30;

    //Calculate the top left of the logo
    //Offset by half a rectangle width so the rectangles are centred on the calculate points
    CIwSVec2 topLeft = CIwSVec2((int16)(Iw2DGetSurfaceWidth() / 2 - g_AirplayLogo->GetWidth() / 2),
        (int16)(Iw2DGetSurfaceHeight() / 2 - g_AirplayLogo->GetHeight() / 2));

    for(uint32 y = 0; y < g_AirplayLogo->GetHeight() / c_RegionSize; y++)
    {
        for(uint32 x = 0; x < g_AirplayLogo->GetWidth() / c_RegionSize; x++)
        {
            //Set the colour for each rectangle
            uint32 col = (x + y + g_Frame) % c_NumberCols;
            Iw2DSetColour(g_Colours[col]);

            //Calculate the top left of the region in the image
            CIwSVec2 pos = CIwSVec2((int16)(x * c_RegionSize), (int16)(y * c_RegionSize));

            //Draw a sub region of the image at the position (offset by the topLeft)
            Iw2DDrawImageRegion(g_AirplayLogo, topLeft + pos, pos, CIwSVec2(c_RegionSize, c_RegionSize));
        }
    }

    // Show the surface
    Iw2DSurfaceShow();
}


Airplay API Reference: Iw2D Strings Example

Airplay API Reference > Iw2D API Documentation > Iw2D Examples > Iw2D Strings Example >

Iw2D Strings Example

The following example demonstrates how to draw text using Iw2D

The main functions used to achieve this are:

  • Iw2DSetColour
  • Iw2DCreateFont
  • Iw2DDrawString

Iw2D supports simple rendering of fonts. Fonts are complex resources that can only be created through Airplay Studio's resource management system

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DStrings
//-----------------------------------------------------------------------------

#include "Iw2D.h"
#include "IwResManager.h"

CIw2DFont* g_Font;

//-----------------------------------------------------------------------------
// The following function initialises the modules, loads the resources and
// prepares them for Iw2D
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();

    // Initialise IwResManager
    IwResManagerInit();

    // Load the group containing the "arial14" font
    IwGetResManager()->LoadGroup("Iw2DStrings.group");

    // Prepare the iwgxfont resource for rendering using Iw2D
    g_Font = Iw2DCreateFontResource("arial14");
}
//-----------------------------------------------------------------------------
// The following function uninitialises the modules and clears up the resources
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    //Clear up the Iw2DFont
    delete g_Font;

    //IwResManagerTerminate will automatically clear up any loaded groups,
    //so there is no need to explicitly destroy the group.
    //However, for demonstration purposes we do so now
    IwGetResManager()->DestroyGroup("Iw2DStrings");

    // Terminate all modules initiaised
    IwResManagerTerminate();
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function does nothing in this example
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
// The following function renders a string in the centre of the screen
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    // Set the current font
    Iw2DSetFont(g_Font);

    // Draw in black
    Iw2DSetColour(0xff000000);

    // Render the text into a 100x100 region
    CIwSVec2 region(100, 100);

    // Centred on the centre of the surface
    CIwSVec2 topLeft((int16)(Iw2DGetSurfaceWidth()/2 - region.x/2),
        (int16)(Iw2DGetSurfaceHeight()/2 - region.y/2));

    // Draw the string into the region
    Iw2DDrawString("Hello world from Iw2D", topLeft, region, IW_2D_FONT_ALIGN_CENTRE, IW_2D_FONT_ALIGN_CENTRE);

    // Show the surface
    Iw2DSurfaceShow();
}


Airplay API Reference: Iw2D Transforms Example

Airplay API Reference > Iw2D API Documentation > Iw2D Examples > Iw2D Transforms Example >

Iw2D Transforms Example

The following example demonstrates how to apply transforms to Iw2D drawing

The main functions used to achieve this are:

  • Iw2DSetColour
  • Iw2DSetTransformMatrix
  • Iw2DCreateImage
  • Iw2DDrawImageRegion

Iw2D can apply an arbitrary 2D matrix transformation to any drawing. This example demonstrates rotating the Iw2DImage example.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DTransforms
//-----------------------------------------------------------------------------

#include "Iw2D.h"

int32 g_Frame = 0;

CIwColour g_Colours[] =
{
    { 0x00, 0x00, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0xc0, 0xe0, 0xff, 0xff },
    { 0xff, 0xff, 0xff, 0xff },
    { 0xcf, 0xef, 0xff, 0xff },
    { 0x80, 0xc0, 0xff, 0xff },
    { 0x40, 0xa0, 0xff, 0xff },
    { 0x00, 0x80, 0xff, 0xff },
    { 0x00, 0x60, 0xff, 0xff },
    { 0x00, 0x40, 0xff, 0xff },
    { 0x00, 0x20, 0xff, 0xff },
};

CIw2DImage* g_AirplayLogo;

//-----------------------------------------------------------------------------
// The following function initialises the 2D module
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();

    g_AirplayLogo = Iw2DCreateImage("largeAirplayLogo.bmp");
}
//-----------------------------------------------------------------------------
// The following function uninitialises the 2D module
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete g_AirplayLogo;

    // Terminate
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function increments the frame counter
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    g_Frame++;

    return true;
}
//-----------------------------------------------------------------------------
// The following function renders the airplay logo cut up into tiles with a
// colours cycle
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    const uint32 c_NumberCols = sizeof(g_Colours)/sizeof(g_Colours[0]);
    const uint32 c_RegionSize = 30;

    //Calculate the top left of the logo
    //Offset by half a rectangle width so the rectangles are centred on the calculate points
    CIwSVec2 centre = CIwSVec2((int16)Iw2DGetSurfaceWidth() / 2, (int16)Iw2DGetSurfaceHeight() / 2);
    CIwSVec2 topLeft = centre - CIwSVec2((int16)g_AirplayLogo->GetWidth() / 2, (int16)g_AirplayLogo->GetHeight() / 2);

    //Make a matrix which is a simple rotate around screen centre by the current angle
    iwfixed angle = g_Frame*IW_FIXED(0.01);
    CIwMat2D rot;
    rot.SetRot(angle, (CIwVec2)centre);
    Iw2DSetTransformMatrix(rot);

    for(uint32 y = 0; y < g_AirplayLogo->GetHeight() / c_RegionSize; y++)
    {
        for(uint32 x = 0; x < g_AirplayLogo->GetWidth() / c_RegionSize; x++)
        {
            //Set the colour for each rectangle
            uint32 col = (x + y + g_Frame) % c_NumberCols;
            Iw2DSetColour(g_Colours[col]);

            //Calculate the top left of the region in the image
            CIwSVec2 pos = CIwSVec2((int16)(x * c_RegionSize), (int16)(y * c_RegionSize));

            //Draw a sub region of the image at the position (offset by the topLeft)
            Iw2DDrawImageRegion(g_AirplayLogo, topLeft + pos, pos, CIwSVec2(c_RegionSize, c_RegionSize));
        }
    }

    //Reset identity transform
    Iw2DSetTransformMatrix(CIwMat2D::g_Identity);

    // Show the surface
    Iw2DSurfaceShow();
}


Airplay API Reference: Iw2D Advanced Transforms Example

Airplay API Reference > Iw2D API Documentation > Iw2D Examples > Iw2D Advanced Transforms Example >

Iw2D AdvancedTransforms Example

The following example demonstrates how to apply arbitrary post-transformations to Iw2D drawing

The main functions used to achieve this are:

  • Iw2DSetColour
  • Iw2DSetPostTransformFn
  • Iw2DCreateImage
  • Iw2DDrawImageRegion

Iw2D can use a callback function to post-transform positions and colours prior to rendering. This allows non-linear transformation and lighting effects. This example adds lighting and a non-linear transformation to the Iw2DImage example.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIw2DAdvancedAdvancedTransforms
//-----------------------------------------------------------------------------

#include "Iw2D.h"

int32 g_Frame = 0;

// The centre of the effect
CIwSVec2 g_EffectCentre;

CIw2DImage* g_AirplayLogo;

//-----------------------------------------------------------------------------
// The following function initialises the 2D module
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    Iw2DInit();

    g_AirplayLogo = Iw2DCreateImage("largeAirplayLogo.bmp");
}
//-----------------------------------------------------------------------------
// The following function uninitialises the 2D module
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete g_AirplayLogo;

    // Terminate
    Iw2DTerminate();
}
//-----------------------------------------------------------------------------
// The following function increments the frame counter
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    g_Frame++;

    return true;
}

//-----------------------------------------------------------------------------
// The following function transforms vertices and colours such that ripples
// appear spreading out from the centre
//-----------------------------------------------------------------------------
void TransformAndLight(CIwSVec2* v, CIwColour* c, int32 numberPoints)
{
    const int32 c_RippleFrequency = 2;
    const int32 c_RippleSpeed = 250;
    const int32 c_RippleStrength = IW_FIXED(0.025);

    //For each point/colour passed in
    while(numberPoints--)
    {
        CIwSVec2 toCentre = *v - g_EffectCentre;

        iwfixed dist = toCentre.GetLength();

        //Get the direction to the centre of the effect
        if( dist )
            toCentre.Normalise();

        //Calculate the ripple strength
        iwfixed ofs =
            IW_FIXED_MUL(
                IwGeomCos(dist*c_RippleFrequency-g_Frame*c_RippleSpeed),
                c_RippleStrength
            );

        //Offset this point according to the strength
        *v += toCentre * ofs;

        //Light based on the offset
        uint8 brightness = (uint8)MIN(255, ((ofs) + 0xa0));

        v++;

        //Set the light
        c->SetGrey(brightness);

        //Knock out red channel below the centre
        c->r -= (uint8)MAX(0, (toCentre.y * 0x20 / IW_GEOM_ONE));
        c++;

    }
}

//-----------------------------------------------------------------------------
// The following function renders the airplay logo cut up into tiles with a
// colours cycle
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen (in this example the screen is cleared by the example
    // framework, so there's no need to call it here)
    // Iw2DSurfaceClear(0xffffffff);

    const uint32 c_RegionSize = 30;

    //Calculate the top left of the logo
    //Offset by half a rectangle width so the rectangles are centred on the calculate points
    CIwSVec2 centre = CIwSVec2((int16)Iw2DGetSurfaceWidth() / 2, (int16)Iw2DGetSurfaceHeight() / 2);
    CIwSVec2 topLeft = centre - CIwSVec2((int16)g_AirplayLogo->GetWidth() / 2, (int16)g_AirplayLogo->GetHeight() / 2);

    //Calculate the centre of the effect (it rotates around the edge of the screen as time passes)
    iwfixed angle = g_Frame*IW_FIXED(0.01);
    g_EffectCentre = CIwSVec2((int16)IwGeomSin(angle), (int16)IwGeomCos(angle)) * (Iw2DGetSurfaceWidth()/2) + centre;

    //The input to the post-transform is in sub pixels (at 8x size)
    g_EffectCentre <<= 3;

    //Set the post transform function
    Iw2DSetPostTransformFn(TransformAndLight);

    //The final images will still be modulated on the same 'order' as their untransformed colour,
    //So to see the blue in the final image we must set a colour that would require full RGB modulation
    //(i.e. The RGB must not be equal)
    Iw2DSetColour(0x80ff8080);

    for(uint32 y = 0; y < g_AirplayLogo->GetHeight() / c_RegionSize; y++)
    {
        for(uint32 x = 0; x < g_AirplayLogo->GetWidth() / c_RegionSize; x++)
        {
            //Calculate the top left of the region in the image
            CIwSVec2 pos = CIwSVec2((int16)(x * c_RegionSize), (int16)(y * c_RegionSize));

            //Draw a sub region of the image at the position (offset by the topLeft)
            Iw2DDrawImageRegion(g_AirplayLogo, topLeft + pos, pos, CIwSVec2(c_RegionSize, c_RegionSize));
        }
    }

    //Clear the post-transformation
    Iw2DSetPostTransformFn(NULL);

    // Show the surface
    Iw2DSurfaceShow();
}


Airplay API Reference: IwResManager API Documentation

Airplay API Reference > IwResManager API Documentation >

IwResManager API Documentation

The IwResManager documentation contains the following sections:

  • IwResManager API Overview
  • IwResManager API Reference
  • IwResManager Examples


Airplay API Reference: IwResManager API Overview

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview >

IwResManager API Overview

IwResManager is a resource management utility module. Conceptually, it sits above IwUtil, and parallel to IwGx. A "resource" is an application asset; for example, a texture, material, or model.

To use IwResManager functionality, you must include "IwResManager.h" in your source and iwresmanager as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwresmanager
  • }

When using IwResManager, the IwGx module does not need to be specified in your project's MKB as it will be implicitly included as a subproject of this module.

IwResManager performs three functions:

  • Loading of resources from their "source" versions (BMP files, text-file descriptions of models, etc.)
  • Serialisation of resources to and from their compact binary representations.
  • Organisation of resources into "groups", for convenience.

It is not mandatory to make use of IwResManager. It is perfectly possible to write an application using IwGx and IwGraphics without using IwResManager. However, IwResManager is very powerful and is tied closely to the SDK's asset pipeline methodology, both on desktop and device.

The following subjects are covered in this section:

  • IwResManager Initialisation and Termination
  • Resource Manager Modes
  • Groups
  • Destroying Resources
  • Resource Searches
  • Resource Templates
  • Resource Handlers
  • The Application Resource Pipeline
  • Advanced - Controlling How Group Binaries are Built
  • Building Multiple Data Sets


Airplay API Reference: IwResManager Initialisation and Termination

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > IwResManager Initialisation and Termination >

IwResManager Initialisation and Termination

The user must initialise IwResManager and terminate IwResManager as follows:

  • // Begin application
  • IwGxInit();
  • IwResManagerInit();

    • ...rest of application

  • // End application
  • IwResManagerTerminate();
  • IwGxTerminate();


Airplay API Reference: Resource Manager Modes

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Manager Modes >

Resource Manager Modes

The resource manager can operate in two modes:

  • BUILD
  • LOAD

In BUILD mode, resources are loaded from their "source" versions; for example, textures are loaded from BMP files (or similar), materials are loaded from text-file descriptions (usually MTL files), models are loaded from text-file descriptions (usually GEO files), etc. If the required "source" assets do not exist, the resource manager will cause an assertion. The associated application objects are then constructed and serialised out as compact binary versions. The application objects are then destroyed, and re-created by serialising in the compact binary versions.

In LOAD mode, resources are loaded from their compact binary versions. If the required binary files do not exist, the resource manager will cause an assertion. The "source" versions of the assets are not required.

By default, the resource manager modes are set as follows:

  • For Win32 Debug builds, the resource manager operates in BUILD mode - so it always loads from "source" assets, and builds the binary versions. The symbol IW_BUILD_RESOURCES is defined only for Win32 Debug builds, and can be used to wrap user resource-building code.
  • For all other builds, the resource manager operates in LOAD mode - so it always loads straight from the binary versions.

The user can explicitly set the resource manager mode as follows:

  • // To set the resource manager into BUILD mode
  • IwGetResManager()->SetMode(CIwResManager::MODE_BUILD);
  • // To set the resource manager into LOAD mode
  • IwGetResManager()->SetMode(CIwResManager::MODE_LOAD);

Note: It is not possible, in a build which is not Win32 Debug, to set the resource manager into BUILD mode (any such attempt will result in an error). This is because much of the code used to build the binary versions of assets from their "source" versions is not compiled into the release executable.


Airplay API Reference: Groups

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Groups >

Groups

All resources sit within the resource manager in "groups". A group is a collection of resources, organised by "type".

Resources are derived from CIwManaged, so they have names. In Debug builds, the full string name is available; in Release builds, only the hashed string name is available.

Note: Within a group, resources of a given type must have unique names. For example, within a group, it is legal to have a texture named "test" and a model named "test", but it is not legal to have two different textures named "test".

The following subjects are discussed in this section:

  • Loading Resources Using the GROUP File
  • Child Groups
  • Shared Groups

Note: For an example of how groups are used in practice, see the Groups Example.


Airplay API Reference: Loading Resources Using the GROUP File

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Groups > Loading Resources Using the GROUP File >

Loading Resources Using the GROUP File

The starting point for loading any resource is the GROUP text file. A GROUP file is a text file in standard ITX format.

Note: For more information on the ITX format and how it is constructed, see the Text Parsing section of the 'IwUtil' documentation.

It declares a single named group, and specifies the resources to load into that group. For example:

  • Text file "example.group"
  • CIwResGroup
  • {
    • /* Must always name the group */
    • name "Example"
    • /* Load a single texture*/
    • "./test.bmp"
  • }

You can load this group as follows:

  • IwGetResManager()->LoadGroup("example.group");

The resource manager will now contain a single group, which contains a single texture. We can access the group as follows:

  • CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

You can then access the texture as follows:

  • CIwTexture* pTexture = (CIwTexture*)pGroup->GetResNamed("test", IW_GX_RESTYPE_TEXTURE);

There are several things to note:

  • By default, any search within the resource manager will cause an assertion if the searched item is not found. It is possible to override this behaviour and return NULL instead. For more information on changing search behaviour, see Resource Searches.
  • By default, resources are named according to their leaf filenames; so "test.bmp" becomes a CIwTexture object named "test". It is possible to override this behaviour and specify a name for the loaded resource. For more information on naming resources, see Resource Templates.
  • Resource "types" are defined according to the SDK module they are associated with. For example, IwGx defines two resources types, IW_GX_RESTYPE_TEXTURE and IW_GX_RESTYPE_MATERIAL. These type defines are strings representing the associated SDK classnames.
  • All resource classes are derived from CIwResource (which is derived from CIwManaged). Searches for resources will return pointers of type CIwResource, which need to be cast to the appropriate type.
  • A GROUP file must contain one and only one CIwResGroup block; i.e., it must define a single resource group. Trying to define multiple groups within a single GROUP file will cause undefined behaviour.

The LoadGroup() Method

Depending on which mode you are in, the LoadGroup() method behaves in two different ways.

In BUILD mode, the resource manager passes the text file to the text parser singleton. The text file is parsed, which results in a group object (an instance of class CIwResGroup) being created. The group is named "Example". Any lines in the text file that are not special tokens are taken to be pathnames to resources to load. So in this case, "./test.bmp" is taken to be a pathname to a resource to load. The resource manager loads the BMP file, creates a texture object (an instance of class CIwTexture) and adds this to the group.

Note: The "./" at the start of the pathname indicates that the base folder is the same as the folder containing the GROUP text file itself.

When all resources have been loaded, the resource manager creates a binary file called "example.group.bin". It then serialises to the binary file all resources of all types within the group; in this case, just the single CIwTexture object.

Two other files are also written. "example.group.bin.txt" is a text description of everything in the group. This can be useful for debugging the group building process. "example.group.hst" is a binary file containing the hash-string table for the group; i.e., a map of resource string names to their hashed versions.

Once the binary file has been written, the resource manager destroys the group. It then reloads the group from the binary version. This process is described below.

In LOAD mode, the resource manager looks for the binary file "example.group.bin". This file contains all the information necessary to create the resource objects and serialise them in. In Debug builds, the resource manager also looks for the file "example.group.hst". If it exists, it loads the map of resource string names to their hashed versions; it is then able to set the resource string names for debugging purposes. It is perfectly legal for the file not to be found; this simply means that in the debugger, only the hashed resource names are available, and the resource string names will simply be "?" (undefined).

All of this behaviour is hidden from the user within the implementation of LoadGroup(). The user simply needs an awareness of what mode the resource manager is in. For development, the user is advised to leave the resource manager in BUILD mode (the default for Debug builds). If the "source" assets are not changing regularly, and the binary files have already been created, the user could switch the resource manager to LOAD mode, which will reduce the time taken for the application to start up.


Airplay API Reference: Child Groups

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Groups > Child Groups >

Child Groups

The GROUP file contains the pathnames of the resources to load into that group. These may include image files (BMPs, etc.), text files (MTL, GEO, etc.) and others.

The user may include in this list the pathname of another GROUP file (or multiple GROUP files). In this case, the specified GROUP file is loaded, and becomes a "child" of the "parent" group. It is important to note that the child group's resources are not added to the parent group; neither are they serialised within the parent group's binary file. The child group is a group like any other, and it serialises its own binary file. However, there is a parent-child relationship between the two groups; destroying the parent will destroy the child, and searches within the parent group will by default also search the child group.

For more information on searching, see Resource Searches.

Child groups are useful because it is often convenient to package up collections of resources into groups at quite a fine granularity; for instance, an application entity might have an associated GROUP file that contains its associated models, animations, sound effects, etc. A game level would then have its own GROUP file which could reference all required application entity GROUP files as child groups.

For example:

In monster1.group

  • CIwResGroup
  • {
    • name "Monster1"
    • "./monster1/models/monster1.geo"
    • "./monster1/sfx/monster1_attack.wav"
    • "./monster1/sfx/monster1_die.wav"
  • }

In monster2.group

  • CIwResGroup
  • {
    • name "Monster2"
    • "./monster2/models/monster2.geo"
    • "./monster2/sfx/monster2_attack.wav"
    • "./monster2/sfx/monster2_die.wav"
  • }

In level1.group

  • CIwResGroup
  • {
    • name "level1"
    • "./monster1/monster1.group"
    • "./monster2/monster2.group"
  • }

Child groups can also be used to simply add their resources to the parent using CIwResTemplateGROUP's 'inline' parameter.


Airplay API Reference: Shared Groups

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Groups > Shared Groups >

Shared Groups

Any group can be flagged as "shared" - by default, groups are not shared. If a group is shared, it will be included in any resource search - for more information on searching, see Resource Searches. You can set a group's shared status within the GROUP file, as follows:

  • CIwResGroup
  • {
    • name "level1"
    • shared true
    • ...
  • }

You can also set it via the API:

  • IwGetResManager()->LoadGroup("example1.group");
  • CIwResGroup* pGroup = IwGetResManager()->GetCurrentGroup();
  • // Set as shared
  • pGroup->SetShared(true);
  • // Set as not shared
  • pGroup->SetShared(false);


Airplay API Reference: Destroying Resources

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Destroying Resources >

Destroying Resources

Resources within groups should never be destroyed individually; instead, you must destroy the entire group, as follows:

  • // Assume group named "Example" exists - now destroy it
  • IwGetResManager()->DestroyGroup("Example");

Or, alternatively:

  • CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");
  • IwGetResManager()->DestroyGroup(pGroup);

If the group has any child groups, they will also be destroyed. In the event that any child group is also a child of another group, the child group will not be destroyed.

It is legal to destroy a group which may be a child of another group (or indeed of multiple other groups).


Airplay API Reference: Resource Searches

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Searches >

Resource Searches

Resource searches come in three types:

  • Searching for a Specified Group
  • Searching within a Group for a Resource of a Specified Name and Type
  • Searching within a Group for a list of Resources of a Specified Type
  • Modifying a Search

Note: For an example of how resource searches are used in practice, see the Resource Search Example and Advanced Resource Search Example.


Airplay API Reference: Searching for a Specified Group

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Searches > Searching for a Specified Group >

Searching for a Specified Group

You can search for a named group as follows:

CIwResGroup pGroup = IwGetResManager()->GetGroupNamed("Example");

By default, the resource manager will cause an assertion if the named group is not found (i.e., it is not loaded). For more information on changing your search, see Modifying a Search. If the group is found, the pointer returned is valid until the group is destroyed.

The resource manager also has a concept of the "current" group. The current group is the group most recently loaded; or alternatively, that specified by the user. For example:

  • IwGetResManager()->LoadGroup("example1.group");
  • IwGetResManager()->LoadGroup("example2.group");
  • CIwResGroup* pGroup; pGroup = IwGetResManager()->GetCurrentGroup();
  • // pGroup now points to example2
  • pGroup = IwGetResManager()->GetGroupNamed("example1");
  • // pGroup now points to example1
  • IwGetResManager()->SetCurrentGroup(pGroup);
  • pGroup = IwGetResManager()->GetCurrentGroup();
  • // pGroup now points to example1


Airplay API Reference: Searching within a Group for a Resource of a Specified Name and Type

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Searches > Searching within a Group for a Resource of a Specified Name and Type >

Searching within a Group for a Resource of a Specified Name and Type

This is the most common type of search; starting from a group, we search for a named resource of a known type. For example:

  • IwGetResManager()->LoadGroup("example1.group");
  • CIwResGroup* pGroup = IwGetResManager()->GetCurrentGroup();
  • CIwTexture* pTexture = (CIwTexture*)pGroup->GetResNamed("test", IW_GX_RESTYPE_TEXTURE);

By default, the resource manager will cause an assertion if the named resource of the specified type is not found. For further information on changing your search options, see Modifying a Search. If the resource is found, the pointer returned is valid until the group is destroyed.


Airplay API Reference: Searching within a Group for a list of Resources of a Specified Type

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Searches > Searching within a Group for a list of Resources of a Specified Type >

Searching within a Group for a list of Resources of a Specified Type

This is unusual, but it is possible to get hold of the list of resources of a given type within a given group. For example:

  • IwGetResManager()->LoadGroup("example1.group");
  • CIwResGroup* pGroup = IwGetResManager()->GetCurrentGroup();
  • CIwResList* pList = pGroup->GetListNamed(IW_GX_RESTYPE_TEXTURE);
  • /* pList->m_Resources is a CIwManagedList of all the resources of the specified type in this group */

By default, the resource manager will cause an assertion if the named list does not exist (i.e., if there are no resources of that type in the group). For more information on searching, see Modifying a Search. If the list is found, the pointer returned is valid until the group is destroyed.


Airplay API Reference: Modifying a Search

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Searches > Modifying a Search >

Modifying a Search

Often you want the search logic to differ from the default behaviour. All of the search functions take an optional input flag, which can be used to modify the search logic. The following flags are available:

  • IW_RES_PERMIT_NULL_F: By default, if any search fails, it will cause an assertion. Pass in this flag if instead you wish the function simply to return NULL.
  • IW_RES_IGNORE_SHARED_F: By default, if any group is flagged as shared, it will be included in any search for a named resource. Pass in the flag if you wish to ignore shared groups (and only search within the group itself).
  • IW_RES_IGNORE_CHILDREN_F: By default, any search for a named resource within a group will also search any child groups of the group. Pass in the flag if you wish to ignore any child groups of the group (and only search within the group itself).

The following example code allows us to determine whether a named resource of a given type exists within a group, while ignoring any other shared groups or child groups:

  • CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example", IW_RES_PERMIT_NULL_F);
  • if (pGroup)
  • {
    • // Group named "Example" exists
    • CIwTexture* pTexture = (CIwTexture)pGroup->GetResNamed("test", IW_RES_PERMIT_NULL_F| IW_RES_IGNORE_SHARED_F | IW_RES_IGNORE_CHILDREN_F);
    • if (pTexture)
    • {
        • // Texture named "test" exists within group // named "Example"
      }
    • else
    • {
      • // Texture named "test" does NOT exist within
      • // group named "Example"
    • }
    • }
    • else
    • {
      • // Group named "Example" does NOT exist
    • }


Airplay API Reference: Resource Templates

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Templates >

Resource Templates

When a resource is loaded from its "source" version, various default parameters may be used when determining how to construct the associated application object. We call this process "conditioning" the resource. For example, a texture may exist as a BMP file in some format, but what format should it be conditioned to for the application?

The resource manager uses the concept of a "template" to describe a named set of parameter values that can be used to control how the application object is conditioned from the "source" version. Named templates should be described in an ITX file, and parsed after constructing the resource manager singleton. GROUP files can then specify which templates to use before loading resources. For example:

Text file "resourcetemplates.itx"

  • // Using this template will result in conversion to default formats
  • CIwResTemplateImage
  • {
    • name "default"
    • formatSW FORMAT_UNDEFINED
    • formatHW FORMAT_UNDEFINED
  • }
  • // Using this template will result in conversion to the specified format for SW only
  • CIwResTemplateImage
  • {
    • name "sw_4bit"
    • formatSW PALETTE4_ABGR_1555
  • }

Text file "example.group"

  • CIwResGroup
  • {
    • useTemplate "image" "sw_4bit"
    • "./test0.bmp"
    • useTemplate "image" "default"
    • "./test1.bmp"
  • }

The 'useTemplate' attribute takes two parameters; firstly the string name of the associated resource file type (in this case, image, which is an accepted resource type name for all image files) and secondly the name of the resource template itself.

In this example the following is performed:

  • we specify the 'sw_4bit' template is used when loading all subsequent image files. By default, image files will be converted to certain types depending on the format of the image on disk; so for example, an 8-bit (256 colour) palettised image will remain as 8-bit palettised. However, our template 'sw_4bit' implies that, for software rasterisation, all images should be converted to format 'PALETTE4_ABGR_1555'

    • Note: This template does not specify a new value for the parameter "formatHW".... so the decision about which format to convert to for hardware rasterisation remains the default.

  • We load 'test0.bmp', which will now be converted to format PALETTE4_ABGR_1555 for software rasterisation, irrespective of the image format on disk because it uses 'useTemplate' command specifies the 'sw_4bit' template.
  • We then specify the use of the template named 'default'. This template sets both parameters 'formatSW' and 'formatHW' to 'FORMAT_UNDEFINED', effectively reverting to the default format conversion.
  • We then load 'test1.bmp', which will now be converted to the default type depending on the format of the image format on disk.

The concept of resource templates is most useful when conditioning models, as there are many parameters that the user may wish to tweak which can not be controlled directly when exporting the model from the art package.

Each resource template class contains the documentation for its parameters. The following resource templates are available in the SDK:

  • CIwResTemplateANIM
  • CIwResTemplateGEO
  • CIwResTemplateGROUP
  • CIwResTemplateImage
  • CIwResTemplateMTL

Note: For an example of how resource templates are used in practice, see the Templates Example.


Airplay API Reference: Resource Handlers

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Resource Handlers >

Resource Handlers

Resource handlers are effectively "plug-ins" that the resource manager uses to handle different file types. It is not necessary to understand them when using the SDK at a basic level; however, you will need an understanding of them if you wish to add your own file types to the resource manager and have them understood.

A resource handler can be associated with a specific file extension. When a GROUP file is parsed, and a resource pathname is encountered, the resource manager searches all its attached handlers to find one which understands the resource file extension. The associated handler is then used to load the "source".

Each SDK module adds resource handlers for the file types associated with that module.

IwResManager adds:

  • CIwResHandlerGROUP: loads child groups.
  • CIwResHandlerImage: loads files of type BMP, GIF, PNG, TGA.
  • CIwResHandlerITX: loads text files of type ITX.
  • CIwResHandlerMTL: loads text files of type MTL.

IwGraphics adds:

  • CIwResHandlerGEO: loads text files of type GEO.

IwAnim adds:

  • CIwResHandlerANIM: loads text files of type ANIM.
  • CIwResHandlerSKIN: loads text files of type SKIN.
  • CIwResHandlerSKEL: loads text files of type SKEL.

It is not necessary to add a user-defined handler simply to parse a text file description of a user-defined class. As long as the class is added to the class factory, the user can write a text file description and save it as type ITX. For example:

  • Text file "myclassexample.itx"
  • CMyClass
  • {
    • name "MyClass1"
    • value0 100
    • value1 200
    • colour {255, 0, 0}
  • }

This file can be successfully parsed, provided:

  • CMyClass is derived from CIwManaged
  • CMyClass is added to the class factory, using IW_CLASS_FACTORY(CMyClass) and IW_CLASS_REGISTER(CMyClass)
  • CMyClass implements ParseAttribute, to parse the attributes 'value0', 'value1' and 'colour'
  • CMyClass implements ParseClose, to do something useful with the created instance (e.g., add it to some list).

Note: For an example of how resource handlers are used in practice, see the Resource HandlerExample".


Airplay API Reference: The Application Resource Pipeline

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > The Application Resource Pipeline >

The Application Resource Pipeline

The Win32 Debug build of an application is used to convert "input assets". The input assets, for example, can be images; sounds; text files; or anim, skel and mtl files output by the Airplay Studio Exporter. Each file, before it can be used in a release application, must be processed by the Win32 Debug build of the application (.S86 file) and converted into grouped binary assets (GROUP.BIN files), and potentially compressed archives (DZ files).

Note: For information on how to build a Win32 Debug build of the application, see the "Building a Project" chapter of the 'Developing in Airplay' documentation.

The Win32 Debug build can then be launched by the programmer, from within the standard programmer IDE (VC6 or .NET), or by an artist/designer, from within Airplay Studio Director.

A Debug build of the application will, by default, place the IwResManager singleton into BUILD_MODE. In this mode, the IwResManager singleton will convert "input assets" into binary form, as required.

To enable Airplay Studio Director to run the Win32 Debug build of the application in such a way as to generate specific binary assets, the programmer needs to insert a small portion of code at the start of their application, as follows:

  • CMyApp::CMyApp
  • {
    • /* Initialise all SDK modules required */
    • IwGxInit();
    • IwGraphicsInit();
    • IwAnimInit();
    • /* Register all application classes with the class factory */
    • IW_CLASS_REGISTER(MyClassA);
    • IW_CLASS_REGISTER(MyClassB);
    • /* Initialise anything else the application might need in order to correctly build binary resources from input assets */
    • /* Only after we have done these 3 things should we insert the required lines, as follows: */
    • #ifdef IW_DEBUG
      • if (IwGetResManager()->BuildResources())
      • return;
    • #endif
    • /* Rest of the application here... */
    • /* Terminate all SDK modules */
    • IwAnimTerminate();
    • IwGraphicsTerminate();
    • IwGxTerminate();
  • }

Once we have made a Win32 Debug build of the application, organised in this way, it is possible for Airplay Studio Director to launch the Debug build and instruct it to build specific GROUP.BIN binary files. The GROUP.BIN binary files can then be taken by the Airplay Studio Director and optimized.

Note: For information on how binary files can be edited using the Airplay Studio Director, see the "Archiving" section of the "Airplay Studio Director" chapter in the 'Airplay Tools Reference'.


Airplay API Reference: Advanced - Controlling How Group Binaries are Built

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Advanced - Controlling How Group Binaries are Built >

Advanced - Controlling How Group Binaries are Built

By default, a GROUP.BIN file will contain serialised versions of all the resources listed in the GROUP text file (with the exception of any child groups, which have their own GROUP.BIN files).

This is the case even if a named resource already exists in memory when the GROUP file is loaded. For example, consider the following:

Text file 'monstershared.group'

  • CIwResGroup
  • {
    • name "MonsterShared"
    • shared true
    • "./monstershared/sfx/monster_die.wav"
  • }

Text file 'monster1.group'

  • CIwResGroup
  • {
    • name "Monster1"
    • "./monster1/models/monster1.geo"
    • "./monster1/sfx/monster1_attack.wav"
    • "./monstershared/sfx/monster_die.wav"
  • }

Load both groups:

  • IwGetResManager()->LoadGroup("monstershared.group");
  • IwGetResManager()->LoadGroup("monster1.group");

In BUILD mode, when 'monster1.group' is loaded, by default it will still construct an application object for 'monster_die.wav' and serialise it to 'monster1.group.bin', even though an application object of that type and name already exists in a shared group. The group is then destroyed and loaded back in from the binary version.

However, when loading back in from the binary version, the resource manager checks (for each resource) to see if a resource of the same type and name already exists. It will find the one in the 'MonsterShared' group, because that group is shared. Therefore, when loading 'monster1.group.bin', it will skip the binary data of the application object 'monster_die.wav', and a corresponding application object will not be created or added to the 'Monster1' group. Of course, a search within that group for a resource named 'monster_die' of the given type will still succeed, because it will find the resource in the shared group.

To summarise: by default, the binary version of a group always contains all the resources listed in the GROUP file (with the exception of any child groups); however, when loading binary versions back into memory, we avoid loading binary resources into memory if an equivalent exists on the search path.

Optimisation of the Group binaries is discussed in the following section:

  • Reducing Binary Size


Airplay API Reference: Reducing Binary Size

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Advanced - Controlling How Group Binaries are Built > Reducing Binary Size >

Reducing Binary Size

The user can potentially reduce the size of the binary group files on disk by telling the resource manager not to write resources to disk if, at the time of writing, they can be found elsewhere on the search path. This is only useful if the user knows that group files are always loaded in a certain order; for example, in the case above, the user must be sure that 'monstershared.group' is always loaded before 'monster1.group'. If this were the case, monster1.group could be amended as follows:

Text file 'monster1.group'

  • CIwResGroup
  • {
    • name "Monster1"
    • omitShared true
    • "./monster1/models/monster1.geo"
    • "./monster1/sfx/monster1_attack.wav"
    • "./monstershared/sfx/monster_die.wav"
  • }

The 'omitShared' attribute is a global resource manager setting that tells the resource manager not to write resources to disk if, at the time of writing, they can be found elsewhere in a shared group. In our example, this will result in 'monster1.group.bin' not containing the serialised version of 'monster_die.wav'.

Another attribute, 'omitChildren' works in a similar way; it is a global resource manager setting that tells the resource manager not to write resources to disk if, at the time of writing, they can be found elsewhere in a child group of the group.

Note: Use 'omitShared' and 'omitChildren' with care - i.e., only when you are certain that group files are always loaded in a set order. Otherwise, you may run into problems where a GROUP.BIN has essentially been built assuming that other groups are loaded, but those groups are in fact not loaded.


Airplay API Reference: Building Multiple Data Sets

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets >

Building Multiple Data Sets

A deployed Airplay application consists of two components:

  • Single S3E binary (usually containing embedded ICF files)
  • Data files

The data files can be of any type, but are generally Derbh archives (DZ files), GROUP.BIN files, and possibly a number of text files. By "data set", we mean the entire set of data files deployed with the application.

This section contains the following subsections:

  • Why Multiple Data Sets?
  • Build Styles
  • The BeatToy Example
  • Building Resources Using the sw Style
  • Building Resources Using the gles1 Style
  • Building Resources Using the pvrtc Style
  • Specifying the Build Style
  • Creating Derbh Archives from Multiple Data Sets
  • Building a Data Set Optimised for a Specified Hardware Platform
  • Failing to Specify a Build Style
  • Interacting with build styles in custom types


Airplay API Reference: Why Multiple Data Sets?

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Why Multiple Data Sets? >

Why Multiple Data Sets?

There are various situations in which the developer might want to build multiple data sets:

  • Optimise a data set for devices with low-powered CPU, and no GPU.
  • Optimise a data set for devices with high-powered CPU, and no GPU.
  • Optimise a data set generically for devices with some GPU.
  • Optimise a data set for devices with a specific GPU.
  • Optimise a data set for devices with abnormally high screen resolutions.
  • Create a "demo" build of the application, which perhaps contains a limited number of data files.
  • Make minor changes, for example changing a splash screen as dictated by a publisher or operator.
  • Combinations of the above, and other similar situations.


Airplay API Reference: Build Styles

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Build Styles >

Build Styles

The deployed application always needs an entire data set. However, when building multiple data sets, it may be that only a few files vary between sets.

IwResManager provides the concept of "build styles", which provide a simple way of building entire data sets by specifying only the files which vary between sets.

The system works as follows:

  • IwResManagerInit() checks for the existence of the file "resbuildstyles.itx" in the root application data folder.
  • If the user wishes to build multiple data sets, they should specify multiple named "build styles" within this file.
  • Each build style can specify multiple prefix strings to add to data file pathnames. These prefix strings point the resource manager to alternative folders which can be searched for alternative data files. If an alternative data file is found, it is used; otherwise, the default data file is used.
  • Within app.icf, the user can specify a named build style to use when building resources.

A set of standard build styles are supported for simply building a single data set conditioned for specific rendering targets. These can be used without a resbuildstyle.itx. They are:

  • sw build assets for the Airplay software renderer.
  • gles1 build assets for OpenGL ES targets without texture compression.
  • gles1-pvrtc build assets for OpenGL ES targets with PVRTC texture compression. Supported on Imagination MBX/SGX-based devices like the Apple iPhone and the Nokia N95.
  • gles1-atitc build assets for OpenGL ES targets with ATITC texture compression. Supported on ATI/Qualcomm Imageon based devices like the MSM7200 and MSM7500 chipsets included in many Windows Mobile and Android devices.
  • gles2-etc build assets for OpenGL ES 2.x targets with ETC texture compression. Supported on some OpenGL ES 2.x devices.


Airplay API Reference: The BeatToy Example

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > The BeatToy Example >

The BeatToy Example

To understand this in more detail, let's look at the BeatToy game example. The data folders are set up as follows:

  • beattoy/data
  • beattoy/data/data-low
  • beattoy/data/data-medium
  • beattoy/data/data-high

Note also that beattoy.mkb specifies beattoy/data as the root data folder for all data files read by the application:

  • options
  • {
    • s3e-data-dir="beattoy/data"
  • }

Additionally, beattoy/data/resbuildstyles.itx looks like this:

  • CIwResBuildStyle
  • {
    • name "sw"
    • addReadPrefix "data-low"
  • }
  • CIwResBuildStyle
  • {
    • name "gles1"
    • addReadPrefix "data-medium"
    • addReadPrefix "data-low"
    • platform "GLES1"
  • }
  • CIwResBuildStyle
  • {
    • name "pvrtc"
    • addReadPrefix "data-high"
    • addReadPrefix "data-medium"
    • addReadPrefix "data-low"
    • platform "GLES1"
    • textureFormat "PVRTC_4"
  • }

When the application code calls IwResManagerInit() (in the case of BeatToy, implicitly through IwGraphicsInit()), "resbuildstyles.itx" is parsed, resulting in the creation of three CIwResBuildStyle objects (i.e. three build styles).

Let's look at the three build styles in turn.


Airplay API Reference: Building Resources Using the sw Style

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Building Resources Using the sw Style >

Building Resources Using the sw Style

The first style is named "sw", and specifies a single "read prefix". A "read prefix" is a pathname prefix which the resource manager will use when opening a file for reading, before searching the unprefixed pathname.

For example, one of the first data files the application reads is "fixed.group", as follows:

    IwGetResManager()->LoadGroup("fixed/fixed.group");

If using the "sw" build style, and building resources, the resource manager will not immediately try to open "fixed/fixed.group". Instead, it will first look for the file "beattoy/data/data-low/fixed/fixed.group". In this case, the file exists, so it is opened for reading.

When building resources, the resource manager will now need to write the file "fixed.group.bin" to disk. If using the "sw" build style, the resource manager automatically uses the build style name to create a top-level folder within which all files are written. The folder is named "data-<build style name>". So the resource manager will write "fixed.group.bin" to "beattoy/data-ram/data-sw/fixed/fixed.group.bin".

Now let's look at another data file loaded by the application:

  • CbeatToyConfig* config = (CBeatToyConfig*)IwGetTextParserITX()->ParseFile("config.itx",false);

Again, the resource manager first looks for "beattoy/data/data-sw/config.itx". However, this file does not exist. So it then looks in the default location, "beattoy/data/config.itx". The file exists and is loaded. Note that parsing this file does not result in any files being written.

In this way, running the application in "build resources" mode results in some files being written to "beattoy/data-ram/data-sw" (i.e. those files which are usually written by the resource building process, and where the source asset was located using the "data-sw" prefix).

Loading Resources Using the sw Style

Now let's consider what happens if we still specify the "sw" build style, but we run the application in "load resources" mode (i.e. it does not build the resources).

Consider what happens when loading the same resources:

  • IwGetResManager()->LoadGroup("fixed/fixed.group");

Remember that when loading files, Airplay System always checks the s3e data directory first, and will then check the corresponding "-ram" directory. So in this case, the resource manager first looks for "beattoy/data/data-sw/fixed/fixed.group.bin". This file does not exist, so it checks "beattoy/data-ram/data-sw/fixed/fixed.group.bin". This file exists and is loaded.

Now the other file:

  • CbeatToyConfig* config = (CBeatToyConfig*)IwGetTextParserITX()->ParseFile("config.itx",false);

The resource manager first looks for "beattoy/data/data-sw/config.itx". This file does not exist, and neither does "beattoy/data-ram/data-sw/config.itx". So the resource manager reverts to the unprefixed path, and looks for "beattoy/data/config.itx". This file exists and is loaded.

In this way, running the application in "load resources" mode results in some files being loaded from "beattoy/data-ram/data-sw", and some loaded from "beattoy/data".


Airplay API Reference: Building Resources Using the gles1 Style

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Building Resources Using the gles1 Style >

Building Resources Using the gles1 Style

The second style is named "gles1", and specifies two read prefixes; "data-medium" and "data-low". This means that whenever opening a file for reading, the resource manager will search using the prefix "data-medium", before searching using the prefix "data-low", before searching for the unprefixed filename.

Notice how "beattoy/data/data-medium" contains only a small number of files. Running the application in "build resources" mode results in every written file going to "beattoy/data-ram/data-gles1". In this way an entire set of GL conditioned binaries is written to this directory.

Source assets would also be used from "beattoy/data/data-gles1" if they exist.


Airplay API Reference: Building Resources Using the 2430 Style

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Building Resources Using the 2430 Style >

Building Resources Using the 2430 Style

The second style is named "pvrtc", and specifies three read prefixes; "data-high", "data-medium" and "data-low". This means that whenever opening a file for reading, the resource manager will search using the prefix "data-high", before searching using the prefix "data-medium", before searching using the prefix "data-low", before searching for the unprefixed filename.

Notice how "beattoy/data/data-high" contains only a very small number of files. Running the application in "build resources" mode results in every written file going to "beattoy/data-ram/data-pvrtc". In this way an entire set of PVRTC conditioned binaries is written to this directory.

Source assets will also be used from "beattoy/data/data-2430" if they exist.

The pvrtc build style also specifies "platform" and "textureFormat" attributes.

  • see later for a description of this.


Airplay API Reference: Specifying the Build Style

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Specifying the Build Style >

Specifying the Build Style

To specify which build style to use when running the Win32 Debug configuration, enter the following in the "app.icf" file:

  • [RESMANAGER]
  • ResBuildStyle=<build style name>

For example:

  • [RESMANAGER]
  • ResBuildStyle=gles1

The named style must be specified within resbuildstyles.itx or be one of the standard build styles. The resource manager will then build all resources using the specified style.

To build multiple data sets, change the "ResBuildStyle" setting and run the application multiple times.


Airplay API Reference: Creating Derbh Archives from Multiple Data Sets

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Creating Derbh Archives from Multiple Data Sets >

Creating Derbh Archives from Multiple Data Sets

Currently, Airplay SDK does not provide a way to build multiple derbh archives, from multiple data sets, using a single DCL script. This functionality will be provided in a future release of the SDK.

For now, it is necessary to create a separate DCL script for each data set.

For example, the DCL script to build the BeatToy Derbh archive from the "sw" data set is at "beattoy/data/derbhscripts/beattoy-sw.dcl".

Note how, for the "sw" data set, the base directories for the Derbh compressor are set up as follows:

  • basedir ..\data-low
  • basedir ..
  • basedir ..\..\data-ram\data-sw

The base directories are relative to the DCL script itself, and must specify all paths required for the subsequent list of assets to be found.

The DCL files for the other two data sets differ only in the list of base directories they need to specify. So, for "beattoy/data/derbhscripts/beattoy-gles1.dcl":

  • basedir ..\data-medium
  • basedir ..\data-low
  • basedir ..
  • basedir ..\..\data-ram\data-gles1

...and for "beattoy/data/derbhscripts/beattoy-pvrtc.dcl":

  • basedir ..\data-high
  • basedir ..\data-medium
  • basedir ..\data-low
  • basedir ..
  • basedir ..\..\data-ram\data-pvrtc

If the win32 build has been run in the appropriate build style to generate the binaries, running DZip over any of these scripts will create an appropriately named "beattoy/data/resources-buildstyle.dz" archive using a different input data set.

Note that the paths in the data directory match the search paths of the build style. This is so any specialised assets (like itx files) that do not have binary versions are found first.


Airplay API Reference: Building a Data Set Optimised for a Specified Hardware Platform

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Building a Data Set Optimised for a Specified Hardware Platform >

Building a Data Set Optimised for a Specified Hardware Platform

When designing multiple data sets, many things are under the user's control; size and depth of textures, polygon density of models, number of bones in animation skeletons, etc. The user can choose to create multiple "levels of detail" of such assets, as appropriate for each data set.

However, there are other asset-conditioning parameters that are more obscure and which Airplay may not expose to the user. For example; models can be optimised for software rasterisation (the default is for models to be built to support both SW and HW rasterisation). Models can further be optimised for particular graphics hardware; for example, certain GPUs are bandwidth-limited, so are better fed with 16-bit geometry streams, whereas others incur a driver overhead if not fed 32-bit geometry streams.

A build style can specify a particular platform to optimise for, using the "platform" attribute. For example:

  • platform "IMG_MBX_VGP"

In this example, the build style will optimise the data sets for devices which have GPU designs from Imagination Technologies, featuring MBX (hardware tile-based rasterisation) and VGP (hardware transform/lighting). For example, all textures which meet certain criteria will be compressed using Imagination's PVRTC texture compression format.

The platforms currently recognised by Airplay are:

  • SW - Airplay software renderer - devices without HW acceleration
  • GLES1 - Generic OpenGL ES 1.x rasterisation - general devices with HW acceleration
  • IMG_MBX - Imagination Technologies GPU - MBX without VGP (e.g. Apple iPhone)
  • IMG_MBX_VGP - Imagination Technologies GPU - MBX with VGP (e.g. Nokia N95)
  • ATI_IMAGEON - ATI Imageon GPU - Qualcomm MSM 7x00 (e.g. HTC Hero series)
  • NVIDIA_GOFORCE - Nvidia GoForce GPU
  • ARM_MALI - ARM Mali GPU

Platform optimisations are realised using the standard resource template system (see "Resource Templates"). Generally the platform optimisation template settings are different from the template settings under user control. Changing resource template settings within GROUP files will not destroy the platform optimisations set up by the build style.

The platform optimisations which are currently implemented are as follows:

  • SW - Optimise models for SW rasterisation. These models CANNOT then be rendered using HW rasterisation.
  • GLES1 - Build "default" models. These will be rendered through the standard IwGx API, and can therefore be rendered in both SW and HW rasterisation.
  • IMG_MBX - Same as GLES1, but use PVRTC texture compression on all textures which meet certain criteria.
  • IMG_MBX_VGP - Same as IMG_MBX_VGP.
  • ATI_IMAGEON - Currently same as GLES1, but use ATITC texture compression on all textures which meet certain criteria.
  • NVIDIA_GOFORCE - Currently same as GLES1.
  • ARM_MALI - Currently same as GLES1.

As you can see most platform settings only control texture compression format. Typically, stream type coercion is done on load.

Build style platforms can also be decomposed and specified as a geometry conditioning parameter and a default texture format. For example:

  • platform "IMG_MBX"
Is equivalent to:
  • platform "GLES1"
  • textureFormat "PVRTC_4"


Airplay API Reference: Failing to Specify a Build Style

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Failing to Specify a Build Style >

Failing to Specify a Build Style

It is perfectly legal NOT to use build styles. In this case (i.e., where no build styles have been defined), data files will of course be loaded from their default locations. IwResManager will use the standard build styles based on the icf [GX] Rasterisation setting.

  • If IwGx is not initialised IwResManager will use the standard build style "sw".
  • If IwGx is initialised to support SW rendering IwResManager will build resources optimised for the SW platform using build style "sw".
  • Otherwise IwResManager will build resources optimised for standard OpenGL ES platforms using the standard build style "gles1".


Airplay API Reference: Interacting with Build Styles in Custom Types

Airplay API Reference > IwResManager API Documentation > IwResManager API Overview > Building Multiple Data Sets > Interacting with Build Styles in Custom Types >

Interacting with Build Styles in Custom Types

Custom types may also want to interact with build styles. If files are opened using IwFileOpenPrefixed the current build style search paths will be searched to find the file.

It is also legal (and can be convenient) to switch build styles while loading. This can be useful if some assets are shared between builds and are expensive to generate, for example visibility information:

  • //Load models from current "platform" build style
  • IwGetResManager()->LoadGroup("models.group");
  • //Remember current build style
  • CIwStringL currStyle = IwGetResManager()->GetBuildStyleCurrName();
  • //Set generic build style to load generic assets
  • IwGetResManager()->SetBuildStyle("generic");
  • //Load visibility information from "generic" build style
  • IwGetResManager()->LoadGroup("visibility.group");
  • //Switch back to "platform" build style
  • IwGetResManager()->SetBuildStyle(defaultStyle.c_str());


Airplay API Reference: IwResManager API Reference

Airplay API Reference > IwResManager API Documentation > IwResManager API Reference >

IwResManager API Reference

Modules

IwResManager Groups
IwResManager Resource Handlers
Initialisation and Termination
Resource Manager Singleton

Data Structures

struct | _IwGxBinaryBlockHashedFn
struct | _IwGxBinaryHeader
class | CIwResHandlerGROUP
class | CIwResHandlerImage
class | CIwResHandlerITX
class | CIwResTemplateGROUP
class | CIwResTemplateImage

Defines

#define | IW_GX_RESTYPE_MATERIAL "CIwMaterial"
#define | IW_GX_RESTYPE_TEXTURE "CIwTexture"
#define | IW_GX_RESTYPE_VERTEXSHADER "CIwVertexShader"

Enumerations

enum | IwGxResManagerFlags

Define Documentation

#define IW_GX_RESTYPE_MATERIAL "CIwMaterial"

Resource type string for materials. Any resource of type CIwMaterial should be addressed using this type. When parsing GROUP files, a text file of type MTL contains blocks of type CIwMaterial {...}, which result in the creation of objects of class CIwMaterial.

#define IW_GX_RESTYPE_TEXTURE "CIwTexture"

Resource type string for textures. Any resource of type CIwTexture should be addressed using this type. When parsing GROUP files, a file of type BMP, GIF, PNG or TGA results in the creation of an object of class CIwTexture.

Required Header Files
IwResManagerClass.h

#define IW_GX_RESTYPE_VERTEXSHADER "CIwVertexShader"

Resource type string for vertex shaders. Any resource of type CIwVertexShader should be addressed using this type.

Required Header Files
IwResManagerClass.h

Enumeration Type Documentation

enum IwGxResManagerFlags

Resource search input flags. Use these to modify search logic from the default behaviour. For more information on modifying search logic, see Resource Searches.

Required Header Files
IwResManagerClass.h
Enumerator:
IW_RES_PERMIT_NULL_F | If a resource is not found, return NULL rather than asserting.
IW_RES_SEARCH_ALL_F | Search all groups, rather than just the specified group, shared groups and child groups.
IW_RES_IGNORE_SHARED_F | Do not search shared groups.
IW_RES_IGNORE_CHILDREN_F | Do not search any child groups of the specified group.


Airplay API Reference: IwResManager Groups

Airplay API Reference > IwResManager API Documentation > IwResManager API Reference > IwResManager Groups >

IwResManager Groups
[IwResManager API Reference]

Data Structures

class | CIwResGroup
class | CIwResGroupBuildData
class | CIwResList

Detailed Description

Note:
For more information on Groups, see the Groups section of the IwResManager API Documentation


Airplay API Reference: IwResManager Resource Handlers

Airplay API Reference > IwResManager API Documentation > IwResManager API Reference > IwResManager Resource Handlers >

IwResManager Resource Handlers
[IwResManager API Reference]

Data Structures

class | CIwResHandler
class | CIwResTemplate

Detailed Description

Note:
For more information on Resource Handlers, see the Resource Handlers section of the IwResManager API Documentation


Airplay API Reference: Initialisation and Termination

Airplay API Reference > IwResManager API Documentation > IwResManager API Reference > Initialisation and Termination >

Initialisation and Termination
[IwResManager API Reference]

Functions

void | IwResManagerInit ()
void | IwResManagerTerminate ()

Detailed Description

Initialisation and termination of the IwResManager module.

Note:
For more information on initialisation and termination, see the Creating the Resource Manager section of the IwResManager API Documentation.

Function Documentation

void IwResManagerInit ( )

Initialises all core functionality for IwResManager. This function must be called before IwResManager is used.

See also:
IwResManagerTerminate
Required Header Files
IwResManager.h

void IwResManagerTerminate ( )

Shuts down IwResManager and frees all memory.

See also:
IwResManagerInit
Required Header Files
IwResManagerClass.h


Airplay API Reference: Resource Manager Singleton

Airplay API Reference > IwResManager API Documentation > IwResManager API Reference > Resource Manager Singleton >

Resource Manager Singleton
[IwResManager API Reference]

Data Structures

class CIwResManager

Functions

CIwResManager * IwGetResManager ()

Detailed Description

Note:
For more information on the Resource Manager Singleton, see the Resource Manager Modes section of the IwResManager API Documentation.

Function Documentation

CIwResManager* IwGetResManager ( ) [inline]

Get the IwResManager singleton.

Returns:
Pointer to the IwResManager singleton.

void IwResolveManagedHash | ( | void * | pptr,
 |  | const char * | resType,
 |  | uint32 | flags = 0
 | ) |  |

Resolve managed ptr as hash.


Airplay API Reference: IwResManager Examples

Airplay API Reference > IwResManager API Documentation > IwResManager Examples >

IwResManager Examples

This document provides a set of examples that illustrate how to use the functionality contained within IwResManager. Each example uses the functionality specific to IwResManager, and endeavours to illustrate the capabilities of some of the IwResManager modules.

The following examples are contained within this section:

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


Airplay API Reference: IwResManager Groups Example

Airplay API Reference > IwResManager API Documentation > IwResManager Examples > IwResManager Groups Example >

IwResManager Groups Example

The following example demonstrates the loading and destroying of resource groups (including child groups).

The main classes used to achieve this are:

  • CIwResManager

  • CIwResGroup

The main functions used to achieve this are:

  • CIwResManager::LoadGroup()

  • CIwResManager::GetCurrentGroup()

  • CIwResManager::GetGroupNamed()

  • CIwResManager::DestroyGroup()

  • CIwResGroup::GetOwner()

The example instantiates the CIwResManager singleton using IwResManagerInit(). Both group0 and group1 are then loaded using the code: IwGetResManager()->LoadGroup("group0.group"). The group0 group file is illustrated below:

 CIwResGroup
 {
    name    "group0"

    # textures
    "textures/testCard_4bit.bmp"
    "textures/testCard_8bit.bmp"

    # child group
    "group1.group"
 }

Group0 has group1 as a child so this is loaded automatically and a pointer to group1 is retrieved using IwGetResManager()->GetGroupNamed("group1").

The loaded group names are output to screen and their relationships are output also.

On shutdown the IwResManagerTerminate is called which destroys all the loaded groups.

The following graphics illustrates the example output.

Note:
For more information on groups, see the Groups section in the IwResManager API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwResManager.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// array of CIwResGroup pointers used for groups retrieved from the CIwResManager singleton
CIwResGroup *s_Groups[2];

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise GX
    IwGxInit();

    // create the CIwResManager singleton
    IwResManagerInit();

    // load group0 (a resource group);
    // since group0 has group1 as a child, group1 will get loaded automatically
    IwGetResManager()->LoadGroup("group0.group");

    // groups can be searched for by name
    s_Groups[1] = IwGetResManager()->GetGroupNamed("group1");

    // CIwResManager::GetCurrentGroup gives the most recently loaded group
    // (this can also be manually set via CIwResManager::SetCurrentGroup);
    // the following gives the same as IwGetResManager()->GetGroupNamed("group0")
    s_Groups[0] = IwGetResManager()->GetCurrentGroup();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // groups can be destroyed by name;
    // group1 is also destroyed, in this case, by this call to DestroyGroup since it is a child of group0
    // (note that groups are destroyed automatically when the CIwResManager singleton is destroyed)
    IwGetResManager()->DestroyGroup("group0");

    // destroy the CIwResManager singleton. Note that this actually destroys all groups, so the above line
    // isn't strictly necessary
    IwResManagerTerminate();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // no lighting
    IwGxLightingOff();

    char display[0x100] = "";
    char buffer[0x80];

    // display some trivia about group0 and group1
    for (int32 i = 0; i < 2; i++)
    {
#ifdef IW_DEBUG
        // Note that CIwManaged::DebugGetName() only returns anything useful in Debug builds
        sprintf(buffer, "Group name '%s' : child of group name '%s'\n",
                s_Groups[i]->DebugGetName(),
                s_Groups[i]->GetOwner() ? s_Groups[i]->GetOwner()->DebugGetName() : "<none>");
#else
        sprintf(buffer, "Group %ld hash is 0x%lx\n", i, s_Groups[i]->m_Hash);
#endif
        strcat(display, buffer);
    }

    IwGxPrintString(0, 50, "Using Resource Groups");
    IwGxPrintString(0, 80, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwResManager Resource Search Example

Airplay API Reference > IwResManager API Documentation > IwResManager Examples > IwResManager Resource Search Example >

IwResManager Resource Search Example

The following example demonstrates how to use the IwResManager search functionality. The example searches through resource groups for resources.

The main classes used to achieve this are:

  • CIwResManager

  • CIwResGroup

The main functions used to achieve this are:

  • CIwResManager::LoadGroup()

  • CIwResManager::GetGroupNamed()

  • CIwResManager::GetResNamed()

  • CIwResGroup::GetResNamed()

The example loads groups: group0, group1 and group2. The GetResNamed() function is then used to search for a variety of resources by searching through an individual group or by searching through all the loaded groups. The names of all searched for files and the groups in which they were found are then output to the surface.

The following graphics illustrates the example output.

Note:
For more information on searching groups, see the Resource Searches section in the IwResManager API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwResManager.h"
#include "IwTexture.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // create the CIwResManager singleton
    IwResManagerInit();

    // load group0; since group0 has group1 as a child, group1 will get loaded automatically
    IwGetResManager()->LoadGroup("group0.group");

    // load group2 (a shared group)
    IwGetResManager()->LoadGroup("group2.group");
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // destroy the CIwResManager singleton
    IwResManagerTerminate();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // no lighting
    IwGxLightingOff();

    char display[1000], buffer[100];
    display[0] = 0;

    // do some searching and display some trivia about assets found in groups group0, group1 and group2

    bool        bResult = false;
    CIwTexture *texture = NULL;

    // get out group0
    CIwResGroup *group = IwGetResManager()->GetGroupNamed("group0");

    // find the CIwTexture resource named "testCard_4bit", searching in group0
    texture = (CIwTexture *)group->GetResNamed("testCard_4bit", IW_GX_RESTYPE_TEXTURE);
    bResult = (texture != NULL);
    if (bResult)
    {
        sprintf(buffer, "%s found in %s\n", texture->DebugGetName(), group->DebugGetName());
        strcat(display, buffer);
    }

    // if you don't know which group to search for a resource, you can use CIwResManager::GetResNamed with the
    // IW_RES_SEARCH_ALL_F flag set - this effectively applies CIwResGroup::GetResNamed to all groups
    // (this function, of course, is less efficient then searching only the group you know the resource is contained in)
    texture = (CIwTexture *)IwGetResManager()->GetResNamed("testCard_8bit", IW_GX_RESTYPE_TEXTURE, IW_RES_SEARCH_ALL_F);
    bResult &= (texture != NULL);
    if (bResult)
    {
        sprintf(buffer, "%s found using global search\n", texture->DebugGetName());
        strcat(display, buffer);
    }

    // the following resource is found by searching in group0 because the search will be extended to group1,
    // seeing as group1 is a child of group0
    texture = (CIwTexture *)group->GetResNamed("testCard_16bit", IW_GX_RESTYPE_TEXTURE);
    bResult &= (texture != NULL);
    if (bResult)
    {
        sprintf(buffer, "%s found searching children of %s\n", texture->DebugGetName(), group->DebugGetName());
        strcat(display, buffer);
    }

    // the following resource is found by searching in group0 because the resource is contained in
    // group2 - a shared group, i.e. ANY resource search which doesn't explicitly ignore shared
    // resources (IW_RES_IGNORE_SHARED_F) will consider this group.
    texture = (CIwTexture *)group->GetResNamed("testTexture", IW_GX_RESTYPE_TEXTURE);
    bResult &= (texture != NULL);
    if (bResult)
    {
        sprintf(buffer, "%s found searching shared groups\n", texture->DebugGetName());
        strcat(display, buffer);
    }

    IwGxPrintString(0, 40, display);

    if (bResult)
    {
        IwGxPrintString(0, 110, "All textures successfully located from their Resource Groups!");
    }

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwResManager Templates Example

Airplay API Reference > IwResManager API Documentation > IwResManager Examples > IwResManager Templates Example >

IwResManager Templates Example

The following example demonstrates how to use the IwResManager Template functionality. The example uses resource templates to condition textures.

The main classes used to achieve this are:

  • CIwResManager

  • CIwResGroup

The main functions used to achieve this are:

  • CIwResManager::LoadGroup()

  • CIwTextParserITX::ParseFile()

  • CIwResManager::GetGroupNamed()

  • CIwResGroup::GetResNamed()

The resource template file templates.itx and resource group group3 are loaded. When the template file is parsed using IwGetTextParserITX()->ParseFile("templates.itx"), the template "palette4" is applied to one of the two textures referenced in group3, as detailed in group3.group. The template file is illustrated below:

 CIwResTemplateImage
 {
    name        "palette4"

    # convert the image format (for SW rasterisation) to PALETTE4_ABGR_1555
    formatSW    "PALETTE4_ABGR_1555"

    # convert the image format (for HW rasterisation) to PALETTE4_RGBA_4444
    formatHW    "PALETTE4_RGBA_4444"
 }

The formats of the textures are output to the surface to verify the conditioning that has occurred due to the "palette4" template.

The following graphics illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwResManager.h"
#include "IwTexture.h"

// included so that we can load templates.itx (resource templates)
#include "IwTextParserITX.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // create the CIwResManager singleton
    IwResManagerInit();

#ifdef IW_BUILD_RESOURCES
    // load available resource templates by parsing the resource templates file
    IwGetTextParserITX()->ParseFile("templates.itx");
#endif

    // load group3 (a resource group);
    // note: group3 makes mention of a resource template defined in the above-mentioned file -
    // this template will be automatically implemented when the group is loaded (below)
    IwGetResManager()->LoadGroup("group3.group");
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // destroy the CIwResManager singleton
    IwResManagerTerminate();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // no lighting
    IwGxLightingOff();

    char display[1000], buffer[100];
    display[0] = 0;

    // get out group3
    CIwResGroup *group = IwGetResManager()->GetGroupNamed("group3");

    CIwTexture *texture;

    // find the CIwTexture resource named "testCard_8bit";
    // this texture is not loaded within the context of a template, so the format we see will be it's native format
    texture = (CIwTexture *)group->GetResNamed("testCard_8bit", IW_GX_RESTYPE_TEXTURE);
    if (texture)
    {
        sprintf(buffer, "%s has format:\n%s (SW)\n%s (HW)\n\n",
                texture->DebugGetName(),
                CIwImage::g_FormatNames[texture->GetFormatSW()],
                CIwImage::g_FormatNames[texture->GetFormatHW()]);
        strcat(display, buffer);
    }

    // find the CIwTexture resource named "testCard_16bit";
    // this texture is loaded within the context of a template, so the format we see will be the one
    // specified by the template (for SW, PALETTE4_ABGR_1555, and for HW, PALETTE4_RGBA_4444)
    texture = (CIwTexture *)group->GetResNamed("testCard_16bit", IW_GX_RESTYPE_TEXTURE);
    if (texture)
    {
        sprintf(buffer, "%s has format:\n%s (SW)\n%s (HW)\n\n",
                texture->DebugGetName(),
                CIwImage::g_FormatNames[texture->GetFormatSW()],
                CIwImage::g_FormatNames[texture->GetFormatHW()]);
        strcat(display, buffer);
    }

    IwGxPrintString(0,  50, "Using resource templates");
    IwGxPrintString(0,  80, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: IwResManager Advanced Resource Search Example

Airplay API Reference > IwResManager API Documentation > IwResManager Examples > IwResManager Advanced Resource Search Example >

IwResManager Advanced Resource Search Example

The following example demonstrates how to use the IwResManager search functionality. The example controls the way binaries are serialised out using the OMIT_SHARED_F (and OMIT_CHILDREN_F) CIwResManager flags.

The main classes used to achieve this are:

  • CIwResManager

  • CIwResGroup

The main functions used to achieve this are:

  • CIwResManager::LoadGroup
  • CIwResManager::DestroyGroup
  • CIwResManager::GetCurrentGroup
  • CIwResGroup::GetResNamed

The example loads group2 and group4 without setting OMIT_SHARED_F using IwGetResManager()->m_Flags &;= ~CIwResManagerOMIT_SHARED_F. Loading without OMIT_SHARED_F means that groups subsequently loaded will include resources, even if they are available in a shared group previously loaded.

The testTexture (testTexture.bmp resides in group2 as well as in group4) is searched for in group4 with IW_RES_IGNORE_SHARED_F set (i.e., don't consider group2 in our search). In this search CIwResManager searches only in group4 and finds testTexture since it is included due to OMIT_SHARED_F is not set.The example then reloads group4 with OMIT_SHARED_F set using IwGetResManager()->m_Flags |= CIwResManager::OMIT_SHARED_F. Loading with OMIT_SHARED_F means that groups subsequently loaded will not include resources should they be available in a shared group previously loaded.The testTexture is searched for in group4 with IW_RES_IGNORE_SHARED_F set. CIwResManager does NOT find testTexture since testTexture was excluded from group4 due to OMIT_SHARED_F being set.

The following graphics illustrates the example output.

Note:
For more information on searching groups, see the Resource Searches section in the IwResManager API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwResManager.h"
#include "IwTexture.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // initialise GX
    IwGxInit();

    // create the CIwResManager singleton
    IwResManagerInit();
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // destroy the CIwResManager singleton
    IwResManagerTerminate();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // no lighting
    IwGxLightingOff();

    char display[1000], buffer[100];
    display[0] = 0;

    CIwTexture *texture;
    CIwResGroup *group;

    // load group2 (shared); group2 contains testTexture.bmp
    IwGetResManager()->LoadGroup("group2.group");

    // unset OMIT_SHARED_F (this is the default behaviour and is explicitly done here for completeness);
    // this means that groups subsequently loaded will include resources, even if they are available in
    // a shared group previously loaded
    IwGetResManager()->m_Flags &= ~CIwResManager::OMIT_SHARED_F;
    sprintf(buffer, "OMIT_SHARED_F unset\n");
    strcat(display, buffer);

    // load group4;
    // group4 contains textTexture.bmp too and since the OMIT_SHARED_F flag is not set, group4 will contain testTexture.bmp
    IwGetResManager()->LoadGroup("group4.group");

    // get group4
    group = IwGetResManager()->GetCurrentGroup();

    // try to find the CIwTexture resource named "testTexture";
    // the resource manager will find testTexture (despite the fact that we are choosing to ignore shared
    // groups in the search) because OMIT_SHARED_F is not set and testTexture resides in group4
    // (note that all searches in this example use IW_RES_PERMIT_NULL_F since we need to accept empty search results)
    texture = (CIwTexture *)group->GetResNamed("testTexture", IW_GX_RESTYPE_TEXTURE, IW_RES_PERMIT_NULL_F | IW_RES_IGNORE_SHARED_F);
    if (texture)
        sprintf(buffer, "%s found\n", texture->DebugGetName());
    else
        sprintf(buffer, "testTexture NOT found\n");

    strcat(display, buffer);

    // now we'll destroy group4 and reload it with OMIT_SHARED_F set

    // destroy group4
    IwGetResManager()->DestroyGroup("group4");

    // set OMIT_SHARED_F; this means that groups subsequently loaded will not include resources should they be
    // available in a shared group previously loaded
    IwGetResManager()->m_Flags |= CIwResManager::OMIT_SHARED_F;
    sprintf(buffer, "OMIT_SHARED_F set\n");
    strcat(display, buffer);

    // load in group4 again
    IwGetResManager()->LoadGroup("group4.group");
    group = IwGetResManager()->GetCurrentGroup();

    // try to find the CIwTexture resource named "testTexture";
    // this time the resource manager does NOT find testTexture since it won't search within the shared
    // group (group2) due to IW_RES_IGNORE_SHARED_F being set, and it won't find testTexture within group4
    // since group4 was loaded with OMIT_SHARED_F set
    texture = (CIwTexture *)group->GetResNamed("testTexture", IW_GX_RESTYPE_TEXTURE, IW_RES_PERMIT_NULL_F | IW_RES_IGNORE_SHARED_F);
    if (texture)
        sprintf(buffer, "%s found\n", texture->DebugGetName());
    else
        sprintf(buffer, "testTexture NOT found\n");

    strcat(display, buffer);

    // destroy groups since they will be reloaded next time ExampleRender() is called
    IwGetResManager()->DestroyGroup("group2");
    IwGetResManager()->DestroyGroup("group4");

    //-----------------------------------------------------------------------------
    // the OMIT_CHILDREN_F flag operates in a similar fashion to the OMIT_SHARED_F flag:
    // when set, a resource is not included in a group if the resource exists in one
    // of the child (c.f. shared) groups; as a result, it is not demonstrated here
    //-----------------------------------------------------------------------------

    IwGxPrintString(0,  50, "Using resource searches");
    IwGxPrintString(0,  80, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------


Airplay API Reference: IwResManager Resource Handler Example

Airplay API Reference > IwResManager API Documentation > IwResManager Examples > IwResManager Resource Handler Example >

IwResManager Resource Handler Example

The following example demonstrates how to use the IwResManager resource handler functionality. The example creates a custom file type and uses the resource handler functionality to understand the file.

The main classes used to achieve this are:

  • CIwResHandler
  • CIwResManager
  • CIwManaged

The main functions used to achieve this are:

  • CIwResManager::AddHandler()
  • CIwResManager::LoadGroup()
  • CIwResHandler::Build()
  • CIwManaged::ParseAttribute()
  • CIwManaged::ParseClose()

The example loads in a group (group5) which references a file of type .mad. The resource manager searches for a handler that understands that file type and this is CResHandlerMAD. The CResHandlerMAD::Build() function parses the .mad file using the ITX text parser (this is a common implementation of resource handlers). The contents of the .mad file are as follows:

 CMad
 {
    name    "haggis"
    random  42
 }

The .mad file contains an object of type CMad, named "haggis", which is parsed and added to the group in context (group5). The CMad object is then retrieved from group5 using a search and output to the screen.

The following graphics illustrates the example output.

Note:
For more information on resource handlers, see the Resource Handlers module overview in the IwResManager API Documentation.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwResManager.h"

// resource handler for parsing .mad files
#include "ResHandlerMAD.h"

// for screen rendering
#include "IwGx.h"
#include "IwGxPrint.h"

// definition of CMad
#include "CMad.h"

// define the class factory and name functions for CMad
IW_CLASS_FACTORY(CMad);
IW_MANAGED_IMPLEMENT(CMad);

// pointer to the CMad object in group5
CMad *s_Haggis = NULL;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise GX
    IwGxInit();

    // add CMad to the class factory
    IW_CLASS_REGISTER(CMad);

    // create the CIwResManager singleton
    IwResManagerInit();

#ifdef IW_BUILD_RESOURCES
    // add a CResHandlerMAD object to the resource manager's list of handlers; this means that when the
    // resource manager encounters a file with extension .mad, it will pass that file onto the CResHandlerMAD object
    // NB. This is not required in a non-resource-building build
    IwGetResManager()->AddHandler(new CResHandlerMAD);
#endif

    // load group5; group5 makes reference to a .mad file (which is dealt with by the CResHandlerMAD object)
    IwGetResManager()->LoadGroup("group5.group");

    // search for the CMad object named "haggis" in the current group (group5); this object will exist due to its
    // declaration in the .mad file (parsed by CResHandlerMAD) referenced in group5
    s_Haggis = (CMad *)IwGetResManager()->GetCurrentGroup()->GetResNamed("haggis", "CMad");
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // destroy the CIwResManager singleton
    IwResManagerTerminate();

    // terminate GX
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // no lighting
    IwGxLightingOff();

    // display contents of the CMad object. Note that DebugGetName() returns an empty string in Release builds.
    char display[0x80];
#ifndef IW_DEBUG
    sprintf(display, "name will be an empty string in release builds");
    IwGxPrintString(0, 80, display);
#endif
    sprintf(display, "Loaded .mad file and found CMad obj:\nname = %s\nrandom = %ld", s_Haggis->DebugGetName(), s_Haggis->m_RandomNumber);
    IwGxPrintString(0, 50, "Using Resource Handlers");
    IwGxPrintString(0, 100, display);

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}
//-----------------------------------------------------------------------------

The Resource Handler

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

/*
 * ResHandlerMAD.cpp
 *
 * Resource handler for .mad files
 */
//-----------------------------------------------------------------------------

// project
#include "ResHandlerMAD.h"

// library
#include "s3eFile.h"
#include "CMad.h"

//--------------------------------------------------------------------------------
// CResHandlerMAD
//--------------------------------------------------------------------------------
CResHandlerMAD::CResHandlerMAD() : CIwResHandler("mad", "CMad")
{
    SetName("MAD");
}
//--------------------------------------------------------------------------------
CIwResource *CResHandlerMAD::Build(const CIwStringL& pathname)
{
    // Check that the file exists
    if ( !s3eFileCheckExists( pathname.c_str() ) )
        return NULL;

    // parse the .mad file
    IwGetTextParserITX()->ParseFile(pathname.c_str());

    return NULL;
}
//--------------------------------------------------------------------------------

The CMad class

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
/*
 * CMad.h
 *
 * Completely arbitrary class, used to illustrate resource handling as part of ExampleIwResManager5
 */
//-----------------------------------------------------------------------------

#ifndef CMAD_H
#define CMAD_H

#include "IwResource.h"
#include "IwTextParserITX.h"

//-----------------------------------------------------------------------------
// CMad
//-----------------------------------------------------------------------------
class CMad : public CIwResource
{
public:
    IW_MANAGED_DECLARE(CMad);

    // arbitrary member
    int32   m_RandomNumber;

    // override of CIwManaged::Serialise
    void Serialise()
    {
        CIwManaged::Serialise();

        // serialise the only member
        IwSerialiseInt32(m_RandomNumber);
    }

    // override of CIwManaged::ParseAttribute
    bool ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
    {
        if (!strcmp(pAttrName, "random"))
        // read the value of the next token into m_RandomNumber
            pParser->ReadInt32(&m_RandomNumber);
        else
            return CIwManaged::ParseAttribute(pParser, pAttrName);

        return true;
    }

    // override of CIwManaged::ParseClose
    void ParseClose(CIwTextParserITX* pParser)
    {
        // add to current resource group
        IwGetResManager()->GetCurrentGroup()->AddRes("CMad", this);
    }
};
//-----------------------------------------------------------------------------

#endif


Airplay API Reference: IwGraphics API Documentation

Airplay API Reference > IwGraphics API Documentation >

IwGraphics API Documentation

The IwGraphics documentation contains the following sections:

  • IwGraphics API Overview
  • IwGraphics API Reference
  • IwGraphics Examples


Airplay API Reference: IwGraphics API Overview

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview >

IwGraphics API Overview

IwGraphics is a model-rendering API. It sits on top of the IwGx drawing API, and adds four main functions:

  • Loading of models (meshes) from intermediary text files (GEO files).
  • Building of models, from their raw loaded form, into conditioned run-time objects (CIwModel objects).
  • Serialisation of conditioned run-time models to and from disk.
  • Rendering of models.

It is perfectly possible to create a 3D application without using IwGraphics. The user could perform all their all rasterisation exclusively using S3E functionality, drawing directly to the S3E surface, or the IwGx drawing API. However, the model functionality provided by IwGraphics is very powerful, and once the user is familiar with the API they will benefit from many efficiencies.

To use IwGraphics functionality, you must include "IwGraphics.h" in your source and iwgraphics as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwgraphics
  • }

When using IwGraphics, the following modules do not need to be specified in your project's MKB as they will be implicitly included as subprojects of this module:

  • IwUtil
  • IwGeom
  • IwResManager
  • IwGx

The following subjects are covered within this section:

  • IwGraphics Initialisation and Termination
  • IwGraphics State
  • Model
  • Model Blocks
  • Model Extensions
  • Model Builder
  • IwGraphics Metrics
  • Loading of Models


Airplay API Reference: IwGraphics Initialisation and Termination

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > IwGraphics Initialisation and Termination >

IwGraphics Initialisation and Termination

The user must initialise IwGraphics and terminate IwGraphics as follows:

  • // Begin application
  • IwGxInit();
  • IwGraphicsInit();

    • ...rest of application

  • // End application
  • IwGraphicsTerminate();
  • IwGxTerminate();

IwGraphicsInit() creates the IwGraphicsState object. IwGraphicsTerminate() destroys the IwGraphicsState object.

In Win32 Debug Builds, IwGraphicsInit() creates the CIwModelBuilder singleton, and IwGraphicsTerminate() destroys the CIwModelBuilder singleton.


Airplay API Reference: IwGraphics State

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > IwGraphics State >

IwGraphics State

The entire IwGraphics state is contained within the IwGraphicsState object. This object is hidden from the user.

This state object includes mainly information for debugging of model rendering.

IwGraphics API calls are used to write to and read from the state.


Airplay API Reference: Model

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Model >

Model

At the heart of IwGraphics is the CIwModel class. An object of this class represents a renderable model (mesh) resource.

The CIwModel class has a Render() method, which will render the model resource using the current IwGx model transform, view transform and frustrum settings.

The model resource contains its own bounding sphere which is used to perform an early frustrum clip check.


Airplay API Reference: Model Blocks

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Model Blocks >

Model Blocks

A model consists of a list of "model blocks". A model block is an object derived from the CIwModelBlock class, which has a virtual Render() method. When CIwModel::Render() is called, the model iterates over its list of blocks, calling Render() on each model block in turn. This means that the model resource itself is completely modular and thus highly flexible.

For example, a typical list of model blocks in a model might be:

  • CIwModelBlockVerts: render method will pass vertex stream to IwGx
  • CIwModelBlockNorms: render method will pass normal stream to IwGx
  • CIwModelBlockCols: render method will pass colour stream to IwGx
  • CIwModelBlockUVs: render method will pass UV stream to IwGx
  • CIwModelBlockTriStrips: render method will call IwGxDrawPrims

The user does not generally have to concern themselves with the details of the model block implementation. However, the class architecture is exposed, opening up the option for advanced users to implement their own custom model blocks, or override the rendering functionality of existing blocks.

The user can get hold of a model block by name. The model block instance name is usually the same as its class name. For example, the following will generally return a non-NULL pointer:

  • CIwModelBlockVerts* pBlock =
  • (CIwModelBlockVerts*)m_Model->GetBlockNamed("CIwModelBlockVerts");


Airplay API Reference: Model Extensions

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Model Extensions >

Model Extensions

A model can contain a list of "model extensions". An extension is anything which can usefully be associated with the model. For example, collision data in the form of points or spheres, or selected sets of vertices.

The user can get hold of a model extension by name. The model block instance name is usually set by the artist from within the modelling package. For example, the artist could create a vertex selection set named "Set0". This would result in an extension of class CIwModelExtSelSetVerts being added to the model. The user could get hold of it as follows:

  • CIwModelExtSelSetVerts* pExt =
  • (CIwModelExtSelSetVerts*)m_Model->GetExtNamed("Set0");

The following model extensions are supported:

  • CIwModelExtPos - Single point (in modelspace)
  • CIwModelExtSphere - Sphere (in modelspace)
  • CIwModelExtSelSetVert - Vertex selection set
  • CIwModelExtSelSetEdge - Edge selection set
  • CIwModelExtSelSetFace - Face selection set

The user is free to derive their own extensions from CIwModelBlockExt. These can be added to the model using CIwModel::AddExt() and removed using CIwModel::RemoveExt().


Airplay API Reference: Model Builder

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Model Builder >

Model Builder

The model builder is a key component of IwGraphics. It takes verbose mesh information (for example, floating point geometry streams, material information) and conditioning information (for example, how to optimise the model, whether or not to include vertex normals) and outputs a single CIwModel resource for use by the application.

Usually, the model builder is populated with mesh information obtained from a GEO file. However, the user is free to populate the model builder themselves, and in this way can "manually" create a model from within the code. See Manually Creating a Model.

Note: The model builder is only available in Win32 Debug Builds, as it contains some bulky floating point code. Users who "manually" create models from within the code must ensure the CIwModel resources are serialised to binary, for use in Release builds. See the IwResManager documentation for details of exactly how resource loading is handled in Debug and Release builds.

The model builder singleton is created during IwGraphicsInit() (in Win32 Debug Builds only), and can be accessed via IwGetModelBuilder().


Airplay API Reference: IwGraphics Metrics

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > IwGraphics Metrics >

IwGraphics Metrics

For Win32 Debug Builds, IwGraphics maintains many useful metrics which can be inspected by the user. For example, the user can track the number of models rendered, the number which were frustrum clipped, etc.

There are two main ways of inspecting the metrics:

  • Using the main IwGraphics debug menu system. See the IwUtil documentation for details of using the debug menu system. Add the main IwGraphics debug menu to your top-level menu, as follows:
    • // Assume pMenu is the top-level debug menu
    • pMenu->AddItem(new CIwMenuItemGraphics);

    This system will allow you have access to a menu of all the IwGraphics metrics.

    Note: See the IwGraphics API Reference for a full list of the IwGraphics metrics.

  • Explicitly interrogating specific metrics: Use the IW_GRAPHICS_METRIC_GET macro to return the current value of a named IwGraphics metric.

    • Note: The input to the macro is the full IwGraphics metric name, but without the IW_GRAPHICS_METRIC_ prefix.


Airplay API Reference: Loading of Models

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Loading of Models >

Loading of Models

Creating a new model object can be achieved either by loading pre-defined mesh data from a GEO file or by specifying mesh data by hand in the code.

The Model Builder singleton is used to generate CIwModel objects from this data, which can then be rendered to the screen (see the Model overview).

  • Loading of Models (Meshes) from GEO Files
  • Manually Creating a Model


Airplay API Reference: Loading of Models (Meshes) from GEO Files

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Loading of Models > Loading of Models (Meshes) from GEO Files >

Loading of Models (Meshes) from GEO Files

Loading a model from a GEO file is the simplest route by which to create a model. GEO files are text files created by the asset export process. They are in the standard ITX format. GEO files describe the original art asset in as much detail as possible. The geometry information contained in a GEO is read in and added to the model builder.

This functionality is typically used in Windows as it is only available in Win32 Debug Builds. In Win32 Debug Builds, IwGraphicsInit() creates the model builder singleton. This is accessed using IwGetModelBuilder(). The model builder singleton is not created in release builds, and thus any attempt to access it by the user will fail.

Note: For more information on how ITX files are formatted, see Text Parsing section of the IwUtil API Documentation.

The user is able to add data to the model builder without supplying a GEO file.

Note: For more information on how to manually create a model, see the section Manually Creating a Model, and the CIwModelBuilder class documentation.

Assuming the model builder has been populated with data, through the use of a GEO file or explicitly by the user, the user can now call 'IwGetModelBuilder()->CreateModel()' to create a run-time CIwModel object from the builder's data.

However, before performing this final stage to create the model, the user should consider how to configure the model builder so that it creates the desired "flavour" of model. The flexibility of this conditioning process is one of the most powerful features of IwGraphics.

Note: For examples of how to load a mesh, see the Example IwGraphics Model and Example IwGraphics Model Two.

Configuring the Model Builder

The model builder is configured using the resource template class CIwResTemplateGEO.

Note: For more information about resource templates, see the IwResManager API Documentation.

An instance of this class contains all the information the model builder needs to know how to condition a model. Usually, the resource template is set up from script files during the resource loading process. However, if desired the user can set the template explicitly, by calling the appropriate function on CIwResHandlerGEO.

The entire model import and model build process is usually driven by parsing GROUP files. For example:

File 'hero.group'

  • CIwResGroup
  • {
    • name "hero_assets"
    • "./models/hero.geo"
  • }

Code to parse the group and access the model:

  • new CIwResManager;
  • IwGetResManager()->AddHandler(new CIwResHandlerGEO);
  • // Get the named group
  • CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("hero_assets");
  • // Get the named resource, of type model, within the named group
  • CIwModel* pModel = (CIwModel*)pGroup->GetResNamed("hero", IW_GRAPHICS_RESTYPE_MODEL);
  • // ...later, render the model
  • IwGxSetModelMatrix(pHeroMatrix);
  • pModel->Render();

For more information on how to use GROUP files and templates to generate model resources, see the IwResManager API Documentation. In this example, the model has been built with the default template settings. There are two main ways to amend the settings the builder uses to build models. The first is simply to specify the settings after the resource pathname in the GROUP file. For example:

File "hero.group"

  • CIwResGroup
  • {
    • name "hero_assets"
    • "./models/hero.geo" { scale 2 }
  • }

In this case, we tell the builder to use resource template setting "scale 2" when building the "hero" model. This setting persists for the single resource only. The second method is to create some named resource templates, which we can then apply to a single resource or block of resources. For example:

File "templates.itx"

  • CIwResTemplateGEO
  • {
    • name "hero_template"
    • scale 2
    • buildNorms false
  • }

File "hero.group"

  • CIwResGroup
  • {
    • name "hero_assets"
    • useTemplate "geo" "hero_template">
    • "./models/hero.geo"
  • }

At some point during initialisation, the user tells the resource manager to parse the 'templates.itx' file, which creates the named template objects, and associates them with their respective resource handlers.

The 'useTemplate' line in the GROUP file tells the model builder to use the named template settings when building subsequent resources of type GEO. These settings persist until another useTemplate line is parsed.

It is possible to override settings on a per-resource basis, as follows:

File 'hero.group'

  • CIwResGroup
  • {
    • name "hero_assets"
    • useTemplate "geo" "hero_template"
    • "./models/hero.geo" { scale 3 }
    • "./models/gun.geo"
  • }

In this case, even though "hero_template" tells the model builder to build models with scale 2, we have overridden this setting just for 'hero.geo', and the model will be built at scale 3. Note that subsequent models will revert to the 'hero_template' settings; so 'gun' will be built at scale 2.


Airplay API Reference: Manually Creating a Model

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Overview > Loading of Models > Manually Creating a Model >

Manually Creating a Model

Although the model builder is normally populated with mesh information automatically when a GEO file is parsed, the user is also free to add mesh data to the model builder for the purposes of creating a CIwModel object from within the code.

The user starts by calling IwGetModelBuilder()->Reset(). This ensures the model builder singleton is cleaned out and ready to receive new mesh data.

This can be done by calling the model builder methods AddVert(), AddNorm() etc. to populate the model builder with mesh data.

Note: Mesh data presented to the model builder is always in floating-point form.

Once arrays of vertices, normals, colours and UV coordinates have been added to the model builder in this way, the user adds face data which indexes into these arrays.

The CIwFace object contains the required face data. A face can contain 3 or 4 points (CIwFace::Point). A point contains vertex, normal, colour and UV coordinate indices (indices into the model builder's arrays of data for these types). A face is added to the model builder using AddFace().

If a face should not use vertex normals, then all the points of the face should have their normal ID set to CIwFace::Point::ID_NONE. Similarly for vertex colours.

The CIwFace object also points to a single material. The user can either set the material member of the CIwFace directly, or they can use IwGetModelBuilder()->SetMaterial() to set a material to be used for all subsequent faces (subsequent calls to AddFace()).

Once all faces have been added, there are various conditioning methods which can be called to modify the model data as a whole. For example, IwGetModelBuilder()->ReverseNorms() will negate all the vertex normals. See the CIwModelBuilder documentation for a complete list of such methods.

Finally, the user calls IwGetModelBuilder()->CreateModel() to create and return a CIwModel object from the model builder's mesh data. Note that the model will be conditioned according to the current template settings of the CIwResHandlerGEO (see Resource Templates for more information).

Note: For more information on how to manually create a model, see the Example IwGraphics Manual Model Builder. This example also shows how to manually create a resource group to serialise the created model to disk. The model building functionality is only present in Debug configurations, so manually-created models must be serialised to disk and loaded in binary form in Release configurations.


Airplay API Reference: IwGraphics API Reference

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference >

IwGraphics API Reference

Modules

Initialisation and Termination
Selective Linking
General State
Model Object
Model Builder
Model Extensions
GEO file helpers

Data Structures

struct | _IwModelPrimBase
struct | _IwModelPrimEdge
struct | _IwModelPrimTextured
struct | _IwModelPrimVert
class | CIwModelBlock
class | CIwModelBlockGLPrimBase
class | CIwModelBlockGLRenderEdges
class | CIwModelBlockGLRenderVerts
class | CIwModelBlockGLTriList
class | CIwModelBlockGLTriStrip
class | CIwModelBlockGLUVs
class | CIwModelBlockGLUVs2
class | CIwModelBlockPrimBase
class | CIwModelBlockPrimGen3
class | CIwModelBlockPrimGen4
class | CIwModelBlockRenderEdges
class | CIwModelBlockRenderVerts
class | CIwModelBlockSWOptim1

Detailed Description

Model block primitive definitions for GL rendering.

Enumeration Type Documentation

anonymous enum

Enumerator:
IW_MODEL_PRIM_NO_RENDER_F | do not render this prim
IW_MODEL_PRIM_QUAD_F | prim is a quad, not a tri
IW_MODEL_PRIM_GOURAUD_F | prim has colour-per-vertex
IW_MODEL_PRIM_TEXTURED_F | prim has texture data
IW_MODEL_PRIM_OTZ_AVG_F | prim OTZ calculated from viewspace z average
IW_MODEL_PRIM_EXCLUDE_FRAME_F | exclude this prim this frame (used for hw path for sw models)
IW_MODEL_PRIM_OTZ_OFS_BITLO | 4 bits total gives 0..15 offset value, with 8 as "no offset"
IW_MODEL_PRIM_OTZ_OFS_MASK | mask for otz offset
IW_MODEL_PRIM_ALPHAMODE_BITLO | 2 bits total gives 0..3 alpha mode
IW_MODEL_PRIM_ALPHAMODE_MASK | mask for alphamode
IW_MODEL_PRIM_MAT_ID_SHIFT | for prims with variable materials, store in high 16


Airplay API Reference: Initialisation and Termination

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > Initialisation and Termination >

Initialisation and Termination
[IwGraphics API Reference]

Functions

void | IwGraphicsInit ()
void | IwGraphicsTerminate ()

Detailed Description

This module controls the initialisation and termination of the IwGraphics module.

Note:
For more information on initialisation and termination of the IwGraphics module, see the IwGraphics Initialisation and Termination section in the IwGraphics API Documentation.

Function Documentation

void IwGraphicsInit ( )

Initialises all features of IwGraphics. This function must be called before IwGraphics is used.

See also:
IwGraphicsTerminate
Required Header Files
IwGraphicsFuncs.h

void IwGraphicsTerminate ( )

Shuts down IwGraphics and frees all memory.

See also:
IwGraphicsInit
Required Header Files
IwGraphicsFuncs.h


Airplay API Reference: Selective Linking

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > Selective Linking >

Selective Linking
[IwGraphics API Reference]

Functions

void | IwGraphicsInit_Base ()
void | IwGraphicsInit_HW ()
void | IwGraphicsInit_SW ()

Detailed Description

IwGraphics provides smaller builds when not using all compiled model types. IwGraphicsInit_Base should always be called first, followed by any other optional model types. If a model type is used that has not been initialised an assert will fire in debug builds. The behaviour in release builds is undefined.

Function Documentation

void IwGraphicsInit_Base ( )

Initialise core features of IwGraphics.

void IwGraphicsInit_HW ( )

Initialise HW model format. HW models are optimised for 'HW' platforms - currently any platform that is not SW rendered. Requires ~2k of code.

void IwGraphicsInit_SW ( )

Initialise SW model format. SW models are optimised for the 'SW' platform. Requires ~10k of code.


Airplay API Reference: General State

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > General State >

General State
[IwGraphics API Reference]

Data Structures

class | CIwGraphicsState

Defines

#define | IW_GRAPHICS_RESTYPE_MODEL "CIwModel"

Enumerations

enum | IwGraphicsStateDebugFlags
enum | IwGraphicsStateFlags

Functions

INLINE void | IwGraphicsClearFlags (uint32 flags)
INLINE uint32 | IwGraphicsGetFlags ()
INLINE int32 * | IwGraphicsGetOTZOfsTable ()
INLINE int32 * | IwGraphicsGetZDepthOfsTable ()
void | IwGraphicsReset ()
INLINE void | IwGraphicsSetFlags (uint32 flags)
void | IwGraphicsSetOTZOfsTable (int32 *pTable)
void | IwGraphicsSetZDepthOfsTable (int32 *pTable)

Detailed Description

Global state object.

Note:
For more information on IwGraphics State, see the IwGraphics State section in the IwGraphics API Documentation.

Define Documentation

#define IW_GRAPHICS_RESTYPE_MODEL "CIwModel"

Resource type string for models - equates to CIwModel.

Required Header Files
IwGraphicsFuncs.h

Enumeration Type Documentation

enum IwGraphicsStateDebugFlags

Enumeration of debug flags for CIwGraphicsState object.

Required Header Files
IwGraphicsState.h
Enumerator:
IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F | Render model chunks as different colours.
IW_GRAPHICS_DEBUG_MODEL_BLOCK_SINGLE_ITEM_F | For m_DebugBlock, display only the item corresponding to m_DebugItemID.
IW_GRAPHICS_DEBUG_MODEL_BLOCK_DEBUG_MATERIAL_F | For m_DebugBlock, display with debug material, flat color.
IW_GRAPHICS_DEBUG_MODEL_RENDER_NAMES_F | Render the model's name at its origin.
IW_GRAPHICS_DEBUG_MODEL_RENDER_CHUNKS_BSPHERES_F | Render model bspheres.

enum IwGraphicsStateFlags

Flags for CIwGraphicsState object.

Required Header Files
IwGraphicsState.h
Enumerator:
IW_GRAPHICS_MODEL_IGNORE_VERTEX_COLS_F | Ignore vertex colours on a model, if they exist.
IW_GRAPHICS_MODEL_NO_SCALE_MAT_COLS_F | Do not scale material colours by global terms.
IW_GRAPHICS_MODEL_NO_VERT_STREAM_CLEAR_F | Use existing vert stream, if any.
IW_GRAPHICS_MODEL_NO_COL_STREAM_CLEAR_F | Use existing colour stream, if any.
IW_GRAPHICS_MODEL_NO_NORM_STREAM_CLEAR_F | Use existing normal stream, if any.
IW_GRAPHICS_MODEL_NO_UV0_STREAM_CLEAR_F | Use existing uv 0 stream, if any.
IW_GRAPHICS_MODEL_NO_UV1_STREAM_CLEAR_F | Use existing uv 1 stream, if any.
IW_GRAPHICS_MODEL_RENDERED_F | Last call to CIwModel::Render() was NOT terminated early (e.g. by bsphere test).
IW_GRAPHICS_MODEL_RESTORE_MAT_F | Something during CIwModel::Render() changed the model mat, so reset when render finishes.

Function Documentation

INLINE void IwGraphicsClearFlags ( uint32 flags )

Clears flags.

Parameters:
flags Flags to clear.
See also:
IwGraphicsSetFlags, IwGraphicsGetFlags
Required Header Files
IwGraphicsFuncs.h

INLINE uint32 IwGraphicsGetFlags ( )

Gets flags.

Returns:
Current flags set.
See also:
IwGraphicsSetFlags, IwGraphicsClearFlags
Required Header Files
IwGraphicsFuncs.h

INLINE int32 * IwGraphicsGetOTZOfsTable ( )

Gets the OTZ offset table.

Returns:
Pointer to an array of 16 signed offsets within the SW poly ordering table.
See also:
IwGraphicsSetOTZOfsTable
Required Header Files
IwGraphicsFuncs.h

INLINE int32 * IwGraphicsGetZDepthOfsTable ( )

Gets the Z depth offset table.

Returns:
Pointer to an array of 16 signed offsets within the SW poly ordering table.
See also:
IwGraphicsSetZDepthOfsTable
Required Header Files
IwGraphicsFuncs.h

void IwGraphicsReset ( )

Resets the IwGraphics state.

Required Header Files
IwGraphicsFuncs.h

INLINE void IwGraphicsSetFlags ( uint32 flags )

Sets flags.

Parameters:
flags Flags to set.
See also:
IwGraphicsGetFlags, IwGraphicsClearFlags
Required Header Files
IwGraphicsFuncs.h

void IwGraphicsSetOTZOfsTable ( int32 * pTable )

Sets the OTZ offset table. For SW rasterisation only, face selection sets within a GEO file can be used to change the z-depth of specific groups of polys, irrespective of their material. This can be useful to compensate for some of the sorting artefacts introduced by the Airplay software renderer, when it is using "OT slots" rather than a full z-buffer.

The default offset table is {-256, -128, -64, -32, -16, -8, -4, -2, 0, 2, 4, 8, 16, 32, 64, 128}, corresponding to the input range of [-8, 7].

So, if a GEO face selection set contains an offset value of -4, this will look-up into an OT offset value of -16. If a GEO face selection set contains an offset value of 6, this will look-up into an OT offset value of 64.

See the section "Manually sorting by Face Selection Sets" within "AirplayToolsGuide.pdf".

Note:
Applications should prefer IwGraphicsSetZDepthOfsTable - OTZ offsets will change meaning depending on frustrum depth.
Parameters:
Pointer to an array of 16 signed offsets within the SW poly ordering table.
See also:
IwGraphicsGetOTZOfsTable IwGraphicsSetZDepthOfsTable
Required Header Files
IwGraphicsFuncs.h

void IwGraphicsSetZDepthOfsTable ( int32 * pTable )

Sets the Z Depth offset table. For SW rasterisation only, face selection sets within a GEO file can be used to change the z-depth of specific groups of polys, irrespective of their material. This can be useful to compensate for some of the sorting artefacts introduced by the Airplay software renderer, when it is using "OT slots" rather than a full z-buffer.

The default offset table is {-640, -320, -160, -80, -40, -20, -10, -5, 0, 5, 10, 20, 40, 80, 160, 320}, corresponding to the input range of [-8, 7].

So, if a GEO face selection set contains an offset value of -4, this will look-up into an OT offset value of -16. If a GEO face selection set contains an offset value of 6, this will look-up into an OT offset value of 64.

See the section "Manually sorting by Face Selection Sets" within "AirplayToolsGuide.pdf".

Parameters:
Pointer to an array of 16 signed offsets within the SW poly ordering table.
See also:
IwGraphicsGetZDepthOfsTable
Required Header Files
IwGraphicsFuncs.h


Airplay API Reference: Model Object

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > Model Object >

Model Object
[IwGraphics API Reference]

Data Structures

class | CIwModel

Defines

#define | IW_MODEL_NUM_UV_SETS 2

Detailed Description

The model object.

Note:
For more information on the IwGraphics Model Object, see the Model section in the IwGraphics API Documentation.

Define Documentation

#define IW_MODEL_NUM_UV_SETS 2

Maximum number of UV sets per model.

Required Header Files
IwModel.h


Airplay API Reference: Model Builder

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > Model Builder >

Model Builder
[IwGraphics API Reference]

Data Structures

class | CIwEdge
class | CIwEdgeCol

Detailed Description

Class for geometry input and CIwModel creation. The model builder singleton.

Note:
For more information on IwGraphics model builder singleton, see the Model Builder section in the IwGraphics API Documentation.


Airplay API Reference: Model Extensions

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > Model Extensions >

Model Extensions
[IwGraphics API Reference]

Data Structures

class | CIwModelExt
class | CIwModelExtPos
class | CIwModelExtSelSet
class | CIwModelExtSelSetEdge
class | CIwModelExtSelSetFace
class | CIwModelExtSelSetVert
class | CIwModelExtSphere

Detailed Description

This module provides the IwGraphics API for model extensions.

Note:
For more information on model extensions, see the Model Extensions section in the IwGraphics API Documentation.


Airplay API Reference: GEO file helpers

Airplay API Reference > IwGraphics API Documentation > IwGraphics API Reference > GEO file helpers >

GEO file helpers
[IwGraphics API Reference]

Data Structures

class | CIwResHandlerGEO
class | CIwResTemplateGEO

Detailed Description

Helper classes for handling GEO files.


Airplay API Reference: IwGraphics Examples

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples >

IwGraphics Examples

IwGraphics is a model-rendering API. It sits on top of the IwGx drawing API, and adds four main functions:

  • Loading of models (meshes) from intermediary text files (GEO files).
  • Building of models, from their raw loaded form, into conditioned run-time objects (CIwModel objects).
  • Serialisation of conditioned run-time models to and from disk.
  • Rendering of models.

The following examples are contained within this section:

  • IwGraphics Model Example Example
  • IwGraphics Model Two Example
  • IwGraphics Model Builder Example
  • IwGraphics Manual Model Builder Example
  • IwGraphics Resource Groups Example
  • IwGraphics Model Builder Callbacks Example
  • IwGraphics GLES2 Example
  • IwGraphics Scalable Pipeline Example


Airplay API Reference: IwGraphics Model Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Model Example >

IwGraphics Model Example

This example demonstrates the loading of a model resource, and rendering of the model.

The main classes used to achieve this are:

  • CIwModel

  • CIwResGroup

The main functions used to achieve this are:

  • IwGraphicsInit()

  • CIwResManager::LoadGroup()

  • CIwResManager::GetGroupNamed()

  • IwGraphicsTerminate();

  • CIwModel::Render();

After IwGraphicsInit() is called the GROUP file containing details of the target model is loaded. The model resource is then identified using the GetGroupNamed() function and then rendered by calling the Render() function.

Upon the closing of the example the IwGraphicsTerminate() function is called.

The following graphic illustrates the example output.

Note:
For more information on the loading of meshes from GEO files, see Loading of Models.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModel
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwGxPrint.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Model;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0x800, 0);

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("Model.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointer to the model resource
    s_Model = (CIwModel*)pGroup->GetResNamed("FunkyVic", IW_GRAPHICS_RESTYPE_MODEL);

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x80;
    view.t.z = -0x180;
    IwGxSetViewMatrix(&view);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Model->Render();

    // Paint the cursor keys buttons and prompt text
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Model Two Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Model Two Example >

IwGraphics Model Two Example

This example demonstrates the loading of multiple model resources, and rendering of multiple models, with lighting options.

The main classes used to achieve this are:

  • CIwModel

  • CIwResGroup

The main functions used to achieve this are:

  • IwGraphicsInit()

  • CIwResManager::LoadGroup()

  • CIwResManager::GetGroupNamed()

  • CIwResManager::GetResNamed()

  • CIwModel::Render();

  • IwGraphicsTerminate();

The lighting is configured differently prior to the rendering of each cube:

  • Cube 0:
    Emissive = true
    Ambient = false
    Diffuse = false

    Therefore cube 0 is applied with the material emissive colour (green).

  • Cube 1:
    Emissive = false
    Ambient = false
    Diffuse = false

    Therefore cube 1 is applied with the material ambient response (grey) as colour, unmodified by scene ambient lighting.

  • Cube 2:
    Emissive = false
    Ambient = true
    Diffuse = false

    Therefore cube 2 is applied with the material ambient response, modified by scene ambient colour (red).

  • Cube 3:
    Emissive = false
    Ambient = true
    Diffuse = true

    Therefore cube 3 is the same as Cube 2, but applied with additional white diffuse lighting.

The following graphic illustrates the example output.

Note:
For more information on the loading of meshes from GEO files, see Loading of Models.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModel2
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resources
CIwModel*   s_Models[2];

// Timer
uint32      s_Timer;

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemResManager);
    pMenu->AddItem(new CIwMenuItemGraphics);
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0x800, 0);

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("Model2.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointer to the model resources
    s_Models[0] = (CIwModel*)pGroup->GetResNamed("FunkyVic", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[1] = (CIwModel*)pGroup->GetResNamed("Test01", IW_GRAPHICS_RESTYPE_MODEL);

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x80;
    view.t.z = -0x180;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    CIwColour colA = {0xff, 0x00, 0x00, 0xff};
    IwGxSetLightCol(0, &colA);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwColour colD = {0xff, 0xff, 0xff, 0xff};
    IwGxSetLightCol(1, &colD);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetMenuManager();

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Reset metrics
#ifdef IW_DEBUG
    IwGraphicsMetricsReset();
    IwGxMetricsReset();
#endif

    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build model matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the main model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Models[0]->Render();

    //-------------------------------------------------------------------------
    // Render the smaller models
    //-------------------------------------------------------------------------
    CIwSVec3 angles;
    angles.x = (int16)s_Timer * 0x20;
    angles.y = (int16)s_Timer * 0x28;
    angles.z = (int16)s_Timer * 0x30;
    CIwMat rotX, rotY, rotZ, m0;
    rotX.SetRotX(angles.x);
    rotY.SetRotY(angles.y);
    rotZ.SetRotZ(angles.z);
    m0.CopyRot(rotZ * rotY * rotX);

    const int32 RADIUS = 0xc0;
    for (uint32 m = 0; m < 4; m++)
    {
        m0.t.y = 0;
        m0.t.x = IW_FIXED_MUL(RADIUS, IW_GEOM_COS((m * 0x400) + (s_Timer << 5)));
        m0.t.z = IW_FIXED_MUL(RADIUS, IW_GEOM_SIN((m * 0x400) + (s_Timer << 5)));

        IwGxSetModelMatrix(&m0);

        /* Configure lighting differently for each cube:
        Cube 0:
            Emissive = true
            Ambient = false
            Diffuse = false
            ...so cube gets material emissive colour (green)

        Cube 1:
            Emissive = false
            Ambient = false
            Diffuse = false
            ...so cube gets material ambient response (grey) as colour, unmodified by scene ambient

        Cube 2:
            Emissive = false
            Ambient = true
            Diffuse = false
            ...so cube gets material ambient response, modified by scene ambient colour (red)

        Cube 3:
            Emissive = false
            Ambient = true
            Diffuse = true
            ...so cube is same as Cube 2, but with additional white diffuse
        */

        IwGxLightingEmissive(m == 0);
        IwGxLightingAmbient(m > 1);
        IwGxLightingDiffuse(m > 2);
        s_Models[1]->Render();
    }

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Model Builder Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Model Builder Example >

IwGraphics Model Builder Example

This example demonstrates the conditioning of models for SW and HW, as well as "chunking" of large models.

Note:
For more information about resource templates and the conditioning of models, see the Resource Manager documentation.
The main classes used to achieve this are:

  • CIwModel

  • CIwResGroup

  • CIwModelBuilder

  • CIwMenuManager

  • CIwFace

The main functions used to achieve this are:

  • IwGraphicsInit()

  • CIwResManager::LoadGroup()

  • CIwResManager::GetGroupNamed()

  • CIwTextParserITX::ParseFile()

  • CIwModel::Render()

By default, the model builder will condition models for SW rasterisation, unless IwGx has been initialised to support HW rasterisation, in which case the model builder will condition models for HW rasterisation. Models conditioned for SW rasterisation will not be renderable if the pipeline is switched to HW rasterisation. However the converse is not true; i.e., models conditioned for HW can in fact be rendered using SW rasterisation (although performance may not be optimal).

To enable this example to dynamically switch between SW and HW rasterisation, you must amend the "Rasterisation" line in the app.icf file to "Rasterisation=SW/HW". This will initialise IwGx to support both forms of rasterisation, and start in SW mode. "Rasterisation=HW/SW" would do the same but start in HW mode.

To toggle between SW and HW rasterisation:

  1. Build and run the example.
  2. Press F6 to display the debug menu.
  3. Use the arrow keys to navigate into the IwGx settings.
  4. Select the rasterisation option and use the + and - keys to the toggle rasterisation between HW and SW.

The display changes (for example, any texture filtering disappears for SW rasterisation), but you can see that the model displays equivalently in SW and HW.

Now try editing the app.icf file so that the application is not built to support HW rasterisation (use the line "Rasterisation=SW"). When running the example, the model will now be conditioned optimally for SW rasterisation (any attempt to switch to HW rasterisation will result in an assertion).

The second point of this example is to illustrate the concept of model "chunking". This is a model conditioning option which binary-partitions the model into spatially discrete sections. A hierarchy of bounding spheres is constructed to provide rapid frustrum culling of non-visible sections.

The following code is contained in the loaded ITX file to condition the loaded model.

 CIwResTemplateGEO
 {
    name        "chunked"
    chunked     true
    maxPrimsPerChunk 100
 }

Note:
For more information on conditioning of resources, see the Resource Templates section of the IwResManager API Documentation
The following code is contained in the loaded group file, ModBuild.group:

 CIwResGroup
 {
    name    "Example"

    // Plain model
    "lava/models/lava.geo"

    // Chunked model
    useTemplate "geo" "chunked"
    "lava/models/lava.geo" { resName "lavaChunked" }
 }

The GROUP file causes the same GEO file to be loaded twice to create two different binary model resources. The second version is chunked.

To toggle between chunked and not chunked:

  1. Press 2 to switch to rendering the second version.
  2. Press F6 to bring up the debug menu.
  3. Navigate to IwGraphics settings, and toggle the COLOUR_CHUNKS setting.

This displays the model chunks in contrasting colours, showing the spatial partitioning.

Note:
For more information on the loading of meshes from GEO files, see Loading of Models.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModelBuilder
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Models[2];

// Timer
uint32      s_Timer;

// Model ID
uint32      m_ModelID = 0;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);
    AddButton("Model 1: 3", w - 70, 70, 70, 30, s3eKey3);
    AddButton("Model 2: 4", w - 70, 110, 70, 30, s3eKey4);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->AddItem(new CIwMenuItemResManager);
    pMenu->AddItem(new CIwMenuItemGraphics);
    pMenu->AddItem(new CIwMenuItemGx);
#endif
    return pMenu;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x2000, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0x200, 0x800, 0);

    // If configured to support HW, then build model for HW
#ifdef IW_BUILD_RESOURCES
    // Load the resource templates
    IwGetTextParserITX()->ParseFile("ModBuild_templates.itx");
#endif

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("ModBuild.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointers to the model resources
    s_Models[0] = (CIwModel*)pGroup->GetResNamed("lava", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[1] = (CIwModel*)pGroup->GetResNamed("lavaChunked", IW_GRAPHICS_RESTYPE_MODEL);

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x80;
    view.t.z = -0x800;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    CIwColour colA = {0x40, 0x40, 0x40, 0xff};
    IwGxSetLightCol(0, &colA);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwColour colD = {0xc0, 0xc0, 0xc0, 0xff};
    IwGxSetLightCol(1, &colD);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetMenuManager();

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Reset metrics
#ifdef IW_DEBUG
    IwGraphicsMetricsReset();
    IwGxMetricsReset();
#endif
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Move camera in/out
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t.z += 0x40;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t.z -= 0x40;

    // Increase/decrease model ID
    if ( CheckButton("Model 1: 3") & S3E_KEY_STATE_PRESSED )
        m_ModelID = (m_ModelID + 1) % 2;
    if ( CheckButton("Model 2: 4") & S3E_KEY_STATE_PRESSED )
        m_ModelID = (m_ModelID + (2-1)) % 2;

#ifdef IW_DEBUG
    // Toggle flag to display chunks in debug colours
    if (s3eKeyboardGetState(s3eKeyD) & S3E_KEY_STATE_PRESSED)
    {
        if (IwGraphicsGetDebugFlags() & IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F)
            IwGraphicsClearDebugFlags(IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F);
        else
            IwGraphicsSetDebugFlags(IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F);
    }
#endif

    // Build model matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Start with full lighting
    IwGxLightingOn();

    //-------------------------------------------------------------------------
    // Render a background poly
    //-------------------------------------------------------------------------
    CIwSVec2* pVec = AllocClientScreenRectangle();
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
    pMat->Init();
    pMat->SetColAmbient(0, 0, 255, 255);
    IwGxSetMaterial(pMat);
    IwGxSetVertStreamScreenSpace(pVec, 4);
    IwGxSetScreenSpaceSlot(-1);
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);
    IwGxSetScreenSpaceSlot(0);

    //-------------------------------------------------------------------------
    // Render the main model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Models[m_ModelID]->Render();

    // Display name of model
    IwGxPrintString( 2, IwGxGetScreenHeight() - 70, s_Models[m_ModelID]->DebugGetName());

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Render menu manager
    IwGetMenuManager()->Render();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Manual Model Builder Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Manual Model Builder Example >

IwGraphics Manual Model Builder Example

This example demonstrates manual creation of a model within the code. Also manual creation and serialisation of a resource group containing the model and all its required resources.

The main classes used to achieve this are:

  • CIwModel

  • CIwModelBuilder

  • CIwFace

The main functions used to achieve this are:

  • IwGraphicsInit()

  • CIwModelBuilder::Reset()

  • CIwModelBuilder::AddVert()

  • CIwModelBuilder::AddNorm()

  • CIwModelBuilder::AddUV()

  • CIwModelBuilder::AddCol()

  • CIwModelBuilder::SetMaterial()

  • CIwModelBuilder::AddFace()

  • CIwModelBuilder::CreateModel()

A CIwModel resource is usually created by parsing a GEO file. However, it is also possible to create models "manually" from within the code. The user adds vertex, normal, colour and UV coords to the CIwModelBuilder singleton. They then add face (triangle or quadrilateral) and material information. Once the CIwModelBuilder has a complete description of the mesh, the user calls CreateModel() to return a fully-formed CIwModel instance.

The CIwModelBuilder singleton is only available in Debug configurations. This is because it contains a fairly large amount of code for manipulating floating point data types, processing lists, etc. Creating the CIwModel instance is also a time-consuming process, due to the amount of "n-squared" type list processing involved.

For this reason, if you wish to manually create models within the code, they must be serialised to a file which is then loaded in Release configurations. This example also illustrates one way of doing that.

In this example, we create a simple cube. Three sides have a single texture mapped continuously. Two sides have another texture face-mapped. The final side is untextured but uses a colour stream to create gouraud shading between four colours.

In order for our example to create the model the vertices, normals and UVs are first declared. After this they are added to the model using the AddVert(), AddNorm() and AddUV() functions, respectively. The AddCol() function is then used to add the colours to the model. Six CIwFace objects are declared to hold the face information for each face of the cube. For each face, four Point objects are declared, and these are attributed the ID of the relevant Vert, Normal and UV. The CreateModel() function is then called to build the model.

Note:
Having very few faces per material is quite inefficient for rendering purposes; we are doing it for illustration only.
Use the up/down/left/right keys to rotate the cube.

The following graphic illustrates the example output.

Note:
For more information on the loading of meshes, see Loading of Models.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModelBuilderManual
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Model;

// Vertices to add
const float s = 200.0f;
CIwFVec3    s_Verts[8] =
{
    CIwFVec3(-s, -s,  s),   // this will become "vertex 0" of the model builder
    CIwFVec3( s, -s,  s),   // this will become "vertex 1" of the model builder, etc.
    CIwFVec3( s,  s,  s),
    CIwFVec3(-s,  s,  s),
    CIwFVec3(-s, -s, -s),
    CIwFVec3( s, -s, -s),
    CIwFVec3( s,  s, -s),
    CIwFVec3(-s,  s, -s),
};

// Normals to add
CIwFVec3    s_Norms[6] =
{
    CIwFVec3(-1.0, 0, 0),   // this will become "normal 0" of the model builder, etc.
    CIwFVec3( 1.0, 0, 0),
    CIwFVec3(0, -1.0, 0),
    CIwFVec3(0,  1.0, 0),
    CIwFVec3(0, 0,  1.0),
    CIwFVec3(0, 0, -1.0),
};

// UVs to add
CIwFVec2    s_UVs[8] =
{
    CIwFVec2(0, 0),         // this will become "UV 0" of the model builder, etc.
    CIwFVec2(0.33f, 0),
    CIwFVec2(0.66f, 0),
    CIwFVec2(1, 0),
    CIwFVec2(0, 1),
    CIwFVec2(0.33f, 1),
    CIwFVec2(0.66f, 1),
    CIwFVec2(1, 1),
};

// Textures
CIwTexture* s_Tex0;
CIwTexture* s_Tex1;

// Materials
CIwMaterial* s_MatTex0;
CIwMaterial* s_MatTex1;
CIwMaterial* s_Mat2;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x00, 0x00, 0xff, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x2000, 0x100);

    // Initialise angles
    s_Angles = CIwSVec3(0x200, 0x800, 0);

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.z = -600;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    CIwColour colA = {0x40, 0x40, 0x40, 0xff};
    IwGxSetLightCol(0, &colA);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwColour colD = {0xc0, 0xc0, 0xc0, 0xff};
    IwGxSetLightCol(1, &colD);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    //-------------------------------------------------------------------------
    // Construct the model
    //-------------------------------------------------------------------------
#ifndef IW_BUILD_RESOURCES
    // In this case, we simply load the existing group.bin, which contains the model, materials and textures
    IwGetResManager()->SetMode(CIwResManager::MODE_LOAD);
    IwGetResManager()->LoadGroup("ModBuildManual.group");
    s_Model = (CIwModel*)IwGetResManager()->GetCurrentGroup()->GetResNamed("cube", IW_GRAPHICS_RESTYPE_MODEL);
#else
    uint32 n;

    // First, reset the builder
    IwGetModelBuilder()->Reset();

    // Add vertices
    for (n = 0; n < 8; n++)
        IwGetModelBuilder()->AddVert(s_Verts[n]);

    // Add normals
    for (n = 0; n < 6; n++)
        IwGetModelBuilder()->AddNorm(s_Norms[n]);

    // Add UVs
    for (n = 0; n < 8; n++)
        IwGetModelBuilder()->AddUV(s_UVs[n]);

    // Add colours
    IwGetModelBuilder()->AddCol(IwGxGetColFixed(IW_GX_COLOUR_RED));
    IwGetModelBuilder()->AddCol(IwGxGetColFixed(IW_GX_COLOUR_GREEN));
    IwGetModelBuilder()->AddCol(IwGxGetColFixed(IW_GX_COLOUR_BLUE));
    IwGetModelBuilder()->AddCol(IwGxGetColFixed(IW_GX_COLOUR_WHITE));

    // Load the textures
    s_Tex0 = new CIwTexture;
    s_Tex0->LoadFromFile("textures/testTexture_4bit.bmp");
    s_Tex0->SetName("Tex0");
    s_Tex1 = new CIwTexture;
    s_Tex1->LoadFromFile("textures/testTexture_8bit.bmp");
    s_Tex1->SetName("Tex1");

    // Set up the materials
    s_MatTex0 = new CIwMaterial;
    s_MatTex0->SetName("MatTex0");
    s_MatTex0->SetTexture(s_Tex0);

    s_MatTex1 = new CIwMaterial;
    s_MatTex1->SetName("MatTex1");
    s_MatTex1->SetTexture(s_Tex1);

    s_Mat2 = new CIwMaterial;
    s_Mat2->SetName("Mat2");

    // Set up the faces. These index into the vertex, normal, etc. streams. Each face uses a single material.
    CIwFace f0, f1, f2, f3, f4, f5;

    IwGetModelBuilder()->SetMaterial(s_MatTex0);
    f0.m_NumPoints = 4;
    f0.m_Points[0].m_VertID     = 0;
    f0.m_Points[0].m_NormID     = 0;
    f0.m_Points[0].m_UVID[0]    = 0;
    f0.m_Points[1].m_VertID     = 3;
    f0.m_Points[1].m_NormID     = 0;
    f0.m_Points[1].m_UVID[0]    = 4;
    f0.m_Points[2].m_VertID     = 7;
    f0.m_Points[2].m_NormID     = 0;
    f0.m_Points[2].m_UVID[0]    = 5;
    f0.m_Points[3].m_VertID     = 4;
    f0.m_Points[3].m_NormID     = 0;
    f0.m_Points[3].m_UVID[0]    = 1;
    IwGetModelBuilder()->AddFace(&f0);

    f1.m_NumPoints = 4;
    f1.m_Points[0].m_VertID     = 4;
    f1.m_Points[0].m_NormID     = 5;
    f1.m_Points[0].m_UVID[0]    = 1;
    f1.m_Points[1].m_VertID     = 7;
    f1.m_Points[1].m_NormID     = 5;
    f1.m_Points[1].m_UVID[0]    = 5;
    f1.m_Points[2].m_VertID     = 6;
    f1.m_Points[2].m_NormID     = 5;
    f1.m_Points[2].m_UVID[0]    = 6;
    f1.m_Points[3].m_VertID     = 5;
    f1.m_Points[3].m_NormID     = 5;
    f1.m_Points[3].m_UVID[0]    = 2;
    IwGetModelBuilder()->AddFace(&f1);

    f2.m_NumPoints = 4;
    f2.m_Points[0].m_VertID     = 5;
    f2.m_Points[0].m_NormID     = 1;
    f2.m_Points[0].m_UVID[0]    = 2;
    f2.m_Points[1].m_VertID     = 6;
    f2.m_Points[1].m_NormID     = 1;
    f2.m_Points[1].m_UVID[0]    = 6;
    f2.m_Points[2].m_VertID     = 2;
    f2.m_Points[2].m_NormID     = 1;
    f2.m_Points[2].m_UVID[0]    = 7;
    f2.m_Points[3].m_VertID     = 1;
    f2.m_Points[3].m_NormID     = 1;
    f2.m_Points[3].m_UVID[0]    = 3;
    IwGetModelBuilder()->AddFace(&f2);

    IwGetModelBuilder()->SetMaterial(s_MatTex1);
    f3.m_NumPoints = 4;
    f3.m_Points[0].m_VertID     = 0;
    f3.m_Points[0].m_NormID     = 2;
    f3.m_Points[0].m_UVID[0]    = 0;
    f3.m_Points[1].m_VertID     = 4;
    f3.m_Points[1].m_NormID     = 2;
    f3.m_Points[1].m_UVID[0]    = 4;
    f3.m_Points[2].m_VertID     = 5;
    f3.m_Points[2].m_NormID     = 2;
    f3.m_Points[2].m_UVID[0]    = 7;
    f3.m_Points[3].m_VertID     = 1;
    f3.m_Points[3].m_NormID     = 2;
    f3.m_Points[3].m_UVID[0]    = 3;
    IwGetModelBuilder()->AddFace(&f3);

    f4.m_NumPoints = 4;
    f4.m_Points[0].m_VertID     = 7;
    f4.m_Points[0].m_NormID     = 3;
    f4.m_Points[0].m_UVID[0]    = 0;
    f4.m_Points[1].m_VertID     = 3;
    f4.m_Points[1].m_NormID     = 3;
    f4.m_Points[1].m_UVID[0]    = 4;
    f4.m_Points[2].m_VertID     = 2;
    f4.m_Points[2].m_NormID     = 3;
    f4.m_Points[2].m_UVID[0]    = 7;
    f4.m_Points[3].m_VertID     = 6;
    f4.m_Points[3].m_NormID     = 3;
    f4.m_Points[3].m_UVID[0]    = 3;
    IwGetModelBuilder()->AddFace(&f4);

    IwGetModelBuilder()->SetMaterial(s_Mat2);
    f5.m_NumPoints = 4;
    f5.m_Points[0].m_VertID     = 1;
    f5.m_Points[0].m_NormID     = 4;
    f5.m_Points[0].m_ColID      = 0;
    f5.m_Points[0].m_UVID[0]    = 0;
    f5.m_Points[1].m_VertID     = 2;
    f5.m_Points[1].m_NormID     = 4;
    f5.m_Points[1].m_ColID      = 3;
    f5.m_Points[1].m_UVID[0]    = 6;
    f5.m_Points[2].m_VertID     = 3;
    f5.m_Points[2].m_NormID     = 4;
    f5.m_Points[2].m_ColID      = 2;
    f5.m_Points[2].m_UVID[0]    = 7;
    f5.m_Points[3].m_VertID     = 0;
    f5.m_Points[3].m_NormID     = 4;
    f5.m_Points[3].m_ColID      = 1;
    f5.m_Points[3].m_UVID[0]    = 1;
    IwGetModelBuilder()->AddFace(&f5);

    // Create the model
    s_Model = IwGetModelBuilder()->CreateModel("cube");

    // Create a resource group and serialise it to disk
    CIwResGroup* pGroup = new CIwResGroup;
    pGroup->SetName("CubeAndStuff");

    // Note that resources must be added in dependency order; i.e. model depends on material depends on texture
    pGroup->AddRes(IW_GX_RESTYPE_TEXTURE, s_Tex0);
    pGroup->AddRes(IW_GX_RESTYPE_TEXTURE, s_Tex1);
    pGroup->AddRes(IW_GX_RESTYPE_MATERIAL, s_MatTex0);
    pGroup->AddRes(IW_GX_RESTYPE_MATERIAL, s_MatTex1);
    pGroup->AddRes(IW_GX_RESTYPE_MATERIAL, s_Mat2);
    pGroup->AddRes(IW_GRAPHICS_RESTYPE_MODEL, s_Model);

    IwSerialiseOpen("ModBuildManual.group.bin", false);
    pGroup->Write();
    IwSerialiseClose();
    IwGetResManager()->AddGroup(pGroup);

    // Note how textures must be uploaded AFTER serialising out to disk
    s_Tex0->Upload();
    s_Tex1->Upload();
#endif
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // We don't explicitly have to free any resources (CIwTexture, CIwMaterial, CIwModel) as they have all been
    // added to the resource manager, which is automatically destroyed by IwGraphicsTerminate, and will destroy the contents
    // of any resource groups it knows about.

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Reset metrics
#ifdef IW_DEBUG
    IwGraphicsMetricsReset();
    IwGxMetricsReset();
#endif
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build model matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with full lighting
    IwGxLightingOn();

    //-------------------------------------------------------------------------
    // Render the main model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Model->Render();

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Resource Groups Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Resource Groups Example >

IwGraphics Resource Groups Example

This example demonstrates using resource groups and resource templates to condition models.

The main classes used to achieve this are:

  • CIwModel
  • CIwMenuManager
  • CIwMenuItemGraphics

The main functions used to achieve this are:

  • IwGraphicsInit()
  • CIwTextParserITX::ParseFile()
  • IwGetResManager()
  • CIwResManager::GetGroupNamed()
  • CIwResManager::GetResNamed()

In this example the same GEO file is loaded 5 times, and built into three different binary models. This is done as follows:

Firstly, an ITX file is parsed which creates a named GEO resource template:

 CIwResTemplateGEO
 {
  name "revNorms"
    reverseNorms true
 }

Next, a GROUP file is loaded. The first relevant line is:

 "./Test01.geo" { resName "Test" }

This tells the resource manager to load the file "./Test01.geo". Additionally, the created binary model resource will be named "Test".

The next relevant line is:

 "./Test01.geo" { resName "Test1" buildNorms false }

This tells the resource manager to load the file "./Test01.geo", named the created binary model resource as "Test1", and additionally build the model without vertex normals.

The next relevant line is:

 useTemplate "geo" "revNorms"

This tells the resource manager to use the GEO resource template named "revNorms" to build all future models (until another named template is specified). So the following line:

 "./Test01.geo" { resName "Test2" }
...results in the same GEO file being used to build a third binary model resource, this time named "Test2", and using the settings of the current GEO resource template, which in this case builds the model with reversed normals.

Another two version of the resource are loaded, this time with different scales. Notice how, on these versions, the "revNorms true" setting persists, because it is still set on the current template.

Press the 1 and 2 buttons to cycle the model being displayed. Notice how the scene diffuse lighting changes as we move between the model with default normals, no normals, and reversed normals.

The following graphics illustrates the example output.

Note:
For more information on the loading of meshes from GEO files, see Loading of Models.
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsResourceGroups
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Models[5];

// Timer
uint32      s_Timer;

// Model ID
uint32      m_ModelID = 0;

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->SetXY(0, 50);
    pMenu->AddItem(new CIwMenuItemResManager);
    pMenu->AddItem(new CIwMenuItemGraphics);
#endif
    return pMenu;
}

void CreateButtonsUI(int w, int h)
{
    // Create the UI
    AddButton("Model1: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Model2: 2", 0, 110, 70, 30, s3eKey2);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x00, 0x00, 0xff, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0x200, 0x200, 0);

#ifdef IW_BUILD_RESOURCES
    // Load the resource templates
    IwGetTextParserITX()->ParseFile("ResourceGroups_templates.itx");
#endif

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("ResourceGroups.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointer to the model resource
    s_Models[0] = (CIwModel*)pGroup->GetResNamed("Test", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[1] = (CIwModel*)pGroup->GetResNamed("Test1", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[2] = (CIwModel*)pGroup->GetResNamed("Test2", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[3] = (CIwModel*)pGroup->GetResNamed("Test3", IW_GRAPHICS_RESTYPE_MODEL);
    s_Models[4] = (CIwModel*)pGroup->GetResNamed("Test4", IW_GRAPHICS_RESTYPE_MODEL);

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x0;
    view.t.z = -0x180;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    CIwColour colA = {0x20, 0x20, 0x20, 0xff};
    IwGxSetLightCol(0, &colA);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwColour colD = {0xc0, 0xc0, 0xc0, 0xff};
    IwGxSetLightCol(1, &colD);
    CIwSVec3 dd(0x1000, 0, 0);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetMenuManager();

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Reset metrics
#ifdef IW_DEBUG
    IwGraphicsMetricsReset();
    IwGxMetricsReset();
#endif

    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Increase/decrease model ID
    if (CheckButton("Model1: 1") & S3E_KEY_STATE_PRESSED)
        m_ModelID = (m_ModelID + 1) % 5;
    if (CheckButton("Model2: 2") & S3E_KEY_STATE_PRESSED)
        m_ModelID = (m_ModelID + (5-1)) % 5;

    // Build model matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with full lighting
    IwGxLightingOn();

    //-------------------------------------------------------------------------
    // Render the main model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Models[m_ModelID]->Render();

    // Paint the cursor keys buttons and prompt text
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();
    // Display name of model
    IwGxPrintString( 2, IwGxGetScreenHeight() - 70, s_Models[m_ModelID]->DebugGetName());

    // Render menu manager
    IwGetMenuManager()->Render();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Model Builder Callbacks Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Model Builder Callbacks Example >

IwGraphics Model Builder Callbacks Example

The following example demonstrates conditioning and extending models with model builder callbacks.

The main functions used to achieve this are:

  • SetPreBuildFn()

  • SetPostBuildFn()

When a model is compiled to a binary resource ModelBuilder provides two callback hooks for client programs to alter the model and add their own annotations while the model is in a readable format.

PreBuildFn - this function is called after the GEO has been loaded into the model builder, but before the binary representation is build. Typically this can be used to transform the model data. In this example, PreBuildFn is attached to a function that warps the loaded geometry.

PostBuildFn - this function is called after the GEO has been converted to binary representation, but before it is serialised. This callback is typically used to store additional information about the model which would be difficult, expensive or impossible to extract from the binary version. In this example it stores the vertex indices of faces in a set called "walkable" in a new separate resource CHalo. It then renders them, transformed, in the scene.

A "userString" is supplied to both callbacks which can be specified in the group file to control the behaviour of the callback functions.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModelBuilder
//-----------------------------------------------------------------------------

// @}

#include "IwGraphics.h"
#include "IwGx.h"
#include "IwGxPrint.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "IwModelExt.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Model;

// Custom resource
class CHalo* s_Halo;

// Timer
uint32      s_Timer;

//--------------------------------------------------------------------------------
CIwMenu* DebugCreateMainMenu()
{
    IW_CALLSTACK("DebugCreateMainMenu")

    CIwMenu* pMenu = new CIwMenu;

#ifdef IW_DEBUG
    pMenu->SetXY(0, 50);
    pMenu->AddItem(new CIwMenuItemResManager);
    pMenu->AddItem(new CIwMenuItemGraphics);
    pMenu->AddItem(new CIwMenuItemGx);
#endif
    return pMenu;
}

//-----------------------------------------------------------------------------
// CHalo is a custom resource that is constructed from a geo at ModelParseClose time.
// It is then used to generate some procedural geometry based on a sub set of the model's faces
//-----------------------------------------------------------------------------
class CHalo : public CIwResource
{
public:
    IW_MANAGED_DECLARE(CHalo);

    CHalo() : m_pModel(NULL) {};

#ifdef IW_BUILD_RESOURCES
    void AddFace(CIwFace* pFace, CIwModel* pModel);
    void Finish();
#endif

    // Standard CIwResource interface
    void Serialise();
    void Resolve();
    void Render();

    // helper function for looking up verts from CIwModel's vertex block
    CIwSVec3& GetVert(int32 i)
    {
        return ((CIwSVec3*)m_pModel->GetVerts())[m_Points[i]];
    }

private:
    // The model this halo is based on
    CIwModel* m_pModel;
    // A list of points. Each triplet is one triangle.
    CIwArray<int16> m_Points;
    // A list of weights based on each point's position
    CIwArray<iwfixed> m_Weights;
};
//-----------------------------------------------------------------------------
IW_MANAGED_IMPLEMENT(CHalo);
IW_CLASS_FACTORY(CHalo);
//-----------------------------------------------------------------------------
#ifdef IW_BUILD_RESOURCES
void CHalo::AddFace(CIwFace* pFace, CIwModel* pModel)
{
    // Remember the model
    IwAssert(GRAPHICS, !m_pModel || m_pModel == pModel);
    m_pModel = pModel;

    // Model build info contains information about how the data in the model was re-arranged.
    // Verts may be reordered for cache performance, etc.
    CIwModelBuildInfoMap& map = m_pModel->GetModelBuildInfo().GetMap(IW_MB_STREAM_VERTS);

    // If this face is a triangle...
    if( pFace->GetNumPoints() == 3 )
    {
        for(uint32 i = 0; i < 3; i++)
        {
            CIwArray<uint16> deps;
            map.GetDependents(pFace->GetVertID(i), deps);
            m_Points.push_back(deps[0]);
        }
    }
    else
    {
        // Only support quads
        IwAssert(GRAPHICS, pFace->GetNumPoints() == 4);

        // Add the quad as two triangles
        uint32 i;
        for(i = 0; i < 3; i++)
        {
            CIwArray<uint16> deps;
            map.GetDependents(pFace->GetVertID(i), deps);
            m_Points.push_back(deps[0]);
        }
        for(i = 0; i < 4; i == 0 ? i += 2 : i++)
        {
            CIwArray<uint16> deps;
            map.GetDependents(pFace->GetVertID(i), deps);
            m_Points.push_back(deps[0]);
        }
    }
}
//-----------------------------------------------------------------------------
void CHalo::Finish()
{
    // Calculate centre
    CIwSVec3 centre = CIwSVec3(0,0,0);
    uint32 i;
    for(i = 0; i < m_Points.size(); i++)
    {
        centre += GetVert(i);
    }
    centre = centre / IW_FIXED(m_Points.size());

    // Calculate weight based on distance from centre
    iwfixed farthestPoint = 0;
    for(i = 0; i < m_Points.size(); i++)
    {
        farthestPoint = MAX(farthestPoint, (GetVert(i) - centre).GetLength());
    }

    m_Weights.resize(m_Points.size());
    for(i = 0; i < m_Points.size(); i++)
    {
        m_Weights[i] = IW_FIXED_DIV(MAX(0, farthestPoint - (GetVert(i) - centre).GetLength() - 40), farthestPoint);
    }

}
#endif
//-----------------------------------------------------------------------------
void CHalo::Serialise()
{
    CIwManaged::Serialise();

    IwSerialiseManagedHash(&m_pModel);
    m_Points.SerialiseHeader();
    IwSerialiseInt16(m_Points[0], m_Points.size());
    m_Weights.SerialiseHeader();
    IwSerialiseInt32(m_Weights[0], m_Points.size());
}
//-----------------------------------------------------------------------------
void CHalo::Resolve()
{
    CIwManaged::Resolve();

    IwResolveManagedHash(&m_pModel, IW_GRAPHICS_RESTYPE_MODEL);
}
//-----------------------------------------------------------------------------
void CHalo::Render()
{
    // Create material in gx data cache
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();

    pMat->SetAlphaMode(CIwMaterial::ADD);
    pMat->SetZDepthOfs(-1000);
    pMat->SetCullMode(CIwMaterial::CULL_NONE);

    IwGxLightingOff();

    // Create storage for verts and colours in gx data cache
    CIwSVec3 *pVerts = IW_GX_ALLOC(CIwSVec3, m_Points.size());
    CIwColour *pCols = IW_GX_ALLOC(CIwColour, m_Points.size());

    // Generate target point
    CIwVec3 target(0, IW_FIXED(2.0), IW_FIXED(1.0));
    CIwMat mat;
    mat.SetRotY(IwGeomSin(s_Timer*50));
    target = mat.RotateVec(target);

    // Construct this frame's verts/colours by copying and transforming the model's verts
    // We generate two streams: one of colour and one of verts.
    for(uint32 i = 0; i < m_Points.size(); i++)
    {
        // Blend original position and target position based on weight
        pVerts[i] = target * m_Weights[i] + GetVert(i) * (IW_GEOM_ONE - m_Weights[i]);

        // Ramp opacity based on inverse weight
        int32 col = (IW_GEOM_ONE - m_Weights[i]) * 0xff / IW_GEOM_ONE;
        uint8 col2 = (uint8)MAX(0, col * col * col / 0xff / 0xff - 0x80);
        pCols[i].Set(col2,col2,col2);
    }

    // Set up for render...
    IwGxSetMaterial(pMat);
    IwGxSetVertStreamModelSpace(pVerts, m_Points.size());
    IwGxSetNormStream(NULL, 0);
    IwGxSetColStream(pCols, m_Points.size());

    // And render
    IwGxDrawPrims(IW_GX_TRI_LIST, NULL, m_Points.size());
}
//-----------------------------------------------------------------------------
#ifdef IW_BUILD_RESOURCES
void ConditionModel(const char* pUserString)
{
    //check user string to test whether to affect this asset
    if( strcmp(pUserString, "level") != 0 )
        return;

    // Loop over model builder verts...
    uint32 i;
    for( i = 0; i < IwGetModelBuilder()->GetNumVerts(); i++)
    {
        CIwFVec3& v = IwGetModelBuilder()->GetVert(i);
        // Applying a transformation (linear stretch based on y value)
        v *= 0.5f + (v.y + 10.0f) * 0.001f;
    }
}
//-----------------------------------------------------------------------------
void BuildHalo(const char* pUserString, CIwModel* pModel)
{
    //check user string to test whether to affect this asset
    if( strcmp(pUserString, "level") != 0 )
        return;

    // Create a new halo resource and name it after its model partner
    CHalo* pHalo = new CHalo;
    pHalo->SetName(pModel->DebugGetName());

    IW_MANAGED_LIST_ITERATE(pModel->m_Exts, itE)
    {
        // Only interested in face selection sets
        if (strcmp((*itE)->GetClassName(), "CIwModelExtSelSetFace")!=0)
            continue;

        const char* name = (*itE)->DebugGetName();

        if (!name) continue;
        CIwModelExtSelSetFace* pSet = (CIwModelExtSelSetFace*)(*itE);

        if (!strcmp(name, "walkable"))
        {
            for(uint32 i = 0; i < pSet->m_FaceIDs.size(); i++)
            {
                pHalo->AddFace(IwGetModelBuilder()->GetFace(pSet->m_FaceIDs[i]), pModel);
            }

            // We'll transform the set into a halo resource, so there's no need to keep it in the model binary
            delete pSet;
            pModel->m_Exts.RemoveSlow(pSet);
            itE--;  // So we don't miss a set!
        }
    }

    // Now that all faces have been added to the halo do some final calculations
    pHalo->Finish();

    // Add the halo resource to IwResManager - it will be serialised as part of the current group.
    IwGetResManager()->AddRes("CHalo", pHalo);
}
#endif

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();

    IW_CLASS_REGISTER(CHalo);

    // Set screen clear colour
    IwGxSetColClear(0x00, 0x00, 0xff, 0x00);

    // Set field of view
    IwGxSetPerspMul(0xa0);

    // Set near and far planes
    IwGxSetFarZNearZ(0x2000, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0x200, 0x800, 0);

    // If configured to support HW, then build model for HW
#ifdef IW_BUILD_RESOURCES
    // Load the resource templates
    IwGetTextParserITX()->ParseFile("ModBuild_templates.itx");

    // Register the model builder callbacks
    IwGetModelBuilder()->SetPreBuildFn(&ConditionModel);
    IwGetModelBuilder()->SetPostBuildFn(&BuildHalo);
#endif

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("ModBuildCallbacks.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointers to the model resources
    s_Model = (CIwModel*)pGroup->GetResNamed("lava", IW_GRAPHICS_RESTYPE_MODEL);
    s_Halo = (CHalo*)pGroup->GetResNamed("lava", "CHalo");

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x80;
    view.t.z = -0x800;
    IwGxSetViewMatrix(&view);

    //-------------------------------------------------------------------------
    // Set up scene lighting
    //-------------------------------------------------------------------------
    // Set single ambient light
    IwGxSetLightType(0, IW_GX_LIGHT_AMBIENT);
    CIwColour colA = {0x40, 0x40, 0x40, 0xff};
    IwGxSetLightCol(0, &colA);

    // Set single diffuse light
    IwGxSetLightType(1, IW_GX_LIGHT_DIFFUSE);
    CIwColour colD = {0xc0, 0xc0, 0xc0, 0xff};
    IwGxSetLightCol(1, &colD);
    CIwSVec3 dd(0x93c, 0x93c, 0x93c);
    IwGxSetLightDirn(1, &dd);

    // Set up the menu manager
    new CIwMenuManager;
    IwGetMenuManager()->SetTextCallback(IwGxPrintMenuCallback);
    IwGetMenuManager()->SetMainMenuFn(DebugCreateMainMenu);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetMenuManager();

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Reset metrics
#ifdef IW_DEBUG
    IwGraphicsMetricsReset();
    IwGxMetricsReset();
#endif
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Move camera in/out
    if (CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN)
        s_ModelMatrix.t.z += 0x40;
    if (CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN)
        s_ModelMatrix.t.z -= 0x40;

#ifdef IW_DEBUG
    // Toggle flag to display chunks in debug colours
    if (s3eKeyboardGetState(s3eKeyD) & S3E_KEY_STATE_PRESSED)
    {
        if (IwGraphicsGetDebugFlags() & IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F)
            IwGraphicsClearDebugFlags(IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F);
        else
            IwGraphicsSetDebugFlags(IW_GRAPHICS_DEBUG_MODEL_COLOUR_CHUNKS_F);
    }
#endif

    // Build model matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update timer
    s_Timer++;

    // Update menu manager
    IwGetMenuManager()->Update();

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with full lighting
    IwGxLightingOn();

    //-------------------------------------------------------------------------
    // Render a background poly
    //-------------------------------------------------------------------------
    CIwSVec2* pVec = AllocClientScreenRectangle();
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
    pMat->Init();
    pMat->SetColAmbient(0, 0, 255, 255);
    IwGxSetMaterial(pMat);
    IwGxSetVertStreamScreenSpace(pVec, 4);
    IwGxSetScreenSpaceSlot(-1);
    IwGxDrawPrims(IW_GX_QUAD_STRIP, NULL, 4);
    IwGxSetScreenSpaceSlot(0);

    //-------------------------------------------------------------------------
    // Render the main model and the halo
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Model->Render();
    s_Halo->Render();

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Render menu manager
    IwGetMenuManager()->Render();
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics GLES2 Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics GLES2 Example >

IwGraphics GLES2 Example

This example demonstrates the loading of a model resource which includes a custom GLES 2.0 shader, changing shader parameters in realtime and rendering of the model.

This example builds on the IwGraphicsModel example.

The main classes used to achieve this are:

  • CIwGxShaderTechnique

  • CIwGxShaderUniform

After the resources have been loaded, the shader technique is retrieved from ResManager. The shader technique resource is a standard CIwResource.

The shader in this example exposes one of its uniforms as a parameter. A pointer to this parameter (as a CIwGxShaderUniform) can be retrived using the GetParam method of the CIwGxShaderTechnique.

CIwGxShaderUniform::Set methods can be used to change the value of the parameter in realtime.

The following graphic illustrates the example output.

Note:
If the example is run with SW rendering or the GLES 1.x API (the default) the model will appear without the shader effect, and will render normally. The second texture will be ignored. In this way, data sets can be build that scale from SW to GLES 2.0
/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsModel
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "IwModel.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwGx.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Model resource
CIwModel*   s_Model;
CIwTexture* s_Texture;
CIwGxShaderUniform* s_Param;

float s_UniformValue = 0.5f;

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(0x4f0 * IwGxGetScreenHeight() / 320);

    // Set near and far planes
    IwGxSetFarZNearZ(0x400, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0x800, 0);

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("GLES2.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("Example");

    // Get and store pointer to the model resource
    s_Model = (CIwModel*)pGroup->GetResNamed("FunkyVicGLES2", IW_GRAPHICS_RESTYPE_MODEL);

    // Get a pointer to the background texture
    s_Texture = (CIwTexture*)pGroup->GetResNamed("largeAirplayLogo", "CIwTexture");

    // Get a pointer to the shader
    CIwGxShaderTechnique* technique =
        (CIwGxShaderTechnique*)pGroup->GetResNamed("FunkyShader", "CIwGxShaderTechnique");

    // Get the parameter we're interested in
    s_Param = technique->GetParam("refractiveIndex");

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x100;
    view.t.z = -0x180;
    IwGxSetViewMatrix(&view);

    if( IwGxGetHWType() == IW_GX_HWTYPE_GL2 )
    {
        //Add buttons
        AddButton("Toggle shaders", 0, 60, 100, 30, s3eKey1);
        AddButton("Increase refractiveIndex", 0, 95, 150, 30, s3eKey2);
        AddButton("Decrease refractiveIndex", 0, 135, 150, 30, s3eKey3);
    }
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    if( CheckButton("Toggle shaders") & S3E_KEY_STATE_PRESSED )
    {
        // The IW_GX_DISABLE_CUSTOM_SHADERS_F flag can be used to disable custom shading
        // In this mode, gx will use its default shaders to replicate gles 1.x mode.
        if( IwGxGetFlags() & IW_GX_DISABLE_CUSTOM_SHADERS_F )
        {
            IwGxClearFlags(IW_GX_DISABLE_CUSTOM_SHADERS_F);
        }
        else
        {
            IwGxSetFlags(IW_GX_DISABLE_CUSTOM_SHADERS_F);
        }
    }

    if( CheckButton("Increase refractiveIndex") & S3E_KEY_STATE_DOWN )
    {
        s_UniformValue += 0.1f;
    }
    if( CheckButton("Decrease refractiveIndex") & S3E_KEY_STATE_DOWN )
    {
        s_UniformValue -= 0.1f;
    }

    // Set the shader uniform parameter. Various overloads are provided for common Airplay Studio types.
    if( s_Param )
    {
        s_Param->Set(s_UniformValue);
    }
    // Build view matrix rotation from angles
    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    s_ModelMatrix.CopyRot(rotY * rotX);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the Backdrop
    //-------------------------------------------------------------------------
    IwGxSetScreenSpaceSlot(-1);
    CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
    pMat->SetTexture(s_Texture);
    pMat->SetColAmbient(0xffffffff);
    IwGxSetMaterial(pMat);
    CIwSVec2 wh((int16)IwGxGetScreenWidth(), (int16)IwGxGetScreenHeight());
    IwGxDrawRectScreenSpace(&CIwSVec2::g_Zero, &wh);

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);
    s_Model->Render();

    // Paint the cursor keys buttons and prompt text
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    if( IwGxGetHWType() != IW_GX_HWTYPE_GL2 )
    {
        IwGxPrintString(2, IwGxGetScreenHeight() - 90, "Select Configuration->GL and set the GLES API to gles 2.0 to see the shaders added to this model.", true);
    }

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwGraphics Scalable Pipeline Example

Airplay API Reference > IwGraphics API Documentation > IwGraphics Examples > IwGraphics Scalable Pipeline Example >

IwGraphics Scalable Pipeline Example

IwGx provides extensive support for assets that render using the resources available on the device.

This example demonstrates the rendering of a scene using a minimal number of duplicated assets and other automatic scaling.

Of particular interest is:

  • Using IwGx to automatically display the same content with different effects in different renderers
  • Use of resource styles to use a simplified asset for SW rendering
  • Use of IwGxGetHwType() to dynamically scale client-side effects

Use the windows simulator GL configuration menu to change which renderer is available.

The example can be deployed to various devices and will render in one of three modes:

If no HW accelerated rendering is available it will render using the SW renderer. In this mode it uses a lower resolution bike asset.

If an OpenGL ES 1.x renderer is available it will render using OpenGL ES 1.x. This includes an example of using EFFECT_NORMAL_MAPPING_SPECULAR to do specular normal mapping using the OpenGL ES 1.x fixed function pipeline.

If OpenGL ES 2.x is available it will use that. Custom shaders add a specular normal mapping with a reflection of the Airplay Logo on the TV screen. IwGxSurface is used to produce a bloom effect.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */
// ExampleIwGraphicsScalablePipeline
//-----------------------------------------------------------------------------

#include "IwGraphics.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;
iwfixed     s_Zoom;

CIwMat s_BikeMat;

// Model resources
CIwResList* s_BikeModelList;
CIwResList* s_EnvModelList;

// Handles to shaders and surfaces
CIwGxShaderTechnique* s_BikeShader;
CIwGxShaderTechnique* s_PostProcessShader;
CIwGxShaderTechnique* s_BloomBufferShader;
CIwGxSurface* s_OffscreenSurface;
CIwGxSurface* s_BloomBuffer;

// Relative size of the bloom buffer in GLES2
// Increasing this number will increase the spread of the bloom at the expense of accuracy
#define BLOOM_DIM 2

//-----------------------------------------------------------------------------
void ResizeSurfaces()
{
    int height = IwGxGetScreenHeight();
    int width = IwGxGetScreenWidth();

    s_OffscreenSurface->RecreateSurface(width, height);

    width /= BLOOM_DIM;
    height /= BLOOM_DIM;
    s_BloomBuffer->RecreateSurface(width, height);
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set near and far planes
    IwGxSetFarZNearZ(0x7fff, 0x10*10);

    // Initialise angles
    s_Angles = CIwSVec3(4032, 29888, 0);
    s_Zoom = IW_FIXED(0.5);

    // Parse the GROUP file, which will load the model, its materials and textures
    IwGetResManager()->LoadGroup("IwGraphicsScalablePipeline.group");

    // A group file is a resource bundle containing a number of resource types.
    // This example uses one group for the bike and turntable and one group for the environment.
    s_BikeModelList = IwGetResManager()->GetGroupNamed("bike")->GetListNamed("CIwModel");
    s_EnvModelList = IwGetResManager()->GetGroupNamed("env")->GetListNamed("CIwModel");

    // Retrieve a handle to the shader for dynamic parameter editing
    s_BikeShader = (CIwGxShaderTechnique*)IwGetResManager()->GetResNamed("normal_specular", "CIwGxShaderTechnique");
    s_PostProcessShader = (CIwGxShaderTechnique*)IwGetResManager()->GetResNamed("postprocess", "CIwGxShaderTechnique");
    s_BloomBufferShader = (CIwGxShaderTechnique*)IwGetResManager()->GetResNamed("bloombuffer", "CIwGxShaderTechnique");

    // Initialise the transform for the bike and turntable
    s_BikeMat = CIwMat::g_Identity;

    // Set up the view matrix
    CIwMat view;
    view.SetRotZ(0x800);
    view.t.y =  0x80*10;
    view.t.z = -0x180*10;
    IwGxSetViewMatrix(&view);

    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);

    //Create render targets for GL2
    if( IwGxGetHWType() == IW_GX_HWTYPE_GL2 )
    {
        int height = IwGxGetScreenHeight();
        int width = IwGxGetScreenWidth();

        s_OffscreenSurface = new CIwGxSurface();
        s_OffscreenSurface->CreateSurface(NULL, width, height, CIwGxSurface::EXACT_MATCH_F);

        width /= BLOOM_DIM;
        height /= BLOOM_DIM;
        s_BloomBuffer = new CIwGxSurface();
        s_BloomBuffer->CreateSurface(NULL, width, height, CIwGxSurface::EXACT_MATCH_F);

        IwGxRegister(IW_GX_SCREENSIZE, ResizeSurfaces);
    }

}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete s_OffscreenSurface;
    delete s_BloomBuffer;

    // Terminate
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_Zoom += IW_FIXED(0.05);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_Zoom -= IW_FIXED(0.05);

    // Restrict the zoom level to know safe values.
    s_Zoom = MAX(IW_FIXED(0.125), MIN(s_Zoom, IW_FIXED(0.25)));

    // Rotate the bike at a constant rate.
    CIwMat rot;
    rot.SetRotY(2);
    s_BikeMat.PostMult(rot);
    s_BikeMat.Normalise();

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

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Build view matrix rotation from angles
    CIwMat view;
    view.SetRotZ(0x800);
    view.t = CIwVec3(0, 0x80*10, -0x480*10) * s_Zoom;

    CIwMat rotX, rotY;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    view *= rotX * rotY;

    view.t += CIwVec3(-0x200, 0x20*10, 0);

    //Restrict y to be inside the room
    view.t.y = MAX(0, MIN(view.t.y, 151*10));

    //Pass the view matrix to gx
    IwGxSetViewMatrix(&view);

    // Configure the pipeline according to HW type
    if( IwGxGetHWType() == IW_GX_HWTYPE_GL2 )
    {
        //Use HW tnl in OpenGL ES 2.0 for clarity in the shaders.
        IwGxSetTransformHW();
        IwGxSetLightingHW();
    }
    else
    {
        //Use SW tnl in OpenGL ES 1.0+ for normal mapping where available.
        //SW Rasterisation is always SW t/l anyway
        IwGxSetTransformSW();
        IwGxSetLightingSW();
    }

    if( s_OffscreenSurface )
    {
        s_OffscreenSurface->MakeCurrent();
    }

    // Set field of view - we maintain a fixed horizontal field of view
    IwGxSetPerspMul(IwGxGetDisplayWidth()*0xa0/320);

    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    IwGxFogOn();
    IwGxSetFogFarZNearZ(800*10, 450*10);

    //Configure the bike's shader

    //GetParam returns the uniform parameter object, which can then be set to control the
    //vertex/fragment shader

    //Set the size of the TV Screen
    s_BikeShader->GetParam("inTVScale")->Set(0.0005f);

    //Parameters which are set in worldspace will be transformed by the framework to the
    //appropriate local coordinate space. In this case, they will be passed to the shader
    //in the bike's model space, so they can be compared directly to vertices and normals
    //in the vertex shader.
    s_BikeShader->GetParam("inEyePos")->SetWorldSpace(view.t);

    //Build a basis for the animated TV screen
    CIwMat tvMat;
    tvMat.SetRotY(-IW_GEOM_ONE/4);
    tvMat.t = CIwVec3(-2000, 500, 1100);

    s_BikeShader->GetParam("inTVPos")->SetWorldSpace(tvMat.t);
    CIwGxShaderUniform* orient = s_BikeShader->GetParam("inTVOrient");
    orient->SetWorldSpaceDirection(tvMat.RowX(), 0);
    orient->SetWorldSpaceDirection(tvMat.RowY(), 1);
    orient->SetWorldSpaceDirection(tvMat.RowZ(), 2);

    //Configure lighting environment
    //Note that in OpenGL ES 2.0, the shader consumes these values passed from the framework.
    IwGxLightingAmbient(true);
    IwGxLightingEmissive(false);
    IwGxLightingDiffuse(true);
    IwGxLightingSpecular(true);

    //Set an ambient term
    IwGxSetLightType(1, IW_GX_LIGHT_AMBIENT);
    CIwColour c;
    c.Set(0x80,0x80,0x80,0xff);
    IwGxSetLightCol(1, &c);

    //Set a single directional light
    IwGxSetLightType(0, IW_GX_LIGHT_DIFFUSE);
    CIwSVec3 dir = CIwSVec3(IW_GEOM_ONE,-IW_GEOM_ONE, IW_GEOM_ONE);
    dir.Normalise();
    IwGxSetLightDirn(0, &dir);

    //-------------------------------------------------------------------------
    // Render the models
    //-------------------------------------------------------------------------

    //Render the environment using the identity matrix
    IwGxSetModelMatrix(&CIwMat::g_Identity);

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

    //Render the bike and turntable using the rotating matrix
    IwGxSetModelMatrix(&s_BikeMat);

    for(i = 0; i < s_BikeModelList->m_Resources.GetSize(); i++)
    {
        CIwModel* pModel = (CIwModel*)s_BikeModelList->m_Resources[i];
        pModel->Render();
    }

    if( s_OffscreenSurface )
    {
        IwGxFlush();

        //Render a smaller version of the frame buffer,
        //transforming into a fake HDR version using the bloombuffer shader

        //Select the bloom buffer target as the current surface
        s_BloomBuffer->MakeCurrent();

        //Render the frame through the shader
        {
            IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

            CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();
            pMat->SetTexture(s_OffscreenSurface->GetTexture());
            pMat->SetShaderTechnique(s_BloomBufferShader);
            IwGxSetMaterial(pMat);
            CIwSVec2 wh((int16)IwGxGetDisplayWidth(), (int16)IwGxGetDisplayHeight());
            CIwSVec2 xy(0,0);
            CIwSVec2 uvxy(0, 0);
            CIwSVec2 uvwh(s_OffscreenSurface->GetClientUVExtent());
            IwGxDrawRectScreenSpace(&xy, &wh, &uvxy, &uvwh);
        }

        IwGxFlush();

        //Now composite the frame buffer and the bloom buffer using the postprocess shader

        //Select the back buffer as the current surface
        CIwGxSurface::MakeDisplayCurrent();

        //Render the buffers through the shader
        {
            IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

            CIwMaterial* pMat = IW_GX_ALLOC_MATERIAL();

            //Select the original surface and the bloom surface into the material
            pMat->SetTexture(s_OffscreenSurface->GetTexture());
            pMat->SetTexture(s_BloomBuffer->GetTexture(), 1);

            pMat->SetShaderTechnique(s_PostProcessShader);

            IwGxSetMaterial(pMat);
            CIwSVec2 xy(0,0);
            CIwSVec2 wh((int16)IwGxGetScreenWidth(), (int16)IwGxGetScreenHeight());
            CIwSVec2 uvxy(0, 0);
            IwGxDrawRectScreenSpace(&xy, &wh, &uvxy, &s_OffscreenSurface->GetClientUVExtent());
        }
    }

    IwGxPrintString( 2,  40, "`x000000Rotate Model: Arrow Keys" );

    // Rendering the frame buffer will have removed the example framework buttons,
    // So render them again
    RenderButtons();
    RenderSoftkeys();
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim API Documentation

Airplay API Reference > IwAnim API Documentation >

IwAnim API Documentation

The IwAnim documentation contains the following sections:

  • IwAnim API Overview
  • IwAnim API Reference
  • IwAnim Examples


Airplay API Reference: IwAnim API Overview

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview >

IwAnim API Overview

To use IwAnim functionality, you must include "IwAnim.h" in your source and iwanim as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwanim
  • }

When using IwAnim, the following modules do not need to be specified in your project's MKB as they will be implicitly included as subprojects of this module:

  • IwUtil
  • IwGeom
  • IwResManager
  • IwGx
  • IwGraphics

IwGx is based around geometry streams, transform state, lighting state, textures and materials (similar to OpenGL or DirectX).

IwGraphics provides the ability to process and display static models. IwAnim provides the facility to modify the vertices of a static model, by "weighting" each vertex to a combination of bone transforms in a skeleton. The process of weighting vertices to bones is known as "skinning".

A bone might correspond to a body part such as a hand, fore-arm, or upper arm. Bones are connected together in parent/child relationships to form a skeleton. For example, the fore-arm bone would have the upper arm bone as its parent, and the hand bone as its child. The hand bone would have the fore-arm bone as its parent, and would have no child bones. Skeletons do not have to correspond to characters -they can represent any form of bone hierarchy.

An animation is a series of "keyframes". Each keyframe is associated with an elapsed time since the start of the animation, and contains a list of bone transforms, which are associated by name with the bones of the skeleton.

An "animation player" contains pointers to a skeleton and various animations. As time elapses, the bone transforms from different keyframes are interpolated and blended to form a final series of transforms which are used to perform the skinning calculation.

Animated models are rendered using the standard static model rendering system. Before the static model is rendered, the user sets a "skin context" and a "skeleton context". The model will already have been pre-processed so that its vertex block will use a special render function within the IwAnim module. This special render function performs the skinning calculations, using the current skeleton context (i.e., the final series of bone transforms).

The workflow for using IwAnim is as follows. Let's assume we wish to display a character running on the spot.

  • In the desired modelling package, create the static character model in some fixed pose. This pose is usually referred to as the "bind pose", and is traditionally an upright stance with arms outstretched.
  • In the desired modelling package, create the character skeleton. This will typically contain between 11 and 20 bones.
  • In the desired modelling package, create the skinning data, to weight each model vertex to a combination of up to 4 bones.
  • In the desired modelling package, create the running animation.
  • Then using the Airplay exporter, export the following files:
    • GEO and MTL files, corresponding to the standard static model.
    • SKIN file, containing the skinning data.
    • SKEL file, containing the skeleton data.
    • ANIM file, containing a series of keyframes, representing the running animation.
  • Create a GROUP file, and add lines pointing to the GEO, SKIN, SKEL and ANIM files.
  • Now in your code, load the resource group, and obtain pointers to the GEO, SKIN, SKEL and ANIM resources (of type CIwModel, CIwAnimSkin, CIwAnimSkel and CIwAnim respectively). Now create a CIwAnimPlayer object and point it to the required resources.

The following subjects are contained within this section:

  • IwAnim Initialisation and Termination
  • IwAnim State
  • Skeleton
  • Skin
  • Animation
  • Animation Player
  • Playing a Single-Boned Animation
  • Blending
  • Offset Animation
  • IwAnim Metrics


Airplay API Reference: IwAnim Initialisation and Termination

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > IwAnim Initialisation and Termination >

IwAnim Initialisation and Termination

The user must initialise IwAnim and terminate IwAnim as follows:

  • // Begin application
  • IwGxInit();
  • IwGraphicsInit();
  • IwAnimInit();

    • ...rest of application

  • // End application
  • IwAnimTerminate();
  • IwGraphicsTerminate();
  • IwGxTerminate();

IwAnimInit() creates a CIwAnimState object. IwAnimTerminate() destroys the CIwAnimState object.

It is illegal to call any IwAnim function or create any IwAnim class before calling IwAnimInit().


Airplay API Reference: IwAnim State

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > IwAnim State >

IwAnim State

The entire IwAnim state is contained within the IwAnimState object. This object is hidden from the user.

This state object includes information like the current skeleton and skin context used when rendering a skinned model.

IwAnim API calls are used to write to and read from the state.


Airplay API Reference: Skeleton

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Skeleton >

Skeleton

A "skeleton" is simply a list of "bones". Each bone contains a pointer to its parent bone (or NULL if it is the root bone in the skeleton) and pointers to any child bones.

CIwAnimSkel is the skeleton object, and is used in two ways.

  • As a resource, loaded from a SKEL file. The skeleton resource defines both the bone hierarchy (parent/child relationships between bones) and the "bind pose" of the skeleton. The bind pose is the pose in which the vertex skinning data is defined (see CIwAnimSkin), and matches up with the shape of the corresponding static model.
  • As a modifiable list of transforms contained within an "animation player" object (see CIwAnimPlayer). The animation player object contains a skeleton object into which it writes final blended bone transforms to be used when rendering the skinned model.

Each bone (CIwAnimBone) contains a position and rotation relative to its parent bone. It also contains a matrix, which holds the final blended modelspace matrix for the bone. These matrices are used by the skinning render code.

CIwAnimSkel contains methods for getting hold of bones by name. The CIwAnimBone object contains methods for getting and setting translations and rotations. In this way, the user can track bone transforms (for example, to obtain a character's hand position), and can also modify animation transforms (for example, to make a character's head turn towards an object, whilst the character is already performing an animation).

Note:For an example of how skeletons are used in an application, see the Animation Skeleton Example.


Airplay API Reference: Skin

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Skin >

Skin

A "skin" is a list of "weights" for each vertex in the corresponding static model. Each skin is associated with a particular model and skeleton, which together represent the "bind pose".

CIwAnimSkin is the skin object, and is created as a resource by loading a SKIN file, exported from a modelling tool.

For each vertex in the corresponding model, it contains a list of up to 4 (bone ID, bone weight) pairs. The bones are taken from the corresponding skeleton.

For example, say we have a static character model, where vertex number 50 is part of the left elbow. We would want to "skin" this vertex to two bones; the left upper arm bone, and the left lower arm bone. Suppose that, within the character skeleton, the left upper arm bone ID = 5, and the left lower arm bone ID = 6. Suppose also that we wish to weight the vertex mainly to the the upper bone, but slightly to the lower bone.

Then, conceptually, our list of pairs for vertex 50 might look something like:(5, 75%), (6, 25%)

Before rendering the character, we set a "skin context" (the skin resource) and a "skeleton context" (typically the local skeleton from an animation player). We then render the static character model. The model vertex block will already have been set to point to a special "skinning" render function, which will use the vertex weights, together with the static model vertices, and the skeleton transforms, to calculate the new skinned vertices to render.

Note that "skinning" is a relatively expensive operation. Care should be taken to ensure that skinned models have as few vertices as possible. Also, reducing the number of weights per vertex will increase performance; so if possible, use a maximum of 2 weights per vertex (up to 4 are supported).

The CIwAnimSkin object is not generally interrogated by the user, so offers a very limited public API.


Airplay API Reference: Animation

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Animation >

Animation

An "animation" is a list of "keyframes". Each keyframe is associated with an elapsed time since the beginning of the animation, and contains an array of bone transformations. By interpolating between keyframes, we can calculate the required bone transformations for any elapsed animation time.

CIwAnim is the animation object, and is created as a resource by loading an ANIM file, exported from a modelling tool.

CIwAnim contains methods for getting the number of keyframes, the duration of the animation, the number of bones used by the animation, and others.

It can be useful for animations to contain only a single bone. These can be used for example to define camera animations in a modelling package, and export them into the application. A seperate SKEL file is not required to play a single-boned animation.


Airplay API Reference: Animation Player

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Animation Player >

Animation Player

CIwAnimPlayer is the "animation player" object, and is at the heart of the IwAnim API.

The CIwAnimPlayer API allows the user to play animations at any speed, forwards or backwards, looping or "one-shot". It allows pausing and restarting, explicit setting of the elapsed animation time, and blending between multiple animations.

The animation player must be fed two types of resources; a skeleton, and multiple animations. The skeleton defines the bone hierarchy which the animations are played on. Any submitted animations must match the bone hierarchy of the skeleton.

For example, suppose we have modelled, rigged, skinned and animated a character in the modelling package, and exported the following files:

  • hero.geo - static model
  • hero.skin - skinning data
  • hero.skel - skeleton
  • run.anim - run animation

We have loaded a resource group containing these resources. To use CIwAnimPlayer, we would get hold of the resources, and set up the player as follows:

  • // Get current resource group
  • CIwResGroup* pGroup = IwGetResManager()->GetCurrentGroup();
  • // Get pointers to loaded resources
  • CIwModel* s_Model = (CIwModel*)pGroup->GetResNamed("hero", IW_GRAPHICS_RESTYPE_MODEL);
  • CIwAnimSkin* s_Skin = (CIwAnimSkin*)pGroup->GetResNamed("hero", IW_ANIM_RESTYPE_SKIN);
  • CIwAnimSkel* s_Skel = (CIwAnimSkel*)pGroup->GetResNamed("hero", IW_ANIM_RESTYPE_SKELETON);
  • CIwAnim* s_Anim = (CIwAnim*)pGroup->GetResNamed("run", IW_ANIM_RESTYPE_ANIMATION);
  • // Create animation player, and set skeleton resource once
  • CIwAnimPlayer* s_Player = new CIwAnimPlayer;
  • s_Player->SetSkel(s_Skel);
  • // Play animation, at half speed, looping
  • s_Player->PlayAnim(s_Anim, IW_GEOM_ONE/2, CIwAnimBlendSource::LOOPING_F);

Note:For an example of how the animation player is used in an application, see the Animation Playback Example.


Airplay API Reference: Playing a Single-Boned Animation

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Playing a Single-Boned Animation >

Playing a Single-Boned Animation

An animation with only a single bone can be played without a seperate skeleton. In this case the animation player does not require a skeleton to be set.

The application can use the single bone to get the current matrix of the animation for positioning models, placing effects, placing cameras, etc.

  • CIwAnimPlayer* player;//animation player
  • CIwMat worldMat;
    • //world position/orientation
  • CIwModel* model;
    • //model to render
  • //Get the bone
  • CIwAnimBone* bone = player->GetSkel()->GetBoneFromID(0);
  • //Use the bone interface to set a model matrix
  • bone->SetModelMatrix(worldMat);
  • //Render a model in the worldMat basis with the animation applied
  • model->Render();
  • //Extract the animation matrix for camera moves, effects, etc.
  • CIwMat boneWorldMat = worldMat * bone->GetMat();

See Animation Single Bone Example for a complete example of animation using a single bone.


Airplay API Reference: Blending

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Blending >

Blending

The animation player provides support for "blending". Blending provides two features:

  • Smooth Transitions between animations.
  • Overlaying Multiple Animations on top of each other.


Airplay API Reference: Smooth Transitions

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Blending > Smooth Transitions >

Smooth Transitions

Let's suppose your character is playing an "idle" animation; moving subtly, and occasionally turning his head. The player presses "go", and now you wish to play a "running" animation. If we switch immediately from one animation to the other, the bone transforms for the start of the "running" animation are likely to be quite different from the bone transforms from the current position within the "idle" animation, resulting in a visible "glitch" as we change from one animation to the other.

To solve this, rather than switching immediately to the new animation, we can define a period of time (known as the "blend duration") over which we will "blend out" the previous animation, and "blend in" the new animation. When this period has elapsed, the new animation will be completely blended in and will continue playing.

When playing any animation, the user can specify the blend duration over which to blend in any existing animation. The default behaviour is to blend in the new animation over a period of 0.25 of a second.

Note: For more information on how to set the blend duration, see the CIwAnimPlayer::PlayAnim() documentation in the IwAnim API Reference.

Support for smooth transitions is handled using two "blend sources". A blend source (CIwAnimBlendSource) is the workhorse object which plays a single animation on a skeleton. The CIwAnimPlayer maintains two main blend sources, current and previous. Generally, only the "current" source is used (see CIwAnimPlayer::GetSourceCurr()). However, if an animation is playing, and the user asks to play a new animation, the full state of the "current" source is copied onto the "previous" source and the new animation becomes "current". Both animations are then blended, moving from "previous" to "current" over the set blend duration. In moving from previous to current the CIwAnimPlayer is updated, both sources are updated, as well as a blend parameter (the blend parameter represents the blend duration as a single unit) which ramps down from 1 to 0 over the specified blend duration. Once the parameter reaches 0, the "previous" source is reset and is no longer used.

Note: For more information on blending of animations, see CIwAnimBlendSource in the IwAnim API Reference.


Airplay API Reference: Overlaying Multiple Animations

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Blending > Overlaying Multiple Animations >

Overlaying Multiple Animations

We have already seen how two full-skeleton animations can be blended together, to smooth out the change from one animation to another. In addition, the CIwAnimPlayer allows up to two additional animations to be "overlaid" on top.

For example, say we have a character who is alternating between "idle" and "running" animations. We also have animations for raising the arms to hold a gun in front of the body ("gun_front"), and for raising the arms to hold the gun above the head ("gun_above"). These animations have been exported as "sub-skeleton" animations from the modelling tool; i.e., they only contain bone transforms for the relevant bones (the shoulders, arms and hands - not the lower body and legs).

At any time, we can decide to overlay "gun_above" or "gun_front" on top of the existing full-skeleton animation. It doesn't matter if the character is idle, running, or somewhere in between. We use CIwAnimPlayer::PlaySubAnim() to overlay a sub-skeleton animation on top of the existing full-skeleton animation(s). In this case, the specified blend duration simply dictates the period of time over which to "blend in" the sub-skeleton animation. By calling CIwAnimPlayer::ClearSubAnim(), we can remove the sub-skeleton animation, and again we can specify a period of time over which to "blend out" the sub-skeleton animation.

Note: For an example of how sub skeletons are used in an application, see the Animation SubSkeleton Example


Airplay API Reference: Offset Animation

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > Offset Animation >

Offset Animation

It is often useful to split the gross movement of a character from the detailed animation. This allows the application engine to track and even override the gross movement with its own collision or application controls.

Offset animations can be exported using the Airplay Studio Exporter and sit alongside the main anim with a suffix, e.g., "MainAnimName_offset.anim". As the offset is exported, the same motion is subtracted from the other bones when they are saved as the main anim.

When the main anim is loaded any matching "..._offset.anim" file is loaded and stored within the CIwAnim.

As the main anim plays back the offset anim plays in sync.

It is up to the application engine to apply the offset back onto the detailed movement, or perhaps override this movement with its own. It is straight forward to get the current offset anim matrix and set this as the model matrix for the render.


Airplay API Reference: IwAnim Metrics

Airplay API Reference > IwAnim API Documentation > IwAnim API Overview > IwAnim Metrics >

IwAnim Metrics

For Debug builds, IwAnim maintains many useful metrics which can be inspected by the user. For example, the user can track the number of vertices skinned, the number of bones interpolated, etc.

There are two main ways of inspecting the metrics:

  • Using the debug menu system: See the IwUtil documentation for details of using the debug menu system. Add the main IwAnim debug menu to your top-level menu:
    • // Assume pMenu is the top-level debug menu
    • pMenu->AddItem(new CIwMenuItemAnim);

    This will allow you to access a menu of all the IwAnim metrics.

    Note: See the IwAnim API Reference for a full list of the IwAnim metrics.

  • Explicitly interrogating specific metrics: Use the IW_ANIM_METRIC_GET macro to return the current value of a named IwAnim metric.

Note: The input to the macro is the full IwAnim metric name, but without the IW_ANIM_METRIC_ prefix.


Airplay API Reference: IwAnim API Reference

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference >

IwAnim API Reference

Modules

Animation Bone.
Animation
Initialisation and Termination
General State
Animation Player
Skeleton
Skin
IwResHandler


Airplay API Reference: Animation Bone.

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Animation Bone. >

Animation Bone.
[IwAnim API Reference]

Data Structures

class CIwAnimBone

Detailed Description

Bone within a skeleton.

Note:
For more information on skeleton animation, see Skeleton section in the IwAnim API Documentation.


Airplay API Reference: Animation

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Animation >

Animation
[IwAnim API Reference]

Data Structures

class CIwAnim

Detailed Description

Animation to play on a skeleton.

Note:
For more information on creating an animation, see Animation section in the IwAnim API Documentation.


Airplay API Reference: Initialisation and Termination

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Initialisation and Termination >

Initialisation and Termination
[IwAnim API Reference]

Functions

void | IwAnimInit ()
void | IwAnimTerminate ()

Detailed Description

Initialisation and termination of the IwAnim module.

Note:
For more information on the initialisation and termination of the IwAnim, see IwAnim Initialisation and Termination section of the IwAnim API Documentation.

Function Documentation

void IwAnimInit ( )

Initialises all core functionality for IwAnim. This function must be called before IwAnim is used.

See also:
IwAnimTerminate
Required Header Files
IwAnimCore.h

void IwAnimTerminate ( )

Shuts down IwAnim and frees all memory.

See also:
IwAnimInit
Required Header Files
IwAnimCore.h


Airplay API Reference: General State

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > General State >

General State
[IwAnim API Reference]

Data Structures

class | CIwAnimState
class | CIwAnimXForm

Defines

#define | IW_ANIM_MAX_BONES 32
#define | IW_ANIM_RESTYPE_ANIMATION "CIwAnim"
#define | IW_ANIM_RESTYPE_SKELETON "CIwAnimSkel"
#define | IW_ANIM_RESTYPE_SKIN "CIwAnimSkin"

Functions

CIwAnimSkel * IwAnimGetSingleBoneSkel ()
INLINE CIwAnimSkel * | IwAnimGetSkelContext ()
INLINE CIwSVec3 * | IwAnimGetSkinCache ()
INLINE uint32 | IwAnimGetSkinCacheSize ()
INLINE CIwAnimSkin * | IwAnimGetSkinContext ()
void | IwAnimReset ()
INLINE void | IwAnimSetSkelContext (CIwAnimSkel *pSkel)
INLINE void | IwAnimSetSkinCache (CIwSVec3 *pCache, uint32 size)
INLINE void | IwAnimSetSkinContext (CIwAnimSkin *pSkin)

Detailed Description

The following functionality allows you to query and set state information.

Note:
For more information on the IwAnim Metrics, see IwAnim State section of the IwAnim API Documentation.

Define Documentation

#define IW_ANIM_MAX_BONES 32

The maximum number of bones-per-skeleton supported by IwAnim.

Required Header Files
IwAnimCore.h

#define IW_ANIM_RESTYPE_ANIMATION "CIwAnim"

Resource type string for animations - equates to CIwAnim.

Required Header Files
IwAnimCore.h

#define IW_ANIM_RESTYPE_SKELETON "CIwAnimSkel"

Resource type string for animation skeletons - equates to CIwAnimSkel.

Required Header Files
IwAnimCore.h

#define IW_ANIM_RESTYPE_SKIN "CIwAnimSkin"

Resource type string for animation skins - equates to CIwAnimSkin.

Required Header Files
IwAnimCore.h

Function Documentation

CIwAnimSkel* IwAnimGetSingleBoneSkel ( )

Get the global single boned animation skeleton The global single boned animation skeleton

Required Header Files
IwAnimCore.h

INLINE CIwAnimSkel * IwAnimGetSkelContext ( )

Get the current animation skeleton context.

Returns:
The current animation skeleton context, or NULL.
See also:
IwAnimSetSkelContext
Required Header Files
IwAnimCore.h

INLINE CIwSVec3 * IwAnimGetSkinCache ( )

Get the current animation skin cache.

Returns:
The current animation skin cache, or NULL.
See also:
IwAnimSetSkinCache
Required Header Files
IwAnimCore.h

INLINE uint32 IwAnimGetSkinCacheSize ( )

Get the current animation skin cache size.

Returns:
Number of entries in the current animation skin cache.
See also:
IwAnimSetSkinCache
Required Header Files
IwAnimCore.h

INLINE CIwAnimSkin * IwAnimGetSkinContext ( )

Get the current animation skin context.

Returns:
The current animation skin context, or NULL.
See also:
IwAnimSetSkinContext
Required Header Files
IwAnimCore.h

void IwAnimReset ( )

Resets the IwAnim state.

Required Header Files
IwAnimCore.h

INLINE void IwAnimSetSkelContext ( CIwAnimSkel * pSkel )

Set the animation skeleton context. This must be done prior to rendering any static model which requires skinned animation. Usually, the skeleton context is taken from a CIwAnimPlayer object.

Parameters:
pSkel Pointer to the skeleton to use for future model rendering.
See also:
IwAnimGetSkelContext
Required Header Files
IwAnimCore.h
Required Header Files
IwAnimState.h

INLINE void IwAnimSetSkinCache | ( | CIwSVec3 * | pCache,
 |  | uint32 | size
 | ) |  |

Set the animation skin cache. This must be done prior to rendering any static model which requires skinned animation, which should use the optimisation of only reskinning vertices which have moved.

Parameters:
pCache Pointer to the skin cache data to use for future model rendering.
See also:
IwAnimGetSkinCache
Required Header Files
IwAnimCore.h

INLINE void IwAnimSetSkinContext ( CIwAnimSkin * pSkin )

Set the animation skin context. This must be done prior to rendering any static model which requires skinned animation. Usually, the skin context is taken from a CIwAnimPlayer object.

Parameters:
pSkin Pointer to the skinning data to use for future model rendering.
See also:
IwAnimGetSkinContext
Required Header Files
IwAnimCore.h


Airplay API Reference: Animation Player

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Animation Player >

Animation Player
[IwAnim API Reference]

Data Structures

class | CIwAnimBlendSource
class | CIwAnimPlayer

Detailed Description

For playing animations on skeleton instances.

Note:
For more information on the IwAnimPlayer, see Animation Player section of the IwAnim API Documentation.


Airplay API Reference: Skeleton

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Skeleton >

Skeleton
[IwAnim API Reference]

Data Structures

class CIwAnimSkel

Detailed Description

Animation skeleton (bone hierarchy).

Note:
For more information on skeleton animation, see Skeleton section in the IwAnim API Documentation.


Airplay API Reference: Skin

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > Skin >

Skin
[IwAnim API Reference]

Data Structures

class | CIwAnimSkin
class | CIwAnimSkinSet

Detailed Description

Skinning data for a model and skeleton.

Note:
For more information on skinning, see the Skin section of the IwAnim API Documentation.


Airplay API Reference: IwResHandler

Airplay API Reference > IwAnim API Documentation > IwAnim API Reference > IwResHandler >

IwResHandler
[IwAnim API Reference]

Resource handler for .anim files. More...

Data Structures

class | CIwResHandlerANIM
class | CIwResHandlerSKEL
class | CIwResHandlerSKIN
class | CIwResTemplateANIM
class | CIwResTemplateSKEL
class | CIwResTemplateSKIN

Detailed Description

Resource handler for .skin files.

Resource handler for .skel files.

Note:
For more information on IwAnim functionality, see the IwAnim API Documentation.


Airplay API Reference: IwAnim Examples

Airplay API Reference > IwAnim API Documentation > IwAnim Examples >

IwAnim Examples

This document provides a set of examples that illustrate how to use the majority of functionality contained within IwAnim. Each example uses the functionality specific to one IwAnim module, and endeavours to illustrate the capabilities of each of these modules.

The following examples are contained within this section:

  • IwAnim Animation Rendering Example
  • IwAnim Animation Playback Example
  • IwAnim Skeleton Example
  • IwAnim SubSkeleton Example
  • IwAnim Offset Example
  • IwAnim Single-Boned Animation Playback Example


Airplay API Reference: IwAnim Animation Rendering Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim Animation Rendering Example >

IwAnim Animation Rendering Example

Demonstrates loading of animation resources, and rendering of the animated model.

The main classes used to achieve this are:

  • CIwModel

  • CIwAnim

  • CIwAnimSkel

  • CIwAnimSkin

  • CIwAnimPlayer

The main functions used to achieve this are:

  • CIwAnim::IwAnimInit()

  • CIwResManager::LoadGroup()

  • CIwResManager::GetGroupNamed()

  • CIwResGroup::GetResNamed()

  • CIwAnimPlayer::SetSkel()

  • CIwAnimPlayer::PlayAnim()

  • IwAnimSetSkelContext()

  • IwAnimSetSkinContext()

IwAnimInit() is first called to initialise the IwAnim functionality. The user must have initialised IwGx and IwGraphics before IwAnim can be initialised. The LoadGroup() function is used to load the animation group. The animation group, or the group file, holds all the information that makes up the animation, namely:

  • geo file

  • skin file

  • skel file

  • and anim file.

Each of the loaded resources is accessed using the GetResNamed() function. The animation player is then instantiated. The animation player combines the character skeleton and the anim file to create the animation. The example plays the animation by calling the PlayAnim() function.

The up, down, left and right keys are set to allow you to manipulate the model matrix to move the animation. The 1 and 4 keys allow you to zoom in and out of the animation.

Note:
For more information on Animation, see the "Animation" module overview in the IwAnim API Reference documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_Model;
CIwAnim*        s_Anim;
CIwAnimSkel*    s_Skel;
CIwAnimSkin*    s_Skin;

// Animation player
CIwAnimPlayer*  s_Player;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0xc00, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x200, 0x300);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimRendering.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("ExampleIwAnimRendering");

    // Get and store pointer to the resources
    s_Model = (CIwModel*)pGroup->GetResNamed("combatEva", IW_GRAPHICS_RESTYPE_MODEL);
    s_Skin  = (CIwAnimSkin*)pGroup->GetResNamed("combatEva", IW_ANIM_RESTYPE_SKIN);
    s_Skel  = (CIwAnimSkel*)pGroup->GetResNamed("combatEva_rig", IW_ANIM_RESTYPE_SKELETON);
    s_Anim  = (CIwAnim*)pGroup->GetResNamed("LfStance", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;
    s_Player->SetSkel(s_Skel);
    s_Player->PlayAnim(s_Anim, IW_GEOM_ONE/2, CIwAnimBlendSource::LOOPING_F);

    // Create the UI
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    // Terminate IwAnim
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t += ofs;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t -= ofs;

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);

    IwAnimSetSkelContext(s_Player->GetSkel());
    IwAnimSetSkinContext(s_Skin);
    s_Model->Render();

    // Tidier to reset these
    IwAnimSetSkelContext(NULL);
    IwAnimSetSkinContext(NULL);

    // Paint the cursor keys buttons and prompt text
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // End drawing
    IwGxFlush();

    // Swap buffers
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim Animation Playback Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim Animation Playback Example >

IwAnim Animation Playback Example

The following example demonstrates how to play animations at any speed, forward and backwards, looping or one-shot. Also shows pause/restart.

The main classes used to achieve this are:

  • CIwAnimPlayer

The main functions used to achieve this are:

  • CIwAnimPlayer::PlayAnim()

This example builds on Animation Rendering Example by adding further controls to set the speed of animation playback. The speed of the animation playback is set using the second parameter of the PlayAnim() function, and it can be thrown into reverse by negating the value passed in.

Note:
For more information on adjusting the playing of an animation, see the Animation Player section of the IwAnim API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_Model;
CIwAnim*        s_Anim;
CIwAnimSkel*    s_Skel;
CIwAnimSkin*    s_Skin;

// Animation player
CIwAnimPlayer*  s_Player;

int32   s_Speed     = IW_GEOM_ONE;
bool    s_Reverse   = false;
bool    s_Looping   = true;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);

    AddButton("Speed -: 4", w - 70, 70, 70, 30, s3eKey4);
    AddButton("Speed +: 5", w - 70, 110, 70, 30, s3eKey5);

    AddButton("Reverse: 3", 0, 150, 70, 30, s3eKey3);

    AddButton("Looping: 6",  w - 70, 150, 70, 30, s3eKey6);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0xc00, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x200, 0x300);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimPlayback.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("ExampleIwAnimPlayback");

    // Get and store pointer to the resources
    s_Model = (CIwModel*)pGroup->GetResNamed("combatEva", IW_GRAPHICS_RESTYPE_MODEL);
    s_Skin  = (CIwAnimSkin*)pGroup->GetResNamed("combatEva", IW_ANIM_RESTYPE_SKIN);
    s_Skel  = (CIwAnimSkel*)pGroup->GetResNamed("combatEva_rig", IW_ANIM_RESTYPE_SKELETON);
    s_Anim  = (CIwAnim*)pGroup->GetResNamed("LfStance", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;
    s_Player->SetSkel(s_Skel);
    s_Player->PlayAnim(s_Anim, IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    // Terminate IwAnim
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t += ofs;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t -= ofs;

    // Update speed
    bool replay = false;

    if ( CheckButton("Speed -: 4") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MAX(0x100, s_Speed >> 1);
        replay = true;
    }
    else
    if ( CheckButton("Speed +: 5") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MIN(0x4000, s_Speed << 1);
        replay = true;
    }

    // Toggle backwards status
    if ( CheckButton("Reverse: 3") & S3E_KEY_STATE_PRESSED )
    {
        s_Reverse = !s_Reverse;
        replay = true;
    }

    // Toggle looping status
    if ( CheckButton("Looping: 6") & S3E_KEY_STATE_PRESSED )
    {
        s_Looping = !s_Looping;
        replay = true;
    }

    if (replay)
        s_Player->PlayAnim(s_Anim, s_Speed * ((s_Reverse == false) ? 1 : -1), (s_Looping == true ? CIwAnimBlendSource::LOOPING_F : 0) | CIwAnimBlendSource::RESET_IF_SAME_F);

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);

    IwAnimSetSkelContext(s_Player->GetSkel());
    IwAnimSetSkinContext(s_Skin);
    s_Model->Render();

    // Tidier to reset these
    IwAnimSetSkelContext(NULL);
    IwAnimSetSkinContext(NULL);

    // Debug display
    char line[80];
    sprintf(line, "Speed: %ld.%02ld", s_Speed / IW_GEOM_ONE, (s_Speed % IW_GEOM_ONE) * 100 / IW_GEOM_ONE);
    IwGxPrintString(2, 32, line);
    sprintf(line, "Reverse: %s", s_Reverse ? "true" : "false");
    IwGxPrintString(2, 40, line);
    sprintf(line, "Looping: %s", s_Looping ? "true" : "false");
    IwGxPrintString(2, 48, line);

    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim Skeleton Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim Skeleton Example >

IwAnim Skeleton Example

The following example demonstrates blending between full-skeleton animations.

The main classes used to achieve this are:

  • CIwAnim

  • CIwAnimPlayer

  • CIwAnimBlendSource

The main functions used to achieve this are:

  • CIwResGroup::GetResNamed()
  • CIwResManager::GetGroupNamed()
  • CIwAnimPlayer::SetSkel()
  • CIwAnimPlayer::PlayAnim()

This example builds on Animation Playback Example by adding further controls to allow you to swap between the loaded animations. During the initalisation phase of our example all resources are loaded up using GetGroupNamed(), all three animations are accessed using the GetResNamed() function and playback of the first animation is started using the PlayAnim() function.

If the 1, 2 or 3 keys are pressed then the corresponding animations are played. When a new animation is introduced it is blended in on top of the old animation. The blending is done over a set period, and this can be set using the minus and plus keys to increase or decrease the amount of time. The blend time is added to the PlayAnim() function as a fourth parameter.

Note:
For more information on blending between animations, see the Smooth Transitions section of the IwAnim API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_Model;
CIwAnim*        s_Anims[3];
CIwAnimSkel*    s_Skel;
CIwAnimSkin*    s_Skin;

// Animation player
CIwAnimPlayer*  s_Player;

// Blend duration
int32   s_BlendDur = IW_GEOM_ONE / 4;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);

    AddButton("Duration -: 4", w - 70, 70, 70, 30, s3eKey4);
    AddButton("Duration +: 5", w - 70, 110, 70, 30, s3eKey5);

    AddButton("Sequence 1: 7", 0, h - 90, w/3, 30, s3eKey7);
    AddButton("Sequence 2: 8", w/3, h - 90, w/3, 30, s3eKey8);
    AddButton("Sequence 3: 9", w/3*2, h - 90, w/3, 30, s3eKey9);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0xc00, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x200, 0x300);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimSkeleton.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("ExampleIwAnimSkeleton");

    // Get and store pointer to the resources
    s_Model = (CIwModel*)pGroup->GetResNamed("combatEva", IW_GRAPHICS_RESTYPE_MODEL);
    s_Skin  = (CIwAnimSkin*)pGroup->GetResNamed("combatEva", IW_ANIM_RESTYPE_SKIN);
    s_Skel  = (CIwAnimSkel*)pGroup->GetResNamed("combatEva_rig", IW_ANIM_RESTYPE_SKELETON);

    s_Anims[0]  = (CIwAnim*)pGroup->GetResNamed("LfStance", IW_ANIM_RESTYPE_ANIMATION);
    s_Anims[1]  = (CIwAnim*)pGroup->GetResNamed("RtStance", IW_ANIM_RESTYPE_ANIMATION);
    s_Anims[2]  = (CIwAnim*)pGroup->GetResNamed("LfDwDodge", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;
    s_Player->SetSkel(s_Skel);
    s_Player->PlayAnim(s_Anims[0], IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F, s_BlendDur);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());

}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    // Terminate IwAnim
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t += ofs;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t -= ofs;

    // Update blend duration
    if ( CheckButton("Duration -: 4") & S3E_KEY_STATE_DOWN )
        s_BlendDur = MAX(0x0, s_BlendDur - 0x200);
    else
    if ( CheckButton("Duration +: 5") & S3E_KEY_STATE_DOWN )
        s_BlendDur = MIN(0x1000, s_BlendDur + 0x200);

    // Change anim
    CIwAnim* pAnim = NULL;
    if ( CheckButton("Sequence 1: 7") & S3E_KEY_STATE_PRESSED )
        pAnim = s_Anims[0];
    else
    if ( CheckButton("Sequence 2: 8") & S3E_KEY_STATE_PRESSED )
        pAnim = s_Anims[1];
    else
    if ( CheckButton("Sequence 3: 9") & S3E_KEY_STATE_PRESSED )
        pAnim = s_Anims[2];

    if (pAnim)
        s_Player->PlayAnim(pAnim, IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F, s_BlendDur);

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);

    IwAnimSetSkelContext(s_Player->GetSkel());
    IwAnimSetSkinContext(s_Skin);
    s_Model->Render();

    // Tidier to reset these
    IwAnimSetSkelContext(NULL);
    IwAnimSetSkinContext(NULL);

    // Debug display
    char line[80];
    sprintf(line, "Animation: %s", s_Player->GetSourceCurr()->GetAnim()->DebugGetName());
    IwGxPrintString(2, 42, line);
    sprintf(line, "Blend Dur: %ld.%ld", s_BlendDur >> IW_GEOM_POINT, (s_BlendDur % IW_GEOM_ONE) * 100 / IW_GEOM_ONE);
    IwGxPrintString(2, 50, line);

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim SubSkeleton Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim SubSkeleton Example >

IwAnim SubSkeleton Example

The following example demonstrates overlaying of sub-skeleton animations.

The main classes used to achieve this are:

  • CIwAnim

  • CIwAnimBlendSource

The main functions used to achieve this are:

  • CIwResManager::GetGroupNamed()

  • CIwResGroup::GetResNamed()

  • CIwAnimPlayer::PlayAnim()

  • CIwAnimPlayer::PlaySubAnim()

  • CIwAnimPlayer::ClearSubAnim()

This example builds on Animation Skeleton Example by adding further controls to allow you to add a sub-skeleton animation to an animation that is currently running.

The example continuously blends between two animations and allows you to add either of two sub-skeletons to those animations. The controls are as follows:

  • Press "1" to add sub-skeleton animation anim0 to the current animation.

  • Press "2" to add sub-skeleton animation anim1 to the current animation.

  • Press "0" to remove any of the applied sub-skeleton animations from the current animation.

Pressing either of "1" or "2" calls the PlaySubAnim() function, which is similar to the PlayAnim function, but takes a sub-skeleton animation. Pressing "0" calls the ClearSubAnim(), which halts the sub-skeleton animation.

Note:
For more information on overlaying sub-skeleton animations, see the Smooth Transitions section of the IwAnim API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_Model;
CIwAnim*        s_FullSkelAnims[2];
CIwAnim*        s_SubSkelAnims[2];
CIwAnimSkel*    s_Skel;
CIwAnimSkin*    s_Skin;

// Animation player
CIwAnimPlayer*  s_Player;

// Timer
uint32  s_Timer = 0;

void CreateButtonsUI(int w, int h)
{
    // Create the UI
    AddButton("Zoom in: 3", 0, 70, 70, 30, s3eKey3);
    AddButton("Zoom out: 6", 0, 110, 70, 30, s3eKey6);

    AddButton("Add Anim 1: 1", w - 90, 70, 90, 30, s3eKey1);
    AddButton("Add Anim 2: 2", w - 90, 110, 90, 30, s3eKey2);
    AddButton("Remove Anim: 0", w - 90, 150, 90, 30, s3eKey0);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, -0x400, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x200, 0x300);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimSubSkeleton.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("ExampleIwAnimSubSkeleton");

    // Get and store pointer to the resources
    s_Model = (CIwModel*)pGroup->GetResNamed("combatEva", IW_GRAPHICS_RESTYPE_MODEL);
    s_Skin  = (CIwAnimSkin*)pGroup->GetResNamed("combatEva", IW_ANIM_RESTYPE_SKIN);
    s_Skel  = (CIwAnimSkel*)pGroup->GetResNamed("combatEva_rig", IW_ANIM_RESTYPE_SKELETON);

    s_FullSkelAnims[0]  = (CIwAnim*)pGroup->GetResNamed("LfStance", IW_ANIM_RESTYPE_ANIMATION);
    s_FullSkelAnims[1]  = (CIwAnim*)pGroup->GetResNamed("RtStance", IW_ANIM_RESTYPE_ANIMATION);
    s_SubSkelAnims[0]   = (CIwAnim*)pGroup->GetResNamed("SubAnimA", IW_ANIM_RESTYPE_ANIMATION);
    s_SubSkelAnims[1]   = (CIwAnim*)pGroup->GetResNamed("SubAnimB", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;
    s_Player->SetSkel(s_Skel);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    // Terminate IwAnim
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if (CheckButton("Zoom out: 6") & S3E_KEY_STATE_DOWN)
        s_ModelMatrix.t += ofs;
    if (CheckButton("Zoom in: 3") & S3E_KEY_STATE_DOWN)
        s_ModelMatrix.t -= ofs;

    // Alternate between two full-skeleton anims, with a short blend duration
    if (!(s_Timer & 0x1f))
        s_Player->PlayAnim(s_FullSkelAnims[(s_Timer >> 5) & 0x1], IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F, 0x400);

    if (CheckButton("Add Anim 1: 1") & S3E_KEY_STATE_PRESSED)
    {
        // Pressed 1: blend in sub-skeleton anim 0, on sub-skeleton anim slot 0
        s_Player->PlaySubAnim(0, s_SubSkelAnims[0], IW_GEOM_ONE, 0, 0x800);
    }
    else
    if (CheckButton("Add Anim 2: 2") & S3E_KEY_STATE_PRESSED)
    {
        // Pressed 2: blend in sub-skeleton anim 1, on sub-skeleton anim slot 0
        s_Player->PlaySubAnim(0, s_SubSkelAnims[1], IW_GEOM_ONE, 0, 0x800);
    }
    else
    if (CheckButton("Remove Anim: 0") & S3E_KEY_STATE_PRESSED)
    {
        // Pressed 0: blend out any anim of sub-skeleton slot 0
        s_Player->ClearSubAnim(0, 0x800);
    }

    s_Timer++;

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);

    IwAnimSetSkelContext(s_Player->GetSkel());
    IwAnimSetSkinContext(s_Skin);
    s_Model->Render();

    // Tidier to reset these
    IwAnimSetSkelContext(NULL);
    IwAnimSetSkinContext(NULL);

    // Debug display
    char line[80];
    sprintf(line, "Full-skel anim: %s", s_Player->GetSourceCurr()->GetAnim()->DebugGetName());
    IwGxPrintString(2, 42, line);
    sprintf(line, "Sub-skel anim:  %s", s_Player->GetSourceSub(0)->GetAnim() ? s_Player->GetSourceSub(0)->GetAnim()->DebugGetName() : "NONE");
    IwGxPrintString(2, 50, line);

    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim Offset Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim Offset Example >

IwAnim Offset Example

The following example demonstrates how to play animation that includes an offset path

The main classes used to achieve this are:

  • CIwAnimPlayer

The main functions used to achieve this are:

  • CIwAnimPlayer::PlayAnim()
  • CIwAnimPlayer::GetMatOfs()

This example demonstrates the use of Offset anims. Offset anims can be exported alongside the main animation using the standard Airplay Studio Exporters. Offsets can be used to separate large scale movement from small internal animation for easier integration into application systems. For exaple, the path of a run can be split from the detailed movement of the bones, allowing the application to trac the large scale movement of the character and potentially override the path with application logic

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_Model;
CIwAnim*        s_Anim;
CIwAnimSkel*    s_Skel;
CIwAnimSkin*    s_Skin;

// Animation player
CIwAnimPlayer*  s_Player;

int32   s_Speed     = IW_GEOM_ONE;
bool    s_Reverse   = false;
bool    s_Looping   = true;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);

    AddButton("Speed -: 4", w - 70, 70, 70, 30, s3eKey4);
    AddButton("Speed +: 5", w - 70, 110, 70, 30, s3eKey5);

    AddButton("Reverse: 3", 0, 150, 70, 30, s3eKey3);

    AddButton("Looping: 6",  w - 70, 150, 70, 30, s3eKey6);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0xc00, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x200, 0x300);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimOffset.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("ExampleIwAnimOffset");

    // Get and store pointer to the resources
    s_Model = (CIwModel*)pGroup->GetResNamed("combatEva", IW_GRAPHICS_RESTYPE_MODEL);
    s_Skin  = (CIwAnimSkin*)pGroup->GetResNamed("combatEva", IW_ANIM_RESTYPE_SKIN);
    s_Skel  = (CIwAnimSkel*)pGroup->GetResNamed("combatEva_rig", IW_ANIM_RESTYPE_SKELETON);
    s_Anim  = (CIwAnim*)pGroup->GetResNamed("offset_LfStance", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;
    s_Player->SetSkel(s_Skel);
    s_Player->PlayAnim(s_Anim, IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    // Terminate IwAnim
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t += ofs;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t -= ofs;

    // Update speed
    bool replay = false;

    if ( CheckButton("Speed -: 4") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MAX(0x100, s_Speed >> 1);
        replay = true;
    }
    else
    if ( CheckButton("Speed +: 5") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MIN(0x4000, s_Speed << 1);
        replay = true;
    }

    // Toggle backwards status
    if ( CheckButton("Reverse: 3") & S3E_KEY_STATE_PRESSED )
    {
        s_Reverse = !s_Reverse;
        replay = true;
    }

    // Toggle looping status
    if ( CheckButton("Looping: 6") & S3E_KEY_STATE_PRESSED )
    {
        s_Looping = !s_Looping;
        replay = true;
    }

    if (replay)
        s_Player->PlayAnim(s_Anim, s_Speed * ((s_Reverse == false) ? 1 : -1), (s_Looping == true ? CIwAnimBlendSource::LOOPING_F : 0) | CIwAnimBlendSource::RESET_IF_SAME_F);

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the model
    //-------------------------------------------------------------------------
    CIwMat model_matrix_with_offset = s_Player->GetMatOfs();
    model_matrix_with_offset.PostMult(s_ModelMatrix);
    IwGxSetModelMatrix(&model_matrix_with_offset);

    IwAnimSetSkelContext(s_Player->GetSkel());
    IwAnimSetSkinContext(s_Skin);
    s_Model->Render(true);

    // Tidier to reset these
    IwAnimSetSkelContext(NULL);
    IwAnimSetSkinContext(NULL);

    // Debug display
    char line[80];
    sprintf(line, "Speed: %ld.%02ld", s_Speed / IW_GEOM_ONE, (s_Speed % IW_GEOM_ONE) * 100 / IW_GEOM_ONE);
    IwGxPrintString(2, 32, line);
    sprintf(line, "Reverse: %s", s_Reverse ? "true" : "false");
    IwGxPrintString(2, 40, line);
    sprintf(line, "Looping: %s", s_Looping ? "true" : "false");
    IwGxPrintString(2, 48, line);

    // Paint the cursor keys buttons
    IwGxPrintString(2, IwGxGetScreenHeight() - 70, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwAnim Single-Boned Animation Playback Example

Airplay API Reference > IwAnim API Documentation > IwAnim Examples > IwAnim Single-Boned Animation Playback Example >

IwAnim Single-Boned Animation Playback Example

The following example demonstrates how to play single-boned animations.

The main classes used to achieve this are:

  • CIwAnimPlayer

The main functions used to achieve this are:

  • CIwAnimPlayer::PlayAnim()
  • CIwAnimBone::SetModelMatrix();

This example builds on Animation Playback Example by substituting a single-boned animation for the multi bone skinned animation.

The position of the single bone is applied to a ball to make it bounce down some stairs.

Note:
For more information on adjusting the playing of an animation, see the Animation Player section of the IwAnim API Documentation.
The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "IwAnim.h"
#include "IwAnimPlayer.h"
#include "IwAnimSkel.h"
#include "IwAnimSkin.h"
#include "IwGraphics.h"
#include "IwGxPrint.h"
#include "IwModelBuilder.h"
#include "IwResManager.h"
#include "IwTextParserITX.h"
#include "s3eKeyboard.h"
#include "ExamplesMain.h"

// Angles
CIwSVec3    s_Angles;

// Local matrix
CIwMat      s_ModelMatrix;

// Resources
CIwModel*       s_StaticModel;
CIwModel*       s_AnimModel;
CIwAnim*        s_Anim;

// Animation player
CIwAnimPlayer*  s_Player;

int32   s_Speed     = IW_GEOM_ONE;
bool    s_Reverse   = false;
bool    s_Looping   = true;

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Zoom in: 1", 0, 70, 70, 30, s3eKey1);
    AddButton("Zoom out: 2", 0, 110, 70, 30, s3eKey2);

    AddButton("Speed -: 4", w - 70, 70, 70, 30, s3eKey4);
    AddButton("Speed +: 5", w - 70, 110, 70, 30, s3eKey5);

    AddButton("Reverse: 3", 0, 150, 70, 30, s3eKey3);

    AddButton("Looping: 6",  w - 70, 150, 70, 30, s3eKey6);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
void ExampleInit()
{
    // Initialise
    IwGxInit();
    IwGraphicsInit();
    IwAnimInit();

    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);

    // Set screen clear colour
    IwGxSetColClear(0x40, 0x40, 0x40, 0x00);

    // Set field of view
    IwGxSetPerspMul(IwGxGetScreenWidth() / 2);

    // Set near and far planes
    IwGxSetFarZNearZ(0x4010, 0x10);

    // Initialise angles
    s_Angles = CIwSVec3(0, 0xa00, 0x800);

    // Initialise model position
    s_ModelMatrix.t = CIwVec3(0, 0x400, 0x1480);

#ifdef IW_BUILD_RESOURCES
    //Initialise resource templates - This scales Eva up so animation can interpolate smoothly
    if( IwGetResManager()->m_Flags & CIwResManager::BUILDRES_F )
        IwGetTextParserITX()->ParseFile("resource_template.itx");
#endif

    // Parse the GROUP file, which will load the resources
    IwGetResManager()->LoadGroup("IwAnimSingleBone.group");

    // Get a pointer to the named group
    CIwResGroup* pGroup = IwGetResManager()->GetGroupNamed("IwAnimSingleBone");

    // Get and store pointer to the resources
    s_StaticModel = (CIwModel*)pGroup->GetResNamed("tower", IW_GRAPHICS_RESTYPE_MODEL);
    s_AnimModel = (CIwModel*)pGroup->GetResNamed("ball_01", IW_GRAPHICS_RESTYPE_MODEL);
    s_Anim  = (CIwAnim*)pGroup->GetResNamed("ball_01", IW_ANIM_RESTYPE_ANIMATION);

    // Create animation player
    s_Player = new CIwAnimPlayer;

    // Play the animation... note that no skeleton needs to be set.
    s_Player->PlayAnim(s_Anim, IW_GEOM_ONE, CIwAnimBlendSource::LOOPING_F);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up resources
    delete s_Player;

    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);

    // Terminate IwAnim
    IwAnimTerminate();
    IwGraphicsTerminate();
    IwGxTerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // Update angles from the arrow keys
    if ( CheckCursorState() == EXCURSOR_LEFT )
        s_Angles.y -= 0x40;
    if ( CheckCursorState() == EXCURSOR_RIGHT )
        s_Angles.y += 0x40;
    if ( CheckCursorState() == EXCURSOR_UP )
        s_Angles.x -= 0x40;
    if ( CheckCursorState() == EXCURSOR_DOWN )
        s_Angles.x += 0x40;

    // Build view matrix rotation from angles
    CIwMat rotX, rotY, rotZ;
    rotX.SetRotX(s_Angles.x);
    rotY.SetRotY(s_Angles.y);
    rotZ.SetRotZ(0x800);
    s_ModelMatrix.CopyRot(rotZ * rotX * rotY);

    // Forward/back
    CIwVec3 ofs(0, 0, 0x10);
    if ( CheckButton("Zoom out: 2") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t += ofs;
    if ( CheckButton("Zoom in: 1") & S3E_KEY_STATE_DOWN )
        s_ModelMatrix.t -= ofs;

    // Update speed
    bool replay = false;

    if ( CheckButton("Speed -: 4") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MAX(0x100, s_Speed >> 1);
        replay = true;
    }
    else
    if ( CheckButton("Speed +: 5") & S3E_KEY_STATE_DOWN )
    {
        s_Speed = MIN(0x4000, s_Speed << 1);
        replay = true;
    }

    // Toggle backwards status
    if ( CheckButton("Reverse: 3") & S3E_KEY_STATE_PRESSED )
    {
        s_Reverse = !s_Reverse;
        replay = true;
    }

    // Toggle looping status
    if ( CheckButton("Looping: 6") & S3E_KEY_STATE_PRESSED )
    {
        s_Looping = !s_Looping;
        replay = true;
    }

    if (replay)
        s_Player->PlayAnim(s_Anim, s_Speed * ((s_Reverse == false) ? 1 : -1), (s_Looping == true ? CIwAnimBlendSource::LOOPING_F : 0) | CIwAnimBlendSource::RESET_IF_SAME_F);

    // Update animation player
    s_Player->Update(0x1000 / 30);

    // Update IwGx state time stamp
    IwGxTickUpdate();
    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear the screen
    IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

    // Start with no lighting
    IwGxLightingOff();

    //-------------------------------------------------------------------------
    // Render the static model
    //-------------------------------------------------------------------------
    IwGxSetModelMatrix(&s_ModelMatrix);

    // Render the stairs
    s_StaticModel->Render();

    //-------------------------------------------------------------------------
    // Render the animated model
    //-------------------------------------------------------------------------

    // Get the single animated bone from the skeleton and place model space at its position.
    s_Player->GetSkel()->GetBoneFromID(0)->SetModelMatrix(s_ModelMatrix);

    // Now render the ball at that position
    s_AnimModel->Render();

    // Debug display
    char line[80];
    sprintf(line, "Speed: %ld.%02ld", s_Speed / IW_GEOM_ONE, (s_Speed % IW_GEOM_ONE) * 100 / IW_GEOM_ONE);
    IwGxPrintString(2, 32, line);
    sprintf(line, "Reverse: %s", s_Reverse ? "true" : "false");
    IwGxPrintString(2, 40, line);
    sprintf(line, "Looping: %s", s_Looping ? "true" : "false");
    IwGxPrintString(2, 48, line);

    IwGxPrintString(2, IwGxGetScreenHeight() - 60, "Rotate Model: Arrow Keys");
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and swap
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxFont API Documentation

Airplay API Reference > IwGxFont API Documentation >

IwGxFont API Documentation

The IwGxFont documentation contains the following sections:

  • IwGxFont API Overview
  • IwGxFont API Reference
  • IwGxFont Examples


Airplay API Reference: IwGxFont API Overview

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview >

IwGxFont API Overview

IwGxFont provides an API for rendering texture based fonts. It supports text layout, including word-wrapping and alignment, and accepts UTF-8 encoded strings. IwGxFont supplies the potential to display localised text in virtually any character set.

To use IwGxFont functionality, you must include "IwGxFont.h" in your source and iwgxfont as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwgxfont
  • }

When using IwGxFont, the following modules do not need to be specified in your project's MKB as they will be implicitly included as subprojects of this module:

  • IwUtil
  • IwGeom
  • IwResManager
  • IwGx

The following topics are covered in this section:

  • IwGxFont Initialisation and Termination
  • IwGxFont State Object
  • Creating a Font
  • IwGxFont Files
  • Formatting Text
  • Rendering Text
  • Conditioning Font Binaries


Airplay API Reference: IwGxFont Initialisation and Termination

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > IwGxFont Initialisation and Termination >

IwGxFont Initialisation and Termination

The user must initialise IwGxFont and terminate IwGxFont as follows:

  • // Begin application
  • IwGxInit();
  • IwResManagerInit();
  • IwGxFontInit();

...rest of application

  • // End application
  • IwGxFontTerminate();
  • IwResManagerTerminate();
  • IwGxTerminate();

IwGxFont relies on the IwGx and IwResManager modules, and the user must initialise these manually.

Note: For more information on the functionality that can be used to initialise and terminate IwGxFont, see Initialisation and Termination.


Airplay API Reference: IwGxFont State Object

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > IwGxFont State Object >

IwGxFont State Object

Like IwGx, IwGxFont has an internal object representing its current state. IwGxFont API calls either affect the state or use some elements of the state internally as inputs. When this document refers to the 'current' state/font/etc. it is referring to this state object.

Note: For more information on the functionality that can be used to query and change IwGxFont State, see IwGxFont State Control.


Airplay API Reference: Creating a Font

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > Creating a Font >

Creating a Font

The first step when working with IwGxFont is to create a font resource. An IwGxFont is encapsulated by the CIwGxFont class. This class is hidden from the user, but it is a class derived from CIwResource, and can be used in the same ways as any other type of resource.

Note: For more information on the loading of groups, see the Groups section of the 'IwResManager API Documentation'.

Like other resources, a CIwGxFont has a human readable ASCII source representation, and a binary representation that is shipped with the application. Each CIwGxFont is constructed from two files:

  • GXFONT (.gxfont) file: This file specifies which characters are mapped by the font and other properties like kerning and leading.
  • TGA (.tga) file: This file contains the actual bitmap for the glyphs (characters).

The easiest way to create these input files is by using the Airplay Studio Font Builder, a standalone application which can output an IwGxFont based on any font available in windows. You should only include IwGxFonts based on fonts to which you hold the copyright. IwGxFonts can also be handrolled.

Note: The Airplay Studio Font Builder can be found at tools\ASFontBuilder\ASFontBuilder.exe. For more information on using this application, see the 'Airplay Tools Reference documentation'

Loading a Font

Once you have output the font and created both the GXFONT and TGA files you can load the font. Typically a font is loaded in two steps:

  • A GROUP file must be created. The elements required to define the font are specified inside a GROUP file. The following group file creates a group named FontBasic and points to the file which defines it, ariall4.gxfont.
    • CIwResGroup
    • {
      • name FontBasic
      • "Fonts/arial14.gxfont"
    • }

    The GXFONT file specifies character mapping, a TGA file and a transformation format.

  • The font is loaded and managed by the IwResManager using the LoadGroup functionality. The following piece of code is used to load a font:
    • //Load the example's font group
    • IwGetResManager()->LoadGroup("IwGxFontBrowser.group");
    • //Get default font
    • CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial14", "CIwGxFont");


Airplay API Reference: IwGxFont Files

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > IwGxFont Files >

IwGxFont Files

There are two file types that IwGxFont uses to describe fonts:

  • GXFONT Files
  • TGA Files

GXFONT Files

A GXFONT file is used to specify which characters are mapped by the font and other properties like kerning and leading.

The GXFONT file is an ITX file of the following form:

CIwGxFont
{
    //treat characters passed to this font as utf8 strings.
    utf8    1

    //specification of the image tga and the characters
    //contained in it (in left to right, top to bottom order)
    image       MyFont.tga
    charmap " abcdefghijklm"

    //other font details
    leading 3
    kerning 12

    kern    cd 14
}

If utf8 is not set to 1, strings will be treated as 256-character sets. This can be used to produce marginally smaller localised text. Generally it is better to use utf8 to avoid the complexities of code pages, additionally many languages cannot be represented in 256 characters.

GXFONT Options

Fine control over other aspects of the font's appearance can be added to the GXFONT file. The following options are available:

  • kerning <int> This sets a global kerning value (in pixels). Kerning is the distance between characters as they are laid out.

  • leading <int> This sets a leading value (in pixels). Leading is the distance between lines of text.

  • kern <char1> <char2> <int> This sets the kerning for an individual pair of characters. Note this is not commutative - this value only takes effect when <char2> is directly preceded by <char1>

  • map <char1> <char2> weakmap <char1> <char2>

    • maprange <range1start> <range1end> <range2start> <range2end>

    weakmaprange <range1start> <range1end> <range2start> <range2end>

    These control the mapping of characters to other characters. A typical problem when dealing with localised text involves the addition of characters which are not included in your fonts. By default these will appear as a box. This set of options can be used to deal with this problem.

    A map instruction tells the font to render <char2> everytime <char1> is encountered.

    For example, when using a font which included only lowercase characters, the line 'maprange azAZ' could be used to map all lowercase letters to uppercase equivalents.

    A weakmap instruction will only take effect if no mapping already exists for <char1> or for an individual character in <range1>. This is useful for providing a set of fall back mappings.

  • height <int> Normally a font will automatically derive its height from the TGA. This setting can be used to override that height.
  • default <char> <char> will be used for any unmapped characters. This is equivalent to map <all unknown="" characters>=""><char2>. By default a distinct glyph will be created automatically to represent unmapped characters.

All character arguments can be given as four character hex values; e.g.,

  • charmap \x0af0\x00ff

Derived Fonts

The final GXFONT option is:

derive <source font> <colour>

For example:

  • CIwGxFont
  • {
    • derive myfont 255,0,0
  • )

This will produce a font that shares much of myfont's state, but changes the colour it appears in. This option can be used to produce 1555 fonts of variable colours. myfont is looked up using the standard IwResManager::GetResNamed function.

TGA Files

A TGA file contains the actual bitmap for the glyphs (characters). The image contained in the TGA file will be sliced into glyphs using the following procedure:

  • The colour at the top left pixel is used as the 'background' colour.
  • Search left-to-right for the first occurring pixel which is not the background colour.
  • Cut out the rectangle that is not background coloured which starts at that pixel. The glyph in this rectangle will be considered the glyph for the next character in the charmap string. It will then continue from the right of that rectangle.

Therefore, each glyph in the TGA should be a rectangle of non-background coloured pixels surrounded by background coloured pixels in the colour plane, aligned exactly along the top edge. The alpha plane is used to determine the visibility of the glyph.

Note: Asserts will fire during this process if something appears to have gone wrong.


Airplay API Reference: Formatting Text

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > Formatting Text >

Formatting Text

Formatting of text is optimised using a prepared text object. A block of formatted text can be held in a CIwGxFontPreparedData object. This allows IwGxFont to decouple formatting and rendering so that your application can render large blocks of text without the overhead of reformatting them every frame.

Prepared text can be rendered at different locations without being re-formatted, making it suitable for scrolling text.

The following is an example of how the CIwGxFontPreparedData object would be used:

  • //container to receive the formatted text
  • CIwGxFontPreparedData data;
  • //Format the string using the current settings
  • IwGxFontPrepareText(data, "This is a string");
  • //Draw text using the prepared text
  • IwGxFontDrawText(data);

The version of IwGxFontDrawText() which takes a string effectively calls IwGxFontPrepareText() followed by IwGxFontDraw() internally.

IwGxFont supports a number of options when formatting text:

  • IwGxFontSetRect() is used to set the region the text will be formatted and positioned within. Note that only the width/height of the rectangle affect the formatting of the string. Changing the position of the rectangle passed to this function and rendering prepared text will move the formatted block around.
  • IwGxFontSetAlignmentHor() and IwGxFontSetAlignmentVer() are used to affect the font's alignment. For example, after IwGxFontSetAlignmentHor(IW_GX_FONT_ALIGN_CENTRE) any line of text will be centred in the formatting region.
  • IwGxFontSetFlags() can be used to control other aspects of formatting. The flags affecting formatting are:
    • IW_GX_FONT_NOWRAP_F,
    • IW_GX_FONT_NOWORDWRAP_F,
    • IW_GX_FONT_ONELINE_F,
    • IW_GX_FONT_NUMBER_ALIGN_F.
  • IwGxFontSetFormatStart() can be used to make the text layout start from somewhere other than the top-left corner. This is useful for concatenating strings that need to be rendered in different colours, etc.

Note: Formatting options only affect text being prepared. Text which has already been prepared will not be affected by these options.


Airplay API Reference: Rendering Text

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > Rendering Text >

Rendering Text

Rendering a string with a loaded font involves setting the current font and calling IwGxFontDrawText(). The following code illustrates how this is done:

  • //Get the font from ResManager (assuming it has already been loaded from a group file)
  • CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("MyFont");
  • //Set the font to be the current font.
  • IwGxFontSetFont(font);
  • //Draw text using the current font.
  • IwGxFontDrawText("This is a string");

This code extract will print the formatted string at the top left of the display.

Strings are rendered through the IwGx interface as IW_GX_QUAD_LISTs or, if possible, IW_GX_SPRITE_LISTs. The latter is much preferable in performance terms, but can only be used in limited circumstances: The font must be in 1555 format, it must be white-coloured, IW_GX_FONT_ITALIC_F must not be activated and the font scale must be IW_GEOM_ONE.

IwGxFont provides an interface for rendering prepared data with arbitrary vertices, this can be done since a font is just a set of polys. IwGxFontSetUVs() will set a UV stream for a quad list based on the prepared text. IwGxFontGetMaterial() can be used to get the default material for the font.

Note: Only fonts with a single texture (or compress-and-cached) can be rendered in this way. For details on compress-and-cache, see the the following section Conditioning Font Binaries

IwGxFont supports a number of options when rendering text:

  • IwGxFontSetRect() can be used to position text. For more information on using this function, see Formatting Text.
  • IwGxFontSetFlags() can be used to activate some styles of text, e.g: italic, underline.
  • IwGxFontSetCol() can be used to set the colour of the text.

Note: Emissive lighting is used to colour the font, so that path must be enabled using IwGxLightingEmissive(true) prior to the draw text call.


Airplay API Reference: Conditioning Font Binaries

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Overview > Conditioning Font Binaries >

Conditioning Font Binaries

The "gxfont" resource handler provides a set of parameters to condition the binary produced for each font. The following settings can be used like any template parameter or alternatively entered in a group file to condition the font resource:

  • compressAndCache - possible values: '0 (off) or Number of characters', default = 0 In compress-and-cache mode the font's bitmap is held in a 1bit-per-pixel compressed surface. Glyphs are extracted into the cache texture on demand.

    • This allows very large fonts to be used with little VRAM cost, but any anti-aliasing in the font will be lost.

    The number of characters represents the maximum number of characters visible in a single flush. Large numbers will cause the cache to be missed less frequently and may improve performance if cache use is near maximum. The cache will only be changed and uploaded once per flush.

  • use1555 - possible settings: 'false or true', default = false When Use1555 is set to 1 the font textures will be produced in renderer-native format (ABGR1555). The advantage of this is that the sprite path can be used for maximum rendering efficiency and poly-based rendering will make use of palette-caches etc. in modulate R mode.

    • The disadvantage is that 1555 fonts cannot be coloured if RGB rendering is not enabled and anti-aliasing will be lost.

    The font's default format (ABGR4444) provides a good trade off between rendering flexibility and speed, but applications striving for the fastest speed possible should consider using 1555 fonts. IwGxFont provides a low-cost way of storing extra versions of a font with colour 'baked in' using a texel-sharing scheme (see gxfont's 'derive' option below)

  • mapType - possible settings: 'CHAR or RANGE', default = RANGE An important part of the formatting operation is mapping a unicode character to a glyph ID (since the font is unlikely to include all possible unicode characters!). Two options are available for the format of this map: RANGE which is slower but normally much smaller in memory and CHAR which is faster, but can get quite big if a wide range of characters are used.
  • mipMapping - possible settings: 'false or true', default = false Sets whether the texture(s) generated by the font are mipmapped; setting this to off improves the performance of compress and cache fonts, and can decrease loading times for other fonts.

The following code is an example of how one of these settings would be used in a group file:

  • CIwResGroup
  • {
    • 'fonts/myfont.gxfont' { Use1555 1 CompressAndCache 80 }
  • }

Note: For more information on using templates, see the Using Resource Templates section.


Airplay API Reference: IwGxFont API Reference

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference >

IwGxFont API Reference

Modules

Initialisation and Termination
IwGxFont State Control
IwGxFont Parameter Callbacks
IwGxFont Types
Drawing and Preparing Text

Data Structures

class CIwGxFontPreparedData

Detailed Description

IwGxFont provides an abstracted font renderer based on IwGx textures. CIwGxFont is a hidden CIwResource class that is constructed from a .gxfont file and a .tga file Strings supplied to IwGxFont should be in utf-8 format.


Airplay API Reference: Initialisation and Termination

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference > Initialisation and Termination >

Initialisation and Termination
[IwGxFont API Reference]

Functions

void | IwGxFontInit ()
void | IwGxFontTerminate ()

Detailed Description

For more information on how this functionality can be used, see the IwGxFont Initialisation and Termination section of the IwGxFont Overview.

Function Documentation

void IwGxFontInit ( )

Initialise the IwGxFont module. Must be called prior to any other IwGxFont functions

Required Header Files
IwGxFont.h

void IwGxFontTerminate ( )

Terminate IwGxFont module. Must be called prior to shutdown.

Required Header Files
IwGxFont.h


Airplay API Reference: IwGxFont State Control

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference > IwGxFont State Control >

IwGxFont State Control
[IwGxFont API Reference]

Functions

void | IwGxFontClearFlags (uint32 flags)
IwGxFontAlignHor IwGxFontGetAlignmentHor ()
IwGxFontAlignVer IwGxFontGetAlignmentVer ()
CIwColour & IwGxFontGetCol ()
uint32 | IwGxFontGetFlags ()
const CIwGxFont * | IwGxFontGetFont ()
CIwRect & IwGxFontGetRect ()
void | IwGxFontResetState ()
void | IwGxFontSetAlignmentHor (IwGxFontAlignHor alignHor)
void | IwGxFontSetAlignmentVer (IwGxFontAlignVer alignVer)
void | IwGxFontSetCol (uint32 col)
void | IwGxFontSetCol (const CIwColour &col)
void | IwGxFontSetFlags (uint32 flags)
void | IwGxFontSetFont (const CIwGxFont *pFont)
void | IwGxFontSetFormatStart (const CIwSVec2 &v)
void | IwGxFontSetGlobalKerning (int32 kerning)
void | IwGxFontSetLeading (int32 leading)
void | IwGxFontSetRect (const CIwRect &rect)
void | IwGxFontSetScale (iwfixed scalex, iwfixed scaley=-1)

Detailed Description

The IwGxFont state controls the formatting and rendering of text. It should only be modified through these functions.

For more information on how this functionality can be used, see the IwGxFont State section of the IwGxFont Overview.

Function Documentation

void IwGxFontClearFlags ( uint32 flags ) [inline]

Clear general state flags.

Parameters:
flags General state flags to clear.
See also:
IwGxFontFlags

IwGxFontAlignHor IwGxFontGetAlignmentHor ( ) [inline]

Get the current horizontal alignment.

Returns:
The current horizontal alignment.

IwGxFontAlignVer IwGxFontGetAlignmentVer ( ) [inline]

Get the current vertical alignment.

Returns:
The current vertical alignment.

CIwColour& IwGxFontGetCol ( ) [inline]

Get the current colour.

Returns:
The font colour currently used.

uint32 IwGxFontGetFlags ( ) [inline]

Get general state flags.

Returns:
flags The general state flags.
See also:
IwGxFontFlags

const CIwGxFont* IwGxFontGetFont ( ) [inline]

Get the current font.

Returns:
The current font

CIwRect& IwGxFontGetRect ( ) [inline]

Get the drawing rectangle.

Returns:
rect The rectangle to draw within.

void IwGxFontResetState ( )

Reset the font state to default settings.

void IwGxFontSetAlignmentHor ( IwGxFontAlignHor alignHor ) [inline]

Set the current horizontal alignment. Defaults to IW_GX_FONT_ALIGN_LEFT.

Parameters:
alignHor The horizontal alignment to use.

void IwGxFontSetAlignmentVer ( IwGxFontAlignVer alignVer ) [inline]

Set current vertical alignment. Defaults to IW_GX_FONT_ALIGN_TOP.

Parameters:
alignVer The vertical alignment to use.

void IwGxFontSetCol ( uint32 col ) [inline]

Set the current colour. Defaults to white.

Parameters:
col The font colour to use for subsequent drawing.

void IwGxFontSetCol ( const CIwColour & col ) [inline]

Set the current colour. Fonts will be rendered using this colour from now on. Defaults to white.

Note:
Fonts are coloured using emissive lighting, so iwgx's emissive lighting must be enabled for colour to take effect. Also, fonts using 1555 format textures require full RGB modulation to be linked into the software render for non-greyscale lighting.
Parameters:
col The font colour to use for subsequent drawing.

void IwGxFontSetFlags ( uint32 flags ) [inline]

Set general state flags. Defaults to no flags set.

Parameters:
flags General state flags to set.
See also:
IwGxFontFlags

void IwGxFontSetFont ( const CIwGxFont * pFont ) [inline]

Set the current font.

Parameters:
pFont Pointer to the font to use for subsequent IwGxFont functions

void IwGxFontSetFormatStart ( const CIwSVec2 & v ) [inline]

Set where the top left-hand corner of the first glyph will appear will appear in the format rectangle. Defaults to (0,0).

Parameters:
v the position
See also:
CIwGxFontPreparedData::GetNextCharacterPosition

void IwGxFontSetGlobalKerning ( int32 kerning ) [inline]

Set the global kerning for any formatting operations with the current font. This change will only persist until the next IwGxFontSetFont call (it does not perminently affect the current font).

Parameters:
kerning the kerning required
See also:
IwGxFontSetFont

void IwGxFontSetLeading ( int32 leading ) [inline]

Set the leading for any formatting operations with the current font. This change will only persist until the next IwGxFontSetFont call (it does not perminently affect the current font).

Parameters:
leading the leading required
See also:
IwGxFontSetFont

void IwGxFontSetRect ( const CIwRect & rect ) [inline]

Set the drawing rectangle. Text wrapping etc. will take affect during the preparation phase using the width/height of this rectangle. The prepared text will then be placed using the position of the rectangle during rendering. This allows text to be prepared once and placed many times. Defaults to entire screen.

Note:
The position has no effect on preparation and the size has no effect on rendering.
Parameters:
rect The rectangle to draw within.

void IwGxFontSetScale | ( | iwfixed | scalex,
 |  | iwfixed | scaley = -1 |
 | ) |  |  | [inline]

Set the scale of font drawing. Affects both rendering and preparation. Default to 1.0

Parameters:
scalex | The scale on X
scaley | The scale on Y (pass -1 for same scale as X)


Airplay API Reference: IwGxFont Parameter Callbacks

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference > IwGxFont Parameter Callbacks >

IwGxFont Parameter Callbacks
[IwGxFont API Reference]

Functions

void IwGxFontSetParameterCallback (IwGxFontParameterCallback cb)

Detailed Description

IwGxFont provides a callback mechanism for substituting named parameters. If a callback is registered any substring bounded with {} will be passed to the callback for formatting. For example, formatting the string "{subject} jumped over {object}" would call the callback twice to get values for "subject" and "object". This is preferable to sprintf for localisation, since the natural order of parameters may change in other languages. Note that the string passed in will NOT usually be NULL-terminated - you must respect the length! The temp_buffer is a pointer to a static piece of memory which should be safe to use as string space (at least 80 bytes long)

Example callback function:

    const char * cb(const char * in_start, int in_length, char* temp_buffer)
    {
        if (in_length==7 && memcmp(in_start, "subject", 7)==0)
        {
            strcpy(temp_buffer, "the quick brown fox");
            return temp_buffer;
        }
        else if( in_length==6 && memcmp(in_start, "object", 6)==0)
        {
            strcpy(temp_buffer, "the lazy dog");
            return temp_buffer;
        }
        else
            return "UNKNOWN PARAMETER";
    }

For an example of how this functionality can be used, see the IwGxFont Parameters Example.

Function Documentation

void IwGxFontSetParameterCallback ( IwGxFontParameterCallback cb ) [inline]

Set the parameter callback.

Parameters:
cb The callback to set. NULL disables parameter processing.


Airplay API Reference: IwGxFont Types

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference > IwGxFont Types >

IwGxFont Types
[IwGxFont API Reference]

Data Structures

struct | IwGxFontPreparedChar

Typedefs

typedef const IwChar *(* | IwGxFontParameterCallback )(const IwChar *in_start, int in_length, IwChar *temp_buffer)

Enumerations

enum | IwGxFontAlignHor
enum | IwGxFontAlignVer
enum | IwGxFontFlags

Detailed Description

Core types and enumerations used by the IwGxFont API.

Typedef Documentation

typedef const IwChar*(* IwGxFontParameterCallback)(const IwChar *in_start, int in_length, IwChar *temp_buffer)

Type definition for character callback

Enumeration Type Documentation

enum IwGxFontAlignHor

Horizontal alignment values.

Enumerator:
IW_GX_FONT_ALIGN_LEFT | Text will be justified against the left-hand side of the rect.
IW_GX_FONT_ALIGN_CENTRE | Text will be centred horizontally in the rect.
IW_GX_FONT_ALIGN_RIGHT | Text will be justified against the right-hand side of the rect.

enum IwGxFontAlignVer

Vertical alignment values.

Enumerator:
IW_GX_FONT_ALIGN_TOP | Text will be positioned against the top of the rect.
IW_GX_FONT_ALIGN_MIDDLE | Text will be centred vertically in the rect.
IW_GX_FONT_ALIGN_BOTTOM | Text will be positioned against the bottom of the rect.

enum IwGxFontFlags

General font state flags.

Enumerator:
IW_GX_FONT_DEFAULT_F | Default settings.
IW_GX_FONT_NOWRAP_F | Don't wrap the font (formatting).
IW_GX_FONT_NOWORDWRAP_F | Don't perform word wrapping (formatting).
IW_GX_FONT_ONELINE_F | Only render one line of text (i.e. terminate at '\n') (formatting).
IW_GX_FONT_NUMBER_ALIGN_F | Forces all number characters to appear to be the same width (formatting).
IW_GX_FONT_UNDERLINE_F | Underline the text (rendering).
IW_GX_FONT_ITALIC_F | Use italics (rendering).


Airplay API Reference: Drawing and Preparing Text

Airplay API Reference > IwGxFont API Documentation > IwGxFont API Reference > Drawing and Preparing Text >

Drawing and Preparing Text
[IwGxFont API Reference]

Functions

void | IwGxFontDrawText (CIwGxFontPreparedData &data, int32 firstChar=-1, int32 lastChar=-1)
void | IwGxFontDrawText (const IwChar *text, int32 len=-1)
void | IwGxFontFreeBuffers ()
void | IwGxFontPrepareText (CIwGxFontPreparedData &data, const IwChar *text, int32 len=-1)
void | IwGxFontReserveBuffers (int32 numChars, int32 numLines)
int32 | IwGxFontSetUVs (CIwGxFontPreparedData &data, int32 line=-1, int32 material=0, uint32 **charIDs=NULL)

Function Documentation

void IwGxFontDrawText | ( | CIwGxFontPreparedData & | data,
 |  | int32 | firstChar = -1,
 |  | int32 | lastChar = -1
 | ) |  |

Draw a previously prepared block of text

Parameters:
data | The prepared text to draw.
firstChar | (optional) The index of the first character to draw.
lastChar | (optional) The index value one greater than that of the last character to draw. The character with this index will not be drawn.
Note:
The number of characters drawn will be lastChar-firstChar.

void IwGxFontDrawText | ( | const IwChar * | text,
 |  | int32 | len = -1
 | ) |  |

Draw text, using the current state. Text will be rendered at the position of the current rect and respect style and format settings. The function call:

 IwGxFontDrawText("Hello", 5);
is equivalent to:
 CIwGxFontPreparedData data;
 IwGxFontPrepareText(data, "Hello", 5);
 IwGxFontDrawText(data);
Note:
IwGxFont using a static instance of CIwGxFontPreparedData as a working area. To free memory allocated in this class call IwGxFontFreeBuffers
Parameters:
text | The text to draw.
len | The number of character to draw, or -1 to draw the entire string.
See also:
IwGxFontSetRect, IwGxFontSetFormatStart, IwGxFontSetAlignVer, IwGxFontSetAlignHor, IwGxFontFreeBuffers

void IwGxFontFreeBuffers ( )

Free buffers held by IwGxFont's internal CIwGxFontPreparedData. When text is drawn using the string argument version of IwGxFontDrawText, a 'working area' of buffer will be allocated. This may grow on future calls. This function releases all memory allocated in this working area.

See also:
IwGxFontDrawText

void IwGxFontPrepareText | ( | CIwGxFontPreparedData & | data,
 |  | const IwChar * | text,
 |  | int32 | len = -1
 | ) |  |

Prepare text for drawing - the IwGxFontPreparedData will be filled in and can then be passed to IwGxFontDrawPreparedText to render the same block of text without reformatting (which can be expensive for long text). The width and height of the current rect will be used along with the format start position.

Parameters:
data | The IwGxFontPreparedData to fill
text | The text to prepare.
len | The number of character to draw, or -1 to prepare the entire string.
See also:
IwGxFontDrawText, IwGxFontSetRect, IwGxFontSetFormatStart, IwGxFontSetAlignmentVer, IwGxFontSetAlignmentHor

void IwGxFontReserveBuffers | ( | int32 | numChars,
 |  | int32 | numLines
 | ) |  |

Reserve buffers held by IwGxFont's internal CIwGxFontPreparedData. When text is drawn using the string argument version of IwGxFontDrawText, a 'working area' of buffer will be allocated. This call will reserve memory for the specified number of lines and characters. Following this call, an assert will fire if the buffers grow.

Parameters:
numChars | the number of characters to reserve memory for
numLines | the number of lines to reserve memory for
See also:
IwGxFontDrawText

int32 IwGxFontSetUVs | ( | CIwGxFontPreparedData & | data,
 |  | int32 | line = -1,
 |  | int32 | material = 0,
 |  | uint32 ** | charIDs = NULL
 | ) |  |

Set the UV stream for the given prepared text. IwGx will be sent a UV stream appropriate for rendering all characters in the line using an GX_QUAD_LIST primitive stream. The default layout of the vertices that IwGxFont has built for the text is accessible using CIwGxFontPreparedData::GetCharacterArea. For multi-material fonts, this should be called for each material in turn. charIDs will be a pointer to a list of indices in the prepared data for the characters that were actually drawn.

Parameters:
data | The prepared text to draw
line | The line within the text to draw (-1 for all text).
material | The font material so set UVs for.
charIDs | Pointer to a list of characters actually rendered for this material
Returns:
The number of characters sent.
See also:
IwGxFontGetMaterial

CIwGxFontPreparedData::GetCharacterArea


Airplay API Reference: IwGxFont Examples

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples >

IwGxFont Examples

This document provides a set of examples that illustrate how to use the functionality contained within IwGxFont. Each example uses the functionality specific to IwGeom, and endeavours to illustrate the capabilities of each of these modules.

The following examples are contained within this section:

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


Airplay API Reference: IwGxFont Basic Example

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples > IwGxFont Basic Example >

IwGxFont Basic Example

This example application loads a font and uses this font to display text on the screen.

The main functions used to achieve this are:

  • IwGxFontInit()
  • IwGetResManager()
  • IwGxFontSetFont()
  • IwGxFontSetCol()
  • IwGxFontSetRect()
  • IwGxFontDrawText()

The example begins by loading the font group file, which points the resource manager to the defining GXFONT file. The GXFONT file sets the TGA file, which graphically defines the font, and the character map. The font is then set as the current font so all printing from this point will use the new font.

The colour and formatting rectangle are set for the font and it is then drawn using the IwGxFontDrawText() function.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-------------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxFont.h"
#include "IwResManager.h"

//-------------------------------------------------------------------------------
// The following function initialises the resource manager and IwGxFont. The
// Resource Manager is used to load the group file which points to the font
// resources.
// The font resources are then used to form the font and this font is set to
// be the current font using the IwGxFontSetFont() function.
//-------------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise modules
    IwResManagerInit();
    IwGxFontInit();

    //Load the group containing the example font
    IwGetResManager()->LoadGroup("IwGxFontBasic.group");

    //Get the example font and set it to be the current font
    CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial14", "CIwGxFont");
    IwGxFontSetFont(font);
}

//-------------------------------------------------------------------------------
// The following function terminates IwGxFont and the Resource Manager on
// shutdown.
//-------------------------------------------------------------------------------
void ExampleShutDown()
{
    //terminate the modules
    IwGxFontTerminate();
    IwResManagerTerminate();
}

bool ExampleUpdate()
{
    return true;
}

//-------------------------------------------------------------------------------
// The following function sets the font colour using the IwGxFontSetCol()
// function as well as the position and area alloted to the displayed text using
// the IwGxFontSetRect(). The IwGxFontSetRect() function accepts a CIwRect object
// which defines the rectangle the text will exist within.
// The text that is to be displayed on screen is entered using the
// IwGxFontDrawText() function.
//-------------------------------------------------------------------------------
void ExampleRender()
{
    //Lighting is required to colour fonts
    IwGxLightingOn();

    //Set font colour to grey
    IwGxFontSetCol(0xff808080);

    //Set the formatting rect - this controls where the text appears and what it is formatted against
    IwGxFontSetRect(CIwRect(10,40,(int16)IwGxGetScreenWidth()-10,(int16)IwGxGetScreenHeight()-50));

    //Draw the text
    IwGxFontDrawText("This is text printed using IwGxFont.\nText printed through this module is device-independent and can be used in both SW and HW modes.\nFonts produced this way can be formatted using word wrap and alignment options, and accept utf8 encoded strings for maximum localisability.");

    //Flush and show
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxFont Parameters Example

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples > IwGxFont Parameters Example >

IwGxFont Parameters Example

This example application loads a font and uses this font to display text on the screen. The text to be displayed contains tokens. A callback is used to substitute a string for each token that is encountered before the text is displayed.

The main functions used to achieve this are:

  • IwGxFontSetFont()
  • IwGxFontSetParameterCallback()
  • IwGxFontDrawText()

The example begins by loading the font. This is done in the exact same way as is described in our first example, IwGxFont Basic Example.

A callback is registered that will be called whenever a token (a string wrapped in parenthasis, i.e., '{','}') is encountered in the display text.

The callback will return a string from an array of possible strings based on keyboard input.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
#include "s3e.h"
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwResManager.h"
#include "ExamplesMain.h"

const char* s_Items[] =
{
    "the quick brown fox",
    "the lazy dog",
    "the man in the moon",
    "the dish and the spoon",
};

int32 s_SubjectIndex = 0;
int32 s_ObjectIndex = 1;

//-----------------------------------------------------------------------------
// This example callback substitutes the tokens {subject} or {object} with the
// relevant entry from s_Items.
//-----------------------------------------------------------------------------
const char * ExampleCallback(const char * in_start, int in_length, char* temp_buffer)
{
    // note we cannot use strcmp because in_start is a pointer into our text buffer
    // (and thus will not be zero-terminated)

    if (in_length==7 && memcmp(in_start, "subject", 7)==0)
    {
        strcpy(temp_buffer, s_Items[s_SubjectIndex]);
        return temp_buffer;
    }
    else if( in_length==6 && memcmp(in_start, "object", 6)==0)
    {
        strcpy(temp_buffer, s_Items[s_ObjectIndex]);
        return temp_buffer;
    }
    else
        return "UNKNOWN PARAMETER";
}

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Text 1 : 1", 10, h-30, 70, 30, s3eKey1);
    AddButton("Text 2 : 2", 90, h-30, 70, 30, s3eKey2);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
// The following function initialises the resource manager and IwGxFont. The
// Resource Manager is used to load the group file which points to the font
// resources.
// The font resources are then used to form the font and this font is set to
// be the current font using the IwGxFontSetFont() function.
// A call back is set using the IwGxFontSetParameterCallback() function.
//-----------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise modules
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwResManagerInit();
    IwGxFontInit();

    //Load the group containing the example font
    IwGetResManager()->LoadGroup("IwGxFontBasic.group");

    //Get the example font and set it to be the current font
    CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial14", "CIwGxFont");
    IwGxFontSetFont(font);

    //Set the callback
    IwGxFontSetParameterCallback(ExampleCallback);

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//-----------------------------------------------------------------------------
// The following function terminates IwGxFont and the Resource Manager on
// shutdown.
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    //terminate the modules
    IwGxFontTerminate();
    IwResManagerTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}

//-----------------------------------------------------------------------------
// The following function tests for keyboard input. Pressing of s3eKey1 causes
// the subject index to be incremented and pressing of s3eKey2 causes the
// object index to be incremented.
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    // On key 1 or 2 change the subject or object item
    int32* pIndex = NULL;
    if( CheckButton("Text 1 : 1") & S3E_KEY_STATE_PRESSED )
        pIndex = &s_SubjectIndex;
    else if( CheckButton("Text 2 : 2") & S3E_KEY_STATE_PRESSED )
        pIndex = &s_ObjectIndex;

    // increment the chosen index
    if( pIndex )
    {
        *pIndex = (*pIndex + 1) % (sizeof(s_Items) / sizeof(const char*));
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function sets the font colour using the IwGxFontSetCol()
// function as well as the position and area alloted to the displayed text using
// the IwGxFontSetRect(). The IwGxFontSetRect() function accepts a CIwRect object
// which defines the rectangle the text will exist within.
// The text that is to be displayed on screen is entered using the
// IwGxFontDrawText() function. The text to be displayed has two words which are
// wrapped in parenthesis. Each set of parenthesis encountered in the input of
// IwGxFontDrawText() results in the callback registered using
// IwGxFontSetParameterCallback() being called.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Lighting is required to colour fonts
    IwGxLightingOn();

    //Set font colour to grey
    IwGxFontSetCol(0xff808080);

    //Set the formatting rect - this controls where the text appears and what it is formatted against
    IwGxFontSetRect(CIwRect(10,40,(int16)IwGxGetScreenWidth()-10,(int16)IwGxGetScreenHeight()-50));

    //Draw the text - note we cannot use prepared text to pick up changing parameters
    IwGxFontDrawText("This is text printed using IwGxFont's parameter substitution:\nI saw {subject} jump over {object}.\n\nText 1 to toggle the subject ({subject}) and Text 2 to toggle the object ({object}).");

    //Flush and show
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxFont Clipping Example

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples > IwGxFont Clipping Example >

IwGxFont Clipping Example

This example application loads a font and illustrates how clipping can be used to isolate parts of the display text in order to change their formatting.

The main functions used to achieve this are:

  • IwGxFontInit()
  • IwGxFontSetFont()
  • IwGxFontSetAlignmentHor()
  • IwGxFontPrepareText()
  • CIwGxFontPreparedData::GetHeight()
  • IwGxFontSetCol()
  • IwGxFontSetRect()
  • IwGxSetScissorScreenSpace()
  • IwGxFontDrawText()

The IwGxFontPrepareText() function is used to add the display text to a CIwPreparedDataText object. The use of prepared text is an optimisation that means the text does not need to be reformated for each render loop.

The IwGxFontSetRect() function is used to set the position of the prepared text, which is gradually scrolled vertically.

The IwGxSetScissorScreenSpace() function is used to isolate the text into slices which are then rendered interpolating between black and white.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-------------------------------------------------------------------------------

#include "IwGx.h"
#include "IwGxFont.h"
#include "IwResManager.h"

CIwGxFontPreparedData s_PreparedText;
int32 s_YPos = 0;

//-------------------------------------------------------------------------------
// The following function initialises the resource manager and IwGxFont. The
// Resource Manager is used to load the group file which points to the font
// resources.
// The font resources are then used to form the font and this font is set to
// be the current font using the IwGxFontSetFont() function.
// A callback is set using the IwGxFontSetParameterCallback() function.
// The IwGxFontPrepareText() function adds a text string to an instantiated
// CIwPreparedDataText object.
//-------------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise modules
    IwResManagerInit();
    IwGxFontInit();

    //Load the group containing the example font
    IwGetResManager()->LoadGroup("IwGxFontBasic.group");

    //Get the example font and set it to be the current font
    CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial14", "CIwGxFont");
    IwGxFontSetFont(font);

    IwGxFontSetRect(CIwRect(0, 0, (int16)IwGxGetScreenWidth(), 10000));
    IwGxFontSetAlignmentHor(IW_GX_FONT_ALIGN_CENTRE);

    //Prepare text
    IwGxFontPrepareText(s_PreparedText, "This example demonstrates the use of IwGxFontPrepareText, \
IwGxFontSetRect, \
IwGxSetScissorScreenSpace, \
IwGxFontSetCol, \
to repeatedly render the same string with different colour settings/clipping without reformatting \
to create a gradient coloured scrolling field.");

    s_YPos = IwGxGetScreenHeight();
}

//-------------------------------------------------------------------------------
// The following function terminates IwGxFont and the Resource Manager on
// shutdown.
//-------------------------------------------------------------------------------
void ExampleShutDown()
{
    // Release prepared text
    s_PreparedText.Clear();

    //terminate the modules
    IwGxFontTerminate();
    IwResManagerTerminate();
}

//-------------------------------------------------------------------------------
// The following function decrements the verticle position variable for each
// render loop.
//-------------------------------------------------------------------------------
bool ExampleUpdate()
{
    s_YPos -= 1;

    if( s_YPos + s_PreparedText.GetHeight() < 40 )
        s_YPos = IwGxGetScreenHeight();

    return true;
}

//-------------------------------------------------------------------------------
// The following function sets the formatting rectangle for the text. The verticle
// position of the formatting rectangle is set using the @a s_YPos variable
// set in the Update section.
// The screen is then sliced into ten sections. A for loop is used to give each
// slice a colour and isolate each section for rendering in that colour. Each slice
// is isolated using the IwGxSetScissorScreenSpace() function.
//-------------------------------------------------------------------------------
void ExampleRender()
{
    //Lighting is required to colour fonts
    IwGxLightingOn();

    IwGxFontSetRect(CIwRect(0,(int16)s_YPos,0,0));

    const uint32 slices = 10;
    const int32 sliceHeight = (IwGxGetScreenHeight() - 40) / slices;
    for(uint32 y = 0; y < slices; y++)
    {
        //linear interpolate between black and white
        uint32 col = (y + 1) * 0xff / slices;
        CIwColour iwcol;
        iwcol.r = iwcol.g = iwcol.b = (uint8)col;
        iwcol.a = 0xff;
        IwGxFontSetCol(iwcol);

        IwGxSetScissorScreenSpace(0, y * sliceHeight + 40, IwGxGetScreenWidth(), sliceHeight);
        IwGxFontDrawText(s_PreparedText);
    }

    IwGxClearScissorScreenSpace();

    //Flush and show
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxFont 3D Example

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples > IwGxFont 3D Example >

IwGxFont 3D Example

This example application loads a font and illustrates how it can be displayed in 3D.

The main functions used to achieve this are:

  • IwGxFontInit()
  • IwGxFontSetFont()
  • IwGxFontPrepareText()
  • CIwGxFontPreparedData::GetNumChars()
  • CIwGxFontPreparedData::GetCharacterArea()
  • IwGxFontSetRect()
  • IwGxFontDrawText()

A set of four vertices is allocated for each glyph in order to map their raw positions. The GetCharacterArea() function is used to find out how much area is taken up by a character. The IwGxFontSetUVs() function sends a UV stream appropriate for rendering all characters in the prepared text using a GX_QUAD_LIST primitive stream.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-------------------------------------------------------------------------------
#include "IwGx.h"
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwMaterial.h"
#include "IwResManager.h"

CIwGxFont* s_Font;
CIwGxFontPreparedData s_PreparedText;
int32 s_Tick;

//-------------------------------------------------------------------------------
// The following function initialises the resource manager and IwGxFont. The
// Resource Manager is used to load the group file which points to the font
// resources.
// The font resources are then used to form the font and this font is set to
// be the current font using the IwGxFontSetFont() function.
// The formatting rectangle to hold the font is then set using the IwGxFontSetRect()
// function.
// A CIwGxFontPreparedData object is handed the display text for the example.
//-------------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise modules
    IwResManagerInit();
    IwGxFontInit();

    //Load the group containing the example font
    IwGetResManager()->LoadGroup("IwGxFont3D.group");

    //Get the example font and set it to be the current font
    s_Font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial24", "CIwGxFont");
    IwGxFontSetFont(s_Font);

    //Set the formatting rect - we only want one long line so we set the region very wide
    IwGxFontSetRect(CIwRect(0,0,10000,1000));

    //Prepare the text - we will then have a continuous line of text
    IwGxFontPrepareText(s_PreparedText, "Using CIwGxFontPrepareText, IwGxFontSetUVs, and IwGxFontGetMaterial you can format text in any fashion/coordinate space you desire!");
}

//-------------------------------------------------------------------------------
// The following function terminates IwGxFont and the Resource Manager on
// shutdown.
//-------------------------------------------------------------------------------
void ExampleShutDown()
{
    //Clear up handle
    s_PreparedText.Clear();

    //terminate the modules
    IwGxFontTerminate();
    IwResManagerTerminate();
}

//-------------------------------------------------------------------------------
// The following function increments a tick on each render loop.
//-------------------------------------------------------------------------------
bool ExampleUpdate()
{
    s_Tick++;
    return true;
}

//-------------------------------------------------------------------------------
// The following function constructs the cone onto which the font is placed.
// The view matrix is then rotated around the y axix so that it looks like the
// text is moving around the cone.
// A set of four vertices is allocated for each glyph in order to map their raw
// positions. The GetCharacterArea() function is used to find out how much area
// is taken up by a character.
// The IwGxFontSetUVs() function sends a UV stream appropriate for rendering all
// characters in the prepared text using a GX_QUAD_LIST primitive stream.
//-------------------------------------------------------------------------------
void ExampleRender()
{
    //Rotate around the cone we're constructing at a regular pace
    CIwMat view;
    view.SetRotY(-s_Tick*10+IW_GEOM_ONE/2);
    view.t = view.RotateVec(CIwVec3(0,0,-7000));
    view.LookAt(view.t, CIwVec3(0,0,0), CIwVec3(0,-IW_GEOM_ONE, 0));
    IwGxSetViewMatrix(&view);

    //Lighting is required to colour fonts
    IwGxLightingOn();

    for(int32 m = 0; m < s_Font->GetNumberMaterials(); m++)
    {
        //IwGxFontSetUVs sets a stream corresponding to the prepared text
        uint32* charIDs;
        uint32 chars = IwGxFontSetUVs(s_PreparedText, -1, m, &charIDs);

        uint32 numberVerts = chars*4;
        CIwSVec3* pVerts = IW_GX_ALLOC(CIwSVec3, numberVerts);
        CIwSVec3* pVert = pVerts;

        //Collect the raw positions that the glyphs were placed at...
        uint32 i;
        for(i = 0; i < chars; i++)
        {
            CIwRect area = s_PreparedText.GetCharacterArea(charIDs[i]);

            *pVert = CIwSVec3(area.x, area.y, 0); pVert++;
            *pVert = CIwSVec3(area.x, area.y+area.h, 0); pVert++;
            *pVert = CIwSVec3(area.x+area.w, area.y+area.h, 0); pVert++;
            *pVert = CIwSVec3(area.x+area.w, area.y, 0); pVert++;
        }

        //Now we transform them onto a very high cone...
        pVert = pVerts;
        for(i = 0; i < numberVerts; i++)
        {
            iwfixed along = pVert->x;
            CIwMat rot(CIwMat::g_Identity);
            rot.PostRotateZ(along*10);
            iwfixed radius = (pVert->y+100-(along/20));
            CIwSVec3 v(0, (int16)(radius*2), 0);
            v = rot.RotateVec(v);

            *pVert = CIwSVec3(v.x*20, -(int16)(radius*50-4500), v.y*20);
            pVert++;
        }

        //Set the verts in world space
        IwGxSetVertStreamWorldSpace(pVerts, numberVerts);

        //Create a material from the font's material to make it darker -
        //note we could do anything else we like to the material
        CIwMaterial* mat = IW_GX_ALLOC_MATERIAL();
        mat->Copy(*IwGxFontGetFont()->GetMaterial(m));
        mat->SetColEmissive(0x80,0x80,0x80,0xff);
        IwGxSetMaterial(mat);

        //Finally draw the glyphs
        IwGxDrawPrims(IW_GX_QUAD_LIST, NULL, numberVerts);
    }

    //Flush and show
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwGxFont Browser Example

Airplay API Reference > IwGxFont API Documentation > IwGxFont Examples > IwGxFont Browser Example >

IwGxFont Browser Example

This example application demonstrates how prepared text can be formatted.

The main functions used to achieve this are:

  • IwGxFontSetFormatStart()
  • IwGxFontPrepareText()
  • CIwGxFontPreparedData::GetNextCharacterPosition()

The application reads in the text of a selected html file and divides it up based on the tags that it encounters. Each piece of text is placed in a block and these blocks is wrapped in a CIwGxFontPreparedData object. Based on the tag surrounding the text the CIwGxFontPreparedData object is given specific formatting.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-------------------------------------------------------------------------------
#include "s3e.h"
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwResManager.h"
#include "ExamplesMain.h"

//--------------------------------------------------------------------------------
// CFormatInfo
//--------------------------------------------------------------------------------

//--------------------------------------------------------------------------------
// Class containing information about how to format a block. As it's created each
// block will inherit the g_Current format info which will reflect the current state
// of tag parsing.
//--------------------------------------------------------------------------------
class CFormatInfo
{
public:
    bool m_Underline;
    bool m_Italic;
    bool m_Link;
    CIwColour m_Colour;
};

//--------------------------------------------------------------------------------
// Global state
//--------------------------------------------------------------------------------
CFormatInfo g_Current; // Format information reflecting the current state of parsing - opening/closing tags affects this info.
CFormatInfo g_Last; // Format information reflecting the state of parsing when the current font tag was opened
const char* g_LinkAddr; // The current address to attach to any created blocks
int32 g_LinkLength; // The length of the current address to attach to any created blocks
CIwSVec2 g_FormatPos; // The current 'cursor position' for laying out text
int32 g_Tick; // Keeping count of which frame we're on for link animations
uint32 g_ScreenWidth, g_ScreenHeight; //Remember gx size
char* g_CurrentPageAddress;

CIwArray<class CBlock*> g_Blocks; // A list of all formatted blocks that make up the current page
CIwArray<class CLink*> g_Links; // A list of all links in the current page
int32 g_SelectedLink; // An index into g_Links to indicate the currently selected link.

//--------------------------------------------------------------------------------
// CLink
//
// Class containing information about a link. If a block is created with
// g_Current.m_Link == true a link will be created and added to the current list.
//--------------------------------------------------------------------------------
class CLink
{
public:
    ~CLink()
    {
        delete m_Addr;
    }

    CBlock* m_Block;
    char* m_Addr;
};

//--------------------------------------------------------------------------------
// CBlock
//
// Container for a CIwGxFontPreparedData and a format info to describe how to
// render it.
//--------------------------------------------------------------------------------
class CBlock
{
public:
    void Render()
    {
        // clear all flags
        IwGxFontClearFlags(0xffffffff);

        // if this block is a link...
        if( m_Info.m_Link )
        {
            IwGxFontSetFlags(IW_GX_FONT_UNDERLINE_F); // underline

            //make link flash if it is the currently selected link
            if( (g_Tick & 0x4) != 0 && g_Links[g_SelectedLink]->m_Block == this )
            {
                IwGxFontSetCol(0xffff00ff);
            }
            else
            {
                IwGxFontSetCol(0xffff0000);
            }
        }
        else
        {
            //Set underline flag if block is underlined
            if( m_Info.m_Underline )
                IwGxFontSetFlags(IW_GX_FONT_UNDERLINE_F);
            //Set colour from block
            IwGxFontSetCol(m_Info.m_Colour);
        }

        //Set italic flag if block is underlined
        if( m_Info.m_Italic )
            IwGxFontSetFlags(IW_GX_FONT_ITALIC_F);

        //Render the prepared text
        IwGxFontDrawText(m_Data);
    }

    //Container for formatted text
    CIwGxFontPreparedData m_Data;
    //Format for rendering
    CFormatInfo m_Info;
};

//--------------------------------------------------------------------------------
// Tag functions
//--------------------------------------------------------------------------------

//--------------------------------------------------------------------------------
// The following function sets the the current prepared text to use the italic
// format type.
//--------------------------------------------------------------------------------
void DoItalic(bool open)
{
    g_Current.m_Italic = open;
    if( !open )
        g_FormatPos.x += 5;
}

//--------------------------------------------------------------------------------
// The following function sets the the current prepared text to use the underline
// format type.
//--------------------------------------------------------------------------------
void DoUnderline(bool open)
{
    g_Current.m_Underline = open;
}

//--------------------------------------------------------------------------------
// The following function sets the the current prepared text to use the link
// format type.
//--------------------------------------------------------------------------------
bool DoLink(bool open, const char* pTag, int32 length)
{
    if( !open )
    {
        g_Current.m_Link = false;
        return true;
    }

    //Find '=' in the tag (assumes href is the only property)
    const char* pEq = strchr(pTag, '=');
    if( !pEq )
        return false;

    //+3 here assumes address is quoted
    g_LinkLength = length - (pEq - pTag + 3);
    g_LinkAddr = pEq+2;
    g_Current.m_Link = true;

    return true;
}

//--------------------------------------------------------------------------------
// The following function calls the relevant tag function. The tag is tested to
// see if it is a closing tag, if it is the relevant function is called and passed
// the open bool set to false. If it is an opening tag, the relevant function
// is called and passed the open tag set to true.
//--------------------------------------------------------------------------------
void DoTag(const char* pTag, int32 length)
{
    //Forward slash at tag start indicates close tag
    bool open = pTag[0] != '/';
    if( !open )
    {
        pTag += 1;
        length -= 1;
    }

    //<i> italic
    if( length == 1 && strncmp(pTag, "i", 1) == 0 )
    {
        DoItalic(open);
    }
    //<u> underline
    else if( length == 1 && strncmp(pTag, "u", 1) == 0 )
    {
        DoUnderline(open);
    }
    //<a href="x"> link
    else if( strncmp(pTag, "a", 1) == 0 && DoLink(open, pTag+1, length-1) )
    {
    }
    //<br> newline
    else if( strncmp(pTag, "br", 2) == 0 )
    {
        //Reset cursor to left hand side
        g_FormatPos.x = 0;
        //And line feed
        g_FormatPos.y += (int16)IwGxFontGetFont()->GetHeight();
    }
}
//--------------------------------------------------------------------------------
// AddBlock
//
// The following function creates a new block for each delimited string, recording
// the current parsing state for rendering. It also creates a link entry if the
// current state indicates a link.
//--------------------------------------------------------------------------------
void AddBlock(const char* text, int32 length)
{
    CBlock* pBlock = new CBlock;

    //Set format start to the cursor position. Format start controls where the text begins
    //within the format rect.
    IwGxFontSetFormatStart(g_FormatPos);

    //Prepare the text - this will fill pBlock->m_Data with formatting information for the
    //block for individual glyphs, including position, scale, and applying word wrapping.
    IwGxFontPrepareText(pBlock->m_Data, text, length);

    //Update the format start to point to the last character rendered.
    g_FormatPos = pBlock->m_Data.GetNextCharacterPosition();

    //Copy current parsing state into this block
    pBlock->m_Info = g_Current;

    //Add to the list of blocks
    g_Blocks.push_back(pBlock);

    //If this will be a link add to the global list
    if( g_Current.m_Link )
    {
        CLink* pLink = new CLink;
        //Record the block
        pLink->m_Block = pBlock;

        //Make copy of address
        pLink->m_Addr = (char*)s3eMalloc(g_LinkLength+1);
        memcpy(pLink->m_Addr, g_LinkAddr, g_LinkLength);
        //Zero-terminate
        pLink->m_Addr[g_LinkLength] = 0;

        //Add to the list of links
        g_Links.push_back(pLink);
    }
}
//--------------------------------------------------------------------------------
// Page Management
//
// HTML doesn't repect new lines in the file (only tagged newlines, so we need to
// strip any newline chars).
//--------------------------------------------------------------------------------
int32 RemoveNewLines(char* line)
{
    char* start = line;
    char* out = line;
    while(*line)
    {
        if( *line != '\n' )
        {
            *out = *line;
            out++;
        }
        line++;
    }
    *out = 0;

    return out - start;
}

void ClosePage()
{
    for(uint32 b = 0; b < g_Blocks.size(); b++)
        delete g_Blocks[b];
    for(uint32 l = 0; l < g_Links.size(); l++)
        delete g_Links[l];
    g_Blocks.clear();
    g_Links.clear();
}

//--------------------------------------------------------------------------------
// The following function reads in the contents of the specified html file.
// The fomatting rectangle is set using the IwGxFontSetRect() function and other
// formatting information is set using the instantiated CFormatInfo struct.
// Each block of text that is surrounded by a tag is isolated and placed in a
// CBlock item. The DoTag() function is then called to do the required parsing.
//--------------------------------------------------------------------------------
void OpenPage(const char* html)
{
    //Get the contents of the next page
    char* pContents = NULL;
    s3eFile* pFile = s3eFileOpen(html, "rt");
    int32 size = 0;

    //If the file open succeeds, the contents of the file are placed in @a pContents
    //and the buffer is zero terminated.
    if( pFile )
    {
        size = s3eFileGetSize(pFile);
        pContents = (char*)s3eMalloc(size+1);

        //size may be less than file size if NL/CF pairs are converted
        size = s3eFileRead(pContents, 1, size, pFile);

        //Zero-terminate
        pContents[size] = 0;

        size = RemoveNewLines(pContents);

        s3eFileClose(pFile);
    }
    else
    {
        // If page is not found, display error message
        pContents = (char*)s3eMalloc(2048);
        sprintf(pContents, "File '%s' not found", html);
        size = strlen(pContents);
    }

    //Remember gx state and details required to rebuild the page
    if( g_CurrentPageAddress != html )
    {
        if( g_CurrentPageAddress )
            delete g_CurrentPageAddress;

        g_CurrentPageAddress = new char[strlen(html)+1];
        strcpy(g_CurrentPageAddress, html);
    }

    g_ScreenWidth = IwGxGetScreenWidth();
    g_ScreenHeight = IwGxGetScreenHeight();

    //Close old page - NB. This must be done after opening
    //the next page because the next address may be owned by the current page
    ClosePage();

    //Set the format rectangle so text doesn't overlap the Ideaworks logo
    IwGxFontSetRect(CIwRect(10,30,(int16)g_ScreenWidth-10,(int16)g_ScreenHeight-40));

    //Set the default parsing state
    g_Current.m_Colour.Set(0x80,0x80,0x80,0xff);
    g_Current.m_Italic = false;
    g_Current.m_Underline = false;
    g_Current.m_Link = false;
    g_Last = g_Current;

    g_FormatPos = CIwSVec2(0,0);

    //Now iterate the contents, chopping off tags and creating blocks
    char* pCursor = pContents;
    char* pEnd = pContents+size;

    while(pCursor < pEnd)
    {
        //find the continuous span to the next tag
        char* pOpenTag = strchr(pCursor, '<');
        if( !pOpenTag )
        {
            //There are no more tags - create a block for the rest of the text and exit
            AddBlock(pCursor, pEnd - pCursor);
            break;
        }
        else
        {
            //Add a block for the span to the tag's opening
            if( (pOpenTag - pCursor) > 1 )
            {
                AddBlock(pCursor, pOpenTag - pCursor);
            }

            //Find the closing brace of the tag
            char* pCloseTag = strchr(pOpenTag, '>');
            if( !pCloseTag )
            {
                //badly formed tag - end here...
                break;
            }
            else
            {
                //Parse the tag and perform any state changes required for it
                DoTag(pOpenTag + 1, pCloseTag - pOpenTag - 1);
                pCursor = pCloseTag+1;
            }
        }

    }

    // Contents are no longer needed (text now exists as formatted glyphs within CIwGxFontPreparedData classes)
    delete pContents;

    // Default to the first link
    g_SelectedLink = 0;
}

//--------------------------------------------------------------------------------
// Main functions
//--------------------------------------------------------------------------------

void CreateButtonsUI(int w, int h)
{
    // Create the UI layout
    AddButton("Select", 2, h - 10, 42, 10, s3eKeyAbsASK);
}

void SurfaceChangedCallback()
{
    DeleteButtons();
    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//--------------------------------------------------------------------------------
// The following function initialises the resource manager and IwGxFont. The
// Resource Manager is used to load the group file which points to the font
// resources.
// The font resources are then used to form the font and this font is set to
// be the current font using the IwGxFontSetFont() function.
// The display text is loaded from a webpage called main.html.
//--------------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise ResManager and IwGxFont (IwGx has already been initialised by example framework)
    IwGxRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
    IwResManagerInit();
    IwGxFontInit();

    //Load the example's font group
    IwGetResManager()->LoadGroup("IwGxFontBrowser.group");

    //Get default font and set it to be the current font
    CIwGxFont* font = (CIwGxFont*)IwGetResManager()->GetResNamed("arial14", "CIwGxFont");
    IwGxFontSetFont(font);

    //Open the first page
    OpenPage("main.html");

    CreateButtonsUI(IwGxGetScreenWidth(), IwGxGetScreenHeight());
}

//--------------------------------------------------------------------------------
// The following function closes any open html page, and terminates IwGxFont and
// the Resource Manager on shutdown.
//--------------------------------------------------------------------------------
void ExampleShutDown()
{
    // Clear up
    ClosePage();
    if( g_CurrentPageAddress )
        delete g_CurrentPageAddress;

    // Release array storage
    g_Blocks.clear_optimised();
    g_Links.clear_optimised();

    //Terminate modules
    IwGxFontTerminate();
    IwResManagerTerminate();
    IwGxUnRegister(IW_GX_SCREENSIZE, SurfaceChangedCallback);
}

//--------------------------------------------------------------------------------
// The following function calls the OpenPage function which opens and reads in the
// contents of the specified html file. The keyboard state is checked to see if any
// of the s3eKeyAbsUp, s3eKeyAbsDown and s3eKeyAbsASK keys have been pressed, as it
// is using these three keys that the user can browse the three supplied webpages.
//--------------------------------------------------------------------------------
bool ExampleUpdate()
{
    if( g_ScreenWidth != IwGxGetScreenWidth() || g_ScreenHeight != IwGxGetScreenHeight() )
        OpenPage(g_CurrentPageAddress);

    //Up/Down select a link
    if ( CheckCursorState() == EXCURSOR_UP )
    {
        g_SelectedLink--;
    }
    else if ( CheckCursorState() == EXCURSOR_DOWN )
    {
        g_SelectedLink++;
    }
    else if( !g_Links.empty() && CheckButton("Select") & S3E_KEY_STATE_PRESSED )
    {
        //ASK activates the selected link
        OpenPage(g_Links[g_SelectedLink]->m_Addr);
    }

    //Maintains the
    if( g_SelectedLink < 0 )
        g_SelectedLink = g_Links.size() - 1;
    else if( g_SelectedLink >= (int32)g_Links.size() )
        g_SelectedLink = 0;

    //Keep track of which frame we're on for link animation
    g_Tick++;

    return true;
}

//--------------------------------------------------------------------------------
// The following function renders each of the blocks that have been discovered on
// the selected web page.
//--------------------------------------------------------------------------------
void ExampleRender()
{
    //Need lighting on to colour text
    IwGxLightingOn();

    //Render all blocks
    for(uint32 b = 0; b < g_Blocks.size(); b++)
    {
        g_Blocks[b]->Render();
    }

    IwGxPrintString(5, IwGxGetScreenHeight() - 70, "Use Up/Down to select a link", false);
    if(s3ePointerGetInt(S3E_POINTER_AVAILABLE))
        RenderCursorskeys();

    // Flush and show buffer
    IwGxFlush();
    IwGxSwapBuffers();
}
//--------------------------------------------------------------------------------


Airplay API Reference: IwHTTP API Documentation

Airplay API Reference > IwHTTP API Documentation >

IwHTTP API Documentation

The IwHTTP Documentation contains the following sections:

  • IwHTTP API Overview
  • IwHTTP API Reference
  • IwHTTP Examples


Airplay API Reference: IwHTTP API Overview

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Overview >

IwHTTP API Overview

IwHTTP provides an API for performing HTTP requests.

To use IwHTTP functionality in a project, you must include "IwHTTP.h" in your source and iwhttp as a subproject in the project's MKB file:

  • subprojects
  • {
    • iwhttp
  • }

IwHTTP does not include any other Airplay modules as subprojects.

The following subjects are covered in this section:

  • HTTP Client
  • URI Parsing


Airplay API Reference: HTTP Client

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Overview > HTTP Client >

HTTP Client

The module provides an engine for performing HTTP requests through the HTTP Client class, CIwHTTP.

Currently this supports GET and simple POST requests and only implements the most common subset of HTTP. Features such as cookies, caching, authentication or HTTPS are not yet supported. Additional features will be added in subsequent versions, and many of these features could be implemented at a higher level.

Using CIwHTTP

The general style of the API is that you call Get() or Post() to make a request. Then, once the header of the response has been received, you call ReadContent() to get the data, passing in a buffer of the right size (which can now be determined with ContentLength(). The callback supplied at this point will be called when the entire operation is completed. A proxy can be defined in the [connection] section of the app.icf file using httpproxy and httpproxyport settings. If it is not defined, any proxy specified by s3e's S3E_SOCKET_HTTP_PROXY property will be used. If neither are specified, a direct connection is used.

Receiving Data

HTTP makes this more complex than we might like by supporting numerous different ways of specifying the data length. In general, the procedure for getting your data is to repeatedly call ReadContent, supplying a buffer which is either ContentExpected() - ContentReceived() in length, or some relevant size if ContentExpected() == ContentReceived(). That will always work. If you happen to know that the response will include a Content-Length: header then you can just call ReadContent once with either ContentExpected() or ContentLength() bytes.

ContentExpected() will give you the length of all the chunks whose headers have been received when using chunked encoding, or the total length if using the Content-Length header. It will give no useful information if the server is communicating the content length by just closing the socket.

When either all the data has been received, or the currently supplied buffer has been filled, the callback supplied to ReadContent() will be called. This condition can also be determined by looking at ContentReceived()

Note: See Internet standards RFC 2616 for HTTP definition.

For full CIwHTTP method documentation, see the IwHTTP API Reference.


Airplay API Reference: URI Parsing

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Overview > URI Parsing >

URI Parsing

Airplay provides URI passing through the CIwURI class. This is a representation of a URI, as defined in RFC 3986. A URI generically comprises a scheme, an authority (made up of a host and a port), a path a query and a fragment, most of which are optional. For example:

  • "scheme://host:port/path?query#fragment"

In layman's terms, this is the thing that appears in the URL bar of your browser.

Note: For full CIwURI method documentation, see the IwHTTP API Reference.


Airplay API Reference: IwHTTP API Reference

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Reference >

IwHTTP API Reference

Modules

HTTP Client Object
URI Object

Data Structures

class CIwUriEscape
A class for URI-escaping functions. More...

Detailed Description

IwHTTP provides an HTTP client, with the CIwHTTP class, and URI parsing functionality with the CIwURI class.


Airplay API Reference: HTTP Client Object

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Reference > HTTP Client Object >

HTTP Client Object
[IwHTTP API Reference]

Data Structures

class CIwHTTP

Detailed Description

The HTTP client object for performing HTTP requests.

Supports GET and simple POST requests. Currently this only implements the most common subset of HTTP. Features such as cookies, caching, authentication or HTTPS are not yet supported.

Note:
For more information on the HTTP Client Object, see the HTTP Client section in the IwHTTP API Documentation.


Airplay API Reference: URI Object

Airplay API Reference > IwHTTP API Documentation > IwHTTP API Reference > URI Object >

URI Object
[IwHTTP API Reference]

Data Structures

class CIwURI

Detailed Description

The URI Object for representing URIs as defined in RFC 3986.

For more information on the URI Object, see the URI Parsing section in the IwHTTP API Documentation.


Airplay API Reference: IwHTTP Examples

Airplay API Reference > IwHTTP API Documentation > IwHTTP Examples >

IwHTTP Examples

This document provides a set of examples that illustrate how to use the functionality contained within IwHTTP. Each example uses functionality specific to one feature of IwHTTP, and endeavours to illustrate the capabilities of this feature.

The following examples are contained within this section:

  • IwHTTP Example
  • IwHTTP Location Map Example


Airplay API Reference: IwHTTP Example

Airplay API Reference > IwHTTP API Documentation > IwHTTP Examples > IwHTTP Example >

IwHTTP Example

This is an example of the use of the IwHTTP HTTP component. It retreives a page and then displays it. It uses CIwHTTP::Get() to start the request, the ReadContent to actually receive the content.

A note about the length of the content:

HTTP has several different ways of specifying the content length. It can specify the length with the response headers, it can just close the socket at the end or it can provide the content in several 'chunks', each of which has a content length specified. Unfortunately, giving the application developer the control over memory allocation that's often needed on mobile means that this complexity must be exposed to the client. There are 3 related functions that indicate the length of the content. ContentLength() returns the total length of the content if known, or 0 if it isn't known. ContentExpected() returns the length of everything we're certain to be getting, which could be just the chunks that we're expecting, or could be 0 if the server is indicating the length by closing the socket. ContentReceived() indicates the ammount of data so far delivered to the client.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------

#include "IwHttpExample.h"
#include <string>
#include "s3eMemory.h"
#include "ExamplesMain.h"
#include "IwGx.h"
#include "IwGxPrint.h"

enum HTTPStatus
{
    kNone,
    kDownloading,
    kOK,
    kError,
};

#define THE_URI "http://http-test.ideaworks3d.net/example.txt"
CIwHTTP *theHttpObject;
char* result = NULL;
uint32 len;
HTTPStatus status = kNone;

static int32 GotData(void*, void*)
{
    // This is the callback indicating that a ReadContent call has
    // completed.  Either we've finished, or a bigger buffer is
    // needed.  If the correct ammount of data was supplied initially,
    // then this will only be called once. However, it may well be
    // called several times when using chunked encoding.

    // Firstly see if there's an error condition.
    if (theHttpObject->GetStatus() == S3E_RESULT_ERROR)
    {
        // Something has gone wrong
        status = kError;
    }
    else if (theHttpObject->ContentReceived() != theHttpObject->ContentLength())
    {
        // We have some data but not all of it. We need more space.
        uint32 oldLen = len;
        // If iwhttp has a guess how big the next bit of data is (this
        // basically means chunked encoding is being used), allocate
        // that much space. Otherwise guess.
        if (len < theHttpObject->ContentExpected())
            len = theHttpObject->ContentExpected();
        else
            len += 1024;

        // Allocate some more space and fetch the data.
        result = (char*)s3eRealloc(result, len);
        theHttpObject->ReadContent(&result[oldLen], len - oldLen, GotData);
    }
    else
    {
        // We've got all the data. Display it.
        status = kOK;
    }
    return 0;
}

//-----------------------------------------------------------------------------
// Called when the response headers have been received
//-----------------------------------------------------------------------------
static int32 GotHeaders(void*, void*)
{
    if (theHttpObject->GetStatus() == S3E_RESULT_ERROR)
    {
        // Something has gone wrong
        status = kError;
    }
    else
    {
        // Depending on how the server is communicating the content
        // length, we may actually know the length of the content, or
        // we may know the length of the first part of it, or we may
        // know nothing. ContentExpected always returns the smallest
        // possible size of the content, so allocate that much space
        // for now if it's non-zero. If it is of zero size, the server
        // has given no indication, so we need to guess. We'll guess at 1k.
        len = theHttpObject->ContentExpected();
        if (!len)
        {
            len = 1024;
        }

        s3eFree(result);
        result = (char*)s3eMalloc(len + 1);
        result[theHttpObject->ContentExpected()] = 0;
        theHttpObject->ReadContent(result, theHttpObject->ContentLength(),
                                GotData, NULL);
    }

    return 0;
}

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

//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    theHttpObject->Cancel();
    delete theHttpObject;
    s3eFree(result);

    IwGxTerminate();
}

// From this point on, the code is general housekeeping functions
// common to other examples.

bool ExampleUpdate()
{
    if(status == kNone)
    {
        theHttpObject = new CIwHTTP;
        theHttpObject->Get(THE_URI, GotHeaders, NULL);
        status = kDownloading;
    }

    return true;
}

//-----------------------------------------------------------------------------
void ExampleRender()
{
    // Clear screen
    IwGxClear( IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F );

    // Render text
    if(status == kOK)
        IwGxPrintString(10, 50, result, 1);
    else if(status == kError)
        IwGxPrintString(10, 50, "Error!", 1);
    else
        IwGxPrintString(10, 50, "Connecting...", 1);

    // Swap buffers
    IwGxFlush();
    IwGxSwapBuffers();
}


Airplay API Reference: IwHTTP Location Map Example

Airplay API Reference > IwHTTP API Documentation > IwHTTP Examples > IwHTTP Location Map Example >

IwHTTP Location Map Example

The following example uses S3E's Location API to display the user's current lattitude, longitude and altitude. It also displays the accuracy of the location in meters. The application then attemps to connect to Google Map to download the map image of the user's location.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

#include "ExamplesMain.h"
#include "s3e.h"
#include "s3eLocation.h"

static s3eLocation g_Location;
static s3eResult g_Error = S3E_RESULT_ERROR;

void ExampleInit()
{
    s3eLocationStart();
}

void ExampleShutDown()
{
    s3eLocationStop();
}

bool ExampleUpdate()
{
    g_Error = s3eLocationGet(&g_Location);

    if (g_Error != S3E_RESULT_SUCCESS)
    {
        g_Location.m_Latitude = 51;
        g_Location.m_Longitude = -0.1;
    }

    return true;
}

//-----------------------------------------------------------------------------
// The following function displays the current time.
//-----------------------------------------------------------------------------
void ExampleRender()
{
    const int   textHeight = s3eDebugGetInt(S3E_DEBUG_FONT_SIZE_HEIGHT);
    int         y = 50;
    char        buf[256];

    if (g_Error == S3E_RESULT_ERROR)
    {
        s3eDebugPrint(10, y, "`x666666Could not determine location!", 0);
        return;
    }

    snprintf(buf, sizeof(buf), "`x666666Latitude %f", (float)g_Location.m_Latitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666Longitude %f", (float)g_Location.m_Longitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666Altitude %f", (float)g_Location.m_Altitude);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666H accuracy %f", (float)g_Location.m_HorizontalAccuracy);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;

    snprintf(buf, sizeof(buf), "`x666666V accuracy %f", (float)g_Location.m_VerticalAccuracy);
    s3eDebugPrint(10, y, buf, 0);
    y += textHeight;
}


Airplay API Reference: IwUI API Documentation

Airplay API Reference > IwUI API Documentation >

IwUI API Documentation

The IwUI documentation contains the following sections:

  • IwUI API Overview
  • IwUI API Reference
  • IwUI Examples


Airplay API Reference: IwUI API Overview

Airplay API Reference > IwUI API Documentation > IwUI API Overview >

IwUI API Overview

IwUI is a new flexible user interface framework for Airplay.

Note: This module is currently a beta component of the Airplay SDK. IwUI interfaces are likely to change before the release version.

To use IwUI functionality, you must include "IwUI.h" in your source and iwui as a subproject in your project's MKB file:

  • subprojects
  • {
    • iwui
  • }

The following subjects are covered in this section:

  • Overview of UI Concepts
  • Elements
  • Properties and Styles
  • The Event Framework
  • The Rendering System
  • Layout Management
  • The Animation System
  • Delegates


Airplay API Reference: Overview of UI Concepts

Airplay API Reference > IwUI API Documentation > IwUI API Overview > Overview of UI Concepts >

Overview of UI Concepts

The central concept in IwUI is that of an element, CIwUIElement. Instances of this class can be used as containers of other elements, providing for hierarchical layout, rendering and event passing.

A number of specific element classes are derived from CIwUIElement. Each of these provide specific behaviours and appearances. Examples include CIwUIImage - which simply renders an image to the screen, CIwUILabel - which renders static text fields, and CIwUIScrollableView - which provides rendering and navigation about a set of children which cover a larger area than itself.

Clients of IwUI may of course derive their own custom element classes, either from CIwUIElement directly or from one of the existing specialised elements. In doing so they have complete control over the rendering, event handling and other properties of their new element class.

User interfaces may be created in code or data, with equal flexibility. Elements are defined (as resources) in data through the use of .ui files. While these files have a custom extension, they are in fact simply ITX files. UI elements can therefore be defined inline in group files, if you so wish. To maintain consistent ownership across programmatic and data-driven elements, all elements which are added to the user interface are owned by it. Resources cannot be added (as they are owned by the resource system). Instead, element resources can be cloned (via CIwUIElement::CreateFromResource). This performs a deep copy of the element and its descendants which can then be added to the user interface.

IwUI provides two top-level manager classes, CIwUIController and CIwUIView. The controller deals with event generation and dispatch. The view deals with functionality relating to the visual appearance of elements, such as rendering and intersection testing, and it also manages the element hierarchy. Clients are encouraged to derive custom versions of these classes in order to perform application-specific top-level functionality.

Rather than storing element properties as member variables of each class, IwUI employs a generalised, typesafe property set system. Each element may point to a property set resource, but can also override each property as desired. Properties may also be shared via the element hierarchy - if a property is not found in the element's property set, the property sets of its ancestors may be searched.

The UI rendering system has been designed with flexibility and efficiency in mind. All drawing takes place via the CIwUIGraphics rendering interface. This supports drawing of text and images, hierarchical transforms, clipping and colour modulation, and the ability to draw the 2D interface with an arbitrary 3D viewspace transform. Behind the scenes it performs automated batching to minimise draw calls on accelerated graphics hardware, and supports use of atlassed materials generated by the Airplay Studio atlassing system.

To further simplify the creation of custom element drawing, the IIwUIDrawable interface is provided, together with the concrete implementations CIwUIDrawableImage, CIwUIDrawableText, CIwUIDrawableBorder. These classes facilitate the drawing of common graphics primitives with a degree of polymorphism. Drawable objects can all be constructed via property sets, allowing for data-driven look and feel and clean sharing of rendering data.

A flexible event system is provided. User events such as key presses and screen touches are converted into corresponding UI events which are sent to the UI controller. This dispatches them to the appropriate element. Standard events are classified within the element base class event handler, allowing derived classes to easily respond to a single class of event. If an element doesn't handle an event then it is passed up the hierarchy until either it is handled or until the top of the hierarchy is reached. Although subclassing can be used to modify this default behaviour, an event filtering mechanism is implemented, the use of which is encouraged. Using this clients of IwUI can intercept events at either an element or at application level.

Related to the events system is the signals and slots system. This system allows more direct links to be made between events (signals) and their handlers (slots), facilitating the re-use of elements and the construction of higher-level functionality either through code or data.

To deal with the issues of variable-sized text strings (particularly through localisation) and varying target screen sizes a layout management system has been implemented. Any element may have a layout assigned to it. The layout is responsible for sizing the element and its immediate children in a manner appropriate to their preferences (minimum size, maximum size, hint size, alignments, etc). Concrete implementations of the CIwUILayout base class include CIwUILayoutVertical (simple vertical layout), CIwUILayoutHorizontal, and CIwUILayoutGrid (html-style table layout).

A 2D animation system supports animations defined as resources. The CIwUIAnimManager singleton is used to play an animation on an element.

A smart pointer class, CIwUIElementPtr, allows pointers elements be held whilst avoiding typical object lifetime issues. If the pointed-to element is destroyed, the pointer is NULLified.


Airplay API Reference: Elements

Airplay API Reference > IwUI API Documentation > IwUI API Overview > Elements >

Elements

In IwUI, user interfaces are built up from a hierarchy of elements. There are a number of element types derived from the CIwUIElement base class, each of which adds specific logical and graphical functionality peculiar to a particular control type - such as a button, a label or a progress bar.

The root and owner of the element hierarchy is the view singleton. Elements may be added to this directly, in which case they become top-level elements with position relative to the top-left of the screen.

    #include "IwUI.h"
    #include "IwUIController.h"
    #include "IwUIView.h"

    int main()
    {
        // Initialize IwUI, create default singletons
        IwUIInit();
        new CIwUIView;
        new CIwUIController;

        // Create an element and add it at the view's top level
        CIwUIElement* pElement = new CIwUIElement;
        IwGetUIView()->AddElement(pElement);

        // Process (one logic, one render) until device quit
        const int32 frametime = 25;
        while (!s3eDeviceCheckQuitRequest())
        {
            // Clear frame buffer
            IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

            // Update ui singletons
            IwGetUIController()->Update();
            IwGetUIView()->Update(frametime);

            // Render ui
            IwGetUIView()->Render();

            // Show
            IwGxFlush();
            IwGxSwapBuffers();
        }

        // Shutdown IwUI
        delete IwGetUIView();
        delete IwGetUIController();
        IwUITerminate();
    }

Active elements

Any element which is added to the view (either directly at the top-level or through adding to an element which already exists in the hierarchy) becomes active, with the Activate(...) virtual being called with parameter true on the added element and its descendants. This function is typically used to create rendering primitives which are only required when the element may be drawn (and to destroy them when they are deactivated).

    CIwUIElement* pParent = new CIwUIElement;
    CIwUIElement* pChild = new CIwUIElement;

    // 'pParent' becomes active [Activate(true)]
    IwGetUIView()->AddElement(pParent);

    // 'pChild' becomes active [Activate(true)]
    pParent->AddChild(pChild);

    // Both 'pParent' and its 'pChild' are deactivated [Activate(false)]
    IwGetUIView()->RemoveElement(pParent);

The primary reason for the concept of activity is to provide a clear separation between that data of an element which must be defined and persist and that data which can be derived and ephemeral. Also there is some state which depends on the element's location within the hierarchy, and so which is pointless to generate out of context.

The element hierarchy

All elements may contain children, and thus form a hierarchy. All children are owned by their parent, meaning that if the parent is destroyed, the entire branch is destroyed. The element hierarchy is fundamental to element processing, the event system and the rendering system.

In the event system, events which are not handled by a particular element are passed up to its parent, allowing events to be handled at whatever level in the tree is most suitable.

In the rendering system, it provides the hierarchy down which clipping, transform and colour information is propagated, as well as allowing whole branches of the hierarchy to be hidden simply by hiding a single parent element. Intersection testing is also carried out hierarchically.

Element updating can be disabled or enabled for branches of the hierarchy simply by disabling or enabling updating of a single parent element.

    CIwUIElement* pDialog = new CIwUIElement;
    pDialog->SetSize(CIwVec2(150, 200));

    CIwUIElement* pButton = new CIwUIButton;
    pButton->SetPos(CIwVec2(20, 180));
    pButton->SetSize(CIwVec2(50, 20));
    //... -> set button properties, eg style, caption, etc.
    pDialog->AddChild(pButton);

    CIwUIElement* pLabel = new CIwUILabel;
    pLabel->SetPos(CIwVec2(20, 20));
    pLabel->SetSize(CIwVec2(110, 120));
    //... -> set label properties, eg style, caption, etc.
    pDialog->AddChild(pLabel);

    // Add dialog hierarchy to the view
    IwGetUIView()->AddElement(pDialog);

    // Remove dialog hierarchy from the view
    IwGetUIView()->RemoveElement(pDialog);

    // Destroy the dialog and its children
    delete pDialog;

Cloning elements

Treating elements as simple objects which can be copy-constructed and assigned to would be fraught with peril. Slicing is the problem which immediately comes to mind. Whether it makes sense to simply copy all members wholesale is another.

For these reasons, CIwUIElement is uncopyable, with private copy constructor and copy assignent declarations. In their place, the Clone method is provided. This both deals with 'virtual copy construction' and allows elements to implement cloning in a semantically appropriate manner.

    CIwUIElement* pTree = new CIwUIElement;

    // Add some standard child elements
    pTree->AddChild(new CIwUILabel);
    pTree->AddChild(new CIwUIButton);
    pTree->AddChild(new CIwUITable);
    CIwUIElement* pSubtree = new CIwUIElement;
    pTree->AddChild(pSubtree);
    pSubtree->AddChild(new CIwUIScrollableView);
    pSubtree->AddChild(new CIwLabel);

    // Clone the entire tree a couple of times
    CIwUIElenent* pTree2 = pTree->Clone();
    CIwUIElenent* pTree3 = pTree->Clone();

    // Add it at various positions in the top level view
    // (and prepare for asserts, as we've set no properties on our elements...!)
    pTree->SetPos(CIwVec2(50, 50));
    pTree2->SetPos(CIwVec2(100, 100));
    pTree3->SetPos(CIwVec2(200, 150));
    IwGetUIView()->AddElement(pTree);
    IwGetUIView()->AddElement(pTree2);
    IwGetUIView()->AddElement(pTree3);

To support this functionality, all custom elements must override virtual void Clone(CIwUIElement* pTarget) const, making use of the IW_UI_CLONE_SUPERCLASS macro (which exists to ensure that all elements support cloning).

    // A custom element...
    class CMyCustomElement : public CIwUIElement
    {
        virtual void Clone(CIwUIElement* pTarget) const;
        int m_CustomData;
    };

    // ... and its clone method
    void CMyCustomElement::Clone(CIwUIElement* pTarget) const
    {
        // Call macro (to notify IwUI that we've defined the clone method)
        IW_UI_CLONE_SUPERCLASS(pTarget, CMyCustomElement, CIwUIElement);

        // Copy custom data to target
        CMyCustomElement* pMyTarget = IwSafeCast<CMyCustomElement*>(pTarget);
        pMyTarget->m_CustomData = m_CustomData;
    }

Element resources

Although elements can be constructed and defined entirely in code, the more typical usage is for them to be cloned from pre-defined resources created in the IwUI Designer tool (or directly in text by the masochistic).

(ok, there isn't actually a tool yet. So I'll need to describe the format. UI elements are defined in the typical .itx manner, with child elements simply nested in the scope of their parent. Properties are set as name-value pairs, as are member attributes such as position, visibility, colour. Whilst a .ui file extension is recommended, the format acts the same as vanilla .itx files. ie. any top-level elements will be added to the resource group in either case).

    // Defining an element resource (in a .group, a .itx or a .ui, as you please)
    CIwUIElement
    {
        name    my_first_element_resource
        pos     { 20, 20 }
        size    { 200, 200 }

        CIwUILabel
        {
            name        test_label
            pos         { 35, 25 }
            sizeToContent   true
            font        someloadedfont
            caption     "Hello world"
        }

        CIwUIButton
        {
            name        test_button
            pos         { 35, 125 }
            size        { 100, 20 }
            font        someloadedfont
            caption     "Quit"
            buttonUp    somedrawablestyle
            buttonDown  someotherdrawablestyle
        }
    }

.ui files and the elements they contain are managed by resource groups in the same way as any other Airplay resource object. Although the user can retrieve a pointer to a UI element resource through the resource manager, this should not be done (as resources should be used to create elements and nothing more). Instead, the CIwUIElement::CreateFromResource function should be used to create a new element instance (including descendants) from a resource, which is then owned by the caller and can be modified and used as he pleases.

    CIwUIElement* pMyFirstElement =
        CIwUIElement::CreateFromResource("my_first_element_resource");
    IwGetUIView()->AddElement(pMyFirstElement);

    // Once created from a resource, I can do what I like...
    CIwUIElement* pMySecondElement =
        CIwUIElement::CreateFromResource("my_first_element_resource");
    CIwUIElement* pMyThirdElement = pMySecondElement->Clone();
    delete pMySecondElement;
    IwGetUIView()->AddElement(pMyThirdElement);

Custom elements

Whilst IwUI provides a range of standard element types, it is likely that clients will wish to modify or add to these. This can be done by either subclassing an existing element type, else subclassing CIwUIElement directly. The advantage of the former is that a fully-featured element interacts with a number of systems (rendering, user interaction, events, layout, styles and properties, intersection testing) - subclassing and overriding a single part of that functionality is obviously more straightforward than implementing from scratch, where appropriate.

Custom elements must at the very least implement their own Clone method. Beyond this, they are likely to want to implement a custom version of Activate and OnPropertyChanged.

For any element which stores additional data (excluding properties, which are managed automatically for all elements), the parsing methods (e.g. ParseAttribute etc.) and serialising methods (Serialise and Resolve) will need to be written.

Intersection testing, rendering and layout provide two hooks for customisation. First, and recommended, are the functions IntersectElement, RenderElement and MeasureElement. These methods act on the element only, and can be overridden without fear of modifying higher-level functionality. If, however, this is your intention, you will need to override the default versions of Intersect, Render and Measure.

In a similar manner event handling has two tiers. Clients are encouraged to override the more specific handlers such as HandleEventClick rather than CIwUIElement::HandleEvent itself - but are not forced to.

For finer-grained customisation than this, please refer to the CIwUIElement documentation for an exhaustive list of virtual functions.

For more information on custom elements, please see the relevant examples.


Airplay API Reference: Properties and Styles

Airplay API Reference > IwUI API Documentation > IwUI API Overview > Properties and Styles >

Properties and Styles

A property set is a mapping of strings to data. Each property set also stores a parent pointer. If a property is queried which doesn't exist in the current set, the parent set(s) are searched in turn.

IwUI's elements (and layouts) store most of their configuration data as property sets rather than as member data. There are a number of reasons for this:

  • Properties common to many elements may be shared, which both makes the elements more lightweight and allows the look and feel of many elements to be modified at once.
  • Element cloning, parsing, serialisation and property access is simplified as the property system deals with this transparently.
  • By decoupling type data from instance data, a level of indirection is added which facilitates global style changes.
  • Default properties emerge naturally.

The disadvantages of the approach are:

  • Properties are dynamically allocated, making the creation of new properties slower than member storage, and potentially causing fragmentation issues (although this is mitigated by storing properties in their own memory bucket).
  • Querying properties is naturally a little slower than would be the case with member data.

Property access

Although properties are stored as heterogeneous lists, type-safe access to them is provided via the use of templates. As an example, here is the "caption" property of a CIwUILabel being set and retrieved:

    // Set the caption property. If the property has changed,
    // the element's OnPropertyChanged virtual will be called with the
    // string "caption", allowing the label to rebuild its graphical
    // representation if necessary. Note that the string has to be
    // passed explicitly as a CIwPropertyString - a raw char* pointer
    // would not provide enough information for template type
    // deduction.
    pLabel->SetProperty("caption", CIwPropertyString("Hello world!"));

    // Retrieve the caption property for this label. The third
    // parameter controls whether or not absence of the property
    // is acceptable. In this case we say that it isn't, meaning
    // an assert will fire if the property isn't found in the
    // element's property set or any parent property sets.
    CIwPropertyString string;
    pLabel->GetProperty("caption", string, false);

In .itx files, properties are specified like any other attribute. The element's parsing code automatically recognises attributes which are properties are takes care of parsing them in an appropriate manner for their type. Repeating the label example...

            CIwUILabel
            {
                name    example_label
                caption "Hello world!"
            }

Custom elements

Naturally, clients of IwUI are likely to want to define their own named properties. This is done in data by adding definitions like the following to the resident resource group:

            CIwPropertyDefine { "MyColourProperty" CIwColour }
            CIwPropertyDefine { "MyStringProperty" CIwPropertyString }

Forgetting to do this will lead to properties not being recognized by the property system.

Custom property types

Users may also define new data types to be used by the property system. This is more involved than simply adding new property names, and is best demonstrated by example - in this case, how the horizontal alignment enum becomes a property in IwUI itself.

            // Source file declaration for the new property data type
            IW_PROPERTY_DECLARE_DATA_TYPE(IwUIAlignmentH);

            // Property type registration (at the same time as one would
            // register class factories)
            IwPropertyAddPropertyFactory<IwUIAlignmentH>();

            // Template specialisation enabling parsing of the new property
            template<>
            void CIwPropertyDataType<IwUIAlignmentH>::Parse(IwUIAlignmentH& data,
                CIwTextParserITX* pParser)
            {
                static const char* ppNames[] = { "left", "centre", "right", NULL };
                uint32 val;
                char buffer[32];
                pParser->ReadString(buffer, 32);
                pParser->FilterStringGetEnumAsserted(buffer, ppNames, val);
                data = (IwUIAlignmentH) val;
            }

            // Template specialisation enabling serialisation of the new property
            template<>
            void CIwPropertyDataType<IwUIAlignmentH>::Serialise(IwUIAlignmentH& data)
            {
                IwSerialiseEnum(&data);
            }

Styles

To facilitate multiple skins, a level of indirection is imposed between elements and their parent property set (which generally defines common attributes across a set of elements). This takes the form of the CIwUIStyle object. Rather than setting a parent property set directly on an element, a style is set on it instead.

Styles are simply names. By default the property set with this name is looked up in the resource system and used as the element's parent property set. This default behaviour can be changed through the use of CIwUIStylesheet. This class explicitly maps styles to property sets. The CIwUIStyleManager can have one stylesheet active. When this is the case, the stylesheet is used to resolve the style name to a property set BEFORE the resource system is searched.

Using this system multiple 'skins' can be defined and switched between at will, simply by calling CIwUIStyleManager::SetStylesheet (any active elements will be deactivated and reactivated at this point, forcing properties to be requeried).

Stylesheets can be loaded as resources or created in code.


Airplay API Reference: The Event Framework

Airplay API Reference > IwUI API Documentation > IwUI API Overview > The Event Framework >

The Event Framework

IwUI provides a traditional event model.

All events are objects derived from Airplay's CIwEvent base class, allowing them to be handled by any object derived from the CIwManaged base class which implements HandleEvent.

Sending events

Events are sent via CIwUIController, the central controller class. This can be done either synchronously via SendEvent , which handles the event immediately, or PostEvent , which queues events to be processed at the next call of CIwUIController::Update.

With both SendEvent and PostEvent the user may explicitly specify an element to receive the event, or leave it to the controller to determine the appropriate element. In the latter case, key events are sent to the element which currently holds the keyboard focus whilst pointer events are sent to the element lying beneath the pointer.

            // Extending the event ID enum for our own custom event
            enum
            {
                MY_EVENT_ID = IW_EVENT_USER
            };

            // Declaring a custom event
            class CMyEvent : public CIwEvent
            {
            public:
                IW_EVENT_DECLARE(CMyEvent, MY_EVENT_ID);
                CIwUIEventFocus(int data) : m_Data(data) { Create(); }

                int GetData() const { return m_Data; }

            private:
                int m_Data;
            };

            // Sending the event to the element named 'my_element'
            CMyEvent event1(1);
            CIwUIElement* pMyElement = IwGetUIView()->GetChildNamed("my_element");
            IwGetUIController()->SendEvent(pMyElement, &event1);

            // Posting the event to the element under the pointer
            // (to be processed next time the ui controller is updated)
            CMyEvent* pEvent2 = new CMyEvent(2);
            CIwUIElement* pPointedElement =
                IwGetUIView()->Intersect(CIwVec2(s3ePointerGetX(), s3ePointerGetY()));
            IwGetUIController()->PostEvent(pPointedElement, pEvent2);

Certain events are generated automatically by the UI controller. These are:

  • Key presses
  • Pointer clicks
  • Pointer movement

Handling events

For each event that is received, event handlers are processed in the following order, with a return value of true from any terminating the event's propagation:

  • First, any application-level event handlers are allowed to filter the event.
        // Call FilterEvent() on application-level event handlers
    if (CIwUIController::FilterEvent(pEvent))
    {
        // Event was filtered by the application.
        return true;
    }
  • Next, the event is passed down through the element hierarchy through an element instance-specific event handlers. Each handler is allowed to filter the event. If no filter traps the event, then the last handler called is the element's own.

    bool CIwUIController::_FilterEvent(CIwEvent* pEvent, CIwUIElement* pElement)
    {
        CIwUIElement* pParent = pElement->GetParent();

        // Allow parent to filter event first
        if (pParent)
        {
            if (_FilterEvent(pEvent, pParent))
            {
                return true;
            }
        }

        // Pass through elements handlers
        return _CallFilterEvent(pElement, pEvent);
    }

  • Next the element's HandleEvent virtual is called. The default implementation of this first calls HandleEvent() on registered handlers. If no handler traps the event, the element classifies common event types and calls a more specific event handler, where one exists (for instance, HandleEventClick ).
    // Pass to target to handle directly
    if (pTarget->HandleEvent(pEvent))
    {
        // Element handled the event.
        return true;
    }
  • If this element doesn't handle the event, it is passed to the element's parent for handling, if one exists.
        // Try parent
    pTarget = pTarget->GetParent();
  • If the root of the hierarchy is reached without the event being handled, HandleEvent is called. Clients of IwUI may wish to override this function - the default implementation calls HandleEvent() on the event to registered event handlers.

Here's some example code showing how we could create a custom label type which reverses its (short) text when pressed:

    class CMyFlippingLabel : public CIwUILabel
    {
        virtual bool HandleEventClick(CIwUIEventClick* pEventClick)
        {
            // Get current string
            CIwPropertyString caption;
            GetProperty("caption", caption);

            // Reverse it
            char buffer1[64];
            char buffer2[64];
            strcpy(buffer1, caption.c_str());
            int i, j;
            for (i = strlen(buffer1) - 1, j = 0; i >= 0; --i, ++j)
            {
                buffer2[j] = buffer1[i];
            }
            buffer2[j] = '\0';

            // Set reversed string
            const CIwPropertyString reversed(buffer2);
            SetProperty("caption", reversed);
            return true;
        }
    };

Event handlers

Event handlers may be installed at both the application and element level. These are objects derived from IIwUIEventHandler which implement either HandleEvent() or FilterEvent() functions.

Event handlers provide a means by which the default application and element event handling behaviours may be modified without subclassing.

    // Event filter which counts key presses (without affecting them)
    struct Lurker : public IIwUIEventHandler
    {
        Lurker() : m_Count(0) {}

        virtual bool FilterEvent(CIwEvent* pEvent)
        {
            if (pEvent->GetID() == IWUI_EVENT_KEY)
            {
                CIwUIEventKey* pEventKey = IwSafeCast<CIwUIEventKey*>(pEvent);
                if (pEventKey->GetPressed())
                {
                    m_Count += 1;
                }
            }

            // Return false so that the event continues to propagate
            return false;
        }

        int m_Count;
    };

    // Event filter which suppresses pointer clicks
    struct Squasher : public IIwUIEventHandler
    {
        virtual bool FilterEvent(CIwEvent* pEvent)
        {
            if (pEvent->GetID() == IWUI_EVENT_CLICK)
            {
                // No clicks please!
                return true;
            }
            else
            {
                // OK, we'll let this event through.
                return false;
            }
        }
    };

    // Count all key presses (by installing an application-level event filter)
    Lurker lurker;
    IwGetUIController()->AddEventHandler(&lurker);

    // Squash pointer clicks on "my_element" (by installing an element-level
    // event filter)
    Squasher squasher;
    CIwUIElement* pElement = IwGetUIView()->GetChildNamed("my_element");
    pElement->AddEventHandler(&squasher, false);

Event types

Each event has its own specific class which uniquely identifies its type (available at runtime via pEvent->GetID()) and often adds additional data specific to the event. Many of IwUI's built-in event types have specific handlers defined in CIwUIElement, allowing clients to define custom elements with overridden behaviour for particular event types.

Examples of events include CIwUIEventKey, CIwUIEventClick and CIwUIEventFocus (all of which have custom handler virtuals in CIwUIElement).

Broadcasting events

Events can also be broadcast to all elements via the controller's BroadcastEvent method. In this case the return value of each individual handler is ignored, and only element HandleEvent functions are called - filters are ignored.

    // Broadcasting MyCustomEvent
    CMyEvent myevent;
    IwGetUIController()->BroadcastEvent(&myevent);

Modifying event behaviour

The recommended way of modifying event behaviour is via handlers, or in the case of custom elements, by overriding the specific event handlers (eg. HandleEventClick ).

Of course, the element's CIwUIElement::HandleEvent virtual can itself be overridden, but this bypasses more functionality than would typically be required, so should be avoided. The controller's NotifyEvent virtual can also be overridden, but this also is not recommended, for similar reasons.


Airplay API Reference: The Rendering System

Airplay API Reference > IwUI API Documentation > IwUI API Overview > The Rendering System >

The Rendering System

The rendering system provides image and text primitive drawing functions. The primitives are transformed, clipped and coloured depending on the current CIwUIGraphics context.

The process for rendering within IwUI is usually as follows:

  • The user calls CIwUIView::Render. This constructs a default CIwUIGraphics context and passes it to CIwUIElement::Render of the root element.
  • CIwUIElement::Render is responsible for creating a local CIwUIGraphics context and setting appropriate settings such as clipping rectangle and transform.
  • CIwUIElement::Render calls CIwUIElement::RenderElement to allow derived elements to draw their content.
  • Instead of drawing primitives directly from CIwUIElement::RenderElement, derived elements usually create concrete implementations of IIwUIDrawable to the encapsulate the information to draw an image or text. The element then calls IIwUIDrawable::Draw on the appropriate drawables.
  • Implementations of IIwUIDrawable::Draw call CIwUIGraphics::DrawImage and CIwUIGraphics::DrawText to do primitive drawing.
  • Primitive draw calls are batched internally by material into larger streams. This is important to maintain performance on platforms each HW draw call has a significant overhead.


Airplay API Reference: Layout Management

Airplay API Reference > IwUI API Documentation > IwUI API Overview > Layout Management >

Layout Management

Layouts are used in IwUI to arrange child elements to fit within the available space. There are a number of different layout classes to provide a range of options on how to arrange elements. Elements interact with the layout system to provide information about how much space they require for their content.

For example, a number of text label elements can be placed within the columns of a grid layout. The grid will automatically adjust the width of the columns to best accommodate the amount of text within the labels.

    CIwUILabel* pLabel1 = new CIwUILabel;
    pLabel1->SetStyle("<label_large>");
    pLabel1->SetCaption("Hello World.");

    CIwUILabel* pLabel2 = new CIwUILabel;
    pLabel2->SetStyle("<label_large>");
    pLabel2->SetCaption("I've got a lot to say so give me room!");

    CIwUILayoutGrid* pGrid = new CIwUILayoutGrid;
    pGrid->AddColumn();
    pGrid->AddColumn();
    pGrid->AddRow();

    pGrid->AddElement(pLabel1, 0, 0);
    pGrid->AddElement(pLabel2, 1, 0);

    CIwUIElement* pContainer = new CIwUIElement;
    pContainer->SetSizeToContent(true);
    pContainer->SetLayout(pGrid);

    IwGetUIView()->AddElementToLayout(pContainer);

A CIwUIElement can have a CIwUILayout attached to it to be responsible for controlling the size and positions of a number of the immediate children of the CIwUIElement. The CIwUILayout itself can have a subhierarchy of other layouts. The child elements are then attached as appropriate into this layout hierarchy.

For example, the vertical layout CIwUILayoutVertical arranges items into a vertical column. Similarly the horizontal layout CIwUILayoutHorizontal arranges items into a row. Hence, a number of button elements, contained in a parent element, could be arranged into rows and columns using nested horizontal and vertical layouts.

The parent element would have attached to it a CIwUILayoutVertical which contained a number of CIwUILayoutHorizontal. Each button would then be attached to one instances of CIwUILayoutHorizontal.

    CIwUIButton* pButtonLeft = new CIwUIButton;
    pButtonLeft->SetStyle("<button>");
    pButtonLeft->SetCaption("Left");

    CIwUIButton* pButtonRight = new CIwUIButton;
    pButtonRight->SetStyle("<button>");
    pButtonRight->SetCaption("Right");

    CIwUIButton* pButtonCentre = new CIwUIButton;
    pButtonCentre->SetStyle("<button>");
    pButtonCentre->SetCaption("Centre");

    CIwUILayoutVertical* pVertical = new CIwUILayoutVertical;
    CIwUILayoutHorizontal* pHorizontal = new CIwUILayoutHorizontal;

    pHorizontal->AddElement(pButtonLeft);
    pHorizontal->AddElement(pButtonRight);

    pVertical->AddLayoutItem(pHorizontal);
    pVertical->AddElement(pButtonCentre);

    CIwUIElement* pContainer = new CIwUIElement;
    pContainer->SetSizeToContent(true);
    pContainer->SetLayout(pVertical);

    IwGetUIView()->AddElementToLayout(pContainer);

Layout invalidation and update

Updating layouts can be computationally intensive. Hence, layouts are only updated when necessary. A layout is invalidated to indicate it should be updated. Invalidation is propagated up the element hierarchy to the root element. The root element's layout is updated, by default, at the end of CIwUIView::Update().

When the content of an element changes which requires layout to be updated, CIwUIElement::InvalidateLayout() should be called. Invalidating an element's layout may subsequently cause sibling element's layout to be updated. Various parts of the layout system, such as CIwUILayoutItemContainer, implement caching to help avoid unnecessary calculations.

Layout calculation

The process of calculating a layout has two stages: measure and arrange. The first stage, measure, is used to determine how much space an element or layout requires/desires given an amount of available space. The amount of available space offered may be infinite (indicated by LAYOUT_INFINITY) in which case the element should return its preferred size. The preffered size for an element can be indicated by its 'sizeHint' property. For example, a vertical layout (CIwUILayoutVertical), which is not set to 'sizeToSpace' allows contained items a infinite amount of vertical space.

The amount of space an element or layout requires is dependent on how much space their child elements or child layout items respectively require. Hence, measuring is a recursive process. An element determines, in CIwUIElement::Measure(), the space required for its child elements by calling CIwUILayout::MeasureItem() on its attached layout. Only child elements which are attached to the layout are considered for their space requirements. Layouts and elements maybe measured a number of times before an appropriate size is determined.

Once a size has been determined for each element, the elements are arranged. The process of arrangement determines a new position and size for each element who's layout was invalidated. The amount of space given to an element maybe greater than its required size. The element's alignment (both horizontal and vertical) is then used to position with the allocated space.

Layout properties

Various properties, of both elements and layout, control the process of layout, and ultimately the position and size given to elements. Some properties are particular to certain layouts, for example column and row are only applicable to a grid layout.

An example of specifying layout properties in a .ui file:

    CIwUIElement
    {
        name "Vertical"

        CIwUILabel
        {
            name        "Label"
            font        font_large
            caption     "HELLO WORLD"

            sizeMin     { 0 20 }
            sizeHint    { -1 30 }
            sizeToContent   true
        }
        CIwUIImage
        {
            name        "Image"
            texture     Image

            sizeMin     { 16 16 }
            sizeToContent   true
        }
        CIwUILayoutVertical
        {
            element
            {
                name "Label"

                alignH "centre"
                border  { 5 5 }
            }
            element
            {
                name "Image"

                alignH "right"
                border  { 5 5 }
            }
        }
    }

Element layout properties

Note:
Element attributes 'pos' and 'size' should not be specified for an element which is within a layout as these properties will be overridden by the layout.
Type | Name | Description
bool | sizeToContent | The element should size to its content. The actual behaviour is dependent on the element type. For example, labels will size to the text they contain, images will size to texture they contain.
CIwVec2 | sizeMin | Minimum pixel size for the element.
CIwVec2 | sizeMax | Maximum pixel size for the element.
CIwVec2 | sizeHint | The preferred pixel size for the element in situations where it has an unlimited amount of space to layout within. For example, the vertical size of an element placed within a vertical layout.
CIwVec2> | aspectRatio | Allows a fixed aspect ratio to be set for the element. The relative size of the x&y components determine the aspect ratio. The absolute values of the components are irrelevant.

Layout item properties

Type | Name | Description
bool | sizeToSpace | The layout should size to the space available to it.
IwUIAlignmentH | alignH | Horizontal alignment of element within allocated space.
IwUIAlignmentV | alignV | Vertical alignment of element within allocated space.
CIwSVec2 | border | Border size around element.

Layout spacers

Layout spacers, type CIwUILayoutSpacer, can be placed into a layout in the same manner as elements to provide spacing. Layout spacers are layout items, not elements, so can only be added to a layout hierarchy. They avoid the need to add dummy elements purely for adding padding. Spacers respect the same 'sizeMin', 'sizeMax', 'sizeHint' and 'aspectRatio' as an element.

Layout attachment and population

When a layout is specified in a .ui file, it specifies the position of elements by name. These names are expected to be of child elements of the element the layout is attached to. The actual process of connecting child elements by name to the layout occurs when the parent element is activated. This process is called population.

When an element with a layout is activated, CIwUIElement::Activate() calls CIwUILayout::Attach() to allow the layout, and any child layouts to look up relevant properites. Then CIwUILayout::Populate which attempts to connect child elements by name into the layout. This requires the names expected by the layout to match those of the child elements.

The element hierarchy

The layout of elements is, such as placing buttons in a column, is usually irrelevant to event handling and other user interface programming. Hence, layouts are kept separate from the element hierarchy.

This also has the advantage that different layouts can be attached to an element to arrange its children in different configurations dependent on screen size. For example, a number of buttons could be arrange in a column for a landscape display and a row for a portrait display. This switching is controlled in code for maximum flexibility.

Layout and element hierarchies interact as follows. An element is placed into a layout hierarchy by being associated with a CIwUIElementItem. The CIwUIElementItem is a place-holder in the layout hierarchy and interacts with the element via calls to CIwUIElement::Measure() and CIwUIElement::Arrange(). In turn, an element primarily interacts with the layout for its children within the same functions.

When a layout item is placed into a CIwUILayout, or a derived class, it is wrapped in a CIwUILayoutItemContainer. Each layout type uses a different CIwUILayoutItemContainer derived class to contain the data about the item's position in the layout. For example, CIwUILayoutGrid places an item's row and column information in a private local class derived from CIwUILayoutItemContainer.

Custom element layout interaction

Derived element types can interact with layout to provide information about the size of their content. For example, CIwUILabel provides information about the space required for the text it contains. Custom elements can override CIwUIElement::MeasureLayout() to provide size information. By convention, CIwUIElement::GetSizeToContent() indicates if an element should fit to the size of its content rather than filling the space available to it.


Airplay API Reference: The Animation System

Airplay API Reference > IwUI API Documentation > IwUI API Overview > The Animation System >

The Animation System

The animation system allows element properties to be animated over time. Animations resources, CIwUIAnimation, are defined as a collection of key frame objects, CIwUIAnimKeyFrame. Key frames specify the value of properties at a particular time. Between key frames the values of properties are interpolated.

An animation is played on an element using the CIwUIAnimManager singleton. Each playing animation is kept track of by the animation manager using instances of CIwUIAnimator.

Interpolated values of properties are provided to an element using CIwUIAnimData. For a derived element to animated a custom property, it must call CIwUIAnimData::AnimateProperty. This both updates the value of the custom property on the elements property set, and provides an opportunity to update any cache of the property. For each type being interpolated an implementation of the template function CIwUIAnimDataType::Interpolate must be provided.


Airplay API Reference: Delegates

Airplay API Reference > IwUI API Documentation > IwUI API Overview > Delegates >

Delegates

The delegates system in IwUI is used to connect signals to slots. Signals are similar to events, such as a button click. Slots are similar to event handlers, or callback functions.

Signals and slots are a type-safe object-orientated alternative to traditional callback functions. A signal is called like a function, which in turn calls any attached slots. A slot calls a function on an object.


Airplay API Reference: IwUI API Reference

Airplay API Reference > IwUI API Documentation > IwUI API Reference >

IwUI API Reference

Modules

Utility Classes
Animation
Drawables
Elements
Events
Focus Handlers
Rendering
Layout
Properties and Styles
Text Input
View

Functions

void | IwUIAddDrawableFactory (const char *pDrawableName, IwUIDrawableFactoryFn facFunc)
IIwUIDrawable * | IwUICreateDrawable (uint32 classHash, const CIwVec2 &size, const CIwPropertySet &propertySet)
IIwUIDrawable * | IwUICreateDrawable (const CIwVec2 &size, const CIwPropertySet &propertySet, const char *defaultType=NULL)
IIwUIDrawable * | IwUICreateDrawable (const CIwUIStyle &style, const CIwVec2 &size, const char *defaultType=NULL)
IwUILocaliseCallbackFunc | IwUIGetLocaliseCallback ()
void | IwUIInit ()
const char * | IwUILocaliseCallback (const CIwPropertySet &pset)
void | IwUISetLocaliseCallback (IwUILocaliseCallbackFunc func)
void | IwUITerminate ()

Detailed Description

IwUI is a new flexible user interface framework for Airplay. Note: This module is currently a beta component of the Airplay SDK. IwUI interfaces are likely to change before the release version.

Typedef Documentation

IwUIDrawableFactoryFn

Function pointer type of localisation callback.

Function Documentation

void IwUIAddDrawableFactory | ( | const char * | pDrawableName,
 |  | IwUIDrawableFactoryFn | facFunc
 | ) |  |

Register a class factory for a custom drawable.

Note:
Use IWUI_DRAWABLE_REGISTER macro instead of calling directly.

IIwUIDrawable* IwUICreateDrawable | ( | uint32 | classHash,
 |  | const CIwVec2 & | size,
 |  | const CIwPropertySet & | propertySet
 | ) |  |

Create drawable of given type using class factory.

Parameters:
classHash | Hash of name used to register drawable factory.
size | Initial size for the drawable object.
propertySet | Property set new drawable should read its construction parameters from.

IIwUIDrawable* IwUICreateDrawable | ( | const CIwVec2 & | size,
 |  | const CIwPropertySet & | propertySet,
 |  | const char * | defaultType = NULL
 | ) |  |

Create a drawable object from the specified property set.

Parameters:
pPropertySet | PropertySet resource with a "style" member denoting the type of drawable, plus additional parameters.
size | Initial size for the drawable object.
defaultType | Optional default type to use for drawable.
Returns:
Pointer to a new drawable object, which the caller owns.

IIwUIDrawable* IwUICreateDrawable | ( | const CIwUIStyle & | style,
 |  | const CIwVec2 & | size,
 |  | const char * | defaultType = NULL
 | ) |  |

Create a drawable object with the specified style.

Parameters:
style | Style used to find a property set to pass to the drawable's constructor.
size | Size of the drawable object.
defaultType | Optional default type to use for drawable.
Returns:
Pointer to a new drawable object, which the caller owns.

void IwUIFreeFontBuffers ( )

Release memory reserved for font rendering buffers.

IwUILocaliseCallbackFunc IwUIGetLocaliseCallback ( )

Get the current localisation callback, if any.

Returns:
Current function pointer.

void IwUIInit ( )

IwUI module initialisation function. Registers class factories and calls sub-module init functions.

Note:
This function should be called on application startup.

const char* IwUILocaliseCallback ( const CIwPropertySet & pset )

Call the localisation callback.

Parameters:
PropertySet for element/drawable to be localised.
Returns:
Return value from callback, if present, otherwise NULL.

void IwUIReserveFontBuffers | ( | int32 | numChars,
 |  | int32 | numLines
 | ) |  |

Reserve memory for font rendering buffers.

void IwUISetLocaliseCallback ( IwUILocaliseCallbackFunc func )

Set a callback to override localisation.

Parameters:
func Callback function pointer.

void IwUITerminate ( )

IwUI module terminate function. Destroys class factories and calls sub-module terminate functions.

Note:
This function should be called on application shutdown.


Airplay API Reference: Utility Classes

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Utility Classes >

Utility Classes
[IwUI API Reference]

Modules

Text Decomposer

Data Structures

class | CIwTextDecomposer::Context
class | CIwUIColour
Derived from CIwColour. Adds functionality such as parsing. More...
class | CIwUIColour
Derived from CIwColour. Adds functionality such as parsing. More...
class | CIwUIHoldingPtr< Type >
Smart pointer which manages destruction of its owned object, useful for pointer member management. More...
class | CIwUIHoldingPtr< Type >
Smart pointer which manages destruction of its owned object, useful for pointer member management. More...
class | CIwUIRect
Derived from CIwRect. Adds functionality such as intersection. More...
class | CIwUIRect
Derived from CIwRect. Adds functionality such as intersection. More...

Enumerations

enum | IwUIAlignmentH
enum | IwUIAlignmentV

Functions

const IIwDecomposable * | CIwTextDecomposer::GetObject (int32 level=0)
IwGxFontAlignVer | IwUIAlignmentGxFont (IwUIAlignmentV valign)
IwGxFontAlignHor | IwUIAlignmentGxFont (IwUIAlignmentH halign)
CIwUIRect | IwUIGetTransformedBounds (const CIwUIMat &mat, const CIwUIRect &rect)
void | CIwTextDecomposer::OpenScope (bool inlineScope)
void | CIwTextDecomposer::WriteAttibuteNameHash (const char *pName, uint32 hash)
void | CIwTextDecomposer::WriteAttribute (const char *pAttrName, const char *pAttrVal)
void | CIwTextDecomposer::WriteAttributeHash (uint32 hash)
void | CIwTextDecomposer::WriteAttributeName (const char *pAttrName)
template<class Type>
void | CIwTextDecomposer::WriteAttributeNameVal (const char *pName, Type val)
template<class Type>
void | CIwTextDecomposer::WriteAttributeNameValArray (const char *pName, const Type *val, int numVals)
template<class Type>
void | CIwTextDecomposer::WriteAttributeVal (Type val)
template<class Type>
void | CIwTextDecomposer::WriteAttributeValArray (const Type *val, int numVals)

Typedef Documentation

CIwUIMat

Affine 2D transformation matrix, used for element sub-frame transforms.

Enumeration Type Documentation

enum IwUIAlignmentH

Horizontal alignment options.

Enumerator:
IW_UI_ALIGN_LEFT | Left alignment.
IW_UI_ALIGN_CENTRE | Centre alignment.
IW_UI_ALIGN_RIGHT | Right alignment.

enum IwUIAlignmentV

Vertical alignment options.

Enumerator:
IW_UI_ALIGN_TOP | Top alignment.
IW_UI_ALIGN_MIDDLE | Middle alignment.
IW_UI_ALIGN_BOTTOM | Bottom alignment.

Function Documentation

void CIwTextDecomposer::CloseAttribute ( ) [inherited]

Close a statement previously opened with OpenAttribute.

void CIwTextDecomposer::CloseScope ( bool inlineScope ) [inherited]

Close a previously opened scope. Value of should match that passed to .

void CIwTextDecomposer::DecomposeChild ( const IIwDecomposable * pDecomposable ) [inherited]

During decomposition, use to write out child decomposable object.

void CIwTextDecomposer::DecomposeToFile | ( | const char * | pPathname,
 |  | const IIwDecomposable * | pDecomposable |
 | ) |  |  | [inherited]

Writes decomposable object, and its children, in ITX format to a given file.

const IIwDecomposable* CIwTextDecomposer::GetObject ( int32 level = 0 ) [inherited]

Get a IIwDecomposable object from the decomposer's stack.

Parameters:
level Stack level to get object from. Must be <= 0. 0 refers to the top of the stack.
Returns:
Pointer object, or NULL if there is no object at that level.

IwGxFontAlignVer IwUIAlignmentGxFont ( IwUIAlignmentV valign )

Utility to convert from UI vertical alignment to GX alignment.

Parameters:
valign Vertical alignment to convert.

IwGxFontAlignHor IwUIAlignmentGxFont ( IwUIAlignmentH halign )

Utility to convert from UI horizontal alignment to GX alignment.

Parameters:
halign Horizontal alignment to convert.

CIwUIRect IwUIGetTransformedBounds | ( | const CIwUIMat & | mat,
 |  | const CIwUIRect & | rect
 | ) |  |

Get the minimum CIwUIRect which contains the given rect after transformation.

Parameters:
mat | Matrix transform to apply to rectangle.
rect | Rectangle to bound after transformation.
Returns:
The smallest axis aligned rectangle containing the given rectangle after transformation by the given matrix.

void CIwTextDecomposer::OpenAttribute ( ) [inherited]

Open a new statement to write attributes within.

void CIwTextDecomposer::OpenScope ( bool inlineScope ) [inherited]

Open a new scope ("{") either inline or on a new line.

Note:
A non-inline scope cannot be nested inside an inline scope.

void CIwTextDecomposer::WriteAttibuteNameHash | ( | const char * | pName,
 |  | uint32 | hash |
 | ) |  |  | [inherited]

Write simple attribute name-hash pair statement.

Note:
The hash should have previously been registered with IIwDecomposable::AddHashString()

void CIwTextDecomposer::WriteAttribute | ( | const char * | pAttrName,
 |  | const char * | pAttrVal |
 | ) |  |  | [inherited]

Write simple attribute name-value pair statement.

Note:
It is not necessary to call OpenAttribute before this function.

void CIwTextDecomposer::WriteAttributeHash ( uint32 hash ) [inherited]

Write the string for a given hash.

Note:
The hash should have previously been registered with IIwDecomposable::AddHashString()

void CIwTextDecomposer::WriteAttributeName ( const char * pAttrName ) [inherited]

Write the name of an attribute.

Note:
must be called before this function.

template<class Type>
void CIwTextDecomposer::WriteAttributeNameVal | ( | const char * | pName,
 |  | Type | val |
 | ) |  |  | [inline, inherited]

Write simple attribute name-value pair statement.

Note:
It is not necessary to call OpenAttribute before this function.

template<class Type>
void CIwTextDecomposer::WriteAttributeNameValArray | ( | const char * | pName,
 |  | const Type * | val,
 |  | int | numVals |
 | ) |  |  | [inline, inherited]

Write an attribute name and an array of attribute values within an inline scope.

Note:
It is not necessary to call OpenAttribute before this function.

template<class Type>
void CIwTextDecomposer::WriteAttributeVal ( Type val ) [inline, inherited]

Write the value of an attribute.

Note:
should be called before this function.

template<class Type>
void CIwTextDecomposer::WriteAttributeValArray | ( | const Type * | val,
 |  | int | numVals |
 | ) |  |  | [inline, inherited]

Write an array of attribute values within an inline scope.

Note:
should be called before this function.

void CIwTextDecomposer::WriteClassName ( const char * pClassName ) [inherited]

Write class name statement.

void CIwTextDecomposer::WriteObjectName ( const char * pObjectName ) [inherited]

Write object name statement.


Airplay API Reference: Text Decomposer

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Utility Classes > Text Decomposer >

Text Decomposer
[Utility Classes]

Data Structures

class | CIwTextDecomposer
Class that can be used to write out an object hierarchy, and its properties, to text format. More...
class | CIwTextDecomposer
Class that can be used to write out an object hierarchy, and its properties, to text format. More...
interface | IIwDecomposable
Interface to allow an object to participate in text decomposition. The interface allows for writing out only the need parts of an objects definition. More...
interface | IIwDecomposable
Interface to allow an object to participate in text decomposition. The interface allows for writing out only the need parts of an objects definition. More...

Detailed Description

Text Decomposer functionality.

Functionality for writing out an object hierarchy, and its properties, to text format.


Airplay API Reference: Animation

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Animation >

Animation
[IwUI API Reference]

Data Structures

class | CIwUIAnimation
Animation resource. Contains a list of keyframes ordered by time. More...
class | CIwUIAnimation
Animation resource. Contains a list of keyframes ordered by time. More...
class | CIwUIAnimator
Represents an animation playing on an element. More...
class | CIwUIAnimator
Represents an animation playing on an element. More...
class | CIwUIAnimData
Provides animation data to animated elements. More...
class | CIwUIAnimData
Provides animation data to animated elements. More...
class | CIwUIAnimDataLocator
Interface for obtaining animation data by property name. Iterates over keyframe data to find corresponding properties. More...
class | CIwUIAnimDataLocator
Interface for obtaining animation data by property name. Iterates over keyframe data to find corresponding properties. More...
class | CIwUIAnimDataType< Type >
Templated class to interpolate a type. More...
class | CIwUIAnimDataType< Type >
Templated class to interpolate a type. More...
class | CIwUIAnimKeyFrame
Animation key frame. Animation resources are made up of key frames. Each keyframe specifies the value of properties at a particular time through an animation. More...
class | CIwUIAnimKeyFrame
Animation key frame. Animation resources are made up of key frames. Each keyframe specifies the value of properties at a particular time through an animation. More...
class | CIwUIAnimManager
Animation manager singleton. Provides an interface for playing and controlling an animation on an element. Updated by CIwUIView. More...
class | CIwUIAnimManager
Animation manager singleton. Provides an interface for playing and controlling an animation on an element. Updated by CIwUIView. More...
class | IIwUIAnimatorObserver
Interface to allow an observation of the state changes of a playing animation. More...
class | IIwUIAnimatorObserver
Interface to allow an observation of the state changes of a playing animation. More...

Detailed Description

Animation functionality for the IwUI module.

The animation system allows element properties to be animated over time by interpolating movements between sets of key frames.

Define Documentation

#define IW_UI_RESTYPE_ANIMATION "CIwUIAnimation"

Resource type string used to store and retrieve CIwUIAnimation objects in the resource manager.


Airplay API Reference: Drawables

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Drawables >

Drawables
[IwUI API Reference]

Data Structures

class | CIwUIDrawableBorder
Draws a border from a single image + corner width (by drawing 9 separate images, the corners being drawn 1:1 (using the corner size to calculate UVs), the other 5 being drawn stretched to fit the specified size). More...
class | CIwUIDrawableBorder
Draws a border from a single image + corner width (by drawing 9 separate images, the corners being drawn 1:1 (using the corner size to calculate UVs), the other 5 being drawn stretched to fit the specified size). More...
class | CIwUIDrawableImage
Drawable wrapper for a simple image. More...
class | CIwUIDrawableImage
Drawable wrapper for a simple image. More...
class | CIwUIDrawableText
Drawable wrapper for the state required to draw some text via Gx. More...
class | CIwUIDrawableText
Drawable wrapper for the state required to draw some text via Gx. More...
class | IIwUIDrawable
Interface for drawable objects such as text, images, borders. More...
class | IIwUIDrawable
Interface for drawable objects such as text, images, borders. More...

Defines

#define | IWUI_DRAWABLE_FACTORY(Drawable)
#define | IWUI_DRAWABLE_REGISTER(Type, Drawable)

Detailed Description

Drawable object classes for the IwUI module.

Define Documentation

#define IWUI_DRAWABLE_FACTORY ( Drawable )

Value:

IIwUIDrawable* _##Drawable##Factory(const CIwVec2& size,                    \
    const CIwPropertySet& propertySet)                                      \
{                                                                           \
    return new Drawable(size, propertySet);                                 \
}
Helper define to define a drawable class factory.

Parameters:
Drawable Drawable class name

#define IWUI_DRAWABLE_REGISTER | ( | Type,
 |  | Drawable | )

Value:

extern IIwUIDrawable* _##Drawable##Factory(const CIwVec2& size,         \
    const CIwPropertySet& propertySet);                                     \
IwUIAddDrawableFactory(#Type, _##Drawable##Factory);
Helper register a drawable class factory.

Parameters:
Type | Name used for drawable when specifying drawableType property.
Drawable | Drawable class name used with IWUI_DRAWABLE_FACTORY macro.


Airplay API Reference: Elements

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Elements >

Elements
[IwUI API Reference]

Data Structures

class | CIwUIAlertDialog
Alert dialog box, with one or more buttons. More...
class | CIwUIAlertDialog
Alert dialog box, with one or more buttons. More...
class | CIwUIButton
Button widget. If the user touches the button, or presses ok whilst the button has focus, it will generate a ButtonPress event with itself as the source. More...
class | CIwUIButton
Button widget. If the user touches the button, or presses ok whilst the button has focus, it will generate a ButtonPress event with itself as the source. More...
class | CIwUICheckbox
Check box element. Has an on / off graphic [+ label] [+ background]. More...
class | CIwUICheckbox
Check box element. Has an on / off graphic [+ label] [+ background]. More...
class | CIwUIElement
Base class for all ui widgets. Also acts a frame within which other elements can be contained. More...
class | CIwUIElement
Base class for all ui widgets. Also acts a frame within which other elements can be contained. More...
class | CIwUIElementPtr
Smart(ish) point which becomes NULL when the element it points to is destroyed. More...
class | CIwUIElementPtr
Smart(ish) point which becomes NULL when the element it points to is destroyed. More...
class | CIwUIImage
Element used to display an image. Has no interaction. More...
class | CIwUIImage
Element used to display an image. Has no interaction. More...
class | CIwUILabel
Read-only text widget - single or multi-line. Has no interaction. More...
class | CIwUILabel
Read-only text widget - single or multi-line. Has no interaction. More...
class | CIwUIProgressBar
0-100% style progress bar. More...
class | CIwUIProgressBar
0-100% style progress bar. More...
class | CIwUIRadioButton
Button with on and off states. To be placed within a tab bar. More...
class | CIwUIRadioButton
Button with on and off states. To be placed within a tab bar. More...
class | CIwUIScrollableView
Element which allows scrolling across content whose total extents exceed the size of the scrollable view widget, either via explicit interaction with the scrollbars(??), else via gestures in the main content area. More...
class | CIwUIScrollableView
Element which allows scrolling across content whose total extents exceed the size of the scrollable view widget, either via explicit interaction with the scrollbars(??), else via gestures in the main content area. More...
class | CIwUISlider
Slider widget. If the user drags the button, or presses left/right whilst the slider has focus, it will generate a Slider event with itself as the source. More...
class | CIwUISlider
Slider widget. If the user drags the button, or presses left/right whilst the slider has focus, it will generate a Slider event with itself as the source. More...
class | CIwUITabBar
Container for a set of radio buttons. One button is always down, the others are always up. More...
class | CIwUITabBar
Container for a set of radio buttons. One button is always down, the others are always up. More...
class | CIwUITable
This is a specialisation of scrollable view which contains a number of row items, and which only allows vertical scrolling. More...
class | CIwUITable
This is a specialisation of scrollable view which contains a number of row items, and which only allows vertical scrolling. More...

Functions

virtual void | CIwUIImage::Activate (bool val)
virtual void | CIwUIImage::Clone (CIwUIElement *pTarget) const
virtual CIwUIRect | CIwUIImage::GetElementBounds () const
virtual CIwVec2 | CIwUIImage::MeasureElement (const CIwVec2 &availableSize) const
virtual void | CIwUIImage::OnPropertyChanged (const char *pName)
virtual void | CIwUIImage::RenderElement (CIwUIGraphics &graphics)

Detailed Description

Elements functionality for the IwUI module.

In IwUI, user interfaces are built up from a hierarchy of elements. There are a number of element types derived from the CIwUIElement base class, each of which adds specific logical and graphical functionality peculiar to a particular control type - such as a button, a label or a progress bar.

Define Documentation

#define IW_UI_RESTYPE_ELEMENT "CIwUIElement"

Resource type string used to store and retrieve CIwUIElement objects in the resource manager.

Function Documentation

virtual void CIwUIImage::Activate ( bool val ) [protected, virtual, inherited]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUIImage::Animate ( const CIwUIAnimData & animData ) [protected, virtual, inherited]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

virtual void CIwUIImage::Clone ( CIwUIElement * pTarget ) const [protected, virtual, inherited]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

virtual CIwUIRect CIwUIImage::GetElementBounds ( ) const [protected, virtual, inherited]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIElement.

virtual CIwVec2 CIwUIImage::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual, inherited]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUIImage::OnPropertyChanged ( const char * pName ) [protected, virtual, inherited]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

virtual void CIwUIImage::OnSizeChanged ( ) [protected, virtual, inherited]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIElement.

virtual void CIwUIImage::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual, inherited]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIElement.


Airplay API Reference: Events

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Events >

Events
[IwUI API Reference]

Data Structures

class | CIwUIController
UI event-handling singleton. More...
class | CIwUIController
UI event-handling singleton. More...
class | CIwUIElementEventHandler
Event handler which can be attached to an element in data. More...
class | CIwUIElementEventHandler
Event handler which can be attached to an element in data. More...
class | CIwUIEventAlertDialogButton
An alert dialog button was pressed. More...
class | CIwUIEventAlertDialogButton
An alert dialog button was pressed. More...
class | CIwUIEventButton
CIwUIButton pressed event. More...
class | CIwUIEventButton
CIwUIButton pressed event. More...
class | CIwUIEventCheckbox
Checkbox on / off state toggle event. More...
class | CIwUIEventCheckbox
Checkbox on / off state toggle event. More...
class | CIwUIEventClick
s3ePointer button press event. More...
class | CIwUIEventClick
s3ePointer button press event. More...
class | CIwUIEventFocus
Keyboard focus change event. More...
class | CIwUIEventFocus
Keyboard focus change event. More...
class | CIwUIEventKey
s3eKey press / release event. More...
class | CIwUIEventKey
s3eKey press / release event. More...
class | CIwUIEventLayout
Layout of the specified element has just been updated. More...
class | CIwUIEventLayout
Layout of the specified element has just been updated. More...
class | CIwUIEventPointerEnter
Event fired when the pointer enters an element (as determined by the element's intersect function). More...
class | CIwUIEventPointerEnter
Event fired when the pointer enters an element (as determined by the element's intersect function). More...
class | CIwUIEventPointerLeave
Event fired when the pointer leaves an element (as determined by the element's intersect function). More...
class | CIwUIEventPointerLeave
Event fired when the pointer leaves an element (as determined by the element's intersect function). More...
class | CIwUIEventPointerMove
Pointer move event. More...
class | CIwUIEventPointerMove
Pointer move event. More...
class | CIwUIEventRadioButton
CIwUIRadioButton selected event. More...
class | CIwUIEventRadioButton
CIwUIRadioButton selected event. More...
class | CIwUIEventSlider
Value of slider changed. More...
class | CIwUIEventSlider
Value of slider changed. More...
class | CIwUIEventSoftKey
SoftKey pressed/released event. More...
class | CIwUIEventSoftKey
SoftKey pressed/released event. More...
class | CIwUIEventTabBarButton
A tab bar button was pressed. More...
class | CIwUIEventTabBarButton
A tab bar button was pressed. More...
class | CIwUIEventTextInput
Text input event. More...
class | CIwUIEventTextInput
Text input event. More...
class | IIwUIEventHandler
Interface to handle or filter events. More...
class | IIwUIEventHandler
Interface to handle or filter events. More...

Detailed Description

Events functionality for the IwUI module.

Define Documentation

#define IW_UI_RESTYPE_ELEMENT_EVENT_HANDLER "CIwUIElementEventHandler"

Resource type string used to store and retrieve CIwUIElementEventHandler objects in the resource manager.

Enumeration Type Documentation

enum IWUI_EVENT

Enumeration of IwUI event IDs. The type of an IwUI event can be determined by calling CIwEvent::GetID and comparing to values of this enumeration.


Airplay API Reference: Focus Handlers

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Focus Handlers >

Focus Handlers
[IwUI API Reference]

Data Structures

class | CIwUIFocusHandler
Base class for focus handlers. A focus handle can be attached to an element to respond to input and control which of the elements children has input focus. More...
class | CIwUIFocusHandler
Base class for focus handlers. A focus handle can be attached to an element to respond to input and control which of the elements children has input focus. More...
class | CIwUIFocusHandler2D
Concrete implementation of a focus handler which 'intelligently' moves focus based on 2D position + pressed direction. More...
class | CIwUIFocusHandler2D
Concrete implementation of a focus handler which 'intelligently' moves focus based on 2D position + pressed direction. More...
class | CIwUIFocusHandlerTab
Concrete implementation of a focus handler which simply moves focus based on element order. More...
class | CIwUIFocusHandlerTab
Concrete implementation of a focus handler which simply moves focus based on element order. More...
class | IIwFocusResolver
Helper interface to determine an element which to give focus to. More...
class | IIwFocusResolver
Helper interface to determine an element which to give focus to. More...

Enumerations

enum | IwUIFocusMovement
enum | IwUIFocusWrapMode

Detailed Description

Focus Handlers functionality for the IwUI module.

Define Documentation

#define IW_UI_RESTYPE_FOCUS_HANDLER "CIwUIFocusHandler"

Resource type string used to store and retrieve CIwUIFocusHandler objects in the resource manager.

Enumeration Type Documentation

enum IwUIFocusMovement

Focus movement directions

Enumerator:
IW_UI_FOCUS_MOVE_LEFT | Move focus left.
IW_UI_FOCUS_MOVE_RIGHT | Move focus right.
IW_UI_FOCUS_MOVE_UP | Move focus up.
IW_UI_FOCUS_MOVE_DOWN | Move focus down.
IW_UI_FOCUS_MOVE_NONE | No movement.

enum IwUIFocusWrapMode

Focus wrapping directions

Enumerator:
IW_UI_FOCUS_WRAP_NONE | Focus movement should move onto next element.
IW_UI_FOCUS_WRAP_WRAP | Focus movement should be wrapped around.
IW_UI_FOCUS_WRAP_STOP | Focus movement should stop rather than wrapping.
IW_UI_FOCUS_WRAP_JUMP | Focus movement should jump to next element.


Airplay API Reference: Rendering

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Rendering >

Rendering
[IwUI API Reference]

Namespaces

namespace | IwUIAtlas
namespace | IwUIAtlas

Data Structures

class | CIwUIGraphics
Provides rendering functionality. More...
class | CIwUIGraphics
Provides rendering functionality. More...

Detailed Description

Rendering functionality for the IwUI module.

The rendering system provides image and text primitive drawing functions. The primitives are transformed, clipped and coloured depending on the current CIwUIGraphics context.


Airplay API Reference: Layout

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Layout >

Layout
[IwUI API Reference]

Data Structures

class | CIwUIElementItem
Used as a wrapper around CIwUIElements, which are then wrapped by a CIwUILayoutItem, before being added into a CIwUILayout. More...
class | CIwUIElementItem
Used as a wrapper around CIwUIElements, which are then wrapped by a CIwUILayoutItem, before being added into a CIwUILayout. More...
class | CIwUILayout
Base class for all layout types. More...
class | CIwUILayout
Base class for all layout types. More...
class | CIwUILayoutForm
Form type layout. Form has a notional size. Items are positioned and size relative to the forms size. Item's can be placed relative to other items used as guides. More...
class | CIwUILayoutForm
Form type layout. Form has a notional size. Items are positioned and size relative to the forms size. Item's can be placed relative to other items used as guides. More...
class | CIwUILayoutGrid
Grid type layout. Organises contained items on a grid. More...
class | CIwUILayoutGrid
Grid type layout. Organises contained items on a grid. More...
class | CIwUILayoutHorizontal
Simple layout which lays out elements in a single row. More...
class | CIwUILayoutHorizontal
Simple layout which lays out elements in a single row. More...
class | CIwUILayoutItem
UI base class to support layout. Interface supports layout, cloning & parentage. More...
class | CIwUILayoutItem
UI base class to support layout. Interface supports layout, cloning & parentage. More...
class | CIwUILayoutItemContainer
Used as a container around CIwUILayoutItem added to a CIwUILayout. Contains additional data such as alignment for the item. Also provides simple caching system. More...
class | CIwUILayoutItemContainer
Used as a container around CIwUILayoutItem added to a CIwUILayout. Contains additional data such as alignment for the item. Also provides simple caching system. More...
class | CIwUILayoutSpacer
Layout item to add space into a layout. More...
class | CIwUILayoutSpacer
Layout item to add space into a layout. More...
class | CIwUILayoutVertical
Simple layout which lays out elements in a single column. More...
class | CIwUILayoutVertical
Simple layout which lays out elements in a single column. More...
class | CIwUIPositionPolicy
Encapsulates element positional preference. More...
class | CIwUIPositionPolicy
Encapsulates element positional preference. More...
class | CIwUISizePolicy
Encapsulates element size restraints. Hint is only applied when result would otherwise be unbounded. More...
class | CIwUISizePolicy
Encapsulates element size restraints. Hint is only applied when result would otherwise be unbounded. More...

Detailed Description

Layout funtionality for the IwUI module.

Layouts are used in IwUI to arrange child elements to fit within the available space. There are a number of different layout classes to provide a range of options on how to arrange elements. Elements interact with the layout system to provide information about how much space they require for their content.

Define Documentation

#define IW_UI_RESTYPE_LAYOUT "CIwUILayout"

Resource type string used to store and retrieve CIwUILayout objects in the resource manager.


Airplay API Reference: Properties and Styles

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Properties and Styles >

Properties and Styles
[IwUI API Reference]

Modules

Property Set

Data Structures

class | CIwUIPropertySet
Property set which uses a style to resolve its parent. This extends CIwPropertySet to support style sheets. More...
class | CIwUIPropertySet
Property set which uses a style to resolve its parent. This extends CIwPropertySet to support style sheets. More...
class | CIwUIStyle
A named style, wrapped up in an object for added semantics. More...
class | CIwUIStyle
A named style, wrapped up in an object for added semantics. More...
class | CIwUIStyleManager
Singleton which stores the currently-set stylesheet, and through which style property sets should be queried. If no stylesheet is set, styles are mapped to property sets by direct lookup of same-named property sets through the resource system. More...
class | CIwUIStyleManager
Singleton which stores the currently-set stylesheet, and through which style property sets should be queried. If no stylesheet is set, styles are mapped to property sets by direct lookup of same-named property sets through the resource system. More...
class | CIwUIStylesheet
Maps styles to property sets, facilitating the switching of property sets globally. More...
class | CIwUIStylesheet
Maps styles to property sets, facilitating the switching of property sets globally. More...

Detailed Description

Styles functionality for the IwUI module.

IwUI's elements (and layouts) store most of their configuration data as property sets rather than as member data. A property set is a mapping of strings to data. This module provides functionality for accessing and modifying these properties.

Define Documentation

#define IW_UI_RESTYPE_PROPERTY_SET "CIwUIPropertySet"

Resource type string used to store and retrieve CIwUIPropertySet objects in the resource manager.

#define IW_UI_RESTYPE_STYLESHEET "CIwUIStylesheet"

Resource type string used to store and retrieve CIwUIStylesheet objects in the resource manager.


Airplay API Reference: Property Set

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Properties and Styles > Property Set >

Property Set
[Properties and Styles]

Data Structures

class | CIwProperty< Type >
Templated class to used by CIwPropertySet to store data of different types. The CIwProperty owns the data it contains and provides an interface for accessing it, as well as parsing, serialise and resolving the data. More...
class | CIwProperty< Type >
Templated class to used by CIwPropertySet to store data of different types. The CIwProperty owns the data it contains and provides an interface for accessing it, as well as parsing, serialise and resolving the data. More...
class | CIwPropertyBase
Base class for CIwProperty. Used by CIwPropertySet to store a collection of properties. More...
class | CIwPropertyBase
Base class for CIwProperty. Used by CIwPropertySet to store a collection of properties. More...
class | CIwPropertyDataType< Type >
Templated class containing static methods used by CIwProperty. Specialisations of the members of this class must be provided for each data type used with the property set system. More...
class | CIwPropertyDataType< Type >
Templated class containing static methods used by CIwProperty. Specialisations of the members of this class must be provided for each data type used with the property set system. More...
class | CIwPropertyDefine
Used to by CIwPropertySet to map a property name to a property data type. For example a property define maps the property name "colour" to the data type "CIwColour". A property of the correct type can be created using CreateProperty which uses the property factory. More...
class | CIwPropertyDefine
Used to by CIwPropertySet to map a property name to a property data type. For example a property define maps the property name "colour" to the data type "CIwColour". A property of the correct type can be created using CreateProperty which uses the property factory. More...
class | CIwPropertyList< Type >
Templated list property (facilitating variable-length properties). More...
class | CIwPropertyList< Type >
Templated list property (facilitating variable-length properties). More...
class | CIwPropertySet
A property set is used to store and retrieve a collection of properties derived from CIwPropertyBase. The property set can also have a parent property set. More...
class | CIwPropertySet
A property set is used to store and retrieve a collection of properties derived from CIwPropertyBase. The property set can also have a parent property set. More...
class | CIwPropertySetBinding
Used to allow binding properties to an external source. More...
class | CIwPropertySetBinding
Used to allow binding properties to an external source. More...
class | CIwPropertyString
Variable-length string class, shared (ref-counted) representation. More...
class | CIwPropertyTypeMap< Key >
Allows mapping between a type used to access property data and the the type used to store a particular property. This can be useful when getting or setting properties on a property set via CIwPropertySet::Get and CIwPropertySet::Set respectively. More...
class | CIwPropertyTypeMap< Key >
Allows mapping between a type used to access property data and the the type used to store a particular property. This can be useful when getting or setting properties on a property set via CIwPropertySet::Get and CIwPropertySet::Set respectively. More...
class | IIwPropertySetObserver
Interface to allow an observer to be informed of property changes. It is used with property set bindings (implementations of CIwPropertySetBinding) to allow a consumer of a property set to be informed when external changes cause property values to change. More...
class | IIwPropertySetObserver
Interface to allow an observer to be informed of property changes. It is used with property set bindings (implementations of CIwPropertySetBinding) to allow a consumer of a property set to be informed when external changes cause property values to change. More...

Defines

#define | IW_PROPERTY_DECLARE_RESOURCE_TYPE(ResType, ResName)

Functions

template<class Type>
Type * | IwPropertyAddPropertyFactory ()
void | IwPropertyAddPropertyFactory (const char *pPropertyName, IwPropertyFactoryFn facFunc)
CIwPropertyBase * | IwPropertyCreateProperty (uint32 hash, uint32 defineId, const char *pDebugName)
CIwPropertyBase * | IwPropertyCreatePropertyFromDefine (const char *pPropertyDefine)
bool | IwPropertyFactoryExists (uint32 hash)
bool | IwPropertyIsProperty (const char *pName)
bool | IwPropertyIsProperty (uint32 hash)
void | IwPropertySetInit ()
void | IwPropertySetTerminate ()

Detailed Description

Low level properties functionality for the IwUIPropertySet.

Used to store and retrieve a collection of properties.

Define Documentation

#define IW_PROPERTY_DECLARE_BASIC_TYPE | ( | Type,
 |  | Name | )

Value:

template<>                                                                  \
const char* CIwPropertyDataType<Type >::s_DataType = Name;                  \
                                                                            \
template<>                                                                  \
void CIwPropertyDataType<Type >::Resolve(Type &)                            \
{                                                                           \
}                                                                           \
                                                                            \
template<>                                                                  \
bool CIwPropertyDataType<Type >::IsOfType(uint32 typeHash)                  \
{                                                                           \
    return typeHash == s_DataTypeHash;                                      \
}                                                                           \
                                                                            \
template<>                                                                  \
void CIwPropertyDataType<Type >::Clone(Type const& src, Type& dst)          \
{                                                                           \
    dst = src;                                                              \
}
Provides default implementations for CIwPropertyDataType of s_DataType, Resolve and Clone. User must supply implementations of Parse, Decompose and Serialise.

#define IW_PROPERTY_DECLARE_RESOURCE_TYPE | ( | ResType,
 |  | ResName | )

Implements CIwPropertyDataType for a CIwResource derived pointer type.

Implements CIwPropertyDataType for an object type by making use of member functions of the object.

#define IW_PROPERTY_DECLARE_SIMPLE_TYPE | ( | Type,
 |  | Name | )

Value:

IW_PROPERTY_DECLARE_BASIC_TYPE(Type, #Type)                                 \
                                                                            \
template<>                                                                  \
void CIwPropertyDataType<Type>::Parse(Type& data,                           \
    CIwTextParserITX* pParser)                                              \
{                                                                           \
    pParser->Read##Name(&data);                                             \
}                                                                           \
                                                                            \
template<>                                                                  \
void CIwPropertyDataType<Type>::Decompose(const Type& data,                 \
    CIwTextDecomposer* pDecomposer)                                         \
{                                                                           \
    pDecomposer->WriteAttributeVal(data);                                   \
}                                                                           \
                                                                            \
template<>                                                                  \
void CIwPropertyDataType<Type>::Serialise(Type& data)                       \
{                                                                           \
    IwSerialise##Name(data);                                                \
}
Implements CIwPropertyDataType for a simple built-in data type.

#define IW_PROPERTY_DEFINE_TYPE_MAP | ( | Key,
 |  | Type | )

Value:

template<>                                                                  \
class CIwPropertyTypeMap<Key >                                              \
{                                                                           \
public:                                                                     \
    typedef Type Val;                                                       \
};
Helper define to property data type mapping.

#define IW_RESTYPE_PROPERTY_SET_BINDING "CIwPropertySetBinding"

Resource type string used to store and retrieve CIwPropertySetBinding objects in the resource manager.

Function Documentation

template<class Type>
Type* IwPropertyAddPropertyFactory ( ) [inline]

Templated helper function to register a property factory.

Returns:
NULL.

void IwPropertyAddPropertyFactory | ( | const char * | pPropertyName,
 |  | IwPropertyFactoryFn | facFunc
 | ) |  |

Register a property type factory.

Parameters:
pPropertyName | Name of property data type.
facFunc | Property factory function pointer.

CIwPropertyBase* IwPropertyCreateProperty | ( | uint32 | hash,
 |  | uint32 | defineId,
 |  | const char * | pDebugName
 | ) |  |

Property factory function.

Parameters:
hash | Hash of the name of a property type.
defineId | Hash of the name of a property define.
pDebugName | Optional debug name of property define.

CIwPropertyBase* IwPropertyCreatePropertyFromDefine ( const char * pPropertyDefine )

Create property using the property factory by first looking up a CIwPropertyDefine resource to determine the property type.

Parameters:
pPropertyDefine String name of property define.

bool IwPropertyFactoryExists ( uint32 hash )

Has a property factory been registered for the given property type.

Parameters:
hash Hash of the name of a data type.

bool IwPropertyIsProperty ( const char * pName )

Checks if a CIwPropertyDefine with the given name exists in the resource manager.

Parameters:
hash String name of a property.

bool IwPropertyIsProperty ( uint32 hash )

Checks if a CIwPropertyDefine with the given hash exists in the resource manager.

Parameters:
hash Hash of the name of a property.

void IwPropertySetInit ( )

IwPropertySet module initialisation function. Creates property factory and registers basic types.

Note:
This function should be called on application startup.

void IwPropertySetTerminate ( )

IwPropertySet module terminate function. Destroys property factory and unregisters basic types.

Note:
This function should be called on application shutdown.


Airplay API Reference: Text Input

Airplay API Reference > IwUI API Documentation > IwUI API Reference > Text Input >

Text Input
[IwUI API Reference]

Data Structures

class | CIwUISoftKey
class | CIwUISoftKeyBalloon
class | CIwUISoftKeyboard
Interface element to display touchable soft keyboard. More...
class | CIwUISoftKeyboard
Interface element to display touchable soft keyboard. More...
class | CIwUISoftKeyPosition
Container for a softkey element. Element is positioned next to hardware softkeys buttons on device. If device changes orientation, the contained elements will move into the correct corners to follow the softkeys. More...
class | CIwUISoftKeyPosition
Container for a softkey element. Element is positioned next to hardware softkeys buttons on device. If device changes orientation, the contained elements will move into the correct corners to follow the softkeys. More...
class | CIwUITextField
Editable text widget. When selected, this element activates modal text entry. More...
class | CIwUITextField
Editable text widget. When selected, this element activates modal text entry. More...
class | CIwUITextInput
Text Input Manager. Handles various forms of text input, including keyboard, on-screen soft keyboard, and numeric pad texting. More...
class | CIwUITextInput
Text Input Manager. Handles various forms of text input, including keyboard, on-screen soft keyboard, and numeric pad texting. More...

Detailed Description

Text Input functionality for the IwUI module. Handles various forms of text input, including keyboard, on-screen soft keyboard, and numeric pad texting.


Airplay API Reference: View

Airplay API Reference > IwUI API Documentation > IwUI API Reference > View >

View
[IwUI API Reference]

Data Structures

class | CIwUIView
IwUI singleton which handles high-level functionality relating to the visual representation of elements - rendering, intersection testing, focus and styles. More...
class | CIwUIView
IwUI singleton which handles high-level functionality relating to the visual representation of elements - rendering, intersection testing, focus and styles. More...

Enumerations

enum | IwUIViewDebugFlags

Detailed Description

High level singleton class for handling functionality relating to the visual representation of element.

Enumeration Type Documentation

enum IwUIViewDebugFlags

Enumeration of debug flags for CIwUIView object.

Required Header Files
IwUIView.h
Enumerator:
IW_UI_DEBUG_ELEMENT_OUTLINE_F | Draw Element Outline.
IW_UI_DEBUG_LAYOUT_ITEM_OUTLINE_F | Draw Layout Item's Outline.
IW_UI_DEBUG_MARGIN_OUTLINE_F | Draw Margins.
IW_UI_DEBUG_ALT_STYLE_F | Draw Alternate Style.
IW_UI_DEBUG_HIERARCHY_F | Draw Hierarchy.
IW_UI_DEBUG_SIBLINGS_F | Draw Siblings.


Airplay API Reference: Iwuidelegate

Airplay API Reference > IwUI API Documentation > Iwuidelegate >

Iwuidelegate

Data Structures

class | CIwUIElementSignal< Signal >
class | CIwUIElementSignalBase

Defines

#define | IW_PROPERTY_DECLARE_SIGNAL(ElementSignal)
#define | IW_UI_CALL_SIGNAL(Element, Signal) CallSignal(Element, #Signal);
#define | IW_UI_CREATE_ELEMENT_SLOT(Element, Class, Member)
#define | IW_UI_CREATE_HANDLER_SLOT(Handler, Class, Member)
#define | IW_UI_CREATE_VIEW_SLOT(Owner, Name, Class, Member)
#define | IW_UI_DESTROY_ELEMENT_SLOTS(Element) (Element)->DestroyDelegates(Element);
#define | IW_UI_DESTROY_VIEW_SLOTS(Owner)

Define Documentation

#define IW_PROPERTY_DECLARE_SIGNAL ( ElementSignal )

Value:

typedef CIwUIElementSignal<CIwUISignal<> > ElementSignal;                   \
IW_PROPERTY_DECLARE_SIGNALN(ElementSignal)
Declare an element signal property type.

Parameters:
ElementSignal Name for type.
Note:
There are other versions of this macro for slots which take parameters.
            // Declare signal property type 'Signal_Element' which takes a
            // single CIwUIElement* parameter.
            IW_PROPERTY_DECLARE_SIGNAL1(Signal_Element, CIwUIElement*);

            // Register property factory for 'Signal_Element'
            IwPropertyAddPropertyFactory<Signal_Element>();

            // Declare in a .group file a signal property 'OnButtonClick' to
            // be of type 'Signal_Event'
            CIwResGroup
            {
                name "Signal-Properties"

                CIwPropertyDefine
                {
                    Signal_Element OnButtonClick
                }
            }

#define IW_UI_CALL_SIGNAL | ( | Element,
 |  | Signal | ) | CallSignal(Element, #Signal);

Call a signal delegate attached to an element. See IW_PROPERTY_DECLARE_SIGNAL for how to declare and register a signal.

Parameters:
Element | Pointer to element with signal.
Signal | Name of signal property.
Note:
There are other versions of this macro for slots which take parameters.
            // Call signal property 'OnButtonClick' which takes a single
            // CIwUIElement* parameter, passing a pointer to ourself.
            IW_UI_CALL_SIGNAL1(this, OnButtonClick, CIwUIElement*, this);

#define IW_UI_CREATE_ELEMENT_SLOT | ( | Element,
 |  | Class,
 |  | Member | )

Value:

{                   \
IDelegateQuery* pSlot =                                                     \
new CIwUISlot<Class>(Element, #Member, &Class::Member);                     \
(Element)->AddDelegate(pSlot); }
Create and register a slot function for a derived element. This macro should be used in a derived CIwUIElement class's Activate() function prior to calling the base CIwUIElement::Activate function.

Parameters:
Element | Pointer to CIwUIElement derived object.
Class | CIwUIElement derived class type.
Member | Name of member function of Element.
Note:
There are other versions of this macro for slots which take parameters.
            // Derived CIwUIElement::Activate() function which registers a slot,
            // which takes a single CIwUIElement* parameter.
            void CWindowElement::Activate(bool val)
            {
                if (val)
                {
                    IW_UI_CREATE_ELEMENT_SLOT1(this, CWindowElement,
                        OnClickQuitHandler, CIwUIElement*)
                }
                CIwUIElement::Activate(val);
            }

            // Connect button click handler in .ui file definition of
            // a quit window.
            CWindowElement
            {
                name "Quit-Window"
                style <window>

                CIwUIButton
                {
                    name "Quit-Button"
                    style <button>
                    caption "Quit"
                    OnButtonClick { CWindowElement::OnClickQuitHandler }
                }
            }

#define IW_UI_CREATE_HANDLER_SLOT | ( | Handler,
 |  | Class,
 |  | Member | )

Value:

{                   \
IDelegateQuery* pSlot =                                                     \
new CIwUISlot<Class>(Handler, #Member, &Class::Member);                     \
(Handler)->GetElement()->AddDelegate(pSlot); }
Create a slot in an element handler and attach it to the associated element. This macro should be used in a derived CIwUIElementEventHandler class's Activate() function. Signals in the element, or a child element, can then be attached to slots in the handler.

Parameters:
Handler | Pointer to CIwUIElementEventHandler derived object.
Class | CIwUIElementEventHandler derived class type.
Member | Name of member function of Handler.
Note:
There are other versions of this macro for slots which take parameters.
            // Derived CIwUIElementEventHandler::Activate() function which
            // registers a slot, which takes a single CIwUIElement* parameter.
            virtual void Activate(bool val)
            {
                CIwUIElementEventHandler::Activate(val);
                if (val)
                {
                    IW_UI_CREATE_HANDLER_SLOT1(this, CQuitHandler,
                        OnClickQuitHandler, CIwUIElement*);
                }
            }

            // Connect button click handler in .ui file definition of element.
            CIwUIButton
            {
                name "Quit-Button"
                style <button>
                caption "Quit"
                OnButtonClick { OnClickQuitHandler }
                CQuitHandler { }
            }

#define IW_UI_CREATE_VIEW_SLOT | ( | Owner,
 |  | Name,
 |  | Class,
 |  | Member | )

Value:

{               \
IDelegateQuery* pSlot =                                                     \
new CIwUISlot<Class>(Owner, #Member, &Class::Member);                       \
IwGetUIView()->AddDelegate(IwHashString(#Class), IwHashString(Name), pSlot); }
Register an application slot function with the CIwUIView singleton. Slots registered with the view can be attached in data or code to element signals.

Parameters:
Owner | Pointer to object that contains the slot function.
Name | String name for object when resolving slot by object name.
Class | Class type which contains slot function.
Member | Name of slot function.
Note:
There are other versions of this macro for slots which take parameters.
            // Derived CIwUIController constructor which registers a slot
            // which takes a single CIwUIElement* parameter.
            CController()
            {
                IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController,
                    OnClickHandler, CIwUIElement*)
            }

#define IW_UI_DESTROY_ELEMENT_SLOTS ( Element ) (Element)->DestroyDelegates(Element);

Unregister and destroy all slot functions for a derived element previous registered using IW_UI_CREATE_ELEMENT_SLOT.

Unregister and destroy all slot functions for a derived element handler previously registered using IW_UI_CREATE_HANDLER_SLOT.

Note:
Generally it is not necessary to call this function as an element destroys all registered slots when it is deactivated.
Parameters:
Element Pointer to CIwUIElement derived object.
Note:
Generally it is not necessary to call this function as a handler's slot are destroyed when the associated element is deactivated or the handler is removed from the element.
Parameters:
Handler Pointer to CIwUIElementEventHandler derived object.

#define IW_UI_DESTROY_VIEW_SLOTS ( Owner )

Value:

{                                   \
    if(CIwUIView* pView = IwGetUIView()) pView->DestroyDelegates(Owner); }
Unregister and destroy all application slot functions for a given object which were previously registered using IW_UI_CREATE_VIEW_SLOT.

Note:
This function should be called if the handler object which has slots registered is being destroyed prior to the CIwUIView singleton being destroyed.
Parameters:
Owner Pointer to slot handler object.


Airplay API Reference: IwUI Examples

Airplay API Reference > IwUI API Documentation > IwUI Examples >

IwUI Examples

This document provides a set of examples that illustrate how to use the functionality contained within IwUI.

The following examples are contained within this section:

  • 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


Airplay API Reference: IwUI Hello World Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Hello World Example >

IwUI Hello World Example

The following example demonstrates simple load and display of a dialogue.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIStyleSheetManager

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

This example demonstrates the loading and instantiation of an element defined in data.

In IwUI, elements are typically stored as a standard resource in IwResManager. It is good practise to clone these resources rather than using them directly. Elements can also be dynamically built from code. See the IwUIHelloWorldDynamic for an example of this usage.

Once the element has been cloned it is added to the UI view singleton. The UI view contains the root element and is responsible for maintaining the elements.

The CIwUIController is a singleton that converts input into events. Events from the system are constantly gathered and are dispatched when CIwUIController::Update is called.

For the button to function CIwUIView::Update and CIwUIController::Update must be called.

This example registers a single global handler (CHelloWorldHandler) to exit on button presses.

Finally CIwUIView::Render is called to render the UI.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIHelloWorld
//-----------------------------------------------------------------------------

// @}

#include "IwGx.h"
#include "IwUI.h"

//Simple handler to quit application on any button press
class CHelloWorldHandler : public IIwUIEventHandler
{
    virtual bool HandleEvent(CIwEvent* pEvent)
    {
        return false;
    }

    virtual bool FilterEvent(CIwEvent* pEvent)
    {
        if( pEvent->GetID() == IWUI_EVENT_BUTTON )
        {
            s3eDeviceRequestQuit();
            return true;
        }

        return false;
    }
} g_HelloWorldHandler;

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Provide global event handler
    IwGetUIController()->AddEventHandler(&g_HelloWorldHandler);

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUIHelloWorld.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    //Find the dialog template
    CIwUIElement* pDialogTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("Vertical", "CIwUIElement");

    //And instantiate it
    CIwUIElement* pDialog = pDialogTemplate->Clone();
    IwGetUIView()->AddElement(pDialog);
    IwGetUIView()->AddElementToLayout(pDialog);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Hello World Dynamic Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Hello World Dynamic Example >

IwUI Hello World Dynamic Example

The following example demonstrates simple creation and displaying of a dialogue.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIButton

  • CIwUILabel

  • CIwUIImage

  • CIwUIStyleSheetManager

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

This example demonstrates the instantiation of elements from code.

While elements are normally created from data, it can sometimes be useful to create them directly in code. This example matches IwUIHelloWorld, except it manually creates the elements instead of using a .ui file. CreateDialog() does the creation of the elements.

Note that few properties apart from style need to be set. This example relies on the Airplay "house style", which is loaded from data, to define most of the element properties.

Once the element has been created it is added to the UI view singleton. The UI view contains the root element and is responsible for maintaining the elements.

The CIwUIController is a singleton that converts input into events. Events from the system are constantly gathered and are dispatched when CIwUIController::Update is called.

For the button to function CIwUIView::Update and CIwUIController::Update must be called.

This example registers a single global handler (CHelloWorldHandler) to exit on button presses.

Finally CIwUIView::Render is called to render the UI.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIHelloWorldDynamic
//-----------------------------------------------------------------------------

//
#include "IwGx.h"
#include "IwUI.h"

//Simple handler to quit application on any button press
class CHelloWorldHandler : public IIwUIEventHandler
{
    virtual bool HandleEvent(CIwEvent* pEvent)
    {
        return false;
    }

    virtual bool FilterEvent(CIwEvent* pEvent)
    {
        if( pEvent->GetID() == IWUI_EVENT_BUTTON )
        {
            s3eDeviceRequestQuit();
            return true;
        }

        return false;
    }
} g_HelloWorldHandler;

//CreateDialog creates the same controls and layout as the .ui file in the regular HelloWorld application
CIwUIElement* CreateDialog()
{
    //Create a container for the dialog
    CIwUIElement* pContainer = new CIwUIElement;

    //Set the container to resize to fit it's children automatically.
    //The layout of the root view element will cause this to be centred on the screen.
    pContainer->SetSizeToContent(true);

    //Give the container a vertical layout. This will automatically arrange it's children vertically.
    pContainer->SetLayout(new CIwUILayoutVertical);

    //Create a label to say "HELLO WORLD"
    CIwUILabel* pLabel = new CIwUILabel;

    //Give the label the standard label style. This is the name of a property set
    //from the current style. This control will inherit the properties of that set.
    pLabel->SetStyle("<label_large>");

    //Set the caption of the label
    pLabel->SetCaption("HELLO WORLD");

    //Add the label to the container and the container's layout
    pContainer->AddChild(pLabel);
    pContainer->GetLayout()->AddElement(pLabel);

    //Create a button in the standard button style
    CIwUIButton* pButton = new CIwUIButton;
    pButton->SetStyle("<button>");

    //Set the maximum size of the button. This tells the button how large to physically
    //expand to if it has unlimited space.
    pButton->SetSizeMax(CIwVec2(120, 37));

    //Set the caption to be "Goodbye world"
    pButton->SetCaption("Goodbye World");

    //Add the button to the container and the container's layout
    pContainer->AddChild(pButton);
    pContainer->GetLayout()->AddElement(pButton);

    //Create an image
    CIwUIImage* pImage = new CIwUIImage;

    //Set the Airplay logo texture to govern its appearance.
    pImage->SetProperty("texture", (CIwTexture*)IwGetResManager()->GetResNamed("Image", "CIwTexture"));

    //Set the image to automatically resize to the size of the material's texture
    pImage->SetSizeToContent(true);

    //Add the image to the container and the container's layout
    pContainer->AddChild(pImage);
    pContainer->GetLayout()->AddElement(pImage);

    return pContainer;
}

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Provide global event handler
    IwGetUIController()->AddEventHandler(&g_HelloWorldHandler);

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUIHelloWorld.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    //And instantiate it
    CIwUIElement* pDialog = CreateDialog();
    IwGetUIView()->AddElement(pDialog);
    IwGetUIView()->AddElementToLayout(pDialog);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Dynamic Population Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Dynamic Population Example >

IwUI Dynamic Population Example

The following example demonstrates using ui files as a template to fill a scrolling view with custom components.

The main classes used to achieve this are:

  • CIwUIElement

  • CIwUILabel

The main functions used to achieve this are:

  • CIwUIElement::GetChildNamed

  • CIwUILabal::SetCaption

This example demonstrates using multiple cloned versions of a template element to produce a scrolling list of Airplay System properties.

Once the element is cloned, specific component elements can be found using GetChildNamed. They can then be cast to the appropriate type for customisation.

IwSafeCast will provide an assertion that the target type is the correct one.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIDynamicPopulation
//-----------------------------------------------------------------------------

// @}

#include "IwGx.h"
#include "IwUI.h"

//Add a string item
void AddStringItem(CIwUIElement* pList, CIwUIElement* pItemTemplate, const char* name, const char* value)
{
    //Instantiate the new item
    CIwUIElement* pItem = pItemTemplate->Clone();

    //Set name/value
    IwSafeCast<CIwUILabel*>(pItem->GetChildNamed("PropName"))->SetCaption(name);
    IwSafeCast<CIwUILabel*>(pItem->GetChildNamed("PropValue"))->SetCaption(value);

    //Generate a unique name for the new item
    char buf[20];
    sprintf(buf, "item_%d", pList->GetNumChildren());
    pItem->SetName(buf);

    //Add to the list and its layout
    pList->GetLayout()->AddElement(pItem);
}

//Add an int item (by converting to a string item call)
void AddIntItem(CIwUIElement* pList, CIwUIElement* pItemTemplate, const char* name, int value)
{
    char strval[20];
    sprintf(strval, "%d", value);
    AddStringItem(pList, pItemTemplate, name, strval);
}

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUIDynamicPopulation.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    //Find the main dialog template
    CIwUIElement* pDialogTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("Main", "CIwUIElement");

    //And instantiate it
    CIwUIElement* pDialog = pDialogTemplate->Clone();
    IwGetUIView()->AddElementToLayout(pDialog);

    //Get the list to populate
    CIwUIElement* pList = pDialog->GetChildNamed("PropList");
    //Get the item template
    CIwUIElement* pItemTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("PropItem", "CIwUIElement");

    //Now populate with various system properties
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_OS", s3eDeviceGetString(S3E_DEVICE_OS));
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_CLASS", s3eDeviceGetString(S3E_DEVICE_CLASS));
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_ID", s3eDeviceGetString(S3E_DEVICE_ID));
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_PHONE_NUMBER", s3eDeviceGetString(S3E_DEVICE_PHONE_NUMBER));
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_ARCHITECTURE", s3eDeviceGetString(S3E_DEVICE_ARCHITECTURE));
    AddStringItem(pList, pItemTemplate, "S3E_DEVICE_S3E_VERSION", s3eDeviceGetString(S3E_DEVICE_S3E_VERSION));

    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_OS", s3eDeviceGetInt(S3E_DEVICE_OS));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_CLASS", s3eDeviceGetInt(S3E_DEVICE_CLASS));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_ID", s3eDeviceGetInt(S3E_DEVICE_ID));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_LANGUAGE", s3eDeviceGetInt(S3E_DEVICE_LANGUAGE));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_TOTAL_RAM", s3eDeviceGetInt(S3E_DEVICE_TOTAL_RAM));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_FREE_RAM", s3eDeviceGetInt(S3E_DEVICE_FREE_RAM));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_ARCHITECTURE", s3eDeviceGetInt(S3E_DEVICE_ARCHITECTURE));
    AddIntItem(pList, pItemTemplate, "S3E_DEVICE_S3E_VERSION", s3eDeviceGetInt(S3E_DEVICE_S3E_VERSION));

    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_WIDTH", s3eSurfaceGetInt(S3E_SURFACE_WIDTH));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_HEIGHT", s3eSurfaceGetInt(S3E_SURFACE_HEIGHT));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_PITCH", s3eSurfaceGetInt(S3E_SURFACE_PITCH));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_PIXEL_TYPE", s3eSurfaceGetInt(S3E_SURFACE_PIXEL_TYPE));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_WIDTH", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_WIDTH));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_HEIGHT", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_HEIGHT));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_PIXEL_TYPE", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_PIXEL_TYPE));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_PITCH", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_PITCH));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_BLIT_DIRECTION", s3eSurfaceGetInt(S3E_SURFACE_BLIT_DIRECTION));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DISPLAY", s3eSurfaceGetInt(S3E_SURFACE_DISPLAY));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_NUM_DISPLAYS", s3eSurfaceGetInt(S3E_SURFACE_NUM_DISPLAYS));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_BLIT_DIRECTION", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_BLIT_DIRECTION));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_WIDTH_QUANTISED", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_WIDTH_QUANTISED));
    AddIntItem(pList, pItemTemplate, "S3E_SURFACE_DEVICE_HEIGHT_QUANTISED", s3eSurfaceGetInt(S3E_SURFACE_DEVICE_HEIGHT_QUANTISED));
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Layouts Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Layouts Example >

IwUI Layouts Example

The following example demonstrates the use of custom properties to provide additional functionality. The data demonstrates the use of layouts for screen-size independence.

The main classes used to achieve this are:

  • CIwManaged

  • CIwUIController

The main functions used to achieve this are:

  • CIwUIController::AddEventHandler

This example installs a global event filter (g_LayoutsHandler) to allow CIwUIButtons with a custom 'uilink' property to open other dialogs.

Custom properties can be added entirely in data. A property definition is required. This is in IwUILayouts.group:

    CIwPropertyDefine
    {
        CIwPropertyString uilink
    }

The expmetatemplate file can be modified to expose custom properties through the editor.

A global concept of the current screen (g_Screen) is introduced and the handler replaces the current screen with the specified target screen, found using a simple resource query.

Various screens are layed out with the UI editor tool, and are navigatible. Any button marked with 'exit' quits the application.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUILayouts
//-----------------------------------------------------------------------------

// @}

#include "IwGx.h"
#include "IwUI.h"
#include "IwString.h"

CIwUIElement* g_Screen;
CIwString<16> g_String;

void SetScreen(const char* screen)
{
    //Find the dialog template
    CIwUIElement* pDialogTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed(screen, "CIwUIElement");

    if( !pDialogTemplate )
        return;

    //Remove the old screen
    if( g_Screen )
        IwGetUIView()->DestroyElements();

    //And instantiate it
    g_Screen = pDialogTemplate->Clone();
    IwGetUIView()->AddElement(g_Screen);
    IwGetUIView()->AddElementToLayout(g_Screen);
}

//Simple handler to quit application on any button press
class CLayoutsHandler : public IIwUIEventHandler
{
    virtual bool FilterEvent(CIwEvent* pEvent)
    {
        if( pEvent->GetID() == IWUI_EVENT_BUTTON )
        {
            CIwPropertyString uilink;
            if( (IwSafeCast<CIwUIElement*>(pEvent->GetSender()))->GetProperty("uilink", uilink, true) )
            {
                if( !strcmp(uilink.c_str(), "exit") )
                {
                    s3eDeviceRequestQuit();
                    return true;
                }

                g_String = uilink.c_str();

                return true;
            }
        }

        return false;
    }

    virtual bool HandleEvent(CIwEvent* pEvent)
    {
        return false;
    }
} g_LayoutsHandler;

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Provide global event handler
    IwGetUIController()->AddEventHandler(&g_LayoutsHandler);

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUILayouts.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    SetScreen("main");
}

//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the UI Screen
    if (g_String.length())
    {
        SetScreen(g_String.c_str());
        g_String = "";
    }

    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Localise Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Localise Example >

IwUI Localise Example

The following example demonstrates localisation of a simple dialogue.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIStyleSheetManager

The main functions used to achieve this are:

  • IwUIInit()
  • IwUISetLocaliseCallback()

  • IwUITerminate();

This example demonstrates the loading localised strings and the useage of a callback to provide this data to IwUI.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUILocalise
//-----------------------------------------------------------------------------

// @}

#include "IwGx.h"
#include "IwUI.h"

// Enumeration of languages we localise for
enum LocaliseLanguages
{
    LOCALISE_ENGLISH,
    LOCALISE_FRENCH,

    NUM_LANGUAGES,

    DEFAULT_LANGUAGE = LOCALISE_ENGLISH
};

// Current language
LocaliseLanguages g_Localise = DEFAULT_LANGUAGE;

// String names of languages
const char* g_LanguageNames[] =
{
    "english",
    "french"
};

// Resource class to contain data for each localised string
#define RESTYPE_LOCALISED_STRING    "CLocalisedString"
class  CLocalisedString : public CIwResource
{
public:
    IW_MANAGED_DECLARE(CLocalisedString);

    CLocalisedString()
    {
    }

    ~CLocalisedString()
    {
    }

    // IwResource virtuals
    virtual bool ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
    {
        for (int i=0; i<NUM_LANGUAGES; i++)
        {
            if (!stricmp(g_LanguageNames[i], pAttrName))
            {
                pParser->ReadString(m_Strings[i]);
                return true;
            }
        }

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

    virtual void ParseClose(CIwTextParserITX* pParser)
    {
        CIwManaged* pParent = pParser->GetObject(-1);
        if(!strcmp(pParent->GetClassName(), "CIwResGroup"))
        {
            // Add ourselves to the current res group.
            IwGetResManager()->AddRes(RESTYPE_LOCALISED_STRING, this);
        }
        else
        {
            CIwResource::ParseClose(pParser);
        }
    }

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

        for (int i=0; i<NUM_LANGUAGES; i++)
        {
            m_Strings[i].Serialise();
        }
    }

    // Public interface
    const char* GetString(LocaliseLanguages language)
    {
        if ((0 <= language) && (language < NUM_LANGUAGES))
        {
            return m_Strings[language].c_str();
        }

        return NULL;
    }

private:
    // Member data
    CIwStringL m_Strings[NUM_LANGUAGES];
};
IW_MANAGED_IMPLEMENT_FACTORY(CLocalisedString);

// Custom controller containing slot functions to be attached to elements
class CController : public CIwUIController
{
public:
    CController()
    {
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickQuit,
            CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT2(this, "CController", CController, OnRadioLanguage,
            CIwUIElement* , int16 )
    }

private:
    void OnRadioLanguage(CIwUIElement*, int16 mode)
    {
        if (mode >= 0 && mode < NUM_LANGUAGES)
        {
            g_Localise = (LocaliseLanguages) mode;
        }
    }

    void OnClickQuit(CIwUIElement*)
    {
        s3eDeviceRequestQuit();
    }
};
//-----------------------------------------------------------------------------
const char* LocaliseCallback(const CIwPropertySet& propertySet)
{
    uint32 hash = 0;
    if(propertySet.GetProperty("localiseCaption", hash, true))
    {
        CLocalisedString* pLocString = (CLocalisedString*)
            IwGetResManager()->GetResHashed(hash,
                RESTYPE_LOCALISED_STRING, IW_RES_SEARCH_ALL_F);

        if (pLocString)
        {
            return pLocString->GetString(g_Localise);
        }
    }
    return NULL;
}
//-----------------------------------------------------------------------------
void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    IW_CLASS_REGISTER(CLocalisedString);

    //Set localilisation callback
    IwUISetLocaliseCallback(LocaliseCallback);

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIView;
    new CController;

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUILocalise.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    //Find the dialog template
    CIwUIElement* pDialogTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("Vertical", "CIwUIElement");

    //And instantiate it
    CIwUIElement* pDialog = pDialogTemplate->Clone();
    IwGetUIView()->AddElement(pDialog);
    IwGetUIView()->AddElementToLayout(pDialog);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    IW_CLASS_REMOVE(CLocalisedString);

    //Terminate the IwUI module
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    static LocaliseLanguages g_OldLocalise = DEFAULT_LANGUAGE;
    if (g_OldLocalise != g_Localise)
    {
        g_OldLocalise = g_Localise;
        IwGetUIView()->Reactivate();
    }

    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Stylesheets Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Stylesheets Example >

IwUI Stylesheets Example

The following example demonstrates switching stylesheets on an application.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIButton

  • CIwUILabel

  • CIwUITabBar

  • CIwUIProgressBar

  • CIwUISlider

  • CIwUIAlertDialog

  • CIwUIStyleManager

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

  • CIwUIStyleManager::SetStylesheet

  • CIwUIStyleManager::QueueStylesheet

This example demonstrates an application with multiple stylesheets that can be switched during run-time by the user.

The stylesheets are defined in itx files that override the default appearance of the application with custom designs.

The stylesheets are loaded from the resource manager and can be changed by clicking a button on the tab bar.

A confirmation alert dialog is displayed when a user tries to quit the application.

The following graphic illustrates the example output.


Airplay API Reference: IwUI Calculator Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Calculator Example >

IwUI Calculator Example

The following example demonstrates a simple calculator

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIButton

  • CIwUILabel

  • CIwUIImage

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

This example demonstrates a simple calculator with all the basic functionality.

The UI file consists of label to show the solution, and a grid of buttons that provide the calculator with functionality. This UI file was constructed by using the ASUI Editor tool, and a tutorial for re-creating it is available.

Each button has a click handler that performs the appropriate calculator function. The result is displayed in the label.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUICalculator
//-----------------------------------------------------------------------------

//
// Library includes
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwUI.h"
#include "IwUIAnimation.h"
#include "IwUIController.h"
#include "IwUIButton.h"
#include "IwUICheckbox.h"
#include "IwUIElement.h"
#include "IwUIEvent.h"
#include "IwUILabel.h"
#include "IwUISlider.h"
#include "IwUIView.h"
#include "IwUIProgressBar.h"
#include "IwUIPropertySet.h"
#include "s3eKeyboard.h"
#include "IwUISoftKeyboard.h"
#include "IwUITextInput.h"

extern bool g_IwTextureAssertPowerOf2;
bool g_Quit;
bool bAC;
CIwUILabel* pLabel;
CIwUIButton* pButton_C;

#define DEFAULTSTYLE

#ifdef DEFAULTSTYLE
// Load the default Stylesheet
static const char* s_Stylesheets[] =
{
    "Small",            // Small Size
    "Medium",           // Medium Size
    "Large",            // Large Size
};
#else
// Load the dark Stylesheet
static const char* s_Stylesheets[] =
{
    "SmallDark",        // Small Size
    "MediumDark",       // Medium Size
    "LargeDark",        // Large Size
};
#endif

//Calculator Modes
enum {
    CALC_MODE_NONE,
    CALC_MODE_PLUS,
    CALC_MODE_MINUS,
    CALC_MODE_TIMES,
    CALC_MODE_DIVIDE,
};

char    CalcText[100];      //Holds the Calculator Text
int16   CalcMode    = CALC_MODE_NONE;
double  Memory      = 0;    //Holds Calculator Memory Value
double  LastValue   = 0;    //Holds the Value of the last operation
double  PastValue   = 0;    //Holds the Value of the operation for repeat
bool    b_Repeat    = false;//Repeat the last operation

#define BUTTON(x) void OnClickButton_##x(CIwUIElement*) { OnButtonPress(#x); }

void OnButtonPress(const char* button)
{
    //Handle button press 0-9
    if (!strcmp(CalcText, "0") || (button[0] == '0' && !strcmp(CalcText, "-0")))
        strcpy(CalcText, button);
    else if (strlen(CalcText) < 85)
        strcat(CalcText, button);

    pLabel->SetCaption(CalcText);
    pButton_C->SetCaption("C"); bAC = false;
}

void OnButtonEqual()
{
    //Load the value from the Calculator
    double NewValue = atof(CalcText);

    if (b_Repeat)
    {
        NewValue = PastValue;
        LastValue = atof(CalcText);
    }

    switch (CalcMode)
    {
        case CALC_MODE_PLUS:
            sprintf(CalcText, "%g", LastValue + NewValue);
            break;
        case CALC_MODE_MINUS:
            sprintf(CalcText, "%g", LastValue - NewValue);
            break;
        case CALC_MODE_TIMES:
            sprintf(CalcText, "%g", LastValue * NewValue);
            break;
        case CALC_MODE_DIVIDE:
            if (!atof(CalcText))
            {
                strcpy(CalcText, "0");
                pLabel->SetCaption("ERROR");
                return;
            }
            else
                sprintf(CalcText, "%g", LastValue / NewValue);
    }

    if (CalcMode)
    {
        pLabel->SetCaption(CalcText);
        if (!b_Repeat)
        {
            PastValue = NewValue;
            b_Repeat = true;
        }
    }
}

class CController : public CIwUIController
{
public:
    CController()
    {
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_0, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_1, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_2, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_3, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_4, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_5, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_6, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_7, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_8, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_9, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_plus, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_minus, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_times, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_divide, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_equal, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_plusminus, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_dot, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_C, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_mc, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_mplus, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_mminus, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickButton_mr, CIwUIElement*)
    }

private:
    void OnClickButton_mc(CIwUIElement*)
    {
        Memory = 0;
    }

    void OnClickButton_mplus(CIwUIElement*)
    {
        Memory += atof(CalcText);
    }

    void OnClickButton_mminus(CIwUIElement*)
    {
        Memory -= atof(CalcText);
    }

    void OnClickButton_mr(CIwUIElement*)
    {
        sprintf(CalcText, "%g", Memory);
        pLabel->SetCaption(CalcText);
    }

    void OnClickButton_plus(CIwUIElement*)
    {
        if (CalcMode && !b_Repeat) OnButtonEqual();

        LastValue = atof(CalcText);
        CalcMode = CALC_MODE_PLUS;
        strcpy(CalcText, "0");
        b_Repeat = false;
    }

    void OnClickButton_minus(CIwUIElement*)
    {
        if (CalcMode && !b_Repeat) OnButtonEqual();

        LastValue = atof(CalcText);
        CalcMode = CALC_MODE_MINUS;
        strcpy(CalcText, "0");
        b_Repeat = false;
    }

    void OnClickButton_times(CIwUIElement*)
    {
        if (CalcMode && !b_Repeat) OnButtonEqual();

        LastValue = atof(CalcText);
        CalcMode = CALC_MODE_TIMES;
        strcpy(CalcText, "0");
        b_Repeat = false;
    }

    void OnClickButton_divide(CIwUIElement*)
    {
        if (CalcMode && !b_Repeat) OnButtonEqual();

        LastValue = atof(CalcText);
        CalcMode = CALC_MODE_DIVIDE;
        strcpy(CalcText, "0");
        b_Repeat = false;
    }

    void OnClickButton_equal(CIwUIElement*)
    {
        //Perform Calculation with set mode
        OnButtonEqual();
    }

    void OnClickButton_plusminus(CIwUIElement*)
    {
        //Flip the sign of the number
        char textbuf[100];
        strcpy(textbuf, CalcText);

        if (textbuf[0] == '-')
        {
            strcpy(CalcText,textbuf+1);
        }
        else
        {
            CalcText[0] = '-';
            strcpy(CalcText+1,textbuf);
        }
        pLabel->SetCaption(CalcText);
    }

    void OnClickButton_dot(CIwUIElement*)
    {
        //Insert the decimal point if it is not already present
        if (!strchr(CalcText, '.'))
        {
            strcat(CalcText, ".");
            pLabel->SetCaption(CalcText);
        }

        pButton_C->SetCaption("C"); bAC = false;
    }

    void OnClickButton_C(CIwUIElement*)
    {
        //Reset the Calculator Text
        strcpy(CalcText, "0");
        pLabel->SetCaption(CalcText);

        if (bAC)
        {
            CalcMode    = CALC_MODE_NONE;
            LastValue   = 0;
            PastValue   = 0;
            b_Repeat    = false;
        }

        bAC = true;
        pButton_C->SetCaption("AC");
    }

    BUTTON(0)
    BUTTON(1)
    BUTTON(2)
    BUTTON(3)
    BUTTON(4)
    BUTTON(5)
    BUTTON(6)
    BUTTON(7)
    BUTTON(8)
    BUTTON(9)

    // Accept number key input
    bool HandleEvent(CIwEvent* pEvent)
    {
        if (pEvent->GetID() == IWUI_EVENT_KEY)
        {
            CIwUIEventKey* pEventKey = (CIwUIEventKey*)pEvent;
            if (!pEventKey->GetPressed())
            {
                s3eKey key = pEventKey->GetKey();
                if ((s3eKey0 <= key) && (key <= s3eKey9))
                {
                    int num = (int)key - s3eKey0;
                    char buffer[0x10];
                    sprintf(buffer, "%d", num);
                    OnButtonPress(buffer);
                    return true;
                }
            }
        }
        return CIwUIController::HandleEvent(pEvent);
    }
};

S3E_MAIN_DECL void IwMain()
{
    g_IwTextureAssertPowerOf2 = false;
    g_Quit = false;

    while(!g_Quit)
    {
        // Initialize Airplay
        IwUIInit();

        {
            CIwUIView view;
            CController controller;

            CIwResGroup* pResGroup = IwGetResManager()->LoadGroup("IwUICalculator.group");

            {
                // Cut-off sizes for stylesheet scale decision
                const int32 area_0 = (320*480); // Smaller than this uses small style
                const int32 area_1 = (640*480); // Larger/Equal than this uses large style
                const int32 actual_area = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT)
                                         *s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
                int32 style_id = 1;
                if(actual_area<area_0)
                    style_id = 0;
                else if(actual_area>=area_1)
                    style_id = 2;

                CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[style_id], IW_UI_RESTYPE_STYLESHEET);
                IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            }

            CIwUIElement* pWidgets = CIwUIElement::CreateFromResource("Calculator");
            view.AddElement(pWidgets);
            view.AddElementToLayout(pWidgets);

            // Reset the Calculator to 0
            strcpy(CalcText, "0");
            pLabel = (CIwUILabel*)pWidgets->GetChildNamed("Label");
            pLabel->SetCaption(CalcText);

            pButton_C = (CIwUIButton*)pWidgets->GetChildNamed("Button_C");
            bAC = true;
            pButton_C->SetCaption("AC");

            CIwUIButton* button;
            button = (CIwUIButton*)pWidgets->GetChildNamed("Button_divide");
            button->SetCaption("\xc3\xb7"); //UTF8 divide
            button = (CIwUIButton*)pWidgets->GetChildNamed("Button_times");
            button->SetCaption("\xc3\x97"); //UTF8 times

            // Ensure layout is valid prior to setting focus element
            view.Layout();

            // Pick an element to have focus by default
            CIwUIElement* pFocusElement = pWidgets->GetChildNamed("Button_equal");
            IwGetUIView()->RequestFocus(pFocusElement);

            bool restart = false;
            while(!g_Quit && !restart)
            {
                IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

                IwGetUIController()->Update();
                view.Update(50);
                view.Render();

                IwGxFlush();
                IwGxSwapBuffers();
                s3eDeviceYield();
                s3eKeyboardUpdate();
                s3ePointerUpdate();

                g_Quit |= (s3eDeviceCheckQuitRequest()!=0);
            }

            IwGetResManager()->DestroyGroup(pResGroup);
        }

        IwUITerminate();
    }
}


Airplay API Reference: IwUI Data Binding Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Data Binding Example >

IwUI Data Binding Example

The following example demonstrates data binding to a database.

CDatabaseHandler holds a connection to a database. It provides functionality to query the database. It also tell observers when changes to the database are made.

CDataBinding is derived from CIwPropertySetBinding and is used to translate requests to get or set a property into database queries. It is also responsible for telling the element it provides a property for when it has changed due to the database being updated.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIDataBinding
//-----------------------------------------------------------------------------

// @}

// Library Includes
#include "IwUI.h"

// Example Includes
#include "DatabaseHandler.h"

// Externs
extern bool g_IwTextureAssertPowerOf2;

// Globals
bool g_Quit = false;
CIwArray<class CDataBinding*> g_NotifyBindings;

// Statics
static const char* s_DatabasePath = "IwUIDatabinding/db";

class CCommandHandler
{
public:
    CCommandHandler()
    {
        IW_UI_CREATE_VIEW_SLOT1(this, "CCommandHandler", CCommandHandler,
            OnClickQuit, CIwUIElement*)
    }

    ~CCommandHandler()
    {
        IW_UI_DESTROY_VIEW_SLOTS(this)
    }

private:
    void OnClickQuit(CIwUIElement*)
    {
        g_Quit = true;
    }
};

S3E_MAIN_DECL void IwMain()
{
    g_IwTextureAssertPowerOf2 = false;
    g_Quit = false;

    while(!g_Quit)
    {
        // Initialize Airplay
        IwUIInit();
        IwGxSetColClear(0xf0, 0xf0, 0xf0, 0xff);

        IW_CLASS_REGISTER(CDataBinding);

        // Create singletons
        CDatabaseHandler* pDatabaseHandler = new CDatabaseHandler;
        new CIwUIView;
        new CIwUIController;
        CCommandHandler* pCommandHandler = new CCommandHandler;

        // Load database
        bool ret = pDatabaseHandler->OpenDatabaseInMemory();
        IwAssertMsg(UI, ret, ("Failed to open databse %s", s_DatabasePath));

        // Ensure we have table
        if (!pDatabaseHandler->TableExists("tbl"))
        {
            const char* pSQL = "create table tbl(id integer primary key, val int);";
            pDatabaseHandler->Exec(pSQL);

            // Put some data in the table
            pSQL = "insert into tbl values (1, 25);";
            pDatabaseHandler->Exec(pSQL);
        }

        // Load resources
        CIwResGroup* pResGroup = IwGetResManager()->LoadGroup("IwUIDataBinding.group");

        // Create main page
        CIwUIElement* pTable = CIwUIElement::CreateFromResource("Table");
        IwGetUIView()->AddElementToLayout(pTable);

        // Pick an element to have focus by default
        CIwUIElement* pFocusElement = pTable->GetChildNamed("Slider");
        IwGetUIView()->RequestFocus(pFocusElement);

        uint64 lastTime = s3eTimerGetMs();
        while(!g_Quit)
        {
            IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

            IwGetUIController()->Update();

            // Calculate an update time step.
            uint64 currentTime = s3eTimerGetMs();
            int32 updateTime = currentTime > lastTime ?
                MIN((int32)(currentTime - lastTime), 1000) : 0;
            lastTime = currentTime;

            // This isn't great but must be a asynchronous
            while (g_NotifyBindings.size())
            {
                CDataBinding* pBinding = g_NotifyBindings.pop_back_get();
                pBinding->NotifyObserverOfChange();
            }

            // Update & render
            IwGetUIView()->Update(updateTime);
            IwGetUIView()->Render();

            // Flush render queue
            IwGxFlush();
            IwGxSwapBuffers();

            // Standard device interaction
            s3eDeviceYield();
            s3eKeyboardUpdate();
            s3ePointerUpdate();

            // Check for quit request
            g_Quit |= (s3eDeviceCheckQuitRequest()!=0);
        }

        // Destroy resources
        IwGetResManager()->DestroyGroup(pResGroup);

        // Close database
        pDatabaseHandler->CloseDatabase();

        // Destroy singletons
        delete pCommandHandler;
        delete IwGetUIController();
        delete IwGetUIView();
        delete pDatabaseHandler;

        IW_CLASS_REMOVE(CDataBinding);

        // Free array
        g_NotifyBindings.clear_optimised();

        // Terminate Airplay
        IwUITerminate();
    }
}


Airplay API Reference: IwUI RSS Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI RSS Example >

IwUI RSS Example

The following example fetches RSS feeds from the web and displays them.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIButton

  • CIwUILabel

  • CIwUIImage

  • CIwHTTP

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

This example demonstrates fetching RSS feeds using the CIwHTTP class and displaying them dynamically on a UI. The example allows the user to maintain a list of feeds that will be fetched by the IwRSS class and stored persistently in feeds.bin.

In the example the news items are parsed and populate a CIwUIScrollableView. If the news item contains an image then it is downloaded and appended to the description.

The functions below AddRSSEntry() and AddRSSImage() add content dynamically to the UI. AddRSSEntry clones a template while AddRSSImage creates a new CIwUIImage and sets its texture property to the downloaded image.

A SetView() function is used to switch the dialog displayed by the application. It calls SetModal to change which element is intersected with and displays a pop-up animation when switching to the edit or quit dialog.

The CIwUIHandleKey class handles OK, Action and Back key presses to perform the correct action.

The stylesheet is changed automatically so that the elements are larger on high resolution screens.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIRSS
//-----------------------------------------------------------------------------

//
// Library includes
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwUI.h"
#include "IwUIAnimation.h"
#include "IwUIController.h"
#include "IwUIButton.h"
#include "IwUICheckbox.h"
#include "IwUIElement.h"
#include "IwUIEvent.h"
#include "IwUILabel.h"
#include "IwUISlider.h"
#include "IwUIView.h"
#include "IwUIProgressBar.h"
#include "IwUIPropertySet.h"
#include "s3eKeyboard.h"
#include "s3eExt_OSExec.h"
#include "s3eExt_OSReadString.h"
#include "IwUISoftKeyboard.h"
#include "IwUITextInput.h"
#include "IwRSS.h"
#include "IwJPEG.h"
#include "IwFeedList.h"
#include "IwModalStack.h"

extern bool g_IwTextureAssertPowerOf2;

// The Base UI Element of the Application
CIwUIElement* g_RSS;
// Pointers to the Edit boxes
CIwUITextField* g_TextTitle, *g_TextURL;
// The feed list and item templates
CIwUIElement* g_Feeds, *g_ItemTemplate, *g_FeedTemplate;
// UI elements
CIwUIElement *g_View, *g_Main, *g_Edit;
// The focus elements
CIwUIElement* g_OldFocus, *g_NewFocus;
// The quit dialog
CIwUIElement* g_QuitScreen;
// The remove button
CIwUIButton* g_Remove;
// The title
CIwUILabel* g_Title;

// Resource group to hold the image textures
CIwResGroup* g_ImageTextures;

// Load the default Stylesheet
static const char* s_Stylesheets[] =
{
    "RSS-Style",            // Original Size
    "RSS-Style-x1.5",       // 1.5x Size
    "RSS-Style-x2.0",       // Double Size
    "RSS-Style-x1.5font",   // Only Font x1.5
};

enum IwUIRSSView
{
    IW_UI_RSS_MAIN,         // The main RSS screen
    IW_UI_RSS_FEED,         // Screen to view RSS feeds
    IW_UI_RSS_ADDEDIT,      // Add/Edit screen
    IW_UI_RSS_QUIT,         // The quit screen
};

//Hold the UI state
int LoadFeed = -1;
int ViewFeed = -1;
int EditFeed = -1;

bool g_Quit;

void ClearList();
void SetView(int mode);

void ClickEditFeed(CIwUIElement * pFocus)
{
    // Find the feed corresponding to the Element with focus
    EditFeed = IwGetFeedList()->ClickEdit(pFocus);

    // Hide the remove button
    g_Remove->SetVisible(true);

    // If the feed is valid, switch to edit view
    if (EditFeed >= 0)
    {
        g_Title->SetCaption("Edit Feed");
        SetView(IW_UI_RSS_ADDEDIT);
    }
}

void ClickAddFeed()
{
    // Update captions
    g_Title->SetCaption("Add New Feed");
    g_TextTitle->SetCaption("New Title");
    g_TextURL->SetCaption("http://");
    g_Remove->SetVisible(false);

    // Switch to the add feed view
    EditFeed = -1;
    SetView(IW_UI_RSS_ADDEDIT);
}

struct CIwUIHandleKey : public CIwUIElementEventHandler
{
    virtual bool FilterEvent(CIwEvent* pEvent)
    {
        if (pEvent->GetID() == IWUI_EVENT_KEY)
        {
            CIwUIEventKey* pEventKey = IwSafeCast<CIwUIEventKey*>(pEvent);
            if (!pEventKey->GetPressed())
            {
                if (pEventKey->GetKey() == s3eKeyAbsOk) // Handle OK button on device
                {
                    if (g_Main->IsVisible())
                    {
                        // Find the correct feed based on the element
                        LoadFeed = IwGetFeedList()->ClickFetch(IwGetUIView()->GetFocus());
                        if (LoadFeed >= 0) return true;
                    }
                }
                else if (pEventKey->GetKey() == s3eKeyAbsBSK) // Handle BSK
                {
                    if (g_Main->IsVisible())
                    {
                        // Edit an existing feed
                        ClickEditFeed(IwGetUIView()->GetFocus());
                        return true;
                    }
                    else if (g_View->IsVisible())
                    {
                        // Clear current list and fetch
                        ClearList();
                        IwGetFeedList()->FetchFeed(0);
                        return true;
                    }
                }
                else if (pEventKey->GetKey() == s3eKeyAbsASK) // Handle ASK
                {
                    if (g_Main->IsVisible())
                    {
                        // Add a new feed
                        ClickAddFeed();
                        return true;
                    }
                    else if (g_View->IsVisible())
                    {
                        // Cancel any active http sessions
                        g_IwRSS->Reset();

                        SetView(IW_UI_RSS_MAIN);
                        return true;
                    }
                }
            }
        }

        // Return false so that the event continues to propogate
        return false;
    }

    virtual void Clone(CIwUIElementEventHandler* pTarget) const
    {
        IW_UI_CLONE_SUPERCLASS(pTarget, CIwUIHandleKey, CIwUIElementEventHandler)
    }
};

// Controller class to handle button clicks
class CController : public CIwUIController
{
public:
    CController()
    {
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickAdd, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickEdit, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickBack, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickRefresh, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickQuit, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickFetch, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickOK, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickCancel, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickRemove, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickShowQuitScreen, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickHideQuitScreen, CIwUIElement*)
    }

private:
    void OnClickAdd(CIwUIElement* Clicked)
    {
        // Add a new feed
        ClickAddFeed();
    }

    void OnClickEdit(CIwUIElement* Clicked)
    {
        // Edit an existing feed
        ClickEditFeed(g_OldFocus);
    }

    void OnClickBack(CIwUIElement* Clicked)
    {
        // Cancel any active http sessions
        g_IwRSS->Reset();

        // Return the main screen
        SetView(IW_UI_RSS_MAIN);
    }

    void OnClickRefresh(CIwUIElement*)
    {
        // Clear current list and fetch
        ClearList();
        IwGetFeedList()->FetchFeed(0);
    }

    void OnClickShowQuitScreen(CIwUIElement*)
    {
        // Open the quit dialog
        SetView(IW_UI_RSS_QUIT);
    }

    void OnClickHideQuitScreen(CIwUIElement*)
    {
        // Hide the quit dialog
        g_QuitScreen->SetVisible(false);
        IwModalStackSetModal(NULL);
    }

    void OnClickQuit(CIwUIElement*)
    {
        // Quit the application
        s3eDeviceRequestQuit();
    }

    void OnClickFetch(CIwUIElement* pElement)
    {
        // Find the correct feed based on the clicked element
        LoadFeed = IwGetFeedList()->ClickFetch(pElement);
    }

    void OnClickOK(CIwUIElement*)
    {
        // Edit/Add feed and return to main screen
        if (EditFeed >= 0)
            IwGetFeedList()->EditFeed(EditFeed, g_TextTitle->GetCaption(), g_TextURL->GetCaption());
        else
            IwGetFeedList()->AddFeed(g_TextTitle->GetCaption(), g_TextURL->GetCaption());

        SetView(IW_UI_RSS_MAIN);
    }

    void OnClickCancel(CIwUIElement*)
    {
        // Return to main screen
        SetView(IW_UI_RSS_MAIN);
    }

    void OnClickRemove(CIwUIElement*)
    {
        // Remove feed and return to main screen
        if (EditFeed >= 0)
            IwGetFeedList()->RemoveFeed(EditFeed);

        SetView(IW_UI_RSS_MAIN);
    }

};

class CTextInput : public CIwUITextInput
{
public:
    CTextInput()
    {
        // Use on-screen keyboard for iPhone.
        bool forceOnscreenKeyboard = s3eExtOSReadStringAvailable() != 0;
        if (forceOnscreenKeyboard)
        {
            IwGetUITextInput()->SetEditorMode(CIwUITextInput::EDITOR_KEYBOARD);
        }
    }

protected:
    virtual void SetSoftKeyboardModal(CIwUISoftKeyboard* pSoftkeyboard)
    {
        if (pSoftkeyboard)
        {
            // Prevent the UI from rendering the dialog behind the fullscreen keyboard
            if(!pSoftkeyboard->UsingInlineEditor())
            {
                g_RSS->SetVisible(false);
                g_Edit->SetVisible(false);
            }
        }
        else
        {
            g_RSS->SetVisible(true);

            if(IwGetModalStack()->Contains(g_Edit))
                g_Edit->SetVisible(true);
        }

        IwModalStackSetModal(pSoftkeyboard);
    }
};

void ClearList()
{
    // Clear all existing items
    for (int i=g_Feeds->GetNumChildren()-1;i>=0;--i)
    {
        CIwUIElement * child = g_Feeds->GetChild(i);
        g_Feeds->RemoveChild(child);
        delete child;
    }

    // Destroy all previously uploaded images
    IwGetResManager()->DestroyGroup(g_ImageTextures);
    g_ImageTextures = new CIwResGroup;
    IwGetResManager()->AddGroup(g_ImageTextures);
}

// Add News items to the Scrollable View
void AddRSSEntry(const char* title, const char* description)
{
    if (ViewFeed >= 0)
    {
        IwGetUIAnimManager()->StopAnim(g_Feeds);

        ClearList();
        ViewFeed = -1;
    }

    // Instantiate the new item
    CIwUIElement* pItem = g_ItemTemplate->Clone();

    // Set name/value
    IwSafeCast<CIwUILabel*>(pItem->GetChildNamed("Title"))->SetCaption(title);
    IwSafeCast<CIwUILabel*>(pItem->GetChildNamed("Description"))->SetCaption(description);

    // Generate a unique name for the new item
    static int32 itemnum = 0;
    char buf[20];
    sprintf(buf, "item_%ld", itemnum++);
    pItem->SetName(buf);

    CIwUILayoutVertical* pLayout = (CIwUILayoutVertical*)g_Feeds->GetLayout();
    pLayout->AddElement(pItem);
}

// Add an image to a news item
void AddRSSImage(const char* title, const char* buf, int len)
{
    // Loop through the news items looking for the correct title
    for (int i=0;i<g_Feeds->GetNumChildren();i++)
    {
        CIwUILabel * label = (CIwUILabel*)g_Feeds->GetChild(i)->GetChildNamed("Title", true, true);

        if (label && !strcmp(title, label->GetCaption()))
        {
            // Create a texture from the downloaded image.
            CIwTexture * ImageTex;
            if (len == 0)
            {
                // The buf is a filename, load from file
                ImageTex = new CIwTexture();
                ImageTex->LoadFromFile(buf);
                ImageTex->Upload();
            }
            else
            {
                // If the buf has a length, load it from memory as a JPEG
                ImageTex = new CIwTexture();
                JPEGTexture(buf, len, *ImageTex);
                ImageTex->Upload();
            }

            // Add the texture to a group so it can be freed later
            g_ImageTextures->AddRes(IW_GX_RESTYPE_TEXTURE, ImageTex);

            CIwUIElement * vertical = (CIwUIElement*)g_Feeds->GetChild(i)->GetChildNamed("Labels");
            CIwUIImage* pImage = new CIwUIImage;
            pImage->SetName("Image");
            pImage->SetProperty("texture", ImageTex);
            pImage->SetSizeToContent(true);

            vertical->GetLayout()->AddElement(pImage, IW_UI_ALIGN_LEFT, IW_UI_ALIGN_MIDDLE, CIwSVec2(4,4));
            return;
        }
    }
}

void SetView(int mode)
{
    if (mode == IW_UI_RSS_MAIN)
    {
        // Reset feed
        ViewFeed = -1;

        // Set the title
        g_Title->SetCaption("My Feeds");

        // Hide all other screens
        g_QuitScreen->SetVisible(false);
        g_Edit->SetVisible(false);
        g_View->SetVisible(false);

        IwGetUIAnimManager()->StopAnim(g_Feeds);

        // Update the list of feeds
        IwGetFeedList()->Update();
        IwModalStackSetModal(NULL);
        g_Main->SetVisible(true);
    }
    else if (mode == IW_UI_RSS_FEED)
    {
        // Switch to the feed view
        g_Edit->SetVisible(false);
        g_Main->SetVisible(false);
        g_View->SetVisible(true);
        g_IwRSS->m_Progress = 0;

        {
            // Play animation
            IwGetUIAnimManager()->StopAnim(g_Feeds);
            IwGetUIAnimManager()->PlayAnim("slideAnim", g_Feeds, false);
        }

    }
    else if (mode == IW_UI_RSS_ADDEDIT)
    {
        // Display the add/edit dialog
        g_Main->SetVisible(false);
        g_Edit->SetVisible(true);

        IwModalStackSetModal(g_Edit);

        {
            // Play an anim on this element
            IwGetUIAnimManager()->StopAnim(g_Edit);
            IwGetUIAnimManager()->PlayAnim("popupAnim", g_Edit, true);
        }
    }
    else if (mode == IW_UI_RSS_QUIT)
    {
        // Display the quit dialog
        g_QuitScreen->SetVisible(true);

        IwModalStackSetModal(g_QuitScreen);

        {
            // Play an anim on this element
            IwGetUIAnimManager()->StopAnim(g_QuitScreen);
            IwGetUIAnimManager()->PlayAnim("popupAnim", g_QuitScreen, true);
        }
    }
}

#ifdef IW_DEBUG
void DebugSwitchStylesheet(CIwResGroup* pResGroup)
{
    if(IwGetModalStack()->IsEmpty()) // Avoid changing style during text entry
    {
        // Cycle Stylesheets
        if(s3eKeyboardGetState(s3eKeyS))
        {
            CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[0], IW_UI_RESTYPE_STYLESHEET);
            IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            IwGetUIView()->Layout();
        }
        else if(s3eKeyboardGetState(s3eKeyM))
        {
            CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[1], IW_UI_RESTYPE_STYLESHEET);
            IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            IwGetUIView()->Layout();
        }
        else if(s3eKeyboardGetState(s3eKeyL))
        {
            CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[2], IW_UI_RESTYPE_STYLESHEET);
            IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            IwGetUIView()->Layout();
        }
        else if(s3eKeyboardGetState(s3eKeyF))
        {
            CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[3], IW_UI_RESTYPE_STYLESHEET);
            IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            IwGetUIView()->Layout();
        }
    }
}
#endif

S3E_MAIN_DECL void IwMain()
{
    g_IwTextureAssertPowerOf2 = false;
    g_Quit = false;

    // Initialize Airplay
    IwUIInit();

    {
        // Instantiate the view and controller singletons.
        CIwUIView view;
        CController controller;
        CIwUIHandleKey key;
        CIwModalStack modalstack;
        CIwFeedList feedlist;

        // Load the resource group
        CIwResGroup* pResGroup = IwGetResManager()->LoadGroup("IwUIRSS.group");

        {
            // Cut-off sizes for stylesheet scale decision
            const int32 area_0 = (320*480); // Smaller/Equal than this uses small style
            const int32 area_1 = (800*480); // Larger/Equal than this uses large style
            const int32 actual_area = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT)
                                     *s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
            int32 style_id = 1;
            if(actual_area<=area_0)
                style_id = 0;
            else
            if(actual_area>=area_1)
                style_id = 2;

            CIwResource* pResource = pResGroup->GetResNamed(s_Stylesheets[style_id], IW_UI_RESTYPE_STYLESHEET);
            IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
        }

        // Create the main UI
        g_RSS = CIwUIElement::CreateFromResource("RSS");
        view.AddElement(g_RSS);
        view.AddElementToLayout(g_RSS);

        // Create the edit dialog
        g_Edit = CIwUIElement::CreateFromResource("Edit");
        view.AddElement(g_Edit);
        view.AddElementToLayout(g_Edit);

        // Create the quit dialog
        g_QuitScreen = CIwUIElement::CreateFromResource("Quit");
        view.AddElement(g_QuitScreen);
        view.AddElementToLayout(g_QuitScreen);

        // Find the feed list
        g_Feeds = g_RSS->GetChildNamed("Feeds");

        // Find the item templates
        g_FeedTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("FeedItemTemplate", "CIwUIElement");
        g_ItemTemplate = (CIwUIElement*)IwGetResManager()->GetResNamed("RSSItemTemplate", "CIwUIElement");

        // Get the progress bar
        CIwUIProgressBar* pProgress = (CIwUIProgressBar*)g_RSS->GetChildNamed("Progress");

        // Find the title
        g_Title = (CIwUILabel*)g_RSS->GetChildNamed("TitleLabel");

        // Find the bottom panel and its contents
        g_View = g_RSS->GetChildNamed("View");
        g_Main = g_RSS->GetChildNamed("Main");

        // Find the elements inside the edit dialog
        g_TextTitle = (CIwUITextField*)g_Edit->GetChildNamed("TextFieldTitle");
        g_TextURL = (CIwUITextField*)g_Edit->GetChildNamed("TextFieldURL");
        g_Remove = (CIwUIButton*)g_Edit->GetChildNamed("Remove");

        // Find the edit button
        CIwUIButton* pEditButton = (CIwUIButton*)g_RSS->GetChildNamed("ButtonEdit");

        // Read Feed List by Serialisation
        if (IwSerialiseExists("feeds.bin"))
        {
            IwSerialiseOpen("feeds.bin", true);
            IwGetFeedList()->Serialise();
            IwSerialiseClose();
        }

        // Instantiate the RSS class and texture group
        g_IwRSS = new CIwRSS();
        g_ImageTextures = new CIwResGroup;

        // Handle key presses
        g_RSS->AddEventHandler(&key);

        // Update the list of feeds
        IwGetFeedList()->Update();

        // Create text input singleton
        CTextInput textinput;
        textinput.CreateSoftKeyboard();

        // Give the quit button focus by default
        CIwUIElement* pFocusElement = g_RSS->GetChildNamed("ButtonQuit");
        IwGetUIView()->RequestFocus(pFocusElement);

        int32 updateTime = 0;
        while(!g_Quit)
        {
            int64 start = s3eTimerGetMs();

            IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

            if (LoadFeed != -1)
            {
                // View the feed
                SetView(IW_UI_RSS_FEED);

                // Begin fetching the feed
                IwGetFeedList()->FetchFeed(LoadFeed);
                ViewFeed = 0;

                LoadFeed = -1;
            }

            // Update the RSS object
            g_IwRSS->Update();

            // Set the value on the progress bar
            pProgress->SetProgress(g_IwRSS->m_Progress);

            // Update the current focus
            g_OldFocus = g_NewFocus;
            g_NewFocus = IwGetUIView()->GetFocus();
            if (g_NewFocus == pEditButton)
                g_NewFocus = g_OldFocus;

            // Enable the edit button
            if (IwGetFeedList()->GetFeed(g_NewFocus) >= 0)
                pEditButton->SetEnabled(true);
            else
                pEditButton->SetEnabled(false);

            IwGetUIController()->Update();

            IwGetUIView()->Update(updateTime);
            IwGetUIView()->Render();

            IwGxFlush();
            IwGxSwapBuffers();
            s3eDeviceYield();
            s3eKeyboardUpdate();
            s3ePointerUpdate();

            // Attempt frame rate
            int32 frameTime = 1000 / 30; // 30fps
            int32 tickTime = (int32)(s3eTimerGetMs() - start);

            if (tickTime < frameTime)
            {
                int32 yield = frameTime - tickTime;
                yield = MAX(0, MIN(yield, 1000));
                s3eDeviceYield(yield);
            }

            updateTime = (int32)(s3eTimerGetMs() - start);
            updateTime = MAX(frameTime, MIN(updateTime, 1000));

            #ifdef IW_DEBUG
            DebugSwitchStylesheet(pResGroup);
            #endif

            g_Quit |= (s3eDeviceCheckQuitRequest()!=0);
        }

        // Save Event Date List by Serialisation
        IwSerialiseOpen("feeds.bin", false);
        IwGetFeedList()->Serialise();
        IwSerialiseClose();

        // Destroy the resource group
        IwGetResManager()->DestroyGroup(pResGroup);
        IwGetResManager()->DestroyGroup(g_ImageTextures);

        // Detach event handler
        g_RSS->RemoveEventHandler(&key);

        // Delete the RSS object
        delete g_IwRSS;
    }

    // Terminate the IwUI module
    IwUITerminate();
}


Airplay API Reference: IwUI Signals and Slots Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Signals and Slots Example >

IwUI Signals and Slots Example

The following example demonstrates use of signals and slots to data drive functionality.

The main classes used to achieve this are:

  • CIwUIElement

The main functions used to achieve this are:

  • IW_UI_CREATE_HANDLER_SLOT1

This example demonstrates the connection of signals to slots. A slot is a single action that an element knows how to perform. A signal is a means of attaching an event (normally one originating below it in the UI hierarchy) to a slot. Signals and slots can be preferable to normal event handling because they are more explicit.

In this case a custom handler is created (CWanderingElement) that knows how to move itself in 2 axes. It 'advertises' these movements as slots.

In data, button presses can be attached to slots of elements. For example:

    CIwUIButton
    {
        OnButtonClick { OnClickLeft }
    }

The example instantiates a control panel element that contains 4 buttons which are configured to send signals to the 4 slots in the wandering handler.

The advantages of slots and signals can be seen by contrasting this approach with a more conventional event handing approach. The CWanderingHandler could override the event handling method and invoke an action based on a custom element property. This would require rather more code.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUISignals
//-----------------------------------------------------------------------------

// @}

// Includes
#include "IwGx.h"
#include "IwUI.h"

//The Wandering Handler class provides slots (signal handlers) to move the element
//it is attached to around.
class CWanderingHandler : public CIwUIElementEventHandler
{
public:
    IW_MANAGED_DECLARE(CWanderingHandler)

private:
    // CIwUIElementEventHandler virtuals
    virtual void Activate(bool val)
    {
        CIwUIElementEventHandler::Activate(val);

        if (val)
        {
            //Add slots. Certain elements generate
            //signals which can be attached to these slots in data.
            IW_UI_CREATE_HANDLER_SLOT1(this, CWanderingHandler, OnClickUp, CIwUIElement*);
            IW_UI_CREATE_HANDLER_SLOT1(this, CWanderingHandler, OnClickDown, CIwUIElement*);
            IW_UI_CREATE_HANDLER_SLOT1(this, CWanderingHandler, OnClickLeft, CIwUIElement*);
            IW_UI_CREATE_HANDLER_SLOT1(this, CWanderingHandler, OnClickRight, CIwUIElement*);
        }
    }

    virtual void Clone(CIwUIElementEventHandler* pTarget) const
    {
        IW_UI_CLONE_SUPERCLASS(pTarget, CWanderingHandler, CIwUIElementEventHandler)
    }

    //Move the control up.
    void OnClickUp(CIwUIElement*)
    {
        CIwUIElement* pElement = GetElement();
        pElement->SetPos(pElement->GetPos() + CIwVec2(0, -10));
    }
    //Move the control down.
    void OnClickDown(CIwUIElement*)
    {
        CIwUIElement* pElement = GetElement();
        pElement->SetPos(pElement->GetPos() + CIwVec2(0, 10));
    }
    //Move the control left.
    void OnClickLeft(CIwUIElement*)
    {
        CIwUIElement* pElement = GetElement();
        pElement->SetPos(pElement->GetPos() + CIwVec2(-10, 0));
    }
    //Move the control right.
    void OnClickRight(CIwUIElement*)
    {
        CIwUIElement* pElement = GetElement();
        pElement->SetPos(pElement->GetPos() + CIwVec2(10, 0));
    }

};
IW_MANAGED_IMPLEMENT_FACTORY(CWanderingHandler)

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();

    //Class factory only really required if we attached the handler in data
    IW_CLASS_REGISTER(CWanderingHandler);

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUISignals.group");

    //Set the default style sheet
    CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
    IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));

    //Find the movement controls template
    CIwUIElement* pMovementTemplate = (CIwUIElement*)
        IwGetResManager()->GetResNamed("Vertical", "CIwUIElement");

    //And instantiate it
    for(uint16 i = 0; i < 2; i++)
    {
        // Clone the movement buttons
        CIwUIElement* pControl = pMovementTemplate->Clone();

        //Generate a unique name for each control
        char buf[20];
        sprintf(buf, "Element%d", i);
        pControl->SetName(buf);

        //Set the initial position
        pControl->SetPos(CIwVec2(i*100, 70 + i * 100));

        //Attach movement handler
        //This could alternatively be done in data.
        pControl->AddEventHandler(new CWanderingHandler);

        //Add the control to the root element. NB. It is not added to the layout
        //because it wants to dictate its own position.
        IwGetUIView()->AddElement(pControl);
    }
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IW_CLASS_REMOVE(CWanderingHandler);
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();
    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: IwUI Widgets Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Widgets Example >

IwUI Widgets Example

The following example demonstrates some of the basic widgets on a dialog.

The main classes used to achieve this are:

  • CIwUIView

  • CIwUIController

  • CIwUIElement

  • CIwUIButton

  • CIwUILabel

  • CIwUITabBar

  • CIwUITextField

  • CIwUIProgressBar

  • CIwUISlider

  • CIwUICheckBox

  • CIwUIAlertDialog

  • CIwUIAnimation

The main functions used to achieve this are:

  • IwUIInit()

  • IwUITerminate();

  • IW_UI_CREATE_VIEW_SLOT1

This example demonstrates the loading and instantiation of some basic widgets.

The widgets are layed out in the .ui file, instantiated and added to CIwUIView. Button clicks are handled by subclassing the CIwUIController and adding view slots.

The CIwUITextInput is used to handle text input to the text field on the dialog and can be subclassed to provide functionality.

A confirmation alert dialog is displayed when a user tries to quit the application. This displays a basic animation on the buttons that is created by the animation manager.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIWidgets
//-----------------------------------------------------------------------------

// @}
//
// Library includes
#include "IwGx.h"
#include "IwGxFont.h"
#include "IwUI.h"

extern bool g_IwTextureAssertPowerOf2;

bool g_Quit;
CIwUIElement* g_QuitScreen;
CIwUIElement* g_AnimQuitButton;

class CController : public CIwUIController
{
public:
    CController()
    {
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickLaunchKeyboard, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickLaunchNumpad, CIwUIElement*)

        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickShowQuitScreen, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickHideQuitScreen, CIwUIElement*)
        IW_UI_CREATE_VIEW_SLOT1(this, "CController", CController, OnClickQuit, CIwUIElement*)

        IW_UI_CREATE_VIEW_SLOT2(this, "CController", CController, OnRadioTextEntryMode, CIwUIElement* , int16 )
    }

private:
    void OnClickLaunchKeyboard(CIwUIElement*)
    {
        IwGetUITextInput()->SetEditorMode(CIwUITextInput::EDITOR_KEYBOARD);
        IwGetUITextInput()->DoTextEntry(NULL,"");
    }

    void OnClickLaunchNumpad(CIwUIElement*)
    {
        IwGetUITextInput()->SetEditorMode(CIwUITextInput::EDITOR_NUMPAD);
        IwGetUITextInput()->DoTextEntry(NULL,"");
    }

    void OnClickShowQuitScreen(CIwUIElement*)
    {
        g_QuitScreen->SetVisible(true);
        IwGetUIView()->SetModal(g_QuitScreen);

        IwGetUIAnimManager()->PlayAnim("quitAnim", g_AnimQuitButton, true);
    }

    void OnRadioTextEntryMode(CIwUIElement*, int16 mode)
    {
        IwGetUITextInput()->SetEditorMode((CIwUITextInput::EditorMode)mode);
    }

    void OnClickHideQuitScreen(CIwUIElement*)
    {
        g_QuitScreen->SetVisible(false);
        IwGetUIView()->SetModal(NULL);

        IwGetUIAnimManager()->StopAnim(g_AnimQuitButton, true);
    }

    void OnClickQuit(CIwUIElement*)
    {
        g_Quit = true;
    }
};

S3E_MAIN_DECL void IwMain()
{
    g_IwTextureAssertPowerOf2 = false;
    g_Quit = false;

    while(!g_Quit)
    {
        // Initialize Airplay
        IwUIInit();

        {
            CIwUIView view;
            CController controller;

            CIwResGroup* pResGroup = IwGetResManager()->LoadGroup("IwUIWidgets.group");

            {
                CIwResource* pResource = IwGetResManager()->GetResNamed("iwui", IW_UI_RESTYPE_STYLESHEET);
                IwGetUIStyleManager()->SetStylesheet(IwSafeCast<CIwUIStylesheet*>(pResource));
            }

            CIwUIElement* pWidgets = CIwUIElement::CreateFromResource("Widgets");
            view.AddElement(pWidgets);
            view.AddElementToLayout(pWidgets);

            CIwUIElement* pQuitScreen = CIwUIElement::CreateFromResource("quit_screen");
            CIwUIElement* pAnimElement = pQuitScreen->GetChildNamed("alert_dialog");

            g_QuitScreen = pQuitScreen;
            g_AnimQuitButton = pAnimElement;

            pQuitScreen->SetVisible(false);
            view.AddElement(pQuitScreen);
            view.AddElementToLayout(pQuitScreen);

            CIwUITextInput textinput;
            textinput.CreateSoftKeyboard();

            // Ensure layout is valid prior to setting focus element
            view.Layout();

            // Pick an element to have focus by default
            CIwUIElement* pFocusElement = pWidgets->GetChildNamed("Button-Plain");
            IwGetUIView()->RequestFocus(pFocusElement);

            // Get the progress bar
            CIwUIProgressBar* pProgress = (CIwUIProgressBar*)pWidgets->GetChildNamed("Progress");

            bool restart = false;
            uint64 lastTime = s3eTimerGetMs();
            while(!g_Quit && !restart)
            {
                IwGxClear(IW_GX_COLOUR_BUFFER_F | IW_GX_DEPTH_BUFFER_F);

                // Test Progress Update
                {
                    static int32 progress = 0;
                    progress = (progress+4)%(1<<12);
                    pProgress->SetProgress(progress);
                }

                IwGetUIController()->Update();

                // Calculate an update time step.
                uint64 currentTime = s3eTimerGetMs();
                int32 updateTime = currentTime > lastTime ?
                    MIN((int32)(currentTime - lastTime), 1000) : 0;
                lastTime = currentTime;

                view.Update(updateTime);
                view.Render();

                IwGxFlush();
                IwGxSwapBuffers();
                s3eDeviceYield();
                s3eKeyboardUpdate();
                s3ePointerUpdate();

                g_Quit |= (s3eDeviceCheckQuitRequest()!=0);
            }

            // Ensure quit button animation is stopped
            IwGetUIAnimManager()->StopAllAnims();

            // Destroy ui resources
            IwGetResManager()->DestroyGroup(pResGroup);
        }

        // Terminate Airplay
        IwUITerminate();
    }
}


Airplay API Reference: IwUI Animation Example

Airplay API Reference > IwUI API Documentation > IwUI Examples > IwUI Animation Example >

IwUI Animation Example

The following example demonstrates playing animations on an element in response to element events.

The main classes used to achieve this are:

  • CIwUIElementEventHandler

  • CIwUIAnimManager

The main functions used to achieve this are:

  • CIwUIAnimManager::PlayAnim
  • CIwUIAnimManager::SetObserver
  • CIwUIAnimManager::StopAnim

This example defines a custom CIwUIElementEventHandler derived class. This is attached to an element in data. In response to focus events, the handler controls the playing on animations on another element. The animations are also defined in data. An animation observer is also installed. The obsever waits until an animation finishes before exiting the application.

The following graphic illustrates the example output.

/*
 * This file is part of the Airplay SDK Code Samples.
 *
 * Copyright (C) 2001-2009 Ideaworks Labs.
 * All Rights Reserved.
 *
 * This source code is intended only as a supplement to Ideaworks Labs
 * Development Tools and/or on-line documentation.
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
 * PARTICULAR PURPOSE.
 */

//-----------------------------------------------------------------------------
// ExampleIwUIAnimatior
//-----------------------------------------------------------------------------

// @}

#include "IwGx.h"
#include "IwUI.h"

// Class to catch button events to play an animation.
// Installs an oberserver on the animation to play a second animation when
// the first has finished.
class CButtonEventHandler : public CIwUIElementEventHandler,
    public IIwUIAnimatorObserver
{
public:
    IW_MANAGED_DECLARE(CButtonEventHandler)

    // IwParseable virtuals
    virtual bool ParseAttribute(CIwTextParserITX* pParser, const char* pAttrName)
    {
        return CIwUIElementEventHandler::ParseAttribute(pParser, pAttrName);
    }

    // IwDecomposable virtuals
    virtual void DecomposeAttributes(CIwTextDecomposer* pDecomposer) const {}
    virtual void DecomposeChildren(CIwTextDecomposer* pDecomposer) const {}

    // IIwUIEventHandler virtuals
    virtual bool HandleEvent(CIwEvent* pEvent)
    {
        if (pEvent->GetID() == IWUI_EVENT_BUTTON)
        {
            CIwUIElement* pElement = GetElement();
            CIwUIAnimation* pAnim = GetAnimation(pElement, true);

            IwGetUIAnimManager()->StopAnim(pElement);
            uint32 handle = IwGetUIAnimManager()->PlayAnim(pAnim, pElement);
            IwGetUIAnimManager()->SetObserver(handle, this);
        }

        // Allow event to propagate
        return false;
    }

    // IIwUIAnimationObserver
    virtual void NotifyProgress(CIwUIAnimator* pAnimator)
    {
    }

    virtual void NotifyStopped(CIwUIAnimator* pAnimator)
    {
        CIwUIElement* pElement = GetElement();

        // Fade in animation has finished or been stopped.
        // Play fade out, blending from current state
        CIwUIAnimation* pAnim = GetAnimation(pElement, false);
        IwGetUIAnimManager()->PlayAnim(pAnim, pElement, false, false, 1000);
    }

protected:
    virtual void Clone(CIwUIElementEventHandler* pTarget) const
    {
        IW_UI_CLONE_SUPERCLASS(pTarget, CButtonEventHandler, CIwUIElementEventHandler)
    }

private:
    CIwUIAnimation* GetAnimation(CIwUIElement* pElement, bool inNotOut)
    {
        CIwUIAnimation* pAnimation = NULL;
        pElement->GetProperty(inNotOut ? "animIn" : "animOut", pAnimation);
        return pAnimation;
    }
};
IW_MANAGED_IMPLEMENT_FACTORY(CButtonEventHandler)

void ExampleInit()
{
    //Initialise the IwUI module
    IwUIInit();
    IW_CLASS_REGISTER(CButtonEventHandler);

    //Instantiate the view and controller singletons.
    //IwUI will not instantiate these itself, since they can be subclassed to add functionality.
    new CIwUIController;
    new CIwUIView;

    //Load the hello world UI
    IwGetResManager()->LoadGroup("IwUIAnimation.group");

    // Create main element
    CIwUIElement* pElement = CIwUIElement::CreateFromResource("Animation");
    IwGetUIView()->AddElementToLayout(pElement);
}
//-----------------------------------------------------------------------------
void ExampleShutDown()
{
    // Stop all animations
    IwGetUIAnimManager()->StopAllAnims();

    // Destroy the view and controller singletons.
    delete IwGetUIController();
    delete IwGetUIView();

    //Terminate the IwUI module
    IW_CLASS_REMOVE(CButtonEventHandler);
    IwUITerminate();
}
//-----------------------------------------------------------------------------
bool ExampleUpdate()
{
    //Update the controller (this will generate control events etc.)
    IwGetUIController()->Update();

    //Update the view (this will do animations etc.) Airplay SDK's example framework has a fixed
    //framerate of 20fps, so we pass that duration to the update function.
    IwGetUIView()->Update(1000/20);

    return true;
}
//-----------------------------------------------------------------------------
void ExampleRender()
{
    //Render the UI
    IwGetUIView()->Render();

    //Flush IwGx
    IwGxFlush();

    //Display the rendered frame
    IwGxSwapBuffers();
}


Airplay API Reference: Data Structures

Airplay API Reference > Data Structures >

Airplay API Reference Data Structures

Here are the data structures with brief descriptions:
CIw2DFont |
CIw2DImage |
CIw2DSurface |
CIwAnim |
CIwAnimBlendSource |
CIwAnimBone |
CIwAnimPlayer |
CIwAnimSkel |
CIwAnimSkin |
CIwArray< X, A, REALLOCATE > |
CIwAutoFile |
CIwBBoxT< V > |
CIwBuffer::ByteProxy |
CIwColour |
CIwFBBox | Double-precision float axis-aligned bounding box
CIwFMat |
CIwFMat2D |
CIwFQuat |
CIwFSphere | Floating-point sphere:
CIwFVec2 |
CIwFVec3 |
CIwFVec4 |
CIwGxFontPreparedData |
CIwGxShaderTechnique |
CIwGxShaderUniform |
CIwGxStream |
CIwGxSurface |
CIwHTTP |
CIwImage |
CIwList< X > |
CIwList< X >::Store |
CIwListNode |
CIwManaged |
CIwManagedList |
CIwMat |
CIwMat2D |
CIwMaterial |
CIwMenu |
CIwMenuItem |
CIwMenuItemDisplayBool |
CIwMenuItemDisplayFloat |
CIwMenuItemDisplayInt16 |
CIwMenuItemDisplayInt32 |
CIwMenuItemDisplayInt8 |
CIwMenuItemDisplayUInt16 |
CIwMenuItemDisplayUInt32 |
CIwMenuItemDisplayUInt8 |
CIwMenuItemEditAngle |
CIwMenuItemEditBool |
CIwMenuItemEditEnum |
CIwMenuItemEditFixed |
CIwMenuItemEditFlags |
CIwMenuItemEditFloat |
CIwMenuItemEditInt16 |
CIwMenuItemEditInt32 |
CIwMenuItemEditInt8 |
CIwMenuItemEditUInt16 |
CIwMenuItemEditUInt32 |
CIwMenuItemEditUInt8 |
CIwMenuItemManagedList | Debug menu: all items in a managed list
CIwMenuItemString |
CIwMenuItemTitle |
CIwMenuManager |
CIwModel |
CIwModelBlock |
CIwModelExt |
CIwModelExtPos |
CIwModelExtSelSet |
CIwModelExtSelSetEdge |
CIwModelExtSelSetFace |
CIwModelExtSelSetVert |
CIwModelExtSphere |
CIwPlane | Fixed-point plane: 3-vector normal and constant
CIwProperty< Type > | Templated class to used by CIwPropertySet to store data of different types. The CIwProperty owns the data it contains and provides an interface for accessing it, as well as parsing, serialise and resolving the data
CIwPropertyBase | Base class for CIwProperty. Used by CIwPropertySet to store a collection of properties
CIwPropertyDataType< Type > | Templated class containing static methods used by CIwProperty. Specialisations of the members of this class must be provided for each data type used with the property set system
CIwPropertyDefine | Used to by CIwPropertySet to map a property name to a property data type. For example a property define maps the property name "colour" to the data type "CIwColour". A property of the correct type can be created using CreateProperty which uses the property factory
CIwPropertyList< Type > | Templated list property (facilitating variable-length properties)
CIwPropertySet | A property set is used to store and retrieve a collection of properties derived from CIwPropertyBase. The property set can also have a parent property set
CIwPropertySetBinding | Used to allow binding properties to an external source
CIwPropertyString | Variable-length string class, shared (ref-counted) representation
CIwPropertyTypeMap< Key > | Allows mapping between a type used to access property data and the the type used to store a particular property. This can be useful when getting or setting properties on a property set via CIwPropertySet::Get and CIwPropertySet::Set respectively
CIwQuat |
CIwRect |
CIwRect32 |
CIwResGroup |
CIwResHandler |
CIwResHandlerANIM |
CIwResHandlerGEO |
CIwResHandlerGROUP |
CIwResHandlerImage |
CIwResHandlerITX |
CIwResHandlerMTL |
CIwResHandlerSKEL |
CIwResHandlerSKIN |
CIwResList |
CIwResManager |
CIwResTemplate |
CIwResTemplateANIM |
CIwResTemplateGEO |
CIwResTemplateGROUP |
CIwResTemplateImage |
CIwResTemplateMTL |
CIwResTemplateSKEL |
CIwResTemplateSKIN |
CIwSphereT< V, R > | Fixed-point sphere: templated origin and radius types
CIwSQuat |
CIwString< N > |
CIwSVec2 |
CIwSVec3 |
CIwSVec4 |
CIwTextDecomposer | Class that can be used to write out an object hierarchy, and its properties, to text format
CIwTextParserITX |
CIwTexture |
CIwUIAlertDialog | Alert dialog box, with one or more buttons
CIwUIAnimation | Animation resource. Contains a list of keyframes ordered by time
CIwUIAnimator | Represents an animation playing on an element
CIwUIAnimData | Provides animation data to animated elements
CIwUIAnimDataLocator | Interface for obtaining animation data by property name. Iterates over keyframe data to find corresponding properties
CIwUIAnimDataType< Type > | Templated class to interpolate a type
CIwUIAnimKeyFrame | Animation key frame. Animation resources are made up of key frames. Each keyframe specifies the value of properties at a particular time through an animation
CIwUIAnimManager | Animation manager singleton. Provides an interface for playing and controlling an animation on an element. Updated by CIwUIView
CIwUIButton | Button widget. If the user touches the button, or presses ok whilst the button has focus, it will generate a ButtonPress event with itself as the source
CIwUICheckbox | Check box element. Has an on / off graphic [+ label] [+ background]
CIwUIColour | Derived from CIwColour. Adds functionality such as parsing
CIwUIController | UI event-handling singleton
CIwUIDrawableBorder | Draws a border from a single image + corner width (by drawing 9 separate images, the corners being drawn 1:1 (using the corner size to calculate UVs), the other 5 being drawn stretched to fit the specified size)
CIwUIDrawableImage | Drawable wrapper for a simple image
CIwUIDrawableText | Drawable wrapper for the state required to draw some text via Gx
CIwUIElement | Base class for all ui widgets. Also acts a frame within which other elements can be contained
CIwUIElementEventHandler | Event handler which can be attached to an element in data
CIwUIElementItem | Used as a wrapper around CIwUIElements, which are then wrapped by a CIwUILayoutItem, before being added into a CIwUILayout
CIwUIElementPtr | Smart(ish) point which becomes NULL when the element it points to is destroyed
CIwUIEventAlertDialogButton | An alert dialog button was pressed
CIwUIEventButton | CIwUIButton pressed event
CIwUIEventCheckbox | Checkbox on / off state toggle event
CIwUIEventClick | S3ePointer button press event
CIwUIEventFocus | Keyboard focus change event
CIwUIEventKey | S3eKey press / release event
CIwUIEventLayout | Layout of the specified element has just been updated
CIwUIEventPointerEnter | Event fired when the pointer enters an element (as determined by the element's intersect function)
CIwUIEventPointerLeave | Event fired when the pointer leaves an element (as determined by the element's intersect function)
CIwUIEventPointerMove | Pointer move event
CIwUIEventRadioButton | CIwUIRadioButton selected event
CIwUIEventSlider | Value of slider changed
CIwUIEventSoftKey | SoftKey pressed/released event
CIwUIEventTabBarButton | A tab bar button was pressed
CIwUIEventTextInput | Text input event
CIwUIFocusHandler | Base class for focus handlers. A focus handle can be attached to an element to respond to input and control which of the elements children has input focus
CIwUIFocusHandler2D | Concrete implementation of a focus handler which 'intelligently' moves focus based on 2D position + pressed direction
CIwUIFocusHandlerTab | Concrete implementation of a focus handler which simply moves focus based on element order
CIwUIGraphics | Provides rendering functionality
CIwUIHoldingPtr< Type > | Smart pointer which manages destruction of its owned object, useful for pointer member management
CIwUIImage | Element used to display an image. Has no interaction
CIwUILabel | Read-only text widget - single or multi-line. Has no interaction
CIwUILayout | Base class for all layout types
CIwUILayoutForm | Form type layout. Form has a notional size. Items are positioned and size relative to the forms size. Item's can be placed relative to other items used as guides
CIwUILayoutGrid | Grid type layout. Organises contained items on a grid
CIwUILayoutHorizontal | Simple layout which lays out elements in a single row
CIwUILayoutItem | UI base class to support layout. Interface supports layout, cloning & parentage
CIwUILayoutItemContainer | Used as a container around CIwUILayoutItem added to a CIwUILayout. Contains additional data such as alignment for the item. Also provides simple caching system
CIwUILayoutSpacer | Layout item to add space into a layout
CIwUILayoutVertical | Simple layout which lays out elements in a single column
CIwUIPositionPolicy | Encapsulates element positional preference
CIwUIProgressBar | 0-100% style progress bar
CIwUIPropertySet | Property set which uses a style to resolve its parent. This extends CIwPropertySet to support style sheets
CIwUIRadioButton | Button with on and off states. To be placed within a tab bar
CIwUIRect | Derived from CIwRect. Adds functionality such as intersection
CIwUIScrollableView | Element which allows scrolling across content whose total extents exceed the size of the scrollable view widget, either via explicit interaction with the scrollbars(??), else via gestures in the main content area
CIwUISizePolicy | Encapsulates element size restraints. Hint is only applied when result would otherwise be unbounded
CIwUISlider | Slider widget. If the user drags the button, or presses left/right whilst the slider has focus, it will generate a Slider event with itself as the source
CIwUISoftKeyboard | Interface element to display touchable soft keyboard
CIwUISoftKeyPosition | Container for a softkey element. Element is positioned next to hardware softkeys buttons on device. If device changes orientation, the contained elements will move into the correct corners to follow the softkeys
CIwUIStyle | A named style, wrapped up in an object for added semantics
CIwUIStyleManager | Singleton which stores the currently-set stylesheet, and through which style property sets should be queried. If no stylesheet is set, styles are mapped to property sets by direct lookup of same-named property sets through the resource system
CIwUIStylesheet | Maps styles to property sets, facilitating the switching of property sets globally
CIwUITabBar | Container for a set of radio buttons. One button is always down, the others are always up
CIwUITable | This is a specialisation of scrollable view which contains a number of row items, and which only allows vertical scrolling
CIwUITextField | Editable text widget. When selected, this element activates modal text entry
CIwUITextInput | Text Input Manager. Handles various forms of text input, including keyboard, on-screen soft keyboard, and numeric pad texting
CIwUIView | IwUI singleton which handles high-level functionality relating to the visual representation of elements - rendering, intersection testing, focus and styles
CIwUncopyable |
CIwURI |
CIwUriEscape | A class for URI-escaping functions
CIwVec2 |
CIwVec3 |
CIwVec4 |
IIwDecomposable | Interface to allow an object to participate in text decomposition. The interface allows for writing out only the need parts of an objects definition
IIwFocusResolver | Helper interface to determine an element which to give focus to
IIwPropertySetObserver | Interface to allow an observer to be informed of property changes. It is used with property set bindings (implementations of CIwPropertySetBinding) to allow a consumer of a property set to be informed when external changes cause property values to change
IIwUIAnimatorObserver | Interface to allow an observation of the state changes of a playing animation
IIwUIDrawable | Interface for drawable objects such as text, images, borders
IIwUIEventHandler | Interface to handle or filter events
s3eAudioCallbackData |
s3eDecompressionInput |
s3eDeviceStateChangeInfo |
s3eDeviceVolChangeInfo |
s3eExtMetricsInfo |
s3eFileUserCallbacks |
s3eInetAddress |
s3eKeyboardCharEvent |
s3eKeyboardEvent |
s3eLocation |
s3eMemoryUsrMgr |
s3ePaymentRequest |
s3ePaymentTransaction |
s3ePointerEvent |
s3ePointerMotionEvent |
s3ePointerTouchEvent |
s3ePointerTouchMotionEvent |
s3eProductIdentifier |
s3eProductInformation |
s3eSoundEndSampleInfo |
s3eSoundGenAudioInfo |
s3eSurfaceCopyupInfo |
s3eSurfaceInfo |
s3eSurfaceOrientation |
s3eTransactionIdentifier |
s3eTransactionReceipt |


Airplay API Reference: CIw2DFont

Airplay API Reference > Data Structures > CIw2DFont >

CIw2DFont Class Reference
[Iw2D API Reference]

#include <Iw2D.h>

Public Member Functions

virtual int32 GetHeight ()=0

Detailed Description

Object representing a bmp font prepared for blitting

Member Function Documentation

virtual int32 CIw2DFont::GetHeight ( ) [pure virtual]

Get the height of the font

Returns:
the line height of the font (in pixels)
Required Header Files
Iw2D.h

The documentation for this class was generated from the following file:
  • Iw2D.h


Airplay API Reference: CIw2DImage

Airplay API Reference > Data Structures > CIw2DImage >

CIw2DImage Class Reference
[Iw2D API Reference]

#include <Iw2D.h>

Public Member Functions

virtual int16 | GetHeight ()=0
virtual int16 | GetWidth ()=0

Detailed Description

Object representing a bmp image prepared for blitting

Member Function Documentation

virtual int16 CIw2DImage::GetHeight ( ) [pure virtual]

Get the height of the image

Returns:
the height of the image (in pixels)
Required Header Files
Iw2D.h

virtual int16 CIw2DImage::GetWidth ( ) [pure virtual]

Get the width of the image

Returns:
the width of the image (in pixels)
Required Header Files
Iw2D.h

The documentation for this class was generated from the following file:
  • Iw2D.h


Airplay API Reference: CIw2DSurface

Airplay API Reference > Data Structures > CIw2DSurface >

CIw2DSurface Class Reference
[Iw2D API Reference]

#include <Iw2D.h>

Detailed Description

Object representing an offscreen surface that can be used as a destination and source for blitting
The documentation for this class was generated from the following file:
  • Iw2D.h


Airplay API Reference: CIwAnim

Airplay API Reference > Data Structures > CIwAnim >

CIwAnim Class Reference
[Animation]

#include <IwAnimClass.h>

Inheritance diagram for CIwAnim:

[legend]

Public Member Functions

void | ApplyScale (iwfixed scale)
iwfixed | GetDuration () const
CIwAnimKeyFrame * | GetKeyFrame (uint32 k)
uint32 | GetNumBones () const
uint32 | GetNumKeyFrames () const
CIwAnimSkel * GetSkel ()

Detailed Description

Resource describing an animation to play on a skeleton. A CIwAnim object contains a number of "keyframes". Each keyframe is associated with a fixed positive time-stamp, and contains an array of "bone" transformations. By interpolating between keyframes, we can calculate the required bone transformations for any elapsed animation time.

Member Function Documentation

void CIwAnim::ApplyScale ( iwfixed scale )

Apply a scaling factor to the animation. This will scale the translation component for all bone transform in all keyframes.

Parameters:
scale Scale to apply, in 1.19.12 format.
Required Header Files
IwAnimClass.h

void CIwAnim::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

iwfixed CIwAnim::GetDuration ( ) const [inline]

Get the duration of the animation.

Returns:
The duration of the animation, in seconds, in 1.19.12 format.
Required Header Files
IwAnimClass.h

CIwAnimKeyFrame* CIwAnim::GetKeyFrame ( uint32 k ) [inline]

Get a keyframe of a specified ID.

Parameters:
k ID of keyframe to return. Must be less that GetNumKeyFrames().
Returns:
Pointer to the keyframe of the specified ID.
Required Header Files
IwAnimClass.h

uint32 CIwAnim::GetNumBones ( ) const

Get the number of bones used by the animation.

Returns:
The number of bones used by the animation.
Note:
A keyframe does not have to contain transformations for all bones in the skeleton. For a particular bone, if no transform appears in any keyframe of the animation, then that bone is not included in this total; i.e. this function returns the number of bones in the skeleton which are ever modified by the animation.
Required Header Files
IwAnimClass.h

uint32 CIwAnim::GetNumKeyFrames ( ) const [inline]

Get the number of keyframes in the animation.

Returns:
The number of keyframes in the animation.
Required Header Files
IwAnim.h

CIwAnimSkel* CIwAnim::GetSkel ( ) [inline]

Get the owner skeleton for the animation.

Returns:
The skeleton the animation runs on.
Required Header Files
IwAnimClass.h

The documentation for this class was generated from the following file:
  • IwAnimClass.h


Airplay API Reference: CIwAnimBlendSource

Airplay API Reference > Data Structures > CIwAnimBlendSource >

CIwAnimBlendSource Class Reference
[Animation Player]

#include <IwAnimPlayer.h>

Public Types

enum

Public Member Functions

void | Clear ()
void | ClearFlags (uint32 flags)
CIwAnim * | GetAnim () const
iwfixed | GetBlendParam () const
uint32 | GetFlags () const
iwfixed | GetOverflow () const
iwfixed | GetSpeed () const
iwfixed | GetTime () const
void | Pause ()
void | PlayAnim (CIwAnim *pAnim, iwfixed speed=IW_GEOM_ONE, uint32 flags=0)
void | SetFlags (uint32 flags)
void | SetSpeed (iwfixed speed)
void | SetTime (iwfixed time)
void | SetTimeFraction (iwfixed time)
void | Start ()
void | Stop ()
void | UpdateParameters (iwfixed secs)
void | UpdateSource (uint32 boneFlags)

Detailed Description

Responsible for calculating the bone transforms for a single animation. Each CIwAnimPlayer can contain multiple blend sources, and thus multiple animations on a single skeleton. It then "blends" between these sources to calculate a final series of bone transforms.
Required Header Files
IwAnimPlayer.h

Member Enumeration Documentation

anonymous enum

Flags.

Enumerator:
RESET_IF_SAME_F | pass to PlayAnim() to reset anim if already playing
CORRECT_OVERFLOW_F | pass to correct for overflow from previous (completed) anim
PAUSED_F | source is paused
LOOPING_F | play looping
COMPLETE_F | one-shot anim has finished
BLEND_COMPLETE_F | blend duration has elapsed
LOOPED_F | looping anim has looped
LOOPED_LAST_ADVANCE_F | looped on last update
UPDATE_XFORMS_F | trigger xforms to be updated

Member Function Documentation

void CIwAnimBlendSource::Clear ( )

Clear this source, so it is not playing an anim.

Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::ClearFlags ( uint32 flags ) [inline]

Clear flags.

Parameters:
flags Flags to clear.
See also:
SetFlags, GetFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

CIwAnim* CIwAnimBlendSource::GetAnim ( ) const [inline]

Get the current animation playing on this source.

Returns:
Pointer to the current animation playing on this source, or NULL if none.
See also:
SetAnim
Required Header Files
IwAnimPlayer.h

iwfixed CIwAnimBlendSource::GetBlendParam ( ) const [inline]

When blending between multiple sources, get the proportion of blend completed.

Returns:
The proportion of blend completed, in 1.19.12 format.
Required Header Files
IwAnimPlayer.h

uint32 CIwAnimBlendSource::GetFlags ( ) const [inline]

Get flags.

Returns:
Current flags set.
See also:
SetFlags, ClearFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

iwfixed CIwAnimBlendSource::GetOverflow ( ) const [inline]

Get any elapsed animation time "left over" after anim completion. This is sometimes useful when playing multiple animations in succession; when the first animation has completed, read this value, and use it as the starting time for the second animation, by calling SetTime().

Returns:
The elapsed animation time "left over" after anim completion.
See also:
GetTime
Required Header Files
IwAnimPlayer.h

iwfixed CIwAnimBlendSource::GetSpeed ( ) const [inline]

Get the playback speed, in 1.19.12 format.

Returns:
The playback speed, in 1.19.12 format.
See also:
SetSpeed
Required Header Files
IwAnimPlayer.h

iwfixed CIwAnimBlendSource::GetTime ( ) const [inline]

Get the elapsed animation time on this source.

Returns:
The elapsed animation time on this source, in seconds, in 1.19.12 format.
See also:
SetTime, SetTimeFraction, GetTimeOverflow
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::Pause ( ) [inline]

Pause this source.

See also:
Start
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::PlayAnim | ( | CIwAnim * | pAnim,
 |  | iwfixed | speed = IW_GEOM_ONE,
 |  | uint32 | flags = 0
 | ) |  |

Play an animation on this source. If the animation has only 1 bone a dummy skeleton will be automatically created. Otherwise a compatible skeleton must be specified using SetSkel.

Parameters:
pAnim | Pointer to the animation resource to use.
speed | Speed at which to play the animation, in 1.19.12 format. Default is IW_GEOM_ONE.
flags | Flags to apply when playing, e.g. LOOPING_F. Default is 0.
See also:
GetAnim
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::SetFlags ( uint32 flags ) [inline]

Set flags.

Parameters:
flags Flags to set.
See also:
ClearFlags, GetFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::SetSpeed ( iwfixed speed ) [inline]

Set the playback speed, in 1.19.12 format.

Parameters:
speed Speed in 1.19.12 format. For example, IW_GEOM_ONE will play back at normal speed; IW_GEOM_ONE*2 will play back at double speed.
See also:
GetSpeed
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::SetTime ( iwfixed time )

Set the elapsed animation time on this source.

Parameters:
time Elapsed time in seconds, in 1.19.12 format.
Note:
If the user wishes to pause the animation, then have explicit control over the playback by using SetTime(), then they should also call SetSpeed(0).
See also:
SetTimeFraction, GetTime
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::SetTimeFraction ( iwfixed time )

Set the elapsed animation time on this source, as a fraction of the animation duration.

Parameters:
time Elapsed time as a fraction of the animation duration, in 1.19.12 format. For example, IW_GEOM_ONE/2 would set the source to half way through the animation.
Note:
If the user wishes to pause the animation, then have explicit control over the playback by using SetTimeFraction(), then they should also call SetSpeed(0).
See also:
SetTime, GetTime

void CIwAnimBlendSource::Start ( ) [inline]

Start this source.

See also:
Stop
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::Stop ( ) [inline]

Stop this source (identical to pausing the source).

See also:
Start
Required Header Files
IwAnimPlayer.h

void CIwAnimBlendSource::UpdateParameters ( iwfixed secs )

Update the blend source by a specified elapsed time.

Parameters:
secs Elapsed time to update by, in seconds, in 1.19.12 format. For example, IW_GEOM_ONE/20 equates to 1/20th second.

void CIwAnimBlendSource::UpdateSource ( uint32 boneFlags )

Blend source at current time to produce interpolated bone transforms

Parameters:
boneFlags Update only the bones whose IDs are set in this bitfield.

The documentation for this class was generated from the following file:
  • IwAnimPlayer.h


Airplay API Reference: CIwAnimBone

Airplay API Reference > Data Structures > CIwAnimBone >

CIwAnimBone Class Reference
[Animation Bone.]

#include <IwAnimBone.h>

Inheritance diagram for CIwAnimBone:

[legend]

Public Member Functions

const CIwMat * | GetMat ()
uint32 | GetNumChildren ()
CIwAnimBone * GetParent ()
const CIwSVec3 | GetPos () const
const CIwSQuat & | GetRot () const
uint16 | GetSkelID ()
void | SetModelMatrix (const CIwMat &matWorld)
void | SetPos (const CIwSVec3 &pos)
void | SetRot (const CIwSQuat &rot)
void | Update ()

Detailed Description

A bone within a skeleton. Contains a rotation (quaternion) and translation relative to its parent bone. Also contains a pointer to the parent bone (or NULL if the bone is the root bone in the skeleton) and pointers to any child bones. Additionally, it contains a modelspace matrix used for skinning.

Member Function Documentation

const CIwMat* CIwAnimBone::GetMat ( )

Get the modelspace bone matrix.

Returns:
Pointer to the modelspace bone matrix.
Required Header Files
IwAnimBone.h

uint32 CIwAnimBone::GetNumChildren ( ) [inline]

Get the number of children.

Returns:
The number of children attached to this bone.
Required Header Files
IwAnimBone.h

CIwAnimBone* CIwAnimBone::GetParent ( ) [inline]

Get the parent bone.

Returns:
Pointer to the parent bone, or NULL if this bone is the root bone in the skeleton.
Required Header Files
IwAnimBone.h

const CIwSVec3 CIwAnimBone::GetPos ( ) const

Get bone translation.

Returns:
Bone translation, relative to parent.
See also:
SetPos, SetRot, GetRot
Required Header Files
IwAnimBone.h

const CIwSQuat& CIwAnimBone::GetRot ( ) const [inline]

Get bone rotation.

Returns:
Bone rotation, relative to parent.
See also:
SetRot, SetPos, GetPos
Required Header Files
IwAnimBone.h

uint16 CIwAnimBone::GetSkelID ( ) [inline]

Get the ID of this bone within the skeleton.

Returns:
The ID of this bone within the skeleton.
Required Header Files
IwAnimBone.h

void CIwAnimBone::SetModelMatrix ( const CIwMat & matWorld )

Set the iwgx model matrix to match this bone's local transform transformed by the specified matWorld. This method should be preferred to manually composing this matrix because it can use the extra internal precision of the animation.

Parameters:
matWorld The world matrix basis to set the bone matrix within

void CIwAnimBone::SetPos ( const CIwSVec3 & pos )

Set bone translation.

Parameters:
pos Bone translation to set, relative to parent.
See also:
GetPos, SetRot, GetRot
Required Header Files
IwAnimBone.h

void CIwAnimBone::SetRot ( const CIwSQuat & rot ) [inline]

Set bone rotation.

Parameters:
rot Bone rotation to set, relative to parent.
See also:
GetRot, SetPos, GetPos
Required Header Files
IwAnimBone.h

void CIwAnimBone::Update ( )

Update the modelspace matrices of this bone and all its children.

Note:
Usually this is called through CIwAnimPlayer::Update(), and the user does not need to call it directly.
Required Header Files
IwAnimBone.h

The documentation for this class was generated from the following file:
  • IwAnimBone.h


Airplay API Reference: CIwAnimPlayer

Airplay API Reference > Data Structures > CIwAnimPlayer >

CIwAnimPlayer Class Reference
[Animation Player]

#include <IwAnimPlayer.h>

Inheritance diagram for CIwAnimPlayer:

[legend]

Public Member Functions

void | ClearFlags (uint32 flags)
void | ClearSubAnim (uint32 s, uint32 blendDur=0x400)
CIwAnimBone * | GetBoneFromID (uint32 id)
CIwAnimBone * | GetBoneHashed (uint32 hash)
CIwAnimBone * | GetBoneNamed (const char *pName)
uint32 | GetFlags () const
const CIwMat & | GetMatOfs () const
const CIwMat | GetMatOfsFinal () const
const CIwMat | GetMatOfsInitial () const
CIwAnimSkel * | GetSkel () const
CIwAnimBlendSource * GetSourceCurr ()
CIwAnimBlendSource * GetSourcePrev ()
CIwAnimBlendSource * | GetSourceSub (uint32 s)
iwfixed | GetTime () const
bool | IsCurrentAnimComplete ()
bool | IsCurrentBlendComplete ()
void | Pause ()
void | PlayAnim (CIwAnim *pAnim, iwfixed speed=IW_GEOM_ONE, uint32 flags=0, uint32 blendDur=0x400)
void | PlayOfsAnim (CIwAnim *pAnim, iwfixed speed=IW_GEOM_ONE, uint32 flags=0)
void | PlaySubAnim (uint32 s, CIwAnim *pAnim, iwfixed speed, uint32 flags, uint32 blendDur=0x400)
virtual void | Resolve ()
virtual void | Serialise ()
void | SetFlags (uint32 flags)
void | SetSkel (CIwAnimSkel *pSkel)
void | SetTime (iwfixed time)
void | SetTimeFraction (iwfixed time)
void | Start ()
void | Stop ()
void | Update (iwfixed secs)
void | UpdateMatrices ()
void | UpdateParameters (iwfixed ts)
void | UpdateSources ()

Detailed Description

An animation player object can track multiple animations on a single skeleton, and blend them to form a final series of bone transforms to use for skinning. Up to two full-skeleton animations and up to two sub-skeleton animations can be tracked at any one time.

Member Enumeration Documentation

anonymous enum

Flags.

Enumerator:
DEBUG_RENDER_BONE_AXES_F | Render bone axes.
DEBUG_RENDER_BONE_NAMES_F | Render bone names.
DEBUG_RENDER_BONE_LINKS_F | Render bone links (lines from bone to bone).
OVERFLOW_CORRECTION_F | Enable correction for blend source overflow time.
OFS_ANIM_LOOPED_F | Indication that offset anim looped.

Member Function Documentation

void CIwAnimPlayer::ClearFlags ( uint32 flags ) [inline]

Clear flags.

Parameters:
flags Flags to clear.
See also:
SetFlags, GetFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::ClearSubAnim | ( | uint32 | s,
 |  | uint32 | blendDur = 0x400
 | ) |  |

Clear a sub-skeleton animation.

Parameters:
s | Sub-skeleton slot to use. The player supports up to 2 sub-skeleton blend sources, so this value must be 0 or 1.
blendDur | Blend from any previous animation over this number of seconds, in 1.19.12 format. Default is IW_GEOM_ONE/4 (1/4 second). If zero, no blend is applied.

virtual void CIwAnimPlayer::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

virtual void CIwAnimPlayer::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

CIwAnimBone* CIwAnimPlayer::GetBoneFromID ( uint32 id )

Get local skeleton bone by ID.

Parameters:
id ID of the bone within the local skeleton.
Returns:
Pointer to the bone of the specified ID.
Required Header Files
IwAnimPlayer.h

CIwAnimBone* CIwAnimPlayer::GetBoneHashed ( uint32 hash )

Get named bone within the local skeleton.

Parameters:
hash The bone name hash to search for.
Returns:
Pointer to the named bone, or NULL if it does not exist.
Required Header Files
IwAnimPlayer.h

CIwAnimBone* CIwAnimPlayer::GetBoneNamed ( const char * pName )

Get named bone within the local skeleton.

Parameters:
pName The bone name string to search for.
Returns:
Pointer to the named bone, or NULL if it does not exist.
Required Header Files
IwAnimPlayer.h

uint32 CIwAnimPlayer::GetFlags ( ) const [inline]

Get flags.

Returns:
Current flags set.
See also:
SetFlags, ClearFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

const CIwMat& CIwAnimPlayer::GetMatOfs ( ) const

Get the offset transform, if valid.

Returns:
The current offset transform, as determined by the offset anim at the current time.
Note:
The offset transform is only valid if there is an offset animation playing.
Required Header Files
IwAnimPlayer.h

const CIwMat CIwAnimPlayer::GetMatOfsFinal ( ) const

Get the final offset transform (i.e. at end of) offset anim

Returns:
Transform matrix at end of offset anim
Required Header Files
IwAnimPlayer.h

const CIwMat CIwAnimPlayer::GetMatOfsInitial ( ) const

Get the initial offset transform (i.e. at start of) offset anim

Returns:
Transform matrix at start of offset anim
Required Header Files
IwAnimPlayer.h

CIwAnimSkel* CIwAnimPlayer::GetSkel ( ) const [inline]

Get the local skeleton.

Returns:
Pointer to the local skeleton.
See also:
GetSkel
Required Header Files
IwAnimPlayer.h

CIwAnimBlendSource* CIwAnimPlayer::GetSourceCurr ( ) [inline]

Get the current full-skeleton blend source.

Returns:
Pointer to the current full-skeleton blend source.
Required Header Files
IwAnimPlayer.h

CIwAnimBlendSource* CIwAnimPlayer::GetSourcePrev ( ) [inline]

Get the previous full-skeleton blend source.

Returns:
Pointer to the previous full-skeleton blend source.
Note:
Whenever a new full-skeleton animation is played, details of any existing animation are copied to the "previous" blend source. Both sources are then tracked in parallel, and the results blended to form the final bone transforms. After a period of time, the effect of the "previous" blend source drops to 0, and is no longer relevant.
Required Header Files
IwAnimPlayer.h

CIwAnimBlendSource* CIwAnimPlayer::GetSourceSub ( uint32 s ) [inline]

Get the specified sub-skeleton blend source.

Parameters:
s Sub-skeleton slot to use. The player supports up to 2 sub-skeleton blend sources, so this value must be 0 or 1.
Returns:
Pointer to the specified sub-skeleton blend source.
Required Header Files
IwAnimPlayer.h

iwfixed CIwAnimPlayer::GetTime ( ) const [inline]

Get the elapsed animation time on the current full-skeleton blend source.

Returns:
The elapsed animation time on this source, in seconds, in 1.19.12 format.
Note:
This is identical to calling GetBlendSourceCurr()->SetGetTime().
See also:
SetTime, SetTimeFraction, GetTimeOverflow
Required Header Files
IwAnimPlayer.h

bool CIwAnimPlayer::IsCurrentAnimComplete ( ) [inline]

Check if the current full-skeleton blend source animation is completed.

Returns:
true only if current full-skeleton animation is completed.
Required Header Files
IwAnimPlayer.h

bool CIwAnimPlayer::IsCurrentBlendComplete ( ) [inline]

Check if the current full-skeleton animation has completed any blend from a previous animation.

Returns:
true only if current full-skeleton animation has completed any blend from a previous animation.
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::Pause ( )

Pause the main anim.

Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::PlayAnim | ( | CIwAnim * | pAnim,
 |  | iwfixed | speed = IW_GEOM_ONE,
 |  | uint32 | flags = 0,
 |  | uint32 | blendDur = 0x400
 | ) |  |

Play a full-skeleton animation.

Parameters:
pAnim | Pointer to the animation resource to use.
speed | Speed at which to play the animation, in 1.19.12 format. Default is IW_GEOM_ONE.
flags | Flags to apply when playing, e.g. LOOPING_F. Default is 0.
blendDur | Blend from any previous animation over this number of seconds, in 1.19.12 format. Default is IW_GEOM_ONE/4 (1/4 second). If zero, no blend is applied.
See also:
PlaySubAnim

void CIwAnimPlayer::PlayOfsAnim | ( | CIwAnim * | pAnim,
 |  | iwfixed | speed = IW_GEOM_ONE,
 |  | uint32 | flags = 0
 | ) |  |

Play an offset animation. An offset animation must contain a single bone, and is used to modify the final root transform of the local skeleton.

Note:
Playing a NULL anim will clear the Offset Animation source.
Parameters:
pAnim | Pointer to the animation resource to use. This must contain a single bone.
speed | Speed at which to play the animation, in 1.19.12 format. Default is IW_GEOM_ONE.
flags | Flags to apply when playing, e.g. LOOPING_F. Default is 0.
See also:
SetMatOfs, GetMatOfs
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::PlaySubAnim | ( | uint32 | s,
 |  | CIwAnim * | pAnim,
 |  | iwfixed | speed,
 |  | uint32 | flags,
 |  | uint32 | blendDur = 0x400
 | ) |  |

Play a sub-skeleton animation.

Parameters:
s | Sub-skeleton slot to use. The player supports up to 2 sub-skeleton blend sources, so this value must be 0 or 1.
pAnim | Pointer to the animation resource to use.
speed | Speed at which to play the animation, in 1.19.12 format. Default is IW_GEOM_ONE.
flags | Flags to apply when playing, e.g. LOOPING_F. Default is 0.
blendDur | Blend from any previous animation over this number of seconds, in 1.19.12 format. Default is IW_GEOM_ONE/4 (1/4 second). If zero, no blend is applied.
See also:
PlayAnim

virtual void CIwAnimPlayer::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwAnimPlayer::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwAnimPlayer::SetFlags ( uint32 flags ) [inline]

Set flags.

Parameters:
flags Flags to set.
See also:
ClearFlags, GetFlags
Required Header Files
IwAnimPlayer.h
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::SetSkel ( CIwAnimSkel * pSkel )

Set the skeleton resource to use.

Parameters:
pSkel Pointer to the skeleton resource to use.
Note:
This function clones the skeleton resource, to create a local copy which is then modified by the animation player. This local copy if usually used as the source to IwAnimSetSkelContext(), prior to rendering a static model which the user wishes to be skinned.
See also:
SetSkel
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::SetTime ( iwfixed time )

Set the elapsed animation time on the current full-skeleton blend source.

Parameters:
time Elapsed time in seconds, in 1.19.12 format.
Note:
If the user wishes to pause the animation, then have explicit control over the playback by using SetTime(), then they should also call SetSpeed(0).

This is identical to calling GetBlendSourceCurr()->SetTime().

See also:
SetTimeFraction, GetTime
Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::SetTimeFraction ( iwfixed time )

Set the elapsed animation time on the current full-skeleton blend source. as a fraction of the animation duration.

Parameters:
time Elapsed time as a fraction of the animation duration, in 1.19.12 format. For example, IW_GEOM_ONE/2 would set the source to half way through the animation.
Note:
If the user wishes to pause the animation, then have explicit control over the playback by using SetTimeFraction(), then they should also call SetSpeed(0).

This is identical to calling GetBlendSourceCurr()->SetTimeFraction().

See also:
SetTime, GetTime

void CIwAnimPlayer::Start ( )

Start the main anim.

Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::Stop ( )

Stop the main anim.

Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::Update ( iwfixed secs )

Update the blend source by a specified elapsed time.

Note:
This function provides a complete update of the animation. For performance reasons this update can be split into separate calls to UpdateParameters, UpdateSources and UpdateMatrices
Parameters:
secs Elapsed time to update by, in seconds, in 1.19.12 format. For example, IW_GEOM_ONE/20 equates to 1/20th second.

void CIwAnimPlayer::UpdateMatrices ( )

Update local skeleton modelspace bone matrices.

Note:
This function is used as part of a separated update along with UpdateParameters and UpdateSources
See also:
UpdateParameters

UpdateSources

Required Header Files
IwAnimPlayer.h

void CIwAnimPlayer::UpdateParameters ( iwfixed ts )

Update current time and status of animation.

Note:
This function is used as part of a separated update along with UpdateSources and UpdateMatrices
Parameters:
secs Elapsed time to update by, in seconds, in 1.19.12 format. For example, IW_GEOM_ONE/20 equates to 1/20th second.
See also:
UpdateSources

UpdateMatrices

void CIwAnimPlayer::UpdateSources ( )

Blend sources at current time, but do NOT calculate modelspace bone matrices.

Note:
This function is used as part of a separated update along with UpdateParameters and UpdateMatrices
See also:
UpdateParameters

UpdateMatrices

The documentation for this class was generated from the following file:
  • IwAnimPlayer.h


Airplay API Reference: CIwAnimSkel

Airplay API Reference > Data Structures > CIwAnimSkel >

CIwAnimSkel Class Reference
[Skeleton]

#include <IwAnimSkel.h>

Inheritance diagram for CIwAnimSkel:

[legend]

Public Member Functions

void | ApplyScale (int32 scale)
CIwAnimBone * | GetBoneFromID (uint32 id)
CIwAnimBone * | GetBoneHashed (uint32 hash)
const CIwManagedList & | GetBoneList () const
CIwAnimBone * | GetBoneNamed (const char *pName)
uint32 | GetNumBones () const
void | ResetSkinCache ()

Detailed Description

Resource describing an animation skeleton. A skeleton is simply a list of bones. Each bone contains a pointer to its parent bone (or NULL if it is the root bone in the skeleton) and pointers to any child bones. The skeleton resource defines both the bone hierarchy (parent/child relationships between bones) and the "bind pose" of the skeleton. The bind pose is the pose in which the vertex skinning data is defined (see CIwAnimSkin).
Note:
When calling CIwAnimPlayer::SetSkel(), we pass in a pointer to a skeleton resource. The skeleton resource is then cloned, and the animation player the owns its own copy of the skeleton. This local skeleton is the one whose bone transforms are modified according to the animation(s) being player, and this local copy is the one which should be provided as an input to IwAnimSetSkelContext().

Member Function Documentation

void CIwAnimSkel::ApplyScale ( int32 scale )

Apply a scaling factor to the skeleton. This will scale the translation component for all bone transforms.

Parameters:
scale Scale to apply, in 1.19.12 format.
Required Header Files
IwAnimSkel.h

void CIwAnimSkel::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

CIwAnimBone* CIwAnimSkel::GetBoneFromID ( uint32 id ) [inline]

Get skeleton bone by ID.

Parameters:
id ID of the bone within the local skeleton. Must be less than GetNumBones().
Returns:
Pointer to the bone of the specified ID.
See also:
GetNumBones
Required Header Files
IwAnimSkel.h

CIwAnimBone* CIwAnimSkel::GetBoneHashed ( uint32 hash ) [inline]

Get named bone within the skeleton.

Parameters:
hash The bone name hash to search for.
Returns:
Pointer to the named bone, or NULL if it does not exist.
Required Header Files
IwAnimSkel.h

const CIwManagedList& CIwAnimSkel::GetBoneList ( ) const [inline]

Get the list of bones.

Returns:
A reference to the list of bones in the skeleton.
Required Header Files
IwAnimSkel.h

CIwAnimBone* CIwAnimSkel::GetBoneNamed ( const char * pName ) [inline]

Get named bone within the skeleton.

Parameters:
pName The bone name string to search for.
Returns:
Pointer to the named bone, or NULL if it does not exist.
Required Header Files
IwAnimSkel.h

uint32 CIwAnimSkel::GetNumBones ( ) const [inline]

Get the number of bones in the skeleton.

Returns:
The number of bones in the skeleton.
Required Header Files
IwAnimSkel.h

void CIwAnimSkel::ResetSkinCache ( )

Reset cache flags to ensure anim skin cache is flagged as dirty This is essential if skinned mesh is swapped while using the same skeleton - eg: for Level of Detail

Required Header Files
IwAnimSkel.h

The documentation for this class was generated from the following file:
  • IwAnimSkel.h


Airplay API Reference: CIwAnimSkin

Airplay API Reference > Data Structures > CIwAnimSkin >

CIwAnimSkin Class Reference
[Skin]

#include <IwAnimSkin.h>

Inheritance diagram for CIwAnimSkin:

[legend]

Public Member Functions

void | ApplyScale (int32 scale)
CIwModel * | GetModel () const
CIwAnimSkel * | GetSkel () const
void | SetModel (CIwModel *pModel)
void | SetSkel (CIwAnimSkel *pSkel)

Detailed Description

Resource describing skinning data for a model and skeleton. The skin resource contains pointers to both a CIwModel (representing the static bind pose) and a CIwAnimSkeleton (describing the bone hierarchy and bind pose transformations). The skin also contains a series of "weights" for each model vertex. Each model vertex can have up to 4 weights. The weights dictate how each vertex should move as the skeleton bone transforms are modified by animation.

Member Function Documentation

void CIwAnimSkin::ApplyScale ( int32 scale )

Apply a scaling factor to the skin.

Parameters:
scale Scale to apply, in 1.19.12 format.
Required Header Files
IwAnimSkin.h

void CIwAnimSkin::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

CIwModel* CIwAnimSkin::GetModel ( ) const [inline]

Get the model used by the skin.

Returns:
Pointer to the model used by the skin.

CIwAnimSkel* CIwAnimSkin::GetSkel ( ) const [inline]

Get the skeleton used by the skin.

Returns:
Pointer to the skeleton used by the skin.

void CIwAnimSkin::SetModel ( CIwModel * pModel )

Set the model to use. Pointer to the model resource to use.

Required Header Files
IwAnimSkin.h

void CIwAnimSkin::SetSkel ( CIwAnimSkel * pSkel )

Set the skeletonl to use. Pointer to the skeleton resource to use.

Required Header Files
IwAnimSkin.h

The documentation for this class was generated from the following file:
  • IwAnimSkin.h


Airplay API Reference: CIwArray

Airplay API Reference > Data Structures > CIwArray< X, A, REALLOCATE > >

CIwArray< X, A, REALLOCATE > Class Template Reference
[IwArray]

#include <IwArray.h>

Public Member Functions

int | append (CIwArray &a)
int | append (X const &x)
X const & | back () const
iterator | begin () const
bool | CanResize ()
uint32 | capacity () const
CIwArray (CIwArray const &v)
CIwArray (uint32 sz=0)
void | clear ()
void | clear_optimised ()
bool | contains (X const &value) const
X * | data ()
bool | empty () const
iterator | end () const
iterator | erase (iterator i, iterator j)
iterator | erase (iterator i)
int | erase (const uint32 i, const uint32 j)
int | erase (const int i)
iterator | erase_fast (iterator i, iterator j)
iterator | erase_fast (iterator i)
int | erase_fast (const int i, const int j)
int | erase_fast (const int i)
int | find (X const &value) const
bool | find_and_remove (X const &value)
bool | find_and_remove_fast (X const &value)
X const & | front () const
void | insert_slow (CIwArray &a, uint32 pos)
void | insert_slow (X const &x, uint32 pos)
void | LockSize (bool lock)
int | MemoryUsage () const
void | operator= (CIwArray const &v)
X & | operator[] (int const i) const
void | optimise_capacity ()
void | pop_back ()
X | pop_back_get ()
int | push_back ()
int | push_back (X const &x)
void | push_back_qty (int qty)
void | push_back_qty (X const &x, int qty)
void | reserve (uint32 q)
void | reserve_optimised (int q)
void | resize (const uint32 q)
void | resize_optimised (uint32 s)
void | resize_quick (const uint32 q)
void | SerialiseHeader ()
void | Share (X *buffer, int current, int max)
void | Share (CIwArray< X, A > const &other)
uint32 | size () const
void | swap (CIwArray< X, A > &v)

Detailed Description

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
class CIwArray< X, A, REALLOCATE >

CIwArray is an implementation of STL's std::vector augmented to provide more control over memory use and various utility functionality.

Constructor & Destructor Documentation

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
CIwArray< X, A, REALLOCATE >::CIwArray ( uint32 sz = 0 ) [inline, explicit]

Default constructor.

Parameters:
sz If specified initialise the array with sz newly constructed members.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
CIwArray< X, A, REALLOCATE >::CIwArray ( CIwArray< X, A, REALLOCATE > const & v ) [inline]

Copy constructor. Construct this array with a copy of v's array data. The capacity of this array will exactly match the size of v's elements, not its capacity.

Parameters:
v The array to copy.

Member Function Documentation

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::append ( CIwArray< X, A, REALLOCATE > & a ) [inline]

Append an array to the array. On return, the capacity will be at lease size()+a.size() elements.

Parameters:
a The array to append
Returns:
The index of the first new element.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::append ( X const & x ) [inline]

Synonym for push_back.

See also:
push_back

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
X const& CIwArray< X, A, REALLOCATE >::back ( ) const [inline]

STL-Equivalent. Get the last element of the array. An error will be raised if the array is empty.

Returns:
The last element of the array.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::begin ( ) const [inline]

STL-equivalent.

Returns:
An iterator that points to the first element of the array (will equal end() if the array is empty)

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
bool CIwArray< X, A, REALLOCATE >::CanResize ( ) [inline]

Does this array own its own storage (i.e. can it be resized)? If not, resizing will cause a runtime error

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
uint32 CIwArray< X, A, REALLOCATE >::capacity ( ) const [inline]

STL-equivalent.

Returns:
The space reserved for elements in the array
See also:
reserve

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::clear ( ) [inline]

STL-Equivalent. Clear the array's elements. Destructors will be called for all elements in the array. The capacity of the array is unaffected (no reallocation will occur).

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::clear_optimised ( ) [inline]

Clear the array's elements and deallocate the entire capacity. Destructors will be called for all elements in the array. On return, the capacity of the array will be zero.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
bool CIwArray< X, A, REALLOCATE >::contains ( X const & value ) const [inline]

Determine whether an element is in the array.

Parameters:
value Value to test for.
Returns:
true if there is an element matching value (determined by operator==) in the array, false if there is no such element in the array.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
X* CIwArray< X, A, REALLOCATE >::data ( ) [inline]

Returns:
A pointer to the memory held by the array. NULL if none is held.
See also:
reserve

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
bool CIwArray< X, A, REALLOCATE >::empty ( ) const [inline]

STL-equivalent.

Returns:
true if the array is empty.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::end ( ) const [inline]

STL-equivalent.

Returns:
An iterator that points to the first element beyond the end of the array

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::erase | ( | iterator | i,
 |  | iterator | j |
 | ) |  |  | [inline]

STL-Equivalent. Iterator version of erase.

Parameters:
i | An iterator for the first element to remove
j | An iterator for the last element to remove (element j will not be removed)
Returns:
An iterator for the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::erase ( iterator i ) [inline]

STL-Equivalent. Iterator version of erase.

Parameters:
i An iterator for the first element to remove
Returns:
An iterator for the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::erase | ( | const uint32 | i,
 |  | const uint32 | j |
 | ) |  |  | [inline]

Erase the element at index i of the array. All subsequent elements will be copied into the preceding element. Use when preserving the order of the elements is important. On return, the capacity will be unchanged. An error will be raised if the array has no element(s) at the specified indices.

Parameters:
i | The index of the first element to remove
j | The index after the last element to remove (element j will not be removed)
Returns:
The index of the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::erase ( const int i ) [inline]

Erase the element at index i of the array. All subsequent elements will be copied into the preceding element. Use when preserving the order of the elements is important. On return, the capacity will be unchanged. An error will be raised if the array has no element at that index.

Parameters:
i The index of the element to remove
Returns:
The index of the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::erase_fast | ( | iterator | i,
 |  | iterator | j |
 | ) |  |  | [inline]

Iterator version of erase_fast.

Parameters:
i | An iterator for the first element to remove
j | An iterator for the last element to remove (element j will not be removed)
Returns:
An iterator for the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
iterator CIwArray< X, A, REALLOCATE >::erase_fast ( iterator i ) [inline]

Iterator version of erase_fast.

Parameters:
i An iterator for the first element to remove
Returns:
An iterator for the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::erase_fast | ( | const int | i,
 |  | const int | j |
 | ) |  |  | [inline]

Erase the elements between index i and index j of the array. Elements from the end of the array will be copied into the place of the elements removed, reducing the amount of work done to re-normalise the array. Use when the order of the elements is not important. An error will be raised if the array has no element(s) at the specified indices. On return, the capacity will be unchanged.

Parameters:
i | The index of the first element to remove
j | The index after the last element to remove (element j will not be removed)
Returns:
The index of the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::erase_fast ( const int i ) [inline]

Erase the element at index i of the array. The final element will be copied into its place, reducing the amount of work done to re-normalise the array. Use when the order of the elements is not important. An error will be raised if the array has no element at that index. On return, the capacity will be unchanged.

Parameters:
i The index of the element to remove
Returns:
The index of the next element after the removed elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::find ( X const & value ) const [inline]

Find an element's position in the array.

Parameters:
value Value to test for.
Returns:
The index occupied by the first element matching value (determined by operator==). -1 if there is no such element in the array.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
bool CIwArray< X, A, REALLOCATE >::find_and_remove ( X const & value ) [inline]

Find and remove an element from the array. On return, the element will be erased (if there was any). The order of elements will not be affected. Only the first occurence will be removed.

Parameters:
value Value to test for.
Returns:
true if there was an element matching value (determined by operator==) in the array. That element will be removed. false if there was no such element in the array.
See also:
erase, find_and_remove_fast

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
bool CIwArray< X, A, REALLOCATE >::find_and_remove_fast ( X const & value ) [inline]

Find and remove an element from the array. On return, the element will be erased (if there was any). The order of elements will change. Only the first occurence will be removed.

Parameters:
value Value to test for.
Returns:
true if there was an element matching value (determined by operator==) in the array. That element will be removed. false if there was no such element in the array.
See also:
erase_fast, find_and_remove

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
X const& CIwArray< X, A, REALLOCATE >::front ( ) const [inline]

Get the first element of the array. An error will be raised if the array is empty.

Returns:
The first element of the array.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::insert_slow | ( | CIwArray< X, A, REALLOCATE > & | a,
 |  | uint32 | pos |
 | ) |  |  | [inline]

Insert an array of elements into the array. Subsequent elements will be shifted up to make space. On return, the capacity will be at least size()+a.size() elements

Parameters:
a | An array of elements to insert into the array
pos | The position to insert the element into.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::insert_slow | ( | X const & | x,
 |  | uint32 | pos |
 | ) |  |  | [inline]

Insert an element into the array. Subsequent elements will be shifted up to make space. On return, the capacity will be at least size()+1 elements

Parameters:
x | An element to insert into the array
pos | The position to insert the element into.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::LockSize ( bool lock ) [inline]

Lock this array's capacity to its current value. The array will assert if any attempt is made to expand its data allocation.

Note:
The array will still be allowed to shrink, and if an optimised call is used to shrink it then an assert will fire if it tries to increase its capacity subsequently.
Parameters:
lock Lock or release array growing.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::MemoryUsage ( ) const [inline]

Get the total memory footprint the array and it's allocated capacity.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::operator= ( CIwArray< X, A, REALLOCATE > const & v ) [inline]

Assignment operator. Set this array to contain a copy of v's array data. The capacity of this array will exactly match the size of v's elements, not its capacity.

Parameters:
v The array to copy.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
X& CIwArray< X, A, REALLOCATE >::operator[] ( int const i ) const [inline]

Get the element at index i of the array. An error will be raised if the array has no element at index i.

Parameters:
i The index to retrieve.
Returns:
The element at index i

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::optimise_capacity ( ) [inline]

Optimise the array's capacity. Make the array occupy as little memory as possible to contain its current element set. On return, the capacity will be size() elements.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::pop_back ( ) [inline]

Remove the final element of the array. An error will be raised if the array is empty. On return, the capacity will be unchanged.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
X CIwArray< X, A, REALLOCATE >::pop_back_get ( ) [inline]

Remove the final element of the array and return a copy of it. An error will be raised if the array is empty. On return, the capacity will be unchanged.

Returns:
a copy of the element that was the final one in the array.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::push_back ( ) [inline]

Append an empty element to the array. The default constructor will be called. On return, the capacity will be at lease size()+1 elements.

Returns:
The index of the new element.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
int CIwArray< X, A, REALLOCATE >::push_back ( X const & x ) [inline]

Append an element to the array. On return, the capacity will be at lease size()+1 elements.

Parameters:
x The element to append
Returns:
The index of the new element.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::push_back_qty ( int qty ) [inline]

Append a number of empty elements to the array. On return, the capacity will be at lease size()+qty elements.

Parameters:
qty The number of copies to append.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::push_back_qty | ( | X const & | x,
 |  | int | qty |
 | ) |  |  | [inline]

Append a number of copies of x to the array. On return, the capacity will be at lease size()+qty elements.

Parameters:
x | The element to copy into the array
qty | The number of copies to append.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::reserve ( uint32 q ) [inline]

Reserve capacity for at least q elements. On return, the capacity will be at least q elements.

Parameters:
q The capacity required.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::reserve_optimised ( int q ) [inline]

Reserve capacity for exactly q elements. On return, the capacity will be exactly q elements.

Parameters:
q The capacity required.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::resize ( const uint32 q ) [inline]

Resize to q elements. Constructors or destructors will be called. On return, the capacity will be at least q elements.

Parameters:
q The capacity required.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::resize_optimised ( uint32 s ) [inline]

Resize the array and optimise the capacity. If s is greater than the current size, new elements will be constructed and appended to the array. On return, the capacity will be s elements.

Parameters:
s Size of the capacity (in elements).

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::resize_quick ( const uint32 q ) [inline]

Resize to q elements. No constructors or destructors will be called. An error will be raised if q is larger than the current capacity. On return, the capacity will be unchanged.

Parameters:
q The capacity required.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::SerialiseHeader ( ) [inline]

Prepare to serialise data from/to this array. On serialise write: write the size of the array. On serialise read: read the size of the array and resize to it.

See also:
IwSerialise

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::Share | ( | X * | buffer,
 |  | int | current,
 |  | int | max |
 | ) |  |  | [inline]

Set this array to share a data set. This array will no longer own its data, and will raise an error if it tries to change capacity.

Parameters:
buffer | The data to share.
current | The number of elements currently in the data.
max | The total capacity of the data.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::Share ( CIwArray< X, A > const & other ) [inline]

Set this array to share another's data. This array will no longer own its data, and will raise an error if it tries to change capacity.

Parameters:
other The array to share data with.

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
uint32 CIwArray< X, A, REALLOCATE >::size ( ) const [inline]

STL-equivalent.

Returns:
The number of elements in the array

template<class X, class A = CIwAllocator<X>, class REALLOCATE = ReallocateDefault<X, A >>
void CIwArray< X, A, REALLOCATE >::swap ( CIwArray< X, A > & v ) [inline]

STL-equivalent swap function. On exit, v will have this vector's storage and this vector will have v's.

Parameters:
v vector to swap with.

The documentation for this class was generated from the following file:
  • IwArray.h


Airplay API Reference: CIwAutoFile

Airplay API Reference > Data Structures > CIwAutoFile >

CIwAutoFile Class Reference
[IwAutoFile]

#include <IwAutoFile.h>

Public Member Functions

CIwAutoFile (void *pBuffer, uint32 size)
CIwAutoFile (const char *filename, const char *mode="rb")
operator s3eFile * ()
s3eFile * s3eFileGet ()
~CIwAutoFile ()

Detailed Description

CIwAutoFile wraps an s3eFile, such that the CIwAutoFile going out of scope closes the file handle.
Required Header Files
IwAutoFile.h
The documentation for this class was generated from the following file:
  • IwAutoFile.h


Airplay API Reference: CIwBBoxT

Airplay API Reference > Data Structures > CIwBBoxT< V > >

CIwBBoxT< V > Class Template Reference
[IwGeomBBox]

#include <IwGeomBBox.h>

Public Member Functions

template<class V2>
void | BoundVec (V2 *pVec)
template<class V2>
void | BoundVecs (V2 *pVec, uint32 v)
CIwBBoxT (const V &_min, const V &_max)
CIwBBoxT ()
template<class V2>
bool | ContainsVec (const V2 &v, CIwMat *pMat=NULL) const
V | GetCentre ()
void | Serialise ()

Data Fields

V | m_Max
V | m_Min

Detailed Description

template<class V>
class CIwBBoxT< V >

CIwBBoxT - Defines an axis-aligned bounding box. V type of vector to define extent of bounding box.

Constructor & Destructor Documentation

template<class V>
CIwBBoxT< V >::CIwBBoxT ( ) [inline]

Creates a new uninitialised bounding box.

template<class V>
CIwBBoxT< V >::CIwBBoxT | ( | const V & | _min,
 |  | const V & | _max |
 | ) |  |  | [inline]

Creates a new bounding box.

Parameters:
_min | sets minimum coordinates of vectors contained within the bounding box.
_max | sets maximum coordinates of vectors contained within the bounding box.
Note:
If the coordinates of _max are not greater than or equal to thoes of _min then the bounding box will contain no vectors.

Member Function Documentation

template<class V>
template<class V2>
void CIwBBoxT< V >::BoundVec ( V2 * pVec ) [inline]

Extends the bounding box, if necessary, to include a given vector.

Parameters:
pVec Vector to include in bounding box.

template<class V>
template<class V2>
void CIwBBoxT< V >::BoundVecs | ( | V2 * | pVec,
 |  | uint32 | v |
 | ) |  |  | [inline]

Sets bounding box to the smallest bounding box possible containing all vectors in the passed array.

Parameters:
pVec | Pointer to array of vectors.
v | Number of vectors pointed to by pVec.
Note:
It is assumed the coordinates of given vectors are in the range [INT16_MIN, INT16_MAX].

template<class V>
template<class V2>
bool CIwBBoxT< V >::ContainsVec | ( | const V2 & | v,
 |  | CIwMat * | pMat = NULL |
 | ) |  |  | const [inline]

Tests if bounding box contains a given vector.

Parameters:
v | Vector, of type V2, pointed to by pVec (implicit).
pMat | Pointer to the matrix to transform bounding box. Passing NULL is equivalent to providing a pointer to the identity matrix.
Returns:
If the vector is contained in the bounding box, true is returned.
See also:
IwMat

template<class V>
V CIwBBoxT< V >::GetCentre ( ) [inline]

Returns a vector with coordinates that are the average of those of m_Min and m_Max.

Returns:
the centre of the bounding box

template<class V>
void CIwBBoxT< V >::Serialise ( )

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise

Field Documentation

template<class V>
V CIwBBoxT< V >::m_Max

Maximum coordinates of vectors contained within the bounding box.

template<class V>
V CIwBBoxT< V >::m_Min

Minimum coordinates of vectors contained within the bounding box.

The documentation for this class was generated from the following file:
  • IwGeomBBox.h


Airplay API Reference: CIwBuffer::ByteProxy

Airplay API Reference > Data Structures > CIwBuffer::ByteProxy >
CIwBuffer::ByteProxy

CIwBuffer::ByteProxy Class Reference

#include <IwBuffer.h>

Detailed Description

The ByteProxy class tells the difference between lvalue and rvalue uses of operator[].
Note:
Taken from Item 30 of Scott Meyer's `More Effective C++'.
The documentation for this class was generated from the following file:
  • IwBuffer.h


Airplay API Reference: CIwColour

Airplay API Reference > Data Structures > CIwColour >

CIwColour Class Reference
[Colours]

#include <IwColour.h>

Inheritance diagram for CIwColour:

[legend]

Public Member Functions

uint32 | Get () const
CIwColour | operator * (iwfixed other)
CIwColour | operator *= (const CIwColour &other)
bool | operator!= (const CIwColour &other) const
bool | operator!= (uint32 rgba) const
CIwColour | operator+ (CIwColour other)
CIwColour | operator+= (const CIwColour &other)
CIwColour | operator-= (const CIwColour &other)
CIwColour | operator= (uint32 rgba)
bool | operator== (const CIwColour &other) const
bool | operator== (uint32 rgba) const
void | Serialise () const
void | Set (CIwColour other)
void | Set (uint8 _r, uint8 _g, uint8 _b)
void | Set (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
void | Set (uint32 rgba)
void | SetGrey (uint8 g)
void | SetOpaque (uint32 rgb)

Detailed Description

Colour object. See the Colour module overview for more information.

Required Header Files
IwColour.h

Member Function Documentation

uint32 CIwColour::Get ( ) const [inline]

Gets the colour as a uint32 value.

See also:
Set
Required Header Files
IwColour.h

CIwColour CIwColour::operator * ( iwfixed other ) [inline]

Saturated component-wise multiplication by an iwfixed scalar,

Parameters:
rhs iwfixed value to scale by.
Returns:
Result colour object itself.

CIwColour CIwColour::operator *= ( const CIwColour & other ) [inline]

Component-wise multiplication by another CIwColour object, where 0x100 is equivalent to unity.

Parameters:
other CIwColour object to scale by.
Returns:
Reference to the colour object itself.

Reimplemented in CIwUIColour.

bool CIwColour::operator!= ( const CIwColour & other ) const [inline]

Tests if colour is not equivalent to another CIwColour object.

Parameters:
other CIwColour object to test against.
Returns:
true only if the values are NOT equivalent.

bool CIwColour::operator!= ( uint32 rgba ) const [inline]

Tests if colour is not equivalent to another 32-bit value.

Parameters:
col 32-bit colour value to test against.
Returns:
true only if the values are not equivalent.

CIwColour CIwColour::operator+ ( CIwColour other ) [inline]

Saturated component-wise addition with another CIwColour object.

Parameters:
other CIwColour object to add.
Returns:
Result colour object itself.

CIwColour CIwColour::operator+= ( const CIwColour & other ) [inline]

Component-wise addition with another CIwColour object.

Parameters:
other CIwColour object to add.
Returns:
Reference to the colour object itself.

CIwColour CIwColour::operator-= ( const CIwColour & other ) [inline]

Component-wise subtraction by another CIwColour object.

Parameters:
other CIwColour object to subtract.
Returns:
Reference to the colour object itself.

CIwColour CIwColour::operator= ( uint32 rgba ) [inline]

Sets all 4 components from a single input.

Parameters:
rgba 32-bit colour value to set.
Returns:
Reference to the colour object itself.

bool CIwColour::operator== ( const CIwColour & other ) const [inline]

Tests if colour is equivalent to another CIwColour object.

Parameters:
other CIwColour object to test against.
Returns:
true only if the values are equivalent.

bool CIwColour::operator== ( uint32 rgba ) const [inline]

Tests if colour is equivalent to another 32-bit value.

Parameters:
col 32-bit colour value to test against.
Returns:
true only if the values are equivalent.

void CIwColour::Serialise ( ) const [inline]

Serialises to/from binary file.

void CIwColour::Set ( CIwColour other ) [inline]

Sets all 4 components from a single input.

Parameters:
col Colour structure to set.
See also:
SetOpaque, SetGrey
Required Header Files
IwColour.h

void CIwColour::Set | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b |
 | ) |  |  | [inline]

Sets r,g,b components with full opacity.

Parameters:
_r | 8-bit r value to set.
_g | 8-bit g value to set.
_b | 8-bit b value to set.
See also:
SetOpaque, SetGrey
Required Header Files
IwColour.h

void CIwColour::Set | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a |
 | ) |  |  | [inline]

Sets all 4 components.

Parameters:
_r | 8-bit r value to set.
_g | 8-bit g value to set.
_b | 8-bit b value to set.
_a | 8-bit a value to set.
See also:
SetOpaque, SetGrey
Required Header Files
IwColour.h

void CIwColour::Set ( uint32 rgba ) [inline]

Sets all 4 components from a single input.

Parameters:
rgba 32-bit value to set.
See also:
SetOpaque, SetGrey
Required Header Files
IwColour.h

void CIwColour::SetGrey ( uint8 g ) [inline]

Sets all 4 components from a single input, by specifying a grayscale value.

Parameters:
g Greyscale value to set (0..255).
See also:
Set, SetOpaque
Required Header Files
IwColour.h

void CIwColour::SetOpaque ( uint32 rgb ) [inline]

Sets all 4 components from a single input, and make alpha value fully opaque.

Parameters:
rgba 24-bit value to set.
See also:
Set, SetGrey
Required Header Files
IwColour.h

Field Documentation

uint8 CIwColour::a

8-bit alpha component.

uint8 CIwColour::b

8-bit blue component.

uint8 CIwColour::g

8-bit green component.

uint8 CIwColour::r

8-bit red component.

The documentation for this class was generated from the following file:
  • IwColour.h


Airplay API Reference: CIwFBBox

Airplay API Reference > Data Structures > CIwFBBox >

CIwFBBox Class Reference

Double-precision float axis-aligned bounding box.

#include <IwGeomFBBox.h>

Member Function Documentation

void CIwFBBox::BoundVec ( CIwFVec3 * pVec ) [inline]

Extend BBox to include vector.

void CIwFBBox::BoundVecs | ( | CIwFVec3 * | pVec,
 |  | uint32 | v |
 | ) |  |  | [inline]

Calculate bbox from array of vecs.

bool CIwFBBox::ContainsVec | ( | CIwFVec3 & | v,
 |  | CIwFMat * | pMat = NULL |
 | ) |  |  | [inline]

Test if bbox contains a point... possibly pass in a matrix, in which point is considered in local space.

CIwFVec3 CIwFBBox::GetCentre ( ) [inline]

Get the centre.

Field Documentation

CIwFVec3 CIwFBBox::maxV

max xyz

CIwFVec3 CIwFBBox::minV

min xyz

The documentation for this class was generated from the following file:
  • IwGeomFBBox.h


Airplay API Reference: CIwFMat

Airplay API Reference > Data Structures > CIwFMat >

CIwFMat Class Reference
[IwGeomFMat]

#include <IwGeomFMat.h>

Public Member Functions

CIwFMat (CIwFMat const &R, CIwFVec3 const &T)
CIwFMat (const CIwMat &M)
CIwFMat (float f)
CIwFMat ()
CIwFVec3 | ColumnX () const
CIwFVec3 | ColumnY () const
CIwFVec3 | ColumnZ () const
INLINE_MEMBER CIwMat | ConvertToCIwMat ()
void | CopyRot (const CIwFMat &m0)
void | CopyTrans (const CIwFMat &m0)
CIwFVec3 const & | GetTrans () const
CIwFMat | GetTranspose () const
void | InterpolatePos (CIwFMat const &m0, CIwFMat const &m1, float fraction)
void | InterpolateRot (CIwFMat const &m0, CIwFMat const &m1, float fraction)
void | InterpRot (CIwFMat const &m0, CIwFMat const &m1, float fraction)
void | InterpTrans (CIwFMat const &m0, CIwFMat const &m1, float fraction)
bool | IsIdentity () const
bool | IsRotIdentity () const
bool | IsRotSame (CIwFMat const &m0) const
bool | IsRotZero () const
bool | IsTransIdentity () const
bool | IsTransSame (CIwFMat const &m0) const
bool | IsTransZero () const
bool | IsZero () const
void | LookAt (const CIwFVec3 &from, const CIwFVec3 &to, const CIwFVec3 &up)
void | Normalise ()
CIwFMat | operator * (CIwFMat const &M) const
CIwFMat & | operator *= (const float v)
CIwFMat & | operator *= (CIwFMat const &M)
bool | operator!= (CIwFMat const &m0) const
CIwFMat | operator+ (CIwFVec3 const &V) const
CIwFMat & | operator+= (CIwFVec3 const &V)
bool | operator== (CIwFMat const &m0) const
CIwFMat & | PostMult (CIwFMat const &M)
CIwFMat & | PostMultiply (CIwFMat const &M)
CIwFMat & | PostRotate (CIwFMat const &M)
CIwFMat & | PreMult (CIwFMat const &M)
CIwFMat & | PreMultiply (CIwFMat const &M)
CIwFMat | PreRotate (CIwFMat const &M)
CIwFVec3 | RotateVec (CIwFVec3 const &V) const
INLINE_MEMBER float | RotateVecX (const CIwFVec3 &V) const
INLINE_MEMBER float | RotateVecY (const CIwFVec3 &V) const
INLINE_MEMBER float | RotateVecZ (const CIwFVec3 &V) const
CIwFVec3 | RowX () const
CIwFVec3 | RowY () const
CIwFVec3 | RowZ () const
CIwFMat & | Scale (float v)
CIwFMat & | ScaleRot (float v)
CIwFMat & | ScaleTrans (float v)
void | Serialise ()
void | SetAxisAngle (CIwFVec3 axis, float angle)
void | SetIdentity ()
INLINE_MEMBER void | SetRotX (float r=0, bool resetTrans=true, bool setZeros=true)
INLINE_MEMBER void | SetRotY (float r=0, bool resetTrans=true, bool setZeros=true)
INLINE_MEMBER void | SetRotZ (float r=0, bool resetTrans=true, bool setZeros=true)
CIwFMat & | SetTrans (CIwFVec3 const &v)
void | SetZero ()
CIwFVec3 | TransformVec (CIwFVec3 const &V) const
void | Transpose ()
CIwFVec3 | TransposeRotateVec (CIwFVec3 const &V) const
CIwFVec3 | TransposeTransformVec (CIwFVec3 const &V) const
void | Zero ()

Data Fields

float | m [3][3]
CIwFVec3 t

Static Public Attributes

static CIwFMat | g_Identity

Detailed Description

CIwFMat - Combines a 3x3 rotation and 3-vector translation.

Note:
The transformation represented by m is normally a rotation, for this reason m will be referred to as a rotation within the following documentation.
0 | 1 | 2 | 3 |  | [0][0] | [0][1] | [0][2]
4 | 5 | 6 | 7 | ==> | [1][0] | [1][1] | [1][2]
8 | 9 | 10 | 11 |  | [2][0] | [2][1] | [2][2]
12 | 13 | 14 | 15 |  | t.x | t.y | t.z
See also:
IwGeomCore

Constructor & Destructor Documentation

CIwFMat::CIwFMat ( ) [inline]

Creates a new uninitialised matrix.

CIwFMat::CIwFMat ( float f ) [inline, explicit]

Creates a new matrix of scales by parameter f along each axis.

Parameters:
f Rotation set as identity scaled by f.

CIwFMat::CIwFMat ( const CIwMat & M ) [explicit]

Creates a new matrix from the supplied matrix.

Parameters:
M Reference to matrix to copy.
See also:
CIwMat

CIwFMat::CIwFMat | ( | CIwFMat const & | R,
 |  | CIwFVec3 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (vector) translation

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to vector from which to copy translation.
See also:
CIwFVec3

Member Function Documentation

CIwFVec3 CIwFMat::ColumnX ( ) const [inline]

Vector representing the world (codomain) space X-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwFVec3::g_AxisX).

CIwFVec3 CIwFMat::ColumnY ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwFVec3::g_AxisY).

CIwFVec3 CIwFMat::ColumnZ ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwFVec3::g_AxisZ).

void CIwFMat::CopyRot ( const CIwFMat & m0 ) [inline]

Copies rotation from another matrix.

Parameters:
m0 Source matrix.

void CIwFMat::CopyTrans ( const CIwFMat & m0 ) [inline]

Copies translation from another matrix.

Parameters:
m0 Source matrix.

CIwFVec3 const& CIwFMat::GetTrans ( ) const [inline]

Gets the translation vector part of a matrix.

Returns:
Reference to the translation vector part of supplied matrix.

CIwFMat CIwFMat::GetTranspose ( ) const [inline]

Returns:
Matrix with transpose of rotation part and zero translation.

void CIwFMat::InterpolatePos | ( | CIwFMat const & | m0,
 |  | CIwFMat const & | m1,
 |  | float | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwFMat::InterpTrans(m0, m1, fraction).

void CIwFMat::InterpolateRot | ( | CIwFMat const & | m0,
 |  | CIwFMat const & | m1,
 |  | float | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwFMat::InterpRot(m0, m1, fraction).

void CIwFMat::InterpRot | ( | CIwFMat const & | m0,
 |  | CIwFMat const & | m1,
 |  | float | fraction
 | ) |  |

Linear interpolation of rotation elements.

Parameters:
m0 | Start rotation elements.
m1 | End rotation elements.
fraction Relative amount of start and end elements to use. fraction is constrained to [0, 1.0f].
fraction = 0 results in rotation being set to that of m0.
fraction = 1.0f results in rotationbeing set to that of m1.

void CIwFMat::InterpTrans | ( | CIwFMat const & | m0,
 |  | CIwFMat const & | m1,
 |  | float | fraction
 | ) |  |

Linear interpolation of translation elements.

Parameters:
m0 | Start translation elements.
m1 | End translation elements.
fraction Relative amount of start and end position to use. fraction is constrained to [0, 1.0f].
fraction = 0 results in position set to that of m0.
fraction = 1.0f results in position being set to that of m1.

bool CIwFMat::IsIdentity ( ) const [inline]

Determines if matrix is equal to the identity matrix.

bool CIwFMat::IsRotIdentity ( ) const [inline]

Determines if rotation part equal is equal to the identity rotation.

bool CIwFMat::IsRotSame ( CIwFMat const & m0 ) const [inline]

Determines if rotation part equal to another matrix.

Parameters:
m0 Matrix for comparison with.
Returns:
true if the matrices have equal rotation elements, otherwise false.

bool CIwFMat::IsRotZero ( ) const [inline]

Determines if rotation part is equal to zero.

bool CIwFMat::IsTransIdentity ( ) const [inline]

Determines if translation part equal is equal to the zero vector.

bool CIwFMat::IsTransSame ( CIwFMat const & m0 ) const [inline]

Determines if translation part of one matrix is equal to that of another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices have equal translation elements, otherwise false.

bool CIwFMat::IsTransZero ( ) const [inline]

Determines if translation part is equal to zero.

bool CIwFMat::IsZero ( ) const [inline]

Determines if matrix is equal to zero.

void CIwFMat::LookAt | ( | const CIwFVec3 & | from,
 |  | const CIwFVec3 & | to,
 |  | const CIwFVec3 & | up |
 | ) |  |  | [inline]

Creates a matrix looking between the specified points with the given up vector.

Note:
Does not affect translation vector.

Bear in mind that positive y is DOWN the screen.

void CIwFMat::Normalise ( ) [inline]

Ensures the rotation part of matrix is orthogonal. (TODO: This function could be faster using Gram-Schmidt orthogonalisation)

CIwFMat CIwFMat::operator * ( CIwFMat const & M ) const [inline]

Composes two matrices together.

Parameters:
M Matrix by which to post multiply.
Returns:
(this matrix) * M. Does not modify either input matrix.

CIwFMat& CIwFMat::operator *= ( const float v ) [inline]

Scales matrix.

Parameters:
v Scale to apply to matrix
Returns:
reference to matrix

CIwFMat& CIwFMat::operator *= ( CIwFMat const & M ) [inline]

Post multiplies matrix.

Parameters:
M Matrix by which to multiply.
Returns:
Reference to matrix.

bool CIwFMat::operator!= ( CIwFMat const & m0 ) const [inline]

Determines if matrix is not equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are not equal, otherwise false.

CIwFMat CIwFMat::operator+ ( CIwFVec3 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix.

CIwFMat& CIwFMat::operator+= ( CIwFVec3 const & V ) [inline]

Translates matrix.

Parameters:
V Vector to add onto translation part of a matrix.
Returns:
Reference to matrix.

bool CIwFMat::operator== ( CIwFMat const & m0 ) const [inline]

Determines if matrix is equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are equal, otherwise false.

CIwFMat& CIwFMat::PostMult ( CIwFMat const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to post multiply.
Returns:
(this matrix) * M. Overwrites this matrix.

CIwFMat& CIwFMat::PostMultiply ( CIwFMat const & M ) [inline]

This method is deprecated in favour of CIwFMat::PostMult(M).

CIwFMat& CIwFMat::PostRotate ( CIwFMat const & M ) [inline]

Transform the rotation part of the matrix by that of the supplied matrix.

Parameters:
M matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwFMat& CIwFMat::PreMult ( CIwFMat const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to pre multiply.
Returns:
M * (this matrix). Overwrites this matrix.

CIwFMat& CIwFMat::PreMultiply ( CIwFMat const & M ) [inline]

This method is deprecated in favour of CIwFMat::PreMult(M).

CIwFMat CIwFMat::PreRotate ( CIwFMat const & M ) [inline]

Transforms the rotation part of the matrix by that of the supplied matrix.

Parameters:
M Matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwFVec3 CIwFMat::RotateVec ( CIwFVec3 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.

INLINE_MEMBER float CIwFMat::RotateVecX ( const CIwFVec3 & V ) const [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
X-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER float CIwFMat::RotateVecY ( const CIwFVec3 & V ) const [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Y-component of vector transformed by transpose of rotation part of matrix.

INLINE_MEMBER float CIwFMat::RotateVecZ ( const CIwFVec3 & V ) const [inline]

If matrix is orthogonal, finds Z component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Z-component of vector transformed by transpose of rotation part of matrix.

CIwFVec3 CIwFMat::RowX ( ) const [inline]

Vector representing the local (domain) space X-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwFVec3::g_AxisX).
Note:
Function has alias VecX.

CIwFVec3 CIwFMat::RowY ( ) const [inline]

Vector representing the local (domain) space Y-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwFVec3::g_AxisY).
Note:
Function has alias VecY.

CIwFVec3 CIwFMat::RowZ ( ) const [inline]

Vector representing the local (domain) space Z-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwFVec3::g_AxisZ).
Note:
Function has alias VecZ.

CIwFMat& CIwFMat::Scale ( float v ) [inline]

Scales rotation and translation parts of matrix.

Parameters:
v Scale to apply to matrix.

CIwFMat& CIwFMat::ScaleRot ( float v ) [inline]

Scales rotation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

CIwFMat& CIwFMat::ScaleTrans ( float v ) [inline]

Scales translation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

void CIwFMat::Serialise ( )

Reads/writes binary file using IwSerialise interface.

See also:
IwSerialise

void CIwFMat::SetAxisAngle | ( | CIwFVec3 | axis,
 |  | float | angle
 | ) |  |

Sets matrix to be rotation by given angle around given axis with zero translation.

Parameters:
axis | Rotation axis (must be a UNIT vector).
angle | Rotation angle.

void CIwFMat::SetIdentity ( ) [inline]

Sets matrix to the identity matrix.

INLINE_MEMBER void CIwFMat::SetRotX | ( | float | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around X-axis by given angle. The rotation is determined by the element [0][0] and those of the minor matrix [0][0] of the rotation part of the matrix.

Parameters:
r | Angle of rotation
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

INLINE_MEMBER void CIwFMat::SetRotY | ( | float | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Y-axis by given angle. The rotation is determined by the element [1][1] and those of the minor matrix [1][1] of the rotation part of the matrix.

Parameters:
r | angle of rotation
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | If the rotation should be zeroed (apart from the elements which determine the rotation).

INLINE_MEMBER void CIwFMat::SetRotZ | ( | float | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis by given angle. The rotation is determined by the element [2][2] and those of the minor matrix [2][2] of the rotation part of the matrix.

Parameters:
r | Angle of rotation.
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

CIwFMat& CIwFMat::SetTrans ( CIwFVec3 const & v ) [inline]

Sets the translation vector part of a matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

void CIwFMat::SetZero ( )

Sets matrix to zero.

CIwFVec3 CIwFMat::TransformVec ( CIwFVec3 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform
Returns:
Vector transformed by matrix.

void CIwFMat::Transpose ( )

Transposes rotation part of matrix.

CIwFVec3 CIwFMat::TransposeRotateVec ( CIwFVec3 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.

CIwFVec3 CIwFMat::TransposeTransformVec ( CIwFVec3 const & V ) const [inline]

If matrix is orthogonal, performs the same operation as transforming vector by inverse of the matrix.

Parameters:
V Vector to transform.
Returns:
Vector, less translation vector, and then transformed by transpose of rotation part of matrix.

void CIwFMat::Zero ( ) [inline]

This method is deprecated in favour of CIwFMat::SetZero().

Field Documentation

CIwFMat CIwFMat::g_Identity [static]

Identity matrix.

float CIwFMat::m[3][3]

3x3 rotation matrix.

CIwFVec3 CIwFMat::t

Trans vector.

The documentation for this class was generated from the following file:
  • IwGeomFMat.h


Airplay API Reference: CIwFMat2D

Airplay API Reference > Data Structures > CIwFMat2D >

CIwFMat2D Class Reference
[IwGeomFMat2D]

#include <IwGeomFMat2D.h>

Public Member Functions

CIwFMat2D (CIwFMat2D const &R, CIwFVec2 const &T)
CIwFMat2D (const CIwMat2D &M)
CIwFMat2D (float f)
CIwFMat2D ()
CIwFVec2 | ColumnX () const
CIwFVec2 | ColumnY () const
INLINE_MEMBER CIwMat2D | ConvertToCIwMat2D ()
void | CopyRot (const CIwFMat2D &m0)
void | CopyTrans (const CIwFMat2D &m0)
CIwFMat2D | GetInverse () const
CIwFVec2 const & | GetTrans () const
CIwFMat2D | GetTranspose () const
void | InterpolatePos (CIwFMat2D const &m0, CIwFMat2D const &m1, float fraction)
void | InterpolateRot (CIwFMat2D const &m0, CIwFMat2D const &m1, float fraction)
void | InterpRot (CIwFMat2D const &m0, CIwFMat2D const &m1, float fraction)
void | InterpTrans (CIwFMat2D const &m0, CIwFMat2D const &m1, float fraction)
bool | IsIdentity ()
bool | IsRotIdentity ()
bool | IsRotSame (CIwFMat2D const &m0) const
bool | IsRotZero ()
bool | IsTransIdentity ()
bool | IsTransSame (CIwFMat2D const &m0) const
bool | IsTransZero ()
bool | IsZero ()
void | Normalise ()
CIwFMat2D | operator * (CIwFMat2D const &M) const
CIwFMat2D & | operator *= (const float v)
CIwFMat2D & | operator *= (CIwFMat2D const &M)
bool | operator!= (CIwFMat2D const &m0) const
CIwFMat2D | operator+ (CIwFVec2 const &V) const
CIwFMat2D & | operator+= (CIwFVec2 const &V)
bool | operator== (CIwFMat2D const &m0) const
CIwFMat2D & | PostMult (CIwFMat2D const &M)
CIwFMat2D & | PostMultiply (CIwFMat2D const &M)
CIwFMat2D & | PostRotate (CIwFMat2D const &M)
CIwFMat2D & | PreMult (CIwFMat2D const &M)
CIwFMat2D & | PreMultiply (CIwFMat2D const &M)
CIwFMat2D | PreRotate (CIwFMat2D const &M)
CIwFVec2 | RotateVec (CIwFVec2 const &V) const
INLINE_MEMBER float | RotateVecX (const CIwFVec2 &V)
INLINE_MEMBER float | RotateVecY (const CIwFVec2 &V)
CIwFVec2 | RowX () const
CIwFVec2 | RowY () const
CIwFMat2D & | Scale (float v)
CIwFMat2D & | ScaleRot (float v)
CIwFMat2D & | ScaleTrans (float v)
void | Serialise ()
void | SetIdentity ()
INLINE_MEMBER void | SetRot (float r, const CIwFVec2 &centre)
INLINE_MEMBER void | SetRot (float r=0, bool resetTrans=true)
CIwFMat2D & | SetTrans (CIwFVec2 const &v)
void | SetZero ()
CIwFVec2 | TransformVec (CIwFVec2 const &V) const
void | Transpose ()
CIwFVec2 | TransposeRotateVec (CIwFVec2 const &V) const
CIwFVec2 | TransposeTransformVec (CIwFVec2 const &V) const
void | Zero ()

Data Fields

float | m [2][2]
CIwFVec2 t

Static Public Attributes

static CIwFMat2D | g_Identity

Detailed Description

CIwFMat2D - Combines a 2x2 rotation and 2-vector translation.

Note:
The transformation represented by m is normally a rotation, for this reason m will be referred to as a rotation within the following documentation.
0 | 1 | 2 | 3 |  | [0][0] | [0][1] | [0][2]
4 | 5 | 6 | 7 | ==> | [1][0] | [1][1] | [1][2]
8 | 9 | 10 | 11 |  | [2][0] | [2][1] | [2][2]
12 | 13 | 14 | 15 |  | t.x | t.y | t.z
See also:
IwGeomCore

Constructor & Destructor Documentation

CIwFMat2D::CIwFMat2D ( ) [inline]

Creates a new uninitialised matrix.

CIwFMat2D::CIwFMat2D ( float f ) [inline, explicit]

Creates a new matrix of scales by parameter f along each axis.

Parameters:
f Rotation set as identity scaled by f.

CIwFMat2D::CIwFMat2D ( const CIwMat2D & M ) [explicit]

Creates a new matrix from the supplied matrix.

Parameters:
M Reference to matrix to copy.
See also:
CIwMat2D

CIwFMat2D::CIwFMat2D | ( | CIwFMat2D const & | R,
 |  | CIwFVec2 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (vector) translation

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to vector from which to copy translation.
See also:
CIwFVec2

Member Function Documentation

CIwFVec2 CIwFMat2D::ColumnX ( ) const [inline]

Vector representing the world (codomain) space X-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwFVec2::g_AxisX).

CIwFVec2 CIwFMat2D::ColumnY ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwFVec2::g_AxisY).

void CIwFMat2D::CopyRot ( const CIwFMat2D & m0 ) [inline]

Copies rotation from another matrix.

Parameters:
m0 Source matrix.

void CIwFMat2D::CopyTrans ( const CIwFMat2D & m0 ) [inline]

Copies translation from another matrix.

Parameters:
m0 Source matrix.

CIwFMat2D CIwFMat2D::GetInverse ( ) const

@ return Matrix that represents the inverse operation. Will return identity if inverse is not possible (i.e. determinant is zero)

CIwFVec2 const& CIwFMat2D::GetTrans ( ) const [inline]

Gets the translation vector part of a matrix.

Returns:
Reference to the translation vector part of supplied matrix.

CIwFMat2D CIwFMat2D::GetTranspose ( ) const [inline]

Returns:
Matrix with transpose of rotation part and zero translation.

void CIwFMat2D::InterpolatePos | ( | CIwFMat2D const & | m0,
 |  | CIwFMat2D const & | m1,
 |  | float | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwFMat2D::InterpTrans(m0, m1, fraction).

void CIwFMat2D::InterpolateRot | ( | CIwFMat2D const & | m0,
 |  | CIwFMat2D const & | m1,
 |  | float | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwFMat2D::InterpRot(m0, m1, fraction).

void CIwFMat2D::InterpRot | ( | CIwFMat2D const & | m0,
 |  | CIwFMat2D const & | m1,
 |  | float | fraction
 | ) |  |

Linear interpolation of rotation elements.

Parameters:
m0 | Start rotation elements.
m1 | End rotation elements.
fraction Relative amount of start and end elements to use. fraction is constrained to [0, 1.0f].
fraction = 0 results in rotation being set to that of m0.
fraction = 1.0f results in rotationbeing set to that of m1.

void CIwFMat2D::InterpTrans | ( | CIwFMat2D const & | m0,
 |  | CIwFMat2D const & | m1,
 |  | float | fraction
 | ) |  |

Linear interpolation of translation elements.

Parameters:
m0 | Start translation elements.
m1 | End translation elements.
fraction Relative amount of start and end position to use. fraction is constrained to [0, 1.0f].
fraction = 0 results in position set to that of m0.
fraction = 1.0f results in position being set to that of m1.

bool CIwFMat2D::IsIdentity ( ) [inline]

Determines if matrix is equal to the identity matrix.

bool CIwFMat2D::IsRotIdentity ( ) [inline]

Determines if rotation part equal is equal to the identity rotation.

bool CIwFMat2D::IsRotSame ( CIwFMat2D const & m0 ) const [inline]

Determines if rotation part equal to another matrix.

Parameters:
m0 Matrix for comparison with.
Returns:
true if the matrices have equal rotation elements, otherwise false.

bool CIwFMat2D::IsRotZero ( ) [inline]

Determines if rotation part is equal to zero.

bool CIwFMat2D::IsTransIdentity ( ) [inline]

Determines if translation part equal is equal to the zero vector.

bool CIwFMat2D::IsTransSame ( CIwFMat2D const & m0 ) const [inline]

Determines if translation part of one matrix is equal to that of another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices have equal translation elements, otherwise false.

bool CIwFMat2D::IsTransZero ( ) [inline]

Determines if translation part is equal to zero.

bool CIwFMat2D::IsZero ( ) [inline]

Determines if matrix is equal to zero.

void CIwFMat2D::Normalise ( ) [inline]

Ensures the rotation part of matrix is orthogonal. (TODO: This function could be faster using Gram-Schmidt orthogonalisation)

CIwFMat2D CIwFMat2D::operator * ( CIwFMat2D const & M ) const [inline]

Composes two matrices together.

Parameters:
M Matrix by which to post multiply.
Returns:
(this matrix) * M. Does not modify either input matrix.

CIwFMat2D& CIwFMat2D::operator *= ( const float v ) [inline]

Scales matrix.

Parameters:
v Scale to apply to matrix
Returns:
reference to matrix

CIwFMat2D& CIwFMat2D::operator *= ( CIwFMat2D const & M ) [inline]

Post multiplies matrix.

Parameters:
M Matrix by which to multiply.
Returns:
Reference to matrix.

bool CIwFMat2D::operator!= ( CIwFMat2D const & m0 ) const [inline]

Determines if matrix is not equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are not equal, otherwise false.

CIwFMat2D CIwFMat2D::operator+ ( CIwFVec2 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix.

CIwFMat2D& CIwFMat2D::operator+= ( CIwFVec2 const & V ) [inline]

Translates matrix.

Parameters:
V Vector to add onto translation part of a matrix.
Returns:
Reference to matrix.

bool CIwFMat2D::operator== ( CIwFMat2D const & m0 ) const [inline]

Determines if matrix is equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are equal, otherwise false.

CIwFMat2D& CIwFMat2D::PostMult ( CIwFMat2D const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to post multiply.
Returns:
(this matrix) * M. Overwrites this matrix.

CIwFMat2D& CIwFMat2D::PostMultiply ( CIwFMat2D const & M ) [inline]

This method is deprecated in favour of CIwFMat2D::PostMult(M).

CIwFMat2D& CIwFMat2D::PostRotate ( CIwFMat2D const & M ) [inline]

Transform the rotation part of the matrix by that of the supplied matrix.

Parameters:
M matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwFMat2D& CIwFMat2D::PreMult ( CIwFMat2D const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to pre multiply.
Returns:
M * (this matrix). Overwrites this matrix.

CIwFMat2D& CIwFMat2D::PreMultiply ( CIwFMat2D const & M ) [inline]

This method is deprecated in favour of CIwFMat2D::PreMult(M).

CIwFMat2D CIwFMat2D::PreRotate ( CIwFMat2D const & M ) [inline]

Transforms the rotation part of the matrix by that of the supplied matrix.

Parameters:
M Matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwFVec2 CIwFMat2D::RotateVec ( CIwFVec2 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.

INLINE_MEMBER float CIwFMat2D::RotateVecX ( const CIwFVec2 & V ) [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
X-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER float CIwFMat2D::RotateVecY ( const CIwFVec2 & V ) [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Y-component of vector transformed by transpose of rotation part of matrix.

CIwFVec2 CIwFMat2D::RowX ( ) const [inline]

Vector representing the local (domain) space X-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwFVec2::g_AxisX).
Note:
Function has alias VecX.

CIwFVec2 CIwFMat2D::RowY ( ) const [inline]

Vector representing the local (domain) space Y-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwFVec2::g_AxisY).
Note:
Function has alias VecY.

CIwFMat2D& CIwFMat2D::Scale ( float v ) [inline]

Scales rotation and translation parts of matrix.

Parameters:
v Scale to apply to matrix.

CIwFMat2D& CIwFMat2D::ScaleRot ( float v ) [inline]

Scales rotation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

CIwFMat2D& CIwFMat2D::ScaleTrans ( float v ) [inline]

Scales translation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

void CIwFMat2D::Serialise ( )

Reads/writes binary file using IwSerialise interface.

See also:
IwSerialise

void CIwFMat2D::SetIdentity ( ) [inline]

Sets matrix to the identity matrix.

INLINE_MEMBER void CIwFMat2D::SetRot | ( | float | r,
 |  | const CIwFVec2 & | centre |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis at a point by given angle

Parameters:
r | Angle of rotation
centre | Centre of rotation

INLINE_MEMBER void CIwFMat2D::SetRot | ( | float | r = 0,
 |  | bool | resetTrans = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis by given angle.

Parameters:
r | Angle of rotation.
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

CIwFMat2D& CIwFMat2D::SetTrans ( CIwFVec2 const & v ) [inline]

Sets the translation vector part of a matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

void CIwFMat2D::SetZero ( )

Sets matrix to zero.

CIwFVec2 CIwFMat2D::TransformVec ( CIwFVec2 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform
Returns:
Vector transformed by matrix.

void CIwFMat2D::Transpose ( )

Transposes rotation part of matrix.

CIwFVec2 CIwFMat2D::TransposeRotateVec ( CIwFVec2 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.

CIwFVec2 CIwFMat2D::TransposeTransformVec ( CIwFVec2 const & V ) const [inline]

If matrix is orthogonal, performs the same operation as transforming vector by inverse of the matrix.

Parameters:
V Vector to transform.
Returns:
Vector, less translation vector, and then transformed by transpose of rotation part of matrix.

void CIwFMat2D::Zero ( ) [inline]

This method is deprecated in favour of CIwFMat2D::SetZero().

Field Documentation

CIwFMat2D CIwFMat2D::g_Identity [static]

Identity matrix.

float CIwFMat2D::m[2][2]

2x2 rotation matrix.

CIwFVec2 CIwFMat2D::t

Trans vector.

The documentation for this class was generated from the following file:
  • IwGeomFMat2D.h


Airplay API Reference: CIwFQuat

Airplay API Reference > Data Structures > CIwFQuat >

CIwFQuat Class Reference
[IwGeomFQuat]

#include <IwGeomFQuat.h>

Public Member Functions

CIwFQuat (CIwFVec3 const &v, float theta)
CIwFQuat (float s)
CIwFQuat (CIwFMat const &mat)
CIwFQuat (float s, float x, float y, float z)
CIwFQuat ()
float | GetLength () const
float | GetLengthSquared () const
float | GetRotationAngle ()
CIwFVec3 GetRotationAxis ()
void | Lerp (const CIwFQuat &startQ, const CIwFQuat &endQ, float const t)
CIwFQuat & NormaliseInPlace ()
CIwFQuat | operator * (float const l) const
CIwFQuat | operator * (CIwFQuat const &q) const
operator CIwFMat () const
bool | operator!= (CIwFQuat const &q) const
CIwFQuat | operator+ (CIwFQuat const &q) const
CIwFQuat | operator- (CIwFQuat const &q) const
CIwFQuat | operator- () const
CIwFQuat & | operator= (CIwFQuat const &q)
bool | operator== (CIwFQuat const &q) const
CIwFVec3 | RotateVector (CIwFVec3 const &v) const
void | Serialise ()
void | SetAxisAngle (float x, float y, float z, float theta)
void | Slerp (const CIwFQuat &startQ, const CIwFQuat &endQ, float const t)

Data Fields

float | s

Static Public Attributes

static CIwFQuat | g_Identity

Detailed Description

CIwFQuat - Floating-point quaternion with 32-bit components.

Constructor & Destructor Documentation

CIwFQuat::CIwFQuat ( ) [inline]

Creates a new quaternion with unit real compoent and zero imaginary component.

CIwFQuat::CIwFQuat | ( | float | s,
 |  | float | x,
 |  | float | y,
 |  | float | z |
 | ) |  |  | [inline]

Creates a new quaternion with supplied components.

Parameters:
s,x,y,z components to initialise quaternion

CIwFQuat::CIwFQuat ( CIwFMat const & mat )

Creates a new quaternion representing the same rotation as the supplied matrix.

Parameters:
mat It is assumed the rotation part of the matrix is orthogonal (represents a spacial rotation).

CIwFQuat::CIwFQuat ( float s ) [inline]

Creates a new quaternion with given real component and zero imaginary component.

Parameters:
s Real component.

CIwFQuat::CIwFQuat | ( | CIwFVec3 const & | v,
 |  | float | theta |
 | ) |  |  | [inline]

Creates a new quaternion with the supplied axis and angle.

Parameters:
Axis | of rotation.
Angle | of rotation.

Member Function Documentation

float CIwFQuat::GetLength ( ) const

Calculates the quaternion's length.

Returns:
Square root of the quaternion's inner product with itself.

float CIwFQuat::GetLengthSquared ( ) const

Calculates the square of the quaternion's length.

Returns:
The inner product of the quaternion with itself.

float CIwFQuat::GetRotationAngle ( ) [inline]

Gets the angle of rotation the quaternion represents.

Returns:
Twice the arccos of the real part of the quaternion.

CIwFVec3 CIwFQuat::GetRotationAxis ( ) [inline]

Gets a normalised eigenvector of the rotation the quaternion represents.

Returns:
Normalised imaginary part of quaternion.

void CIwFQuat::Lerp | ( | const CIwFQuat & | startQ,
 |  | const CIwFQuat & | endQ,
 |  | float const | t
 | ) |  |

Linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

CIwFQuat& CIwFQuat::NormaliseInPlace ( ) [inline]

Scales quaternion so it has unit length.

Returns:
Reference to quaternion.

CIwFQuat CIwFQuat::operator * ( float const l ) const [inline]

Scale operator.

CIwFQuat CIwFQuat::operator * ( CIwFQuat const & q ) const [inline]

Calculates quaternion product.

Parameters:
q Quaternion with which to find product.
Returns:
quaternion representing the rotation by this quaternion and then by q.

CIwFQuat::operator CIwFMat ( ) const [inline]

Matrix operator.

Returns:
Matrix of rotation represented by this quaternion.

bool CIwFQuat::operator!= ( CIwFQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q Quaternion for comparison.
Returns:
False if components of quaternions are the same, otherwise true.

CIwFQuat CIwFQuat::operator+ ( CIwFQuat const & q ) const [inline]

Sum operator.

Parameters:
q Quaternion to sum this quaternion with
Returns:
Quaternion with components that are the sum of the supplied quaternions.

CIwFQuat CIwFQuat::operator- ( CIwFQuat const & q ) const [inline]

Difference operator.

Parameters:
q Quaternion to difference this quaternion with
Returns:
Quaternion with components that are the difference of the supplied quaternions.

CIwFQuat CIwFQuat::operator- ( ) const [inline]

Conjugates quaternion.

Returns:
A quaternion which represents the opposite rotation

CIwFQuat& CIwFQuat::operator= ( CIwFQuat const & q ) [inline]

Assignment operator.

Parameters:
q Quaternion from which to copy components.
Returns:
Reference to this quaternion.

bool CIwFQuat::operator== ( CIwFQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q quaternion for comparison
Returns:
true iff components of quaternions are the same

CIwFVec3 CIwFQuat::RotateVector ( CIwFVec3 const & v ) const [inline]

Parameters:
v Vector to rotate.
Returns:
Rotated vector.

void CIwFQuat::Serialise ( ) [inline]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise

void CIwFQuat::SetAxisAngle | ( | float | x,
 |  | float | y,
 |  | float | z,
 |  | float | theta
 | ) |  |

Sets quaternion representing the rotation around the supplied aixis by the supplied angle.

Parameters:
axis | Rotation axis - assumed to be normalised.
angle30 | Rotation angle, where 1.0f represents a rotation of 360 degrees.

void CIwFQuat::Slerp | ( | const CIwFQuat & | startQ,
 |  | const CIwFQuat & | endQ,
 |  | float const | t
 | ) |  |

Spherical linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

Field Documentation

CIwFQuat CIwFQuat::g_Identity [static]

Identity unit quaternion.

float CIwFQuat::s

Quaternion components

The documentation for this class was generated from the following file:
  • IwGeomFQuat.h


Airplay API Reference: CIwFSphere

Airplay API Reference > Data Structures > CIwFSphere >

CIwFSphere Class Reference

Floating-point sphere:.

#include <IwGeomFSphere.h>

Member Function Documentation

void CIwFSphere::BoundVecs | ( | CIwFVec3 * | pVec,
 |  | uint32 | v |
 | ) |  |  | [inline]

Calculate bsphere from array of vecs.

void CIwFSphere::Combine ( CIwFSphere & rhs ) [inline]

Produce smallest bsphere that compasses this sphere and the other.

Field Documentation

float CIwFSphere::r

radius

float CIwFSphere::r2

radius squared

CIwFVec3 CIwFSphere::t

origin

The documentation for this class was generated from the following file:
  • IwGeomFSphere.h


Airplay API Reference: CIwFVec2

Airplay API Reference > Data Structures > CIwFVec2 >

CIwFVec2 Class Reference
[IwGeomFVec2]

#include <IwGeomFVec2.h>

Public Member Functions

CIwFVec2 (float _x, float _y)
CIwFVec2 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER float | Dot (CIwFVec2 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

float | GetLength () const
float | GetLengthSquared () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwFVec2 | GetNormalised () const
bool | IsNormalised () const
void | Normalise ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwFVec2 | operator * (float l) const
CIwFVec2 & | operator *= (float l)
VALUE_IN_REGS CIwFVec2 | operator- () const
VALUE_IN_REGS CIwFVec2 | operator/ (const float s) const
VALUE_IN_REGS float | operator[] (const int n) const
VALUE_IN_REGS float & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

float | operator * (CIwFVec2 const &v) const
bool | operator!= (CIwFVec2 const &v) const
VALUE_IN_REGS CIwFVec2 | operator+ (CIwFVec2 const &v) const
CIwFVec2 & | operator+= (CIwFVec2 const &v)
VALUE_IN_REGS CIwFVec2 | operator- (CIwFVec2 const &v) const
CIwFVec2 & | operator-= (CIwFVec2 const &v)
CIwFVec2 & | operator= (CIwFVec2 const &v)
bool | operator== (CIwFVec2 const &v) const
VALUE_IN_REGS CIwFVec2 | operator^ (CIwFVec2 const &v) const

Static Public Attributes

static CIwFVec2 | g_AxisX
static CIwFVec2 | g_AxisY
static CIwFVec2 | g_Zero

Detailed Description

CIwFVec2

Constructor & Destructor Documentation

CIwFVec2::CIwFVec2 ( ) [inline]

Constructor: creates a new vector.

CIwFVec2::CIwFVec2 | ( | float | _x,
 |  | float | _y |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component

Member Function Documentation

INLINE_MEMBER float CIwFVec2::Dot ( CIwFVec2 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

float CIwFVec2::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

float CIwFVec2::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

CIwFVec2 CIwFVec2::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

bool CIwFVec2::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwFVec2::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwFVec2::Normalise ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwFVec2::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwFVec2 CIwFVec2::g_AxisX [static]

World X-axis.

CIwFVec2 CIwFVec2::g_AxisY [static]

World Y-axis.

CIwFVec2 CIwFVec2::g_Zero [static]

Zero vector.

float CIwFVec2::x

x-coordinate of the vector

float CIwFVec2::y

y-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomFVec2.h


Airplay API Reference: CIwFVec3

Airplay API Reference > Data Structures > CIwFVec3 >

CIwFVec3 Class Reference
[IwGeomFVec3]

#include <IwGeomFVec3.h>

Public Member Functions

CIwFVec3 (float _x, float _y, float _z)
CIwFVec3 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

VALUE_IN_REGS INLINE_MEMBER
CIwFVec3 		Cross (CIwFVec3 const &v) const
INLINE_MEMBER float | Dot (CIwFVec3 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

float | GetLength () const
float | GetLengthSquared () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwFVec3 | GetNormalised () const
bool | IsNormalised () const
void | Normalise ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwFVec3 | operator * (float l) const
CIwFVec3 & | operator *= (float l)
VALUE_IN_REGS CIwFVec3 | operator- () const
VALUE_IN_REGS CIwFVec3 | operator/ (const float s) const
VALUE_IN_REGS float | operator[] (const int n) const
VALUE_IN_REGS float & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

float | operator * (CIwFVec3 const &v) const
bool | operator!= (CIwFVec3 const &v) const
VALUE_IN_REGS CIwFVec3 | operator+ (CIwFVec3 const &v) const
CIwFVec3 & | operator+= (CIwFVec3 const &v)
VALUE_IN_REGS CIwFVec3 | operator- (CIwFVec3 const &v) const
CIwFVec3 & | operator-= (CIwFVec3 const &v)
CIwFVec3 & | operator= (CIwFVec3 const &v)
bool | operator== (CIwFVec3 const &v) const
VALUE_IN_REGS CIwFVec3 | operator^ (CIwFVec3 const &v) const

Static Public Attributes

static CIwFVec3 | g_AxisX
static CIwFVec3 | g_AxisY
static CIwFVec3 | g_AxisZ
static CIwFVec3 | g_Zero

Detailed Description

CIwFVec3

Constructor & Destructor Documentation

CIwFVec3::CIwFVec3 ( ) [inline]

Constructor: creates a new vector.

CIwFVec3::CIwFVec3 | ( | float | _x,
 |  | float | _y,
 |  | float | _z |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component

Member Function Documentation

VALUE_IN_REGS INLINE_MEMBER CIwFVec3 CIwFVec3::Cross ( CIwFVec3 const & v ) const [inline]

Cross product.

Parameters:
Vector for cross product operation.
Returns:
Resulting vector.

INLINE_MEMBER float CIwFVec3::Dot ( CIwFVec3 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

float CIwFVec3::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

float CIwFVec3::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

CIwFVec3 CIwFVec3::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

bool CIwFVec3::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwFVec3::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwFVec3::Normalise ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwFVec3::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwFVec3 CIwFVec3::g_AxisX [static]

World X-axis.

CIwFVec3 CIwFVec3::g_AxisY [static]

World Y-axis.

CIwFVec3 CIwFVec3::g_AxisZ [static]

World Z-axis.

CIwFVec3 CIwFVec3::g_Zero [static]

Zero vector.

float CIwFVec3::x

x-coordinate of the vector

float CIwFVec3::y

y-coordinate of the vector

float CIwFVec3::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomFVec3.h


Airplay API Reference: CIwFVec4

Airplay API Reference > Data Structures > CIwFVec4 >

CIwFVec4 Class Reference
[IwGeomFVec4]

#include <IwGeomFVec4.h>

Public Member Functions

CIwFVec4 (float _x, float _y, float _z, float _w)
CIwFVec4 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER float | Dot (CIwFVec4 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

float | GetLength () const
float | GetLengthSquared () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwFVec4 | GetNormalised () const
bool | IsNormalised () const
void | Normalise ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwFVec4 | operator * (float l) const
CIwFVec4 & | operator *= (float l)
VALUE_IN_REGS CIwFVec4 | operator- () const
VALUE_IN_REGS CIwFVec4 | operator/ (const float s) const
VALUE_IN_REGS float | operator[] (const int n) const
VALUE_IN_REGS float & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

float | operator * (CIwFVec4 const &v) const
bool | operator!= (CIwFVec4 const &v) const
VALUE_IN_REGS CIwFVec4 | operator+ (CIwFVec4 const &v) const
CIwFVec4 & | operator+= (CIwFVec4 const &v)
VALUE_IN_REGS CIwFVec4 | operator- (CIwFVec4 const &v) const
CIwFVec4 & | operator-= (CIwFVec4 const &v)
CIwFVec4 & | operator= (CIwFVec4 const &v)
bool | operator== (CIwFVec4 const &v) const
VALUE_IN_REGS CIwFVec4 | operator^ (CIwFVec4 const &v) const

Static Public Attributes

static CIwFVec4 | g_AxisW
static CIwFVec4 | g_AxisX
static CIwFVec4 | g_AxisY
static CIwFVec4 | g_AxisZ
static CIwFVec4 | g_Zero

Detailed Description

CIwFVec4

Constructor & Destructor Documentation

CIwFVec4::CIwFVec4 ( ) [inline]

Constructor: creates a new vector.

CIwFVec4::CIwFVec4 | ( | float | _x,
 |  | float | _y,
 |  | float | _z,
 |  | float | _w |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component
_w | W-component

Member Function Documentation

INLINE_MEMBER float CIwFVec4::Dot ( CIwFVec4 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

float CIwFVec4::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

float CIwFVec4::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

CIwFVec4 CIwFVec4::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

bool CIwFVec4::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwFVec4::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwFVec4::Normalise ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwFVec4::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwFVec4 CIwFVec4::g_AxisW [static]

World W-axis.

CIwFVec4 CIwFVec4::g_AxisX [static]

World X-axis.

CIwFVec4 CIwFVec4::g_AxisY [static]

World Y-axis.

CIwFVec4 CIwFVec4::g_AxisZ [static]

World Z-axis.

CIwFVec4 CIwFVec4::g_Zero [static]

Zero vector.

float CIwFVec4::w

w-coordinate of the vector

float CIwFVec4::x

x-coordinate of the vector

float CIwFVec4::y

y-coordinate of the vector

float CIwFVec4::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomFVec4.h


Airplay API Reference: CIwGxFontPreparedData

Airplay API Reference > Data Structures > CIwGxFontPreparedData >

CIwGxFontPreparedData Class Reference
[IwGxFont API Reference]

#include <IwGxFontPreparedData.h>

Public Member Functions

void | Clear ()
CIwRect | GetCharacterArea (uint32 c) const
int32 | GetHeight () const
int32 | GetLineEnd (uint32 line) const
int32 | GetLineStart (uint32 line) const
CIwSVec2 | GetNextCharacterPosition () const
uint32 | GetNumChars () const
uint32 | GetNumLines () const
int32 | GetWidth () const
void | MoveCharacters (int32 c1, int32 c2, const CIwSVec2 &offset)
void | Reserve (int numChar, int numLines, bool allowGrowth=true)

Detailed Description

Structure for holding prepared text.

Member Function Documentation

void CIwGxFontPreparedData::Clear ( )

Free all owned memory

CIwRect CIwGxFontPreparedData::GetCharacterArea ( uint32 c ) const

Get a CIwRect representing the area of the character at index c.

Parameters:
c The index of the character to query.
Returns:
CIwRect representing the area of the character at index c

int32 CIwGxFontPreparedData::GetHeight ( ) const [inline]

Get the height of the formatted data.

Returns:
height of the formatted data.

int32 CIwGxFontPreparedData::GetLineEnd ( uint32 line ) const

Get the index of the last character in the specified line. If the line is empty (i.e. contains no characters) the index of the last character will be less than the index of the first character.

Parameters:
line The line to query
Returns:
index of the last glyph in the specified line

int32 CIwGxFontPreparedData::GetLineStart ( uint32 line ) const

Get the index of the first character in the specified line

Parameters:
line The line to query
Returns:
index of the first character in the specified line

CIwSVec2 CIwGxFontPreparedData::GetNextCharacterPosition ( ) const

Get the position at which formatting should start to follow this text.

Returns:
position at which formatting should start to follow this text.
See also:
IwGxFontSetFormatStart

uint32 CIwGxFontPreparedData::GetNumChars ( ) const

Get the total number of characters in the text.

Note:
The CIwGxFontPreparedData will generally contain fewer characters than were passed to IwGxFontPrepareText, because whitespace characters are discarded.
Returns:
total number of characters in the text.

uint32 CIwGxFontPreparedData::GetNumLines ( ) const

Get the number of lines in the formatted block.

Returns:
number of lines in the formatted block.

int32 CIwGxFontPreparedData::GetWidth ( ) const [inline]

Get the width of the formatted data.

Returns:
width of the formatted data.

void CIwGxFontPreparedData::MoveCharacters | ( | int32 | c1,
 |  | int32 | c2,
 |  | const CIwSVec2 & | offset
 | ) |  |

Move the characters between these indices (inclusive) by a standard offset.

Parameters:
c1 | Index of first character to move
c2 | Index of last character to move
offset | Distance to move each character

void CIwGxFontPreparedData::Reserve | ( | int | numChar,
 |  | int | numLines,
 |  | bool | allowGrowth = true
 | ) |  |

Reserve storage.

Parameters:
numChar | Max number of characters
numLines | Max number of lines

The documentation for this class was generated from the following file:
  • IwGxFontPreparedData.h


Airplay API Reference: CIwGxShaderTechnique

Airplay API Reference > Data Structures > CIwGxShaderTechnique >

CIwGxShaderTechnique Class Reference
[OpenGL ES 2.x Shader Techniques]

#include <IwGxShaderTechnique.h>

Inheritance diagram for CIwGxShaderTechnique:

[legend]

Public Member Functions

CIwGxShaderUniform * | GetParam (const char *name, bool allowNull=false)
bool | IsEnabled ()
void | LoadTemp ()
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
void | SaveTemp ()
void | Serialise ()
void | SetEnabled (bool enable)

Detailed Description

A shader technique

Member Function Documentation

CIwGxShaderUniform* CIwGxShaderTechnique::GetParam | ( | const char * | name,
 |  | bool | allowNull = false
 | ) |  |

Get a named uniform parameter

Parameters:
name | the name to retrieve
allowNull | if false, assert on missing parameters. if true, fail silently A uniform parameter object (NULL if not found)
Required Header Files
IwGx.h

bool CIwGxShaderTechnique::IsEnabled ( ) [inline]

Test whether this shader is enabled. whether this shader is enabled.

Required Header Files
IwGx.h

void CIwGxShaderTechnique::LoadTemp ( )

Load GLSL code from 'vertex_shader.txt' and 'fragment_shader.txt' and recompile the shader. This can be used with SaveTemp() to quickly edit shaders.

Required Header Files
IwGx.h

virtual bool CIwGxShaderTechnique::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

virtual void CIwGxShaderTechnique::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwGxShaderTechnique::SaveTemp ( )

Save the current GLSL code to 'vertex_shader.txt' and 'fragment_shader.txt'. This can be used with LoadTemp() to quickly edit shaders.

Required Header Files
IwGx.h

void CIwGxShaderTechnique::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwGxShaderTechnique::SetEnabled ( bool enable ) [inline]

Enable this shader. Use this shader when it is attached to a material. By default, shaders are always enabled. If a shader is disabled IwGx will use the default fixed function shader for the material.

Parameters:
enable whether to enable the shader.
Required Header Files
IwGx.h

The documentation for this class was generated from the following file:
  • IwGxShaderTechnique.h


Airplay API Reference: CIwGxShaderUniform

Airplay API Reference > Data Structures > CIwGxShaderUniform >

CIwGxShaderUniform Class Reference
[OpenGL ES 2.x Shader Techniques]

#include <IwGxShaderTechnique.h>

Public Member Functions

int32 | GetArraySize ()
int32 | GetElementSize ()
int32 | GetElementType ()
void | Set (CIwMat &value, int32 offset=0)
void | Set (CIwSVec3 &value, int32 offset=0)
void | Set (CIwVec3 &value, int32 offset=0)
void | Set (float value, int32 offset=0)
void | Set (CIwGxShaderUniformType type, int32 offset, const void *value)
void | SetWorldSpace (const CIwVec3 &pos, int32 offset=0)
void | SetWorldSpaceDirection (const CIwVec3 &pos, int32 offset=0)

Detailed Description

A shader uniform parameter. Uniform parameters can be exposed for runtime alteration by code using the 'param' or 'instanceParam' itx commands.

Member Enumeration Documentation

enum CIwGxShaderUniform::CIwGxShaderUniform

Enumerator:
FLOAT | 'float' GLSL type (or equivalent)
VEC2 | 'vec2' GLSL type (or equivalent)
VEC3 | 'vec3' GLSL type (or equivalent)
VEC4 | 'vec4' GLSL type (or equivalent)
INT | 'int' GLSL type (or equivalent)
IVEC2 | 'ivec2' GLSL type (or equivalent)
IVEC3 | 'ivec3' GLSL type (or equivalent)
IVEC4 | 'ivec4' GLSL type (or equivalent)
MAT2 | 'mat2' GLSL type (or equivalent)
MAT3 | 'mat3' GLSL type (or equivalent)
MAT4 | 'mat4' GLSL type (or equivalent)

Member Function Documentation

int32 CIwGxShaderUniform::GetArraySize ( ) [inline]

Get the number of elements in the uniform array The number of elements in the uniform array

Required Header Files
IwGx.h

int32 CIwGxShaderUniform::GetElementSize ( ) [inline]

Get the size of each uniform component the size (in dwords) of each component

Required Header Files
IwGx.h

int32 CIwGxShaderUniform::GetElementType ( ) [inline]

Get the type of each uniform component the type of each component

Required Header Files
IwGx.h

void CIwGxShaderUniform::Set | ( | CIwMat & | value,
 |  | int32 | offset = 0
 | ) |  |

Set a fixed point matrix value as a float matrix. The uniform can have any GLSL 'mat' type. If the type is 'mat2' the top left of the matrix will be used. If the type is 'mat3' the rotation part of the matrix will be used. If the type is 'mat4' the whole matrix will be used. Note that the translation part will not be cast to float (for consistency with standard IwGx vertex input).

Parameters:
value | The value to set.
offset | The array index to set.
Required Header Files
IwGx.h

void CIwGxShaderUniform::Set | ( | CIwSVec3 & | value,
 |  | int32 | offset = 0
 | ) |  |

Set a short fixed point vector value as a float. The uniform must have the GLSL type 'vec3'. The fixed point values will be converted to float.

Parameters:
value | The value to set.
offset | The array index to set.
Required Header Files
IwGx.h

void CIwGxShaderUniform::Set | ( | CIwVec3 & | value,
 |  | int32 | offset = 0
 | ) |  |

Set a fixed point vector value as a float. The uniform must have the GLSL type 'vec3'. The fixed point values will be converted to float.

Parameters:
value | The value to set.
offset | The array index to set.
Required Header Files
IwGx.h

void CIwGxShaderUniform::Set | ( | float | value,
 |  | int32 | offset = 0
 | ) |  |

Set a float value. The uniform must have the GLSL type 'float'

Parameters:
value | The value to set.
offset | The array index to set.
Required Header Files
IwGx.h

void CIwGxShaderUniform::Set | ( | CIwGxShaderUniformType | type,
 |  | int32 | offset,
 |  | const void * | value
 | ) |  |

Generic set value.

Parameters:
type | The type of value. This must match the type of the uniform.
offset | The array index to set.
value | A pointer to the value to set
Required Header Files
IwGx.h

void CIwGxShaderUniform::SetWorldSpace | ( | const CIwVec3 & | pos,
 |  | int32 | offset = 0
 | ) |  |

Set a world space position. This position will be transformed into the current coordinate space before being set into the shader.

Parameters:
pos | A world space position.
offset | The array index to set.
Required Header Files
IwGx.h

void CIwGxShaderUniform::SetWorldSpaceDirection | ( | const CIwVec3 & | pos,
 |  | int32 | offset = 0
 | ) |  |

Set a world space direction. This direction will be transformed into the current coordinate space before being set into the shader.

Parameters:
pos | A world space direction.
offset | The array index to set.
Required Header Files
IwGx.h

The documentation for this class was generated from the following file:
  • IwGxShaderTechnique.h


Airplay API Reference: CIwGxStream

Airplay API Reference > Data Structures > CIwGxStream >

CIwGxStream Class Reference
[Stream Objects]

#include <IwGxStream.h>

Public Types

enum | Type

Public Member Functions

CIwGxStream (CIwGxStream &share, uint16 type, uint16 offset)
CIwGxStream (uint16 *data, uint32 length=0)
CIwGxStream (CIwColour *data, uint32 length=0)
CIwGxStream (CIwSVec3 *data, uint32 length=0)
CIwGxStream (CIwSVec2 *data, uint32 length=0)
CIwGxStream (Type type, void *data, uint32 length=0, uint16 stride=0)
CIwGxStream ()
void | Free ()
CIwColour * | GetColour () const
void * | GetData () const
int32 | GetLength () const
uint32 | GetMemSize () const
uint16 | GetOffset () const
uint16 | GetStride () const
CIwSVec2 * | GetSVec2 () const
CIwSVec3 * | GetSVec3 () const
uint16 | GetType () const
uint16 * | GetUInt16 () const
void | Upload (bool staticUsage, bool freeLocal)

Detailed Description

A retained stream

Member Enumeration Documentation

enum CIwGxStream::Type

Data type description. A full type must be constructed by or-ing a TYPE_ element and a COMPONENTS_ element.

Types for default IwGx streams are provided.

Enumerator:
TYPE_INT8 | element type: int8
TYPE_UINT8 | element type: uint8
TYPE_INT16 | element type: int16
TYPE_UINT16 | element type: uint16
TYPE_FLOAT | element type: float
TYPE_FIXED | element type: int32 in GL fixed format (1:15:16)
COMPONENTS_1 | element type: scalar values
COMPONENTS_2 | element type: 2 component vector
COMPONENTS_3 | element type: 3 component vector
COMPONENTS_4 | element type: 4 component vector
SVEC3 | CIwSVec3 (COMPONENTS_3 | TYPE_INT16).
SVEC2 | CIwSVec2 (COMPONENTS_2 | TYPE_INT16).
COLOUR | CIwColour (COMPONENTS_4 | TYPE_UINT8).
UINT16 | uint16 (COMPONENTS_1 | TYPE_UINT16)

Constructor & Destructor Documentation

CIwGxStream::CIwGxStream ( ) [inline]

Default constructor

Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | Type | type,
 |  | void * | data,
 |  | uint32 | length = 0,
 |  | uint16 | stride = 0 |
 | ) |  |  | [inline]

Generic constructor.

Parameters:
type | Type of each element of data
data | Pointer to data
length | Number of elements
stride | Stride of data (0 is tightly packed)
Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | CIwSVec2 * | data,
 |  | uint32 | length = 0 |
 | ) |  |  | [inline]

Type aware constructor.

Parameters:
data | Pointer to data
length | Number of elements
Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | CIwSVec3 * | data,
 |  | uint32 | length = 0 |
 | ) |  |  | [inline]

Type aware constructor.

Parameters:
data | Pointer to data
length | Number of elements
Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | CIwColour * | data,
 |  | uint32 | length = 0 |
 | ) |  |  | [inline]

Type aware constructor.

Parameters:
data | Pointer to data
length | Number of elements
Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | uint16 * | data,
 |  | uint32 | length = 0 |
 | ) |  |  | [inline]

Type aware constructor.

Parameters:
data | Pointer to data
length | Number of elements
Required Header Files
IwGx.h

CIwGxStream::CIwGxStream | ( | CIwGxStream & | share,
 |  | uint16 | type,
 |  | uint16 | offset |
 | ) |  |  | [inline]

Create a substream which has the specified offset (shared stream should be uploaded prior to this call)

Parameters:
share | An uploaded stream containing interleaved data
type | The type of this stream
offset | The offset to the first element of this stream in the parent stream (in bytes)
Required Header Files
IwGx.h

Member Function Documentation

void CIwGxStream::Free ( )

Free any storage allocated for this stream, including client and HW memory.

Required Header Files
IwGx.h

CIwColour* CIwGxStream::GetColour ( ) const [inline]

Get a pointer to CIwColour contents of the client data. If the client data is not a tightly packed array of CIwColour objects. NULL will be returned. pointer to client memory or NULL

Required Header Files
IwGx.h

void* CIwGxStream::GetData ( ) const [inline]

Get a pointer to the client data (may be NULL if the stream is uninitialised or uploaded) pointer to the client data

Required Header Files
IwGx.h

int32 CIwGxStream::GetLength ( ) const [inline]

Get the length (in elements) of the stream the length (in elements) of the stream

Required Header Files
IwGx.h

uint32 CIwGxStream::GetMemSize ( ) const

Get the memory size (in bytes) of the stream the memory size (in bytes) of the stream

Required Header Files
IwGx.h

uint16 CIwGxStream::GetOffset ( ) const [inline]

Get the offset (in bytes) of the first element in the stream the offset (in bytes) of the first element in the stream

Required Header Files
IwGx.h

uint16 CIwGxStream::GetStride ( ) const [inline]

Get the stride (in bytes) of the stream the stride (in bytes) of the stream

Required Header Files
IwGx.h

CIwSVec2* CIwGxStream::GetSVec2 ( ) const [inline]

Get a pointer to CIwSVec2 contents of the client data. If the client data is not a tightly packed array of CIwSVec2 objects. NULL will be returned. pointer to client memory or NULL

Required Header Files
IwGx.h

CIwSVec3* CIwGxStream::GetSVec3 ( ) const [inline]

Get a pointer to CIwSVec3 contents of the client data. If the client data is not a tightly packed array of CIwSVec3 objects. NULL will be returned. pointer to client memory or NULL

Required Header Files
IwGx.h

uint16 CIwGxStream::GetType ( ) const [inline]

Get the type descriptor of the client data type descriptor of the client data

Required Header Files
IwGx.h

uint16* CIwGxStream::GetUInt16 ( ) const [inline]

Get a pointer to uint16 contents of the client data. If the client data is not a tightly packed array of uint16 objects. NULL will be returned. pointer to client memory or NULL

Required Header Files
IwGx.h

void CIwGxStream::Upload | ( | bool | staticUsage,
 |  | bool | freeLocal
 | ) |  |

Upload the stream. A rasterister-specific object will be created that corresponds to the client data. If freeLocal is true then the client data will be freed.

Note:
The stream may be converted to a different format if the device is known to not support the client format.

By default the client data is never freed in upload (it will be freed when Free called on the stream). IwGx requires applications to opt-in to stream freeing using [GX] FreeStreamData=1 since it requires extra care to write code that doesn't rely on access to client data.

Upload may not actually upload if the current rasteriser has no support for retained streams, or stream uploading has been disabled globally in the icf using [GX] UploadStreams=0. In this case the client data will not be freed.

Parameters:
staticUsage | Should always be true. Dynamic buffers will be exposed in a future SDK revision.
freeLocal | If true, the data can be safely deleted.
Required Header Files
IwGx.h

The documentation for this class was generated from the following file:
  • IwGxStream.h


Airplay API Reference: CIwGxSurface

Airplay API Reference > Data Structures > CIwGxSurface >

CIwGxSurface Class Reference
[Surfaces and Render Targets]

#include <IwGxSurface.h>

Public Types

enum
enum | CIwGxSurfaceImplementation

Public Member Functions

bool | CreateSurface (CIwTexture *pTexture, uint32 width, uint32 height, uint32 usage)
uint32 | GetClientHeight ()
const CIwSVec2 & | GetClientUVExtent ()
uint32 | GetClientWidth ()
uint32 | GetHeight ()
CIwGxSurfaceImplementation GetImplementation ()
const s3eSurfaceInfo & | GetSurfaceInfo ()
INLINE_MEMBER CIwTexture * | GetTexture ()
uint32 | GetWidth ()
bool | HasAlphaChannel ()
bool | IsValid ()
void | MakeCurrent ()
bool | RecreateSurface (uint32 width, uint32 height)

Static Public Member Functions

static void | MakeDisplayCurrent ()

Detailed Description

A surface that can be used as a render target

Member Enumeration Documentation

anonymous enum

Surface usage flags

Enumerator:
EXACT_MATCH_F | Get a surface which exactly matches the size. If a surface this size cannot be created the largest possible surface with the same aspect ratio will be created.
ALPHA_F | Get a surface with an alpha channel. It may not be possible to create a surface with an alpha channel, if so the resulting will return false from HasAlphaChannel().
PERSISTENT_F | Get a surface which has a persistent state. Surface creation will fail if not available.
FREE_ASPECT_F | Allow any aspect ratio... default will match aspect in width/height creation arguments.
PRESERVE_FRAME_BUFFER_F | Selecting this surface must not invalidate the frame buffer. Surface creation will fail if not available.
CREATE_565_SURFACE_F | Get a surface that has a RGB565 surface pixel type.
CREATE_8888_SURFACE_F | Get a surface that has an ARGB8888 surface pixel type.

enum CIwGxSurface::CIwGxSurface

Underlying surface implementation

Enumerator:
SW | SW renderer surface. Surface switches are cheap.
CTI | EGL1.0 glCopyTexImage using frame buffer. Surface switches require a copy of the surface, making them expensive for larger surfaces. NB. If PERSISTENT_F is set, a copy is required on MakeCurrent also.
EGL_10 | EGL1.0 glCopyTexImage using 'real' surface. Surface switches require a copy of the surface, making them expensive for larger surfaces.
EGL_11 | EGL1.1 glBindTexImage using 'real' surface. Surface switches should not require a copy of the surface. However context switches are still generally fairly expensive.
FBO_OES | GL1.x Frame Buffer Object via GL_OES_framebuffer_object extension. Surface switches should be cheap, but in practise it varies from driver to driver.
FBO | GL2.0 Frame Buffer Object. Surface switches are generally cheap.

Member Function Documentation

bool CIwGxSurface::CreateSurface | ( | CIwTexture * | pTexture,
 |  | uint32 | width,
 |  | uint32 | height,
 |  | uint32 | usage
 | ) |  |

Creates the surface and attaches it to the specified texture. The size of the surface will be as near as possible to the requested size, but additional restrictions may apply on certain hardware.

If EXACT_MATCH_F is specified the surface will be large enough to accomodate the specified size, and will automatically use a 'client window' into the surface that exactly matches the requested size. If a large enough surface cannot be created, the surface will be the largest possible. When this surface is current IwGxGetScreenWidth/IwGxGetScreenHeight will return the size of the underlying surface, while IwGxGetDisplayWidth/IwGxGetDisplayHeight will return the size of the client window.

If ALPHA_F is specified the surface will have an alpha channel. EGL surfaces will not respect this parameter - they will get an alpha channel if the main display has one, and vice versa. SW surfaces will never have an alpha channel.

If PERSISTENT_F is specified the surface's contents will be persistent. i.e. if the surface is deselected then selected the pixels will still be in the same state. Selecting a non-persistent surface may also invalidate the frame buffer. Win32 will have worst-case behaviour for debugging purposes (invalidated surfaces will be cleared to purple).

If FREE_ASPECT_F is specified the surface's will have no client window and may not match the aspect ratio requested. The default behaviour is to use a client window to maintain aspect ratio if neccessary.

If PRESERVE_FRAME_BUFFER_F is specified selecting this surface will not invalidate the frame buffer. This setting will prevent the surface from being created on platforms that do not support real multiple surfaces. Win32 will have worst-case behaviour for debugging purposes (invalidated frame buffer will be cleared to purple).

If CREATE_565_SURFACE_F is specified the surface will have a 16bit pixel type. EGL surfaces will not respect this parameter - they will get the main display pixel type. SW surfaces will have an RGB565 pixel type. If neither of CREATE_888_SURFACE_F or CREATE_565_SURFACE_F is specified then the surface will have the s3e surface pixel type

If CREATE_888_SURFACE_F is specified the surface will have a 16bit pixel type. EGL surfaces will not respect this parameter - they will get the main display pixel type. SW surfaces will have an ARGB8888 pixel type. If neither of CREATE_888_SURFACE_F or CREATE_565_SURFACE_F is specified then the surface will have the s3e surface pixel type

If pTexture is NULL a new texture will be created (and destroyed) by the surface.

Parameters:
pTexture | The texture object to attach this surface to. Any current contents will be lost, and the contents of the texture will be undefined until the surface has been made current, renderered to and deselected.
width | The desired width of the surface in pixels
height | The desired height of the surface in pixels
usage | Usage characteristics for the surface.
Returns:
true if surface creation succeeded
Required Header Files
IwGx.h

uint32 CIwGxSurface::GetClientHeight ( )

Get the client height.

Returns:
The height of the client window in pixels

const CIwSVec2& CIwGxSurface::GetClientUVExtent ( )

Get the size in UV coordinates of the 'client window' of the surface.

Returns:
The UV extent of the client window.

uint32 CIwGxSurface::GetClientWidth ( )

Get the client width.

Returns:
The width of the client window in pixels

uint32 CIwGxSurface::GetHeight ( )

Get the surface height.

Returns:
The height of the underlying surface in pixels

CIwGxSurfaceImplementation CIwGxSurface::GetImplementation ( )

Get the attached texture

Returns:
The implementation the surface is using

const s3eSurfaceInfo& CIwGxSurface::GetSurfaceInfo ( )

Get a surface info structure representing the surface. This can be used to directly push pixels into a SW surface.

Returns:
The surface info

INLINE_MEMBER CIwTexture* CIwGxSurface::GetTexture ( ) [inline]

Get the attached texture

Returns:
The attached texture

uint32 CIwGxSurface::GetWidth ( )

Get the surface width.

Returns:
The width of the underlying surface in pixels

bool CIwGxSurface::HasAlphaChannel ( )

Does the surface have an alpha channel

Returns:
true if the surface has an alpha channel

bool CIwGxSurface::IsValid ( ) [inline]

Has this surface been created?

Returns:
true if the surface has been created and can be rendered to.

void CIwGxSurface::MakeCurrent ( )

Select this surface as the current rendering target.

If PERSISTENT_F was not passed to CreateSurface the contents of the surface will be undefined (magenta in win32) following this call.

static void CIwGxSurface::MakeDisplayCurrent ( ) [static]

Select the display as current rendering target.

If PRESERVE_FRAME_BUFFER_F was not passed to CreateSurface the contents of the display will be undefined (magenta in win32) following this call.

bool CIwGxSurface::RecreateSurface | ( | uint32 | width,
 |  | uint32 | height
 | ) |  |

Recreate this surface at the specified size. This will typically require less work that deleting the surface object and creating a new one. The contents of the surface are undefined after recreation.

Parameters:
width | The desired width of the surface in pixels
height | The desired height of the surface in pixels
Returns:
true if surface recreation succeeded

The documentation for this class was generated from the following file:
  • IwGxSurface.h


Airplay API Reference: CIwHTTP

Airplay API Reference > Data Structures > CIwHTTP >

CIwHTTP Class Reference
[HTTP Client Object]

#include <IwHTTP.h>

Public Member Functions

s3eResult Cancel ()
uint32 | ContentExpected ()
bool | ContentFinished ()
uint32 | ContentLength ()
uint32 | ContentReceived ()
s3eResult | Get (const char *URI, s3eCallback callback, void *data)
bool | GetHeader (const char *pName, std::string &val)
bool | GetHeader (const char *pName, int32 &val)
uint32 | GetResponseCode ()
s3eResult | GetStatus () const
s3eResult | Post (const char *URI, const char *Body, int32 BodyLength, s3eCallback callback, void *data)
uint32 | ReadContent (char *pBuf, uint32 max_bytes, s3eCallback callback=NULL, void *cb_data=NULL)
void | SetRequestHeader (const char *pName, const std::string &val)
void | SetRequestHeader (const char *pName, int32 val)

Data Structures

struct | ReqHeader

Detailed Description

HTTP Client Class

Constructor & Destructor Documentation

CIwHTTP::CIwHTTP ( )

Constructor.

virtual CIwHTTP::~CIwHTTP ( ) [virtual]

Destructor.

Member Function Documentation

s3eResult CIwHTTP::Cancel ( )

Cancel the current GET or POST request.

Returns:
A standard s3e result code to indicate if the operation succeeded.

uint32 CIwHTTP::ContentExpected ( )

Returns the amount of data currently known to be expected. If a Content-Length: header has been received then the return will be that value. If the transfer encoding is chunked then this value will increase over time as chunk sizes are received. If neither of these options are in use then the return is HTTP_SIZE_UNKNOWN

Returns:
the minumum expected content size

bool CIwHTTP::ContentFinished ( )

Returns true when the data has all been received

Returns:
true when the data has all been received

uint32 CIwHTTP::ContentLength ( )

DEPRECATED: Use GetHeader("Content-Length:", int32 &); instead. Returns the length of the response content. This assumes the response has a Content-Length: header (and the header has been received)

uint32 CIwHTTP::ContentReceived ( )

Returns the total amount of data so far received

Returns:
The ammount of data so far received

s3eResult CIwHTTP::Get | ( | const char * | URI,
 |  | s3eCallback | callback,
 |  | void * | data
 | ) |  |

Performs a GET request. If supplied, the callback will be called when all the headers have been received.

Parameters:
URI | The URI to fetch.
callback | A callback that is called when the header has been received. This can be NULL if you want to poll instead. The callback is also called when the operation fails; it should call GetStatus to find out why it has been called.
data | User data argument to the callback.
Returns:
A standard s3e result code to indicate if the operation succeeded.

bool CIwHTTP::GetHeader | ( | const char * | pName,
 |  | std::string & | val
 | ) |  |

Gets a response header as a string. This will only work after the response headers have been received.

Parameters:
pName | The name of the header
val | The value is filled in here
Returns:
true if the header is present.

bool CIwHTTP::GetHeader | ( | const char * | pName,
 |  | int32 & | val
 | ) |  |

Gets a response header as an integer. This will only work after the response headers have been received.

Parameters:
pName | The name of the header
val | The value is filled in here
Returns:
true if the header is present.

uint32 CIwHTTP::GetResponseCode ( )

Returns the response code of the request. This will return 0 if the headers have yet to be received. e.g. 200 means OK, 404 means not found.

Returns:
The response code.

s3eResult CIwHTTP::GetStatus ( ) const [inline]

Returns the status of the current or last operation.

Returns:
If the operation is in progress or has succeeded, S3E_RESULT_SUCCESS is returned. Otherwise S3E_RESULT_ERROR is returned.
Note:
Note that any callback should check the status by calling this function to see if the operation has actually succeeded.

s3eResult CIwHTTP::Post | ( | const char * | URI,
 |  | const char * | Body,
 |  | int32 | BodyLength,
 |  | s3eCallback | callback,
 |  | void * | data
 | ) |  |

Performs a POST request. If supplied, the callback will be called when all the headers have been received. The body must be supplied all at once, and must remain valid until the response headers are received.

Parameters:
URI | The URI to fetch.
callback | A callback that is called when the header has been received. This can be NULL if you want to poll instead. The callback is also called when the operation fails; it should call GetStatus to find out why it has been called.
Body | A pointer to the request body
BodyLength | the length of the request body in bytes.
data | User data argument to the callback.
Returns:
A standard s3e result code to indicate if the operation succeeded.

uint32 CIwHTTP::ReadContent | ( | char * | pBuf,
 |  | uint32 | max_bytes,
 |  | s3eCallback | callback = NULL,
 |  | void * | cb_data = NULL
 | ) |  |

Receives the content. The content may not be immediately available, but the callback is called when it is. If no callback is supplied then only the immediately-available data is returned.

Parameters:
pBuf | A buffer to fill with data
max_bytes | The length of the buffer
callback | An optional callback to call when either the buffer is full or all data has been received.
cb_data | A user data argument passed to the callback
Returns:
the number of bytes returned so far.

void CIwHTTP::SetRequestHeader | ( | const char * | pName,
 |  | const std::string & | val
 | ) |  |

Sets a request header as a string. This will be used for all subsequent requests. To unset them, set them to the empty string.

Note:
Host and Content-Length headers set using this function are always ignored. Any header starting in Content- will be ignored on GET requests. If User-Agent is not set then a default User-Agent header is added. For POST requests where Content-Type has not been set, then a default Content-Type of multipart/form-data is added.
Parameters:
pName | The name of the header, excluding the colon.
val | The value

void CIwHTTP::SetRequestHeader | ( | const char * | pName,
 |  | int32 | val
 | ) |  |

Sets a request header as an integer. This will be used for all subsequent requests. To remove it, set it to the empty string using the other overload of this function.

Note:
Host and Content-Length headers set using this function are always ignored. Any header starting in Content- will be ignored on GET requests. If User-Agent is not set then a default User-Agent header is added. For POST requests where Content-Type has not been set, then a default Content-Type of multipart/form-data is added.
Parameters:
pName | The name of the header, excluding the colon.
val | The value

The documentation for this class was generated from the following file:
  • IwHTTP.h


Airplay API Reference: CIwImage

Airplay API Reference > Data Structures > CIwImage >

CIwImage Class Reference
[IwImage]

#include <IwImage.h>

Public Types

enum | Format

Public Member Functions

CIwImage (const CIwImage &img)
CIwImage ()
void | ConvertToImage (CIwImage *pImage, uint8 *pTexels, uint32 texelsSize, uint8 *pPalette, uint32 palSize, bool chooseDepth)
void | ConvertToImage (CIwImage *pImage, bool chooseDepth=false)
int | CountColours ()
uint32 | FormatColour (uint8 red, uint8 green, uint8 blue, uint8 alpha=0xff)
uint32 | GetBitDepth () const
uint32 | GetByteDepth () const
uint32 | GetByteWidth () const
uint16 | GetFlags () const
Format | GetFormat () const
FormatData | GetFormatData () const
uint32 | GetHeight () const
uint8 * | GetPalette () const
uint32 | GetPaletteMemSize () const
uint32 | GetPaletteSize () const
uint32 | GetPitch () const
uint32 | GetTexelBitDepth () const
uint8 * | GetTexels () const
uint32 | GetTexelsMemSize () const
uint32 | GetWidth () const
uint8 | HasAlpha () const
void | LoadFromFile (const char *imageFile)
uint32 | MakeAlphaPalZero (uint8 threshold, uint8 keyR, uint8 keyG, uint8 keyB)
void | ReadFile (s3eFile *pFile, uint8 *pTexels, uint32 texelsSize, uint8 *pPalette, uint32 palSize)
void | ReadFile (s3eFile *pFile)
void | ReadPalette (uint8 *pPaletteSrc)
void | ReadTexels (uint8 *pTexelsSrc)
uint32 | ReplaceAlpha (uint8 threshold, uint8 chromaR, uint8 chromaG, uint8 chromaB)
uint32 | ReplaceAlphaColourWithSurrounding (uint8 threshold=0x80, uint8 numSurrounding=0x2)
uint32 | ReplaceColour (uint8 srcR, uint8 srcG, uint8 srcB, uint8 srcA, uint8 dstR, uint8 dstG, uint8 dstB, uint8 dstA)
void | ReplacePalette (uint8 *pPalette)
void | SaveBmp (const char *filename)
void | Serialise ()
void | SetFormat (Format format)
void | SetHeight (uint32 height)
void | SetOwnedBuffers (uint8 *pTexels, uint8 *pPalette)
void | SetPitch (uint32 pitch)
void | SetWidth (uint32 width)
bool | UsesAlpha (uint8 threshold=0xff) const
bool | UsesChromakey () const
~CIwImage ()

Static Public Member Functions

static bool | FixedBufferAvailable ()
static void | FixedBufferCheckOverflow ()
static void | FixedBufferFree ()
static void | FixedBufferSetSize (uint32 size)
static uint32 | GetBitDepth (const Format &format)
static uint32 | GetByteDepth (const Format &format)
static uint32 | GetPaletteMemSize (const Format &format)
static uint32 | GetPaletteSize (const Format &format)
static uint32 | GetTexelBitDepth (const Format &format)

Data Structures

struct | FormatData

Detailed Description

CIwImage is a storage, loading and manipulation class for a range of image formats. Images can be loaded from BMP, GIF, PNG and TGA files, and converted to a wide range of palettised and unpalettised formats.

The following file formats can be read:
File type | Bits per pixel | Palettised | Run-length encoded
BMP | 4 | YES | NO
BMP | 4 | YES | YES
BMP | 8 | YES | NO
BMP | 8 | YES | YES
BMP | 16 | NO | NO
BMP | 24 | NO | NO
BMP | 32 | NO | NO
GIF | 4 | YES | NO
GIF | 5 | YES | NO
GIF | 6 | YES | NO
GIF | 8 | YES | NO
PNG | 4 | YES | NO
PNG | 8 | YES | NO
PNG | 24 | NO | NO
TGA | 16 | NO | NO
TGA | 16 | NO | YES
TGA | 24 | NO | NO
TGA | 24 | NO | YES
TGA | 32 | NO | NO
TGA | 32 | NO | YES

Format The "Format" enumeration is a list of all formats which images can be converted to internally. Note that the component order is MSB first/

Required Header Files
IwImage.h

Member Enumeration Documentation

enum CIwImage::Format

Image formats.

Required Header Files
IwImage.h
Enumerator:
FORMAT_UNDEFINED | Format is undefined.
RGB_332 | Unpalettised 8-bit.
BGR_332 | Unpalettised 8-bit.
RGB_565 | Unpalettised 16-bit, no alpha.
BGR_565 | Unpalettised 16-bit, no alpha.
RGBA_4444 | Unpalettised 16-bit, alpha.
ABGR_4444 | Unpalettised 16-bit, alpha.
RGBA_5551 | Unpalettised 16-bit, alpha.
ABGR_1555 | Unpalettised 16-bit, alpha.
RGB_888 | Unpalettised 24-bit, no alpha.
BGR_888 | Unpalettised 24-bit, no alpha.
RGBA_6666 | Unpalettised 24-bit, alpha.
ABGR_6666 | Unpalettised 24-bit, alpha.
RGBA_8888 | Unpalettised 32-bit, alpha.
ABGR_8888 | Unpalettised 32-bit, alpha.
RGBA_AAA2 | Unpalettised 32-bit, alpha.
ABGR_2AAA | Unpalettised 32-bit, alpha.
PALETTE4_RGB_888 | 16-colour palettised.
PALETTE4_RGBA_8888 | 16-colour palettised.
PALETTE4_RGB_565 | 16-colour palettised.
PALETTE4_RGBA_4444 | 16-colour palettised.
PALETTE4_RGBA_5551 | 16-colour palettised.
PALETTE8_RGB_888 | 256-colour palettised.
PALETTE8_RGBA_8888 | 256-colour palettised.
PALETTE8_RGB_565 | 256-colour palettised.
PALETTE8_RGBA_4444 | 256-colour palettised.
PALETTE8_RGBA_5551 | 256-colour palettised.
PALETTE7_ABGR_1555 | 32-colour palettised.
PALETTE6_ABGR_1555 | 64-colour palettised.
PALETTE5_ABGR_1555 | 128-colour palettised.
PVRTC_2 | PowerVR compressed format.
PVRTC_4 | PowerVR compressed format.
ATITC | ATI compressed format.
COMPRESSED | gfx specific compressed format
PALETTE4_ABGR_4444 | 16-colour palettised.
PALETTE8_ABGR_4444 | 256-colour palettised.
A_8 | Unpalettised 8-bit alpha.
ETC | Ericsson compressed format.
ARGB_8888 | Unpalettised 32-bit, alpha.
PALETTE4_ARGB_8888 | 16-colour palettised.
PALETTE8_ARGB_8888 | 256-colour palettised.

Constructor & Destructor Documentation

CIwImage::CIwImage ( )

Constructor, creates a CIwImage with all fields set to zero except for m_Format, which is set to FORMAT_UNDEFINED.

CIwImage::CIwImage ( const CIwImage & img )

Constructor, clones a CIwImage from an existing CIwImage reference.

Parameters:
img Image to clone from.

CIwImage::~CIwImage ( )

Destructor.

Member Function Documentation

void CIwImage::ConvertToImage | ( | CIwImage * | pImage,
 |  | uint8 * | pTexels,
 |  | uint32 | texelsSize,
 |  | uint8 * | pPalette,
 |  | uint32 | palSize,
 |  | bool | chooseDepth
 | ) |  |

Converts an image so that it obeys the properties of the supplied image type. This version of the function allows you to specify texel and palette data and size separately from the template Image .

Parameters:
pImage | Pointer to a CIwImage object, which acts as a template for the converted image. This object is also used to hold the resulting converted image.
pTexels | Pointer to a pre-existing texel buffer.
texelsSize | The size of the pre-existing texel buffer.
pPalette | Pointer to a pre-existing palette.
palSize | The size of the pre-existing palette.
chooseDepth | Allow the IwUtil functionality to choose the optimal bit size for the palette specified by pPalette.
Remarks:
The invoking image is not changed. The user sets the desired properties within the supplied image pImage, which acts as a template. Texel and palette data and size can be set as parameters. The image resulting from the convertion is pointed to by pImage.
Required Header Files
IwImage.h

void CIwImage::ConvertToImage | ( | CIwImage * | pImage,
 |  | bool | chooseDepth = false
 | ) |  |

Converts an image so that it obeys the properties of the supplied image type.

Parameters:
pImage | Pointer to a CIwImage object, which acts as a template for the converted image. This object is also used to hold the resulting converted image.
chooseDepth | If you are converting to a palettised image, setting this to true allows the IwUtil functionality to choose the optimal bit size.
Remarks:
The invoking image is not changed. The user must set the desired properties within the supplied image pImage, which acts as a template. The image resulting from the convertion is pointed to by pImage.
Required Header Files
IwImage.h

int CIwImage::CountColours ( )

Counts the number of colours in an image up to 256.

Returns:
The number of colours up to 256. INT_MAX if more than 256.

uint32 CIwImage::FormatColour | ( | uint8 | red,
 |  | uint8 | green,
 |  | uint8 | blue,
 |  | uint8 | alpha = 0xff
 | ) |  |

Format an RGB value into the correct format for this image

Parameters:
red | Red value
green | Green value
blue | Blue value
alpha | Alpha value
Returns:
The specified colour in the native format for this image

static uint32 CIwImage::GetBitDepth ( const Format & format ) [static]

Gets the bit depth in the specified format (8, 16, 24, 32).

Parameters:
format The format.
Returns:
The bit depth of the format (8, 16, 24, 32).
Note:
For palettised formats, this is the bit depth of a palette entry.
Required Header Files
IwImage.h

uint32 CIwImage::GetBitDepth ( ) const [inline]

Gets the bit depth of the image (8, 16, 24, 32).

Returns:
The bit depth of the image (8, 16, 24, 32).
Note:
For palettised formats, this is the bit depth of a palette entry.
Required Header Files
IwImage.h

static uint32 CIwImage::GetByteDepth ( const Format & format ) [inline, static]

Gets the byte depth in the specified format (1, 2, 3, 4).

Parameters:
format The format.
Returns:
the byte depth of the format (1, 2, 3, 4).
Note:
For palettised formats, this is the byte depth of a palette entry, NOT of a texel.
Required Header Files
IwImage.h

uint32 CIwImage::GetByteDepth ( ) const [inline]

Gets the byte depth of the image (1, 2, 3, 4).

Returns:
the byte depth of the image (1, 2, 3, 4).
Note:
For palettised formats, this is the byte depth of a palette entry, NOT of a texel.
Required Header Files
IwImage.h

uint32 CIwImage::GetByteWidth ( ) const [inline]

Gets the minimum number of bytes that will include all texels

Returns:
The width in bytes.
Required Header Files
IwImage.h

uint16 CIwImage::GetFlags ( ) const [inline]

Gets the image flags.

Required Header Files
IwImage.h

Format CIwImage::GetFormat ( ) const [inline]

Gets the image format.

Returns:
The format of the image.
See also:
SetFormat
Required Header Files
IwImage.h

FormatData CIwImage::GetFormatData ( ) const [inline]

Gets the format data.

Returns:
A structure providing format information.
Required Header Files
IwImage.h

uint32 CIwImage::GetHeight ( ) const [inline]

Gets the height, in texels.

Returns:
The height in texels.
Required Header Files
IwImage.h

uint8* CIwImage::GetPalette ( ) const [inline]

Get the palette.

Returns:
A pointer to the current image palette. NULL if none exists.
Required Header Files
IwImage.h

static uint32 CIwImage::GetPaletteMemSize ( const Format & format ) [static]

Gets the amount of memory occupied by the palette (in client memory) in the specified format.

Parameters:
format The format.
Returns:
The amount of memory allocated to the palette, in bytes.
See also:
GetPaletteSize
Required Header Files
IwImage.h

uint32 CIwImage::GetPaletteMemSize ( ) const [inline]

Gets the amount of memory occupied by the palette (in client memory).

Returns:
The amount of memory allocated to the palette, in bytes.
See also:
GetPaletteSize
Required Header Files
IwImage.h

static uint32 CIwImage::GetPaletteSize ( const Format & format ) [static]

Gets the number of palette entries (0, 16, 32, 64, 128, 256) in the specified format.

Parameters:
format The format.
Returns:
The number of entries in the palette.
See also:
GetPaletteMemSize
Required Header Files
IwImage.h

uint32 CIwImage::GetPaletteSize ( ) const [inline]

Gets the number of palette entries (0, 16, 32, 64, 128, 256).

Returns:
The number of entries in the palette.
See also:
GetPaletteMemSize
Required Header Files
IwImage.h

uint32 CIwImage::GetPitch ( ) const [inline]

Gets the pitch, in bytes.

Returns:
The pitch in bytes.
Required Header Files
IwImage.h

static uint32 CIwImage::GetTexelBitDepth ( const Format & format ) [static]

Gets the bit depth of a texel in the specified format.

Parameters:
format The format.
Returns:
the bit depth of a texel.
Note:
For palettised formats, this is 4 or 8.
Required Header Files
IwImage.h

uint32 CIwImage::GetTexelBitDepth ( ) const [inline]

Gets the bit depth of a texel.

Returns:
the bit depth of a texel.
Note:
For palettised formats, this is 4 or 8.
Required Header Files
IwImage.h

uint8* CIwImage::GetTexels ( ) const [inline]

Gets the texels.

Returns:
A pointer to the current image texels, or NULL if none exists.
Required Header Files
IwImage.h

uint32 CIwImage::GetTexelsMemSize ( ) const [inline]

Gets the amount of memory occupied by the texels (in client memory).

Returns:
The amount of memory allocated to the texels, in bytes.
See also:
GetTexelBitDepth
Required Header Files
IwImage.h

uint32 CIwImage::GetWidth ( ) const [inline]

Gets the width, in texels.

Returns:
The width in texels.
Required Header Files
IwImage.h

uint8 CIwImage::HasAlpha ( ) const [inline]

Indicates whether the image has an alpha channel.

Returns:
1 if an alpha channel is present and 0 otherwise
Required Header Files
IwImage.h

void CIwImage::LoadFromFile ( const char * imageFile )

Reads an image from a file, allocating space for required data and filling in the class members. This function will assert if the file doesn't exist.

Parameters:
imageFile name of file to load.
Note:
The format of the resulting image object will match the format of the file - no format conversion takes place at this stage.
Required Header Files
IwImage.h

uint32 CIwImage::MakeAlphaPalZero | ( | uint8 | threshold,
 |  | uint8 | keyR,
 |  | uint8 | keyG,
 |  | uint8 | keyB
 | ) |  |

Make all texels that with alpha below the threshold or that match the key colour be index zero and replace this entry with black. May rearrange the palette to achieve this.

Parameters:
threshold | alpha value to replace
keyR | red value to replace
keyG | green value to replace
keyB | blue value to replace
Returns:
Number of texels transformed
Required Header Files
IwImage.h

void CIwImage::ReadFile | ( | s3eFile * | pFile,
 |  | uint8 * | pTexels,
 |  | uint32 | texelsSize,
 |  | uint8 * | pPalette,
 |  | uint32 | palSize
 | ) |  |

Reads an image from a file into pre-existing texel and palette buffers.

Parameters:
pFile | Pointer to an s3eFile object.
pTexels | Pointer to the destination texel buffer.
texelsSize | The size of the destination texel buffer.
pPalette | Pointer to the destination palette buffer.
palSize | The size of the destination palette buffer.
Note:
The format of the resulting image object will match the format of the file - no format conversion takes place at this stage.
Required Header Files
IwImage.h

void CIwImage::ReadFile ( s3eFile * pFile )

Reads an image from a file, allocating space for required data and filling in the class members. The image format and properties are determined automatically.

Parameters:
pFile Pointer to an IwFile object.
Note:
The format of the resulting image object will match the format of the file - no format conversion takes place at this stage.
Required Header Files
IwImage.h

void CIwImage::ReadPalette ( uint8 * pPaletteSrc )

Reads and stores palette information from palette data.

Parameters:
pPaletteSrc a pointer to the palette data
Required Header Files
IwImage.h

void CIwImage::ReadTexels ( uint8 * pTexelsSrc )

Reads and stores texel information from texel data.

Parameters:
pTexelsSrc a pointer to the texel data
Required Header Files
IwImage.h

uint32 CIwImage::ReplaceAlpha | ( | uint8 | threshold,
 |  | uint8 | chromaR,
 |  | uint8 | chromaG,
 |  | uint8 | chromaB
 | ) |  |

Replace all instances of colours with alpha below threshold with the specified chromakey

uint32 CIwImage::ReplaceAlphaColourWithSurrounding | ( | uint8 | threshold = 0x80,
 |  | uint8 | numSurrounding = 0x2
 | ) |  |

Replace the colour components of pixels, with alpha component less than a threshold, with the average colour of surrounding pixels.

uint32 CIwImage::ReplaceColour | ( | uint8 | srcR,
 |  | uint8 | srcG,
 |  | uint8 | srcB,
 |  | uint8 | srcA,
 |  | uint8 | dstR,
 |  | uint8 | dstG,
 |  | uint8 | dstB,
 |  | uint8 | dstA
 | ) |  |

@ @ Replace all instances of one colour with another

Parameters:
srcR | red value to replace
srcG | green value to replace
srcB | blue value to replace
srcA | alpha value to replace
dstR | red value to replace with
dstG | green value to replace with
dstB | blue value to replace with
dstA | alpha value to replace with
Returns:
number of colours replaced.
Note:
for palettised images the return value will be the number of palette entries replaced
Required Header Files
IwImage.h

void CIwImage::ReplacePalette ( uint8 * pPalette )

Replaces the current palette with the specified one.

Parameters:
pPalette The new palette to use.
Note:
The supplied palette must match current format.
Required Header Files
IwImage.h

void CIwImage::SaveBmp ( const char * filename )

Saves this image as a win32 .bmp file. If the image is not RGB_888, an RGB_888 version will be created. Therefore this function may use large amounts of memory.

Parameters:
filename Filename to save to.
Required Header Files
IwImage.h

void CIwImage::Serialise ( )

Reads/writes CIwImage to the current binary file, using the IwSerialise interface.

See also:
IwSerialise

void CIwImage::SetFormat ( Format format )

Sets the image format.

Parameters:
format The format of the image.
See also:
GetFormat
Required Header Files
IwImage.h

void CIwImage::SetHeight ( uint32 height )

Sets the height, in texels.

Parameters:
height The new height in texels.
Note:
This method will assert if either the format has not been set, or a texel/palette allocation has already been made.

void CIwImage::SetOwnedBuffers | ( | uint8 * | pTexels,
 |  | uint8 * | pPalette
 | ) |  |

Sets the texels and palette data, taking ownership of them.

Note:
The palette is not owned. (This is for backwards compatibility with the old way of reading images, where image and palette data was allocated as a single buffer)
Required Header Files
IwImage.h

void CIwImage::SetPitch ( uint32 pitch )

Sets the pitch, in bytes.

Parameters:
The new pitch in bytes.
Note:
This method will assert if either the format has not been set, or a texel/palette allocation has already been made.

void CIwImage::SetWidth ( uint32 width )

Sets the width, in texels.

Parameters:
width The new width in texels.
Note:
This method will assert if either the format has not been set, or a texel/palette allocation has already been made.

bool CIwImage::UsesAlpha ( uint8 threshold = 0xff ) const

Indicates whether this image has a non-trivial alpha channel.

Returns:
true if the image has an alpha channel, and some entry is not fully opaque.
Required Header Files
IwImage.h

bool CIwImage::UsesChromakey ( ) const

Indicates whether this image uses a chromakey value.

Returns:
true if the image uses a chromakey value, otherwise false.
Note:
The "magic" chromakey value is (r,g,b) = (255,0,255). Any texel with this colour will appear "transparent".
Required Header Files
IwImage.h

The documentation for this class was generated from the following file:
  • IwImage.h


Airplay API Reference: CIwList

Airplay API Reference > Data Structures > CIwList< X > >

CIwList< X > Class Template Reference
[IwList]

#include <IwList.h>

Public Member Functions

void | append (X const &x)
X & | back ()
iterator | begin ()
void | clear ()
X & | element_at (int idx)
iterator | end ()
iterator | erase (X *el)
iterator | erase (iterator &it)
bool | find_and_remove (X &el)
X & | front ()
void | push_back (X const &x)

Data Structures

class | iterator
class | Store

Detailed Description

template<class X>
class CIwList< X >

Basic list object similar to std::list. In many cases it can be used to substitute for CIwArray.

Member Function Documentation

template<class X>
void CIwList< X >::append ( X const & x ) [inline]

Adds an element to the end of the list.

Required Header Files
IwList.h
Required Header Files
IwList.h

template<class X>
X& CIwList< X >::back ( ) [inline]

Returns the last element in the list.

template<class X>
iterator CIwList< X >::begin ( ) [inline]

Returns an iterator for the beginning of the list.

Required Header Files
IwList.h

template<class X>
void CIwList< X >::clear ( ) [inline]

Deletes the list and frees all memory used in storage.

Required Header Files
IwList.h

template<class X>
X& CIwList< X >::element_at ( int idx ) [inline]

Returns the element at position idx in the list.

Required Header Files
IwList.h

template<class X>
iterator CIwList< X >::end ( ) [inline]

Returns an iterator for the element beyond the end of the list.

Required Header Files
IwList.h

template<class X>
iterator CIwList< X >::erase ( X * el ) [inline]

Removes the given element from the list.

Required Header Files
IwList.h

template<class X>
iterator CIwList< X >::erase ( iterator & it ) [inline]

Removes the given iterator from the list.

Required Header Files
IwList.h

template<class X>
bool CIwList< X >::find_and_remove ( X & el ) [inline]

Finds the given element and removes it from the list. Returns true on success.

Required Header Files
IwList.h

template<class X>
X& CIwList< X >::front ( ) [inline]

Returns the first element in the list.

template<class X>
void CIwList< X >::push_back ( X const & x ) [inline]

Adds an element to the end of the list.

Required Header Files
IwList.h
Required Header Files
IwList.h

The documentation for this class was generated from the following file:
  • IwList.h


Airplay API Reference: CIwList

Airplay API Reference > Data Structures > CIwList< X >::Store >
CIwList::Store

CIwList< X >::Store Class Reference

#include <IwList.h>

Detailed Description

template<class X>
class CIwList< X >::Store

Linked list storage element.
Required Header Files
IwList.h
The documentation for this class was generated from the following file:
  • IwList.h


Airplay API Reference: CIwListNode

Airplay API Reference > Data Structures > CIwListNode >

CIwListNode Class Reference
[IwList]

#include <IwList.h>

Inheritance diagram for CIwListNode:

[legend]

Detailed Description

Linked list node structure. Any class that you would like to take a list form should be derived from this structure. The list itself is defined by instantiating the root, e.g:

 CIwListNode m_ListRoot;

You can then add and remove nodes to the list by passing in a pointer to this root node. You can also iterate over the list using the IW_LIST_ITERATE macro.

Required Header Files
IwList.h
The documentation for this class was generated from the following file:
  • IwList.h


Airplay API Reference: CIwManaged

Airplay API Reference > Data Structures > CIwManaged >

CIwManaged Class Reference
[IwUtil API Reference]

#include <IwManaged.h>

Inheritance diagram for CIwManaged:

[legend]

Public Member Functions

virtual bool | HandleEvent (CIwEvent *pEvent)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual void | ParseOpen (CIwTextParserITX *pParser)
virtual void | Resolve ()
virtual void | Serialise ()
virtual void | SetName (const char *pName)

Detailed Description

Base class for a "managed" object. Provides many useful virtual functions. The only data members are a per-instance string name (which exists in Debug builds only) and a 32-bit hashed value derived from the string name (which exists in all builds). See the Managed Objects module overview for more information.

CIwManaged objects accept the following attributes in ITX files:
Attribute | Value | Description | Example
name | (string) | Object name | name "Object1"

Member Function Documentation

virtual void CIwManaged::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented in CIwMaterial, CIwModel, CIwModelBlock, CIwModelExt, CIwModelExtSelSetFace, CIwAnim, CIwAnimPlayer, CIwAnimSkel, and CIwAnimSkin.

const char* CIwManaged::DebugGetName ( ) const [inline]

Debug: get name.

Reimplemented in CIwUIStyle.

virtual void CIwManaged::DebugRender ( ) [inline, virtual]

Debug rendering.

Reimplemented in CIwModel, CIwModelExtPos, CIwModelExtSphere, CIwModelExtSelSetVert, CIwModelExtSelSetEdge, CIwModelExtSelSetFace, and CIwAnimPlayer.

virtual bool CIwManaged::HandleEvent ( CIwEvent * pEvent ) [inline, virtual]

Handles events of all types.

Parameters:
pEvent the event
Returns:
true if the event was handled, false otherwise.
See also:
CIwTextParserITX
Note:
Derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented in CIwUIElement, CIwUIElementEventHandler, CIwUIRadioButton, CIwUISoftKeyboard, CIwUITabBar, and CIwUITextField.

virtual bool CIwManaged::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented in CIwGxShaderTechnique, CIwMaterial, CIwResTemplateMTL, CIwModelExt, CIwModelExtPos, CIwModelExtSphere, CIwModelExtSelSetVert, CIwModelExtSelSetEdge, CIwModelExtSelSetFace, CIwResTemplateGEO, CIwResTemplateANIM, CIwResTemplateSKEL, CIwResTemplateSKIN, CIwResTemplate, CIwResTemplateGROUP, CIwResTemplateImage, CIwUIAnimKeyFrame, CIwUIElement, CIwUILayout, CIwUILayoutGrid, CIwUILayoutItem, CIwUIPropertySet, CIwPropertyDefine, and CIwPropertySet.

virtual void CIwManaged::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented in CIwGxShaderTechnique, CIwMaterial, CIwModel, CIwModelBlock, CIwModelExt, CIwModelExtSelSetFace, CIwResTemplate, CIwUIAnimation, CIwUIElement, CIwUIElementEventHandler, CIwUIFocusHandler, CIwUILayout, CIwUIPropertySet, CIwPropertyDefine, CIwPropertySet, and CIwPropertySetBinding.

virtual void CIwManaged::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented in CIwUIAnimation, CIwUIElement, CIwUILayout, CIwUILayoutGrid, CIwUILayoutItemContainer, and CIwPropertySet.

virtual void CIwManaged::ParseOpen ( CIwTextParserITX * pParser ) [inline, virtual]

Parses from text file: start block.

Parameters:
pParser the parser instance to use
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented in CIwMaterial, CIwResTemplateMTL, CIwModelExtSelSetVert, and CIwModelExtSelSetEdge.

virtual void CIwManaged::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented in CIwMaterial, CIwTexture, CIwModel, CIwModelBlock, CIwAnimPlayer, CIwResGroup, CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUILayout, CIwUILayoutGrid, CIwUILayoutItem, CIwUILayoutItemContainer, CIwUIPropertySet, CIwUIStyle, CIwProperty< Type >, CIwPropertyBase, and CIwPropertySet.

virtual void CIwManaged::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented in CIwGxShaderTechnique, CIwMaterial, CIwTexture, CIwModel, CIwModelBlock, CIwModelExt, CIwModelExtPos, CIwModelExtSphere, CIwModelExtSelSetVert, CIwModelExtSelSetEdge, CIwModelExtSelSetFace, CIwAnimPlayer, CIwResList, CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUILayout, CIwUILayoutGrid, CIwUILayoutItem, CIwUILayoutItemContainer, CIwUIPropertySet, CIwUIStyle, CIwProperty< Type >, CIwPropertyBase, CIwPropertyDefine, and CIwPropertySet.

virtual void CIwManaged::SetName ( const char * pName ) [virtual]

Set name (hashed value)

Parameters:
pName the hashed name of the managed object
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented in CIwMaterial, CIwUIAnimKeyFrame, CIwUIElement, and CIwUILayoutItem.

Field Documentation

uint32 CIwManaged::m_Hash

Hashed string name of object.

The documentation for this class was generated from the following file:
  • IwManaged.h


Airplay API Reference: CIwManagedList

Airplay API Reference > Data Structures > CIwManagedList >

CIwManagedList Class Reference
[IwManagedList]

#include <IwManagedList.h>

Public Member Functions

void | Add (CIwManaged *pObject, bool allowDups=false)
void | Clear ()
void | ClearAndFree ()
bool | Contains (CIwManaged *pObject) const
void | CopyList (const CIwManagedList &list)
void | Delete ()
CIwManaged ** | Erase (CIwManaged **it)
uint32 | EraseFast (uint32 i)
int32 | Find (CIwManaged *const &pObject) const
CIwManaged ** | GetBegin () const
uint32 | GetCapacity () const
CIwManaged ** | GetEnd () const
CIwManaged * | GetObjHashed (uint32 hash, bool allowDups=false) const
CIwManaged::ArrayIt | GetObjHashedNextIt (uint32 hash, CIwManaged::ArrayIt start=NULL, bool allowDups=false) const
CIwManaged * | GetObjNamed (const char *pName, bool allowDups=false) const
uint32 | GetSize () const
CIwManaged * GetTop ()
void | Insert (CIwManaged *pObject, uint32 pos, bool allowDups=false)
void | LockSize (bool lock)
CIwManaged *& | operator[] (int const i) const
void | OptimizeCapacity ()
CIwManaged * Pop ()
void | Push (CIwManaged *pObject, bool allowDups=false)
bool | RemoveFast (CIwManaged *pObject)
bool | RemoveSlow (CIwManaged *pObject)
void | Reserve (uint32 i)
void | Resolve ()
void | ResolvePtrs (const CIwManagedList &list)
void | Serialise ()
void | SerialiseHeader ()
void | SerialisePtrs ()

Detailed Description

A list of managed objects. Implemented using a dynamic array of pointers to managed objects.
See also:
CIwManaged
Required Header Files
IwManagedList.h

Member Function Documentation

void CIwManagedList::Add | ( | CIwManaged * | pObject,
 |  | bool | allowDups = false
 | ) |  |

Adds a managed object pointer to the list.

Parameters:
pObject | The object pointer to add
allowDups | Set to true only if you wish to allow the list to contain more than one object with the same non-zero hash value. The default is false.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::Clear ( ) [inline]

Clears the list but does not free any pointers in the list or any of the managed objects referenced.

Required Header Files
IwManagedList.h

void CIwManagedList::ClearAndFree ( ) [inline]

Performs an optimised clear on the list and frees all pointers, but does not free any managed objects referenced by the list.

Required Header Files
IwManagedList.h

bool CIwManagedList::Contains ( CIwManaged * pObject ) const [inline]

Checks to see if the specified object pointer is contained within the list.

Parameters:
pObject The pointer to check.
Returns:
true if the pointer is present, otherwise false.
Required Header Files
IwManagedList.h

void CIwManagedList::CopyList ( const CIwManagedList & list )

Copies the contents of the supplied list into the caller's list.

Parameters:
list The list to copy.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::Delete ( )

Frees all managed objects referenced by the list.

Required Header Files
IwManagedList.h

CIwManaged** CIwManagedList::Erase ( CIwManaged ** it ) [inline]

Erases a managed object pointer by iterator.

Parameters:
it Iterator indicating entry to remove.
Returns:
The value of it.
See also:
CIwManaged
Required Header Files
IwManagedList.h

uint32 CIwManagedList::EraseFast ( uint32 i ) [inline]

Erases a managed object pointer by index (does not preserve order).

Parameters:
i The index of the entry to delete.
Returns:
The value of i.
See also:
CIwManaged
Required Header Files
IwManagedList.h

int32 CIwManagedList::Find ( CIwManaged *const & pObject ) const [inline]

Returns the index of found object, or -1 if not found.

Parameters:
pObject The pointer to check.
Returns:
true if the pointer is present, otherwise false.
See also:
CIwManaged
Required Header Files
IwManagedList.h

CIwManaged** CIwManagedList::GetBegin ( ) const [inline]

Gets begin() iterator.

Returns:
An iterator to the beginning of the list.
Required Header Files
IwManagedList.h

uint32 CIwManagedList::GetCapacity ( ) const [inline]

Gets the amount of space available in the list, before automatic reallocation will occur.

Returns:
The maximum number of elements which will fit in the list without it being reallocated.
Required Header Files
IwManagedList.h

CIwManaged** CIwManagedList::GetEnd ( ) const [inline]

Gets end() iterator.

Returns:
An iterator to the last element of the list.
See also:
CIwManaged
Required Header Files
IwManagedList.h

CIwManaged* CIwManagedList::GetObjHashed | ( | uint32 | hash,
 |  | bool | allowDups = false |
 | ) |  |  | const

Gets a pointer to a list member by hash.

Parameters:
pName | Pointer to the string hash of the desired list member
allowDups | Set to true only if you wish to permit the list to contain more than one object with the same non-zero hash value. The default is false.
Returns:
A pointer to the requested list member, NULL on failure
See also:
CIwManaged
Note:
This functions causes an assertings if more than one object in the list has the entered hash.
Required Header Files
IwManagedList.h

CIwManaged::ArrayIt CIwManagedList::GetObjHashedNextIt | ( | uint32 | hash,
 |  | CIwManaged::ArrayIt | start = NULL,
 |  | bool | allowDups = false |
 | ) |  |  | const

Gets hashed member. Returns an iterator that can be passed back if you need to get all objects with the given hash.

Parameters:
hash | Hash of the desired member.
start | An iterator pointing to the start of the search run
allowDups | Set to true only if you wish to allow the list to contain more than one object with the same non-zero hash value. The default is false.
Returns:
Returns an iterator to the first location in the list referencing an object with the specified hash.
See also:
CIwManaged

CIwManaged* CIwManagedList::GetObjNamed | ( | const char * | pName,
 |  | bool | allowDups = false |
 | ) |  |  | const

Gets a pointer to a list member by name.

Parameters:
pName | Pointer to the string name of the desired list member
allowDups | Set to true only if you wish to permit the list to contain more than one object with the same non-zero hash value. The default is false.
Returns:
A pointer to the requested list member, NULL on failure
See also:
CIwManaged
Note:
Asserts if more than one object in the list has that hash/name.

uint32 CIwManagedList::GetSize ( ) const [inline]

Gets the number of elements in the list.

Returns:
The number of elements in the list.
Required Header Files
IwManagedList.h

CIwManaged* CIwManagedList::GetTop ( ) [inline]

Interprets a list as stack: gets an item from the top of the stack.

Returns:
The pointer at the top of the stack.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::Insert | ( | CIwManaged * | pObject,
 |  | uint32 | pos,
 |  | bool | allowDups = false |
 | ) |  |  | [inline]

Inserts a managed object pointer at the specified index, pushing the existing entries upwards from the point of insertion.

Parameters:
pObject | The pointer to add
pos | The index position at which to insert the object.
allowDups | Set to true only if you wish to allow the list to contain more than one object with the same non-zero hash value. The default is false.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::LockSize ( bool lock ) [inline]

Lock this list's capacity to its current value. The array will assert if any attempt is made to expand its data allocation.

Note:
The array will still be allowed to shrink, and if an optimised call is used to shrink it then an assert will fire if it tries to increase its capacity subsequently.
Parameters:
lock Lock or release array growing.

CIwManaged* & CIwManagedList::operator[] ( int const i ) const [inline]

Overloaded operator[] for convenience. Gets the item at the specified index.

Parameters:
i The index from which to fetch the item.
See also:
CIwManaged

void CIwManagedList::OptimizeCapacity ( ) [inline]

Optimise capacity so that the minimum amount of memory is used.

CIwManaged* CIwManagedList::Pop ( ) [inline]

Interprets a list as stack: pops an item from the top of the stack.

Parameters:
pObject The pointer to pop.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::Push | ( | CIwManaged * | pObject,
 |  | bool | allowDups = false |
 | ) |  |  | [inline]

Interprets a list as stack: pushes item onto the top of the stack.

Parameters:
pObject | The pointer to push.
allowDups | Set to true only if you wish to allow the list to contain more than one object with the same non-zero hash value. The default is false.
Required Header Files
IwManagedList.h

bool CIwManagedList::RemoveFast ( CIwManaged * pObject ) [inline]

Removes a managed object pointer (does not preserve order).

Parameters:
pObject The pointer to remove.
Returns:
true on sucess, and false on failure.
See also:
CIwManaged
Required Header Files
IwManagedList.h

bool CIwManagedList::RemoveSlow ( CIwManaged * pObject ) [inline]

Removes a managed object pointer (preserves order).

Parameters:
pObject The pointer to remove.
Returns:
true on sucess, and false on failure.
See also:
CIwManaged
Required Header Files
IwManagedList.h

void CIwManagedList::Reserve ( uint32 i ) [inline]

Sets the capacity of the list.

Parameters:
i The new capacity of the list.
Note:
This will cause an assertion if you set your capacity lower than the current size of the list.
Required Header Files
IwManagedList.h

void CIwManagedList::Resolve ( )

Resolve references to other managed objects in the elements of the list. Calls the resolve method on each managed object in the list.

See also:
IwManaged;
Required Header Files
IwManagedList.h

void CIwManagedList::ResolvePtrs ( const CIwManagedList & list )

Resolve hashes of objects in list to ptrs. This is equivalent to calling IwResolveManagedHash for every item in the list.

See also:
IwResolveManagedHash
Required Header Files
IwManagedList.h

void CIwManagedList::Serialise ( )

Serialises all objects in the list using the IwSerialise interface. If we are currently in a serialised write mode then the classes currently in the list are serialised to file. If we are in read mode then each class serialised is instantiated using the appropriate class factory (if avaliable) and added to the list.

See also:
IwSerialise
Required Header Files
IwManagedList.h

void CIwManagedList::SerialiseHeader ( ) [inline]

Serialises the array header using the IwSerlialise interface. For serialised read it reserves list capacity up to the value parsed. For serialised write it writes the list size to file.

See also:
IwSerialise
Required Header Files
IwManagedList.h

void CIwManagedList::SerialisePtrs ( )

Serialise hashes of objects in list. This is equivalent to calling IwSerialiseManagedHash for every item in the list.

See also:
IwSerialiseManagedHash
Required Header Files
IwManagedList.h

The documentation for this class was generated from the following file:
  • IwManagedList.h


Airplay API Reference: CIwMat

Airplay API Reference > Data Structures > CIwMat >

CIwMat Class Reference
[IwGeomMat]

#include <IwGeomMat.h>

Public Member Functions

CIwMat (CIwMat const &R, CIwSVec3 const &T)
CIwMat (CIwMat const &R, CIwVec3 const &T)
CIwMat (const CIwFMat &M)
CIwMat (iwfixed f)
CIwMat ()
CIwVec3 | ColumnX () const
CIwVec3 | ColumnY () const
CIwVec3 | ColumnZ () const
INLINE_MEMBER CIwFMat | ConvertToCIwFMat ()
void | CopyRot (const CIwMat &m0)
void | CopyTrans (const CIwMat &m0)
CIwVec3 const & | GetTrans () const
CIwMat | GetTranspose () const
void | InterpolatePos (CIwMat const &m0, CIwMat const &m1, iwfixed fraction)
void | InterpolateRot (CIwMat const &m0, CIwMat const &m1, iwfixed fraction)
void | InterpRot (CIwMat const &m0, CIwMat const &m1, iwfixed fraction)
void | InterpTrans (CIwMat const &m0, CIwMat const &m1, iwfixed fraction)
bool | IsIdentity () const
bool | IsRotIdentity () const
bool | IsRotSame (CIwMat const &m0) const
bool | IsRotZero () const
bool | IsTransIdentity () const
bool | IsTransSame (CIwMat const &m0) const
bool | IsTransZero () const
bool | IsZero () const
void | LookAt (const CIwVec3 &from, const CIwVec3 &to, const CIwVec3 &up)
void | Normalise ()
CIwMat | operator * (CIwMat const &M) const
CIwMat & | operator *= (const iwfixed v)
CIwMat & | operator *= (CIwMat const &M)
bool | operator!= (CIwMat const &m0) const
CIwMat | operator+ (CIwSVec3 const &V) const
CIwMat | operator+ (CIwVec3 const &V) const
CIwMat & | operator+= (CIwSVec3 const &V)
CIwMat & | operator+= (CIwVec3 const &V)
CIwMat & | operator<<= (int32 s)
bool | operator== (CIwMat const &m0) const
CIwMat & | operator>>= (int32 s)
CIwMat & | PostMult (CIwMat const &M)
CIwMat & | PostMultiply (CIwMat const &M)
CIwMat & | PostRotate (CIwMat const &M)
CIwMat & | PreMult (CIwMat const &M)
CIwMat & | PreMultiply (CIwMat const &M)
CIwMat | PreRotate (CIwMat const &M)
CIwSVec3 | RotateVec (CIwSVec3 const &V) const
CIwVec3 | RotateVec (CIwVec3 const &V) const
CIwVec3 | RotateVecSafe (CIwVec3 const &V) const
INLINE_MEMBER iwsfixed | RotateVecX (const CIwSVec3 &V) const
INLINE_MEMBER iwfixed | RotateVecX (const CIwVec3 &V) const
INLINE_MEMBER iwsfixed | RotateVecY (const CIwSVec3 &V) const
INLINE_MEMBER iwfixed | RotateVecY (const CIwVec3 &V) const
INLINE_MEMBER iwsfixed | RotateVecZ (const CIwSVec3 &V) const
INLINE_MEMBER iwfixed | RotateVecZ (const CIwVec3 &V) const
CIwVec3 | RowX () const
CIwVec3 | RowY () const
CIwVec3 | RowZ () const
CIwMat & | Scale (iwfixed v)
CIwMat & | ScaleRot (iwfixed v)
CIwMat & | ScaleTrans (iwfixed v)
void | Serialise ()
void | SetAxisAngle (CIwVec3 axis, iwangle angle)
void | SetIdentity ()
INLINE_MEMBER void | SetRotX (iwangle r=0, bool resetTrans=true, bool setZeros=true)
INLINE_MEMBER void | SetRotY (iwangle r=0, bool resetTrans=true, bool setZeros=true)
INLINE_MEMBER void | SetRotZ (iwangle r=0, bool resetTrans=true, bool setZeros=true)
CIwMat & | SetTrans (CIwSVec3 const &v)
CIwMat & | SetTrans (CIwVec3 const &v)
void | SetZero ()
CIwVec3 | TransformVec (CIwSVec3 const &V) const
CIwVec3 | TransformVec (CIwVec3 const &V) const
CIwVec3 | TransformVecSafe (CIwSVec3 const &V) const
CIwVec3 | TransformVecSafe (CIwVec3 const &V) const
CIwVec3 | TransformVecShift (CIwSVec3 const &V, int32 shift) const
void | Transpose ()
CIwSVec3 | TransposeRotateVec (CIwSVec3 const &V) const
CIwVec3 | TransposeRotateVec (CIwVec3 const &V) const
CIwVec3 | TransposeRotateVecSafe (CIwVec3 const &V) const
CIwVec3 | TransposeTransformVec (CIwVec3 const &V) const
void | Zero ()

Data Fields

iwfixed | m [3][3]
CIwVec3 t

Static Public Attributes

static CIwMat | g_Identity

Detailed Description

CIwMat - Combines a 3x3 rotation and 3-vector translation.

Note:
The transformation represented by m is normally a rotation, for this reason m will be referred to as a rotation within the following documentation.
0 | 1 | 2 | 3 |  | [0][0] | [0][1] | [0][2]
4 | 5 | 6 | 7 | ==> | [1][0] | [1][1] | [1][2]
8 | 9 | 10 | 11 |  | [2][0] | [2][1] | [2][2]
12 | 13 | 14 | 15 |  | t.x | t.y | t.z
See also:
IwGeomCore

Constructor & Destructor Documentation

CIwMat::CIwMat ( ) [inline]

Creates a new uninitialised matrix.

CIwMat::CIwMat ( iwfixed f ) [inline, explicit]

Creates a new matrix of scales by parameter f along each axis.

Parameters:
f Rotation set as identity scaled by f.

CIwMat::CIwMat ( const CIwFMat & M ) [explicit]

Creates a new matrix from the supplied matrix.

Parameters:
M Reference to matrix to copy.
See also:
CIwFMat

CIwMat::CIwMat | ( | CIwMat const & | R,
 |  | CIwVec3 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (vector) translation

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to vector from which to copy translation.
See also:
CIwVec3

CIwMat::CIwMat | ( | CIwMat const & | R,
 |  | CIwSVec3 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (short vector) translation.

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to short vector from which to copy translation.
See also:
CIwSVec3

Member Function Documentation

CIwVec3 CIwMat::ColumnX ( ) const [inline]

Vector representing the world (codomain) space X-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwVec3::g_AxisX).

CIwVec3 CIwMat::ColumnY ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwVec3::g_AxisY).

CIwVec3 CIwMat::ColumnZ ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwVec3::g_AxisZ).

void CIwMat::CopyRot ( const CIwMat & m0 ) [inline]

Copies rotation from another matrix.

Parameters:
m0 Source matrix.

void CIwMat::CopyTrans ( const CIwMat & m0 ) [inline]

Copies translation from another matrix.

Parameters:
m0 Source matrix.

CIwVec3 const& CIwMat::GetTrans ( ) const [inline]

Gets the translation vector part of a matrix.

Returns:
Reference to the translation vector part of supplied matrix.

CIwMat CIwMat::GetTranspose ( ) const [inline]

Returns:
Matrix with transpose of rotation part and zero translation.

void CIwMat::InterpolatePos | ( | CIwMat const & | m0,
 |  | CIwMat const & | m1,
 |  | iwfixed | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwMat::InterpTrans(m0, m1, fraction).

void CIwMat::InterpolateRot | ( | CIwMat const & | m0,
 |  | CIwMat const & | m1,
 |  | iwfixed | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwMat::InterpRot(m0, m1, fraction).

void CIwMat::InterpRot | ( | CIwMat const & | m0,
 |  | CIwMat const & | m1,
 |  | iwfixed | fraction
 | ) |  |

Linear interpolation of rotation elements.

Parameters:
m0 | Start rotation elements.
m1 | End rotation elements.
fraction Relative amount of start and end elements to use. fraction is constrained to [0, IW_GEOM_ONE].
fraction = 0 results in rotation being set to that of m0.
fraction = IW_GEOM_ONE results in rotationbeing set to that of m1.

void CIwMat::InterpTrans | ( | CIwMat const & | m0,
 |  | CIwMat const & | m1,
 |  | iwfixed | fraction
 | ) |  |

Linear interpolation of translation elements.

Parameters:
m0 | Start translation elements.
m1 | End translation elements.
fraction Relative amount of start and end position to use. fraction is constrained to [0, IW_GEOM_ONE].
fraction = 0 results in position set to that of m0.
fraction = IW_GEOM_ONE results in position being set to that of m1.

bool CIwMat::IsIdentity ( ) const [inline]

Determines if matrix is equal to the identity matrix.

bool CIwMat::IsRotIdentity ( ) const [inline]

Determines if rotation part equal is equal to the identity rotation.

bool CIwMat::IsRotSame ( CIwMat const & m0 ) const [inline]

Determines if rotation part equal to another matrix.

Parameters:
m0 Matrix for comparison with.
Returns:
true if the matrices have equal rotation elements, otherwise false.

bool CIwMat::IsRotZero ( ) const [inline]

Determines if rotation part is equal to zero.

bool CIwMat::IsTransIdentity ( ) const [inline]

Determines if translation part equal is equal to the zero vector.

bool CIwMat::IsTransSame ( CIwMat const & m0 ) const [inline]

Determines if translation part of one matrix is equal to that of another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices have equal translation elements, otherwise false.

bool CIwMat::IsTransZero ( ) const [inline]

Determines if translation part is equal to zero.

bool CIwMat::IsZero ( ) const [inline]

Determines if matrix is equal to zero.

void CIwMat::LookAt | ( | const CIwVec3 & | from,
 |  | const CIwVec3 & | to,
 |  | const CIwVec3 & | up |
 | ) |  |  | [inline]

Creates a matrix looking between the specified points with the given up vector.

Note:
Does not affect translation vector.

Bear in mind that positive y is DOWN the screen.

void CIwMat::Normalise ( ) [inline]

Ensures the rotation part of matrix is orthogonal. (TODO: This function could be faster using Gram-Schmidt orthogonalisation)

CIwMat CIwMat::operator * ( CIwMat const & M ) const [inline]

Composes two matrices together.

Parameters:
M Matrix by which to post multiply.
Returns:
(this matrix) * M. Does not modify either input matrix.

CIwMat& CIwMat::operator *= ( const iwfixed v ) [inline]

Scales matrix.

Parameters:
v Scale to apply to matrix
Returns:
reference to matrix

CIwMat& CIwMat::operator *= ( CIwMat const & M ) [inline]

Post multiplies matrix.

Parameters:
M Matrix by which to multiply.
Returns:
Reference to matrix.

bool CIwMat::operator!= ( CIwMat const & m0 ) const [inline]

Determines if matrix is not equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are not equal, otherwise false.

CIwMat CIwMat::operator+ ( CIwSVec3 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix

CIwMat CIwMat::operator+ ( CIwVec3 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix.

CIwMat& CIwMat::operator+= ( CIwSVec3 const & V ) [inline]

Translates matrix

Parameters:
V Vector to add onto translation part of matrix
Returns:
Reference to matrix

CIwMat& CIwMat::operator+= ( CIwVec3 const & V ) [inline]

Translates matrix.

Parameters:
V Vector to add onto translation part of a matrix.
Returns:
Reference to matrix.

CIwMat& CIwMat::operator<<= ( int32 s ) [inline]

Shifts elements of a matrix.

Parameters:
s Left shift to apply to elements of matrix.
Returns:
Reference to matrix.

bool CIwMat::operator== ( CIwMat const & m0 ) const [inline]

Determines if matrix is equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are equal, otherwise false.

CIwMat& CIwMat::operator>>= ( int32 s ) [inline]

Shifts elements of matrix.

Parameters:
s Right shift to apply to elements of matrix.
Returns:
Reference to matrix.

CIwMat& CIwMat::PostMult ( CIwMat const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to post multiply.
Returns:
(this matrix) * M. Overwrites this matrix.

CIwMat& CIwMat::PostMultiply ( CIwMat const & M ) [inline]

This method is deprecated in favour of CIwMat::PostMult(M).

CIwMat& CIwMat::PostRotate ( CIwMat const & M ) [inline]

Transform the rotation part of the matrix by that of the supplied matrix.

Parameters:
M matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwMat& CIwMat::PreMult ( CIwMat const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to pre multiply.
Returns:
M * (this matrix). Overwrites this matrix.

CIwMat& CIwMat::PreMultiply ( CIwMat const & M ) [inline]

This method is deprecated in favour of CIwMat::PreMult(M).

CIwMat CIwMat::PreRotate ( CIwMat const & M ) [inline]

Transforms the rotation part of the matrix by that of the supplied matrix.

Parameters:
M Matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwSVec3 CIwMat::RotateVec ( CIwSVec3 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V vector to transform.
Returns:
Vec rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::RotateVec ( CIwVec3 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::RotateVecSafe ( CIwVec3 const & V ) const [inline]

Transforms vector by rotation part of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

INLINE_MEMBER iwsfixed CIwMat::RotateVecX ( const CIwSVec3 & V ) const [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
X-component of vector transformed by transpose of rotation part of matrix.

INLINE_MEMBER iwfixed CIwMat::RotateVecX ( const CIwVec3 & V ) const [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
X-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER iwsfixed CIwMat::RotateVecY ( const CIwSVec3 & V ) const [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform
Returns:
Y-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER iwfixed CIwMat::RotateVecY ( const CIwVec3 & V ) const [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Y-component of vector transformed by transpose of rotation part of matrix.

INLINE_MEMBER iwsfixed CIwMat::RotateVecZ ( const CIwSVec3 & V ) const [inline]

If matrix is orthogonal, finds Z component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Z-component of vector transformed by transpose of rotation part of matrix.

INLINE_MEMBER iwfixed CIwMat::RotateVecZ ( const CIwVec3 & V ) const [inline]

If matrix is orthogonal, finds Z component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Z-component of vector transformed by transpose of rotation part of matrix.

CIwVec3 CIwMat::RowX ( ) const [inline]

Vector representing the local (domain) space X-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwVec3::g_AxisX).
Note:
Function has alias VecX.

CIwVec3 CIwMat::RowY ( ) const [inline]

Vector representing the local (domain) space Y-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwVec3::g_AxisY).
Note:
Function has alias VecY.

CIwVec3 CIwMat::RowZ ( ) const [inline]

Vector representing the local (domain) space Z-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwVec3::g_AxisZ).
Note:
Function has alias VecZ.

CIwMat& CIwMat::Scale ( iwfixed v ) [inline]

Scales rotation and translation parts of matrix.

Parameters:
v Scale to apply to matrix.

CIwMat& CIwMat::ScaleRot ( iwfixed v ) [inline]

Scales rotation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

CIwMat& CIwMat::ScaleTrans ( iwfixed v ) [inline]

Scales translation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

void CIwMat::Serialise ( )

Reads/writes binary file using IwSerialise interface.

See also:
IwSerialise

void CIwMat::SetAxisAngle | ( | CIwVec3 | axis,
 |  | iwangle | angle
 | ) |  |

Sets matrix to be rotation by given angle around given axis with zero translation.

Parameters:
axis | Rotation axis (must be a UNIT vector).
angle | Rotation angle.

void CIwMat::SetIdentity ( ) [inline]

Sets matrix to the identity matrix.

INLINE_MEMBER void CIwMat::SetRotX | ( | iwangle | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around X-axis by given angle. The rotation is determined by the element [0][0] and those of the minor matrix [0][0] of the rotation part of the matrix.

Parameters:
r | Angle of rotation
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

INLINE_MEMBER void CIwMat::SetRotY | ( | iwangle | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Y-axis by given angle. The rotation is determined by the element [1][1] and those of the minor matrix [1][1] of the rotation part of the matrix.

Parameters:
r | angle of rotation
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | If the rotation should be zeroed (apart from the elements which determine the rotation).

INLINE_MEMBER void CIwMat::SetRotZ | ( | iwangle | r = 0,
 |  | bool | resetTrans = true,
 |  | bool | setZeros = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis by given angle. The rotation is determined by the element [2][2] and those of the minor matrix [2][2] of the rotation part of the matrix.

Parameters:
r | Angle of rotation.
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

CIwMat& CIwMat::SetTrans ( CIwSVec3 const & v ) [inline]

Sets the translation vector part of the supplied matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

CIwMat& CIwMat::SetTrans ( CIwVec3 const & v ) [inline]

Sets the translation vector part of a matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

void CIwMat::SetZero ( )

Sets matrix to zero.

CIwVec3 CIwMat::TransformVec ( CIwSVec3 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
This overload takes a short vector but it returns a vector, as the translation is a vector.

Debug version provides overflow checking.

CIwVec3 CIwMat::TransformVec ( CIwVec3 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform
Returns:
Vector transformed by matrix.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::TransformVecSafe ( CIwSVec3 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::TransformVecSafe ( CIwVec3 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::TransformVecShift | ( | CIwSVec3 const & | V,
 |  | int32 | shift |
 | ) |  |  | const [inline]

Transforms vector by rotation and then translation parts of matrix using a specifiable shift amount.

Parameters:
V | Vector to transform.
shift | amount to shift rotational component of matrix down by
Returns:
Transformed vector compensated for shift down - so it will be in correct fixed point format.
Note:
This takes a short vector but it returns a vector, as the translation is a vector.

Debug version provides overflow checking.

void CIwMat::Transpose ( )

Transposes rotation part of matrix.

CIwSVec3 CIwMat::TransposeRotateVec ( CIwSVec3 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
Transformed matrix.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::TransposeRotateVec ( CIwVec3 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec3 CIwMat::TransposeRotateVecSafe ( CIwVec3 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix. Calculation is made using int64 numbers.

Parameters:
V vector to transform
Returns:
Transformed matrix.
Note:
Debug version provides overflow checking

CIwVec3 CIwMat::TransposeTransformVec ( CIwVec3 const & V ) const [inline]

If matrix is orthogonal, performs the same operation as transforming vector by inverse of the matrix.

Parameters:
V Vector to transform.
Returns:
Vector, less translation vector, and then transformed by transpose of rotation part of matrix.
Note:
Debug version provides overflow checking.

void CIwMat::Zero ( ) [inline]

This method is deprecated in favour of CIwMat::SetZero().

Field Documentation

CIwMat CIwMat::g_Identity [static]

Identity matrix.

iwfixed CIwMat::m[3][3]

3x3 rotation matrix.

CIwVec3 CIwMat::t

Trans vector.

The documentation for this class was generated from the following file:
  • IwGeomMat.h


Airplay API Reference: CIwMat2D

Airplay API Reference > Data Structures > CIwMat2D >

CIwMat2D Class Reference
[IwGeomMat2D]

#include <IwGeomMat2D.h>

Public Member Functions

CIwMat2D (CIwMat2D const &R, CIwSVec2 const &T)
CIwMat2D (CIwMat2D const &R, CIwVec2 const &T)
CIwMat2D (const CIwFMat2D &M)
CIwMat2D (iwfixed f)
CIwMat2D ()
CIwVec2 | ColumnX () const
CIwVec2 | ColumnY () const
INLINE_MEMBER CIwFMat2D | ConvertToCIwFMat2D ()
void | CopyRot (const CIwMat2D &m0)
void | CopyTrans (const CIwMat2D &m0)
CIwMat2D | GetInverse () const
CIwVec2 const & | GetTrans () const
CIwMat2D | GetTranspose () const
void | InterpolatePos (CIwMat2D const &m0, CIwMat2D const &m1, iwfixed fraction)
void | InterpolateRot (CIwMat2D const &m0, CIwMat2D const &m1, iwfixed fraction)
void | InterpRot (CIwMat2D const &m0, CIwMat2D const &m1, iwfixed fraction)
void | InterpTrans (CIwMat2D const &m0, CIwMat2D const &m1, iwfixed fraction)
bool | IsIdentity ()
bool | IsRotIdentity ()
bool | IsRotSame (CIwMat2D const &m0) const
bool | IsRotZero ()
bool | IsTransIdentity ()
bool | IsTransSame (CIwMat2D const &m0) const
bool | IsTransZero ()
bool | IsZero ()
void | Normalise ()
CIwMat2D | operator * (CIwMat2D const &M) const
CIwMat2D & | operator *= (const iwfixed v)
CIwMat2D & | operator *= (CIwMat2D const &M)
bool | operator!= (CIwMat2D const &m0) const
CIwMat2D | operator+ (CIwSVec2 const &V) const
CIwMat2D | operator+ (CIwVec2 const &V) const
CIwMat2D & | operator+= (CIwSVec2 const &V)
CIwMat2D & | operator+= (CIwVec2 const &V)
CIwMat2D & | operator<<= (int32 s)
bool | operator== (CIwMat2D const &m0) const
CIwMat2D & | operator>>= (int32 s)
CIwMat2D & | PostMult (CIwMat2D const &M)
CIwMat2D & | PostMultiply (CIwMat2D const &M)
CIwMat2D & | PostRotate (CIwMat2D const &M)
CIwMat2D & | PreMult (CIwMat2D const &M)
CIwMat2D & | PreMultiply (CIwMat2D const &M)
CIwMat2D | PreRotate (CIwMat2D const &M)
CIwSVec2 | RotateVec (CIwSVec2 const &V) const
CIwVec2 | RotateVec (CIwVec2 const &V) const
CIwVec2 | RotateVecSafe (CIwVec2 const &V) const
INLINE_MEMBER iwsfixed | RotateVecX (const CIwSVec2 &V)
INLINE_MEMBER iwfixed | RotateVecX (const CIwVec2 &V)
INLINE_MEMBER iwsfixed | RotateVecY (const CIwSVec2 &V)
INLINE_MEMBER iwfixed | RotateVecY (const CIwVec2 &V)
CIwVec2 | RowX () const
CIwVec2 | RowY () const
CIwMat2D & | Scale (iwfixed v)
CIwMat2D & | ScaleRot (iwfixed v)
CIwMat2D & | ScaleTrans (iwfixed v)
void | Serialise ()
void | SetIdentity ()
INLINE_MEMBER void | SetRot (iwangle r, const CIwVec2 &centre)
INLINE_MEMBER void | SetRot (iwangle r=0, bool resetTrans=true)
CIwMat2D & | SetTrans (CIwSVec2 const &v)
CIwMat2D & | SetTrans (CIwVec2 const &v)
void | SetZero ()
CIwVec2 | TransformVec (CIwSVec2 const &V) const
CIwVec2 | TransformVec (CIwVec2 const &V) const
CIwVec2 | TransformVecSafe (CIwSVec2 const &V) const
CIwVec2 | TransformVecSafe (CIwVec2 const &V) const
CIwVec2 | TransformVecShift (CIwSVec2 const &V, int32 shift) const
void | Transpose ()
CIwSVec2 | TransposeRotateVec (CIwSVec2 const &V) const
CIwVec2 | TransposeRotateVec (CIwVec2 const &V) const
CIwVec2 | TransposeRotateVecSafe (CIwVec2 const &V) const
CIwVec2 | TransposeTransformVec (CIwVec2 const &V) const
void | Zero ()

Data Fields

iwfixed | m [2][2]
CIwVec2 t

Static Public Attributes

static CIwMat2D | g_Identity

Detailed Description

CIwMat2D - Combines a 2x2 rotation and 2-vector translation.

Note:
The transformation represented by m is normally a rotation, for this reason m will be referred to as a rotation within the following documentation.
0 | 1 | 2 | 3 |  | [0][0] | [0][1] | [0][2]
4 | 5 | 6 | 7 | ==> | [1][0] | [1][1] | [1][2]
8 | 9 | 10 | 11 |  | [2][0] | [2][1] | [2][2]
12 | 13 | 14 | 15 |  | t.x | t.y | t.z
See also:
IwGeomCore

Constructor & Destructor Documentation

CIwMat2D::CIwMat2D ( ) [inline]

Creates a new uninitialised matrix.

CIwMat2D::CIwMat2D ( iwfixed f ) [inline, explicit]

Creates a new matrix of scales by parameter f along each axis.

Parameters:
f Rotation set as identity scaled by f.

CIwMat2D::CIwMat2D ( const CIwFMat2D & M ) [explicit]

Creates a new matrix from the supplied matrix.

Parameters:
M Reference to matrix to copy.
See also:
CIwFMat2D

CIwMat2D::CIwMat2D | ( | CIwMat2D const & | R,
 |  | CIwVec2 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (vector) translation

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to vector from which to copy translation.
See also:
CIwVec2

CIwMat2D::CIwMat2D | ( | CIwMat2D const & | R,
 |  | CIwSVec2 const & | T |
 | ) |  |  | [inline]

Creates a new matrix with given rotation and (short vector) translation.

Parameters:
R | Reference to matrix from which to copy rotation.
T | Reference to short vector from which to copy translation.
See also:
CIwSVec2

Member Function Documentation

CIwVec2 CIwMat2D::ColumnX ( ) const [inline]

Vector representing the world (codomain) space X-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwVec2::g_AxisX).

CIwVec2 CIwMat2D::ColumnY ( ) const [inline]

Vector representing the world (codomain) space Y-axis in local (domain) space.

Returns:
The same vector as calling TransposeRotateVec(CIwVec2::g_AxisY).

void CIwMat2D::CopyRot ( const CIwMat2D & m0 ) [inline]

Copies rotation from another matrix.

Parameters:
m0 Source matrix.

void CIwMat2D::CopyTrans ( const CIwMat2D & m0 ) [inline]

Copies translation from another matrix.

Parameters:
m0 Source matrix.

CIwMat2D CIwMat2D::GetInverse ( ) const

@ return Matrix that represents the inverse operation. Will return identity if inverse is not possible (i.e. determinant is zero)

CIwVec2 const& CIwMat2D::GetTrans ( ) const [inline]

Gets the translation vector part of a matrix.

Returns:
Reference to the translation vector part of supplied matrix.

CIwMat2D CIwMat2D::GetTranspose ( ) const [inline]

Returns:
Matrix with transpose of rotation part and zero translation.

void CIwMat2D::InterpolatePos | ( | CIwMat2D const & | m0,
 |  | CIwMat2D const & | m1,
 |  | iwfixed | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwMat2D::InterpTrans(m0, m1, fraction).

void CIwMat2D::InterpolateRot | ( | CIwMat2D const & | m0,
 |  | CIwMat2D const & | m1,
 |  | iwfixed | fraction |
 | ) |  |  | [inline]

This method is deprecated in favour of CIwMat2D::InterpRot(m0, m1, fraction).

void CIwMat2D::InterpRot | ( | CIwMat2D const & | m0,
 |  | CIwMat2D const & | m1,
 |  | iwfixed | fraction
 | ) |  |

Linear interpolation of rotation elements.

Parameters:
m0 | Start rotation elements.
m1 | End rotation elements.
fraction Relative amount of start and end elements to use. fraction is constrained to [0, IW_GEOM_ONE].
fraction = 0 results in rotation being set to that of m0.
fraction = IW_GEOM_ONE results in rotationbeing set to that of m1.

void CIwMat2D::InterpTrans | ( | CIwMat2D const & | m0,
 |  | CIwMat2D const & | m1,
 |  | iwfixed | fraction
 | ) |  |

Linear interpolation of translation elements.

Parameters:
m0 | Start translation elements.
m1 | End translation elements.
fraction Relative amount of start and end position to use. fraction is constrained to [0, IW_GEOM_ONE].
fraction = 0 results in position set to that of m0.
fraction = IW_GEOM_ONE results in position being set to that of m1.

bool CIwMat2D::IsIdentity ( ) [inline]

Determines if matrix is equal to the identity matrix.

bool CIwMat2D::IsRotIdentity ( ) [inline]

Determines if rotation part equal is equal to the identity rotation.

bool CIwMat2D::IsRotSame ( CIwMat2D const & m0 ) const [inline]

Determines if rotation part equal to another matrix.

Parameters:
m0 Matrix for comparison with.
Returns:
true if the matrices have equal rotation elements, otherwise false.

bool CIwMat2D::IsRotZero ( ) [inline]

Determines if rotation part is equal to zero.

bool CIwMat2D::IsTransIdentity ( ) [inline]

Determines if translation part equal is equal to the zero vector.

bool CIwMat2D::IsTransSame ( CIwMat2D const & m0 ) const [inline]

Determines if translation part of one matrix is equal to that of another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices have equal translation elements, otherwise false.

bool CIwMat2D::IsTransZero ( ) [inline]

Determines if translation part is equal to zero.

bool CIwMat2D::IsZero ( ) [inline]

Determines if matrix is equal to zero.

void CIwMat2D::Normalise ( ) [inline]

Ensures the rotation part of matrix is orthogonal. (TODO: This function could be faster using Gram-Schmidt orthogonalisation)

CIwMat2D CIwMat2D::operator * ( CIwMat2D const & M ) const [inline]

Composes two matrices together.

Parameters:
M Matrix by which to post multiply.
Returns:
(this matrix) * M. Does not modify either input matrix.

CIwMat2D& CIwMat2D::operator *= ( const iwfixed v ) [inline]

Scales matrix.

Parameters:
v Scale to apply to matrix
Returns:
reference to matrix

CIwMat2D& CIwMat2D::operator *= ( CIwMat2D const & M ) [inline]

Post multiplies matrix.

Parameters:
M Matrix by which to multiply.
Returns:
Reference to matrix.

bool CIwMat2D::operator!= ( CIwMat2D const & m0 ) const [inline]

Determines if matrix is not equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are not equal, otherwise false.

CIwMat2D CIwMat2D::operator+ ( CIwSVec2 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix

CIwMat2D CIwMat2D::operator+ ( CIwVec2 const & V ) const [inline]

Gets a copy of this matrix translated by given vector.

Parameters:
V Vector by which to translate matrix copy.
Returns:
Translated matrix.

CIwMat2D& CIwMat2D::operator+= ( CIwSVec2 const & V ) [inline]

Translates matrix

Parameters:
V Vector to add onto translation part of matrix
Returns:
Reference to matrix

CIwMat2D& CIwMat2D::operator+= ( CIwVec2 const & V ) [inline]

Translates matrix.

Parameters:
V Vector to add onto translation part of a matrix.
Returns:
Reference to matrix.

CIwMat2D& CIwMat2D::operator<<= ( int32 s ) [inline]

Shifts elements of a matrix.

Parameters:
s Left shift to apply to elements of matrix.
Returns:
Reference to matrix.

bool CIwMat2D::operator== ( CIwMat2D const & m0 ) const [inline]

Determines if matrix is equal to another matrix.

Parameters:
m0 Matrix for comparison.
Returns:
true if the matrices are equal, otherwise false.

CIwMat2D& CIwMat2D::operator>>= ( int32 s ) [inline]

Shifts elements of matrix.

Parameters:
s Right shift to apply to elements of matrix.
Returns:
Reference to matrix.

CIwMat2D& CIwMat2D::PostMult ( CIwMat2D const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to post multiply.
Returns:
(this matrix) * M. Overwrites this matrix.

CIwMat2D& CIwMat2D::PostMultiply ( CIwMat2D const & M ) [inline]

This method is deprecated in favour of CIwMat2D::PostMult(M).

CIwMat2D& CIwMat2D::PostRotate ( CIwMat2D const & M ) [inline]

Transform the rotation part of the matrix by that of the supplied matrix.

Parameters:
M matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwMat2D& CIwMat2D::PreMult ( CIwMat2D const & M ) [inline]

Composes two matrices together.

Parameters:
M matrix by which to pre multiply.
Returns:
M * (this matrix). Overwrites this matrix.

CIwMat2D& CIwMat2D::PreMultiply ( CIwMat2D const & M ) [inline]

This method is deprecated in favour of CIwMat2D::PreMult(M).

CIwMat2D CIwMat2D::PreRotate ( CIwMat2D const & M ) [inline]

Transforms the rotation part of the matrix by that of the supplied matrix.

Parameters:
M Matrix from which to apply rotation.
Returns:
Reference to matrix.

CIwSVec2 CIwMat2D::RotateVec ( CIwSVec2 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V vector to transform.
Returns:
Vec rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::RotateVec ( CIwVec2 const & V ) const [inline]

Transforms vector by rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::RotateVecSafe ( CIwVec2 const & V ) const [inline]

Transforms vector by rotation part of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Vector rotated by rotation part of matrix.
Note:
Debug version provides overflow checking.

INLINE_MEMBER iwsfixed CIwMat2D::RotateVecX ( const CIwSVec2 & V ) [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
X-component of vector transformed by transpose of rotation part of matrix.

INLINE_MEMBER iwfixed CIwMat2D::RotateVecX ( const CIwVec2 & V ) [inline]

If matrix is orthogonal, finds X component of vector transformed by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
X-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER iwsfixed CIwMat2D::RotateVecY ( const CIwSVec2 & V ) [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform
Returns:
Y-component of vector transformed by transpose of rotation part of matrix

INLINE_MEMBER iwfixed CIwMat2D::RotateVecY ( const CIwVec2 & V ) [inline]

If matrix is orthogonal, finds Y component of vector transformed by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Y-component of vector transformed by transpose of rotation part of matrix.

CIwVec2 CIwMat2D::RowX ( ) const [inline]

Vector representing the local (domain) space X-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwVec2::g_AxisX).
Note:
Function has alias VecX.

CIwVec2 CIwMat2D::RowY ( ) const [inline]

Vector representing the local (domain) space Y-axis in world (codomain) space.

Returns:
The same vector as calling RotateVec(CIwVec2::g_AxisY).
Note:
Function has alias VecY.

CIwMat2D& CIwMat2D::Scale ( iwfixed v ) [inline]

Scales rotation and translation parts of matrix.

Parameters:
v Scale to apply to matrix.

CIwMat2D& CIwMat2D::ScaleRot ( iwfixed v ) [inline]

Scales rotation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

CIwMat2D& CIwMat2D::ScaleTrans ( iwfixed v ) [inline]

Scales translation part of matrix.

Parameters:
v Scale to apply to rotation.
Returns:
Reference to matrix.

void CIwMat2D::Serialise ( )

Reads/writes binary file using IwSerialise interface.

See also:
IwSerialise

void CIwMat2D::SetIdentity ( ) [inline]

Sets matrix to the identity matrix.

INLINE_MEMBER void CIwMat2D::SetRot | ( | iwangle | r,
 |  | const CIwVec2 & | centre |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis at a point by given angle

Parameters:
r | Angle of rotation
centre | Centre of rotation

INLINE_MEMBER void CIwMat2D::SetRot | ( | iwangle | r = 0,
 |  | bool | resetTrans = true |
 | ) |  |  | [inline]

Sets matrix to be rotation around Z-axis by given angle.

Parameters:
r | Angle of rotation.
resetTrans | Whether the translation part of the matrix should be reset.
setZeros | Whether the rotation should be zeroed (apart from the elements which determine the rotation).

CIwMat2D& CIwMat2D::SetTrans ( CIwSVec2 const & v ) [inline]

Sets the translation vector part of the supplied matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

CIwMat2D& CIwMat2D::SetTrans ( CIwVec2 const & v ) [inline]

Sets the translation vector part of a matrix.

Parameters:
v Reference to vector to be set as translation part of a matrix.
Returns:
Reference to matrix.

void CIwMat2D::SetZero ( )

Sets matrix to zero.

CIwVec2 CIwMat2D::TransformVec ( CIwSVec2 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
This overload takes a short vector but it returns a vector, as the translation is a vector.

Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransformVec ( CIwVec2 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix.

Parameters:
V Vector to transform
Returns:
Vector transformed by matrix.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransformVecSafe ( CIwSVec2 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransformVecSafe ( CIwVec2 const & V ) const [inline]

Transforms vector by rotation and then translation parts of matrix. Calculation is made using int64 numbers.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransformVecShift | ( | CIwSVec2 const & | V,
 |  | int32 | shift |
 | ) |  |  | const [inline]

Transforms vector by rotation and then translation parts of matrix using a specifiable shift amount.

Parameters:
V | Vector to transform.
shift | amount to shift rotational component of matrix down by
Returns:
Transformed vector compensated for shift down - so it will be in correct fixed point format.
Note:
This takes a short vector but it returns a vector, as the translation is a vector.

Debug version provides overflow checking.

void CIwMat2D::Transpose ( )

Transposes rotation part of matrix.

CIwSVec2 CIwMat2D::TransposeRotateVec ( CIwSVec2 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V vector to transform
Returns:
Transformed matrix.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransposeRotateVec ( CIwVec2 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix.

Parameters:
V Vector to transform.
Returns:
Transformed vector.
Note:
Debug version provides overflow checking.

CIwVec2 CIwMat2D::TransposeRotateVecSafe ( CIwVec2 const & V ) const [inline]

If matrix is orthogonal, transforms vector by inverse of rotation part of matrix. Calculation is made using int64 numbers.

Parameters:
V vector to transform
Returns:
Transformed matrix.
Note:
Debug version provides overflow checking

CIwVec2 CIwMat2D::TransposeTransformVec ( CIwVec2 const & V ) const [inline]

If matrix is orthogonal, performs the same operation as transforming vector by inverse of the matrix.

Parameters:
V Vector to transform.
Returns:
Vector, less translation vector, and then transformed by transpose of rotation part of matrix.
Note:
Debug version provides overflow checking.

void CIwMat2D::Zero ( ) [inline]

This method is deprecated in favour of CIwMat2D::SetZero().

Field Documentation

CIwMat2D CIwMat2D::g_Identity [static]

Identity matrix.

iwfixed CIwMat2D::m[2][2]

2x2 rotation matrix.

CIwVec2 CIwMat2D::t

Trans vector.

The documentation for this class was generated from the following file:
  • IwGeomMat2D.h


Airplay API Reference: CIwMaterial

Airplay API Reference > Data Structures > CIwMaterial >

CIwMaterial Class Reference
[Materials]

#include <IwMaterial.h>

Inheritance diagram for CIwMaterial:

[legend]

Public Types

enum AlphaMode {
ALPHA_NONE,
ALPHA_HALF,
ALPHA_ADD,
ALPHA_SUB,
ALPHA_BLEND,
ALPHA_DEFAULT
}
enum | AlphaTestMode
enum | BlendMode
enum CullMode {
CULL_FRONT,
CULL_BACK,
CULL_NONE
}
enum | DepthWriteMode
enum | EffectPreset
enum ModulateMode {
MODULATE_RGB,
MODULATE_R,
MODULATE_NONE
}
enum ShadeMode {
SHADE_FLAT,
SHADE_GOURAUD
}

Public Member Functions

void | Copy (const CIwMaterial &mat)
void | CreateAnim ()
AlphaMode | GetAlphaMode () const
AlphaTestMode | GetAlphaTestMode () const
uint8 | GetAlphaTestRefVal () const
uint8 | GetAnimCelH () const
uint8 | GetAnimCelID () const
uint8 | GetAnimCelNum () const
uint8 | GetAnimCelNumU () const
uint8 | GetAnimCelPeriod () const
uint8 | GetAnimCelW () const
uint8 | GetAnimOfsU () const
uint8 | GetAnimOfsV () const
BlendMode | GetBlendMode () const
bool | GetClamping ()
CIwColour & GetColAmbient ()
CIwColour & GetColDiffuse ()
CIwColour & GetColEmissive ()
CIwColour & GetColSpecular ()
CullMode GetCullMode ()
EffectPreset | GetEffectPreset () const
bool | GetFiltering ()
bool | GetMergeGeom () const
ModulateMode GetModulateMode ()
ShadeMode GetShadeMode ()
uint8 | GetSpecularPower ()
CIwTexture * | GetTexture (uint32 t=0) const
uint16 | GetUserFlags () const
const CIwSVec2 & | GetUVOfs () const
int32 | GetZDepthOfs () const
int32 | GetZDepthOfsHW () const
bool | HasIdentityAmbient () const
bool | HasIdentityCols () const
bool | HasIdentityDiffuse () const
bool | HasIdentityEmissive () const
bool | IsAnim ()
bool | IsAnimPaused () const
bool | IsEquivalent (const CIwMaterial &mat)
bool | IsInvisible ()
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseOpen (CIwTextParserITX *pParser)
void | PauseAnim ()
void | Reset ()
virtual void | Resolve ()
void | RestartAnim ()
virtual void | Serialise ()
void | SetAlphaMode (AlphaMode mode)
void | SetAlphaTestMode (AlphaTestMode mode)
void | SetAlphaTestRefVal (uint8 alphaRefVal)
void | SetAnimCelH (uint8 n)
void | SetAnimCelID (uint8 celID)
void | SetAnimCelNum (uint8 n)
void | SetAnimCelNumU (uint8 n)
void | SetAnimCelPeriod (uint8 n)
void | SetAnimCelW (uint8 n)
void | SetAnimOfsU (uint8 n)
void | SetAnimOfsV (uint8 n)
void | SetBlendMode (BlendMode mode)
void | SetClamping (bool b)
void | SetColAmbient (const CIwColour &col)
void | SetColAmbient (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
void | SetColAmbient (uint32 col)
void | SetColDiffuse (const CIwColour &col)
void | SetColDiffuse (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
void | SetColDiffuse (uint32 col)
void | SetColEmissive (const CIwColour &col)
void | SetColEmissive (uint8 _r, uint8 _g, uint8 _b, uint8 _a)
void | SetColEmissive (uint32 col)
void | SetColSpecular (const CIwColour &col)
void | SetColSpecular (uint8 _r, uint8 _g, uint8 _b)
void | SetColSpecular (uint32 col)
void | SetCullMode (CullMode m)
void | SetEffectPreset (EffectPreset effectpreset)
void | SetFiltering (bool b)
void | SetInvisible (bool b)
void | SetMergeGeom (bool set)
void | SetModulateMode (ModulateMode m)
virtual void | SetName (const char *pName)
void | SetShadeMode (ShadeMode m)
void | SetSpecularPower (uint8 power)
void | SetTexture (CIwTexture *pTex, uint32 t=0)
void | SetUserFlags (uint16 flags)
void | SetUVOfs (const CIwSVec2 *pOfs)
void | SetZDepthOfs (int32 val)
void | SetZDepthOfsHW (int32 val)
Constructors & Destructor
CIwMaterial ()
virtual | ~CIwMaterial ()

Friends

CIwMaterial * IW_GX_ALLOC_MATERIAL ()
void | IwGxDrawPrims (IwGxPrimType, uint16 *, uint32)
void | IwGxFlush ()

Detailed Description

Material object. See the Materials module overview for more information.

CIwMaterial objects accept the following attributes in ITX files:
Attribute | Value | Description | Example
name | (string) | Material name | name "Material1"
texture0 | (texture name) | Specify texture for stage 0 (diffuse map). | texture0 "Grass"
texture1 | (texture name) | Specify texture for stage 1. | texture1 "Lightmap"
vertexShader | (vertex shader name) | Specify vertex shader to use. | vertexShader "reflectx"
colEmissive | {r, g, b, a} | Emissive colour. | colEmissive {0, 128, 255, 255}
colAmbient | {r, g, b, a} | Ambient colour. | colAmbient {0, 128, 255, 255}
colDiffuse | {r, g, b, a} | Diffuse colour. | colDiffuse {0, 128, 255, 255}
colSpecular | {r, g, b, a} | Specular colour. | colSpecular { 255, 255, 255, 255}
specularPower | (integer) | The specular cosine power. | specularPower 10
shadeMode | (FLAT or GOURAUD) | Shading mode. | shadeMode FLAT
modulateMode | (R or RGB or NONE) | Modulation mode (of texel by vertex colour). | modulateMode RGB
cullMode | (BACK or FRONT or NONE) | Backface culling mode. | cullMode NONE
alphaMode | (NONE or ADD or SUB or HALF or BLEND) | Transparency (alpha) mode. | alphaMode ADD
blendMode | (MODULATE or DECAL or ADD or REPLACE or BLEND) | Blend mode between texture stages 0 and 1. | blendMode MODULATE
effectPreset | (DEFAULT or NORMAL_MAPPING or NORMAL_MAPPING_SPECULAR or REFLECTION_MAPPING) | Preset multi-texturing effect. | effectPreset NORMAL_MAPPING
alphaTest | (DISABLED or NEVER or LESS or EQUAL or LEQUAL or GREATER or NOTEQUAL or GEQUAL or ALWAYS, followed by a uint8 value (0..255)) | Specify the alpha test function as well as the alpha test reference value. | alphaTest LESS 100
zDepthOfs | (-32768 .. 32767) | Depth offset to apply when using SW rasterisation. | zDepthOfs 100
zDepthOfsHW | (-32768 .. 32767) | Depth offset to apply when using HW rasterisation. | zDepthOfsHW 1
invisible | true or false | True only if the material should not be rendered. | invisible true
filtering | true or false | True only if the material's textures should use bilinear filtering. | filtering false
depthWriteEnable | true or false | Enable writing to depth buffer. Only affects HW rasterisation. Defaults to on. | depthWriteEnable false
mergeGeom | true or false | Enable geometry merging for this material. | mergeGeom true
celW | 0 .. 255 | UV animation: width of cel (U delta to apply at each update). | celW 4
celH | 0 .. 255 | UV animation: height of cel (V delta to apply when a "row" of cels is complete). | celH 16
celNum | 0 .. n | UV animation: total number of cels before animation restarts. | celNum 32
celNumU | 0 .. n | UV animation: total number of cels in a "row", i.e. before applying a V delta. | celNumU 8
celPeriod | 0 .. n | UV animation: number of application updates before each UV animation update. | celPeriod 1
formatSW | (image format) | Specify a format to convert the image to, before uploading for SW rasterisation. | formatSW PALETTE4_ABGR_1555
formatHW | (image format) | Specify a format to convert the image to, before uploading for HW rasterisation. | formatHW PALETTE4_RGBA_4444
keepAfterUpload | true or false | Keep the contents of the texture after upload. Normally uploaded texels are deleted. | keepAfterUpload true
clampUV | true or false | If true the texture UV coordinates are clamped. | clampUV true
noFog | true or false | Disable fogging for this material. | noFog true
shaderTechnique | (technique name) | Attach the specified shader to this material. | shaderTechnique dot3

Member Enumeration Documentation

enum CIwMaterial::AlphaMode

Alpha (transparency) modes.

See also:
GetAlphaMode, SetAlphaMode
Required Header Files
IwMaterial.h
Enumerator:
ALPHA_NONE | Material is opaque (not transparent).
ALPHA_HALF | Material is transparent. Source colour (as calculated by the lighting pipeline) and destination colour (the current colour in the backbuffer) are combined as follows: Colour = (Source + Destination) / 2
ALPHA_ADD | Material is transparent. Source colour (as calculated by the lighting pipeline) and destination colour (the current colour in the backbuffer) are combined as follows: Colour = (Source + Destination)
ALPHA_SUB | Material is transparent. Source colour (as calculated by the lighting pipeline) and destination colour (the current colour in the backbuffer) are combined as follows: Colour = (Destination - Source)
ALPHA_BLEND Material is transparent. Source colour (as calculated by the lighting pipeline) and destination colour (the current colour in the backbuffer) are combined as follows: Colour = (Source * SourceAlpha) + (Destination * (1 - SourceAlpha))
Note:
This mode is not available when using software rasterisation; in that case, it performs identically to ALPHA_NONE.
ALPHA_DEFAULT | TODO bgp Material is transparent. Source colour (as calculated by the lighting pipeline) and destination colour (the current colour in the backbuffer) are combined as follows: Colour = (Source + Destination) / 2

enum CIwMaterial::AlphaTestMode

Alpha (transparency) Testing modes.

See also:
GetAlphaTestMode, SetAlphaTestMode
Required Header Files
IwMaterial.h
Enumerator:
ALPHATEST_DISABLED | no alpha testing;
ALPHATEST_NEVER | never pass alpha test;
ALPHATEST_LESS | pass alpha test when alpha is less that reference value;
ALPHATEST_EQUAL | pass alpha test when alpha is equal that reference value;
ALPHATEST_LEQUAL | pass alpha test when alpha is less or equal that reference value;
ALPHATEST_GREATER | pass alpha test when alpha is greater that reference value;
ALPHATEST_NOTEQUAL | pass alpha test when alpha is not equal that reference value;
ALPHATEST_GEQUAL | pass alpha test when alpha is greater or equal that reference value;
ALPHATEST_ALWAYS | always pass the alpha test;

enum CIwMaterial::BlendMode

Blend modes for 2nd texture, if any.

See also:
GetBlendMode, SetBlendMode
Required Header Files
IwMaterial.h
Enumerator:
BLEND_MODULATE | multiply;
BLEND_DECAL | decal;
BLEND_ADD | additive;
BLEND_REPLACE | replace;
BLEND_BLEND | blend (strange inverting behaviour);

enum CIwMaterial::CullMode

Backface culling modes.

See also:
GetCullMode, SetCullMode
Required Header Files
IwMaterial.h
Enumerator:
CULL_FRONT | Polygons with a clockwise winding order are culled.
CULL_BACK | Polygons with an anti-clockwise winding order are culled.
CULL_NONE | Polygons are not culled (polygons are "double-sided").

enum CIwMaterial::DepthWriteMode

Depth write mode. Only affects gl.

See also:
GetDepthWrite, SetDepthWrite
Required Header Files
IwMaterial.h
Enumerator:
DEPTH_WRITE_NORMAL | Defer to blend mode to determine depth buffer write.
DEPTH_WRITE_DISABLED | Disable depth buffer write.

enum CIwMaterial::EffectPreset

Preset effect modes.

See also:
GetEffectPreset, SetEffectPreset
Required Header Files
IwMaterial.h
Enumerator:
EFFECT_DEFAULT | Combine 2nd texture using BlendMode, use 2nd UV set if available, otherwise 1st UV set.
EFFECT_NORMAL_MAPPING | Use 2nd texture as a normal map, then use BlendMode to combine 1st texture.
EFFECT_REFLECTION_MAPPING | Combine 2nd texture as a spherical reflection map, Automatically computes reflection UVs.
EFFECT_CONSTANT_COLOUR_CHANNEL | Use primary colour for RGB.
EFFECT_LIGHTMAP_POST_PROCESS | Modulate in framebuffer for gl lightmaps.
EFFECT_NORMAL_MAPPING_SPECULAR | Use 2nd texture as a specular normal map, then use BlendMode to combine 1st texture.
EFFECT_TEXTURE0_ONLY | Ignore the second texture stage on non-shader HW.

enum CIwMaterial::ModulateMode

Modulation modes. For textured materials, this affects how the texel colour is modified by the vertex colour to calculate the colour to be written to the backbuffer.

See also:
GetModulateMode, SetModulateMode
Required Header Files
IwMaterial.h
Enumerator:
MODULATE_RGB | Texel colour is modified by vertex colour in the following way: Cr = Tr * Vr, Cg = Tg * Vg, Cb = Tb * Vb, Ca = Ta * Va Because this carries a significant performance penalty in SW rendering, an application must opt-in to full SW RGB modulation by including "[GX] UseRGBLighting=1" in its icf file. HW accelerated rendering always respects MODULATE_RGB.
MODULATE_R | Texel colour is modified by vertex colour in the following way: Cr = Cg = Cb = Tr * Vr, Ca = 0xFF
MODULATE_NONE | Texel colour is NOT modified by vertex colour, so the final colour is always equal to the texel colour: Cr = Tr, Cg = Tg, Cb = Tb, Ca = Ta

enum CIwMaterial::ShadeMode

Shade modes.

See also:
GetShadeMode, SetShadeMode
Required Header Files
IwMaterial.h
Enumerator:
SHADE_FLAT | Polygons are flat-shaded according to the colour of the first vertex in each polygon, so each polygon is a single colour.
SHADE_GOURAUD | Polygons are gouraud-shaded according to the vertex colours.

Constructor & Destructor Documentation

CIwMaterial::CIwMaterial ( )

Default constructor.

Note:
If this material is constructed on the data cache then it destructor will never get called.

virtual CIwMaterial::~CIwMaterial ( ) [virtual]

Destructor.

Note:
This never gets called for a material created on the data cache.

Member Function Documentation

void CIwMaterial::Copy ( const CIwMaterial & mat )

Copy all settings from the input material.

Parameters:
mat Referencer to the material to copy from.

void CIwMaterial::CreateAnim ( )

Creates a UV animation structure.

Note:
This function must be called before calling any of the other UV-animation functions.

For more information on how to implement UV animation, see UV Animation.
Required Header Files
IwMaterial.h

virtual void CIwMaterial::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

AlphaMode CIwMaterial::GetAlphaMode ( ) const [inline]

Gets alpha (transparency) mode.

Returns:
Enumerated alpha mode.
See also:
SetAlphaMode
Required Header Files
IwMaterial.h

AlphaTestMode CIwMaterial::GetAlphaTestMode ( ) const [inline]

Gets alpha (transparency) test mode.

Returns:
Enumerated alpha test mode.
See also:
SetAlphaTestMode
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAlphaTestRefVal ( ) const [inline]

Gets alpha (transparency) test reference value.

Returns:
uint8 alpha test reference value.
See also:
SetAlphaTestRefVal
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelH ( ) const [inline]

Gets the height of each cel, in texels.

Returns:
Height in texels.
See also:
SetAnimCelH, SetAnimCelW, GetAnimCelW
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelID ( ) const [inline]

Gets the ID of the current cel in this animation.

Returns:
The ID of the current cel.
See also:
SetAnimCelNum, SetAnimCelNumU
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelNum ( ) const [inline]

Gets the number of cels in the animation.

Returns:
The number of cels.
See also:
SetAnimCelNum
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelNumU ( ) const [inline]

Gets the number of cels across each row of the texture.

Returns:
The number of cels.
See also:
SetAnimCelNumU
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelPeriod ( ) const [inline]

Gets the animation period. This is the number of frame updates before changing to the next cel.

Returns:
Animation period, in frames.
See also:
SetAnimCelPeriod, Pause, Restart, IsPaused
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimCelW ( ) const [inline]

Gets the width of each cel, in texels.

Returns:
Width in texels.
See also:
SetAnimCelW, SetAnimCelH, GetAnimCelH
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimOfsU ( ) const [inline]

Equivalent to GetAnimCelW().

See also:
GetAnimCelW
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetAnimOfsV ( ) const [inline]

Equivalent to GetAnimCelH().

See also:
GetAnimCelH
Required Header Files
IwMaterial.h

BlendMode CIwMaterial::GetBlendMode ( ) const [inline]

Gets blend mode.

Returns:
Enumerated blend mode.
See also:
SetBlendMode
Required Header Files
IwMaterial.h

bool CIwMaterial::GetClamping ( )

Gets whether or not the material has been set to clamped texture coordinates.

Returns:
True only if all the textures of the material have been set to use clamped texture coordinates.
See also:
SetClamping
Required Header Files
IwMaterial.h

CIwColour& CIwMaterial::GetColAmbient ( ) [inline]

Gets the current ambient colour.

Returns:
The current ambient colour.
See also:
SetColAmbient
Required Header Files
IwMaterial.h

CIwColour& CIwMaterial::GetColDiffuse ( ) [inline]

Gets the current diffuse colour.

Returns:
The current diffuse colour.
See also:
SetColDiffuse
Required Header Files
IwMaterial.h

CIwColour& CIwMaterial::GetColEmissive ( ) [inline]

Gets the current emissive colour.

Returns:
The current emissive colour.
See also:
SetColEmissive
Required Header Files
IwMaterial.h

CIwColour& CIwMaterial::GetColSpecular ( ) [inline]

Gets the current specular colour, with the specular power in its alpha channel

Returns:
The current specular colour.
See also:
SetColSpecular
Required Header Files
IwMaterial.h

CullMode CIwMaterial::GetCullMode ( )

Gets the material cull mode; this can be either CULL_FRONT, CULL_BACK or CULL_NONE (double-sided).

Returns:
m The material cull mode.
See also:
SetCullMode
Required Header Files
IwMaterial.h

EffectPreset CIwMaterial::GetEffectPreset ( ) const [inline]

Gets effect preset.

Returns:
Enumerated preset effect.
See also:
SetEffectPreset
Required Header Files
IwMaterial.h

bool CIwMaterial::GetFiltering ( )

Gets whether or not the material has been set to use bi-linear filtering.

Returns:
True only if all the material has been set to use bi-linear filtering.
See also:
SetFiltering
Required Header Files
IwMaterial.h

bool CIwMaterial::GetMergeGeom ( ) const [inline]

Gets the merged geometry status.

See also:
SetMergeGeom
Required Header Files
IwMaterial.h

ModulateMode CIwMaterial::GetModulateMode ( ) [inline]

Gets the material modulation mode; this can be either MODULATE_RGB or MODULATE_R.

Returns:
The material modulation mode.
See also:
SetModulateMode
Required Header Files
IwMaterial.h

ShadeMode CIwMaterial::GetShadeMode ( ) [inline]

Gets the material shade mode; this can be either SHADE_FLAT or SHADE_GOURAUD.

Returns:
The material shade mode.
See also:
SetShadeMode
Required Header Files
IwMaterial.h

uint8 CIwMaterial::GetSpecularPower ( ) [inline]

Gets the current specular power.

Returns:
The current specular power.
Note:
When a material is constructed, its specular colour/power is copied from the template material.
See also:
GetColSpecular, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

CIwTexture* CIwMaterial::GetTexture ( uint32 t = 0 ) const [inline]

Gets the texture to use (at specified stage).

Note:
The Airplay software renderer supports only stage 0 - the diffuse map. Hardware-accelerated sub-systems may support multiple texture stages.
Parameters:
t The stage to query (0 if not specified).
Returns:
The texture used at the specified stage.
See also:
SetTexture
Required Header Files
IwMaterial.h

uint16 CIwMaterial::GetUserFlags ( ) const [inline]

Gets user flags.

Note:
The material makes a special 16-bit flags field available to the user. The user can read and write these flags at will, and they are untouched by the system.. @
Returns:
The user flags currently set on the material.
See also:
SetUserFlags
Required Header Files
IwMaterial.h

const CIwSVec2& CIwMaterial::GetUVOfs ( ) const [inline]

Gets the current UV offset for this material.

Note:
The UV offset will be added to all UV coordinates, for streams drawn with this material.
Returns:
The current UV offset.
See also:
SetUVOfs
Required Header Files
IwMaterial.h

int32 CIwMaterial::GetZDepthOfs ( ) const [inline]

Gets geometry z-depth offset for SW rasterisation modes.

Returns:
Offset to add to geometry's z-depth position.
See also:
SetZDepthOfs
Required Header Files
IwMaterial.h

int32 CIwMaterial::GetZDepthOfsHW ( ) const [inline]

Gets geometry z-depth offset for HW rasterisation modes.

Returns:
Offset to add to geometry's z-depth position.
See also:
SetZDepthOfsHW
Required Header Files
IwMaterial.h

bool CIwMaterial::HasIdentityAmbient ( ) const [inline]

Does the material have identity ambient colour?

Returns:
True only if the material has identity ambient colour (r == 0x80, g = 0x80, b = 0x80).
See also:
SetColAmbient, HasIdentityEmissive, HasIdentityDiffuse, HasIdentityCols
Required Header Files
IwMaterial.h

bool CIwMaterial::HasIdentityCols ( ) const [inline]

Does the material have identity emissive, ambient and diffuse colours?

Returns:
True only if the material has identity emissive, ambient and diffuse colours.
See also:
HasIdentityAmbient, HasIdentityDiffuse, HasIdentityEmissive
Required Header Files
IwMaterial.h

bool CIwMaterial::HasIdentityDiffuse ( ) const [inline]

Does the material have identity diffuse colour?

Returns:
True only if the material has identity diffuse colour (r == 0x80, g = 0x80, b = 0x80).
See also:
SetColDiffuse, HasIdentityAmbient, HasIdentityEmissive, HasIdentityCols
Required Header Files
IwMaterial.h

bool CIwMaterial::HasIdentityEmissive ( ) const [inline]

Does the material have identity emissive colour?

Returns:
True only if the material has identity emissive colour (r == 0x00, g = 0x00, b = 0x00).
See also:
SetColEmissive, HasIdentityAmbient, HasIdentityDiffuse, HasIdentityCols
Required Header Files
IwMaterial.h

bool CIwMaterial::IsAnim ( ) [inline]

Is there a UV animation on the material?

Returns:
true only if there is a UV animation on the material.
Required Header Files
IwMaterial.h

bool CIwMaterial::IsAnimPaused ( ) const [inline]

Checks if the animation is paused.

Returns:
true only if the animation is paused.
See also:
Pause, Restart
Required Header Files
IwMaterial.h

bool CIwMaterial::IsEquivalent ( const CIwMaterial & mat )

Compare material to input material, returning true if both are identical.

Returns:
true if the materials are equivalent
Parameters:
mat Referencer to the material to copy from.

bool CIwMaterial::IsInvisible ( )

Gets whether or not the material is invisible.

Returns:
b True only if the material is invisible (not rendered).
See also:
SetInvisible
Required Header Files
IwMaterial.h

virtual bool CIwMaterial::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

virtual void CIwMaterial::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwMaterial::ParseOpen ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: start block.

Parameters:
pParser the parser instance to use
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwMaterial::PauseAnim ( ) [inline]

Pauses the animation.

See also:
Restart, IsPaused
Required Header Files
IwMaterial.h

void CIwMaterial::Reset ( ) [inline]

Reset all settings to those of the "template" material.

See also:
IwGxGetMaterialTemplate

virtual void CIwMaterial::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwMaterial::RestartAnim ( ) [inline]

Restarts the animation.

See also:
Pause, IsPaused
Required Header Files
IwMaterial.h

virtual void CIwMaterial::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwMaterial::SetAlphaMode ( AlphaMode mode ) [inline]

Sets alpha (transparency) mode. The alpha mode affects how pixels written to the colour buffer are blended with values already in the colour buffer.

Note:
When a material is constructed, its alpha mode is copied from the template material.

It is illegal to modify this value if the material is already in use. A material is in use if some geometry has been drawn using that material within the current frame.

Parameters:
mode Enumerated alpha mode.
Note:
It is illegal to call this method if the material has already been used this frame to render some geometry.
See also:
GetAlphaMode

void CIwMaterial::SetAlphaTestMode ( AlphaTestMode mode ) [inline]

Sets alpha (transparency) test mode. The alpha test determines if the pixel is written or not in the colour buffer.

Note:
When a material is constructed, its alpha test mode is copied from the template material.

It is illegal to modify this value if the material is already in use. A material is in use if some geometry has been drawn using that material within the current frame.

Parameters:
mode Enumerated alpha testing mode.
Note:
It is illegal to call this method if the material has already been used this frame to render some geometry.
See also:
GetAlphaTestMode

void CIwMaterial::SetAlphaTestRefVal ( uint8 alphaRefVal ) [inline]

Sets alpha (transparency) test reference value. The alpha test reference value is compared to the pixel alpha value.

Note:
When a material is constructed, its alpha test ref value is copied from the template material.

It is illegal to modify this value if the material is already in use. A material is in use if some geometry has been drawn using that material within the current frame.

Parameters:
mode uint8.
Note:
It is illegal to call this method if the material has already been used this frame to render some geometry.
See also:
GetAlphaTestRefVal

void CIwMaterial::SetAnimCelH ( uint8 n ) [inline]

Sets the height of each cel, in texels.

Parameters:
n Height in texels.
See also:
SetAnimCelW, GetAnimCelH, SetAnimCelNum, SetAnimCelNumU, SetAnimCelPeriod
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimCelID ( uint8 celID )

Sets UV animation cel ID.

Parameters:
celID ID of cel within UV animation.
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimCelNum ( uint8 n ) [inline]

Sets the number of cels in the animation.

Parameters:
n Number of cels.
See also:
GetAnimCelNum, SetAnimCelNumU, SetAnimCelW, SetAnimCelH, SetAnimCelPeriod
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimCelNumU ( uint8 n ) [inline]

Sets the number of cels across each row of the texture.

Parameters:
n Number of cels.
See also:
SetAnimCelNum, SetAnimCelNumU, SetAnimCelW, SetAnimCelH, SetAnimCelPeriod
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimCelPeriod ( uint8 n ) [inline]

Sets the animation period. This is the number of frame updates before changing to the next cel.

Parameters:
n Animation period, in frames.
See also:
GetAnimCelPeriod, PauseAnim, RestartAnim, IsAnimPaused
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimCelW ( uint8 n ) [inline]

Sets the width of each cel, in texels.

Parameters:
n Width in texels.
See also:
SetAnimCelH, GetAnimCelW, SetAnimCelNum, SetAnimCelNumU, SetAnimCelPeriod
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimOfsU ( uint8 n ) [inline]

Equivalent to SetAnimCelW().

See also:
SetAnimCelW
Required Header Files
IwMaterial.h

void CIwMaterial::SetAnimOfsV ( uint8 n ) [inline]

Equivalent to SetAnimCelH().

See also:
SetAnimCelH
Required Header Files
IwMaterial.h

void CIwMaterial::SetBlendMode ( BlendMode mode ) [inline]

Sets blend mode. The blend mode affects how texels from stages 0 and 1 are blended together before being written to the colour buffer.

Note:
When a material is constructed, its blend mode is copied from the template material.

Is is illegal to modify this value if the material is already in use. A material is in use if some geometry has been drawn using that material this frame.

It is illegal to call this method if the material has already been used this frame to render some geometry.

Parameters:
mode Enumerated blend mode.
See also:
GetBlendMode

void CIwMaterial::SetClamping ( bool b )

Sets whether or not all the material's textures should use clamped texture coordinates.

Parameters:
b If true all the material's textures will be set to use clamped texture coordinates.
See also:
GetClamping
Required Header Files
IwMaterial.h

void CIwMaterial::SetColAmbient ( const CIwColour & col ) [inline]

Sets the current ambient colour.

Parameters:
col Colour structure.
Note:
When a material is constructed, its ambient colour is copied from the template material.
See also:
GetColAmbient, SetColEmissive, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColAmbient | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a |
 | ) |  |  | [inline]

Sets the current ambient colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
Note:
When a material is constructed, its ambient colour is copied from the template material.
See also:
GetColAmbient, SetColEmissive, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColAmbient ( uint32 col ) [inline]

Sets the current ambient colour.

Parameters:
col Colour, as 32-bit ABGR value.
Note:
When a material is constructed, its ambient colour is copied from the template material.
See also:
GetColAmbient, SetColEmissive, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColDiffuse ( const CIwColour & col ) [inline]

Sets the current diffuse colour.

Parameters:
col Colour structure.
Note:
When a material is constructed, its diffuse colour is copied from the template material.
See also:
GetColDiffuse, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetColDiffuse | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a |
 | ) |  |  | [inline]

Sets the current diffuse colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
Note:
When a material is constructed, its diffuse colour is copied from the template material.
See also:
GetColDiffuse, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetColDiffuse ( uint32 col ) [inline]

Sets the current diffuse colour.

Parameters:
col Colour, as 32-bit ABGR value.
Note:
When a material is constructed, its diffuse colour is copied from the template material.
See also:
GetColDiffuse, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetColEmissive ( const CIwColour & col ) [inline]

Sets the current emissive colour.

Parameters:
col Colour structure.
Note:
When a material is constructed, its emissive colour is copied from the template material.
See also:
GetColEmissive, SetColAmbient, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColEmissive | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b,
 |  | uint8 | _a |
 | ) |  |  | [inline]

Sets the emissive colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
_a | 8-bit alpha component.
Note:
When a material is constructed, its emissive colour is copied from the template material.
See also:
GetColEmissive, SetColAmbient, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColEmissive ( uint32 col ) [inline]

Sets the emissive colour.

Parameters:
col Colour, as 32-bit ABGR value.
Note:
When a material is constructed, its emissive colour is copied from the template material.
See also:
GetColEmissive, SetColAmbient, SetColDiffuse
Required Header Files
IwMaterial.h

void CIwMaterial::SetColSpecular ( const CIwColour & col ) [inline]

Sets the current specular colour.

Parameters:
col Colour structure.
Note:
When a material is constructed, its specular colour is copied from the template material.
See also:
GetColSpecular, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetColSpecular | ( | uint8 | _r,
 |  | uint8 | _g,
 |  | uint8 | _b |
 | ) |  |  | [inline]

Sets the current specular colour.

Parameters:
_r | 8-bit red component.
_g | 8-bit green component.
_b | 8-bit blue component.
Note:
When a material is constructed, its specular colour is copied from the template material.
See also:
GetColSpecular, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetColSpecular ( uint32 col ) [inline]

Sets the current specular colour (including the specular power)

Parameters:
col Colour, as 32-bit ABGR value.
Note:
When a material is constructed, its specular colour is copied from the template material.
See also:
GetColDiffuse, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetCullMode ( CullMode m )

Sets the material cull mode; this can be either CULL_FRONT, CULL_BACK or CULL_NONE (double-sided).

Note:
When a material is constructed, its cull mode is copied from the template material.
Parameters:
m The cull mode to set.
See also:
GetCullMode
Required Header Files
IwMaterial.h

void CIwMaterial::SetEffectPreset ( EffectPreset effectpreset ) [inline]

Sets effect preset. Prepares material for rendering a preset effect

EFFECT_DEFAULT: Combine 2nd texture using BlendMode, use 2nd UV set if available, otherwise 1st UV set This effect can be used for overlay, shadowmap, lightmap, detail textures etc. Just add a 2nd texture to the material

EFFECT_NORMAL_MAPPING - Use 2nd texture as a normal map, then use BlendMode to combine 1st texture Hardware transform and rasterisation is required for this effect. A bumpmapping compatable vertex shader must be set to get meaningful results from this effect. Tangent and BiTangent vectors must be set in the model (These are built automatically when using exporter and resource pipeline)

EFFECT_REFLECTION_MAPPING: Combine 2nd texture as a spherical reflection map, Automatically computes reflection UVs

Parameters:
effectpreset Enumerated preset effect.
See also:
GetEffectPreset
Note:
When a material is constructed, its effect preset is copied from the template material.

It is illegal to call this method if the material has already been used this frame to render some geometry.

Required Header Files
IwMaterial.h

void CIwMaterial::SetFiltering ( bool b )

Sets whether or not all the material's textures should use bi-linear filtering.

Note:
When a material is constructed, its filtering mode is copied from the template material.
Parameters:
b True only if all the material's textures should use bi-linear filtering.
See also:
GetFiltering
Required Header Files
IwMaterial.h

void CIwMaterial::SetInvisible ( bool b )

Sets whether or not the material is invisible. Defaults to false.

Parameters:
b True only if the material should be invisible (not rendered).
See also:
IsInvisible
Required Header Files
IwMaterial.h

void CIwMaterial::SetMergeGeom ( bool set ) [inline]

Sets the merged geometry status. If Rasterisation=HW, Transform=SW, Lighting=SW, and sorting mode is IW_GX_SORT_BY_MATERIAL, this setting will attempt to merge all instances of IwGxDrawPrims using this material, so that a single combined piece of geometry is sent to the HW driver. This effectively takes some load off the HW driver and passes it to the CPU. Note that the merging process may result in a considerable amount of memory copying; however, if the scene is GPU-bound then this may still be the preferred option.

See also:
GetMergeGeom
Required Header Files
IwMaterial.h

void CIwMaterial::SetModulateMode ( ModulateMode m ) [inline]

Sets the material modulation mode; this can be either MODULATE_RGB, MODULATE_R or MODULATE_NONE.

Parameters:
m The modulation mode to set.
Note:
When a material is constructed, its modulation mode is copied from the template material.

It is illegal to call this method if the material has already been used this frame to render some geometry.

See also:
GetModulateMode
Required Header Files
IwMaterial.h

virtual void CIwMaterial::SetName ( const char * pName ) [virtual]

Set name (hashed value)

Parameters:
pName the hashed name of the managed object
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwMaterial::SetShadeMode ( ShadeMode m ) [inline]

Sets the material shade mode; this can be either SHADE_FLAT or SHADE_GOURAUD.

Note:
When a material is constructed, its shade mode is copied from the template material.

It is illegal to call this method if the material has already been used this frame to render some geometry.

Parameters:
m The shade mode to set.
See also:
GetShadeMode
Required Header Files
IwMaterial.h

void CIwMaterial::SetSpecularPower ( uint8 power ) [inline]

Sets the current specular power.

Parameters:
power New integer specular power.
Note:
When a material is constructed, its specular colour/power is copied from the template material.
See also:
GetColSpecular, SetColAmbient, SetColEmissive
Required Header Files
IwMaterial.h

void CIwMaterial::SetTexture | ( | CIwTexture * | pTex,
 |  | uint32 | t = 0 |
 | ) |  |  | [inline]

Sets the texture to use (at specified stage).

Note:
The Airplay software renderer supports only stage 0 - the diffuse map. Hardware-accelerated sub-systems may support multiple texture stages.
Parameters:
pTex | The texture to use at the specified stage.
t | The stage to set (0 if not specified).
See also:
GetTexture
Note:
It is illegal to call this method if the material has already been used this frame to render some geometry.
Required Header Files
IwMaterial.h

void CIwMaterial::SetUserFlags ( uint16 flags ) [inline]

Sets user flags.

Note:
The material makes a special 16-bit flags field available to the user. The user can read and write these flags at will, and they are untouched by the system. at will.
Parameters:
flags User flags to set.
Required Header Files
IwMaterial.h

void CIwMaterial::SetUVOfs ( const CIwSVec2 * pOfs ) [inline]

Sets the current UV offset for this material (will be added to UV streams).

Parameters:
pOfs Pointer to a UV offset to set.
Note:
When a material is constructed, its UV offset is copied from the template material.
See also:
GetUVOfs
Required Header Files
IwMaterial.h

void CIwMaterial::SetZDepthOfs ( int32 val ) [inline]

Sets geometry z-depth offset for SW rasterisation modes.

Parameters:
otzOfs Offset to add to geometry's z-depth position.
Note:
When a material is constructed, its z-depth offset is copied from the template material.
See also:
GetZDepthOfs
Required Header Files
IwMaterial.h

void CIwMaterial::SetZDepthOfsHW ( int32 val ) [inline]

Sets geometry z-depth offset for HW rasterisation modes.

Parameters:
otzOfs Offset to add to geometry's z-depth position.
Note:
When a material is constructed, its z-depth offset is copied from the template material.
See also:
GetZDepthOfsHW
Required Header Files
IwMaterial.h

Friends And Related Function Documentation

CIwMaterial* IW_GX_ALLOC_MATERIAL ( ) [friend]

Allocates a material from the IwGx global cache.

Returns:
The allocated material.
Required Header Files
IwMaterial.h

void IwGxDrawPrims | ( | IwGxPrimType | primType,
 |  | uint16 * | pInds,
 |  | uint32 | numInds |
 | ) |  |  | [friend]

Draws geometry by stiching together geometry streams, in various ways, from a supplied index stream.

Parameters:
primType | Enumerated type specifying whether to create triangles, quads, lines, etc.
pInds | Pointer to index stream.
numInds | Number of indices in stream.
See also:
IwGxFlush, IwGxSwapBuffers
Required Header Files
IwGx.h

void IwGxFlush ( ) [friend]

Flushes any cached geometry to the surface.

See also:
IwGxDrawPrims, IwGxSwapBuffers
Required Header Files
IwGx.h

void IwGxSetRasterisationHW ( ) [friend]

Sets the rasterisation pipeline to HW.

The documentation for this class was generated from the following file:
  • IwMaterial.h


Airplay API Reference: CIwMenu

Airplay API Reference > Data Structures > CIwMenu >

CIwMenu Class Reference
[IwMenu]

#include <IwMenu.h>

Detailed Description

Base class for all menus. The user creates an empty menu, then create objects derived from CIwMenuItem and adds them to the menu.
The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItem

Airplay API Reference > Data Structures > CIwMenuItem >

CIwMenuItem Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItem:

[legend]

Public Types

enum | ColourID

Public Member Functions

virtual void | Back ()
virtual void | Enter ()
virtual void | Exit ()
CIwMenu * | GetMenu () const
virtual void | Minus ()
virtual void | Plus ()
virtual void | Render (int32 x, int32 y)
virtual void | Run ()
virtual void | Select ()
void | SetSelectable (bool s)
virtual void | Update (bool active)

Detailed Description

Base class for all menu items. Derived menu items implement the virtual functions to describe the complete behaviour of the item.

Member Enumeration Documentation

anonymous enum

Enumerator:
UNSELECTABLE_F | Item is unselectable (cannot be selected).
NO_SCROLL_F | Item is always visible on screen (does not scroll).
PARAGRAPH_END_F | Leave an extra gap after this item.

enum CIwMenuItem::ColourID

Standard colours available for menu items.

Member Function Documentation

virtual void CIwMenuItem::Back ( ) [virtual]

Called when the user "navigates out of" the item, by pressing the left arrow.

See also:
Select, Run

virtual void CIwMenuItem::Enter ( ) [inline, virtual]

Called when the user moves from another item in the same menu onto this item, by pressing the up or down arrow.

See also:
Exit

virtual void CIwMenuItem::Exit ( ) [inline, virtual]

Called when the user moves from this item to another item in the same menu, by pressing the up or down arrow.

See also:
Enter

CIwMenu* CIwMenuItem::GetMenu ( ) const [inline]

Get a pointer to the owner menu.

Returns:
Pointer to the owner menu, or NULL if the item does not have an owner menu.

virtual void CIwMenuItem::Minus ( ) [inline, virtual]

Called when the user decreases the value of this item, by pressing "-" (on the numeric keypad).

See also:
Plus

virtual void CIwMenuItem::Plus ( ) [inline, virtual]

Called when the user increases the value of this item, by pressing "+" (on the numeric keypad).

See also:
Minus

virtual void CIwMenuItem::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented in CIwMenuItemString, CIwMenuItemEditFlags, CIwMenuItemEditEnum, CIwMenuItemEditFixed, and CIwMenuItemEditAngle.

virtual void CIwMenuItem::Run ( ) [inline, virtual]

Called when the user "executes" the item, by pressing return.

See also:
Select, Back

virtual void CIwMenuItem::Select ( ) [inline, virtual]

Called when the user "navigates into" the item, by pressing the right arrow.

See also:
Back, Run

Reimplemented in CIwMenuItemManagedList.

void CIwMenuItem::SetSelectable ( bool s ) [inline]

Set the selectability of the item. By default, all items are selectable. However, after adding items to a menu, the user can decide to make some unselectable.

Parameters:
s False only if the item is to be unselectable.

virtual void CIwMenuItem::Update ( bool active ) [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Update() is called.

Parameters:
active True only if this item is the current (selected) item in the menu.

Field Documentation

ColourID CIwMenuItem::m_ColourID

Colour ID.

int32 CIwMenuItem::m_H

Item height in pixels.

const char* CIwMenuItem::m_Name

Instance name.

CIwMenuString CIwMenuItem::m_Text

Text string to display.

int32 CIwMenuItem::m_W

Item width in pixels.

int32 CIwMenuItem::m_X

Screen x coord of top-left of item.

int32 CIwMenuItem::m_Y

Screen y coord of top-left of item.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayBool

Airplay API Reference > Data Structures > CIwMenuItemDisplayBool >

CIwMenuItemDisplayBool Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayBool:

[legend]

Public Member Functions

CIwMenuItemDisplayBool (const char *text, bool Value)

Detailed Description

Displays a bool value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayBool::CIwMenuItemDisplayBool | ( | const char * | text,
 |  | bool | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayFloat

Airplay API Reference > Data Structures > CIwMenuItemDisplayFloat >

CIwMenuItemDisplayFloat Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayFloat:

[legend]

Public Member Functions

CIwMenuItemDisplayFloat (const char *text, float Value)

Detailed Description

Displays a float value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayFloat::CIwMenuItemDisplayFloat | ( | const char * | text,
 |  | float | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayInt16

Airplay API Reference > Data Structures > CIwMenuItemDisplayInt16 >

CIwMenuItemDisplayInt16 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayInt16:

[legend]

Public Member Functions

CIwMenuItemDisplayInt16 (const char *text, int16 Value)

Detailed Description

Displays a int16 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayInt16::CIwMenuItemDisplayInt16 | ( | const char * | text,
 |  | int16 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayInt32

Airplay API Reference > Data Structures > CIwMenuItemDisplayInt32 >

CIwMenuItemDisplayInt32 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayInt32:

[legend]

Public Member Functions

CIwMenuItemDisplayInt32 (const char *text, int32 Value)

Detailed Description

Displays a int32 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayInt32::CIwMenuItemDisplayInt32 | ( | const char * | text,
 |  | int32 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayInt8

Airplay API Reference > Data Structures > CIwMenuItemDisplayInt8 >

CIwMenuItemDisplayInt8 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayInt8:

[legend]

Public Member Functions

CIwMenuItemDisplayInt8 (const char *text, int8 Value)

Detailed Description

Displays a int8 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayInt8::CIwMenuItemDisplayInt8 | ( | const char * | text,
 |  | int8 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayUInt16

Airplay API Reference > Data Structures > CIwMenuItemDisplayUInt16 >

CIwMenuItemDisplayUInt16 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayUInt16:

[legend]

Public Member Functions

CIwMenuItemDisplayUInt16 (const char *text, uint16 Value)

Detailed Description

Displays a uint16 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayUInt16::CIwMenuItemDisplayUInt16 | ( | const char * | text,
 |  | uint16 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayUInt32

Airplay API Reference > Data Structures > CIwMenuItemDisplayUInt32 >

CIwMenuItemDisplayUInt32 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayUInt32:

[legend]

Public Member Functions

CIwMenuItemDisplayUInt32 (const char *text, uint32 Value)

Detailed Description

Displays a uint32 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayUInt32::CIwMenuItemDisplayUInt32 | ( | const char * | text,
 |  | uint32 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemDisplayUInt8

Airplay API Reference > Data Structures > CIwMenuItemDisplayUInt8 >

CIwMenuItemDisplayUInt8 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemDisplayUInt8:

[legend]

Public Member Functions

CIwMenuItemDisplayUInt8 (const char *text, uint8 Value)

Detailed Description

Displays a uint8 value. Does NOT permit editing of the value.

Constructor & Destructor Documentation

CIwMenuItemDisplayUInt8::CIwMenuItemDisplayUInt8 | ( | const char * | text,
 |  | uint8 | Value |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
Value | The value to display.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditAngle

Airplay API Reference > Data Structures > CIwMenuItemEditAngle >

CIwMenuItemEditAngle Class Reference
[IwGeomMenu]

#include <IwGeomMenu.h>

Inheritance diagram for CIwMenuItemEditAngle:

[legend]

Public Member Functions

CIwMenuItemEditAngle (const char *text, iwfixed *pValue, float delta=(float) IW_ANGLE_FROM_DEGREES(1), float min=(float) INT32_MIN, float max=(float) INT32_MAX, float def=0.0f)
void Render (int32 x, int32 y)

Detailed Description

Displays a iwangle value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditAngle::CIwMenuItemEditAngle | ( | const char * | text,
 |  | iwfixed * | pValue,
 |  | float | delta = (float)IW_ANGLE_FROM_DEGREES(1),
 |  | float | min = (float)INT32_MIN,
 |  | float | max = (float)INT32_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is IW_ANGLE_FROM_DEGREES(1).
min | Minimum value to allow. Default is INT32_MIN.
max | Maximum value to allow. Default is INT32_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

Member Function Documentation

void CIwMenuItemEditAngle::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwGeomMenu.h


Airplay API Reference: CIwMenuItemEditBool

Airplay API Reference > Data Structures > CIwMenuItemEditBool >

CIwMenuItemEditBool Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditBool:

[legend]

Public Member Functions

CIwMenuItemEditBool (const char *text, bool *pValue, float delta=1.0f, float min=(float) 0x0, float max=(float) 0x1, float def=0.0f)

Detailed Description

Displays a bool value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditBool::CIwMenuItemEditBool | ( | const char * | text,
 |  | bool * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)0x0,
 |  | float | max = (float)0x1,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is 0.
max | Maximum value to allow. Default is 1.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditEnum

Airplay API Reference > Data Structures > CIwMenuItemEditEnum >

CIwMenuItemEditEnum Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditEnum:

[legend]

Public Member Functions

CIwMenuItemEditEnum (const char *text, uint32 *pValue, const char **ppNames=NULL, bool edit=true, uint32 min=0, uint32 max=0)
void Render (int32 x, int32 y)

Detailed Description

Displays an enumerated 32-bit value as a string.

Constructor & Destructor Documentation

CIwMenuItemEditEnum::CIwMenuItemEditEnum | ( | const char * | text,
 |  | uint32 * | pValue,
 |  | const char ** | ppNames = NULL,
 |  | bool | edit = true,
 |  | uint32 | min = 0,
 |  | uint32 | max = 0
 | ) |  |

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the 32-bit enum value.
ppNames | Pointer to a null-terminated array of strings corresponding to the enum values.
edit | True only if the user is permitted to edit the enum value.
min | If editable, this is the minimum permissable value. Default is 0.
max | If editable, this is the maximum permissable value. Default is 0.

Member Function Documentation

void CIwMenuItemEditEnum::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditFixed

Airplay API Reference > Data Structures > CIwMenuItemEditFixed >

CIwMenuItemEditFixed Class Reference
[IwGeomMenu]

#include <IwGeomMenu.h>

Inheritance diagram for CIwMenuItemEditFixed:

[legend]

Public Member Functions

CIwMenuItemEditFixed (const char *text, iwfixed *pValue, float delta=(float) IW_FIXED(1.0f/IW_FIXED_DISPLAY_DECIMAL_MULTIPLIER), float min=(float) INT32_MIN, float max=(float) INT32_MAX, float def=0.0f)
void Render (int32 x, int32 y)

Detailed Description

Displays a iwfixed value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditFixed::CIwMenuItemEditFixed | ( | const char * | text,
 |  | iwfixed * | pValue,
 |  | float | delta = (float)IW_FIXED(1.0f / IW_FIXED_DISPLAY_DECIMAL_MULTIPLIER),
 |  | float | min = (float)INT32_MIN,
 |  | float | max = (float)INT32_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is IW_FIXED(1 / 1000).
min | Minimum value to allow. Default is INT32_MIN.
max | Maximum value to allow. Default is INT32_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

Member Function Documentation

void CIwMenuItemEditFixed::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwGeomMenu.h


Airplay API Reference: CIwMenuItemEditFlags

Airplay API Reference > Data Structures > CIwMenuItemEditFlags >

CIwMenuItemEditFlags Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditFlags:

[legend]

Public Member Functions

CIwMenuItemEditFlags (const char *text, uint32 *pValue, uint32 mask)
void Render (int32 x, int32 y)

Detailed Description

Displays the status of a bit within a 32-bit field.

Constructor & Destructor Documentation

CIwMenuItemEditFlags::CIwMenuItemEditFlags | ( | const char * | text,
 |  | uint32 * | pValue,
 |  | uint32 | mask |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the 32-bit flags field.
mask | Flag value to toggle with. Should be (1 << n), where (31 <= n <= 0).

Member Function Documentation

void CIwMenuItemEditFlags::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditFloat

Airplay API Reference > Data Structures > CIwMenuItemEditFloat >

CIwMenuItemEditFloat Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditFloat:

[legend]

Public Member Functions

CIwMenuItemEditFloat (const char *text, float *pValue, float delta=0.01f, float min=(float) INT32_MIN, float max=(float) INT32_MAX, float def=0.0f)

Detailed Description

Displays a float value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditFloat::CIwMenuItemEditFloat | ( | const char * | text,
 |  | float * | pValue,
 |  | float | delta = 0.01f,
 |  | float | min = (float)INT32_MIN,
 |  | float | max = (float)INT32_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is INT32_MIN.
max | Maximum value to allow. Default is INT32_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditInt16

Airplay API Reference > Data Structures > CIwMenuItemEditInt16 >

CIwMenuItemEditInt16 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditInt16:

[legend]

Public Member Functions

CIwMenuItemEditInt16 (const char *text, int16 *pValue, float delta=1.0f, float min=(float) INT16_MIN, float max=(float) INT16_MAX, float def=0.0f)

Detailed Description

Displays a int16 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditInt16::CIwMenuItemEditInt16 | ( | const char * | text,
 |  | int16 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)INT16_MIN,
 |  | float | max = (float)INT16_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is INT16_MIN.
max | Maximum value to allow. Default is INT16_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditInt32

Airplay API Reference > Data Structures > CIwMenuItemEditInt32 >

CIwMenuItemEditInt32 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditInt32:

[legend]

Public Member Functions

CIwMenuItemEditInt32 (const char *text, int32 *pValue, float delta=1.0f, float min=(float) INT32_MIN, float max=(float) INT32_MAX, float def=0.0f)

Detailed Description

Displays a int32 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditInt32::CIwMenuItemEditInt32 | ( | const char * | text,
 |  | int32 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)INT32_MIN,
 |  | float | max = (float)INT32_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is INT32_MIN.
max | Maximum value to allow. Default is INT32_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditInt8

Airplay API Reference > Data Structures > CIwMenuItemEditInt8 >

CIwMenuItemEditInt8 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditInt8:

[legend]

Public Member Functions

CIwMenuItemEditInt8 (const char *text, int8 *pValue, float delta=1.0f, float min=(float) INT8_MIN, float max=(float) INT8_MAX, float def=0.0f)

Detailed Description

Displays a int8 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditInt8::CIwMenuItemEditInt8 | ( | const char * | text,
 |  | int8 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)INT8_MIN,
 |  | float | max = (float)INT8_MAX,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is INT8_MIN.
max | Maximum value to allow. Default is INT8_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditUInt16

Airplay API Reference > Data Structures > CIwMenuItemEditUInt16 >

CIwMenuItemEditUInt16 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditUInt16:

[legend]

Public Member Functions

CIwMenuItemEditUInt16 (const char *text, uint16 *pValue, float delta=1.0f, float min=(float) 0x0, float max=(float) 0xffff, float def=0.0f)

Detailed Description

Displays a uint16 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditUInt16::CIwMenuItemEditUInt16 | ( | const char * | text,
 |  | uint16 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)0x0,
 |  | float | max = (float)0xffff,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is UINT16_MIN.
max | Maximum value to allow. Default is UINT16_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditUInt32

Airplay API Reference > Data Structures > CIwMenuItemEditUInt32 >

CIwMenuItemEditUInt32 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditUInt32:

[legend]

Public Member Functions

CIwMenuItemEditUInt32 (const char *text, uint32 *pValue, float delta=1.0f, float min=(float) 0x0000, float max=(float) 0xffff, float def=0.0f)

Detailed Description

Displays a uint32 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditUInt32::CIwMenuItemEditUInt32 | ( | const char * | text,
 |  | uint32 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)0x0000,
 |  | float | max = (float)0xffff,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is UINT32_MIN.
max | Maximum value to allow. Default is UINT32_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemEditUInt8

Airplay API Reference > Data Structures > CIwMenuItemEditUInt8 >

CIwMenuItemEditUInt8 Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemEditUInt8:

[legend]

Public Member Functions

CIwMenuItemEditUInt8 (const char *text, uint8 *pValue, float delta=1.0f, float min=(float) 0x0, float max=(float) 0xff, float def=0.0f)

Detailed Description

Displays a uint8 value, and permits editing of the value.

Constructor & Destructor Documentation

CIwMenuItemEditUInt8::CIwMenuItemEditUInt8 | ( | const char * | text,
 |  | uint8 * | pValue,
 |  | float | delta = 1.0f,
 |  | float | min = (float)0x0,
 |  | float | max = (float)0xff,
 |  | float | def = 0.0f |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
pValue | Pointer to the value to display/edit.
delta | Value to increment/decrement by. Default is 1.
min | Minimum value to allow. Default is UINT8_MIN.
max | Maximum value to allow. Default is UINT8_MAX.
def | Default value to set. If delta is passed in as zero, this default is set if the user tries to edit the value.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemManagedList

Airplay API Reference > Data Structures > CIwMenuItemManagedList >

CIwMenuItemManagedList Class Reference
[IwManagedList]

Debug menu: all items in a managed list.

#include <IwManagedList.h>

Inheritance diagram for CIwMenuItemManagedList:

[legend]

Public Member Functions

void Select ()

Member Function Documentation

void CIwMenuItemManagedList::Select ( ) [virtual]

Called when the user "navigates into" the item, by pressing the right arrow.

See also:
Back, Run

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwManagedList.h


Airplay API Reference: CIwMenuItemString

Airplay API Reference > Data Structures > CIwMenuItemString >

CIwMenuItemString Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemString:

[legend]

Public Member Functions

CIwMenuItemString (const char *text, const char *string, uint32 flags=0)
void Render (int32 x, int32 y)

Detailed Description

Displays a simple string.

Constructor & Destructor Documentation

CIwMenuItemString::CIwMenuItemString | ( | const char * | text,
 |  | const char * | string,
 |  | uint32 | flags = 0 |
 | ) |  |  | [inline]

Constructor.

Parameters:
text | Item text (for left-hand column).
string | String to display (in right-hand column).
flags | Standard CIwMenuItem flags.

Member Function Documentation

void CIwMenuItemString::Render | ( | int32 | x,
 |  | int32 | y |
 | ) |  |  | [virtual]

Called every frame for every menu item in the current (displayed) menu, when IwGetMenuManager()->Render() is called.

Parameters:
x | Screen x coord of the top-left of the item.
y | Screen y coord of the top-left of the item.

Reimplemented from CIwMenuItem.

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuItemTitle

Airplay API Reference > Data Structures > CIwMenuItemTitle >

CIwMenuItemTitle Class Reference
[IwMenu]

#include <IwMenu.h>

Inheritance diagram for CIwMenuItemTitle:

[legend]

Public Member Functions

CIwMenuItemTitle (const char *text)

Detailed Description

Displays a "title" item. This is unselectable, and appears in the TITLE colour.

Constructor & Destructor Documentation

CIwMenuItemTitle::CIwMenuItemTitle ( const char * text ) [inline]

Constructor.

Parameters:
text Item text (for left-hand column).

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwMenuManager

Airplay API Reference > Data Structures > CIwMenuManager >

CIwMenuManager Class Reference
[IwMenu]

#include <IwMenu.h>

Public Types

typedef CIwMenu *(* | MainFn )()
typedef void(* | TextCallback )(const char *line, int32 x, int32 y, CIwMenuItem::ColourID colID)

Public Member Functions

void | AddMenu (CIwMenu *menu)
void | AddMenuOrDestroy (CIwMenu *pMenu)
void | DestroyMenu ()
void | DestroyMenus ()
bool | HasFocus ()
void | RebuildMenu (int32 forceID=-1)
virtual void | Render ()
void | SelectMenu (int32 forceID=-1)
void | SetFocus (bool focus)
void | SetFocusKey (int32 k)
void | SetMainMenuFn (MainFn cb)
void | SetMenuCharWH (uint32 w, uint32 h)
void | SetMenuDefaultW (uint32 w)
void | SetMenuDefaultXY (uint32 x, uint32 y)
void | SetTextCallback (TextCallback cb)
virtual void | Update ()

Detailed Description

Singleton for handling all debug menu update and rendering.

Member Typedef Documentation

typedef CIwMenu*(* CIwMenuManager::MainFn)()

Typedef for callback to create main menu.

typedef void(* CIwMenuManager::TextCallback)(const char *line, int32 x, int32 y, CIwMenuItem::ColourID colID)

Typedef for text display callback.

Member Function Documentation

void CIwMenuManager::AddMenu ( CIwMenu * menu )

Add a menu to the manager.

Parameters:
menu Pointer to the menu to add.

void CIwMenuManager::AddMenuOrDestroy ( CIwMenu * pMenu )

Add a menu to the manager, unless it contains no items, in which case destroy it.

Parameters:
menu Pointer to the menu to add or destroy.

void CIwMenuManager::DestroyMenu ( ) [inline]

Destroy last menu in the manager's list. The menu will be destroyed at the next call to Update().

void CIwMenuManager::DestroyMenus ( )

Destroy all menus.

bool CIwMenuManager::HasFocus ( ) [inline]

Does the menu manager have input focus?

Returns:
True only if the menu manager has input focus.

void CIwMenuManager::RebuildMenu ( int32 forceID = -1 ) [inline]

Rebuild current menu at next call to Update() (this happens AFTER DESTROY_MENU_F is picked up)

Parameters:
forceID Index to set cursor to, or -1 to leave unchanged

virtual void CIwMenuManager::Render ( ) [virtual]

Render all menus. This calls CIwMenu::Render() on any current (visible) menu, which in turn will call CIwMenuItem::Render() on any items it contains.

Note:
virtual only to help linker eliminate this class

void CIwMenuManager::SelectMenu ( int32 forceID = -1 ) [inline]

Ensure setting of INPUT_RIGHT_F at next call to Update()

Parameters:
forceID Index to set cursor to, or -1 to leave unchanged

void CIwMenuManager::SetFocus ( bool focus )

Change the menu manager input focus state.

Parameters:
focus True only if the menu manager should be set to have input focus.

void CIwMenuManager::SetFocusKey ( int32 k ) [inline]

Set the key to use to toggle the input focus to and from the menus.

Parameters:
k The s3eKey ID to use.

void CIwMenuManager::SetMainMenuFn ( MainFn cb ) [inline]

Set the user callback which will create the main (initial) menu.

Parameters:
cb The user callback which will create the main (initial) menu.

void CIwMenuManager::SetMenuCharWH | ( | uint32 | w,
 |  | uint32 | h |
 | ) |  |  | [inline]

Set the width and height of the fixed-width font being used.

Parameters:
w | Width of all characters in pixels.
h | Height of all characters in pixels.

void CIwMenuManager::SetMenuDefaultW ( uint32 w ) [inline]

Set the width of the left-hand text column, in characters.

Parameters:
w Width in characters.

void CIwMenuManager::SetMenuDefaultXY | ( | uint32 | x,
 |  | uint32 | y |
 | ) |  |  | [inline]

Set the default top-left coordinate for all menu.

Parameters:
x | Default x coord.
y | Default y coord.

void CIwMenuManager::SetTextCallback ( TextCallback cb ) [inline]

Register a user callback to actually display the text. This must be done before rendering any menus.

Parameters:
cb The user callback to display text.

virtual void CIwMenuManager::Update ( ) [virtual]

Update all menus. This checks for navigation between menus. It also calls CIwMenu::Update() on any current (visible) menu, which in turn will call CIwMenuItem::Update() on any items it contains.

Note:
virtual only to help linker eliminate this class

The documentation for this class was generated from the following file:
  • IwMenu.h


Airplay API Reference: CIwModel

Airplay API Reference > Data Structures > CIwModel >

CIwModel Class Reference
[Model Object]

#include <IwModel.h>

Inheritance diagram for CIwModel:

[legend]

Public Member Functions

Blocks
void | AddBlock (CIwModelBlock *pBlock, bool setOwned=true)
CIwModelBlock * | GetBlockNamed (const char *pName) const
Extensions
void | AddExt (CIwModelExt *pExt)
CIwModelExt * | GetExtHashed (uint32 hash) const
CIwModelExt * | GetExtNamed (const char *pName) const
void | RemoveExt (CIwModelExt *pExt)
Constructor / Destructor
CIwModel ()
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | Resolve ()
virtual void | Serialise ()
virtual | ~CIwModel ()
Flags
void | ClearFlags (uint32 flags)
uint32 | GetFlags () const
void | SetFlags (uint32 flags)
void | WriteFlags (uint32 flags)
Miscellaneous
CIwModel * CloneWithNewMaterials ()
Geometry Queries
void * | GetBiTangents () const
const CIwSphere * | GetBSphere () const
void * | GetCols () const
void * | GetNorms () const
uint16 | GetNumChunks () const
uint16 | GetNumCols () const
uint16 | GetNumNorms () const
uint16 | GetNumUVs () const
uint16 | GetNumVerts () const
uint16 | GetNumVertsUnique () const
void * | GetTangents () const
void * | GetUVs (uint32 id=0) const
void * | GetVerts () const
int32 | GetZDepthFixed ()
int32 | GetZDepthOfs ()
const bool | IsCloned () const
void | SetZDepthFixed (int32 val)
void | SetZDepthOfs (int32 ofs)
const bool | VertCopiesAreIDs () const
Rendering
virtual void | Render (bool checkBSphere=true, uint32 renderFlags=0) const

Detailed Description

Model object.

Constructor & Destructor Documentation

CIwModel::CIwModel ( )

Constructor.

virtual CIwModel::~CIwModel ( ) [virtual]

Destructor.

Member Function Documentation

void CIwModel::AddBlock | ( | CIwModelBlock * | pBlock,
 |  | bool | setOwned = true
 | ) |  |

Adds model block.

Parameters:
pBlock | Pointer to model block to add.
setOwned | If set to true the block is owned by the model. Defaults to true.
See also:
GetBlockNamed
Required Header Files
IwModel.h

void CIwModel::AddExt ( CIwModelExt * pExt )

Adds model extension.

Parameters:
pExt Pointer to the model extension that you would like to add.
See also:
RemoveExt, GetExtNamed
Required Header Files
IwModel.h

void CIwModel::ClearFlags ( uint32 flags ) [inline]

Clears flag bits.

Parameters:
flags Flags to clear.
See also:
SetFlags, GetFlags, WriteFlags
Required Header Files
IwModel.h

CIwModel* CIwModel::CloneWithNewMaterials ( )

Creates a new model, which points to all the same blocks, except the standard primitive blocks, which are copied and point to new copies of the materials.

Parameters:
Pointer to the newly-created model.
Required Header Files
IwModel.h

virtual void CIwModel::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

virtual void CIwModel::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

void* CIwModel::GetBiTangents ( ) const [inline]

Gets a pointer to the model bitangent list.

Returns:
Pointer to the model bitangent list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumNorms(). The type of entry varies according to how the model is conditioned. By default, the type of entry is CIwSVec3.
See also:
GetNumBiTangents
Required Header Files
IwModel.h

CIwModelBlock* CIwModel::GetBlockNamed ( const char * pName ) const

Gets named model block.

Parameters:
pName Model block name to find.
Returns:
Named model block object, or NULL if not found.
See also:
AddBlock
Required Header Files
IwModel.h

const CIwSphere* CIwModel::GetBSphere ( ) const [inline]

Gets a pointer to the model bounding sphere.

Returns:
Pointer to the model bounding sphere.
Required Header Files
IwModel.h

void* CIwModel::GetCols ( ) const [inline]

Gets a pointer to the model colours list.

Returns:
Pointer to the model colour list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumCols(). The type of entry is CIwColour.
See also:
GetNumCols
Required Header Files
IwModel.h

CIwModelExt* CIwModel::GetExtHashed ( uint32 hash ) const

Gets named model extension.

Parameters:
hash The hashed name of the model extension you would like to find.
Returns:
Named model extension object, or NULL if not found.
See also:
AddExt, RemoveExt
Required Header Files
IwModel.h

CIwModelExt* CIwModel::GetExtNamed ( const char * pName ) const

Gets named model extension.

Parameters:
pName The name of the model extension you would like to find.
Returns:
Named model extension object, or NULL if not found.
See also:
AddExt, RemoveExt
Required Header Files
IwModel.h

uint32 CIwModel::GetFlags ( ) const [inline]

Gets current flags.

Returns:
The current flags.
See also:
SetFlags, ClearFlags, GetFlags
Required Header Files
IwModel.h

void* CIwModel::GetNorms ( ) const [inline]

Gets a pointer to the model normal list.

Returns:
Pointer to the model normal list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumNorms(). The type of entry varies according to how the model is conditioned. By default, the type of entry is CIwSVec3.
See also:
GetNumNorms
Required Header Files
IwModel.h

uint16 CIwModel::GetNumChunks ( ) const [inline]

Gets the number of model chunks.

Returns:
The number of chunks in the model.
Remarks:
If models are conditioned in certain ways, they may be "chunked" into spatially discrete sections. In this case, this method returns the number of chunks in the model.
Required Header Files
IwModel.h

uint16 CIwModel::GetNumCols ( ) const [inline]

Gets the number of model colours (vertex colours).

Returns:
The number of colours in the model.
See also:
GetCols
Required Header Files
IwModel.h

uint16 CIwModel::GetNumNorms ( ) const [inline]

Gets the number of model normals (vertex normals).

Returns:
The number of normals in the model.
See also:
GetNorms
Required Header Files
IwModel.h

uint16 CIwModel::GetNumUVs ( ) const [inline]

Gets the number of model UVs (texture coordinates).

Returns:
The number of UVs in the model.
See also:
GetUVs
Required Header Files
IwModel.h

uint16 CIwModel::GetNumVerts ( ) const [inline]

Gets the number of model vertices.

Returns:
The number of vertices in the model.
See also:
GetVerts, GetNumVertsUnique
Required Header Files
IwModel.h

uint16 CIwModel::GetNumVertsUnique ( ) const [inline]

Gets the number of unique model vertices.

Returns:
The number of unique vertices in the model.
See also:
GetNumVerts, GetVerts
Remarks:
If models are conditioned in certain ways, the vertex list may contain duplicates. However, the unique vertices are always first in the list, followed by any duplicates. This method returns the number of unique vertices, which is always <= total vertices.
Required Header Files
IwModel.h

void* CIwModel::GetTangents ( ) const [inline]

Gets a pointer to the model tangent list.

Returns:
Pointer to the model tangent list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumNorms(). The type of entry varies according to how the model is conditioned. By default, the type of entry is CIwSVec3.
See also:
GetNumNorms
Required Header Files
IwModel.h

void* CIwModel::GetUVs ( uint32 id = 0 ) const [inline]

Gets a pointer to the specified model UV list.

Parameters:
id Index of UV list to return. Defaults to 0.
Returns:
Pointer to the specified model UV list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumUVs(). The type of entry is CIwSVec2.
See also:
GetNumUVs
Required Header Files
IwModel.h

void* CIwModel::GetVerts ( ) const [inline]

Gets a pointer to the model vertex list.

Returns:
Pointer to the model vertex list, or NULL if there are none.
Remarks:
The number of entries in the list is GetNumVerts(). The type of entry varies according to how the model is conditioned. By default, the type of entry is CIwSVec3.
See also:
GetNumVerts, GetNumVertsUnique
Required Header Files
IwModel.h

int32 CIwModel::GetZDepthFixed ( ) [inline]

Set a fixed z-depth for the entire model.

Returns:
Fixed z-depth for entire model, or -1 for no offset.
See also:
SetZDepthFixed, SetZDepthOfs, GetZDepthOfs
Required Header Files
IwModel.h

int32 CIwModel::GetZDepthOfs ( ) [inline]

Set a z-depth offset for the entire model.

Returns:
Z-depth offset for entire model, or 0 for no offset.
See also:
SetZDepthOfs, SetZDepthFixed, GetZDepthFixed
Required Header Files
IwModel.h

const bool CIwModel::IsCloned ( ) const [inline]

Is this model created by cloning an original model.

Returns:
True if the model was created by cloning another model.
Required Header Files

virtual void CIwModel::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwModel::RemoveExt ( CIwModelExt * pExt )

Removes model extension.

Parameters:
pExt Pointer to model extension that you would like to remove.
See also:
AddExt, GetExtNamed
Required Header Files
IwModel.h

virtual void CIwModel::Render | ( | bool | checkBSphere = true,
 |  | uint32 | renderFlags = 0 |
 | ) |  |  | const [virtual]

Renders a model with the current IwGxState transform, performing optional bsphere check.

Parameters:
checkBSphere | If set to true, performs an intersection test between the model bounding sphere and the current view frustrum. Defaults to true.
renderFlags | These should be considered opaque.
Required Header Files
IwModel.h

virtual void CIwModel::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwModel::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwModel::SetFlags ( uint32 flags ) [inline]

Sets flag bits.

Parameters:
flags Flags to set.
See also:
ClearFlags, GetFlags, WriteFlags
Required Header Files
IwModel.h

void CIwModel::SetZDepthFixed ( int32 val ) [inline]

Set a fixed z-depth for the entire model. If not -1, this value will override any fixed z-depth set on any material used by the model. In this way, a constant fixed z-depth can be applied to the entire model. If set to -1, the model material fixed z-depths are used, as usual.

Parameters:
val Fixed z-depth to set, or -1 for no offset.
See also:
GetZDepthFixed, SetZDepthOfs, GetZDepthOfs
Required Header Files
IwModel.h

void CIwModel::SetZDepthOfs ( int32 ofs ) [inline]

Set a z-depth offset for the entire model. If not 0, this value will override any z-depth offset set on any material used by the model. In this way, a constant z-depth offset can be applied to the entire model. If set to 0, the model material z-depth offsets are used, as usual.

Parameters:
ofs Z-depth offset to set, or 0 for no offset.
See also:
GetZDepthOfs, SetZDepthFixed, GetZDepthFixed
Required Header Files
IwModel.h

const bool CIwModel::VertCopiesAreIDs ( ) const [inline]

Are vertex copies in this model IDs.

Returns:
True if the model's copy vertices are IDs.
Required Header Files

void CIwModel::WriteFlags ( uint32 flags ) [inline]

Writes flags, changing all bits to those specified.

Parameters:
flags New flags value to set.
See also:
SetFlags, ClearFlags, GetFlags
Required Header Files
IwModel.h

Field Documentation

CIwModel* CIwModel::g_Context [static]

Global pointer to "current" model, when a model is being created/serialised/rendered.

void* CIwModel::g_Norms [static]

Global pointer to "current" normal block, when a model is being parsed/rendered.

void* CIwModel::g_Verts [static]

Global pointer to "current" vertex block, when a model is being parsed/rendered.

CIwManagedList CIwModel::m_Blocks

List of model blocks.

CIwSphere CIwModel::m_BSphere

Model bounding sphere.

CIwManagedList CIwModel::m_Exts

List of model extensions.

CIwManagedList CIwModel::m_Materials

List of all materials used the the model.

The documentation for this class was generated from the following file:
  • IwModel.h


Airplay API Reference: CIwModelBlock

Airplay API Reference > Data Structures > CIwModelBlock >

CIwModelBlock Class Reference
[IwGraphics API Reference]

#include <IwModelBlock.h>

Inheritance diagram for CIwModelBlock:

[legend]

Public Types

enum
typedef uint32(* | IwModelBlockRender )(CIwModel *pModel, CIwModelBlock *pBlock, uint32 flags)

Public Member Functions

virtual void | ApplyScale (iwfixed scale)
CIwModelBlock ()
virtual uint32 | GetItemSize ()
virtual uint32 | GetTotalSize ()
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | PostRender (CIwModel *pModel, uint32 flags)
virtual uint32 | Render (CIwModel *pModel, uint32 flags)
virtual void | Resolve ()
virtual void | Serialise ()

Detailed Description

Base class for all model blocks. See the Model Block module overview for more information.

Member Typedef Documentation

typedef uint32(* CIwModelBlock::IwModelBlockRender)(CIwModel *pModel, CIwModelBlock *pBlock, uint32 flags)

Typedef for model block render override callback. The user can set this callback on any instance of a model block, to perform custom rendering.

Note:
Only users with an advanced understanding of IwGraphics and IwGx should attempt this.

Member Enumeration Documentation

anonymous enum

Block flags.

Enumerator:
USER_F user flags start here

anonymous enum

Classes derived from CIwModelBlock must return either RENDER_OK, or a combination of these flags.

Note:
Only users with an advanced understanding of IwGraphics and IwGx should attempt this.
Enumerator:
CLIPPED_F model clipped, do no further processing

Constructor & Destructor Documentation

CIwModelBlock::CIwModelBlock ( ) [inline]

Constructor.

Member Function Documentation

virtual void CIwModelBlock::ApplyScale ( iwfixed scale ) [inline, virtual]

Apply a fixed-point scaling factor to the model.

Parameters:
scale Scaling factor, in iwfixed format.

virtual void CIwModelBlock::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

virtual uint32 CIwModelBlock::GetItemSize ( ) [inline, virtual]

Most model blocks point to a list of items. This method returns the size of an individual item. For example, CIwModelBlockVerts contains a list of CIwSVec3 items, so this function would return sizeof(CIwSVec3).

Returns:
Size of an individual item, in bytes.

virtual uint32 CIwModelBlock::GetTotalSize ( ) [inline, virtual]

The size of the entire model block, in bytes.

Returns:
Size of entire model block, in bytes.

virtual void CIwModelBlock::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwModelBlock::PostRender | ( | CIwModel * | pModel,
 |  | uint32 | flags |
 | ) |  |  | [inline, virtual]

Clear any persistent effects of rendering this block. This is never called by the framework, but can be used in client code to clear up per-instance colours etc.

virtual uint32 CIwModelBlock::Render | ( | CIwModel * | pModel,
 |  | uint32 | flags |
 | ) |  |  | [inline, virtual]

The "process" function called on the model block, when CIwModel::Render() is called on the model. For example, CIwModelBlockVerts::Render() will transform the model vertices from modelspace to viewspace.

Parameters:
pModel | Pointer to the owning model.
flags | Flags. RENDER_OK, or a combination of flags from the same enumeration.

virtual void CIwModelBlock::Resolve ( ) [inline, virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwModelBlock::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

Field Documentation

uint16 CIwModelBlock::m_Flags

Flags governing block usage.

uint16 CIwModelBlock::m_NumItems

Number of prims following .

CIwModel* CIwModelBlock::m_Owner

Pointer to model which owns this block (for blocks in cloned model lists, this may point to the original model).

IwModelBlockRender CIwModelBlock::m_RenderFn

If non-NULL, override class Render() method.

uint16 CIwModelBlock::m_Size

Size of block data (including header) in bytes.

The documentation for this class was generated from the following file:
  • IwModelBlock.h


Airplay API Reference: CIwModelExt

Airplay API Reference > Data Structures > CIwModelExt >

CIwModelExt Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExt:

[legend]

Public Types

enum

Public Member Functions

virtual void | ApplyScale (int32 scale)
CIwModelExt ()
void | ClearFlags (uint32 flags)
uint32 | GetFlags () const
bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
void | ParseClose (CIwTextParserITX *pParser)
virtual void | RemapVertexIDs (uint32 *vertmap)
void | Serialise ()
void | SetFlags (uint32 flags)
void | SetRedundant ()

Data Fields

CIwModel * m_Owner

Detailed Description

Model extension. See the Model Extension module overview for more information.

Member Enumeration Documentation

anonymous enum

Flags.

Required Header Files
IwModelExt.h
Enumerator:
REDUNDANT_F Can be set during build process - extension will NOT be copied to model.

Constructor & Destructor Documentation

CIwModelExt::CIwModelExt ( ) [inline]

Constructor.

Member Function Documentation

virtual void CIwModelExt::ApplyScale ( int32 scale ) [inline, virtual]

Applies scaling to the extension.

Parameters:
scale Scaling to apply.
Required Header Files
IwModelExt.h

void CIwModelExt::ClearFlags ( uint32 flags ) [inline]

Clears flags.

Parameters:
Flag bits to clear.
See also:
SetFlags, GetFlags
Required Header Files
IwModelExt.h

virtual void CIwModelExt::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwManaged.

Reimplemented in CIwModelExtSelSetFace.

uint32 CIwModelExt::GetFlags ( ) const [inline]

Gets flags.

Returns:
The current flags.
See also:
SetFlags, ClearFlags
Required Header Files
IwModelExt.h

bool CIwModelExt::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

Reimplemented in CIwModelExtPos, CIwModelExtSphere, CIwModelExtSelSetVert, CIwModelExtSelSetEdge, and CIwModelExtSelSetFace.

void CIwModelExt::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Reimplemented in CIwModelExtSelSetFace.

virtual void CIwModelExt::RemapVertexIDs ( uint32 * vertmap ) [inline, virtual]

Reorder vertex IDs used in this extension such that newID = vertmap[oldID] Must be implimented by derived classes if extension uses vertex IDs

Required Header Files
IwModelExt.h

Reimplemented in CIwModelExtSelSetVert, and CIwModelExtSelSetEdge.

void CIwModelExt::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

Reimplemented in CIwModelExtPos, CIwModelExtSphere, CIwModelExtSelSetVert, CIwModelExtSelSetEdge, and CIwModelExtSelSetFace.

void CIwModelExt::SetFlags ( uint32 flags ) [inline]

Sets flags.

Parameters:
Flag bits to set.
See also:
ClearFlags, GetFlags
Required Header Files
IwModelExt.h

void CIwModelExt::SetRedundant ( ) [inline]

Sets extension as redundant. This can be done during the model building process, so the extension will NOT be copied to the created model.

Required Header Files
IwModelExt.h

Field Documentation

CIwModel* CIwModelExt::m_Owner

Pointer to the model which owns this extension. For extensions in a cloned model, this will point back to the original model.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtPos

Airplay API Reference > Data Structures > CIwModelExtPos >

CIwModelExtPos Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtPos:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Serialise ()

Detailed Description

Model extension: position (point).

Member Function Documentation

virtual void CIwModelExtPos::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

virtual bool CIwModelExtPos::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwModelExt.

virtual void CIwModelExtPos::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwModelExt.

Field Documentation

CIwSVec3 CIwModelExtPos::m_Pos

Position.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtSelSet

Airplay API Reference > Data Structures > CIwModelExtSelSet >

CIwModelExtSelSet Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtSelSet:

[legend]

Detailed Description

Model extension: selection set.
The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtSelSetEdge

Airplay API Reference > Data Structures > CIwModelExtSelSetEdge >

CIwModelExtSelSetEdge Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtSelSetEdge:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseOpen (CIwTextParserITX *pParser)
virtual void | RemapVertexIDs (uint32 *vertmap)
virtual void | Serialise ()

Detailed Description

Model extension: edge selection set.

Member Function Documentation

virtual void CIwModelExtSelSetEdge::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

virtual bool CIwModelExtSelSetEdge::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetEdge::ParseOpen ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: start block.

Parameters:
pParser the parser instance to use
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwModelExtSelSetEdge::RemapVertexIDs ( uint32 * vertmap ) [virtual]

Reorder vertex IDs used in this extension such that newID = vertmap[oldID] Must be implimented by derived classes if extension uses vertex IDs

Required Header Files
IwModelExt.h

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetEdge::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwModelExt.

Field Documentation

CIwArray<CIwEdge> CIwModelExtSelSetEdge::m_Edges

Array of IDs into model edge list.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtSelSetFace

Airplay API Reference > Data Structures > CIwModelExtSelSetFace >

CIwModelExtSelSetFace Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtSelSetFace:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | Serialise ()

Detailed Description

Model extension: face selection set.

Member Function Documentation

virtual void CIwModelExtSelSetFace::DebugAddMenuItems ( CIwMenu * pMenu ) [virtual]

Add menu items to a CIwMenu for debugging purposes.

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetFace::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

virtual bool CIwModelExtSelSetFace::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetFace::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetFace::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwModelExt.

Field Documentation

CIwArray<uint16> CIwModelExtSelSetFace::m_FaceIDs

IDs into model builder face array.

uint8 CIwModelExtSelSetFace::m_Flags

CIwFace flags - general.

Reimplemented from CIwModelExt.

uint8 CIwModelExtSelSetFace::m_FlagsHW

CIwFace flags - HW.

uint8 CIwModelExtSelSetFace::m_FlagsSW

CIwFace flags - SW.

uint32 CIwModelExtSelSetFace::m_NumFaces

Number of faces in model this set applies to.

int8 CIwModelExtSelSetFace::m_OTZOfsSW

OTZ offset for SW.

bool CIwModelExtSelSetFace::m_WorldSet

True if this set is a world file only set.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtSelSetVert

Airplay API Reference > Data Structures > CIwModelExtSelSetVert >

CIwModelExtSelSetVert Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtSelSetVert:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseOpen (CIwTextParserITX *pParser)
virtual void | RemapVertexIDs (uint32 *vertmap)
virtual void | Serialise ()

Detailed Description

Model extension: vertex selection set.

Member Function Documentation

virtual void CIwModelExtSelSetVert::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

virtual bool CIwModelExtSelSetVert::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetVert::ParseOpen ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: start block.

Parameters:
pParser the parser instance to use
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwModelExtSelSetVert::RemapVertexIDs ( uint32 * vertmap ) [virtual]

Reorder vertex IDs used in this extension such that newID = vertmap[oldID] Must be implimented by derived classes if extension uses vertex IDs

Required Header Files
IwModelExt.h

Reimplemented from CIwModelExt.

virtual void CIwModelExtSelSetVert::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwModelExt.

Field Documentation

CIwArray<uint16> CIwModelExtSelSetVert::m_VertIDs

Array of IDs into model vertex list.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwModelExtSphere

Airplay API Reference > Data Structures > CIwModelExtSphere >

CIwModelExtSphere Class Reference
[Model Extensions]

#include <IwModelExt.h>

Inheritance diagram for CIwModelExtSphere:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Serialise ()

Detailed Description

Model extension: sphere.

Member Function Documentation

virtual void CIwModelExtSphere::DebugRender ( ) [virtual]

Debug rendering.

Reimplemented from CIwManaged.

virtual bool CIwModelExtSphere::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwModelExt.

virtual void CIwModelExtSphere::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwModelExt.

Field Documentation

CIwSphere CIwModelExtSphere::m_Sphere

Sphere.

The documentation for this class was generated from the following file:
  • IwModelExt.h


Airplay API Reference: CIwPlane

Airplay API Reference > Data Structures > CIwPlane >

CIwPlane Class Reference
[IwGeomPlane]

Fixed-point plane: 3-vector normal and constant. More...

#include <IwGeomPlane.h>

Public Member Functions

CIwPlane (CIwSVec3 const &_a, CIwSVec3 const &_b, CIwSVec3 const &_c)
CIwPlane (CIwVec3 const &_a, CIwVec3 const &_b, CIwVec3 const &_c)
CIwPlane (CIwSVec3 const &_v, CIwSVec3 const &vk)
CIwPlane (CIwSVec3 const &_v, CIwVec3 const &vk)
CIwPlane (CIwSVec3 const &_v, int32 vk)
CIwPlane ()
int32 | GetPerpDist (CIwVec3 const &a) const
CIwPlane | operator- () const
bool | operator== (CIwPlane const &p) const

Data Fields

int32 | k
CIwSVec3 v

Static Public Attributes

static CIwPlane | g_XY
static CIwPlane | g_XZ
static CIwPlane | g_YZ

Detailed Description

Elements are 32-bit. Fixed point is defined by user. CIwPlane - Defines a fixed-point plane by a 3-vector normal and constant.
See also:
IwGeomCore

IwGeomVec

Required Header Files
IwGeomPlane.h

Constructor & Destructor Documentation

CIwPlane::CIwPlane ( ) [inline]

Creates a new uninitialised plane.

CIwPlane::CIwPlane | ( | CIwSVec3 const & | _v,
 |  | int32 | vk |
 | ) |  |  | [inline]

Creates a new plane.

Parameters:
_v | Normal of plane. Assumed to be normalised.
vk | Plane constant. Distance of plane from the origin.

CIwPlane::CIwPlane | ( | CIwSVec3 const & | _v,
 |  | CIwVec3 const & | vk |
 | ) |  |  | [inline]

Creates the unique plane defined by the given parameters.

Parameters:
_v | Normal of plane (16 bit).
vk | A point lying in the plane (32 bit).

CIwPlane::CIwPlane | ( | CIwSVec3 const & | _v,
 |  | CIwSVec3 const & | vk |
 | ) |  |  | [inline]

Creates the unique plane defined by the given parameters.

Parameters:
_v | Normal of plane (16 bit).
vk | A point lying in the plane (16 bit).

CIwPlane::CIwPlane | ( | CIwVec3 const & | _a,
 |  | CIwVec3 const & | _b,
 |  | CIwVec3 const & | _c |
 | ) |  |  | [inline]

Creates the unique plane defined by the given parameters.

Parameters:
_a | Point lying in the plane (32 bit).
_b | Point lying in the plane (32 bit).
_c | Point lying in the plane (32 bit).

CIwPlane::CIwPlane | ( | CIwSVec3 const & | _a,
 |  | CIwSVec3 const & | _b,
 |  | CIwSVec3 const & | _c |
 | ) |  |  | [inline]

Creates the unique plane defined by the given parameters.

Parameters:
_a | Point lying in the plane (16 bit).
_b | Point lying in the plane (16 bit).
_c | Point lying in the plane (16 bit).

Member Function Documentation

int32 CIwPlane::GetPerpDist ( CIwVec3 const & a ) const [inline]

Returns the perpendicular distance of point from plane.

Parameters:
a The point from which to measure.
Returns:
Signed perpendicular distance of point from plane.
Note:
The distance is positive if point lies above plane (on side of plane its normal points into).
Required Header Files
IwGeomPlane.h

CIwPlane CIwPlane::operator- ( ) const [inline]

Creates a plane that is logically the same as this plane, but with a different representation.

Returns:
Plane with opposite normal and constant.

bool CIwPlane::operator== ( CIwPlane const & p ) const [inline]

Compares the representations of this plane to another.

Parameters:
p Plane for comparison.
Returns:
true if this plane and p have the same normal and constant.

Field Documentation

CIwPlane CIwPlane::g_XY [static]

World plane containing the X-axis and Y-axis.

CIwPlane CIwPlane::g_XZ [static]

World plane containing the X-axis and Z-axis.

CIwPlane CIwPlane::g_YZ [static]

World plane containing the Y-axis and Z-axis.

int32 CIwPlane::k

Distance of plane from origin along normal vector. A vector w lies in the plane iff w*v==k

CIwSVec3 CIwPlane::v

Normal vector of plane, normalised.

The documentation for this class was generated from the following file:
  • IwGeomPlane.h


Airplay API Reference: CIwProperty

Airplay API Reference > Data Structures > CIwProperty< Type > >

CIwProperty< Type > Class Template Reference
[Property Set, Property Set]

Templated class to used by CIwPropertySet to store data of different types. The CIwProperty owns the data it contains and provides an interface for accessing it, as well as parsing, serialise and resolving the data. More...

#include <IwProperty.h>

Inheritance diagram for CIwProperty< Type >:

[legend]

Public interface

const Type & | Get () const
template<class DataType>
void | Get (DataType &data) const
template<class DataType>
bool | Set (const DataType &data)
static CIwPropertyBase * | ClassFactory (uint32 defineId, const char *pDebugName)

Public Member Functions

CIwProperty (uint32 defineId, const char *pDebugName)
template<class DataType>
CIwProperty (uint32 defineId, const char *pDebugName, const DataType &val)
CIwPropertyBase virtuals
virtual CIwPropertyBase * | Clone () const
virtual CIwPropertyBase * | Copy () const
virtual void | Decompose (CIwTextDecomposer *pDecomposer) const
virtual const void * | ExposeData () const
virtual uint32 | GetDataType () const
virtual const char * | GetDataTypeString () const
virtual bool | isDataType (uint32 dataType) const
virtual void | Parse (CIwTextParserITX *pParser)

Detailed Description

template<class Type>
class CIwProperty< Type >

To allow an instance of the CIwProperty template to be created for a new data type, an specialisation of the static members of CIwPropertyDataType template must be provided somewhere.

Constructor & Destructor Documentation

template<class Type>
template<class DataType>
CIwProperty< Type >::CIwProperty | ( | uint32 | defineId,
 |  | const char * | pDebugName,
 |  | const DataType & | val |
 | ) |  |  | [inline]

Property constructor.

Parameters:
defineId | Hash of property define
pDebugName | Optional debug property define string name
val | Initial value of property's data
Note:
Requires property data type to have copy constructor from the supplied type.

template<class Type>
CIwProperty< Type >::CIwProperty | ( | uint32 | defineId,
 |  | const char * | pDebugName |
 | ) |  |  | [inline]

Property constructor.

Parameters:
defineId | Hash of property define
pDebugName | Optional debug property define string name

Member Function Documentation

template<class Type>
static CIwPropertyBase* CIwProperty< Type >::ClassFactory | ( | uint32 | defineId,
 |  | const char * | pDebugName |
 | ) |  |  | [inline, static]

Class factory for property.

Parameters:
Hash | of property define.
Optional | property define debug string name.
Returns:
A pointer to new property of this type.

template<class Type>
virtual CIwPropertyBase* CIwProperty< Type >::Clone ( ) const [inline, virtual]

Clones this property. The property's data is copied using CIwPropertyDataType::Clone, which must be implemented for the property's data type.

Returns:
Pointer to a clone of the property.

Implements CIwPropertyBase.

template<class Type>
virtual CIwPropertyBase* CIwProperty< Type >::Copy ( ) const [inline, virtual]

Copies this property. The property's data is copied using the data's copy constructor.

Returns:
Pointer to a copy of the property.

Implements CIwPropertyBase.

template<class Type>
virtual void CIwProperty< Type >::Decompose ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Decomposes property's data to text format. Requires CIwPropertyDataType::Decompose to be implemented for the property's data type.

Parameters:
pDecomposer Pointer to text decomposer to write data to.

Implements CIwPropertyBase.

template<class Type>
virtual const void* CIwProperty< Type >::ExposeData ( ) const [inline, virtual]

Expose a pointer to the data contained by this property.

Returns:
Pointer to data which user must cast to the appropriate type.

Implements CIwPropertyBase.

template<class Type>
const Type& CIwProperty< Type >::Get ( ) const [inline]

Get read-only access to the property's data.

Returns:
A reference to the property's data.

template<class Type>
template<class DataType>
void CIwProperty< Type >::Get ( DataType & data ) const [inline]

Copy property's data over supplied reference.

Parameters:
data Reference to copy property data to.
Note:
Requires property data type to have an assignment operator.

template<class Type>
virtual uint32 CIwProperty< Type >::GetDataType ( ) const [inline, virtual]

Get the hash of the property's data type.

Returns:
Same result as IwHashString(GetDataTypeString())

Implements CIwPropertyBase.

template<class Type>
virtual const char* CIwProperty< Type >::GetDataTypeString ( ) const [inline, virtual]

Get string representing property's data type. This requires CIwPropertyDataType::s_Data to be defined somewhere for the property's data type.

Returns:
Pointer to data type string.

Implements CIwPropertyBase.

template<class Type>
virtual bool CIwProperty< Type >::isDataType ( uint32 dataType ) const [inline, virtual]

Determines if the pointer returned by ExposeData can safely be cast to a particular data type. Requires CIwPropertyDataType::IsOfType to be implemented for the property's data type.

Parameters:
dataType Hash name of a property data type.

Implements CIwPropertyBase.

template<class Type>
virtual void CIwProperty< Type >::Parse ( CIwTextParserITX * pParser ) [inline, virtual]

Parses the property's data from text format. Requires CIwPropertyDataType::Parse to be implemented for the property's data type.

Parameters:
pParser Pointer to text parser data is being read from.

Implements CIwPropertyBase.

template<class Type>
virtual void CIwProperty< Type >::Resolve ( ) [inline, virtual]

Resolves the property's data. Requires CIwPropertyDataType::Resolve to be implemented for the property's data type.

Reimplemented from CIwPropertyBase.

template<class Type>
virtual void CIwProperty< Type >::Serialise ( void ) [inline, virtual]

Serialises the property's data. Requires CIwPropertyDataType::Serialise to be implemented for the property's data type.

Reimplemented from CIwPropertyBase.

template<class Type>
template<class DataType>
bool CIwProperty< Type >::Set ( const DataType & data ) [inline]

Set the property's data to supplied value, if it is different to the current value.

Parameters:
data Reference to value to set property's data to.
Returns:
Whether the property changed or not.
Note:
Requires property data type to have a comparison operator and an assignment operator.

The documentation for this class was generated from the following file:
  • IwProperty.h


Airplay API Reference: CIwPropertyBase

Airplay API Reference > Data Structures > CIwPropertyBase >

CIwPropertyBase Class Reference
[Property Set, Property Set]

Base class for CIwProperty. Used by CIwPropertySet to store a collection of properties.

#include <IwPropertyBase.h>

Inheritance diagram for CIwPropertyBase:

[legend]

Public Member Functions

Declared virtuals
virtual CIwPropertyBase * | Clone () const =0
virtual CIwPropertyBase * | Copy () const =0
virtual void | Decompose (CIwTextDecomposer *pDecomposer) const =0
virtual const void * | ExposeData () const =0
virtual uint32 | GetDataType () const =0
virtual const char * | GetDataTypeString () const =0
virtual bool | isDataType (uint32 dataType) const =0
virtual void | Parse (CIwTextParserITX *pParser)=0
Public interface
const char * | DebugGetPropertyDefine () const
uint32 | GetPropertyDefineID () const
bool | isDefineMatch (uint32 idToMatch) const
void | SetPropertyDefine (const char *pName)

Member Function Documentation

virtual CIwPropertyBase* CIwPropertyBase::Clone ( ) const [pure virtual]

Makes a clone of this property. This will do a deep copy of property data and hence can be considered owned.

Returns:
The clone of this property

Implemented in CIwProperty< Type >.

virtual CIwPropertyBase* CIwPropertyBase::Copy ( ) const [pure virtual]

Makes a copy of this property. The copied properties data may reference shared data. To ensure the property data is owned, use Clone instead.

Returns:
The copy of this property

Implemented in CIwProperty< Type >.

const char* CIwPropertyBase::DebugGetPropertyDefine ( ) const

In debug, get this property's definition name.

Returns:
Pointer to debug string name of property define.

virtual void CIwPropertyBase::Decompose ( CIwTextDecomposer * pDecomposer ) const [pure virtual]

Decompose property's data to text format.

Parameters:
pDecomposer Pointer to text decomposer to write data to.

Implemented in CIwProperty< Type >.

virtual const void* CIwPropertyBase::ExposeData ( ) const [pure virtual]

Expose a pointer to the data contained by this property.

Returns:
Pointer to property's data.
Note:
isDataType can be used to interrogate the type of the pointer returned.a
        // Is property data a ptr to a class derived from CIwManaged?
        if(pProperty->isDataType(IwHashString("CIwManaged*"))
        {
            const char* pDebugName =
                (*(CIwManaged**)pProperty->ExposeVal())->DebugGetName();
        }

Implemented in CIwProperty< Type >.

virtual uint32 CIwPropertyBase::GetDataType ( ) const [pure virtual]

Gets this property's data type.

Returns:
A hash representing this property's data type.

Implemented in CIwProperty< Type >.

virtual const char* CIwPropertyBase::GetDataTypeString ( ) const [pure virtual]

Gets this property's data type.

Returns:
A string representing this property's data type.

Implemented in CIwProperty< Type >.

uint32 CIwPropertyBase::GetPropertyDefineID ( ) const [inline]

Get this property's property definition hash.

Returns:
Hash representing the property define for this property.

virtual bool CIwPropertyBase::isDataType ( uint32 dataType ) const [pure virtual]

Determines if the pointer returned by ExposeData can safely be cast to a particular data type.

Parameters:
dataType Hash name of a property data type.

Implemented in CIwProperty< Type >.

bool CIwPropertyBase::isDefineMatch ( uint32 idToMatch ) const [inline]

Compares the property's Definition ID to a hash value passed in.

Parameters:
idToMatch Hash value to compare against this property's define ID.
Returns:
If the hashes match.

virtual void CIwPropertyBase::Parse ( CIwTextParserITX * pParser ) [pure virtual]

Parses property's data from text format.

Parameters:
pParser Pointer to text parser data is being read from.

Implemented in CIwProperty< Type >.

virtual void CIwPropertyBase::Resolve ( ) [virtual]

Resolves the property's data.

Reimplemented from CIwManaged.

Reimplemented in CIwProperty< Type >.

virtual void CIwPropertyBase::Serialise ( ) [virtual]

Serialises the property's data.

Reimplemented from CIwManaged.

Reimplemented in CIwProperty< Type >.

void CIwPropertyBase::SetPropertyDefine ( const char * pName )

Set the name of this property's definition.

Parameters:
pName String name of property definition.

The documentation for this class was generated from the following file:
  • IwPropertyBase.h


Airplay API Reference: CIwPropertyDataType

Airplay API Reference > Data Structures > CIwPropertyDataType< Type > >

CIwPropertyDataType< Type > Class Template Reference
[Property Set, Property Set]

Templated class containing static methods used by CIwProperty. Specialisations of the members of this class must be provided for each data type used with the property set system. More...

#include <IwPropertyDataType.h>

Detailed Description

template<class Type>
class CIwPropertyDataType< Type >

That is, for each data type the CIwProperty template is instantiated, a specialisation of CIwPropertyDataType must be provided somewhere.

Helper defines are provided to reduce the amount of code that needs to be written in the majority of cases.

The documentation for this class was generated from the following file:
  • IwPropertyDataType.h


Airplay API Reference: CIwPropertyDefine

Airplay API Reference > Data Structures > CIwPropertyDefine >

CIwPropertyDefine Class Reference
[Property Set, Property Set]

Used to by CIwPropertySet to map a property name to a property data type. For example a property define maps the property name "colour" to the data type "CIwColour". A property of the correct type can be created using CreateProperty which uses the property factory. More...

#include <IwPropertyDefine.h>

Inheritance diagram for CIwPropertyDefine:

[legend]

Public Member Functions

CIwPropertyBase * | CreateProperty () const
const uint32 | GetDataTypeHash ()
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | Serialise ()

Detailed Description

Property defines are used in data to declare new properties in data. For example,
            CIwPropertyDefine
            {
                // Declare "offsetPos" property to have vector type "CIwSVec2".
                CIwSVec2 offsetPos;
            }

Member Function Documentation

CIwPropertyBase* CIwPropertyDefine::CreateProperty ( ) const

Create a property, using the property factory and the property defines data type.

Returns:
New property, or NULL if factory function was not found.

const uint32 CIwPropertyDefine::GetDataTypeHash ( ) [inline]

Get this definition's data type.

Returns:
A hash representing this definition's data type.

virtual bool CIwPropertyDefine::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

virtual void CIwPropertyDefine::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwPropertyDefine::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

The documentation for this class was generated from the following file:
  • IwPropertyDefine.h


Airplay API Reference: CIwPropertyList

Airplay API Reference > Data Structures > CIwPropertyList< Type > >

CIwPropertyList< Type > Class Template Reference
[Property Set, Property Set]

Templated list property (facilitating variable-length properties). More...

#include <IwPropertyList.h>

Inheritance diagram for CIwPropertyList< Type >:

[legend]

Data Structures

class CIwPropertyListImpl

Detailed Description

template<typename Type>
class CIwPropertyList< Type >

Note:
Shared private implementation to avoid array copying.
The documentation for this class was generated from the following file:
  • IwPropertyList.h


Airplay API Reference: CIwPropertySet

Airplay API Reference > Data Structures > CIwPropertySet >

CIwPropertySet Class Reference
[Property Set, Property Set]

A property set is used to store and retrieve a collection of properties derived from CIwPropertyBase. The property set can also have a parent property set. More...

#include <IwPropertySet.h>

Inheritance diagram for CIwPropertySet:

[legend]

Public Member Functions

void | AddProperty (CIwPropertyBase *newProperty)
void | Clone (const CIwPropertySet &other)
iterator | GetBegin () const
iterator | GetEnd () const
uint32 | GetNumProperties () const
template<class Type>
bool | GetProperty (const char *propDef, Type &val, bool allowMissing=false, bool checkParent=true) const
const CIwPropertyBase * | GetPropertyByHash (uint32 hash, bool checkParent=true) const
const CIwPropertyBase * | GetPropertyByIndex (uint32 index) const
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual void | Resolve ()
virtual void | Serialise ()
void | SetBinding (CIwPropertySetBinding *pBinding)
template<typename Type>
bool | SetProperty (const char *propDefName, const Type &newDataVal)

Detailed Description

When retrieving a property, via CIwPropertySet::Get, the property set's own collection is first searched. If the property is not found, then the the parent property set, if present, is searched.

Member Function Documentation

void CIwPropertySet::AddProperty ( CIwPropertyBase * newProperty )

Add an new property to this property list.

Parameters:
newProperty Pointer to the property to be added.

void CIwPropertySet::Clone ( const CIwPropertySet & other )

Returns:
Make this property set a clone of the given property set.

virtual void CIwPropertySet::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

Reimplemented in CIwUIPropertySet.

virtual void CIwPropertySet::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwPropertySet::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwPropertySet::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

iterator CIwPropertySet::GetBegin ( ) const [inline]

Returns:
begin() iterator

CIwPropertySetBinding* CIwPropertySet::GetBinding ( ) const [inline]

Get binding, if any, of this property set.

iterator CIwPropertySet::GetEnd ( ) const [inline]

Returns:
end() iterator

uint32 CIwPropertySet::GetNumProperties ( ) const

Returns:
Number of properties present in this property set.

virtual const CIwPropertySet* CIwPropertySet::GetParent ( ) const [virtual]

Get this property set's parent.

Reimplemented in CIwUIPropertySet.

template<class Type>
bool CIwPropertySet::GetProperty | ( | const char * | propDef,
 |  | Type & | val,
 |  | bool | allowMissing = false,
 |  | bool | checkParent = true |
 | ) |  |  | const [inline]

Get the value of a specified property.

Parameters:
propDef | the definition (or "name") of the property searched for.
val | reference to the variable to store the value upon success.
allowMissing | should function assert if property is not found?
checkParent | should the parent property set be searched?
Returns:
Boolean determining the result of the search.
Return values:
true | A value was successfully found and stored in the provided reference
false | A value was not found. No value was stored.

const CIwPropertyBase* CIwPropertySet::GetPropertyByHash | ( | uint32 | hash,
 |  | bool | checkParent = true |
 | ) |  |  | const

Parameters:
hash Hash of property
Returns:
Property with given hash, or NULL if not present

const CIwPropertyBase* CIwPropertySet::GetPropertyByIndex ( uint32 index ) const

Parameters:
index Index of property
Returns:
Property at given index within this property set

virtual bool CIwPropertySet::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

Reimplemented in CIwUIPropertySet.

virtual void CIwPropertySet::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Reimplemented in CIwUIPropertySet.

virtual void CIwPropertySet::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwPropertySet::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Reimplemented in CIwUIPropertySet.

virtual void CIwPropertySet::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

Reimplemented in CIwUIPropertySet.

void CIwPropertySet::SetBinding ( CIwPropertySetBinding * pBinding ) [inline]

Set a binding for this property set (giving ownership to property set).

Note:
Property set does not destroy any previous property set

virtual void CIwPropertySet::SetParent ( const CIwPropertySet * pPropertySet ) [virtual]

Set a new parent for this property set.

Reimplemented in CIwUIPropertySet.

template<typename Type>
bool CIwPropertySet::SetProperty | ( | const char * | propDefName,
 |  | const Type & | newDataVal |
 | ) |  |  | [inline]

Set property on this property list.

Parameters:
propDefine | Hash representing the property definition.
newDataVal | data for this property.
Returns:
Whether the property changed or not.

The documentation for this class was generated from the following file:
  • IwPropertySet.h


Airplay API Reference: CIwPropertySetBinding

Airplay API Reference > Data Structures > CIwPropertySetBinding >

CIwPropertySetBinding Class Reference
[Property Set, Property Set]

Used to allow binding properties to an external source.

#include <IwPropertySetBinding.h>

Inheritance diagram for CIwPropertySetBinding:

[legend]

Public Member Functions

virtual void | Clone (CIwPropertySetBinding *pTarget) const
virtual bool | GetProperty (const CIwPropertySet *pSet, CIwPropertyBase *pProperty)=0
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual bool | SetProperty (const CIwPropertySet *pSet, CIwPropertyBase *pProperty)=0

Member Function Documentation

virtual void CIwPropertySetBinding::Clone ( CIwPropertySetBinding * pTarget ) const [virtual]

Returns:
A clone of this binding

virtual void CIwPropertySetBinding::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwPropertySetBinding::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwPropertySetBinding::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwPropertySetBinding::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

virtual bool CIwPropertySetBinding::GetProperty | ( | const CIwPropertySet * | pSet,
 |  | CIwPropertyBase * | pProperty |
 | ) |  |  | [pure virtual]

Allows binding to provide the value of properties. A template property is provided for the binding to store its value in. Bindings selectively provide values by checking the hash of the given property.

Parameters:
pSet | Property set which is querying the binding.
pProperty | Template property for binding to store value in.
Returns:
Boolean indicating if the property value has been stored in pProperty.
Note:
The data with the property is uninitialised and shouldn't be read.

virtual void CIwPropertySetBinding::NotifyPropertyChanged ( const char * pName ) [virtual]

By default, informs any observer that a bound property has changed.

virtual void CIwPropertySetBinding::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual bool CIwPropertySetBinding::SetProperty | ( | const CIwPropertySet * | pSet,
 |  | CIwPropertyBase * | pProperty |
 | ) |  |  | [pure virtual]

Allows binding to store the value of properties. A property containing the new value is provided. Bindings selectively store values by checking the hash of the given property.

A template property is provided for the binding to store its value in. Bindings selectively provide properties by checking the hash.

Parameters:
pSet | Property set which is querying the binding.
pProperty | Property containing value for binding to store.
Returns:
Boolean indicating if the property value has been stored by the binding and does not need to be stored by the property set.
Return values:
true Indicates that the binding will provide the value to future calls to GetProperty().

The documentation for this class was generated from the following file:
  • IwPropertySetBinding.h


Airplay API Reference: CIwPropertyString

Airplay API Reference > Data Structures > CIwPropertyString >

CIwPropertyString Class Reference
[Property Set]

Variable-length string class, shared (ref-counted) representation.

#include <IwPropertyString.h>

The documentation for this class was generated from the following file:
  • IwPropertyString.h


Airplay API Reference: CIwPropertyTypeMap

Airplay API Reference > Data Structures > CIwPropertyTypeMap< Key > >

CIwPropertyTypeMap< Key > Class Template Reference
[Property Set, Property Set]

Allows mapping between a type used to access property data and the the type used to store a particular property. This can be useful when getting or setting properties on a property set via CIwPropertySet::Get and CIwPropertySet::Set respectively. More...

#include <IwProperty.h>

Detailed Description

template<class Key>
class CIwPropertyTypeMap< Key >

To make use of a mapping, the compiler must be able to find a conversion to (for CIwPropertySet::Get) or from (for CIwPropertySet::Set) the provided type which is mapped to the property storage type.
The documentation for this class was generated from the following file:
  • IwProperty.h


Airplay API Reference: CIwQuat

Airplay API Reference > Data Structures > CIwQuat >

CIwQuat Class Reference
[IwGeomQuat]

#include <IwGeomQuat.h>

Public Member Functions

CIwQuat (CIwVec3 const &v, iwqangle theta)
CIwQuat (iwqfixed s)
CIwQuat (CIwMat const &mat)
CIwQuat (iwqfixed s, iwqfixed x, iwqfixed y, iwqfixed z)
CIwQuat ()
iwqfixed | GetLength () const
iwqfixed | GetLengthSquared () const
iwqangle GetRotationAngle ()
CIwVec3 GetRotationAxis ()
void | Lerp (const CIwQuat &startQ, const CIwQuat &endQ, iwfixed const t)
CIwQuat & NormaliseInPlace ()
CIwQuat | operator * (iwqfixed const l) const
CIwQuat | operator * (CIwQuat const &q) const
operator CIwMat () const
bool | operator!= (CIwQuat const &q) const
CIwQuat | operator+ (CIwQuat const &q) const
CIwQuat | operator- (CIwQuat const &q) const
CIwQuat | operator- () const
CIwQuat | operator<< (const int c) const
CIwQuat & | operator= (CIwQuat const &q)
bool | operator== (CIwQuat const &q) const
CIwQuat | operator>> (const int c) const
CIwVec3 | RotateVector (CIwVec3 const &v) const
void | Serialise ()
void | SetAxisAngle (iwqfixed x, iwqfixed y, iwqfixed z, iwqangle theta)
void | Slerp (const CIwQuat &startQ, const CIwQuat &endQ, iwfixed const t)

Data Fields

iwqfixed s

Static Public Attributes

static CIwQuat | g_Identity

Detailed Description

CIwQuat - Fixed-point quaternion with 32-bit components.

Constructor & Destructor Documentation

CIwQuat::CIwQuat ( ) [inline]

Creates a new quaternion with unit real compoent and zero imaginary component.

CIwQuat::CIwQuat | ( | iwqfixed | s,
 |  | iwqfixed | x,
 |  | iwqfixed | y,
 |  | iwqfixed | z |
 | ) |  |  | [inline]

Creates a new quaternion with supplied components.

Parameters:
s,x,y,z components to initialise quaternion

CIwQuat::CIwQuat ( CIwMat const & mat )

Creates a new quaternion representing the same rotation as the supplied matrix.

Parameters:
mat It is assumed the rotation part of the matrix is orthogonal (represents a spacial rotation).

CIwQuat::CIwQuat ( iwqfixed s ) [inline]

Creates a new quaternion with given real component and zero imaginary component.

Parameters:
s Real component.

CIwQuat::CIwQuat | ( | CIwVec3 const & | v,
 |  | iwqangle | theta |
 | ) |  |  | [inline]

Creates a new quaternion with the supplied axis and angle.

Parameters:
Axis | of rotation.
Angle | of rotation.

Member Function Documentation

iwqfixed CIwQuat::GetLength ( ) const

Calculates the quaternion's length.

Returns:
Square root of the quaternion's inner product with itself.

iwqfixed CIwQuat::GetLengthSquared ( ) const

Calculates the square of the quaternion's length.

Returns:
The inner product of the quaternion with itself.

iwqangle CIwQuat::GetRotationAngle ( ) [inline]

Gets the angle of rotation the quaternion represents.

Returns:
Twice the arccos of the real part of the quaternion.

CIwVec3 CIwQuat::GetRotationAxis ( ) [inline]

Gets a normalised eigenvector of the rotation the quaternion represents.

Returns:
Normalised imaginary part of quaternion.

void CIwQuat::Lerp | ( | const CIwQuat & | startQ,
 |  | const CIwQuat & | endQ,
 |  | iwfixed const | t
 | ) |  |

Linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

CIwQuat& CIwQuat::NormaliseInPlace ( ) [inline]

Scales quaternion so it has unit length.

Returns:
Reference to quaternion.

CIwQuat CIwQuat::operator * ( iwqfixed const l ) const [inline]

Scale operator.

CIwQuat CIwQuat::operator * ( CIwQuat const & q ) const [inline]

Calculates quaternion product.

Parameters:
q Quaternion with which to find product.
Returns:
quaternion representing the rotation by this quaternion and then by q.

CIwQuat::operator CIwMat ( ) const [inline]

Matrix operator.

Returns:
Matrix of rotation represented by this quaternion.

bool CIwQuat::operator!= ( CIwQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q Quaternion for comparison.
Returns:
False if components of quaternions are the same, otherwise true.

CIwQuat CIwQuat::operator+ ( CIwQuat const & q ) const [inline]

Sum operator.

Parameters:
q Quaternion to sum this quaternion with
Returns:
Quaternion with components that are the sum of the supplied quaternions.

CIwQuat CIwQuat::operator- ( CIwQuat const & q ) const [inline]

Difference operator.

Parameters:
q Quaternion to difference this quaternion with
Returns:
Quaternion with components that are the difference of the supplied quaternions.

CIwQuat CIwQuat::operator- ( ) const [inline]

Conjugates quaternion.

Returns:
A quaternion which represents the opposite rotation

CIwQuat CIwQuat::operator<< ( const int c ) const [inline]

Shifts components of quaternion.

Parameters:
c Component left shift.
Returns:
Quaternion with components shifted by given amount.

CIwQuat& CIwQuat::operator= ( CIwQuat const & q ) [inline]

Assignment operator.

Parameters:
q Quaternion from which to copy components.
Returns:
Reference to this quaternion.

bool CIwQuat::operator== ( CIwQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q quaternion for comparison
Returns:
true iff components of quaternions are the same

CIwQuat CIwQuat::operator>> ( const int c ) const [inline]

Shifts components of quaternion.

Parameters:
c Component right shift.
Returns:
Quaternion with components shifted by given amount.

CIwVec3 CIwQuat::RotateVector ( CIwVec3 const & v ) const [inline]

Parameters:
v Vector to rotate.
Returns:
Rotated vector.

void CIwQuat::Serialise ( void ) [inline]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise

void CIwQuat::SetAxisAngle | ( | iwqfixed | x,
 |  | iwqfixed | y,
 |  | iwqfixed | z,
 |  | iwqangle | theta
 | ) |  |

Sets quaternion representing the rotation around the supplied aixis by the supplied angle.

Parameters:
axis | Rotation axis - assumed to be normalised.
angle30 | Rotation angle, where IW_GEOM_QONE represents a rotation of 360 degrees.

void CIwQuat::Slerp | ( | const CIwQuat & | startQ,
 |  | const CIwQuat & | endQ,
 |  | iwfixed const | t
 | ) |  |

Spherical linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

Field Documentation

CIwQuat CIwQuat::g_Identity [static]

Identity unit quaternion.

iwqfixed CIwQuat::s

Quaternion components

The documentation for this class was generated from the following file:
  • IwGeomQuat.h


Airplay API Reference: CIwRect

Airplay API Reference > Data Structures > CIwRect >

CIwRect Class Reference
[IwGxTypes]

#include <IwGxTypes.h>

Public Member Functions

CIwRect (int16 _x, int16 _y, int16 _w, int16 _h)
CIwRect ()
void Make (int16 _x, int16 _y, int16 _w, int16 _h)

Detailed Description

General rectangle, 16-bit members.

Constructor & Destructor Documentation

CIwRect::CIwRect ( ) [inline]

Constructor.

Required Header Files
IwGxTypes.h

CIwRect::CIwRect | ( | int16 | _x,
 |  | int16 | _y,
 |  | int16 | _w,
 |  | int16 | _h |
 | ) |  |  | [inline]

Constructor.

Parameters:
_x | X coordinate.
_y | Y coordinate.
_w | Width.
_h | Height.
Required Header Files
IwGxTypes.h

Member Function Documentation

void CIwRect::Make | ( | int16 | _x,
 |  | int16 | _y,
 |  | int16 | _w,
 |  | int16 | _h |
 | ) |  |  | [inline]

Set all members.

Parameters:
_x | X coordinate.
_y | Y coordinate.
_w | Width.
_h | Height.
Required Header Files
IwGxTypes.h

Field Documentation

int16 CIwRect::h

height

int16 CIwRect::w

width

int16 CIwRect::x

x coordinate

int16 CIwRect::y

y coordinate

The documentation for this class was generated from the following file:
  • IwGxTypes.h


Airplay API Reference: CIwRect32

Airplay API Reference > Data Structures > CIwRect32 >

CIwRect32 Class Reference
[IwGxTypes]

#include <IwGxTypes.h>

Inheritance diagram for CIwRect32:

[legend]

Public Member Functions

CIwRect32 (int32 _x, int32 _y, int32 _w, int32 _h)
CIwRect32 ()
void Make (int32 _x, int32 _y, int32 _w, int32 _h)

Detailed Description

General rectangle, 32-bit members.

Constructor & Destructor Documentation

CIwRect32::CIwRect32 ( ) [inline]

Constructor.

Required Header Files
IwGxTypes.h

CIwRect32::CIwRect32 | ( | int32 | _x,
 |  | int32 | _y,
 |  | int32 | _w,
 |  | int32 | _h |
 | ) |  |  | [inline]

Constructor.

Parameters:
_x | X coordinate.
_y | Y coordinate.
_w | Width.
_h | Height.
Required Header Files
IwGxTypes.h

Member Function Documentation

void CIwRect32::Make | ( | int32 | _x,
 |  | int32 | _y,
 |  | int32 | _w,
 |  | int32 | _h |
 | ) |  |  | [inline]

Set all members.

Parameters:
_x | X coordinate.
_y | Y coordinate.
_w | Width.
_h | Height.
Required Header Files
IwGxTypes.h

Field Documentation

int32 CIwRect32::h

height

int32 CIwRect32::w

width

int32 CIwRect32::x

x coordinate

int32 CIwRect32::y

y coordinate

The documentation for this class was generated from the following file:
  • IwGxTypes.h


Airplay API Reference: CIwResGroup

Airplay API Reference > Data Structures > CIwResGroup >

CIwResGroup Class Reference
[IwResManager Groups]

#include <IwResGroup.h>

Inheritance diagram for CIwResGroup:

[legend]

Public Member Functions

void | AddChild (CIwResGroup *pGroup, bool toOwn=true)
void | AddRes (uint32 resTypeHash, CIwResource *pData)
void | AddRes (const char *resType, CIwResource *pData)
CIwResGroup (const char *name=NULL)
void | Finalise ()
const CIwManagedList & | GetChildren () const
CIwResList * | GetListHashed (uint32 resTypeHash, uint32 flags=0) const
CIwResList * | GetListNamed (const char *resType, uint32 flags=0) const
CIwResGroup * | GetOwner () const
CIwResource * | GetResHashed (uint32 hash, uint32 resTypeHash, uint32 flags=0, bool topLevel=true) const
CIwResource * | GetResHashed (uint32 hash, const char *resType, uint32 flags=0, bool topLevel=true) const
CIwResource * | GetResNamed (const char *name, const char *resType, uint32 flags=0) const
bool | IsShared () const
void | ReserveExtraChildren (int extra)
virtual void | Resolve ()
void | SetShared (bool shared)
void | Write ()

Data Structures

struct | CIwResRequest

Detailed Description

A resource group. Contains pointers to resources of different types. See the Groups module overview for more information.

CIwResGroup objects accept the following attributes in ITX files:
Attribute | Value | Description | Example
name | (string) | Group name | name "Group1"
shared | true or false | True if the group should be flagged as "shared". | shared true
useTemplate | (handler extension) (template name) | Switch a specified resource handler to use a specified resource template. | useTemplate "GEO" "Template1"
omitShared | true or false | True only if we do NOT want to build resources into GROUP.BIN files, if they already exist in a loaded shared group. | omitShared true
omitChildren | true or false | True only if we do NOT want to build resources into GROUP.BIN files, if they already exist in a loaded child group. | omitChildren true

Required Header Files
IwResGroup.h

Constructor & Destructor Documentation

CIwResGroup::CIwResGroup ( const char * name = NULL )

Creates an empty group.

Parameters:
name The name of the group.

Member Function Documentation

void CIwResGroup::AddChild | ( | CIwResGroup * | pGroup,
 |  | bool | toOwn = true
 | ) |  |

Adds a child group.

Parameters:
pGroup | Pointer to the child group you want to add.
toOwn | false only if we are not to own this child group. The default value is true.
Note:
By default, groups own their child groups. This is usually the desired behaviour.
Required Header Files
IwResGroup.h

void CIwResGroup::AddRes | ( | uint32 | resTypeHash,
 |  | CIwResource * | pData
 | ) |  |

Adds a resource to a specified list.

Parameters:
resTypeHash | The hashed string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE.
pData | Pointer to the resource you want to add.
See also:
GetResNamed, GetResHashed
Note:
If the group currently contains no resources of the specified type, a new resource list is created, named according to the resource type, and added to the group.
Required Header Files
IwResGroup.h

void CIwResGroup::AddRes | ( | const char * | resType,
 |  | CIwResource * | pData
 | ) |  |

Adds a resource to a specified list.

Parameters:
resType | The string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE.
pData | Pointer to the resource you want to add.
See also:
GetResNamed, GetResHashed
Note:
If the group currently contains no resources of the specified type, a new resource list is created, named according to the resource type, and added to the group.
Required Header Files
IwResGroup.h

void CIwResGroup::Finalise ( )

Finish reading from this mounted group. This will free up memory taken up by directories etc.

const CIwManagedList& CIwResGroup::GetChildren ( ) const [inline]

Get a reference to the group's list of child groups.

Returns:
A reference to the group's list of child groups.
Required Header Files
IwResGroup.h

CIwResList* CIwResGroup::GetListHashed | ( | uint32 | resTypeHash,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a pointer to a named resource list (i.e., a list of all resources of the named type).

Parameters:
resTypeHash | The hashed string corresponding to the resource type, for example IwHashString(IW_GX_RESTYPE_TEXTURE).
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource list, or NULL if no list exists of the specified type.
See also:
AddRes
Required Header Files
IwResGroup.h

CIwResList* CIwResGroup::GetListNamed | ( | const char * | resType,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a pointer to a named resource list (i.e., a list of all resources of the named type).

Parameters:
resType | The string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource list, or NULL if no list exists of the specified type.
See also:
AddRes
Required Header Files
IwResGroup.h

CIwResGroup* CIwResGroup::GetOwner ( ) const [inline]

Gets the group's owner.

Returns:
A pointer to the group's owner, or NULL if the group has no owner.
Required Header Files
IwResGroup.h

CIwResource* CIwResGroup::GetResHashed | ( | uint32 | hash,
 |  | uint32 | resTypeHash,
 |  | uint32 | flags = 0,
 |  | bool | topLevel = true |
 | ) |  |  | const

Gets a named resource of specified type.

Parameters:
hash | The hashed resource name to search for.
resTypeHash | The hashed string corresponding to the resource type, for example IW_GX_RESTYPE_TEXTURE.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource, or NULL if the named resource does not exist.
See also:
AddRes, GetResNamed
Note:
This function is identical to GetResNamed(), but accepts a hashed name rather than a string name.
Required Header Files
IwResGroup.h

CIwResource* CIwResGroup::GetResHashed | ( | uint32 | hash,
 |  | const char * | resType,
 |  | uint32 | flags = 0,
 |  | bool | topLevel = true |
 | ) |  |  | const

Gets a named resource of specified type.

Parameters:
hash | The hashed resource name to search for.
resType | The string corresponding to the resource type, for example, IwHashString(IW_GX_RESTYPE_TEXTURE). If NULL, will search all resource types.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource, or NULL if the named resource does not exist.
See also:
AddRes, GetResNamed
Note:
This function is identical to GetResNamed(), but accepts a hashed name rather than a string name.
Required Header Files
IwResGroup.h

CIwResource* CIwResGroup::GetResNamed | ( | const char * | name,
 |  | const char * | resType,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a named resource of specified type.

Parameters:
name | The resource name to search for.
resType | The string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE. If NULL, will search all resource types.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource, or NULL if the named resource does not exist.
See also:
AddRes, GetResHashed
Note:
This function is identical to GetResHashed(), but accepts a string name rather than a hashed name.
Required Header Files
IwResGroup.h

bool CIwResGroup::IsShared ( ) const [inline]

Returns the group's shared status.

Returns:
true only if the group is shared.
See also:
SetShared
Required Header Files
IwResGroup.h

void CIwResGroup::ReserveExtraChildren ( int extra ) [inline]

Expands the reserved size of the child array to allow at least the specified number of children to be added

virtual void CIwResGroup::Resolve ( ) [virtual]

Resolve resource references in this group. This will be done automatically on load unless MANUAL_RESOLVE_F is set in IwResManager

Reimplemented from CIwManaged.

void CIwResGroup::SetShared ( bool shared )

Sets the group's shared status.

Parameters:
shared true only if the group is to be shared.
See also:
IsShared
Note:
If a group is flagged as shared, then resource manager searches will also include this group. Resource manager searches can be set to explicitly ignore shared groups, by passing in the IW_RES_IGNORE_SHARED_F to the search function.
Required Header Files
IwResGroup.h

void CIwResGroup::Write ( )

Serialise the group to disk. The user should already have called IwSerialiseOpen() to open a binary file of the desired name. Afterwards, the user should call IwSerialiseClose().

Note:
This function sets this group as the "current group".

The documentation for this class was generated from the following file:
  • IwResGroup.h


Airplay API Reference: CIwResHandler

Airplay API Reference > Data Structures > CIwResHandler >

CIwResHandler Class Reference
[IwResManager Resource Handlers]

#include <IwResHandler.h>

Inheritance diagram for CIwResHandler:

[legend]

Public Member Functions

void | AddTemplate (CIwResTemplate *pTemplate)
void | ApplySettings ()
virtual CIwResource * | Build (const CIwStringL &pathname)=0
CIwResHandler (const char *ext, const char *resType)
void | ConstructFullPathname (CIwStringL &ret, const CIwStringL &pathonly, const CIwStringL &fileonly, const char *ext)
const char * | GetExt () const
const char * | GetResType () const
CIwResTemplate * | GetSettings () const
CIwResTemplate * | GetTemplate () const
CIwResTemplate * | GetTemplateNamed (const char *name) const
void | Reset ()
void | SetTemplate (const char *name)
void | SetTemplate (CIwResTemplate *pTemplate)

Detailed Description

Base class for a resource handler to load/process resource type from file extension. See the Handlers module overview for more information.

See also:
CIwResTemplate
Required Header Files
IwResHandler.h

Constructor & Destructor Documentation

CIwResHandler::CIwResHandler | ( | const char * | ext,
 |  | const char * | resType
 | ) |  |

Creates a new CIwResHandler.

Parameters:
ext | The extension(s) that this handler will be invoked for. Can be a string containing multiple extensions, e.g., "bmp tga gif".
resType | The type of constructed resources. Used when adding to resource groups etc.
See also:
CIwResManager::AddHandler
Note:
The application must add a CIwResHandler to the resource manager before it will be invoked.
Required Header Files
IwResHandler.h

Member Function Documentation

void CIwResHandler::AddTemplate ( CIwResTemplate * pTemplate ) [inline]

Add a template to the handler's internal list of templates. This template can then be selected in future using group "useTemplate" syntax or via SetTemplate.

Parameters:
pTemplate Template to add
See also:
SetTemplate
Required Header Files
IwResHandler.h

void CIwResHandler::ApplySettings ( ) [inline]

Apply the current settings of the handler. Typically the template will override Apply to prepare some settings in a builder singleton.

Required Header Files
IwResHandler.h

virtual CIwResource* CIwResHandler::Build ( const CIwStringL & pathname ) [pure virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implemented in CIwResHandlerMTL, CIwResHandlerGEO, CIwResHandlerANIM, CIwResHandlerSKEL, CIwResHandlerSKIN, CIwResHandlerGROUP, CIwResHandlerImage, and CIwResHandlerITX.

void CIwResHandler::ConstructFullPathname | ( | CIwStringL & | ret,
 |  | const CIwStringL & | pathonly,
 |  | const CIwStringL & | fileonly,
 |  | const char * | ext
 | ) |  |

Helper function to construct a full pathname from pieces. This is the inverse of CIwResManager::SplitPathName

Parameters:
ret | String to receive constructed path
pathonly | Path part of path
fileonly | Filename part of path
ext | File extension part of path
See also:
CIwResManager::SplitPathName
Required Header Files
IwResHandler.h

const char* CIwResHandler::GetExt ( ) const [inline]

Get extension(s) this handler should be invoked for.

Returns:
Extension(s) this handler should be invoked for.
Required Header Files
IwResHandler.h

const char* CIwResHandler::GetResType ( ) const [inline]

Get asset type name associated with this handler.

Returns:
Asset type name associated with this handler.
Required Header Files
IwResHandler.h

CIwResTemplate* CIwResHandler::GetSettings ( ) const [inline]

Get current settings

Returns:
A pointer to the template that contains the current settings.
Required Header Files
IwResHandler.h

CIwResTemplate* CIwResHandler::GetTemplate ( ) const [inline]

Get the current template. This contains the settings that the handler's settings will be based on.

Returns:
The current template
Required Header Files
IwResHandler.h

CIwResTemplate* CIwResHandler::GetTemplateNamed ( const char * name ) const [inline]

Get a named template

Parameters:
name Name of template to return
Returns:
A template from the internal list.
Required Header Files
IwResHandler.h

void CIwResHandler::Reset ( )

Called prior to each resource's construction. Restores the most recently specified template's settings (or does nothing if no templates are used).

Required Header Files
IwResHandler.h

void CIwResHandler::SetTemplate ( const char * name ) [inline]

Select a template from the internal list (m_Templates) to be the current template.

Parameters:
name Name of template to use.
Required Header Files
IwResHandler.h

void CIwResHandler::SetTemplate ( CIwResTemplate * pTemplate ) [inline]

Set the current template (and copy to handler's settings).

Parameters:
pTemplate Template to make current.
Required Header Files
IwResHandler.h

Field Documentation

const char* CIwResHandler::m_Ext [protected]

File extension which uses this handler.

const char* CIwResHandler::m_ResType [protected]

Resource type name to create.

CIwResTemplate* CIwResHandler::m_Settings [protected]

Current settings.

CIwResTemplate* CIwResHandler::m_TemplateCurr [protected]

Current template.

CIwResTemplate* CIwResHandler::m_TemplateInit [protected]

Default template.

CIwManagedList CIwResHandler::m_Templates [protected]

Owned list of all templates.

The documentation for this class was generated from the following file:
  • IwResHandler.h


Airplay API Reference: CIwResHandlerANIM

Airplay API Reference > Data Structures > CIwResHandlerANIM >

CIwResHandlerANIM Class Reference
[IwResHandler]

#include <IwResHandlerANIM.h>

Inheritance diagram for CIwResHandlerANIM:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for ANIM files. This handler is used whenever a pathname to a file with extension ".ANIM" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerANIM.h

Member Function Documentation

virtual CIwResource* CIwResHandlerANIM::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerANIM.h


Airplay API Reference: CIwResHandlerGEO

Airplay API Reference > Data Structures > CIwResHandlerGEO >

CIwResHandlerGEO Class Reference
[GEO file helpers]

#include <IwResHandlerGEO.h>

Inheritance diagram for CIwResHandlerGEO:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for GEO files. This handler is used whenever a pathname to a file with extension ".GEO" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerGEO.h

Member Function Documentation

virtual CIwResource* CIwResHandlerGEO::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerGEO.h


Airplay API Reference: CIwResHandlerGROUP

Airplay API Reference > Data Structures > CIwResHandlerGROUP >

CIwResHandlerGROUP Class Reference
[IwResManager API Reference]

#include <IwResHandlerGROUP.h>

Inheritance diagram for CIwResHandlerGROUP:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for GROUP files. This handler is used whenever a pathname to a file with extension ".GROUP" is specified within a GROUP file (i.e., we wish to load a "child" group).

Required Header Files
IwResHandlerGROUP.h

Member Function Documentation

virtual CIwResource* CIwResHandlerGROUP::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerGROUP.h


Airplay API Reference: CIwResHandlerImage

Airplay API Reference > Data Structures > CIwResHandlerImage >

CIwResHandlerImage Class Reference
[IwResManager API Reference]

#include <IwResHandlerImage.h>

Inheritance diagram for CIwResHandlerImage:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for image files. This handler is used whenever a pathname to a file with extension ".BMP", ".GIF", ".PNG" or ".TGA" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerImage.h

Member Function Documentation

virtual CIwResource* CIwResHandlerImage::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerImage.h


Airplay API Reference: CIwResHandlerITX

Airplay API Reference > Data Structures > CIwResHandlerITX >

CIwResHandlerITX Class Reference
[IwResManager API Reference]

#include <IwResHandlerITX.h>

Inheritance diagram for CIwResHandlerITX:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for ITX files. This handler is used whenever a pathname to a file with extension ".ITX" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerITX.h

Member Function Documentation

virtual CIwResource* CIwResHandlerITX::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerITX.h


Airplay API Reference: CIwResHandlerMTL

Airplay API Reference > Data Structures > CIwResHandlerMTL >

CIwResHandlerMTL Class Reference

#include <IwResHandlerMTL.h>

Inheritance diagram for CIwResHandlerMTL:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for MTL files. This handler is used whenever a pathname to a file with extension ".MTL" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerMTL.h

Member Function Documentation

virtual CIwResource* CIwResHandlerMTL::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerMTL.h


Airplay API Reference: CIwResHandlerSKEL

Airplay API Reference > Data Structures > CIwResHandlerSKEL >

CIwResHandlerSKEL Class Reference
[IwResHandler]

#include <IwResHandlerSKEL.h>

Inheritance diagram for CIwResHandlerSKEL:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for SKEL files. This handler is used whenever a pathname to a file with extension ".SKEL" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerSKEL.h

Member Function Documentation

virtual CIwResource* CIwResHandlerSKEL::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerSKEL.h


Airplay API Reference: CIwResHandlerSKIN

Airplay API Reference > Data Structures > CIwResHandlerSKIN >

CIwResHandlerSKIN Class Reference
[IwResHandler]

#include <IwResHandlerSKIN.h>

Inheritance diagram for CIwResHandlerSKIN:

[legend]

Public Member Functions

virtual CIwResource * Build (const CIwStringL &pathname)

Detailed Description

Resource handler for SKIN files. This handler is used whenever a pathname to a file with extension ".SKIN" is specified within a GROUP file. See the Resource Handlers module overview for more information.

Required Header Files
IwResHandlerSKIN.h

Member Function Documentation

virtual CIwResource* CIwResHandlerSKIN::Build ( const CIwStringL & pathname ) [virtual]

Build binary resource from the specified file. If the resource is not named when it is returned, resource manager will name it after the file - e.g., "/files/lava.geo" will be named "lava".

Parameters:
pathname The path to the source file, e.g., "/files/lava.geo".
Returns:
The CIwResource that was constructed. It will be added to the current group, and serialised with it. If the handler did not construct a resource (or is passing ownership to some other object) it can return NULL.
Required Header Files
IwResHandler.h

Implements CIwResHandler.

The documentation for this class was generated from the following file:
  • IwResHandlerSKIN.h


Airplay API Reference: CIwResList

Airplay API Reference > Data Structures > CIwResList >

CIwResList Class Reference
[IwResManager Groups]

#include <IwResGroup.h>

Inheritance diagram for CIwResList:

[legend]

Public Member Functions

virtual void | Serialise ()

Data Structures

struct | CIwGroupDirectoryEntry

Detailed Description

List of resources of a specified type. See the Groups module overview for more information.

Required Header Files
IwResGroup.h

Member Function Documentation

virtual void CIwResList::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

Field Documentation

CIwManagedList CIwResList::m_Resources

All the resources in the list.

The documentation for this class was generated from the following file:
  • IwResGroup.h


Airplay API Reference: CIwResManager

Airplay API Reference > Data Structures > CIwResManager >

CIwResManager Class Reference
[Resource Manager Singleton]

#include <IwResManagerClass.h>

Public Types

typedef void(* | BuildGroupCallbackPost )(void)
typedef void(* | BuildGroupCallbackPre )(void)
enum | GlobalMode

Public Member Functions

void | AddGroup (CIwResGroup *pGroup)
void | AddHandler (CIwResHandler *pHandler)
void | AddRes (const char *resType, CIwResource *pData)
CIwResGroup::ArrayIt | DestroyGroup (CIwResGroup *pGroup)
CIwResGroup::ArrayIt | DestroyGroup (const char *groupname)
CIwMaterial * | GetAtlasMaterial (CIwMaterial *pMaterial, CIwRect &outUVRect)
CIwStringL | GetBuildStyleCurrName () const
CIwResGroup * | GetCurrentGroup () const
CIwResGroup * | GetGroup (uint32 index) const
CIwResGroup * | GetGroupHashed (uint32 hash, uint32 flags=0) const
CIwResGroup * | GetGroupNamed (const char *groupname, uint32 flags=0) const
CIwResHandler * | GetHandler (const char *ext, uint32 flags=0) const
CIwResGroup * | GetLastSearchGroup () const
GlobalMode | GetMode () const
uint32 | GetNumGroups () const
CIwResource * | GetResHashed (uint32 hash, const char *resType, uint32 flags=0) const
CIwResource * | GetResNamed (const char *resName, const char *resType, uint32 flags=0) const
const char * | GetResType (const char *ext, uint32 flags=0) const
CIwResGroup * | LoadGroup (const char *pathname, bool allowNonExist=false)
CIwResGroup * | LoadGroupFromMemory (const uint8 *buffer, uint32 length)
CIwResGroup * | MountGroup (const char *pathname, bool allowNonExist=false)
void | RemoveHandler (const char *classname)
void | ReserveGroups (int numGroups)
void | ReserveHandlers (int numHandlers)
void | ResolveResPtr (CIwManaged *&pData, const char *resType)
void | SerialiseResPtr (CIwManaged *&pData, const char *resType, bool resolveNow=true)
void | SetBuildGroupCallbackPost (BuildGroupCallbackPost fn)
void | SetBuildGroupCallbackPre (BuildGroupCallbackPre fn)
void | SetBuildStyle (const char *name)
void | SetCurrentGroup (CIwResGroup *pGroup)
void | SetMode (GlobalMode mode)
void | SplitPathName (const char *pathname, CIwStringL &pathonly, CIwStringL &fileonly, CIwStringS &ext)

Friends

void | IwResManagerInit ()
void | IwResManagerTerminate ()

Detailed Description

The resource manager singleton. See the Resource Manager Modes module overview for more information.

Required Header Files
IwResManagerClass.h

Member Typedef Documentation

typedef void(* CIwResManager::BuildGroupCallbackPost)(void)

Typedef for callback function called after loading a GROUP file in BUILD mode.

Required Header Files
IwResManagerClass.h

typedef void(* CIwResManager::BuildGroupCallbackPre)(void)

Typedef for callback function called before loading a GROUP file in BUILD mode.

Required Header Files
IwResManagerClass.h

Member Enumeration Documentation

anonymous enum

Enumerator:
DONT_SERIALISE_BLOCK_SIZES_F | Do not serialise a block size in res lists.
DONT_LOAD_CHILD_GROUPS_F | Do not load child groups.
OPTIMISE_INCLUDE_UNUSED_RES_F | include unused resources in optimised mounted groups
OPTIMISE_MOUNTED_BINARIES_F | optimised mounted groups on resmanager destructor

enum CIwResManager::GlobalMode

Global modes.

Enumerator:
MODE_BUILD | Resource manager will build binary files from source assets, then load binary files.
MODE_LOAD | Resource manager will ignore source assets and simply load binary files.

Member Function Documentation

void CIwResManager::AddGroup ( CIwResGroup * pGroup )

Adds a resource group to the resource manager.

Parameters:
pGroup Pointer to the resource group you want to add.
See also:
DestroyGroup, GetGroupNamed, GetNumGroups
Required Header Files
IwResManagerClass.h

void CIwResManager::AddHandler ( CIwResHandler * pHandler )

Adds a resource handler to the manager.

Parameters:
pHandler Pointer to the resource handler you want to add.
Note:
The resource manager singleton must be configured by the user to handle specific resource types. This is done by adding handlers to the resource manager. The following resource handlers are provided by the IwGx module:
  • CIwResHandlerImage: reads BMP, GIF, TGA and PNG files, and creates CIwTexture resources (type IW_GX_RESTYPE_TEXTURE) for each.
  • CIwResHandlerMTL: reads MTL files, and creates CIwMaterial resources (type IW_GX_RESTYPE_MATERIAL) for each.
  • CIwResHandlerGROUP: reads GROUP files, and creates CIwResGroup objects.
  • CIwResHandlerITX: reads ITX files.
The CIwResManager singleton constructor automatically adds the Image, MTL, GROUP and ITX handlers for you.

The resource manager owns its handlers, so the user does not need to destroy them.

void CIwResManager::AddRes | ( | const char * | resType,
 |  | CIwResource * | pData
 | ) |  |

Adds a resource to the specified list of the current group. A current group must have been set, either by parsing a GROUP flie, or by calling SetCurrentGroup().

Parameters:
resType | The string corresponding to the resource type, for example IW_GX_RESTYPE_TEXTURE.
pData | Pointer to the resource to add.
See also:
GetResNamed, GetResHashed
Note:
If the current group contains no resources of the specified type, a new resource list is created, named according to the resource type, and added to the group.

CIwResGroup::ArrayIt CIwResManager::DestroyGroup ( CIwResGroup * pGroup )

Destroys a group and all its resources.

Parameters:
pGroup Pointer to the group you want to destroy.
Returns:
Returns an iterator to the subsequent group in the resource manager's group list.
See also:
AddGroup, GetGroupNamed, GetNumGroups

CIwResGroup::ArrayIt CIwResManager::DestroyGroup ( const char * groupname )

Destroys a named group and all its resources.

Parameters:
groupname Name of the group to destroy.
Returns:
Returns an iterator to the subsequent group in the resource manager's group list.
See also:
AddGroup, GetGroupNamed, GetNumGroups

CIwMaterial* CIwResManager::GetAtlasMaterial | ( | CIwMaterial * | pMaterial,
 |  | CIwRect & | outUVRect
 | ) |  |

Determine whether the passed material ended up in an atlas and return the dimensions of the sub-texture that need to be applied.

Parameters:
pMaterial | Pointer to material to resolve
outUVRect | Will be set to the UV rectangle of the texture. To convert full texture UVs to atlas UVs multiply the UV by (w,h) of the returned rectangle and add (x,y). The corresponding atlas material (NULL if the material was not atlassed)
Required Header Files
IwResManagerClass.h

CIwStringL CIwResManager::GetBuildStyleCurrName ( ) const

Get the current build style. The name of the current build style.

Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::GetCurrentGroup ( ) const [inline]

Gets the current group.

Returns:
A pointer to the current group.
See also:
SetCurrentGroup, AddRes
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::GetGroup ( uint32 index ) const

Gets a group by index.

Parameters:
index The index of the group within the resource manager.
Returns:
Pointer to the group.
Note:
An assertion will occur if the index is greater than or equal to the number of groups in the manager.
See also:
GetNumGroups
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::GetGroupHashed | ( | uint32 | hash,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Finds a named group.

Parameters:
hash | The hashed name of the group you want to find.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
Pointer to the named group, or NULL if the named group does not exist.
Note:
This function is identical to GetGroupNamed(), but accepts a hashed name rather than a string name.
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::GetGroupNamed | ( | const char * | groupname,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Finds a named group.

Parameters:
groupname | The name of the group you want to find.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
Pointer to the named group, or NULL if the named group does not exist.
Note:
This function is identical to GetGroupHashed(), but accepts a string name rather than a hashed name.
Required Header Files
IwResManagerClass.h

CIwResHandler* CIwResManager::GetHandler | ( | const char * | ext,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a resource handler, by specifying the associated file extension.

Parameters:
ext | The file extension string associated with the handler.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
Pointer to the handler, or NULL if the handler does not exist.
See also:
AddHandler
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::GetLastSearchGroup ( ) const

Gets the group involved in the last resource search (if the last resource search was successful, returns a pointer to the group where the resource was found; otherwise, it returns NULL).

Returns:
A pointer to the group involved in the last resource search.
Required Header Files
IwResManagerClass.h

GlobalMode CIwResManager::GetMode ( ) const [inline]

Gets the resource manager global mode.

Returns:
MODE_BUILD or MODE_LOAD. For more information on build mode and load mode, see @ ref resourceManagerModes "Resource Manager Modes".
Required Header Files
IwResManagerClass.h

uint32 CIwResManager::GetNumGroups ( ) const

Gets the number of groups in the manager.

Returns:
The number of groups in the manager.
Required Header Files
IwResManagerClass.h

CIwResource* CIwResManager::GetResHashed | ( | uint32 | hash,
 |  | const char * | resType,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a named resource of specified type.

Parameters:
hash | The hashed resource name to search for.
resType | The string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource, or NULL if the named resource does not exist.
See also:
GetResNamed
Note:
This function is identical to GetResNamed(), but accepts a hashed name rather than a string name.

CIwResource* CIwResManager::GetResNamed | ( | const char * | resName,
 |  | const char * | resType,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets a named resource of specified type.

Parameters:
name | The resource name to search for.
resType | The string corresponding to the resource type, for example, IW_GX_RESTYPE_TEXTURE.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
A pointer to the named resource, or NULL if the named resource does not exist.
See also:
GetResHashed
Note:
This function is identical to GetResHashed(), but accepts a string name rather than a hashed name.
Required Header Files
IwResManagerClass.h

const char* CIwResManager::GetResType | ( | const char * | ext,
 |  | uint32 | flags = 0 |
 | ) |  |  | const

Gets the resource type associated with a file extension.

Parameters:
ext | The file extension associated with the resource type.
flags | IwGxResManagerFlags used to tailor the search, or 0 by default.
Returns:
The resource type string, or NULL if the file extension does not have an associated handler.
See also:
GetHandler
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::LoadGroup | ( | const char * | pathname,
 |  | bool | allowNonExist = false
 | ) |  |

Loads a resource group from a file. For more information on build mode and load mode, see @ ref resourceManagerModes "Resource Manager Modes".

Parameters:
pathname | Pathname to GROUP text file to load.
allowNonExist | true only if we wish to permit the non-existence of the GROUP file. Defaults to false.
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::LoadGroupFromMemory | ( | const uint8 * | buffer,
 |  | uint32 | length
 | ) |  |

Loads a resource group from a memory buffer.

Parameters:
buffer | Pointer to buffer to read from.
length | Length of buffer
Note:
The buffer must contain a binary representation of a resource group. Source assets must be converted to binaries via LoadGroup to generate binaries.
Required Header Files
IwResManagerClass.h

CIwResGroup* CIwResManager::MountGroup | ( | const char * | pathname,
 |  | bool | allowNonExist = false
 | ) |  |

Mounts a resource group from a file. For more information on build mode and load mode, see @ ref resourceManagerModes "Resource Manager Modes".

Parameters:
pathname | Pathname to GROUP text file to load.
allowNonExist | true only if we wish to permit the non-existence of the GROUP file. Defaults to false.
Required Header Files
IwResManagerClass.h

void CIwResManager::RemoveHandler ( const char * classname )

Removes a resource handler from the manager.

Parameters:
pHandler Pointer to the resource handler you want to remove.
The resource manager owns its handlers, so the user does not need to destroy them.

void CIwResManager::ReserveGroups ( int numGroups )

Reserves space in the resource manager for a specified maximum number of groups.

Parameters:
numGroups The number of groups to reserve space for.
Note:
It is not required that this function is called, but reserving space in this way can lead to less memory fragmentation as multiple groups are added to the manager.
See also:
AddGroup
Required Header Files
IwResManagerClass.h

void CIwResManager::ReserveHandlers ( int numHandlers )

Reserves space in the resource manager for a specified maximum number of resource handlers.

Parameters:
numHandlers The number of handlers to reserve space for.
Note:
It is not required that this function is called, but reserving space in this way can lead to less memory fragmentation as multiple handlers are added to the manager.
See also:
AddHandler
Required Header Files
IwResManagerClass.h

void CIwResManager::ResolveResPtr | ( | CIwManaged *& | pData,
 |  | const char * | resType
 | ) |  |

Resolves resource ptr previously serialised with SerialiseResPtr

Note:
This function will cause an assertion if the hashed instance name cannot be resolved to a loaded resource.
Parameters:
pData | Reference to the CIwManaged* pointer to resolve.
resType | Resource type name, e.g. IW_GX_RESTYPE_TEXTURE.
Required Header Files
IwResManagerClass.h

void CIwResManager::SerialiseResPtr | ( | CIwManaged *& | pData,
 |  | const char * | resType,
 |  | bool | resolveNow = true
 | ) |  |

Serialises resource ptr to/from hash name. When writing binary files, the managed object's hashed instance name will be written. When reading binary files, the hashed instance name will be read, and, if the resolveNow flag is set, the resource manager will be searched for a resource of the specified name and type. The pointer is then set to that resource. If the resolveNow flag is false, the pointer may be resolve manually at a later point via the ResolveResPtr method

Note:
This function will cause an assertion if, when reading, the resolveNow flag is set, and the hashed instance name cannot be resolved to a loaded resource.
Parameters:
pData | Reference to the CIwManaged* pointer to serialise.
resType | Resource type name, e.g. IW_GX_RESTYPE_TEXTURE.
resolveNow | If true, resolve the resource ptr immediately

void CIwResManager::SetBuildGroupCallbackPost ( BuildGroupCallbackPost fn )

Sets the callback called after loading a GROUP file, when in BUILD mode.

Parameters:
fn The function callback.
Required Header Files
IwResManagerClass.h

void CIwResManager::SetBuildGroupCallbackPre ( BuildGroupCallbackPre fn )

Sets the callback called before loading a GROUP file, when in BUILD mode.

Parameters:
fn The function callback.
Required Header Files
IwResManagerClass.h

void CIwResManager::SetBuildStyle ( const char * name )

Set the current build style. In resource building mode the build style must be a standard build style or one of the styles specified in resbuildstyles.itx. In resource loading mode this only modifies the search path to include "data-name".

Parameters:
name The name of the new build style.
Required Header Files
IwResManagerClass.h

void CIwResManager::SetCurrentGroup ( CIwResGroup * pGroup ) [inline]

Sets the current group.

Parameters:
pGroup The group to set as the current group.
See also:
GetCurrentGroup, AddRes
Required Header Files
IwResManagerClass.h

void CIwResManager::SetMode ( GlobalMode mode ) [inline]

Sets the resource manager global mode.

Parameters:
mode MODE_BUILD or MODE_LOAD. For more information on build mode and load mode, see @ ref resourceManagerModes "Resource Manager Modes".
Required Header Files
IwResManagerClass.h

void CIwResManager::SplitPathName | ( | const char * | pathname,
 |  | CIwStringL & | pathonly,
 |  | CIwStringL & | fileonly,
 |  | CIwStringS & | ext
 | ) |  |

Separates a pathname string into path (folder) string, filename string, and file extension string.

Parameters:
pathname | The full pathname string.
pathonly | String object into which the path (folder) string is written.
fileonly | String object into which the filename string is written.
pathonly | String object into which the file extension string is written.
Note:
For example:
 const char* pathname = "./models/level0/sky.bmp";
 CIwStringL pathonly;
 CIwStringS fileonly, ext;
 IwGetResManager()->SplitPathName(pathname, pathonly, fileonly, ext);
Would result in:
pathonly = "./models/level0"
fileonly = "sky"
ext = "bmp"

Friends And Related Function Documentation

void IwResManagerInit ( ) [friend]

Initialises all core functionality for IwResManager. This function must be called before IwResManager is used.

See also:
IwResManagerTerminate
Required Header Files
IwResManager.h

void IwResManagerTerminate ( ) [friend]

Shuts down IwResManager and frees all memory.

See also:
IwResManagerInit
Required Header Files
IwResManagerClass.h

The documentation for this class was generated from the following file:
  • IwResManagerClass.h


Airplay API Reference: CIwResTemplate

Airplay API Reference > Data Structures > CIwResTemplate >

CIwResTemplate Class Reference
[IwResManager Resource Handlers]

#include <IwResHandler.h>

Inheritance diagram for CIwResTemplate:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)=0
const char * | GetResName () const
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | Reset ()

Detailed Description

Base class for handler templates.

A template provides a set of attributes that control the binary generation process. For example, a template might specify that a model should be scaled by 2 when its binary is generated.

Templates provide a hook Apply to apply these settings to a builder object (typically a singleton) or the template can be used directly from CIwResHandler::Build.

Templates can be specified in data in two ways:

  • Explictly in the 'root' block of any itx file (typically all templates will be in one itx file that is parsed before any other resources). The default implementation of ParseClose will add any template instantiated in this way to the appropriate handler identified by GetResExt(). The current template in use by the handler can then be selected within a group using "useTemplate". For example, in resource_templates.itx:

     CIwResTemplateGEO
 {
    name "big"
    scale 2.0
 }

    in level.group:

     CIwResGroup
 {
        useTemplate "geo" "big"
        "/files/lava.geo"
 }
  • On a per resource basis using a bracketed scope after the resource path. This is done in the following way:

     CIwResGroup
 {
        "/files/lava.geo" { scale 2.0 }
 }

    In this case no template is instantiated - the resource handler's m_Settings will be set to a copy of m_TemplateCurr (or m_TemplateInit if no current template is set) and ParseAttribute calls to that m_Settings template will be generated from the bracketed scope. In this case ParseClose should not add itself to the handler.

Note:
See the IwResManager Resource Handlers module overview for more information.
See also:
CIwResGroup, CIwResHandler
Required Header Files
IwResHandler.h

Member Function Documentation

virtual void CIwResTemplate::Apply ( ) [inline, virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented in CIwResTemplateMTL, CIwResTemplateANIM, CIwResTemplateSKEL, CIwResTemplateSKIN, CIwResTemplateGROUP, and CIwResTemplateImage.

virtual void CIwResTemplate::Copy ( CIwResTemplate * pSource ) [pure virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implemented in CIwResTemplateMTL, CIwResTemplateANIM, CIwResTemplateSKEL, CIwResTemplateSKIN, CIwResTemplateGROUP, and CIwResTemplateImage.

const char* CIwResTemplate::GetResName ( ) const [inline]

Get the current resource name (if any).

Returns:
Current resource name (if any).
Required Header Files
IwResHandler.h

virtual bool CIwResTemplate::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwManaged.

Reimplemented in CIwResTemplateMTL, CIwResTemplateGEO, CIwResTemplateANIM, CIwResTemplateSKEL, CIwResTemplateSKIN, CIwResTemplateGROUP, and CIwResTemplateImage.

virtual void CIwResTemplate::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Override of standard CIwManaged::ParseClose. If this object is at the top of the parse object stack (i.e., it is in the "root" of an itx file) it will add itself to the handler for GetResExt() files, ready to be selected using "useTemplate" group command.

Parameters:
pParser The parser instance to use.
Required Header Files
IwResHandler.h

Reimplemented from CIwManaged.

virtual void CIwResTemplate::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented in CIwResTemplateMTL, CIwResTemplateGEO, CIwResTemplateANIM, CIwResTemplateSKEL, CIwResTemplateSKIN, CIwResTemplateGROUP, and CIwResTemplateImage.

Field Documentation

CIwStringS CIwResTemplate::m_ResName

Resource instance name.

The documentation for this class was generated from the following file:
  • IwResHandler.h


Airplay API Reference: CIwResTemplateANIM

Airplay API Reference > Data Structures > CIwResTemplateANIM >

CIwResTemplateANIM Class Reference
[IwResHandler]

#include <IwResHandlerANIM.h>

Inheritance diagram for CIwResTemplateANIM:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for ANIM files.

See the Resource Templates module overview for more information.

CIwResTemplateANIM objects accept the following attributes in ITX files:
Attribute | Value | Description | Default value | Example
zeroMotionTolerance | float | A tolerance value for dropping the translation part of a keyframe transform. This can result in significantly smaller data if small translations have been widely added by accident. | All translations are retained (0.0) | zeroMotionTolerance 1.0
transformPrecision | float | The transformPrecision of the animation. This allows animations to be carried out at a higher precision than worldspace. | Transforms are carried out at 4x worldspace | transformPrecision 8.0

Member Function Documentation

virtual void CIwResTemplateANIM::Apply ( ) [virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateANIM::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateANIM::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateANIM::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerANIM.h


Airplay API Reference: CIwResTemplateGEO

Airplay API Reference > Data Structures > CIwResTemplateGEO >

CIwResTemplateGEO Class Reference
[GEO file helpers]

#include <IwResHandlerGEO.h>

Inheritance diagram for CIwResTemplateGEO:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for GEO files. Associated with the CIwResHandlerGEO resource handler. See the Resource Templates module overview for more information.

CIwResTemplateGEO objects accept the following attributes in ITX files:
Attribute | Value | Description | Default value | Example
scale | float | Scale the model's vertices. | 1.0 | scale 1.0
buildNorms | true or false | Build vertex normals into the model (if they exist). | true | buildNorms false
buildCols | true or false | Build vertex colours into the model (if they exist). | true | buildCols false
buildUVs | true or false | Build texture coordinates (set 0) into the model (if they exist). | true | buildUVs false
buildUV1s | true or false | Build texture coordinates (set 1) into the model (if they exist). | true | buildUVs1 false
reverseWindingOrder | true or false | Reverse winding order of all faces. | true | reverseWindingOrder false
reverseNorms | true or false | Reverse the direction of all vertex normals. | false | reverseNorms true
triStrip | true or false | If model is NOT being optimised for SW rasterisation, this determines whether model blocks will be built to contain tri-lists or tri-strips. | false | triStrip true
verts2D | true or false | If true, build vertex block to submit vertex stream in viewspace (i.e. model will be "billboarded" to the camera). Note that the verts2D attribute will only come into effect if the model is exported with the appropriate transform type setting | false | verts2D true
convertColsToGreyscale | true or false | If true, all vertex colours will be converted to a greyscale value, determined using r = b = g = (MAX(r, g, b) + MIN(r, g, b) / 2. | false | convertColsToGreyscale true
calculateNorms | true or false | If true, vertex normals will be re-calculated from the model vertex positions and connectivity. | false | calculateNorms true
userString | (string) | Specify a user string which can be read by any custom model building process. | "" | userString "CustomModel"
chunked | true or false | If true, model will be "chunked" into discrete sub-models. A binary space partioning is used, until "leaf" sub-models have less than a specified number of primitives (tris or quads). | false | chunked true
maxPrimsPerChunk | 1 .. n | If model is "chunked", this sets the maximum number of primitives (tris or quads) per chunk. | 80 | maxPrimsPerChunk 200
supportLightingSW | true or false | False only if the model will never be rendered using the SW lighting pipeline. | true | supportLightingSW false
discardMutableSourceVerts | true or false | Indicates whether to keep the vertices from the GEO file for a mutable model. If the model will never be rendered without its vertices overridden these can be safely discarded for a smaller data set. | false | discardMutableSourceVerts true
discardMutableSourceLighting | true or false | Indicates whether to keep the vertex colours from the GEO file for a mutable model. If the model will never be rendered without its colours overridden these can be safely discarded for a smaller data set. | false | discardMutableSourceLighting true
discardMutableSourceNormals | true or false | Indicates whether to keep the normals from the GEO file for a mutable model. If the model will never be rendered without its normals overridden these can be safely discarded for a smaller data set. | false | discardMutableSourceNormals true
discardMutableSourceUV0s | true or false | Indicates whether to keep the UV0s from the GEO file for a mutable model. If the model will never be rendered without its UV0s overridden these can be safely discarded for a smaller data set. | false | discardMutableSourceUV0s true
discardMutableSourceUV1s | true or false | Indicates whether to keep the UV1s from the GEO file for a mutable model. If the model will never be rendered without its UV1s overridden these can be safely discarded for a smaller data set. | false | discardMutableSourceUV1s true
ignoreMutableVerts | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableVerts true
ignoreMutableLighting | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableLighting true
ignoreMutableNormals | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableNormals true
ignoreMutableFaces | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableFaces true
ignoreMutableUV0s | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableUV0s true
ignoreMutableUV1s | true or false | Disable mutability for models. When this setting is true, no models will ever be mutable. The default is that the mutability specified in the GEO file is respected. | false | ignoreMutableUV1s true
serialiseColours565 | true or false | Serialise the model's colours in 565 format. This can produce significantly smaller assets with little decrease in visual quality. Note that greyscaled colours will always be detected and serialised in a compact format. | false | serialiseColours565 true
combineThresholdColour | float | Allow model builder to combine multiple vertex colour entries into a single colour entry if all components are within this threshold of each other. Combining vertex attributes can improve rendering performance at the cost of fidelity to the source asset. | 0.0 (no combine) | combineThresholdColour 0.1
combineThresholdNormal | float | Allow model builder to combine multiple vertex normal entries into a single normal entry if all components are within this threshold of each other. Combining vertex attributes can improve rendering performance at the cost of fidelity to the source asset. | 0.0 (no combine) | combineThresholdNormal 0.1
stripMajorOrdering | true or false | Optimise vertex and index streams in strip major order. This is recommended for img platforms. However, it can be somewhat slow. | false | stripMajorOrdering true

combineThresholdUV

float

Allow model builder to combine multiple vertex UV entries into a single UV entry if all components are within this threshold of each other. Combining vertex attributes can improve rendering performance at the cost of fidelity to the source asset.

0.0 (no combine)

combineThresholdUV 0.01

mergeIdenticalMaterials

true or false

Merge materials with identical properties (texture, blend mode, etc.) into a single material. This can significantly improve rendering performance. It can be disabled if materials are required to remain distinct for the application's use (for example, it uses material overrides).

true

mergeIdenticalMaterials false

Required Header Files
IwResHandlerGEO.h

Member Function Documentation

virtual bool CIwResTemplateGEO::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateGEO::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerGEO.h


Airplay API Reference: CIwResTemplateGROUP

Airplay API Reference > Data Structures > CIwResTemplateGROUP >

CIwResTemplateGROUP Class Reference
[IwResManager API Reference]

#include <IwResHandlerGROUP.h>

Inheritance diagram for CIwResTemplateGROUP:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for group files. Associated with the CIwResHandlerGROUP resource handler. See the Resource Templates module overview for more information.

CIwResTemplateGROUP objects accept the following attributes in ITX files:
Attribute | Value | Description | Default value | Example
inline | true or false | If true, add all resources in groups governed by the template to their parent. Child groups added in this way do not produce seperate binary files. | false (child groups produce distinct binaries) | inline true
maxAtlasTargets | (max number of atlas targets) | If greater than zero textures within this group will be automatically atlassed. This parameter is the maximum number of atlasses that will be produced. Textures will be added to atlasses on a first-come basis. | 0 (no atlassing is performed) | maxAtlasTargets 10
maxAreaPerTexture | two component vector | When producing atlasses, restrict the area a single texture can consume. Note that atlassed textures may be tiled multiple times if models require it. | 0 0 (no restriction on are) | maxAreaPerTexture 256 256
excludeFromAtlas | (name of a texture resource) | When producing atlasses, exclude any materials referencing the specified texture from atlassing. Additional uses of this parameter will add to a list. | Empty list (all textures are atlassed if other requirements are met | excludeFromAtlas "myTroubleSomeTexture"
atlasPadding | (integer) | When producing atlasses, add padding between adjacent textures. Padding is required to allow atlasses to mipmap correctly. | 16 (16 pixels border added to textures) | atlasPadding 16
pageDimensions | two component vector | When producing atlasses, This is the maximum size of a texture atlas. | 1024,1024 | pageDimensions 2048 2048
atlasAllMaterials | (true or false) | When producing atlasses, this will control which materials are considered for atlassing. By default, only materials in Airplay Studio types (like GEOs) which automatically handle atlassing are added. If this parameter is true, all materials will be added. The client code should use CIwResManager::GetAtlasMaterial to fix up material and UV references. | false | atlasAllMaterials true

Required Header Files
IwResHandlerImage.h

Member Function Documentation

virtual void CIwResTemplateGROUP::Apply ( ) [inline, virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateGROUP::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateGROUP::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateGROUP::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

Field Documentation

bool CIwResTemplateGROUP::m_AtlasAllMaterials

Automatically add all materials to the atlas.

uint32 CIwResTemplateGROUP::m_AtlasPadding

Duplicate pixels around the edges of each texture for mipmapping.

CIwSVec2 CIwResTemplateGROUP::m_MaxAreaPerTexture

control auto tiling

uint32 CIwResTemplateGROUP::m_MaxAtlasTargets

Maximum number of atlas pages per batch.

CIwSVec2 CIwResTemplateGROUP::m_PageSize

Atlas Page size.

CIwArray<CIwTileSpecs*> CIwResTemplateGROUP::m_TileSpecs

User tiling specifications.

The documentation for this class was generated from the following file:
  • IwResHandlerGROUP.h


Airplay API Reference: CIwResTemplateImage

Airplay API Reference > Data Structures > CIwResTemplateImage >

CIwResTemplateImage Class Reference
[IwResManager API Reference]

#include <IwResHandlerImage.h>

Inheritance diagram for CIwResTemplateImage:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for image files. Associated with the CIwResHandlerImage resource handler. See the Resource Templates module overview for more information.

CIwResTemplateImage objects accept the following attributes in ITX files:
Attribute | Value | Description | Default value | Example
formatSW | (image format) | Specify a format to convert the image to, before uploading for SW rasterisation. | FORMAT_UNDEFINED (so the default preferred conversion is performed) | formatSW PALETTE4_ABGR_1555
formatHW | (image format) | Specify a format to convert the image to, before uploading for HW rasterisation. | FORMAT_UNDEFINED (so the default preferred conversion is performed) | formatHW PALETTE4_RGBA_4444
compressForDiskSpace | true or false | When compressing textures only compress textures where there is a saving in disk space - palettised 4-bit textures are often smaller on disk than compressed textures. | false (always compress textures if possible) | compressForDiskSpace true
allowLowQualityCompression | true or false | Allow texture compression where the visual results are generally not acceptable. By default, iwgx will not compress textures into formats known to look significantly degraded at 1:1 rendering. These results may be acceptable in certain applications. | false (exclude visually unacceptable compression) | allowLowQualityCompression true

Required Header Files
IwResHandlerImage.h

Member Function Documentation

virtual void CIwResTemplateImage::Apply ( ) [virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateImage::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateImage::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateImage::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerImage.h


Airplay API Reference: CIwResTemplateMTL

Airplay API Reference > Data Structures > CIwResTemplateMTL >

CIwResTemplateMTL Class Reference

#include <IwResHandlerMTL.h>

Inheritance diagram for CIwResTemplateMTL:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseOpen (CIwTextParserITX *pParser)
virtual void | Reset ()

Detailed Description

Template settings for MTL files. The template can accept any settings of a normal material and will propogate them to any material created while this template is current.

Member Function Documentation

virtual void CIwResTemplateMTL::Apply ( ) [virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateMTL::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateMTL::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateMTL::ParseOpen ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: start block.

Parameters:
pParser the parser instance to use
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwResTemplateMTL::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerMTL.h


Airplay API Reference: CIwResTemplateSKEL

Airplay API Reference > Data Structures > CIwResTemplateSKEL >

CIwResTemplateSKEL Class Reference
[IwResHandler]

#include <IwResHandlerSKEL.h>

Inheritance diagram for CIwResTemplateSKEL:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for SKEL files.

Member Function Documentation

virtual void CIwResTemplateSKEL::Apply ( ) [virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateSKEL::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateSKEL::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateSKEL::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerSKEL.h


Airplay API Reference: CIwResTemplateSKIN

Airplay API Reference > Data Structures > CIwResTemplateSKIN >

CIwResTemplateSKIN Class Reference
[IwResHandler]

#include <IwResHandlerSKIN.h>

Inheritance diagram for CIwResTemplateSKIN:

[legend]

Public Member Functions

virtual void | Apply ()
virtual void | Copy (CIwResTemplate *pSource)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Reset ()

Detailed Description

Resource template for SKEL files.

Member Function Documentation

virtual void CIwResTemplateSKIN::Apply ( ) [virtual]

Apply is called by ApplySettings, to prepare for resource building.

See also:
ApplySettings
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateSKIN::Copy ( CIwResTemplate * pSource ) [virtual]

Copy pSource into this template. The passed template should always be the same type as this template, and can be cast to this template's type.

Parameters:
pSource A CIwResTemplate source to copy.
Required Header Files
IwResHandler.h

Implements CIwResTemplate.

virtual bool CIwResTemplateSKIN::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Override of standard CIwManaged::ParseAttribute - adding support for "resName"

Parameters:
pParser | The parser instance to use.
pAttrName | The name of the attribute to parse.
Returns:
true if attribute has been set, false otherwise.
Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

virtual void CIwResTemplateSKIN::Reset ( ) [virtual]

Virtual override for returning a template to factory settings. Responsibility for calling this function belongs to derived classed and associated handlers. It is recommended that any setup code is done in this function and derived class constructors simply call this.

Required Header Files
IwResHandler.h

Reimplemented from CIwResTemplate.

The documentation for this class was generated from the following file:
  • IwResHandlerSKIN.h


Airplay API Reference: CIwSphereT

Airplay API Reference > Data Structures > CIwSphereT< V, R > >

CIwSphereT< V, R > Class Template Reference
[IwGeomSphere]

Fixed-point sphere: templated origin and radius types. More...

#include <IwGeomSphere.h>

Public Member Functions

template<class V2>
void | BoundVecs (V2 *pVec, uint32 v)
CIwSphereT (V const &_t, R _r)
CIwSphereT ()
bool | ClipToFrustrum (CIwPlane *pPlanes, uint32 clipFlags)
bool | ClipToPlane (const CIwPlane &plane)
template<class V2>
bool | ContainsVec (const V2 &v) const
iwufixed | GetDistSqFromLine (const CIwVec3 &point, const CIwVec3 &dir) const
uint32 | GetRadius () const
V const & | GetTrans () const
bool | IntersectsLine (CIwVec3 &point, CIwVec3 &dir)
void | Serialise ()
void | SetRadius (R _r)

Data Fields

R | r
uint32 | r2
V | t

Detailed Description

template<class V, class R>
class CIwSphereT< V, R >

CIwSphereT - Defines a sphere class template and two standards instances of this template.
Parameters:
V | Vector type to define origin of sphere.
R | Type to define radius of sphere.

Constructor & Destructor Documentation

template<class V, class R>
CIwSphereT< V, R >::CIwSphereT ( ) [inline]

Creates a new uninitialised sphere.

template<class V, class R>
CIwSphereT< V, R >::CIwSphereT | ( | V const & | _t,
 |  | R | _r |
 | ) |  |  | [inline]

Creates a new sphere.

Parameters:
_t | Origin of sphere.
_r | Radius of sphere.

Member Function Documentation

template<class V, class R>
template<class V2>
void CIwSphereT< V, R >::BoundVecs | ( | V2 * | pVec,
 |  | uint32 | v |
 | ) |  |  | [inline]

Calculates a sphere to contain the vectors.

Parameters:
pVec | Pointer to an array of vectors.
v | Number of vectors in array.
Remarks:
The origin of the resulting sphere is at the average of the given verts; hence, the radius of the sphere may not be the smallest possible.

template<class V, class R>
bool CIwSphereT< V, R >::ClipToFrustrum | ( | CIwPlane * | pPlanes,
 |  | uint32 | clipFlags |
 | ) |  |  | [inline]

Confirm: Tests sphere against up to 6 planes, based on flags.

Parameters:
pPlane | Pointer to an array of planes of number implied by clipFlags.
clipFlags | Planes to clip against.
Returns:
false if the sphere lies entirely inside the frustrum.
See also:
IwCamera
Required Header Files
IwGeomSphere.h

template<class V, class R>
bool CIwSphereT< V, R >::ClipToPlane ( const CIwPlane & plane ) [inline]

Tests if sphere lies entirely on the normal side of a plane

Parameters:
plane Plane to test against.
Returns:
true if sphere lies entirely on the side of the plane its normal points into.

template<class V, class R>
template<class V2>
bool CIwSphereT< V, R >::ContainsVec ( const V2 & v ) const [inline]

Tests if the sphere contains a point.

Parameters:
pt Point to test against sphere
Returns:
true if sphere contains the point.
Remarks:
This calculation is not optimised.

template<class V, class R>
iwufixed CIwSphereT< V, R >::GetDistSqFromLine | ( | const CIwVec3 & | point,
 |  | const CIwVec3 & | dir |
 | ) |  |  | const [inline]

Confirm: Gets the least square distance of a line from the sphere.

Parameters:
point | A point on the line.
dir | Vector along line, assumed normalised.
Returns:
Square of the distance of the line from the sphere.
Required Header Files
IwGeomSphere.h

template<class V, class R>
uint32 CIwSphereT< V, R >::GetRadius ( ) const [inline]

Gets the radius of the sphere.

Returns:
The fixed-point radius of the sphere.
Required Header Files
IwGeomSphere.h

template<class V, class R>
V const& CIwSphereT< V, R >::GetTrans ( ) const [inline]

Gets the translation of the sphere.

Returns:
The origin of the sphere.

template<class V, class R>
bool CIwSphereT< V, R >::IntersectsLine | ( | CIwVec3 & | point,
 |  | CIwVec3 & | dir |
 | ) |  |  | [inline]

Tests if a line intersects the sphere.

Parameters:
point | A point on the line.
dir | Vector along line, assumed normalised.
Returns:
true if the line intersects the sphere
Required Header Files
IwGeomSphere.h

template<class V, class R>
void CIwSphereT< V, R >::Serialise ( )

Reads/writes binary file using IwSerialise interface.

See also:
IwSerialise

template<class V, class R>
void CIwSphereT< V, R >::SetRadius ( R _r ) [inline]

Sets sphere radius. Use this function instead of setting r directly to ensure r2 is kept in sync.

Parameters:
_r Radius for sphere.
Required Header Files
IwGeomSphere.h

Field Documentation

template<class V, class R>
R CIwSphereT< V, R >::r

Radius of sphere.

template<class V, class R>
uint32 CIwSphereT< V, R >::r2

Radius of sphere squared as an integer (i.e., not shifted down).

template<class V, class R>
V CIwSphereT< V, R >::t

Origin of sphere.

The documentation for this class was generated from the following file:
  • IwGeomSphere.h


Airplay API Reference: CIwSQuat

Airplay API Reference > Data Structures > CIwSQuat >

CIwSQuat Class Reference
[IwGeomSQuat]

#include <IwGeomSQuat.h>

Public Member Functions

CIwSQuat (CIwVec3 const &v, iwangle theta)
CIwSQuat (iwsfixed s)
CIwSQuat (iwsfixed s, CIwSVec3 const &v)
CIwSQuat (iwsfixed s, iwsfixed x, iwsfixed y, iwsfixed z)
CIwSQuat ()
iwfixed | GetLength () const
iwfixed | GetLengthSquared () const
iwangle GetRotationAngle ()
CIwSVec3 GetRotationAxis ()
void | Lerp (const CIwSQuat &startQ, const CIwSQuat &endQ, iwfixed const t)
CIwSQuat & NormaliseInPlace ()
CIwSQuat | operator * (iwfixed const l) const
CIwSQuat | operator * (CIwSQuat const &q) const
operator CIwMat () const
bool | operator!= (CIwSQuat const &q) const
CIwSQuat | operator+ (CIwSQuat const &q) const
CIwSQuat | operator- (CIwSQuat const &q) const
CIwSQuat | operator- () const
CIwSQuat | operator<< (const int c) const
CIwSQuat & | operator= (CIwSQuat const &q)
bool | operator== (CIwSQuat const &q) const
CIwSQuat | operator>> (const int c) const
CIwVec3 | RotateVector (CIwVec3 const &v) const
void | Serialise ()
void | SetAxisAngle (iwsfixed x, iwsfixed y, iwsfixed z, iwangle theta)
void | Slerp (const CIwSQuat &startQ, const CIwSQuat &endQ, iwfixed const t)

Data Fields

iwsfixed s

Static Public Attributes

static CIwSQuat | g_Identity

Detailed Description

CIwSQuat - Fixed-point quaternion with 16-bit components.

Constructor & Destructor Documentation

CIwSQuat::CIwSQuat ( ) [inline]

Creates a new quaternion with unit real compoent and zero imaginary component.

CIwSQuat::CIwSQuat | ( | iwsfixed | s,
 |  | iwsfixed | x,
 |  | iwsfixed | y,
 |  | iwsfixed | z |
 | ) |  |  | [inline]

Creates a new quaternion with supplied components.

Parameters:
s,x,y,z components to initialise quaternion

CIwSQuat::CIwSQuat | ( | iwsfixed | s,
 |  | CIwSVec3 const & | v |
 | ) |  |  | [inline]

Creates a new quaternion with given components.

Parameters:
s | Real component of quaternion.
v | CIwSVec3 containing imaginary components.

CIwSQuat::CIwSQuat ( iwsfixed s ) [inline]

Creates a new quaternion with given real component and zero imaginary component.

Parameters:
s Real component.

CIwSQuat::CIwSQuat | ( | CIwVec3 const & | v,
 |  | iwangle | theta |
 | ) |  |  | [inline]

Creates a new quaternion with the supplied axis and angle.

Parameters:
Axis | of rotation.
Angle | of rotation.

Member Function Documentation

iwfixed CIwSQuat::GetLength ( ) const

Calculates the quaternion's length.

Returns:
Square root of the quaternion's inner product with itself.

iwfixed CIwSQuat::GetLengthSquared ( ) const

Calculates the square of the quaternion's length.

Returns:
The inner product of the quaternion with itself.

iwangle CIwSQuat::GetRotationAngle ( ) [inline]

Gets the angle of rotation the quaternion represents.

Returns:
Twice the arccos of the real part of the quaternion.

CIwSVec3 CIwSQuat::GetRotationAxis ( ) [inline]

Gets a normalised eigenvector of the rotation the quaternion represents.

Returns:
Normalised imaginary part of quaternion.

void CIwSQuat::Lerp | ( | const CIwSQuat & | startQ,
 |  | const CIwSQuat & | endQ,
 |  | iwfixed const | t
 | ) |  |

Linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

CIwSQuat& CIwSQuat::NormaliseInPlace ( ) [inline]

Scales quaternion so it has unit length.

Returns:
Reference to quaternion.

CIwSQuat CIwSQuat::operator * ( iwfixed const l ) const [inline]

Scale operator.

CIwSQuat CIwSQuat::operator * ( CIwSQuat const & q ) const [inline]

Calculates quaternion product.

Parameters:
q Quaternion with which to find product.
Returns:
quaternion representing the rotation by this quaternion and then by q.

CIwSQuat::operator CIwMat ( ) const [inline]

Matrix operator.

Returns:
Matrix of rotation represented by this quaternion.

bool CIwSQuat::operator!= ( CIwSQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q Quaternion for comparison.
Returns:
False if components of quaternions are the same, otherwise true.

CIwSQuat CIwSQuat::operator+ ( CIwSQuat const & q ) const [inline]

Sum operator.

Parameters:
q Quaternion to sum this quaternion with
Returns:
Quaternion with components that are the sum of the supplied quaternions.

CIwSQuat CIwSQuat::operator- ( CIwSQuat const & q ) const [inline]

Difference operator.

Parameters:
q Quaternion to difference this quaternion with
Returns:
Quaternion with components that are the difference of the supplied quaternions.

CIwSQuat CIwSQuat::operator- ( ) const [inline]

Conjugates quaternion.

Returns:
A quaternion which represents the opposite rotation

CIwSQuat CIwSQuat::operator<< ( const int c ) const [inline]

Shifts components of quaternion.

Parameters:
c Component left shift.
Returns:
Quaternion with components shifted by given amount.

CIwSQuat& CIwSQuat::operator= ( CIwSQuat const & q ) [inline]

Assignment operator.

Parameters:
q Quaternion from which to copy components.
Returns:
Reference to this quaternion.

bool CIwSQuat::operator== ( CIwSQuat const & q ) const [inline]

Compares quaternions.

Parameters:
q quaternion for comparison
Returns:
true iff components of quaternions are the same

CIwSQuat CIwSQuat::operator>> ( const int c ) const [inline]

Shifts components of quaternion.

Parameters:
c Component right shift.
Returns:
Quaternion with components shifted by given amount.

CIwVec3 CIwSQuat::RotateVector ( CIwVec3 const & v ) const [inline]

Parameters:
v Vector to rotate.
Returns:
Rotated vector.

void CIwSQuat::Serialise ( )

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise

void CIwSQuat::SetAxisAngle | ( | iwsfixed | x,
 |  | iwsfixed | y,
 |  | iwsfixed | z,
 |  | iwangle | theta
 | ) |  |

Sets quaternion representing the rotation around the supplied aixis by the supplied angle.

Parameters:
axis | Rotation axis - assumed to be normalised.
angle30 | Rotation angle, where IW_GEOM_ONE represents a rotation of 360 degrees.

void CIwSQuat::Slerp | ( | const CIwSQuat & | startQ,
 |  | const CIwSQuat & | endQ,
 |  | iwfixed const | t
 | ) |  |

Spherical linear interpolation of quaternion components.

Parameters:
startQ | Start quaternion.
endQ | End quaternion.
t | Fraction of relative amount of start and end components to use.
Remarks:
If the inner product of startQ and endQ is negative, then end components are the negative of endQ's.

Field Documentation

CIwSQuat CIwSQuat::g_Identity [static]

Identity unit quaternion.

iwsfixed CIwSQuat::s

Quaternion components

The documentation for this class was generated from the following file:
  • IwGeomSQuat.h


Airplay API Reference: CIwString

Airplay API Reference > Data Structures > CIwString< N > >

CIwString< N > Class Template Reference
[IwString]

#include <IwString.h>

Public Member Functions

Methods
const char * | c_str () const
int | capacity () const
int | length () const
void | setLength (int len)
int | size () const
Operator overloads

Detailed Description

template<int N>
class CIwString< N >

CIwString

Member Function Documentation

template<int N>
const char* CIwString< N >::c_str ( ) const [inline]

Returns a pointer to a non-modifiable C string, which is constructed by adding a terminating null element (E(0)) to the controlled sequence. Calling any non-const member function for *this can invalidate the pointer.

Required Header Files
IwString.h

template<int N>
int CIwString< N >::capacity ( ) const [inline]

Gets the capacity (maximum length) of a string.

Required Header Files
IwString.h

template<int N>
int CIwString< N >::length ( ) const [inline]

Gets the length of a string.

Required Header Files
IwString.h
Required Header Files
IwString.h

template<int N>
void CIwString< N >::setLength ( int len ) [inline]

Sets the length of this string to the specified value.

Required Header Files
IwString.h

template<int N>
int CIwString< N >::size ( ) const [inline]

Gets the length of a string.

Required Header Files
IwString.h
Required Header Files
IwString.h

The documentation for this class was generated from the following file:
  • IwString.h


Airplay API Reference: CIwSVec2

Airplay API Reference > Data Structures > CIwSVec2 >

CIwSVec2 Class Reference
[IwGeomSVec2]

#include <IwGeomSVec2.h>

Public Member Functions

CIwSVec2 (int16 _x, int16 _y)
CIwSVec2 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER int32 | Dot (CIwSVec2 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwSVec2 | GetNormalised () const
CIwSVec2 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwSVec2 | operator * (iwfixed l) const
CIwSVec2 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec2 | operator- () const
VALUE_IN_REGS CIwSVec2 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec2 | operator<< (const int s) const
VALUE_IN_REGS CIwSVec2 | operator<<= (const int s)
VALUE_IN_REGS CIwSVec2 | operator>> (const int s) const
VALUE_IN_REGS CIwSVec2 | operator>>= (const int s)
VALUE_IN_REGS int16 | operator[] (const int n) const
VALUE_IN_REGS int16 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwSVec2 const &v) const
bool | operator!= (CIwSVec2 const &v) const
VALUE_IN_REGS CIwSVec2 | operator+ (CIwSVec2 const &v) const
CIwSVec2 & | operator+= (CIwSVec2 const &v)
VALUE_IN_REGS CIwSVec2 | operator- (CIwSVec2 const &v) const
CIwSVec2 & | operator-= (CIwSVec2 const &v)
CIwSVec2 & | operator= (CIwSVec2 const &v)
bool | operator== (CIwSVec2 const &v) const
VALUE_IN_REGS CIwSVec2 | operator^ (CIwSVec2 const &v) const

Static Public Attributes

static CIwSVec2 | g_AxisX
static CIwSVec2 | g_AxisY
static CIwSVec2 | g_Zero

Detailed Description

CIwSVec2

Constructor & Destructor Documentation

CIwSVec2::CIwSVec2 ( ) [inline]

Constructor: creates a new vector.

CIwSVec2::CIwSVec2 | ( | int16 | _x,
 |  | int16 | _y |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component

Member Function Documentation

INLINE_MEMBER int32 CIwSVec2::Dot ( CIwSVec2 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwSVec2::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec2::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec2::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec2::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec2::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwSVec2 CIwSVec2::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwSVec2 CIwSVec2::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwSVec2::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwSVec2::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwSVec2::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwSVec2::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwSVec2::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwSVec2::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwSVec2 CIwSVec2::g_AxisX [static]

World X-axis.

CIwSVec2 CIwSVec2::g_AxisY [static]

World Y-axis.

CIwSVec2 CIwSVec2::g_Zero [static]

Zero vector.

int16 CIwSVec2::x

x-coordinate of the vector

int16 CIwSVec2::y

y-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomSVec2.h


Airplay API Reference: CIwSVec3

Airplay API Reference > Data Structures > CIwSVec3 >

CIwSVec3 Class Reference
[IwGeomSVec3]

#include <IwGeomSVec3.h>

Public Member Functions

CIwSVec3 (int16 _x, int16 _y, int16 _z)
CIwSVec3 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

VALUE_IN_REGS INLINE_MEMBER
CIwSVec3 		Cross (CIwSVec3 const &v) const
INLINE_MEMBER int32 | Dot (CIwSVec3 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwSVec3 | GetNormalised () const
CIwSVec3 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwSVec3 | operator * (iwfixed l) const
CIwSVec3 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec3 | operator- () const
VALUE_IN_REGS CIwSVec3 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec3 | operator<< (const int s) const
VALUE_IN_REGS CIwSVec3 | operator<<= (const int s)
VALUE_IN_REGS CIwSVec3 | operator>> (const int s) const
VALUE_IN_REGS CIwSVec3 | operator>>= (const int s)
VALUE_IN_REGS int16 | operator[] (const int n) const
VALUE_IN_REGS int16 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwSVec3 const &v) const
bool | operator!= (CIwSVec3 const &v) const
VALUE_IN_REGS CIwSVec3 | operator+ (CIwSVec3 const &v) const
CIwSVec3 & | operator+= (CIwSVec3 const &v)
VALUE_IN_REGS CIwSVec3 | operator- (CIwSVec3 const &v) const
CIwSVec3 & | operator-= (CIwSVec3 const &v)
CIwSVec3 & | operator= (CIwSVec3 const &v)
bool | operator== (CIwSVec3 const &v) const
VALUE_IN_REGS CIwSVec3 | operator^ (CIwSVec3 const &v) const

Static Public Attributes

static CIwSVec3 | g_AxisX
static CIwSVec3 | g_AxisY
static CIwSVec3 | g_AxisZ
static CIwSVec3 | g_Zero

Detailed Description

CIwSVec3

Constructor & Destructor Documentation

CIwSVec3::CIwSVec3 ( ) [inline]

Constructor: creates a new vector.

CIwSVec3::CIwSVec3 | ( | int16 | _x,
 |  | int16 | _y,
 |  | int16 | _z |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component

Member Function Documentation

VALUE_IN_REGS INLINE_MEMBER CIwSVec3 CIwSVec3::Cross ( CIwSVec3 const & v ) const [inline]

Cross product.

Parameters:
Vector for cross product operation.
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwSVec3::Dot ( CIwSVec3 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwSVec3::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec3::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec3::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec3::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec3::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwSVec3 CIwSVec3::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwSVec3 CIwSVec3::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwSVec3::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwSVec3::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwSVec3::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwSVec3::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwSVec3::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwSVec3::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwSVec3 CIwSVec3::g_AxisX [static]

World X-axis.

CIwSVec3 CIwSVec3::g_AxisY [static]

World Y-axis.

CIwSVec3 CIwSVec3::g_AxisZ [static]

World Z-axis.

CIwSVec3 CIwSVec3::g_Zero [static]

Zero vector.

int16 CIwSVec3::x

x-coordinate of the vector

int16 CIwSVec3::y

y-coordinate of the vector

int16 CIwSVec3::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomSVec3.h


Airplay API Reference: CIwSVec4

Airplay API Reference > Data Structures > CIwSVec4 >

CIwSVec4 Class Reference
[IwGeomSVec4]

#include <IwGeomSVec4.h>

Public Member Functions

CIwSVec4 (int16 _x, int16 _y, int16 _z, int16 _w)
CIwSVec4 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER int32 | Dot (CIwSVec4 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwSVec4 | GetNormalised () const
CIwSVec4 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwSVec4 | operator * (iwfixed l) const
CIwSVec4 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwSVec4 | operator- () const
VALUE_IN_REGS CIwSVec4 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwSVec4 | operator<< (const int s) const
VALUE_IN_REGS CIwSVec4 | operator<<= (const int s)
VALUE_IN_REGS CIwSVec4 | operator>> (const int s) const
VALUE_IN_REGS CIwSVec4 | operator>>= (const int s)
VALUE_IN_REGS int16 | operator[] (const int n) const
VALUE_IN_REGS int16 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwSVec4 const &v) const
bool | operator!= (CIwSVec4 const &v) const
VALUE_IN_REGS CIwSVec4 | operator+ (CIwSVec4 const &v) const
CIwSVec4 & | operator+= (CIwSVec4 const &v)
VALUE_IN_REGS CIwSVec4 | operator- (CIwSVec4 const &v) const
CIwSVec4 & | operator-= (CIwSVec4 const &v)
CIwSVec4 & | operator= (CIwSVec4 const &v)
bool | operator== (CIwSVec4 const &v) const
VALUE_IN_REGS CIwSVec4 | operator^ (CIwSVec4 const &v) const

Static Public Attributes

static CIwSVec4 | g_AxisW
static CIwSVec4 | g_AxisX
static CIwSVec4 | g_AxisY
static CIwSVec4 | g_AxisZ
static CIwSVec4 | g_Zero

Detailed Description

CIwSVec4

Constructor & Destructor Documentation

CIwSVec4::CIwSVec4 ( ) [inline]

Constructor: creates a new vector.

CIwSVec4::CIwSVec4 | ( | int16 | _x,
 |  | int16 | _y,
 |  | int16 | _z,
 |  | int16 | _w |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component
_w | W-component

Member Function Documentation

INLINE_MEMBER int32 CIwSVec4::Dot ( CIwSVec4 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwSVec4::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec4::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec4::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec4::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwSVec4::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwSVec4 CIwSVec4::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwSVec4 CIwSVec4::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwSVec4::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwSVec4::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwSVec4::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwSVec4::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwSVec4::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwSVec4::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwSVec4 CIwSVec4::g_AxisW [static]

World W-axis.

CIwSVec4 CIwSVec4::g_AxisX [static]

World X-axis.

CIwSVec4 CIwSVec4::g_AxisY [static]

World Y-axis.

CIwSVec4 CIwSVec4::g_AxisZ [static]

World Z-axis.

CIwSVec4 CIwSVec4::g_Zero [static]

Zero vector.

int16 CIwSVec4::w

w-coordinate of the vector

int16 CIwSVec4::x

x-coordinate of the vector

int16 CIwSVec4::y

y-coordinate of the vector

int16 CIwSVec4::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomSVec4.h


Airplay API Reference: CIwTextDecomposer

Airplay API Reference > Data Structures > CIwTextDecomposer >

CIwTextDecomposer Class Reference
[Text Decomposer, Text Decomposer]

Class that can be used to write out an object hierarchy, and its properties, to text format. More...

#include <IwTextDecomposer.h>

Public Member Functions

const IIwDecomposable * | GetObject (int32 level=0)
void | OpenScope (bool inlineScope)
void | WriteAttibuteNameHash (const char *pName, uint32 hash)
void | WriteAttribute (const char *pAttrName, const char *pAttrVal)
void | WriteAttributeHash (uint32 hash)
void | WriteAttributeName (const char *pAttrName)
template<class Type>
void | WriteAttributeNameVal (const char *pName, Type val)
template<class Type>
void | WriteAttributeNameValArray (const char *pName, const Type *val, int numVals)
template<class Type>
void | WriteAttributeVal (Type val)
template<class Type>
void | WriteAttributeValArray (const Type *val, int numVals)

Data Structures

class | Context

Detailed Description

Provides an interface for writing class names, scopes and attributes. The number of calls to OpenScope & CloseScope and OpenAttribute & CloseAttribute must be equal. There must be an open attribute before calls to WriteAttributeName or WriteAttributeVal.
The documentation for this class was generated from the following file:
  • IwTextDecomposer.h


Airplay API Reference: CIwTextParserITX

Airplay API Reference > Data Structures > CIwTextParserITX >

CIwTextParserITX Class Reference
[IwTextParserITX]

#include <IwTextParserITX.h>

Inheritance diagram for CIwTextParserITX:

[legend]

Public Types

typedef CIwString< 40 > | Field
typedef CIwArray< Field > | FieldArray
typedef FieldArray::iterator | FieldArrayIt

Public Member Functions

CIwTextParserITX ()
CIwManaged * | GetObject (int32 level=0)
virtual void * | ParseFile (const char *pPathname, bool allowNonExist=false)
void | PeekString (char *pString, int32 len, bool checkValid=true)
CIwManaged * PopObject ()
void | PushObject (CIwManaged *pObject)
void | ReadAngleDegrees (iwangle *pValue)
void | ReadAngleRadians (iwangle *pValue)
void | ReadBool (bool *pValue)
void | ReadDouble (double *pValue)
void | ReadDoubleArray (double *pValue, uint32 maxVals)
void | ReadFixed (iwfixed *pValue, uint32 shift=IW_GEOM_POINT)
void | ReadFixedArray (iwfixed *pValue, uint32 maxVals, uint32 shift=IW_GEOM_POINT)
void | ReadFloat (float *pValue)
void | ReadFloatArray (float *pValue, uint32 maxVals)
void | ReadInt16 (int16 *pValue)
void | ReadInt16Array (int16 *pValue, uint32 maxVals)
void | ReadInt32 (int32 *pValue)
void | ReadInt32Array (int32 *pValue, uint32 maxVals)
void | ReadInt8 (int8 *pValue)
void | ReadInt8Array (int8 *pValue, uint32 maxVals)
void | ReadLine (char *pBuffer, uint32 buffSize)
void | ReadScope (char *pBuffer, uint32 buffSize)
void | ReadString (CIwStringL &string, bool checkValid=true)
void | ReadString (CIwStringS &string, bool checkValid=true)
void | ReadString (char *pBuffer, uint32 buffSize, bool checkValid=true)
void | ReadStringHash (uint32 *pValue)
void | ReadUInt16 (uint16 *pValue)
void | ReadUInt16Array (uint16 *pValue, uint32 maxVals)
void | ReadUInt32 (uint32 *pValue)
void | ReadUInt32Array (uint32 *pValue, uint32 maxVals)
void | ReadUInt8 (uint8 *pValue)
void | ReadUInt8Array (uint8 *pValue, uint32 maxVals)
void | SetAssertOnUnrecognisedTokens (bool as)
void | SkipScope ()
~CIwTextParserITX ()

Static Public Member Functions

static void | FieldStripQuotes (Field &f)
static void | FilterString (const char *&pChar, FieldArray &fields, const char *fieldBreaks, const char *stringBreaks)
static bool | FilterStringGetEnum (const char *pChar, const char **ppNames, uint32 &value)
static bool | FilterStringGetEnumAsserted (const char *pChar, const char **ppNames, uint32 &value)
static uint32 | FilterStringGetFlags (const char *pChar, const char **ppNames)
static bool | FilterStringResetFlags (const char *pChar, const char **ppNames, uint32 &flags)
static bool | FilterStringSetFlags (const char *pChar, const char **ppNames, uint32 &flags)

Data Structures

class | CIwReference

Detailed Description

Text parser singleton for handling ITX-style formatting.

Member Typedef Documentation

typedef CIwString<40> CIwTextParserITX::Field

Typedef for a "field". Lists of strings separated by whitespace can be automatically split into arrays of fields. A field is a maximum of 40 characters long.

typedef CIwArray<Field> CIwTextParserITX::FieldArray

Typedef for an array of fields.

typedef FieldArray::iterator CIwTextParserITX::FieldArrayIt

Typedef for an iterator over an array of fields.

Constructor & Destructor Documentation

CIwTextParserITX::CIwTextParserITX ( )

Constructor.

CIwTextParserITX::~CIwTextParserITX ( )

Destructor.

Member Function Documentation

static void CIwTextParserITX::FieldStripQuotes ( Field & f ) [static]

Strip any quotes from a field.

Parameters:
f Reference to the field to strip any quotes from.
See also:
FilterString
Required Header Files
IwTextParserITX.h

static void CIwTextParserITX::FilterString | ( | const char *& | pChar,
 |  | FieldArray & | fields,
 |  | const char * | fieldBreaks,
 |  | const char * | stringBreaks |
 | ) |  |  | [static]

Filter a string into multiple fields by specifying field break characters and string break characters.

Parameters:
pChar | Pointer to the string to filter.
fields | Reference to the field array to fill.
fieldBreaks | String representing all characters which should be interpreted as field separators.
stringBreaks | String representing all characters which should be interpreted as the end of the string.
Required Header Files
IwTextParserITX.h

static bool CIwTextParserITX::FilterStringGetEnum | ( | const char * | pChar,
 |  | const char ** | ppNames,
 |  | uint32 & | value |
 | ) |  |  | [static]

Get an enumerated value from a NULL-terminated array of names.

Parameters:
pChar | Pointer to the string to check against the list of names.
ppNames | Pointer to a NULL-terminated array of names.
value | The value to write into.
Returns:
true only if the string matched one of the names.
Required Header Files
IwTextParserITX.h

static bool CIwTextParserITX::FilterStringGetEnumAsserted | ( | const char * | pChar,
 |  | const char ** | ppNames,
 |  | uint32 & | value |
 | ) |  |  | [static]

Get an enumerated value from a NULL-terminated array of names. Assert if not found

Parameters:
pChar | Pointer to the string to check against the list of names.
ppNames | Pointer to a NULL-terminated array of names.
value | The value to write into.
Returns:
true only if the string matched one of the names.
Required Header Files
IwTextParserITX.h

static uint32 CIwTextParserITX::FilterStringGetFlags | ( | const char * | pChar,
 |  | const char ** | ppNames |
 | ) |  |  | [static]

Filter a string of the form "<flagname> | <flagname> | ..." and get the flags field from a NULL-terminated array of flag name strings.

Parameters:
pChar | Pointer to the string to filter.
ppNames | Pointer to a NULL-terminated array of flag name strings.
Returns:
The resulting flags.
See also:
FilterString, FilterStringSetFlags, FilterStringResetFlags, FilterStrinGetEnum
Required Header Files
IwTextParserITX.h

static bool CIwTextParserITX::FilterStringResetFlags | ( | const char * | pChar,
 |  | const char ** | ppNames,
 |  | uint32 & | flags |
 | ) |  |  | [static]

Filter a string of the form "<flagname> | <flagname> | ..." and reset the flags.

Parameters:
pChar | Pointer to the string to filter.
ppNames | Pointer to a NULL-terminated array of flag name strings.
flags | The flags field to set.
Returns:
true only if any flag was reset.
See also:
FilterString, FilterStringGetFlags, FilterStringSetFlags, FilterStrinGetEnum
Required Header Files
IwTextParserITX.h

static bool CIwTextParserITX::FilterStringSetFlags | ( | const char * | pChar,
 |  | const char ** | ppNames,
 |  | uint32 & | flags |
 | ) |  |  | [static]

Filter a string of the form "<flagname> | <flagname> | ..." and set the flags.

Parameters:
pChar | Pointer to the string to filter.
ppNames | Pointer to a NULL-terminated array of flag name strings.
flags | The flags field to set.
Returns:
true only if any flag was set.
See also:
FilterString, FilterStringGetFlags, FilterStringResetFlags, FilterStrinGetEnum
Required Header Files
IwTextParserITX.h

CIwManaged* CIwTextParserITX::GetObject ( int32 level = 0 )

Get a CIwManaged object from the parser's object stack.

Parameters:
level Stack level to get object from. Must be <= 0. 0 refers to the top of the stack, -1 the level above, etc.
Returns:
Pointer to the CIwManaged object at the specified stack level, or NULL if there is no object at that level.
Required Header Files
IwTextParserITX.h

virtual void* CIwTextParserITX::ParseFile | ( | const char * | pPathname,
 |  | bool | allowNonExist = false |
 | ) |  |  | [virtual]

Parse a text file in ITX format.

Parameters:
pPathname | Full pathname of file.
allowNonExist | true only if we wish to permit the non-existence of the file. Defaults to false.
Returns:
Parsed objects have the ability to set a single global value, which is returned. Defaults to NULL.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::PeekString | ( | char * | pString,
 |  | int32 | len,
 |  | bool | checkValid = true
 | ) |  |

Read the next string into a buffer and reset the read position, so ReadString will read the same string.

Parameters:
string String object to read into.
Note:
Asserts if the read string is too large.
Required Header Files
IwTextParserITX.h

CIwManaged* CIwTextParserITX::PopObject ( )

Pop a CIwManaged object from the parser's object stack.

Returns:
The object at the current stack level.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::PushObject ( CIwManaged * pObject )

Push a CIwManaged object onto the parser's object stack.

Parameters:
pObject Pointer to the object to push onto the stack.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadAngleDegrees ( iwangle * pValue )

Read a single-precision floating-point value, representing an angle in degrees, and convert to a iwangle variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
For example, reading "360" would result in a value of IW_GEOM_ONE.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadAngleRadians ( iwangle * pValue )

Read a single-precision floating-point value, representing an angle in radians, and convert to a iwangle variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
For example, reading "3.1415926" would result in a value of IW_GEOM_ONE/2.

void CIwTextParserITX::ReadBool ( bool * pValue )

Read a boolean value into a bool variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
"true", "on" or "1" will result in the variable being set to true, otherwise it will be set to false.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadDouble ( double * pValue )

Read a double-precision floating-point value into a float variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if a floating-point value was not read.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadDoubleArray | ( | double * | pValue,
 |  | uint32 | maxVals
 | ) |  |

Read an array of double-precision floating-point values into an array of float variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0.5, 10, 20.25, 30.375}

Asserts if the number of values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadFixed | ( | iwfixed * | pValue,
 |  | uint32 | shift = IW_GEOM_POINT
 | ) |  |

Read a single-precision floating-point value, and convert to a iwfixed variable.

Parameters:
pValue | Pointer to the variable to write into.
shift | Number of fractional bits in the iwfixed variable. Defaults to 12.
Note:
For example, reading "1.0" would result in a value of IW_GEOM_ONE.

Asserts if a single-precision floating-point value was not read, or was outside the range of iwfixed.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadFixedArray | ( | iwfixed * | pValue,
 |  | uint32 | maxVals,
 |  | uint32 | shift = IW_GEOM_POINT
 | ) |  |

Read an array of single-precision floating-point values, and convert to an array of iwfixed variables.

Parameters:
pValue | Pointer to the array to write into.
maxVals | The maximum number of values to read.
shift | Number of fractional bits in the iwfixed variable. Defaults to 12.
Note:
The array should be within a new scope; for example {0.5, 10, 20.25, 30.375}

Asserts if the number of values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadFloat ( float * pValue )

Read a single-precision floating-point value into a float variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if a floating-point value was not read.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadFloatArray | ( | float * | pValue,
 |  | uint32 | maxVals
 | ) |  |

Read an array of single-precision floating-point values into an array of float variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0.5, 10, 20.25, 30.375}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt16 ( int16 * pValue )

Read an integer value into a int16 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt16Array | ( | int16 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of int16 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt32 ( int32 * pValue )

Read an integer value into a int32 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt32Array | ( | int32 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of int32 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt8 ( int8 * pValue )

Read an integer value into a int8 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadInt8Array | ( | int8 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of int8 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadLine | ( | char * | pBuffer,
 |  | uint32 | buffSize
 | ) |  |

Read the rest of the current line into a buffer.

Parameters:
pBuffer | Pointer to the buffer to read into.
buffSize | Size of the buffer.
Note:
Asserts if the read line is too large.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadScope | ( | char * | pBuffer,
 |  | uint32 | buffSize
 | ) |  |

Read the next scope into a buffer.

Parameters:
pBuffer | Pointer to the buffer to read into.
buffSize | Size of the buffer.
Note:
Asserts if the read scope is too large.

A "scope" is a block of text enclosed by curly brackets.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadString | ( | CIwStringL & | string,
 |  | bool | checkValid = true |
 | ) |  |  | [inline]

Read the next string into a CIwStringL object.

Parameters:
string String object to read into.
Note:
Asserts if the read string is too large.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadString | ( | CIwStringS & | string,
 |  | bool | checkValid = true |
 | ) |  |  | [inline]

Read the next string into a CIwStringS object.

Parameters:
string String object to read into.
Note:
Asserts if the read string is too large.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadString | ( | char * | pBuffer,
 |  | uint32 | buffSize,
 |  | bool | checkValid = true
 | ) |  |

Read the next string into a buffer.

Parameters:
pBuffer | Pointer to the buffer to read into.
buffSize | Size of the buffer.
checkValid | Assert if the string contains ascii control characters (any character under 32)
Note:
Asserts if the read string is too large.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadStringHash ( uint32 * pValue )

Read the next string, calculate the 32-bit hashed value and store it.

Parameters:
pValue Pointer to 32-bit value to write to.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt16 ( uint16 * pValue )

Read an integer value into a uint16 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt16Array | ( | uint16 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of uint16 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt32 ( uint32 * pValue )

Read an unsigned integer value into a uint32 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt32Array | ( | uint32 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of uint32 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt8 ( uint8 * pValue )

Read an integer value into a uint8 variable.

Parameters:
pValue Pointer to the variable to write into.
Note:
Asserts if an integer value was not read, or was outside the range of the variable type.
Required Header Files
IwTextParserITX.h

void CIwTextParserITX::ReadUInt8Array | ( | uint8 * | pValue,
 |  | uint32 | maxVals |
 | ) |  |  | [inline]

Read an array of integers value into an array of uint8 variables.

Parameters:
pValue | Pointer to the array of variables to write into.
maxVals | The maximum number of values to read.
Note:
The array should be within a new scope; for example {0, 10, 20, 30}

Asserts if the number of integer values read was 0, or greater than maxVals.

Required Header Files
IwTextParserITX.h

void CIwTextParserITX::SetAssertOnUnrecognisedTokens ( bool as ) [inline]

Set whether or not to assert on unrecognised tokens.

ITX files are in the format:

 <classname>
 {
     <attribute> <value>
     <attribute> <value>
     ...
 }
 ...

If <attribute> is not recognised by the enclosing class, or <classname> is not recognised by the class factory, this counts as an "unrecognised token". By default, the parser will in this case silently skip the following scope (i.e. the following string or the following text enclosed by curly braces). This function can be used to turn on warnings, so that unrecognised tokens trigger an assertion dialog.

skip true if the parser should assert when finding an unrecognised token.

void CIwTextParserITX::SkipScope ( )

Skip the next scope.

Note:
If the current line contains '}' before '{', then scope is defined as the text leading up to (but not including) the first occurrence of '}'. If the current line contains '{' or the first non-whitespace character of the next line is '{', then scope is defined as the text leading up to the first occurrence of '{' as well as the text contained (inclusively) between the first occurrence of '{' and the '}' at the same depth. Otherwise, scope is defined as the text up to (but not including) the first non-whitespace character on the next line.

Asserts if a scope is not found before the end of the file.

Required Header Files
IwTextParserITX.h

The documentation for this class was generated from the following file:
  • IwTextParserITX.h


Airplay API Reference: CIwTexture

Airplay API Reference > Data Structures > CIwTexture >

CIwTexture Class Reference
[Textures]

#include <IwTexture.h>

Inheritance diagram for CIwTexture:

[legend]

Public Types

enum | Flags

Public Member Functions

void | ChangePalette (uint16 *pPalette, CIwImage::Format format)
void | ChangeTexels (uint8 *pTexels, CIwImage::Format format)
CIwTexture ()
void | CopyFromBuffer (uint16 w, uint16 h, CIwImage::Format format, uint16 pitch, uint8 *pImageData, uint16 *pPalette)
void | CopyFromImage (CIwImage *pImg)
CIwTexture * | ExtractSubTexture (uint16 x, uint16 y, uint16 w, uint16 h, const char *name)
bool | GetClamping () const
uint16 | GetDepth () const
bool | GetFiltering () const
uint32 | GetFlags () const
CIwImage::Format | GetFormat () const
CIwImage::Format | GetFormatHW () const
CIwImage::Format | GetFormatSW () const
uint32 | GetHeight () const
bool | GetMipMapping () const
bool | GetModifiable () const
void | GetPalette (uint16 *pPalette, CIwImage::Format format) const
const uint8 * | GetPalette () const
const CIwColour * | GetPaletteCacheRGBs () const
int32 | GetPaletteMemSize () const
int32 | GetPaletteNumEntries () const
uint32 | GetPitch () const
void | GetTexels (uint8 *pTexels, CIwImage::Format format) const
const uint8 * | GetTexels () const
int32 | GetTexelsMemSize () const
uint32 | GetWidth () const
uint8 | HasAlpha () const
void | LoadFromFile (const char *imageFile)
void | RemakeMipmaps ()
virtual void | Resolve ()
virtual void | Serialise ()
void | SetClamping (bool bOn)
void | SetFiltering (bool bOn)
void | SetFormatHW (CIwImage::Format formatHW)
void | SetFormatSW (CIwImage::Format formatSW)
void | SetImage (CIwImage *pImg)
void | SetMipMapping (bool bOn)
void | SetModifiable (bool modifiable)
void | SetPaletteCacheRGBs (CIwColour *pCols, bool owned=false)
virtual void | Upload ()
void | UseAsHandle (CIwTexture *pTex)
bool | UsesAlpha (uint8 threshold=0xff) const
bool | UsesChromakey () const
virtual | ~CIwTexture ()

Friends

void | IwGxSetMaterial (CIwMaterial *pMat)

Detailed Description

Texture object. See the Textures module overview for more information.

Member Enumeration Documentation

enum CIwTexture::Flags

Texture flags. These can be read but should not be written directly.

Required Header Files
IwTexture.h
Enumerator:
UPLOADED_F | This texture has been uploaded.
NEEDS_SW_TRANSPARENCY_F | This texture has (and uses chromakey).
UPLOAD_ON_LOAD_F | Upload this texture as soon as it's been loaded.
USES_TRANSPARENCY_F | Texture uses colour-keying.
NO_TRANSPARENCY_F | Texture doesn't use colour-keying.
NO_FILTER_F | Disable filtering.
OWNS_TEXELS_F | m_Texels (texel data) points to an owned allocation.
OWNS_PALETTE_F | m_Palette (palette data) points to an owned allocation.
OWNS_PALETTE_CACHE_RGBS_F | m_PaletteCacheRGBs points to an owned allocation
NATIVE_16BIT_F | Convert 16bit texture to native when uploading to VRAM.
SHARES_TEXELS_F | Uses another texture's texels.
DO_SW_F | Perform SW-related functions on this texture.
DO_HW_F | Perform HW-related functions on this texture.
KEEP_DATA_AFTER_UPLOAD_F | Don't delete the texels and palette after upload. Use this for palette animation. Uses no extra memory if software rendering is enabled.
NEVER_SW_F | Never upload this texture for SW.
NO_MIPMAPPING_F | Disable mipmapping.
CLAMP_UV_F | Clamp (rather than wrap) in U and V.
SKIPPED_MIPMAP_GENERATION | Record if mip maps should have been generated, but weren't.
CREATE_FOR_3D_API_F | For targets which support separate 2D and 3D APIs (e.g. J2ME + JSR-184), create the 3D API image (e.g. JSR-184's Image2D and Texture2D).
CREATE_FOR_2D_API_F | For targets which support separate 2D and 3D APIs (e.g. J2ME + JSR-184), create the 2D API image (e.g. MIDP's Image).
SHARED_SOURCE_F | Other textures share this texture's texels.
CLAMP_UV_SET_F | Has HW target been set to clamp?
DONT_SERIALISE_IMAGE_F | Do not save any image data for this texture.
ATTACHED_TO_SURFACE_F | It is an error to use a texture that's bound to the active surface.
BOUND_TO_ACTIVE_SURFACE_F | It is an error to use a texture that's bound to the active surface.
OWNS_HW_TEXELS_F | Does this texture own its HW storage?

Constructor & Destructor Documentation

CIwTexture::CIwTexture ( )

Constructor.

virtual CIwTexture::~CIwTexture ( ) [virtual]

Destructor.

Member Function Documentation

void CIwTexture::ChangePalette | ( | uint16 * | pPalette,
 |  | CIwImage::Format | format
 | ) |  |

Changes the texture's palette.

Parameters:
pPalette | Pointer to the new palette to use.
format | Format of pPalette data
See also:
ChangeTexels
Note:
For HW rasterisation uploaded textures must keep source data to allow change
Required Header Files
IwTexture.h

void CIwTexture::ChangeTexels | ( | uint8 * | pTexels,
 |  | CIwImage::Format | format
 | ) |  |

Changes the texture's texels.

Parameters:
pTexels | Pointer to the new texels to use.
format | Format of pTexels data
See also:
ChangePalette
Note:
For HW rasterisation uploaded textures must keep source data to allow change
Required Header Files
IwTexture.h

void CIwTexture::CopyFromBuffer | ( | uint16 | w,
 |  | uint16 | h,
 |  | CIwImage::Format | format,
 |  | uint16 | pitch,
 |  | uint8 * | pImageData,
 |  | uint16 * | pPalette
 | ) |  |

Loads image data from a memory buffer.

Note:
The file loaded is an old-style IwImageFormat.
Parameters:
w | Width of the image to create.
h | Height of the image to create.
format | Format of the image to create (the same as input data).
pitch | Pitch of the image to create.
pImageData | Pointer to the texel data to read from.
pPalette | Pointer to the palette data to read from (or NULL, for an unpalettised image format).
Required Header Files
IwTexture.h

void CIwTexture::CopyFromImage ( CIwImage * pImg )

Sets image data to be a copy of the passed image. Any current image will be cleared. If pImg owned its buffers, this will make an owned copy of them, otherwise the buffers are shared unowned

Parameters:
pImg A pointer to the source image
Required Header Files
IwTexture.h

CIwTexture* CIwTexture::ExtractSubTexture | ( | uint16 | x,
 |  | uint16 | y,
 |  | uint16 | w,
 |  | uint16 | h,
 |  | const char * | name
 | ) |  |

Creates a new texture based on a sub-rectangle of this one.

Parameters:
x | Left U coord of specified region.
y | Top V coord of specified region.
w | Width of specified region.
h | Height of specified region.
name | Name of new texture.
Returns:
Pointer to a newly-created texture which uses the specified region.
See also:
Upload
Required Header Files
IwTexture.h

bool CIwTexture::GetClamping ( ) const [inline]

Gets whether or not the texture uses clamping.

Returns:
True only if the texture uses clamping.
See also:
SetClamping
Required Header Files
IwTexture.h

uint16 CIwTexture::GetDepth ( ) const [inline]

Gets texture colour depth, in bits.

Returns:
The texture colour depth, in bits.
See also:
GetWidth, GetHeight, GetFormat, GetFlags
Required Header Files
IwTexture.h

bool CIwTexture::GetFiltering ( ) const [inline]

Gets whether or not the texture uses bilinear filtering.

Returns:
True only if the texture uses bilinear filtering.
See also:
SetFiltering
Required Header Files
IwTexture.h

uint32 CIwTexture::GetFlags ( ) const [inline]

Gets the texture flags.

Returns:
The texture flags.
See also:
GetWidth, GetHeight, GetDepth, GetFormat
Required Header Files
IwTexture.h

CIwImage::Format CIwTexture::GetFormat ( ) const [inline]

Gets the enumerated texture format. This is the texture format as loaded from disk. Note that the texture may be converted to a different format when being "uploaded" to the target graphics sub-device (for instance, the Airplay software renderer, or OpenGL ES).

Returns:
The enumerated texture format.
See also:
GetFormatSW, GetFormatHW, GetWidth, GetHeight, GetDepth, GetFlags

CIwImage::Format CIwTexture::GetFormatHW ( ) const [inline]

Gets the enumerated texture format after uploading to any HW graphics sub-device (for instance, OpenGL ES). Note that this may be different from the texture's format on disk.

Returns:
The enumerated texture format.
See also:
GetFormatSW, GetFormat, GetWidth, GetHeight, GetDepth, GetFlags

CIwImage::Format CIwTexture::GetFormatSW ( ) const [inline]

Gets the enumerated texture format after uploading to the SW graphics sub-device (the Airplay software renderer). Note that this may be different from the texture's format on disk.

Returns:
The enumerated texture format.
See also:
GetFormatHW, GetFormat, GetWidth, GetHeight, GetDepth, GetFlags

uint32 CIwTexture::GetHeight ( ) const [inline]

Gets texture height.

Returns:
The texture height, in texels.
See also:
GetWidth, GetDepth, GetFormat, GetFlags
Required Header Files
IwTexture.h

bool CIwTexture::GetMipMapping ( ) const [inline]

Gets whether or not the texture uses mipmapping.

Returns:
True only if the texture uses mipmapping.
See also:
SetMipMapping
Required Header Files
IwTexture.h

bool CIwTexture::GetModifiable ( ) const [inline]

Returns true if the texture is modifiable.

Required Header Files
IwTexture.h

void CIwTexture::GetPalette | ( | uint16 * | pPalette,
 |  | CIwImage::Format | format |
 | ) |  |  | const

Copies palette data into supplied buffer

Parameters:
pPalette | Pointer to the palette to use.
format | Format of pPalette data
Note:
It is only legal to call this function after the texture has been uploaded when the texture is flagged as Modifiable.
Required Header Files
IwTexture.h

const uint8* CIwTexture::GetPalette ( ) const [inline]

Gets a pointer to the palette data.

Returns:
Pointer to the palette data.
See also:
GetTexels
Note:
It is illegal to call this function after the texture has been uploaded. If you wish to get a copy of the palette data after the texture has been uploaded, you must use GetPaletteFromVRAM().
Required Header Files
IwTexture.h

const CIwColour* CIwTexture::GetPaletteCacheRGBs ( ) const [inline]

Get the palette cache RGB multipliers.

Returns:
Pointer to current palette cache RGB multipliers.
Required Header Files
IwTexture.h

int32 CIwTexture::GetPaletteMemSize ( ) const [inline]

Gets the size of the palette data in bytes.

Returns:
The size of the palette data in bytes.
See also:
GetTexelsMemSize
Required Header Files
IwTexture.h

int32 CIwTexture::GetPaletteNumEntries ( ) const [inline]

Get palette size (0, 16, 32, 64, 128, 256).

Returns:
the number of entries in the palette
See also:
GetTexelsMemSize
Required Header Files
IwTexture.h

uint32 CIwTexture::GetPitch ( ) const [inline]

Gets the pitch of the texel data, in bytes.

Returns:
The pitch of the texel data, in bytes.
Note:
It is illegal to call this function after the texture has been uploaded.
Required Header Files
IwTexture.h

void CIwTexture::GetTexels | ( | uint8 * | pTexels,
 |  | CIwImage::Format | format |
 | ) |  |  | const

Get a copy of the texture's texel data in the specified format. No conversion will occur if the format matches the internal format of the texture.

Returns:
Pointer to the source image texel data.
See also:
GetPalette, ChangeTexels
Note:
It is illegal to call this function after the texture has been uploaded unless the texture has been marked as modifiable using CIwTexture::SetModifiable or the 'keepAfterUpload' image template parameter.

The format conversion cannot require the palette to be changed. E.g. if the internal texture format is PALETTE4_RGB_565 it is illegal to call GetTexels with any format that is not a 4bit palettised format. In a HW build the internal format is the format of the original image loaded (the data is retained in application memory for manipulation). In a SW build the format will be the chosen VRAM format (retreivable using GetFormatSW()). In a SW/HW build either will work, but the source image must be palettised to the same order as the FormatSW. In a SW build, prior to upload the format will be the original source image format. Therefore, for HW-agnostic texel swapping either perform texel substitution before upload, or ensure that the source image is palettised to 4bit or 8bit, or is unpalettised in a 16bit format (these formats will not change palettisation on upload).

: Changing texels on a palettised source image in a HW build will likely be slow.

Required Header Files
IwTexture.h

const uint8* CIwTexture::GetTexels ( ) const [inline]

Gets a pointer to the source image texel data.

Returns:
Pointer to the source image texel data.
See also:
GetPalette
Note:
It is illegal to call this function after the texture has been uploaded unless the texture has been marked as modifiable using CIwTexture::SetModifiable or the 'keepAfterUpload' image template parameter.
Required Header Files
IwTexture.h

int32 CIwTexture::GetTexelsMemSize ( ) const [inline]

Gets the size of the texel data in bytes.

Returns:
The size of the texel data in bytes.
See also:
GetPaletteMemSize
Required Header Files
IwTexture.h

uint32 CIwTexture::GetWidth ( ) const [inline]

Gets texture width.

Returns:
The texture width, in texels.
See also:
GetHeight, GetDepth, GetFormat, GetFlags
Required Header Files
IwTexture.h

uint8 CIwTexture::HasAlpha ( ) const [inline]

Indicates whether the image has an alpha channel.

Returns:
1 if an alpha channel is present and 0 otherwise
Required Header Files
IwTexture.h

void CIwTexture::LoadFromFile ( const char * imageFile )

Loads image data from a file.

Parameters:
imageFile Filename of the image file to load.
Required Header Files
IwTexture.h

void CIwTexture::RemakeMipmaps ( )

Remakes the texture's mipmaps.

Note:
Only affects software rasterisation.
Required Header Files
IwTexture.h

virtual void CIwTexture::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwTexture::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwTexture::SetClamping ( bool bOn )

Sets whether or not the texture should use clamping.

Parameters:
bOn True only if the texture should use clamping.
See also:
GetClamping
Required Header Files
IwTexture.h

void CIwTexture::SetFiltering ( bool bOn )

Sets whether or not the texture should use bilinear filtering.

Parameters:
bOn True only if the texture should use bilinear filtering.
See also:
GetFiltering
Required Header Files
IwTexture.h

void CIwTexture::SetFormatHW ( CIwImage::Format formatHW ) [inline]

Sets the enumerated texture format. This is the target texture format for the HW device. Only certain formats are supported and some maybe inoptimal, depending on the HW device.

Parameters:
formatHW The target format
Returns:
The enumerated texture format.
See also:
GetFormatSW, GetFormatHW, GetWidth, GetHeight, GetDepth, GetFlags

void CIwTexture::SetFormatSW ( CIwImage::Format formatSW ) [inline]

Sets the enumerated texture format. This is the target texture format for the SW device. The texture image is converted to this format on UpLoad(); Only certain formats are supported: CIwImage::FORMAT_UNDEFINED <default> An appropriate SW format is assigned on Upload(). * CIwImage::PALETTE4_ABGR_1555 4bit paletted. CIwImage::PALETTE8_ABGR_1555 8bit paletted CIwImage::ABGR_1555 16bit. CIwImage::RGB_565 16bit native. CIwImage::PALETTE4_ABGR_4444 4bit paletted. CIwImage::ABGR_4444 16bit. CIwImage::ARGB_8888 32bit.

Parameters:
formatSW The target format
See also:
GetFormatSW, GetFormatHW, GetWidth, GetHeight, GetDepth, GetFlags

void CIwTexture::SetImage ( CIwImage * pImg )

Sets image data to be the passed image. Any current image will be cleared. Ownership of pImg's texels and palette will pass to the texture.

Parameters:
pImg A pointer to the source image
Required Header Files
IwTexture.h

void CIwTexture::SetMipMapping ( bool bOn )

Sets whether or not the texture should use mipmapping.

Parameters:
bOn True only if the texture should use mipmapping.
See also:
GetMipMapping
Required Header Files
IwTexture.h

void CIwTexture::SetModifiable ( bool modifiable )

Marks the texture as modifiable or not ensuring its data is kept after uploading if set.

Parameters:
modifiable true if the texture is modifiable
Required Header Files
IwTexture.h

void CIwTexture::SetPaletteCacheRGBs | ( | CIwColour * | pCols,
 |  | bool | owned = false
 | ) |  |

Set the 32 palette cache RGB multipliers

Parameters:
pCols | new palette cache RGB multipliers to set
owned | True if pCols' memory should become owned by this texture, otherwise ownership remains with caller.
Required Header Files
IwTexture.h

virtual void CIwTexture::Upload ( ) [virtual]

Uploads the texture to VRAM.

Note:
A texture cannot be used until it has been uploaded. The Airplay software renderer maintains its own area of memory (referred to as VRAM) which is uses to store textures and their mipmaps. Hardware-accelerated sub-systems may maintain their own driver-side copies of textures. For example, if using OpenGL ES, this function will create the OpenGL ES texture on the driver side.

void CIwTexture::UseAsHandle ( CIwTexture * pTex )

Sets this texture object to be a handle to the passed texture. In future when this texture is used, pTex will be used instead. This can be useful for using dynamic textures with resources, for example, if a double buffered frame buffer is being bound.

Note:
The lifetime of the this object must not exceed the lifetime of the target texture.
Parameters:
pTex the texture to act as a handle to.
Required Header Files
IwTexture.h

bool CIwTexture::UsesAlpha ( uint8 threshold = 0xff ) const [inline]

Indicates whether this image uses its alpha channel (if it has one). i.e. whether any alpha value is under threshold

Returns:
true if uses an alpha channel, otherwise false
Required Header Files
IwTexture.h

bool CIwTexture::UsesChromakey ( ) const [inline]

Indicates whether this image uses a chromakey value, i.e. whether it ordinarily would display a texel value of (0xff, 0x00, 0xff).

Returns:
true if uses a chromakey value, otherwise false
Required Header Files
IwTexture.h

Friends And Related Function Documentation

void IwGxSetMaterial ( CIwMaterial * pMat ) [friend]

Sets the current material. This defines the entire render state.

Parameters:
pMat Pointer to the material the set.
See also:
IwGxGetMaterial, IwGxSetMaterialFixed
Note:
This function has no effect if a fixed material has been set using IwGxSetMaterialFixed().
Required Header Files
IwGx.h

Field Documentation

uint32 CIwTexture::m_Flags [protected]

e.g. USES_TRANSPARENCY_F

uint8 CIwTexture::m_FormatHW [protected]

Preferred format for hardware rendering.

uint8 CIwTexture::m_FormatSW [protected]

Preferred format for software rendering.

uint16 CIwTexture::m_GLOTIndex

index used to place poly in OT;

uint32 CIwTexture::m_HWID

OpenGLES texture ID ("texture name").

CIwColour* CIwTexture::m_PaletteCacheRGBs

if non-NULL, use these (32?) values as colour multipliers when generating the palettes

uint8 CIwTexture::m_UShiftFactor

factor for converting application u to GL fixed pt u; (left shift u by this factor);

CIwTPageInfo CIwTexture::m_VRAMInfo

IwRenderer VRAM info for image and palette.

uint8 CIwTexture::m_VShiftFactor

factor for converting application v to GL fixed pt v; (left shift v by this factor);

The documentation for this class was generated from the following file:
  • IwTexture.h


Airplay API Reference: CIwUIAlertDialog

Airplay API Reference > Data Structures > CIwUIAlertDialog >

CIwUIAlertDialog Class Reference
[Elements, Elements]

Alert dialog box, with one or more buttons.

#include <IwUIAlertDialog.h>

Inheritance diagram for CIwUIAlertDialog:

[legend]

Public Member Functions

void | AttachButtonClickSlot (bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | AttachButtonClickSlot (CIwUIElement *pElement, const char *pSlotName)
void | DetachButtonClickSlot (bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | DetachButtonClickSlot (CIwUIElement *pElement, const char *pSlotName)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIElement * | FindWantsFocus ()
virtual CIwUIRect | GetElementBounds () const
virtual bool | HandlesFocus () const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)

Member Function Documentation

virtual void CIwUIAlertDialog::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUIAlertDialog::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

void CIwUIAlertDialog::AttachButtonClickSlot | ( | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Attach a slot in the hierarchy to this alert dialog's button clicked signal.

Parameters:
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of class or object used to register slot.
pSlotName | Name of slot we are attaching.

void CIwUIAlertDialog::AttachButtonClickSlot | ( | CIwUIElement * | pElement,
 |  | const char * | pSlotName
 | ) |  |

Attach an element's slot to this alert dialog's button clicked signal.

Parameters:
pElement | Ptr to element whose slot we are attaching.
pSlotName | Name of slot we are attaching.

virtual void CIwUIAlertDialog::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

void CIwUIAlertDialog::DetachButtonClickSlot | ( | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Detach a slot in the hierarchy from this alert dialog's button clicked signal.

Parameters:
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of class or object used to register slot.
pSlotName | Name of slot we are detaching.

void CIwUIAlertDialog::DetachButtonClickSlot | ( | CIwUIElement * | pElement,
 |  | const char * | pSlotName
 | ) |  |

Detach an element's slot from this alert dialog's button clicked signal.

Parameters:
pElement | Ptr to element whose slot we are detaching.
pSlotName | Name of slot we are detaching.

virtual CIwUIElement* CIwUIAlertDialog::FindWantsFocus ( ) [protected, virtual]

Chooses an appropriate focus element. This can either be the element itself or one of its children.

Returns:
Pointer to element which wants focus, or NULL if none found.

Reimplemented from CIwUIElement.

virtual CIwUIRect CIwUIAlertDialog::GetElementBounds ( ) const [protected, virtual]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIElement.

virtual bool CIwUIAlertDialog::HandlesFocus ( ) const [protected, virtual]

This element wants to choose its own focus element where possible.

Returns:
By default, returns true if either the element itself wants focus or it has an attached focus handler which is able to determine a child to have focus.

Reimplemented from CIwUIElement.

virtual CIwVec2 CIwUIAlertDialog::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUIAlertDialog::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

virtual void CIwUIAlertDialog::OnSizeChanged ( ) [protected, virtual]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIElement.

virtual void CIwUIAlertDialog::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUIAlertDialog.h


Airplay API Reference: CIwUIAnimation

Airplay API Reference > Data Structures > CIwUIAnimation >

CIwUIAnimation Class Reference
[Animation, Animation]

Animation resource. Contains a list of keyframes ordered by time.

#include <IwUIAnimation.h>

Inheritance diagram for CIwUIAnimation:

[legend]

Public Member Functions

const CIwUIAnimKeyFrame * | GetKeyFrame (int index) const
int | GetNumKeyFrames () const
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual void | Resolve ()
virtual void | Serialise ()

Member Function Documentation

void CIwUIAnimation::AttachPropertySets ( )

Ensure key frame property sets have the correct parent's attached according to the styles.

virtual void CIwUIAnimation::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwUIAnimation::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwUIAnimation::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwUIAnimation::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

const CIwUIAnimKeyFrame* CIwUIAnimation::GetKeyFrame ( int index ) const

Provides read-only access to keyframe data.

Returns:
Pointer to animation keyframe.

int CIwUIAnimation::GetNumKeyFrames ( ) const

The index passed to GetFrame must be smaller than this value.

Returns:
The number of keyframes in the animation.

virtual void CIwUIAnimation::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIAnimation::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIAnimation::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIAnimation::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

The documentation for this class was generated from the following file:
  • IwUIAnimation.h


Airplay API Reference: CIwUIAnimator

Airplay API Reference > Data Structures > CIwUIAnimator >

CIwUIAnimator Class Reference
[Animation, Animation]

Represents an animation playing on an element.

#include <IwUIAnimManager.h>

Public Member Functions

int32 | GetAnimationTime () const
uint32 | GetHandle () const
int32 | GetKeyFrame () const
const CIwPropertySet * | GetKeyFrameData (int index) const
int32 | GetKeyFrameTime (int index) const
int | GetNumKeyFrames () const
IIwUIAnimatorObserver * | GetObserver () const
CIwUIElement * | GetTarget () const
int32 | GetTime () const
void | SetObserver (IIwUIAnimatorObserver *pObserver)
bool | SetTime (int32 time)
void | Stop (bool stopNextUpdate=false)
bool | Update (int32 deltaMS)

Member Function Documentation

int32 CIwUIAnimator::GetAnimationTime ( ) const

Get the total length of the animation.

Returns:
Total animation time
Return values:
INT32_MAX If animation is set to loop.
Note:
Not scaled by speed.

uint32 CIwUIAnimator::GetHandle ( ) const [inline]

Returns the handle associate by the animation manager with this animator.

Returns:
Animator handle.

int32 CIwUIAnimator::GetKeyFrame ( ) const [inline]

Get the index of the keyframe currently active.

Returns:
Keyframe index.

const CIwPropertySet* CIwUIAnimator::GetKeyFrameData ( int index ) const

Provides read-only access to keyframe data.

Returns:
Pointer to the properties associated with a keyframe.

int32 CIwUIAnimator::GetKeyFrameTime ( int index ) const

Get the time of a keyframe in the playing animation.

Returns:
Keyframe time.

int CIwUIAnimator::GetNumKeyFrames ( ) const

Query the number of keyframes in the playing animation.

Returns:
Index passed to GetKeyFrameTime or GetKeyFrameData must be less than this value.

IIwUIAnimatorObserver* CIwUIAnimator::GetObserver ( ) const [inline]

Returns:
Animator's observer, or NULL if not set.

CIwUIElement* CIwUIAnimator::GetTarget ( ) const [inline]

Get the element this animation is playing on.

Returns:
Pointer to an element, or NULL if it has been destroyed.

int32 CIwUIAnimator::GetTime ( ) const [inline]

Get the progress time through the playing animation.

Returns:
Progress time.

void CIwUIAnimator::SetObserver ( IIwUIAnimatorObserver * pObserver ) [inline]

Parameters:
pObserver Observer to attach to animator
Note:
Animator will not destroy the observer

bool CIwUIAnimator::SetTime ( int32 time )

Parameters:
time The progress of the animation to set.
Returns:
True if animation has not finished and time successfully set.

void CIwUIAnimator::Stop ( bool stopNextUpdate = false )

Stops animation. Restores element properties if originally requested.

Parameters:
stopNextUpdate Stop next update, rather than immediately.

bool CIwUIAnimator::Update ( int32 deltaMS )

Updates animated properties on the element.

Returns:
False when animation finished.

The documentation for this class was generated from the following file:
  • IwUIAnimManager.h


Airplay API Reference: CIwUIAnimData

Airplay API Reference > Data Structures > CIwUIAnimData >

CIwUIAnimData Class Reference
[Animation, Animation]

Provides animation data to animated elements.

#include <IwUIAnimData.h>

Public Member Functions

void | AnimateDrawableStyle (IIwUIDrawable *pDrawable, const char *pStyleName) const
template<class Type>
bool | AnimateProperty (const char *propDef, Type &val) const

Member Function Documentation

void CIwUIAnimData::AnimateDrawableStyle | ( | IIwUIDrawable * | pDrawable,
 |  | const char * | pStyleName |
 | ) |  |  | const

Used to animate a drawable's properties which are from a style.

Parameters:
pDrawable | Drawable to animate
pStyleName | Name of the style which contains the drawables properties.

template<class Type>
bool CIwUIAnimData::AnimateProperty | ( | const char * | propDef,
 |  | Type & | val |
 | ) |  |  | const [inline]

Calculates interpolated value of an animation property. The value is stored in the elements property set and the provided reference.

Parameters:
propDef | Name of property to animate
val | Reference to return animated value in
Returns:
If appropriate source values were found to animate the value and this value is different from that current stored in the elements property set.

The documentation for this class was generated from the following file:
  • IwUIAnimData.h


Airplay API Reference: CIwUIAnimDataLocator

Airplay API Reference > Data Structures > CIwUIAnimDataLocator >

CIwUIAnimDataLocator Class Reference
[Animation, Animation]

Interface for obtaining animation data by property name. Iterates over keyframe data to find corresponding properties. More...

#include <IwUIAnimData.h>

Detailed Description

Also, finds or creates an appropriate property set to store interpolated values on the element being animated.

Member Function Documentation

virtual CIwPropertySet* CIwUIAnimDataLocator::CreateDestination ( ) [pure virtual]

Finds or creates an appropriate property set on the animated element's property set.

virtual void CIwUIAnimDataLocator::DecrementCurrent ( ) [pure virtual]

Decrements current search index.

virtual const CIwPropertySet* CIwUIAnimDataLocator::GetBase ( ) const [pure virtual]

Get appropriate property set of the animated element which contains the current value.

virtual const CIwPropertySet* CIwUIAnimDataLocator::GetCurrent ( int32 & time ) [pure virtual]

Returns property set for current source.

template<class Type>
bool CIwUIAnimDataLocator::GetCurrent | ( | const char * | propDef,
 |  | Type & | val,
 |  | int32 & | time |
 | ) |  |  | [inline]

Finds the current source value of a given property by stepping back from the current keyframe until the property is found.

virtual const CIwPropertySet* CIwUIAnimDataLocator::GetNext ( int32 & time ) [pure virtual]

Returns property set for next source.

template<class Type>
bool CIwUIAnimDataLocator::GetNext | ( | const char * | propDef,
 |  | Type & | val,
 |  | int32 & | time |
 | ) |  |  | [inline]

Finds the next source value of a given property by stepping forward from the next keyframe until the property is found.

virtual void CIwUIAnimDataLocator::IncrementNext ( ) [pure virtual]

Increments next search index.

virtual void CIwUIAnimDataLocator::ResetCurrent ( ) [pure virtual]

Reset current source index.

virtual void CIwUIAnimDataLocator::ResetNext ( ) [pure virtual]

Reset next source index.

The documentation for this class was generated from the following file:
  • IwUIAnimData.h


Airplay API Reference: CIwUIAnimDataType

Airplay API Reference > Data Structures > CIwUIAnimDataType< Type > >

CIwUIAnimDataType< Type > Class Template Reference
[Animation, Animation]

Templated class to interpolate a type.

#include <IwUIAnimData.h>

Static Public Member Functions

static Type Interpolate (const Type &start, const Type &end, iwfixed prop)

template<class Type>
class CIwUIAnimDataType< Type >

Member Function Documentation

template<class Type>
static Type CIwUIAnimDataType< Type >::Interpolate | ( | const Type & | start,
 |  | const Type & | end,
 |  | iwfixed | prop |
 | ) |  |  | [static]

Interpolates between start and end values.

Parameters:
prop Fixed point interpolation value
Note:
This function has to be implemented for each type which is required to be interpolated by the animation system.

The documentation for this class was generated from the following file:
  • IwUIAnimData.h


Airplay API Reference: CIwUIAnimKeyFrame

Airplay API Reference > Data Structures > CIwUIAnimKeyFrame >

CIwUIAnimKeyFrame Class Reference
[Animation, Animation]

Animation key frame. Animation resources are made up of key frames. Each keyframe specifies the value of properties at a particular time through an animation.

#include <IwUIAnimation.h>

Inheritance diagram for CIwUIAnimKeyFrame:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | Resolve ()
virtual void | Serialise ()
virtual void | SetName (const char *pName)
Public interface
void | AddProperty (CIwPropertyBase *pProperty)
bool | ContainsProperty (uint32 propertyDefine) const
CIwUIPropertySet & ExposePropertySet ()
const CIwUIPropertySet & | GetPropertySet () const
int32 | GetTime () const
template<class Type>
bool | SetProperty (const char *pName, const Type &val)
void | SetTime (int32 time)

Member Function Documentation

void CIwUIAnimKeyFrame::AddProperty ( CIwPropertyBase * pProperty )

Add a property to the keyframe.

Parameters:
pProperty Property to become owned by keyframe's property set.

bool CIwUIAnimKeyFrame::ContainsProperty ( uint32 propertyDefine ) const

Query if a property is present on the keyframe.

Parameters:
propertyDefine Hash of the name of a property.
Returns:
True if the a property is found with the given hash.

virtual void CIwUIAnimKeyFrame::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwUIAnimKeyFrame::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwUIAnimKeyFrame::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwUIAnimKeyFrame::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

CIwUIPropertySet& CIwUIAnimKeyFrame::ExposePropertySet ( ) [inline]

Expose the keyframes property set.

Returns:
Reference to the keyframe's property set.
Note:
It is not advisable to mutate properties on keyframes which are part of an animation resource.

const CIwUIPropertySet& CIwUIAnimKeyFrame::GetPropertySet ( ) const [inline]

Provides read-only access to the keyframe's properties.

Returns:
Reference to the keyframe's property set.

int32 CIwUIAnimKeyFrame::GetTime ( ) const [inline]

Get time of keyframe.

Returns:
Time of keyframe through an animation.

virtual bool CIwUIAnimKeyFrame::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

virtual void CIwUIAnimKeyFrame::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIAnimKeyFrame::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

virtual void CIwUIAnimKeyFrame::SetName ( const char * pName ) [virtual]

Set name (hashed value)

Parameters:
pName the hashed name of the managed object
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

template<class Type>
bool CIwUIAnimKeyFrame::SetProperty | ( | const char * | pName,
 |  | const Type & | val |
 | ) |  |  | [inline]

Set the value of a property on the keyframe.

Parameters:
pName | Name of property to set.
val | Value of property to set on keyframe's property set.

void CIwUIAnimKeyFrame::SetTime ( int32 time ) [inline]

Set the time of keyframe.

Parameters:
time Time value to set in milliseconds.
Note:
Time should not be set if the keyframe is within an animation.

The documentation for this class was generated from the following file:
  • IwUIAnimation.h


Airplay API Reference: CIwUIAnimManager

Airplay API Reference > Data Structures > CIwUIAnimManager >

CIwUIAnimManager Class Reference
[Animation, Animation]

Animation manager singleton. Provides an interface for playing and controlling an animation on an element. Updated by CIwUIView.

#include <IwUIAnimManager.h>

Public Member Functions

bool | IsAnimPlaying () const
uint32 | PlayAnim (const char *pAnimResName, CIwUIElement *pElement, bool onFinishRestore=false, bool looping=false, int32 blendInTime=-1, int32 blendOutTime=-1, iwfixed speed=IW_GEOM_ONE)
bool | SetObserver (uint32 handle, IIwUIAnimatorObserver *pObserver)
bool | SetTime (uint32 handle, int32 time)
bool | Update (int32 deltaMS)

Member Function Documentation

bool CIwUIAnimManager::IsAnimPlaying ( ) const

Returns:
If there are any animations currently playing

uint32 CIwUIAnimManager::PlayAnim | ( | const char * | pAnimResName,
 |  | CIwUIElement * | pElement,
 |  | bool | onFinishRestore = false,
 |  | bool | looping = false,
 |  | int32 | blendInTime = -1,
 |  | int32 | blendOutTime = -1,
 |  | iwfixed | speed = IW_GEOM_ONE
 | ) |  |

Plays an animation on the given element. Returns a handle to allow controlling the playing animation.

Parameters:
pAnimResName | Name of an animation resource, stored in the resource manager, to play.
pElement | Element to play animation on.
onFinishRestore | Should the elements properties be restored to their previous value when the animation is stopped or finishes.
looping | Should the animation loop until stopped.
blendInTime | Time to blend to the first keyframe.
blendOutTime | Time to blend from the final keyframe back to the elements original properties.
Note:
Blending out () and restoring () are different. Blending out may leave additional properties set on the element, restoring ensures the elements property set is returned to its original state.
Returns:
Handle which can be passed to

bool CIwUIAnimManager::SetObserver | ( | uint32 | handle,
 |  | IIwUIAnimatorObserver * | pObserver
 | ) |  |

Attaches an observer to a playing animation.

Parameters:
handle | Handle return be previous call to
pObserver | Observer to set on animator.
Returns:
Boolean indicating if the observer was set.

bool CIwUIAnimManager::SetTime | ( | uint32 | handle,
 |  | int32 | time
 | ) |  |

Set the progress of a playing animation.

Parameters:
handle | Handle return be previous call to
time | Progress time to set
Note:
The element's properties will be updated next time the animator is updated
Returns:
Boolean indicating if the progress was successfully set.

void CIwUIAnimManager::StopAllAnims ( bool stopNextUpdate = false )

Stop all currently playing animations.

bool CIwUIAnimManager::StopAnim | ( | CIwUIElement * | pElement,
 |  | bool | stopNextUpdate = false
 | ) |  |

Stops all animations playing on an element.

bool CIwUIAnimManager::StopAnim | ( | uint32 | handle,
 |  | bool | stopNextUpdate = false
 | ) |  |

Stop animation using handle previously returned by .

bool CIwUIAnimManager::Update ( int32 deltaMS )

Updates currently playing animations. By default, this is called by CIwUIView::Update.

Returns:
False when no animations are playing, that is, any previously playing animations have completed.

The documentation for this class was generated from the following file:
  • IwUIAnimManager.h


Airplay API Reference: CIwUIButton

Airplay API Reference > Data Structures > CIwUIButton >

CIwUIButton Class Reference
[Elements, Elements]

Button widget. If the user touches the button, or presses ok whilst the button has focus, it will generate a ButtonPress event with itself as the source. More...

#include <IwUIButton.h>

Inheritance diagram for CIwUIButton:

[legend]

Public Member Functions

void | AttachClickSlot (bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | AttachClickSlot (CIwUIElement *pElement, const char *pSlotName)
void | DetachClickSlot (bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | DetachClickSlot (CIwUIElement *pElement, const char *pSlotName)
void | SetCaption (const char *pString)
void | SetEnabled (bool val)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIRect | GetElementBounds () const
virtual bool | HandleEventClick (CIwUIEventClick *pEventClick)
virtual bool | HandleEventFocus (CIwUIEventFocus *pEventFocus)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | HandleEventPointerEnter (CIwUIEventPointerEnter *pEventPointerEnter)
virtual bool | HandleEventPointerLeave (CIwUIEventPointerLeave *pEventPointerLeave)
virtual bool | IntersectElement (const CIwVec2 &pos) const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)
virtual bool | WantsFocus () const

Detailed Description

Buttons have the following properties:

Type | Name | Description
CIwUIStyle | buttonUp | Drawable style to use for this button's 'up' graphic.
CIwUIStyle | buttonDown | Drawable style to use for this button's 'down' graphic.
CIwPropertyString | caption | Caption to display on the button.
CIwSVec2 | margin | Margin, in pixels, to impose between the caption and the button graphic.
bool | enabled | Whether this button is enabled, and thus should respond to user interactions. When disabled, the button's colour will be modulated by its colourDisabled property.
CIwColour | colourDisabled | Colour to modulate the element by when it is disabled.

Member Function Documentation

virtual void CIwUIButton::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

virtual void CIwUIButton::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

void CIwUIButton::AttachClickSlot | ( | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Attach a slot in the hierarchy to this button's click signal.

Parameters:
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of class or object used to register slot.
pSlotName | Name of slot we are attaching.

void CIwUIButton::AttachClickSlot | ( | CIwUIElement * | pElement,
 |  | const char * | pSlotName
 | ) |  |

Attach an element's slot to this button's click signal.

Parameters:
pElement | Ptr to element whose slot we are attaching.
pSlotName | Name of slot we are attaching.

virtual void CIwUIButton::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

void CIwUIButton::DetachClickSlot | ( | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Detach a slot in the hierarchy from this button's click signal.

Parameters:
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of class or object used to register slot.
pSlotName | Name of slot we are detaching.

void CIwUIButton::DetachClickSlot | ( | CIwUIElement * | pElement,
 |  | const char * | pSlotName
 | ) |  |

Detach an element's slot from this button's click signal.

Parameters:
pElement | Ptr to element whose slot we are detaching.
pSlotName | Name of slot we are detaching.

virtual CIwUIRect CIwUIButton::GetElementBounds ( ) const [protected, virtual]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

virtual bool CIwUIButton::HandleEventClick ( CIwUIEventClick * pEventClick ) [protected, virtual]

Handle a pointer click event.

Parameters:
pEventClick The click event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUIButton::HandleEventFocus ( CIwUIEventFocus * pEventFocus ) [protected, virtual]

Handle focus changes.

Parameters:
pEventFocus The focus event to handle.
Note:
Focus handlers should generally return false so that all elements in the focus chain receive the event.

Reimplemented from CIwUIElement.

virtual bool CIwUIButton::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUIButton::HandleEventPointerEnter ( CIwUIEventPointerEnter * pEventPointerEnter ) [protected, virtual]

Handle a pointer enter event, which is issued when the pointer moves into a position which intersects this element.

Parameters:
pEventPointerEnter The pointer enter event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUIButton::HandleEventPointerLeave ( CIwUIEventPointerLeave * pEventPointerLeave ) [protected, virtual]

Handle a pointer leave event, which is issued when the pointer moves into a position which doesn't intersect this element (either because it intersects another element before this, or just because it doesn't intersect with this), or in the case of a touchscreen when the screen is 'released'.

Parameters:
pEventPointerLeave The pointer leave event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUIButton::IntersectElement ( const CIwVec2 & pos ) const [protected, virtual]

Test whether the specified position intersects with this element.

Note:
Custom elements wishing which wish to be clicked on should override this function.
Return values:
true | If the specified position intersects with this element.
false | If it doesn't.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

virtual CIwVec2 CIwUIButton::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUIButton::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

virtual void CIwUIButton::OnSizeChanged ( ) [protected, virtual]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

virtual void CIwUIButton::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIElement.

Reimplemented in CIwUIRadioButton.

void CIwUIButton::SetCaption ( const char * pString )

Set "caption" property for this button, updating its graphical representation if necessary.

Parameters:
pString String / localisation ID property to set.

void CIwUIButton::SetEnabled ( bool val )

Set "enabled" property for this button, updating its graphical representation if necessary. When disabled, the button won't respond to user input.

Parameters:
val True to enable, false to disable.

virtual bool CIwUIButton::WantsFocus ( ) const [inline, protected, virtual]

Query the element and return whether it supports/wants keyboard focus.

Returns:
By default, returns false. Overridden by derived elements.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUIButton.h


Airplay API Reference: CIwUICheckbox

Airplay API Reference > Data Structures > CIwUICheckbox >

CIwUICheckbox Class Reference
[Elements, Elements]

Check box element. Has an on / off graphic [+ label] [+ background]. More...

#include <IwUICheckbox.h>

Inheritance diagram for CIwUICheckbox:

[legend]

Public Member Functions

bool | GetChecked () const
void | SetChecked (bool val)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIRect | GetElementBounds () const
virtual bool | HandleEventClick (CIwUIEventClick *pEventClick)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | IntersectElement (const CIwVec2 &pos) const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)
virtual bool | WantsFocus () const

Detailed Description

Checkboxes use the following properties:

Type | Name | Description
CIwUIStyle | boxStyle | Drawable style to use to render the checkbox box graphic.
CIwUIStyle | crossStyle | Drawable style to use to render the checkbox cross graphic.
CIwVec2 | boxSize | Size, in pixels, of the box and cross graphics.
CIwPropertyString | caption | Caption to show next to the check box.
CIwPropertyString | localiseCaption | Identifier for Localised Caption to show next to the check box.
CIwGxFont* | font | Font to use to render the caption.
CIwSVec2 | margin | Margin to impose between the checkbox graphic and text and its frame.
bool | sizeToContent | Whether the size of the checkbox should be automatically modified to just fit the caption.
CIwUIStyle | background | Drawable style to use to render the checkbox's background graphic.

Member Function Documentation

virtual void CIwUICheckbox::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUICheckbox::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

virtual void CIwUICheckbox::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

bool CIwUICheckbox::GetChecked ( ) const

Get checkbox value

Returns:
If the checkbox is checked

virtual CIwUIRect CIwUICheckbox::GetElementBounds ( ) const [protected, virtual]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIElement.

virtual bool CIwUICheckbox::HandleEventClick ( CIwUIEventClick * pEventClick ) [protected, virtual]

Handle a pointer click event.

Parameters:
pEventClick The click event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUICheckbox::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUICheckbox::IntersectElement ( const CIwVec2 & pos ) const [protected, virtual]

Test whether the specified position intersects with this element.

Note:
Custom elements wishing which wish to be clicked on should override this function.
Return values:
true | If the specified position intersects with this element.
false | If it doesn't.

Reimplemented from CIwUIElement.

virtual CIwVec2 CIwUICheckbox::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUICheckbox::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

virtual void CIwUICheckbox::OnSizeChanged ( ) [protected, virtual]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIElement.

virtual void CIwUICheckbox::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIElement.

void CIwUICheckbox::SetChecked ( bool val )

Set checkbox value.

Parameters:
val If checked or unchecked.

virtual bool CIwUICheckbox::WantsFocus ( ) const [inline, protected, virtual]

Query the element and return whether it supports/wants keyboard focus.

Returns:
By default, returns false. Overridden by derived elements.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUICheckbox.h


Airplay API Reference: CIwUIColour

Airplay API Reference > Data Structures > CIwUIColour >

CIwUIColour Class Reference
[Utility Classes, Utility Classes]

Derived from CIwColour. Adds functionality such as parsing.

#include <IwUIColour.h>

Inheritance diagram for CIwUIColour:

[legend]

Public Member Functions

Public operators
CIwUIColour | operator * (const CIwUIColour &other) const
CIwColour & | operator *= (const CIwColour &other)
CIwColour & | operator= (const CIwColour &other)
Public interface
void | Parse (CIwTextParserITX *pParser)
void | Serialise ()
void | SetColourFixed (IwGxColourFixed fixedCol)

Member Function Documentation

CIwUIColour CIwUIColour::operator * ( const CIwUIColour & other ) const

Multiplication operator.

Parameters:
other Second operand.
Returns:
Colour with component wise products.

CIwColour& CIwUIColour::operator *= ( const CIwColour & other ) [inline]

Multiplication assignment operator. Multiply this colour by the given colour and assign to this colour.

Parameters:
other Second operand.
Returns:
Reference to this colour.

Reimplemented from CIwColour.

CIwColour& CIwUIColour::operator= ( const CIwColour & other )

Assignment operator. Copies colour components from given colour.

Parameters:
other Source colour.
Returns:
Reference to this colour.

void CIwUIColour::Parse ( CIwTextParserITX * pParser )

Parse colour components.

Parameters:
pParser Pointer to text parser to read from.

void CIwUIColour::Serialise ( )

Serialise colour components.

Parameters:

void CIwUIColour::SetColourFixed ( IwGxColourFixed fixedCol )

Set colour components from a fixed colour.

Parameters:
fixedCol Enumerated value of desired fixed colour.

The documentation for this class was generated from the following file:
  • IwUIColour.h


Airplay API Reference: CIwUIController

Airplay API Reference > Data Structures > CIwUIController >

CIwUIController Class Reference
[Events, Events]

UI event-handling singleton. More...

#include <IwUIController.h>

Inheritance diagram for CIwUIController:

[legend]

Protected virtuals

virtual bool | FilterEvent (CIwEvent *pEvent)
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual bool | Notify (CIwUIElement *pReceiver, CIwEvent *pEvent)

Public Member Functions

Public interface
void | AddEventHandler (IIwUIEventHandler *pEventHandler)
void | BroadcastEvent (CIwEvent *pEvent)
bool | HasPointerCapture (CIwUIElement *pElement)
bool | IsFilteringEvent (IIwUIEventHandler *pFilter=NULL) const
bool | IsHandlingEvent (IIwUIEventHandler *pHandler=NULL) const
virtual void | PostEvent (CIwUIElement *pReceiver, CIwEvent *pEvent)
void | RemoveEventHandler (IIwUIEventHandler *pEventHandler)
bool | SendEvent (CIwUIElement *pReceiver, CIwEvent *pEvent)
Declared virtuals

Data Structures

struct | QueuedEvent

Detailed Description

A CIwUIController (or derived) instance must exist for IwUI to operate.

Member Function Documentation

void CIwUIController::AddEventHandler ( IIwUIEventHandler * pEventHandler )

Add an application-wide event handler. Note, the caller maintains ownership of the handler object.

Parameters:
pEventHandler Object through which all events will be passed. The object must should implement either HandleEvent and/or FilterEvent virtuals, returning true if the event was handled/filtered and shouldn't be propagated further.

void CIwUIController::BroadcastEvent ( CIwEvent * pEvent )

Broadcast an event to all active elements.

Parameters:
pEvent The event to broadcast.

virtual bool CIwUIController::FilterEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-filter. Calls through to registered event handlers.

See also:
AddEventHandler()
Parameters:
pEvent Event to be filtered.
Returns:
Boolean value signifying whether the event was filtered.

virtual bool CIwUIController::HandleEvent ( CIwEvent * pEvent ) [protected, virtual]

Function which is called if an event is unhandled all the way to the application level.

Note:
Subclasses are encouraged to reimplement this function. The default implementation calls through to registered event handlers.

bool CIwUIController::HasPointerCapture ( CIwUIElement * pElement )

Returns:
Does element own captured pointer

bool CIwUIController::IsFilteringEvent ( IIwUIEventHandler * pFilter = NULL ) const

Returns:
If the given handler, or any handler if NULL passed, is currently filtering an event.

bool CIwUIController::IsHandlingEvent ( IIwUIEventHandler * pHandler = NULL ) const

Returns:
If the given handler, or any handler if NULL passed, is currently handling an event.

virtual bool CIwUIController::Notify | ( | CIwUIElement * | pReceiver,
 |  | CIwEvent * | pEvent |
 | ) |  |  | [protected, virtual]

Common interface which SendEvent and PostEvent both call. If pReceiver is NULL, we attempt to determine an appropriate target for the event.

Note:
Subclasses are encouraged *not* to reimplement this function, though they may choose to (installing an event handler is preferable). All non-broadcast events come through here.

virtual void CIwUIController::PostEvent | ( | CIwUIElement * | pReceiver,
 |  | CIwEvent * | pEvent |
 | ) |  |  | [virtual]

Posts an event to the event queue and returns immediately. Ownership of the event passes to the ui controller (therefore the event must be allocated on the heap).

Parameters:
pReceiver | Element to send the event to.
pEvent | The event to post.
Note:
The event queue is flushed on each call to Update()

void CIwUIController::RemoveEventHandler ( IIwUIEventHandler * pEventHandler )

Remove the specified event handler (but doesn't destroy it).

Parameters:
pEventHandler Event handler object to remove, which must have been added at some previous point.

bool CIwUIController::SendEvent | ( | CIwUIElement * | pReceiver,
 |  | CIwEvent * | pEvent
 | ) |  |

Send an event for immediate handling. Such events can be created on the stack.

Parameters:
pReceiver | Element to send the event to.
pEvent | The event to send.
Returns:
true if the event was handled.

void CIwUIController::SetPointerCapture ( CIwUIElement * pElement )

Set pointer capture to pElement.

virtual void CIwUIController::Update ( ) [virtual]

Per-tick update. Processes the event queue.

The documentation for this class was generated from the following file:
  • IwUIController.h


Airplay API Reference: CIwUIDrawableBorder

Airplay API Reference > Data Structures > CIwUIDrawableBorder >

CIwUIDrawableBorder Class Reference
[Drawables, Drawables]

Draws a border from a single image + corner width (by drawing 9 separate images, the corners being drawn 1:1 (using the corner size to calculate UVs), the other 5 being drawn stretched to fit the specified size).

#include <IwUIDrawableBorder.h>

Inheritance diagram for CIwUIDrawableBorder:

[legend]

Public Member Functions

CIwUIDrawableBorder (const CIwVec2 &size, const CIwPropertySet &propertySet)
CIwUIDrawableBorder (CIwTexture *pTexture, const CIwSVec2 &uv0, const CIwSVec2 &uv1, const CIwVec2 &size, const CIwSVec2 &border, bool shrinkDontCrop)
CIwUIDrawableBorder (CIwMaterial *pMaterial, const CIwSVec2 &uv0, const CIwSVec2 &uv1, const CIwVec2 &size, const CIwSVec2 &border, bool shrinkDontCrop)
IIwUIDrawable virtuals
virtual void | Draw (CIwUIGraphics &graphics) const
virtual bool | Intersects (const CIwVec2 &pos) const
virtual void | SetColour (const CIwColour &colour)
virtual void | SetPosition (const CIwVec2 &position)
virtual void | SetSize (const CIwVec2 &size)

Constructor & Destructor Documentation

CIwUIDrawableBorder::CIwUIDrawableBorder | ( | CIwMaterial * | pMaterial,
 |  | const CIwSVec2 & | uv0,
 |  | const CIwSVec2 & | uv1,
 |  | const CIwVec2 & | size,
 |  | const CIwSVec2 & | border,
 |  | bool | shrinkDontCrop
 | ) |  |

No default constructor is provided. All attributes bar position and colour must be specified at construction time.

Parameters:
pMaterial | The material with which the border will be rendered.
uv0 | Top-left UV coordinate of the full border texture.
uv1 | Bottom-right UV coordinate of the full border texture.
size | The size of the rectangle within which the border will be rendered.
border | Size of border corner in each dimension.

CIwUIDrawableBorder::CIwUIDrawableBorder | ( | CIwTexture * | pTexture,
 |  | const CIwSVec2 & | uv0,
 |  | const CIwSVec2 & | uv1,
 |  | const CIwVec2 & | size,
 |  | const CIwSVec2 & | border,
 |  | bool | shrinkDontCrop
 | ) |  |

No default constructor is provided. All attributes bar position and colour must be specified at construction time.

Parameters:
pTexture | The texture with which the border will be rendered.
uv0 | Top-left UV coordinate of the full border texture.
uv1 | Bottom-right UV coordinate of the full border texture.
size | The size of the rectangle within which the border will be rendered.
border | Size of border corner in each dimension.

CIwUIDrawableBorder::CIwUIDrawableBorder | ( | const CIwVec2 & | size,
 |  | const CIwPropertySet & | propertySet
 | ) |  |

Create from properties within the specified property set.

Parameters:
size | The size of the rectangle within which the border will be rendered.
propertySet | Other properties: 'material', 'uv0', 'uv1', 'border'

Member Function Documentation

virtual void CIwUIDrawableBorder::Animate ( const CIwUIAnimData & animData ) [virtual]

Used by animation system to update properties from interpolated data.

Implements IIwUIDrawable.

virtual void CIwUIDrawableBorder::Draw ( CIwUIGraphics & graphics ) const [virtual]

Draw the border to the graphics context.

Parameters:
graphics Graphics context to draw the border to.

Implements IIwUIDrawable.

virtual CIwUIRect CIwUIDrawableBorder::GetBounds ( ) const [virtual]

Query the bounds of the border.

Implements IIwUIDrawable.

virtual CIwColour CIwUIDrawableBorder::GetColour ( ) const [virtual]

Query the colour of the border.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableBorder::GetPosition ( ) const [virtual]

Query the position of the border.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableBorder::GetSize ( ) const [virtual]

Query the size of the border.

Implements IIwUIDrawable.

virtual bool CIwUIDrawableBorder::Intersects ( const CIwVec2 & pos ) const [virtual]

Intersection test.

Parameters:
pos Position to test.
Returns:
True if the position intersects the border.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableBorder::Measure ( const CIwVec2 & availableSize ) const [virtual]

Returns pixel size of area of covered by border's UVs.

Implements IIwUIDrawable.

virtual void CIwUIDrawableBorder::SetColour ( const CIwColour & colour ) [virtual]

Set the vertex colour of the border.

Parameters:
colour Colour to modulate the border by.

Implements IIwUIDrawable.

virtual void CIwUIDrawableBorder::SetPosition ( const CIwVec2 & position ) [virtual]

Set the position of the border.

Parameters:
position Position where the border will appear relative to top-left corner of the graphic context.
Note:
The default position is zero.

Implements IIwUIDrawable.

virtual void CIwUIDrawableBorder::SetSize ( const CIwVec2 & size ) [virtual]

Set the size of the border.

Parameters:
size Border size.

Implements IIwUIDrawable.

The documentation for this class was generated from the following file:
  • IwUIDrawableBorder.h


Airplay API Reference: CIwUIDrawableImage

Airplay API Reference > Data Structures > CIwUIDrawableImage >

CIwUIDrawableImage Class Reference
[Drawables, Drawables]

Drawable wrapper for a simple image. More...

#include <IwUIDrawableImage.h>

Inheritance diagram for CIwUIDrawableImage:

[legend]

Public Member Functions

CIwUIDrawableImage (const CIwVec2 &size, const CIwPropertySet &propertySet)
CIwUIDrawableImage (CIwTexture *pTexture, const CIwSVec2 &uv0, const CIwSVec2 &uv1, const CIwVec2 &size)
IIwUIDrawable virtuals
virtual void | Draw (CIwUIGraphics &graphics) const
virtual bool | Intersects (const CIwVec2 &pos) const
virtual void | SetColour (const CIwColour &colour)
virtual void | SetPosition (const CIwVec2 &position)
virtual void | SetSize (const CIwVec2 &size)

Detailed Description

Note:
This is NOT a ui element. It is a low-level primitive which encapsulates the data required to draw an image to the screen, ie texture, uvs, colour, alpha mode.

Constructor & Destructor Documentation

CIwUIDrawableImage::CIwUIDrawableImage | ( | CIwTexture * | pTexture,
 |  | const CIwSVec2 & | uv0,
 |  | const CIwSVec2 & | uv1,
 |  | const CIwVec2 & | size
 | ) |  |

No default constructor is provided. All attributes bar position and colour must be specified at construction time.

Parameters:
pTexture | The texture with which the image will be rendered.
uv0 | Top-left UV in pixel coordinates.
uv1 | Bottom-right in pixel UV coordinates.
size | The size of the rectangle within which the image will be rendered.

CIwUIDrawableImage::CIwUIDrawableImage | ( | const CIwVec2 & | size,
 |  | const CIwPropertySet & | propertySet
 | ) |  |

Create from properties within the specified property set.

Parameters:
size | The size of the rectangle within which the image will be rendered.
propertySet | Other properties: 'material' / 'texture', 'uv0', 'uv1'

Member Function Documentation

virtual void CIwUIDrawableImage::Animate ( const CIwUIAnimData & animData ) [virtual]

Used by animation system to update properties from interpolated data.

Implements IIwUIDrawable.

virtual void CIwUIDrawableImage::Draw ( CIwUIGraphics & graphics ) const [virtual]

Draw the image to the specified graphics context.

Parameters:
graphics Graphics context to draw the image to.

Implements IIwUIDrawable.

virtual CIwUIRect CIwUIDrawableImage::GetBounds ( ) const [virtual]

Query the bounds of the image.

Implements IIwUIDrawable.

virtual CIwColour CIwUIDrawableImage::GetColour ( ) const [virtual]

Query the colour of the image.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableImage::GetPosition ( ) const [virtual]

Query the position of the image.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableImage::GetSize ( ) const [virtual]

Query of the size of the image.

Implements IIwUIDrawable.

virtual bool CIwUIDrawableImage::Intersects ( const CIwVec2 & pos ) const [virtual]

Intersection test.

Parameters:
pos Position to test.
Returns:
True if the position intersects the image.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableImage::Measure ( const CIwVec2 & availableSize ) const [virtual]

Returns pixel size of area of covered by image UVs.

Implements IIwUIDrawable.

virtual void CIwUIDrawableImage::SetColour ( const CIwColour & colour ) [virtual]

Set the vertex colour of the image.

Parameters:
colour Colour to modulate the image by.

Implements IIwUIDrawable.

virtual void CIwUIDrawableImage::SetPosition ( const CIwVec2 & position ) [virtual]

Set the position of the image.

Parameters:
position Position where the image will appear relative to top-left corner of the graphic context.
Note:
The default position is zero.

Implements IIwUIDrawable.

virtual void CIwUIDrawableImage::SetSize ( const CIwVec2 & size ) [virtual]

Set the size of the image.

Parameters:
size Image size.

Implements IIwUIDrawable.

The documentation for this class was generated from the following file:
  • IwUIDrawableImage.h


Airplay API Reference: CIwUIDrawableText

Airplay API Reference > Data Structures > CIwUIDrawableText >

CIwUIDrawableText Class Reference
[Drawables, Drawables]

Drawable wrapper for the state required to draw some text via Gx. More...

#include <IwUIDrawableText.h>

Inheritance diagram for CIwUIDrawableText:

[legend]

Public Member Functions

CIwUIDrawableText (const CIwVec2 &size, const CIwPropertySet &propertySet)
IIwUIDrawable virtuals
virtual void | Draw (CIwUIGraphics &graphics) const
virtual CIwRect | GetCharacterArea (int32 c) const
virtual CIwVec2 | GetSize () const
virtual CIwVec2 | GetTextSize () const
virtual bool | Intersects (const CIwVec2 &pos) const
virtual CIwVec2 | Measure (const CIwVec2 &availableSize) const
virtual void | SetColour (const CIwColour &colour)
virtual void | SetPosition (const CIwVec2 &position)
virtual void | SetSize (const CIwVec2 &size)

Detailed Description

Note:
This is NOT a ui element. It is a low-level primitive which encapsulates the data required to draw a piece of text to the screen, ie string (potentially localised), font, colour, alignment, wrap mode?

Constructor & Destructor Documentation

CIwUIDrawableText::CIwUIDrawableText | ( | const CIwVec2 & | size,
 |  | const CIwPropertySet & | propertySet
 | ) |  |

Create from properties within the specified property set.

Parameters:
size | The size of the rectangle within which the text will be rendered.
propertySet | Other properties: 'font', 'caption', etc.

Member Function Documentation

virtual void CIwUIDrawableText::Animate ( const CIwUIAnimData & animData ) [virtual]

Used by animation system to update properties from interpolated data.

Implements IIwUIDrawable.

virtual void CIwUIDrawableText::Draw ( CIwUIGraphics & graphics ) const [virtual]

Draw the text to the specified graphics context.

Parameters:
graphics Graphics context to draw the text to.

Implements IIwUIDrawable.

virtual CIwUIRect CIwUIDrawableText::GetBounds ( ) const [virtual]

Query the bounds of the text.

Implements IIwUIDrawable.

virtual CIwRect CIwUIDrawableText::GetCharacterArea ( int32 c ) const [virtual]

Get a CIwRect representing the area of the character at index c.

Parameters:
c The index of the character to query.
Returns:
CIwRect representing the area of the character at index c

virtual CIwColour CIwUIDrawableText::GetColour ( ) const [virtual]

Query the colour of the text.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableText::GetPosition ( ) const [virtual]

Query the position of the text.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableText::GetSize ( ) const [virtual]

Query laid-out size of this text object.

Note:
This is likely to be smaller than the (maximum) size specified in the ctor.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableText::GetTextSize ( ) const [inline, virtual]

Query laid-out size of the area available to the text.

Note:
This is likely to be smaller than the (maximum) size specified in the ctor.

virtual bool CIwUIDrawableText::Intersects ( const CIwVec2 & pos ) const [virtual]

Intersection test.

Parameters:
pos Position to test.
Returns:
True if the position intersects the text.

Implements IIwUIDrawable.

virtual CIwVec2 CIwUIDrawableText::Measure ( const CIwVec2 & availableSize ) const [virtual]

Query how much space text would take up given a size to layout within.

Parameters:
Space available for the text to layout in.
Returns:
Required space.

Implements IIwUIDrawable.

virtual void CIwUIDrawableText::SetColour ( const CIwColour & colour ) [virtual]

Set the colour of the text.

Parameters:
colour Colour to modulated the text's natural colour by.

Implements IIwUIDrawable.

virtual void CIwUIDrawableText::SetPosition ( const CIwVec2 & position ) [virtual]

Set the position of the text.

Parameters:
position Position where the text will appear relative to top-left corner of the graphic context.
Note:
The default position is zero.

Implements IIwUIDrawable.

virtual void CIwUIDrawableText::SetSize ( const CIwVec2 & size ) [virtual]

Set the size of the text.

Parameters:
size Text size.

Implements IIwUIDrawable.

The documentation for this class was generated from the following file:
  • IwUIDrawableText.h


Airplay API Reference: CIwUIElement

Airplay API Reference > Data Structures > CIwUIElement >

CIwUIElement Class Reference
[Elements, Elements]

Base class for all ui widgets. Also acts a frame within which other elements can be contained. More...

#include <IwUIElement.h>

Inheritance diagram for CIwUIElement:

[legend]

Public Member Functions

Hierarchy
void | AddChild (CIwUIElement *pChild)
CIwUIElement * | GetChild (int index) const
CIwUIElement * | GetChildHashed (uint32 hash, bool recurse=true, bool permitNull=false) const
CIwUIElement * | GetChildNamed (const char *pName, bool recurse=true, bool permitNull=false) const
void | GetCloneList (uint32 hash, CIwManagedList &list)
CIwUIElement * | GetParent () const
bool | IsAncestor (const CIwUIElement *pElement) const
bool | IsDescendant (const CIwUIElement *pElement) const
template<class Type>
void | LookupChildHashed (Type *&ptr, uint32 hash, bool recurse=true, bool permitNull=false) const
template<class Type>
void | LookupChildNamed (Type *&ptr, const char *pName, bool recurse=true, bool permitNull=false) const
void | RemoveChild (CIwUIElement *pChild)
Delegates (signals and slots)
void | AddDelegate (IDelegateQuery *pDelegate)
void | AttachSignalSlot (const char *pSignalName, bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | AttachSignalSlot (const char *pSignalName, CIwUIElement *pSlotOwner, const char *pSlotName)
void | DestroyDelegates (void *pHandler)
void | DetachSignalSlot (const char *pSignalName, bool classNotObjectName, const char *pSlotOwnerName, const char *pSlotName)
void | DetachSignalSlot (const char *pSignalName, CIwUIElement *pSlotOwner, const char *pSlotName)
IDelegateQuery * | GetDelegate (uint32 delegateName)
void | RemoveDelegate (IDelegateQuery *pDelegate)
Events
void | AddEventHandler (CIwUIElementEventHandler *pEventHandler)
void | RemoveEventHandler (CIwUIElementEventHandler *pEventHandler)
Declared virtuals
void | Intersect (CIwManagedList &contained, const CIwUIRect &rect) const
virtual CIwUIElement * | Intersect (const CIwVec2 &pos) const
virtual void | Render (const CIwUIGraphics &parentGraphics)
virtual void | Update (int32 deltaMS)
Element copying
CIwUIElement * | Clone () const
IwUIEventHandler virtuals
virtual bool | FilterEvent (CIwEvent *pEvent)
virtual bool | HandleEvent (CIwEvent *pEvent)
Focus
virtual CIwUIElement * | FindWantsFocus ()
CIwUIElement * | GetFocus () const
virtual bool | HandlesFocus () const
void | SetFocusHandler (CIwUIFocusHandler *pFocusHandler)
virtual bool | WantsFocus () const
General settings
CIwVec2 | GetPosAbsolute (const CIwVec2 &offset=CIwVec2::g_Zero) const
void | SetColour (const CIwColour &colour)
void | SetPos (const CIwVec2 &pos, bool invalidateLayout=false)
void | SetPosAbsolute (const CIwVec2 &pos, const CIwVec2 &offset=CIwVec2::g_Zero)
void | SetSize (const CIwVec2 &size, bool invalidateLayout=false)
void | SetTransform (const CIwUIMat &transform)
void | SetTransformPos (const CIwVec2 &pos)
void | SetVisible (bool val)
Layout
CIwVec2 | GetSizeHint () const
CIwVec2 | GetSizeMax () const
CIwVec2 | GetSizeMin () const
void | SetLayout (CIwUILayout *pLayout)
void | SetSizeHint (const CIwVec2 &hint)
void | SetSizeMax (const CIwVec2 &max)
void | SetSizeMin (const CIwVec2 &min)
Properties
template<class Type>
bool | GetProperty (const char *pName, Type &val, bool allowMissing=false) const
virtual void | OnPropertyChanged (const char *pName=NULL)
template<class Type>
bool | SetProperty (const char *pName, const Type &val)
void | SetPropertySetBinding (CIwPropertySetBinding *pBinding)
void | SetStyle (const CIwUIStyle &style)
IwManaged virtuals
virtual void | SetName (const char *pName)

Static Public Member Functions

Static functionality
static CIwUIElement * | CreateFromResource (const char *pElementName, CIwResGroup *pResGroup=NULL)

Protected Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual void | Resolve ()
virtual void | Serialise ()
General settings
virtual void | Activate (bool val)
void | SetClipped (bool val)
void | SetUpdatable (bool val)
Layout
void | Arrange (const CIwVec2 &pos, const CIwVec2 &size)
void | Layout (const CIwVec2 &pos, const CIwVec2 &sizeHint)
Element copying
virtual void | Clone (CIwUIElement *pTarget) const
Graphics
IIwUIDrawable * | CreateDrawable (const char *styleName, const CIwVec2 &size, const char *defaultType=NULL, bool allowMissing=false) const
IIwUIDrawable * | CreateDrawable (const CIwVec2 &size, const char *defaultType=NULL)
CIwUIRect | GetChildBounds () const
void | RenderChildren (const CIwUIGraphics &graphics)
void | SetRenderSlot (int32 slot)
Hierarchy
Events
virtual bool | HandleEventClick (CIwUIEventClick *pEventClick)
virtual bool | HandleEventFocus (CIwUIEventFocus *pEventFocus)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | HandleEventLayout (CIwUIEventLayout *pEventLayout)
virtual bool | HandleEventPointerEnter (CIwUIEventPointerEnter *pEventPointerEnter)
virtual bool | HandleEventPointerLeave (CIwUIEventPointerLeave *pEventPointerLeave)
virtual bool | HandleEventPointerMove (CIwUIEventPointerMove *pEventPointerMove)
Properties
template<class Type>
bool | SetProperty (const char *pName, const Type &val, bool callOnPropertyChanged)

Friends

void | IwUIInit ()
void | IwUITerminate ()

Detailed Description

Elements have the following attributes which can be specified in the itx (and are also available programmatically through the public interface). All of these attributes are stored as member data within the object rather than in property sets.

Type | Name | Description
CIwStringS | name | The element's name. Sibling names (which are non-NULL) must be unique, otherwise an assert will fire.
CIwVec2 | pos, position | The initial position, in pixels, in parent space, of this element. Note that this property may be updated by a controlling layout once the element is activated.
CIwVec2 | size | The initial size, in pixels, of this element. Note that this property may be updated be a controlling layout once the element is activated.
CIwVec2 | sizeMin | The minimum permissible size for this element.
CIwVec2 | sizeMax | The maximum permissible size for this element.
bool | visible | Whether this element (and its descendants) should be rendered.
bool | updatable | Whether this element (and its descendants) should be updated.
bool | clipped | Whether this object's drawing (and the drawing of its children) should be clipped to its bounding frame.
CIwColour | colour | The colour to draw this element with.
bool | modulatesColour | Should the element's colour modulate that of all contained drawables and children. </TR?
CIwStringS | style | Style name to use for this element.
iwangle | rotation | Rotation transform to apply to this element, in iwangle units (4096 => 360 degrees).
int16 | slot | The graphics slot to render this element in - with higher slot indices being rendered in front of lower slot indices.

Member Function Documentation

virtual void CIwUIElement::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented in CIwUIAlertDialog, CIwUIButton, CIwUICheckbox, CIwUIImage, CIwUILabel, CIwUIRadioButton, CIwUIScrollableView, CIwUISlider, CIwUISoftKeyboard, CIwUISoftKeyPosition, CIwUITabBar, and CIwUITextField.

void CIwUIElement::AddChild ( CIwUIElement * pChild )

Add the specified element as a child. Ownership transfers to this element.

Parameters:
pChild Element to add as a child.

void CIwUIElement::AddDelegate ( IDelegateQuery * pDelegate )

Use on activation to register a derived element's slots.

Parameters:
Pointer to delegate for the element.
Note:
The element will destroy any delegate which are still registered when it is deactivated.
See also:
IW_UI_CREATE_ELEMENT_SLOT

void CIwUIElement::AddEventHandler ( CIwUIElementEventHandler * pEventHandler )

Add an event handler which can either handle or filter events on this element.

Parameters:
pEventHandler The filter to add.
Note:
The element takes ownership of the filter object.

virtual void CIwUIElement::Animate ( const CIwUIAnimData & animData ) [virtual]

Update animated properties from the provided animation data.

Reimplemented in CIwUIAlertDialog, CIwUIButton, CIwUICheckbox, CIwUIImage, CIwUILabel, CIwUIRadioButton, CIwUISlider, and CIwUITabBar.

void CIwUIElement::Arrange | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | size |
 | ) |  |  | [protected]

Sets position and size to given values. Arranges children within our new bounds.

Parameters:
pos | New position.
size | New size.

void CIwUIElement::AttachSignalSlot | ( | const char * | pSignalName,
 |  | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Looks up a slot in parent hierarchy, or registered in the view, and attaches it to a signal of this element.

Parameters:
pSignalName | Name of a signal property to attach slot to.
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of element or other object that owns the slot.
pSlotName | Name of slot to be attached.
Note:
This function should only be called on an active element. If the signal doesn't already exist, then a CIwPropertyDefine with name is expected to exist in the resource system to use a template for creating the signal.

void CIwUIElement::AttachSignalSlot | ( | const char * | pSignalName,
 |  | CIwUIElement * | pSlotOwner,
 |  | const char * | pSlotName
 | ) |  |

Looks up a slot and attaches it to a signal of this element.

Parameters:
pSignalName | Name of a signal property to attach slot to.
pSlotOwner | Element which contains a slot of name pSlotName.
pSlotName | Name of slot to be attached.
Note:
This function should only be called on an active element. If the signal doesn't already exist, then a CIwPropertyDefine with name is expected to exist in the resource system to use a template for creating the signal.

virtual void CIwUIElement::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented in CIwUIAlertDialog, CIwUIButton, CIwUICheckbox, CIwUIImage, CIwUILabel, CIwUIRadioButton, CIwUIScrollableView, CIwUISlider, CIwUISoftKeyboard, CIwUISoftKeyPosition, CIwUITabBar, and CIwUITextField.

CIwUIElement* CIwUIElement::Clone ( ) const

Clone this element and all its descendants.

Returns:
The clone, which the caller of this function owns.

IIwUIDrawable* CIwUIElement::CreateDrawable | ( | const char * | styleName,
 |  | const CIwVec2 & | size,
 |  | const char * | defaultType = NULL,
 |  | bool | allowMissing = false |
 | ) |  |  | const [protected]

Creates a drawable from the style named in the specified property.

Parameters:
styleName | Name of style property to try to resolve.
size | Size to pass to drawable construction.
defaultType | Optional default type to use for drawable.
allowMissing | Allow property set to be missing and no drawable to be constructed.

IIwUIDrawable* CIwUIElement::CreateDrawable | ( | const CIwVec2 & | size,
 |  | const char * | defaultType = NULL |
 | ) |  |  | [protected]

Creates a drawable using the element's property set to provide construction data.

Parameters:
size | Size to pass to drawable construction.
defaultType | Optional default type to use for drawable.

static CIwUIElement* CIwUIElement::CreateFromResource | ( | const char * | pElementName,
 |  | CIwResGroup * | pResGroup = NULL |
 | ) |  |  | [static]

Instantiate the element with the specified name from the element resource of the same name. If a res group is specified, only that will be searched. Otherwise all loaded groups will be searched.

Parameters:
pElementName | Name of the element resource to clone from.
pResGroup | If specified, res group to restrict the search for the element resource to.

virtual void CIwUIElement::DebugRender ( const CIwUIGraphics & parentGraphics ) [virtual]

Debug rendering.

void CIwUIElement::DebugRenderChildren ( const CIwUIGraphics & graphics ) [protected]

Debug rendering.

virtual void CIwUIElement::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [protected, virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwUIElement::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [protected, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwUIElement::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [protected, virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwUIElement::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [protected, virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

void CIwUIElement::DestroyChildren ( ) [protected]

Destroy all the children of this element.

void CIwUIElement::DestroyDelegates ( void * pHandler )

Use to unregister and destroy all slots previously registered by AddDelegate for a given handler.

Parameters:
handler The delegate's handler.
See also:
IW_UI_DESTROY_ELEMENT_SLOTS

void CIwUIElement::DetachSignalSlot | ( | const char * | pSignalName,
 |  | bool | classNotObjectName,
 |  | const char * | pSlotOwnerName,
 |  | const char * | pSlotName
 | ) |  |

Looks up a slot in parent hierarchy, or registered in the view, and detaches it from a signal of this element.

Parameters:
pSignalName | Name of a signal property to detach slot from.
classNotObjectName | Slot name is of a class not an object.
pSlotOwnerName | Name of element or other object that owns the slot.
pSlotName | Name of slot to be attached.
Note:
This function will assert if the signal or slot is not found or if the slot was never attached to the signal.

void CIwUIElement::DetachSignalSlot | ( | const char * | pSignalName,
 |  | CIwUIElement * | pSlotOwner,
 |  | const char * | pSlotName
 | ) |  |

Looks up a slot and detaches it from a signal of this element.

Parameters:
pSignalName | Name of a signal property to detach slot from.
pSlotOwner | Element which contains a slot of name pSlotName.
pSlotName | Name of slot to be attached.
Note:
This function will assert if the signal or slot is not found or if the slot was never attached to the signal.

virtual bool CIwUIElement::FilterEvent ( CIwEvent * pEvent ) [virtual]

Base event-filter. Calls through to registered event handlers.

See also:
AddEventHandler()
Parameters:
pEvent Event to be filtered.
Returns:
Boolean value signifying whether the event was filtered.

Implements IIwUIEventHandler.

Reimplemented in CIwUISlider.

virtual CIwUIElement* CIwUIElement::FindWantsFocus ( ) [virtual]

Chooses an appropriate focus element. This can either be the element itself or one of its children.

Returns:
Pointer to element which wants focus, or NULL if none found.

Reimplemented in CIwUIAlertDialog, and CIwUITabBar.

CIwUIElement* CIwUIElement::GetChild ( int index ) const

Get a ptr to the child at the specified index.

Parameters:
index Index into child array.

CIwUIRect CIwUIElement::GetChildBounds ( ) const [protected]

Query the bounds of this element's children (in its frame of reference).

Note:
Result is not intersected with this element's clipping frame.

CIwUIElement* CIwUIElement::GetChildHashed | ( | uint32 | hash,
 |  | bool | recurse = true,
 |  | bool | permitNull = false |
 | ) |  |  | const

Retrieve a ptr to child element who's name hash matches that specified.

Parameters:
hash | Name hash of the child to search for.
recurse | Whether descendants below immediate children should be searched.
permitNull | Whether this function should allow the search to fail
Note:
If permitNull is false and the element isn't found, an assert will fire.
Returns:
Ptr to the child with the specified name hash, else NULL if it wasn't found.

CIwUIElement* CIwUIElement::GetChildNamed | ( | const char * | pName,
 |  | bool | recurse = true,
 |  | bool | permitNull = false |
 | ) |  |  | const

Retrieve a ptr to a named child element.

Parameters:
pName | The name of the child to search for.
recurse | Whether descendants below immediate children should be searched.
permitNull | Whether this function should allow the search to fail
Note:
If permitNull is false and the element isn't found, an assert will fire.
Returns:
Ptr to the named child, else NULL if it wasn't found.

void CIwUIElement::GetCloneList | ( | uint32 | hash,
 |  | CIwManagedList & | list
 | ) |  |

Find all children and descendants that were cloned from an item whose name matches this hash.

Parameters:
hash | Name hash of the children to search for.
list | List to put the matching children in.

IDelegateQuery* CIwUIElement::GetDelegate ( uint32 delegateName )

Lookup a delegate by hash.

Parameters:
delegateName Hash of string name of delegate.

CIwUIElement* CIwUIElement::GetFocus ( ) const [inline]

Query the current focus target for this element.

Note:
This returns this element's focused child if any.

CIwUIFocusHandler* CIwUIElement::GetFocusHandler ( ) const [inline]

Get the current focus handler, if any, owned by this element.

CIwUIRect CIwUIElement::GetFrame ( ) const

Query this element's frame, which is a rectangle whose x and y coordinates are derived from the element's position, w and h are derived from the element's size. Defines clipping area.

CIwUILayout* CIwUIElement::GetLayout ( ) const [inline]

Get the layout current active on this element, if any.

bool CIwUIElement::GetModulatesColour ( ) const

Does this element's colour modulate the draw colour of contained drawables and elements.

int CIwUIElement::GetNumChildren ( ) const

Query the number of children this element has.

CIwUIElement* CIwUIElement::GetParent ( ) const [inline]

Query a ptr to this element's parent, if any.

Returns:
Ptr to the element's parent if it has one, else NULL.

CIwVec2 CIwUIElement::GetPos ( ) const

Query the position (in parent's coordinate space) of this element.

CIwVec2 CIwUIElement::GetPosAbsolute ( const CIwVec2 & offset = CIwVec2::g_Zero ) const

Query the position (in top-level coordinate space) of this element.

Parameters:
offset Optional offset to apply to this element's position before transforming from parent element's space to view space. Useful, for example, to get the absolute position of the centre of the element.

template<class Type>
bool CIwUIElement::GetProperty | ( | const char * | pName,
 |  | Type & | val,
 |  | bool | allowMissing = false |
 | ) |  |  | const [inline]

Get the value of a named property from the element's property set.

Parameters:
pName | Name of the property definition we're searching for.
val | Reference to a variable that will store the value upon success.
allowMissing | If false, routine will assert if the property isn't found.
Returns:
Boolean upon success/failure of search
Return values:
true | Property was found and value stored in provided reference.
false | Property was NOT found. Value was NOT stored in provided reference.

CIwPropertySetBinding* CIwUIElement::GetPropertySetBinding ( ) const

Get binding for element's properties.

int32 CIwUIElement::GetRenderSlot ( ) const [inline, protected]

Get our render slot, which controls render order relative to our siblings.

CIwVec2 CIwUIElement::GetSize ( ) const

Query the size of this element.

CIwVec2 CIwUIElement::GetSizeHint ( ) const

Query the hint size of this element.

Note:
If a maximum isn't specified for a dimension, the dimension will be LAYOUT_INFINITY.

CIwVec2 CIwUIElement::GetSizeMax ( ) const

Query the maximum size of this element.

Note:
If a maximum isn't specified for a dimension, the dimension will be LAYOUT_INFINITY.

CIwVec2 CIwUIElement::GetSizeMin ( ) const

Query the minimum size of this element.

Note:
If a minimum isn't specified for a dimension, that dimension will return 0.

bool CIwUIElement::GetSizeToContent ( ) const

Does this element attempt to fit its content when in a layout.

const CIwUIStyle& CIwUIElement::GetStyle ( ) const

Expose this element's style for read-only access.

const CIwUIMat& CIwUIElement::GetTransform ( ) const

Query the 2D transform currently applied to this element.

virtual bool CIwUIElement::HandleEvent ( CIwEvent * pEvent ) [virtual]

Base event-handler for all ui elements.

Parameters:
pEvent Event to be handled.
Returns:
Boolean value signifying whether the event was handled.
Return values:
true | If the event was handled and requires no further processing.
false | If the event wasn't handled and so requires further processing.
Note:
Derived classes are encouraged to override one or more of the more specific event handlers, eg. HandleEventClick, etc, rather than this function.

Implements IIwUIEventHandler.

Reimplemented in CIwUIRadioButton, CIwUISoftKeyboard, CIwUITabBar, and CIwUITextField.

virtual bool CIwUIElement::HandleEventClick ( CIwUIEventClick * pEventClick ) [protected, virtual]

Handle a pointer click event.

Parameters:
pEventClick The click event to handle.

Reimplemented in CIwUIButton, CIwUICheckbox, CIwUISlider, and CIwUITextField.

virtual bool CIwUIElement::HandleEventFocus ( CIwUIEventFocus * pEventFocus ) [inline, protected, virtual]

Handle focus changes.

Parameters:
pEventFocus The focus event to handle.
Note:
Focus handlers should generally return false so that all elements in the focus chain receive the event.

Reimplemented in CIwUIButton.

virtual bool CIwUIElement::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented in CIwUIButton, CIwUICheckbox, CIwUISlider, CIwUITabBar, and CIwUITextField.

virtual bool CIwUIElement::HandleEventLayout ( CIwUIEventLayout * pEventLayout ) [inline, protected, virtual]

Handle the fact that an element's layout has been updated.

Parameters:
pEventLayout The layout event to handle.

virtual bool CIwUIElement::HandleEventPointerEnter ( CIwUIEventPointerEnter * pEventPointerEnter ) [inline, protected, virtual]

Handle a pointer enter event, which is issued when the pointer moves into a position which intersects this element.

Parameters:
pEventPointerEnter The pointer enter event to handle.

Reimplemented in CIwUIButton.

virtual bool CIwUIElement::HandleEventPointerLeave ( CIwUIEventPointerLeave * pEventPointerLeave ) [inline, protected, virtual]

Handle a pointer leave event, which is issued when the pointer moves into a position which doesn't intersect this element (either because it intersects another element before this, or just because it doesn't intersect with this), or in the case of a touchscreen when the screen is 'released'.

Parameters:
pEventPointerLeave The pointer leave event to handle.

Reimplemented in CIwUIButton, and CIwUITextField.

virtual bool CIwUIElement::HandleEventPointerMove ( CIwUIEventPointerMove * pEventPointerMove ) [inline, protected, virtual]

Handle the movement of the pointer within our bounds (or a child element's bounds).

Parameters:
pEventPointerMove The pointer move event to handle.

Reimplemented in CIwUISlider.

virtual bool CIwUIElement::HandlesFocus ( ) const [virtual]

This element wants to choose its own focus element where possible.

Returns:
By default, returns true if either the element itself wants focus or it has an attached focus handler which is able to determine a child to have focus.

Reimplemented in CIwUIAlertDialog, and CIwUITabBar.

bool CIwUIElement::HasFocus ( ) const

Has this element got global keyboard focus.

void CIwUIElement::Intersect | ( | CIwManagedList & | contained,
 |  | const CIwUIRect & | rect |
 | ) |  |  | const

Performs intersection testing, returning into a list all elements which are completely within a given rectangle.

Parameters:
contained | Reference to list to add contained elements to.
rect | Rectangle to test - in our parent's frame of reference.

virtual CIwUIElement* CIwUIElement::Intersect ( const CIwVec2 & pos ) const [virtual]

Perform intersection testing at the specified position, returning the lowest-level element at the position (if any).

Parameters:
pos Position to test - in our parent's frame of reference.
Returns:
Lowest-level element which intersects with the specified position.

void CIwUIElement::InvalidateLayout ( )

Mark this element so its layout will be updated next frame.

bool CIwUIElement::IsActive ( ) const [protected]

Check whether we are currently active (ie added to the ui view).

bool CIwUIElement::IsAncestor ( const CIwUIElement * pElement ) const

Query whether an element is our parent or an ancestor.

Parameters:
pElement Element to query.
Returns:
If the given element is a parent, or a parent's parent.

bool CIwUIElement::IsClipped ( ) const [protected]

Check whether we are clipped to our frame.

bool CIwUIElement::IsDescendant ( const CIwUIElement * pElement ) const

Query whether an element is a child or a descendant.

Parameters:
pElement Element to query.
Returns:
If the given element is a child, or a child's child.

bool CIwUIElement::IsLayoutInvalid ( ) const

Query if the element's layout has been invalidated.

bool CIwUIElement::IsUpdatable ( ) const [protected]

Check whether this element should be updated each frame.

bool CIwUIElement::IsVisible ( ) const

Returns true if the element is visible.

bool CIwUIElement::IsWithinLayout ( ) const

Is this element contained within a layout. That is, is the element's position and size controlled by its parent element's layout hierarchy.

void CIwUIElement::Layout | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | sizeHint |
 | ) |  |  | [protected]

Layout this element and children.

Parameters:
pos | Position for element.
sizeHint | Size we would like element to be. Elements final size is determined by size policy & space requirements of children.

template<class Type>
void CIwUIElement::LookupChildHashed | ( | Type *& | ptr,
 |  | uint32 | hash,
 |  | bool | recurse = true,
 |  | bool | permitNull = false |
 | ) |  |  | const [inline]

Templated version of GetChildHashed.

Parameters:
ptr | Pointer to be filled with requested element
hash | Name hash of the child to search for
recurse | Whether descendants below immediate children should be searched.
permitNull | Whether this function should allow the search to fail

template<class Type>
void CIwUIElement::LookupChildNamed | ( | Type *& | ptr,
 |  | const char * | pName,
 |  | bool | recurse = true,
 |  | bool | permitNull = false |
 | ) |  |  | const [inline]

Templated version of GetChildNamed.

Parameters:
ptr | Pointer to be filled with requested element
pName | String name of requested element
recurse | Whether descendants below immediate children should be searched.
permitNull | Whether this function should allow the search to fail

virtual CIwVec2 CIwUIElement::Measure ( const CIwVec2 & availableSize ) const [protected, virtual]

Calculates our desiredSize given an availableSize. Elements can override MeasureElement to provide custom size constraints.

Reimplemented in CIwUIScrollableView.

virtual void CIwUIElement::OnPropertyChanged ( const char * pName = NULL ) [virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented in CIwUIAlertDialog, CIwUIButton, CIwUICheckbox, CIwUIImage, CIwUILabel, CIwUIRadioButton, CIwUISlider, CIwUISoftKeyPosition, CIwUITabBar, and CIwUITextField.

virtual bool CIwUIElement::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [protected, virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

virtual void CIwUIElement::ParseClose ( CIwTextParserITX * pParser ) [protected, virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIElement::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [protected, virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwUIElement::RemoveChild ( CIwUIElement * pChild )

Remove the specified element from the child list.

Parameters:
pChild Pointer to child element to remove.
Note:
The child element is not destroyed by this function call. The calling code becomes the child element's owner.

All child elements after the one removed will be shifted up one place in the child vector. Bear this in mind if you are iterating over the child vector whilst calling this function!

void CIwUIElement::RemoveDelegate ( IDelegateQuery * pDelegate )

Use on to unregister a derived element's slots. The slot is also detached from any signals in the sub-hierarchy.

Parameters:
Pointer to delegate previously added.
Note:
Element no longer owns delegate after it has been removed.

void CIwUIElement::RemoveEventHandler ( CIwUIElementEventHandler * pEventHandler )

Remove the specified event handler (but don't destroy it).

Parameters:
pEventHandler The filter to remove.

virtual void CIwUIElement::Render ( const CIwUIGraphics & parentGraphics ) [virtual]

Render this element.

Parameters:
parentGraphics The parent's graphics context, which we should transform into our own frame of reference.
Note:
Overriding Render is not recommended, derived classes wishing to provide their own rendering implementation should override RenderElement().

Reimplemented in CIwUIScrollableView.

void CIwUIElement::RenderChildren ( const CIwUIGraphics & graphics ) [protected]

Call render on our children with given graphics object. Children are ordered first by slot, then by index. This method is useful if Render() is overridden.

Parameters:
graphics Graphics content to render to.

void CIwUIElement::RequestFocus ( )

Request keyboard focus on this element.

virtual void CIwUIElement::Resolve ( ) [protected, virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUIElement::Serialise ( ) [protected, virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

void CIwUIElement::SetClipped ( bool val ) [protected]

Set whether ourselves and our children should be clipped to our frame.

Parameters:
val True to clip ourselves and our children, false otherwise.

void CIwUIElement::SetColour ( const CIwColour & colour )

Set the colour of this element.

Parameters:
colour The colour to set this element to.

void CIwUIElement::SetFocusHandler ( CIwUIFocusHandler * pFocusHandler )

Set the specified focus handler on this element.

Note:
The element takes ownership of the passed focus handler.

void CIwUIElement::SetLayout ( CIwUILayout * pLayout )

Set the specified layout on this element. The size of this element and the position and size of its children will henceforth be controlled by the layout object.

Parameters:
pLayout object to set on this element.
Note:
The element takes ownership of the passed layout.

void CIwUIElement::SetModulatesColour ( bool val )

Set if this element's colour should be used to modulate the draw colour of contained drawables and elements.

virtual void CIwUIElement::SetName ( const char * pName ) [virtual]

The given string is hashed and stored as the element's identifier.

Note:
In debug builds, the string name is available as DebugGetName(), however in release only m_Hash is present.

Reimplemented from CIwManaged.

void CIwUIElement::SetPos | ( | const CIwVec2 & | pos,
 |  | bool | invalidateLayout = false
 | ) |  |

Set the position of this element within its parent's frame of reference.

Parameters:
pos | The new position to (attempt) to set this element to.
invalidateLayout | Whether or not to invalidate element's layout. (primarily to inform layouts of the change)
Note:
If a layout object is specified for this element or its parent, this size is likely to be overridden the next time layout occurs.

void CIwUIElement::SetPosAbsolute | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | offset = CIwVec2::g_Zero
 | ) |  |

Set the position of this element within the top-level frame of reference. Asserts if the element is within a layout (which determines its position).

Parameters:
pos | The new absolute position to set this element to.
offset | Optional offset in parent element's space to apply to pos. Useful, for example, to position centre of element.

template<class Type>
bool CIwUIElement::SetProperty | ( | const char * | pName,
 |  | const Type & | val,
 |  | bool | callOnPropertyChanged |
 | ) |  |  | [inline, protected]

Set the value of a named property, for this element.

Parameters:
pName | Name of the property to set.
val | Value to set on the property.
callOnPropertyChanged | Should OnPropertyChanged be called if this element has been activated.

template<class Type>
bool CIwUIElement::SetProperty | ( | const char * | pName,
 |  | const Type & | val |
 | ) |  |  | [inline]

Set the value of a named property, for this element.

Parameters:
pName | Name of the property to set.
val | Value to set on the property.
Note:
OnPropertyChanged will be called if the property has changed in value and the element has been activated.

void CIwUIElement::SetPropertySetBinding ( CIwPropertySetBinding * pBinding )

Set binding for element's properties (giving ownership to element).

Note:
Call OnPropertyChanged() after setting the binding so the element rereads its properties.

void CIwUIElement::SetRenderSlot ( int32 slot ) [protected]

Set our render slot. A higher slots means we are rendered after siblings with a lower slot.

Parameters:
slot Slot index to assign to this element.

void CIwUIElement::SetSize | ( | const CIwVec2 & | size,
 |  | bool | invalidateLayout = false
 | ) |  |

Set the size of this element.

Parameters:
size | The new size to (attempt) to set this element to.
invalidateLayout | Whether or not to invalidate element's layout. (primarily to inform layouts of the change)
Note:
If a layout object is specified for this element or its parent, this size is likely to be overridden the next time layout occurs.

void CIwUIElement::SetSizeHint ( const CIwVec2 & hint )

Set size hint to be used by layout system.

Parameters:
hint New size hint to set for this element.
Note:
Layout is invalidated if constraint has changed. Constraint will be applied when the layout is updated.

void CIwUIElement::SetSizeMax ( const CIwVec2 & max )

Set maximum size constraint.

Parameters:
max New maximum size to set for this element.
Note:
Layout is invalidated if constraint has changed. Constraint will be applied when the layout is updated.

void CIwUIElement::SetSizeMin ( const CIwVec2 & min )

Set minimum size constraint.

Parameters:
min New minimum size to set for this element.
Note:
Layout is invalidated if constraint has changed. Constraint will be applied when the layout is updated.

void CIwUIElement::SetSizeToContent ( bool val )

Set if this element should size to fit its content.

void CIwUIElement::SetStyle ( const CIwUIStyle & style )

Set the style for this widget. If a stylesheet is set on the view then that will determine which property set the style corresponds to. Otherwise the property set resource with the specified name will be applied to the widget.

Parameters:
style Style to apply to this widget.

void CIwUIElement::SetTransform ( const CIwUIMat & transform )

Set a 2D transform to apply to this widget.

Parameters:
transform 2D transform matrix.
Note:
Layout does not take transform data into account.

void CIwUIElement::SetTransformPos ( const CIwVec2 & pos )

Set a 2D positional transform to apply to this widget.

Parameters:
pos 2D positional transform.
Note:
This affects the sub-frame positioning of the widget.

void CIwUIElement::SetUpdatable ( bool val ) [protected]

Set whether this element (and it's ancestors) should be updated each frame.

Parameters:
val True to update this element each frame, false not to.

void CIwUIElement::SetVisible ( bool val )

Sets the visibility of this element.

Parameters:
val True to show this element, false to hide it.
Note:
Elements (and their children) are not rendered if visibility is set to false.

virtual void CIwUIElement::Update ( int32 deltaMS ) [virtual]

Per-frame update.

Parameters:
deltaMS The number of milliseconds since the last update.
Note:
This is only called if the element and its ancestor's are active and updatable.

Reimplemented in CIwUIScrollableView, and CIwUISoftKeyPosition.

virtual bool CIwUIElement::WantsFocus ( ) const [virtual]

Query the element and return whether it supports/wants keyboard focus.

Returns:
By default, returns false. Overridden by derived elements.

Reimplemented in CIwUIButton, CIwUICheckbox, CIwUISlider, and CIwUITextField.

Friends And Related Function Documentation

void IwUIInit ( ) [friend]

IwUI module initialisation function. Registers class factories and calls sub-module init functions.

Note:
This function should be called on application startup.

void IwUITerminate ( ) [friend]

IwUI module terminate function. Destroys class factories and calls sub-module terminate functions.

Note:
This function should be called on application shutdown.

The documentation for this class was generated from the following file:
  • IwUIElement.h


Airplay API Reference: CIwUIElementEventHandler

Airplay API Reference > Data Structures > CIwUIElementEventHandler >

CIwUIElementEventHandler Class Reference
[Events, Events]

Event handler which can be attached to an element in data.

#include <IwUIEventHandler.h>

Inheritance diagram for CIwUIElementEventHandler:

[legend]

Declared virtuals

static const char * | s_CloneExpectedClassName

Public Member Functions

virtual bool | FilterEvent (CIwEvent *pEvent)
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual void | ParseClose (CIwTextParserITX *pParser)
Public interface
CIwUIElementEventHandler * | Clone () const
CIwUIElement * GetElement ()

Member Function Documentation

virtual void CIwUIElementEventHandler::Activate ( bool val ) [protected, virtual]

Called when owner element is activated.

virtual void CIwUIElementEventHandler::Clone ( CIwUIElementEventHandler * pTarget ) const [protected, virtual]

Clone this event handler on to the given target.

CIwUIElementEventHandler* CIwUIElementEventHandler::Clone ( ) const

Clone this event handler.

Returns:
The clone, which the caller of this function owns.

virtual void CIwUIElementEventHandler::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwUIElementEventHandler::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwUIElementEventHandler::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwUIElementEventHandler::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

virtual bool CIwUIElementEventHandler::FilterEvent ( CIwEvent * pEvent ) [inline, virtual]

Called by CIwUIController and CIwUIElement to filter events.

Parameters:
pEvent Event to filter
Returns:
If the event was filtered and shouldn't be propagated.

Implements IIwUIEventHandler.

CIwUIElement* CIwUIElementEventHandler::GetElement ( ) [inline]

Returns:
The element which owns this event handler

virtual bool CIwUIElementEventHandler::HandleEvent ( CIwEvent * pEvent ) [inline, virtual]

Called by CIwUIController and CIwUIElement to handle events.

Parameters:
pEvent Event to handle
Returns:
If the event was handled and shouldn't be propagated.

Implements IIwUIEventHandler.

virtual void CIwUIElementEventHandler::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Field Documentation

const char* CIwUIElementEventHandler::s_CloneExpectedClassName [static, protected]

Used by the Clone() method to enforce its declaration at every level of the hierarchy

The documentation for this class was generated from the following file:
  • IwUIEventHandler.h


Airplay API Reference: CIwUIElementItem

Airplay API Reference > Data Structures > CIwUIElementItem >

CIwUIElementItem Class Reference
[Layout, Layout]

Used as a wrapper around CIwUIElements, which are then wrapped by a CIwUILayoutItem, before being added into a CIwUILayout.

#include <IwUIElementItem.h>

Inheritance diagram for CIwUIElementItem:

[legend]

Member Function Documentation

static CIwUIElementItem* CIwUIElementItem::GetElementItem ( CIwUIElement * pElement ) [static]

Get the layout item containing the given element.

The documentation for this class was generated from the following file:
  • IwUIElementItem.h


Airplay API Reference: CIwUIElementPtr

Airplay API Reference > Data Structures > CIwUIElementPtr >

CIwUIElementPtr Class Reference
[Elements, Elements]

Smart(ish) point which becomes NULL when the element it points to is destroyed.

#include <IwUIElementPtr.h>

The documentation for this class was generated from the following file:
  • IwUIElementPtr.h


Airplay API Reference: CIwUIEventAlertDialogButton

Airplay API Reference > Data Structures > CIwUIEventAlertDialogButton >

CIwUIEventAlertDialogButton Class Reference
[Events, Events]

An alert dialog button was pressed.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventAlertDialogButton:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventButton

Airplay API Reference > Data Structures > CIwUIEventButton >

CIwUIEventButton Class Reference
[Events, Events]

CIwUIButton pressed event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventButton:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventCheckbox

Airplay API Reference > Data Structures > CIwUIEventCheckbox >

CIwUIEventCheckbox Class Reference
[Events, Events]

Checkbox on / off state toggle event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventCheckbox:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventClick

Airplay API Reference > Data Structures > CIwUIEventClick >

CIwUIEventClick Class Reference
[Events, Events]

s3ePointer button press event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventClick:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventFocus

Airplay API Reference > Data Structures > CIwUIEventFocus >

CIwUIEventFocus Class Reference
[Events, Events]

Keyboard focus change event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventFocus:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventKey

Airplay API Reference > Data Structures > CIwUIEventKey >

CIwUIEventKey Class Reference
[Events, Events]

s3eKey press / release event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventKey:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventLayout

Airplay API Reference > Data Structures > CIwUIEventLayout >

CIwUIEventLayout Class Reference
[Events, Events]

Layout of the specified element has just been updated.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventLayout:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventPointerEnter

Airplay API Reference > Data Structures > CIwUIEventPointerEnter >

CIwUIEventPointerEnter Class Reference
[Events, Events]

Event fired when the pointer enters an element (as determined by the element's intersect function).

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventPointerEnter:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventPointerLeave

Airplay API Reference > Data Structures > CIwUIEventPointerLeave >

CIwUIEventPointerLeave Class Reference
[Events, Events]

Event fired when the pointer leaves an element (as determined by the element's intersect function).

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventPointerLeave:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventPointerMove

Airplay API Reference > Data Structures > CIwUIEventPointerMove >

CIwUIEventPointerMove Class Reference
[Events, Events]

Pointer move event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventPointerMove:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventRadioButton

Airplay API Reference > Data Structures > CIwUIEventRadioButton >

CIwUIEventRadioButton Class Reference
[Events, Events]

CIwUIRadioButton selected event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventRadioButton:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventSlider

Airplay API Reference > Data Structures > CIwUIEventSlider >

CIwUIEventSlider Class Reference
[Events, Events]

Value of slider changed.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventSlider:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventSoftKey

Airplay API Reference > Data Structures > CIwUIEventSoftKey >

CIwUIEventSoftKey Class Reference
[Events, Events]

SoftKey pressed/released event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventSoftKey:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventTabBarButton

Airplay API Reference > Data Structures > CIwUIEventTabBarButton >

CIwUIEventTabBarButton Class Reference
[Events, Events]

A tab bar button was pressed.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventTabBarButton:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIEventTextInput

Airplay API Reference > Data Structures > CIwUIEventTextInput >

CIwUIEventTextInput Class Reference
[Events, Events]

Text input event.

#include <IwUIEvent.h>

Inheritance diagram for CIwUIEventTextInput:

[legend]
The documentation for this class was generated from the following file:
  • IwUIEvent.h


Airplay API Reference: CIwUIFocusHandler

Airplay API Reference > Data Structures > CIwUIFocusHandler >

CIwUIFocusHandler Class Reference
[Focus Handlers, Focus Handlers]

Base class for focus handlers. A focus handle can be attached to an element to respond to input and control which of the elements children has input focus.

#include <IwUIFocusHandler.h>

Inheritance diagram for CIwUIFocusHandler:

[legend]

Declared virtuals

static const char * | s_CloneExpectedClassName

Public interface

CIwUIFocusHandler * | Clone () const
static IwUIFocusWrapMode | GetWrapMode (CIwUIElement *pElement, IwUIFocusMovement movement)

Public Member Functions

IwDecomposable virtuals
Declared virtuals
virtual CIwUIElement * | FindWantsFocus (CIwUIElement *pParentElement) const
virtual CIwUIElement * | MoveFocus (CIwUIElement *pParentElement, CIwUIElement *pCurrentFocus, IwUIFocusMovement movement) const
IwParseable virtuals
virtual void | ParseClose (CIwTextParserITX *pParser)

Member Function Documentation

virtual void CIwUIFocusHandler::Clone ( CIwUIFocusHandler * pTarget ) const [protected, virtual]

Clone this focus handler on to the given target.

Reimplemented in CIwUIFocusHandler2D, and CIwUIFocusHandlerTab.

CIwUIFocusHandler* CIwUIFocusHandler::Clone ( ) const

Clone this focus handler.

Returns:
The clone, which the caller of this function owns.

virtual void CIwUIFocusHandler::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

virtual void CIwUIFocusHandler::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

virtual void CIwUIFocusHandler::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

virtual void CIwUIFocusHandler::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

virtual CIwUIElement* CIwUIFocusHandler::FindWantsFocus ( CIwUIElement * pParentElement ) const [virtual]

Attempt to choose a child of the given element that will accept focus.

Parameters:
pParentElement Element to choose child that can gain focus.
Returns:
A focusable child of pParentElement, otherwise NULL.

static IwUIFocusWrapMode CIwUIFocusHandler::GetWrapMode | ( | CIwUIElement * | pElement,
 |  | IwUIFocusMovement | movement |
 | ) |  |  | [static]

Query the given element's property set for the wrap mode for the given focus movement.

Parameters:
pElement | Element to query wrap mode property of.
movement | Direction to return wrap mode for.
Returns:
How focus should be moved to the end of a focus chain.

virtual CIwUIElement* CIwUIFocusHandler::MoveFocus | ( | CIwUIElement * | pParentElement,
 |  | CIwUIElement * | pCurrentFocus,
 |  | IwUIFocusMovement | movement |
 | ) |  |  | const [virtual]

Attempt to choose a child of pParentElement that will accept focus, relative to pCurrentFocus, moving in the given manner.

Parameters:
pParentElement | Element which contains pCurrentFocus
pCurrentFocus | Element to move focus relative to.
movement | Direction to find new focus element in.
Returns:
A focusable child of pParentElement, otherwise NULL.

Reimplemented in CIwUIFocusHandler2D, and CIwUIFocusHandlerTab.

virtual void CIwUIFocusHandler::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Field Documentation

const char* CIwUIFocusHandler::s_CloneExpectedClassName [static, protected]

Used by the Clone() method to enforce its declaration at every level of the hierarchy

The documentation for this class was generated from the following file:
  • IwUIFocusHandler.h


Airplay API Reference: CIwUIFocusHandler2D

Airplay API Reference > Data Structures > CIwUIFocusHandler2D >

CIwUIFocusHandler2D Class Reference
[Focus Handlers, Focus Handlers]

Concrete implementation of a focus handler which 'intelligently' moves focus based on 2D position + pressed direction.

#include <IwUIFocusHandler2D.h>

Inheritance diagram for CIwUIFocusHandler2D:

[legend]

Protected Member Functions

virtual CIwUIElement * MoveFocus (CIwUIElement *pParentElement, CIwUIElement *pCurrentFocus, IwUIFocusMovement movement) const

Member Function Documentation

virtual void CIwUIFocusHandler2D::Clone ( CIwUIFocusHandler * pTarget ) const [protected, virtual]

Clone this focus handler on to the given target.

Reimplemented from CIwUIFocusHandler.

virtual CIwUIElement* CIwUIFocusHandler2D::MoveFocus | ( | CIwUIElement * | pParentElement,
 |  | CIwUIElement * | pCurrentFocus,
 |  | IwUIFocusMovement | movement |
 | ) |  |  | const [protected, virtual]

Attempt to choose a child of pParentElement that will accept focus, relative to pCurrentFocus, moving in the given manner.

Parameters:
pParentElement | Element which contains pCurrentFocus
pCurrentFocus | Element to move focus relative to.
movement | Direction to find new focus element in.
Returns:
A focusable child of pParentElement, otherwise NULL.

Reimplemented from CIwUIFocusHandler.

The documentation for this class was generated from the following file:
  • IwUIFocusHandler2D.h


Airplay API Reference: CIwUIFocusHandlerTab

Airplay API Reference > Data Structures > CIwUIFocusHandlerTab >

CIwUIFocusHandlerTab Class Reference
[Focus Handlers, Focus Handlers]

Concrete implementation of a focus handler which simply moves focus based on element order.

#include <IwUIFocusHandlerTab.h>

Inheritance diagram for CIwUIFocusHandlerTab:

[legend]

Protected Member Functions

virtual CIwUIElement * MoveFocus (CIwUIElement *pParentElement, CIwUIElement *pCurrentFocus, IwUIFocusMovement movement) const

Member Function Documentation

virtual void CIwUIFocusHandlerTab::Clone ( CIwUIFocusHandler * pTarget ) const [protected, virtual]

Clone this focus handler on to the given target.

Reimplemented from CIwUIFocusHandler.

virtual CIwUIElement* CIwUIFocusHandlerTab::MoveFocus | ( | CIwUIElement * | pParentElement,
 |  | CIwUIElement * | pCurrentFocus,
 |  | IwUIFocusMovement | movement |
 | ) |  |  | const [protected, virtual]

Attempt to choose a child of pParentElement that will accept focus, relative to pCurrentFocus, moving in the given manner.

Parameters:
pParentElement | Element which contains pCurrentFocus
pCurrentFocus | Element to move focus relative to.
movement | Direction to find new focus element in.
Returns:
A focusable child of pParentElement, otherwise NULL.

Reimplemented from CIwUIFocusHandler.

The documentation for this class was generated from the following file:
  • IwUIFocusHandlerTab.h


Airplay API Reference: CIwUIGraphics

Airplay API Reference > Data Structures > CIwUIGraphics >

CIwUIGraphics Class Reference
[Rendering, Rendering]

Provides rendering functionality.

#include <IwUIGraphics.h>

Public Member Functions

CIwUIGraphics (const CIwUIRect drawArea=CIwUIRect(0, 0, IwGxGetScreenWidth(), IwGxGetScreenHeight()), const CIwMat &viewMat=CIwMat::g_Identity)
void | DebugDrawRect (const CIwUIRect &rect, const CIwUIColour &col)
void | DrawImage (CIwTexture *pTexture, CIwMaterial *pMaterial, const CIwUIRect &rect, const CIwSVec2 &uv0, const CIwSVec2 &uv1, const CIwUIColour &col, bool applyColour=true)
void | DrawText (const CIwGxFont *pFont, const CIwVec2 &position, const CIwGxFontPreparedData *pData, const CIwUIColour &col, bool applyColour=false)
void | IntersectFrame (const CIwUIRect &localFrame)
bool | IsFrameEmpty () const
void | ModulateColour (const CIwUIColour &colour)
void | SetViewMat (const CIwMat &viewMat)

Constructor & Destructor Documentation

CIwUIGraphics::CIwUIGraphics | ( | const CIwUIRect | drawArea = CIwUIRect(0, 0, IwGxGetScreenWidth(), IwGxGetScreenHeight()),
 |  | const CIwMat & | viewMat = CIwMat::g_Identity
 | ) |  |

Public constructor which by default sets up a graphics object to render to an area the size of the screen.

Parameters:
primitiveDrawer | Primitive drawer to use (lifetime must exceed that of the CIwUIGraphics object!)
drawArea | Optional top-level clipping rect.

CIwUIGraphics::CIwUIGraphics ( const CIwUIGraphics & graphics )

Private. CIwUIElement copies parent graphics internally.

Member Function Documentation

void CIwUIGraphics::ComposeTransform ( const CIwUIMat & transform )

Set transformation as the product of the current and given transformations.

void CIwUIGraphics::DebugDrawRect | ( | const CIwUIRect & | rect,
 |  | const CIwUIColour & | col
 | ) |  |

Outlines a rect with a line of the given colour. For debug use.

Parameters:
rect | Rect to outline in local coordinates
col | Colour to draw outline

void CIwUIGraphics::DrawImage | ( | CIwTexture * | pTexture,
 |  | CIwMaterial * | pMaterial,
 |  | const CIwUIRect & | rect,
 |  | const CIwSVec2 & | uv0,
 |  | const CIwSVec2 & | uv1,
 |  | const CIwUIColour & | col,
 |  | bool | applyColour = true
 | ) |  |

Queue an image to be drawn.

Parameters:
pTexture | Texture to use for image.
pMaterial | Material whose texture to use for image (may be NULL)
rect | Position and size to draw image, in local space of transform. That is, rect will be transformed.
uv0 | Top-left UV coordinate.
uv1 | Bottom-right UV coordinate.
col | Vertex colour to use.
applyColour | Should the current colour be applied to this draw call. The modulate colour is always applied regardless.

void CIwUIGraphics::DrawText | ( | const CIwGxFont * | pFont,
 |  | const CIwVec2 & | position,
 |  | const CIwGxFontPreparedData * | pData,
 |  | const CIwUIColour & | col,
 |  | bool | applyColour = false
 | ) |  |

Queue prepared text data to be drawn.

Parameters:
pFont | Font used to prepare pData.
position | Position to draw text, in local space of transform. That is, rect will be transformed.
pData | Prepared font data.
col | Colour to render text with.
applyColour | Should the current colour be applied to this draw call. The modulate colour is always applied regardless.

const CIwUIColour& CIwUIGraphics::GetColour ( ) const [inline]

/return The current colour.

CIwUIColour CIwUIGraphics::GetDrawColour | ( | const CIwUIColour & | col,
 |  | bool | applyColour
 | ) |  |

Query what colour will be used for a draw call.

CIwUIRect CIwUIGraphics::GetFrameBounds ( ) const

/return Get the containing bounds of the current clipping frame.

const CIwUIColour& CIwUIGraphics::GetModulateColour ( ) const [inline]

/return The current modulate colour.

CIwUIMat CIwUIGraphics::GetTransform ( ) const

return The current transformation.

CIwMat CIwUIGraphics::GetViewMat ( ) const

Get the current view transformation matrix.

void CIwUIGraphics::IntersectFrame ( const CIwUIRect & localFrame )

Intersect the clipping frame with the given rect. Rectangle will be transform before clipping is applied.

bool CIwUIGraphics::IsFrameEmpty ( ) const

/return Does the clipping frame have zero area and hence would completely clip all draw calls.

void CIwUIGraphics::ModulateColour ( const CIwUIColour & colour )

Set modulate colour as the product of the current modulate colour and given colour.

void CIwUIGraphics::SetColour ( CIwUIColour colour ) [inline]

/param colour Colour to set as current

void CIwUIGraphics::SetFrame ( const CIwUIRect & frame )

/param frame Clipping frame to set as current.

void CIwUIGraphics::SetModulateColour ( CIwUIColour colour ) [inline]

/param colour Colour to set as current modulate colour

void CIwUIGraphics::SetTransform ( const CIwUIMat & transform )

param transform Transformation to set as current.

void CIwUIGraphics::SetViewMat ( const CIwMat & viewMat )

Set the current view transformation matrix.

Parameters:
viewMat Post transformation to apply to rendered geometry.
Note:
Resets the current 2D transform.

void CIwUIGraphics::TranslateTransform ( const CIwVec2 & translation )

Apply a post-translation to the current transformation.

The documentation for this class was generated from the following file:
  • IwUIGraphics.h


Airplay API Reference: CIwUIHoldingPtr

Airplay API Reference > Data Structures > CIwUIHoldingPtr< Type > >

CIwUIHoldingPtr< Type > Class Template Reference
[Utility Classes, Utility Classes]

Smart pointer which manages destruction of its owned object, useful for pointer member management. More...

#include <IwUIHoldingPtr.h>

Inheritance diagram for CIwUIHoldingPtr< Type >:

[legend]

Detailed Description

template<typename Type>
class CIwUIHoldingPtr< Type >

Note:
Copying and assignment are not allowed.
The documentation for this class was generated from the following file:
  • IwUIHoldingPtr.h


Airplay API Reference: CIwUIImage

Airplay API Reference > Data Structures > CIwUIImage >

CIwUIImage Class Reference
[Elements, Elements]

Element used to display an image. Has no interaction. More...

#include <IwUIImage.h>

Inheritance diagram for CIwUIImage:

[legend]

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIRect | GetElementBounds () const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)

Detailed Description

Images use the following properties:

Type | Name | Description
CIwMaterial* | material | The material to use to render this image. NOTE: if a material is specified, a texture shouldn't be.
CIwMaterial* | texture | The texture to use to render this image. NOTE: if a texture is specified, a material shouldn't be.
CIwSVec2 | uv0 | The texel coordinates of the image's top-left corner.
CIwSVec2 | uv1 | The texel coordinates of the image's bottom-right corner.
CIwSVec2 | border | If this is specified, and non-zero, the image will be created using the border style, with a border of the width and height (in texels) specified.
bool | sizeToContent | Whether the image should be sized automatically to the same dimensions as its material.

Additionally, we may wish to support the following additional properties in the future:

Name | Description
animationImages | Array of ui images to animate through.
animation_duration | The time it takes to play one cycle of the animation, in milliseconds.

The documentation for this class was generated from the following file:
  • IwUIImage.h


Airplay API Reference: CIwUILabel

Airplay API Reference > Data Structures > CIwUILabel >

CIwUILabel Class Reference
[Elements, Elements]

Read-only text widget - single or multi-line. Has no interaction. More...

#include <IwUILabel.h>

Inheritance diagram for CIwUILabel:

[legend]

Public Member Functions

const char * | GetCaption () const
void | SetCaption (const char *pString)
void | SetCaptionLocalised (const char *pTag)

Protected Member Functions

IwUIElement virtuals
virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)

Detailed Description

Labels use the following properties:

Type | Name | Description
CIwGxFont* | font | Font to use to render this label.
CIwPropertyString | caption | The caption to display on this label, or the localisation tag of the string to use if the 'localise' property is true.
hash | localiseCaption | Identifier for Localised Caption to show next to the check box.
CIwSVec2 | margin | The margin to impose between the label's frame and its text.
bool | sizeToContent | If true, the label will be sized to fit its caption text. If a minimum or maximum sizes are specified for this element, they will be respected by the sizeToContent operation.
bool | oneLine | If true, text will not wrap, it will always appear on one line.
CIwUIStyle | background | If specified, the named property set resource will be used to create a drawable object which will provide the background graphic for the label.
IwUIAlignmentH | alignH | 'left', 'centre' or 'right' horizontal alignment of text.
IwUIAlignmentV | alignV | 'top', 'middle' or 'bottom' vertical alignment of text.

Member Function Documentation

virtual void CIwUILabel::Activate ( bool val ) [protected, virtual]

We hook into the activate call so that we can create / destroy our ui text object appropriately.

Reimplemented from CIwUIElement.

Reimplemented in CIwUITextField.

virtual void CIwUILabel::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Animate properties.

Reimplemented from CIwUIElement.

virtual void CIwUILabel::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

Reimplemented in CIwUITextField.

virtual void CIwUILabel::DebugRenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Debug Draw.

Reimplemented from CIwUIElement.

const char* CIwUILabel::GetCaption ( ) const

Get the caption string from the label.

Returns:
Ptr to caption string.

virtual CIwUIRect CIwUILabel::GetElementBounds ( ) const [protected, virtual]

Get bounding rectangle of our drawables.

Reimplemented from CIwUIElement.

const IIwUIDrawable* CIwUILabel::GetText ( ) [protected]

Get Text Drawable (N.B. Not necessarily a CIwUIDrawableText object).

virtual CIwVec2 CIwUILabel::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUILabel::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

Reimplemented in CIwUITextField.

virtual void CIwUILabel::OnSizeChanged ( ) [protected, virtual]

Update size of drawables.

Reimplemented from CIwUIElement.

Reimplemented in CIwUITextField.

virtual void CIwUILabel::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

We provide a custom render function.

Reimplemented from CIwUIElement.

Reimplemented in CIwUITextField.

void CIwUILabel::SetCaption ( const char * pString )

Set a string to be displayed on this label.

Parameters:
pString The string to set.

void CIwUILabel::SetCaptionLocalised ( const char * pTag )

Set a localised string to be displayed on this label.

Parameters:
pTag The localisation tag of the string to set.

The documentation for this class was generated from the following file:
  • IwUILabel.h


Airplay API Reference: CIwUILayout

Airplay API Reference > Data Structures > CIwUILayout >

CIwUILayout Class Reference
[Layout, Layout]

Base class for all layout types.

#include <IwUILayout.h>

Inheritance diagram for CIwUILayout:

[legend]

Public Member Functions

bool | GetSizeToSpace () const
bool | InsertElement (CIwUIElement *pElement, const CIwVec2 &pos, int16 tolerance)
bool | MoveElement (CIwUIElement *pElement, const CIwVec2 &pos, int16 tolerance)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual bool | RemoveElement (CIwUIElement *pElement)
virtual void | Resolve ()
virtual void | Serialise ()

Protected Member Functions

virtual void | ArrangeItem (const CIwVec2 &pos, const CIwVec2 &size)
virtual void | Clone (CIwUILayoutItem *pTarget) const
virtual CIwUILayoutItemContainer * | ContainerFactory ()
virtual CIwUIElement * | GetParentElement () const
virtual CIwUILayoutItemContainer * | InsertIntoLayout (CIwUILayoutItem *pItem, const CIwVec2 &insertPos, const CIwVec2 &arrangePos, const CIwVec2 &arrangeSize)
virtual bool | InsertItem (CIwUILayoutItem *pItem, const CIwVec2 &insertPos, int16 tolerance, const CIwVec2 &arrangePos, const CIwVec2 &arrangeSize)
virtual CIwUILayoutItemContainer * | InsertOverLayoutItem (CIwUILayoutItem *pInsertItem, const CIwVec2 &insertPos, CIwUILayoutItemContainer *pContainer)
virtual bool | PopulateElement (CIwUIElement *pElement)

Static Protected Member Functions

static bool | TestInsertPos (const CIwVec2 &insertPos, int16 tolerance, const CIwVec2 &rectPos, const CIwVec2 &rectSize)

Member Function Documentation

void CIwUILayout::AddElement | ( | CIwUIElement * | pElement,
 |  | const CIwUIStyle & | style
 | ) |  |

Add an element to this layout, using the given style to obtain required properties.

void CIwUILayout::AddElement | ( | CIwUIElement * | pElement,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add an element to this layout, with given alignment. Element can only be a child of this layout's ultimate parent.

void CIwUILayout::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const CIwUIStyle & | style
 | ) |  |

Add a layout item to this layout, using the given style to obtain required properties.

void CIwUILayout::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add a layout item to this layout, with given alignment. The item becomes owned by the layout.

virtual void CIwUILayout::ArrangeItem | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | size |
 | ) |  |  | [protected, virtual]

Provide position and size for item, and ask item to layout children within the given area.

Implements CIwUILayoutItem.

virtual void CIwUILayout::Attach ( ) [protected, virtual]

CIwUILayoutItem virtuals.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayout::Clone ( CIwUILayoutItem * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the destination object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function and call the base class version.

Reimplemented from CIwUILayoutItem.

CIwUILayout* CIwUILayout::Clone ( ) const

Create a copy of this layout and its children.

Reimplemented from CIwUILayoutItem.

virtual CIwUILayoutItemContainer* CIwUILayout::ContainerFactory ( ) [protected, virtual]

Create a CIwUILayoutItemContainer.

Note:
Derived classes can override if they want to use a derived CIwUILayoutItemContainer class to store more information.

virtual void CIwUILayout::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out the full definition of child objects.

Reimplemented from CIwUILayoutItem.

Reimplemented in CIwUILayoutGrid.

CIwUILayoutItemContainer* CIwUILayout::GetLayoutItem ( CIwUILayoutItem * pItem ) [protected]

Get the container item which contains the given item (non-recursive).

const CIwUILayoutItemContainer* CIwUILayout::GetLayoutItem ( const char * pName ) const [protected]

Get container item by name.

CIwUILayoutItemContainer* CIwUILayout::GetLayoutItem ( int i ) [protected]

Get container item by index.

CIwUILayoutItemContainer* CIwUILayout::GetLayoutItem ( CIwUIElement * pElement )

Get the container item which contains the given element (recursive).

int CIwUILayout::GetLayoutItemIndex | ( | CIwUILayoutItem * | pItem,
 |  | bool | recursive = false |
 | ) |  |  | const [protected]

Get the index of the container item which contains the given item (optionally recursive).

CIwManagedList& CIwUILayout::GetLayoutItems ( ) [inline, protected]

Access layout item array.

int CIwUILayout::GetNumLayoutItems ( ) const [protected]

Get the number of items the layout contains.

virtual CIwUIElement* CIwUILayout::GetParentElement ( ) const [protected, virtual]

Returns parent element if we have one. This may not be our immediate parent but rather the element our parent layout is attached to.

Reimplemented from CIwUILayoutItem.

bool CIwUILayout::GetSizeToSpace ( ) const

Returns:
If this layout will attempt to fit to the space available to it to arrange elements within.

bool CIwUILayout::InsertElement | ( | CIwUIElement * | pElement,
 |  | const CIwVec2 & | pos,
 |  | int16 | tolerance
 | ) |  |

Attempt to insert an element, at given position, into layout.

Parameters:
pos Absolute position we wish to insert element at.
Note:
Layout must be valid before calling .

Should only be called on top-level layout attached to an element.

virtual CIwUILayoutItemContainer* CIwUILayout::InsertIntoLayout | ( | CIwUILayoutItem * | pItem,
 |  | const CIwVec2 & | insertPos,
 |  | const CIwVec2 & | arrangePos,
 |  | const CIwVec2 & | arrangeSize |
 | ) |  |  | [protected, virtual]

Attempt to insert item into this layout. Called by InsertItem, which has already attempted to insert item into layout's children.

Note:
Derived classes can override this function to customise insertion position.

virtual bool CIwUILayout::InsertIntoLayoutItem | ( | CIwUILayoutItem * | pInsertItem,
 |  | const CIwVec2 & | insertPos,
 |  | int16 | tolerance,
 |  | CIwUILayoutItemContainer * | pContainer |
 | ) |  |  | [protected, virtual]

Attempt to insert item into an existing container item.

virtual bool CIwUILayout::InsertItem | ( | CIwUILayoutItem * | pItem,
 |  | const CIwVec2 & | insertPos,
 |  | int16 | tolerance,
 |  | const CIwVec2 & | arrangePos,
 |  | const CIwVec2 & | arrangeSize |
 | ) |  |  | [protected, virtual]

Attempt to add the given item into layout hierarchy. Returns if item was added. Item can be inserted if lies within rectangle defined by & . Tolerance is used when area of is zero.

As layout items do not in general store a concept of their position & size, this information must be provided. However, the layout should be valid before calling so any cached values are correct. The and parameters should be equal to those passed to when the layout was last calculated.

Parameters:
pItem | Layout item to attempt to insert into hierarchy.
insertPos | Position, relative to arrangePos, to insert .
tolerance | Allowed distance from insertPos we can insert .
arrangePos | Position last passed to ArrangeItem
arrangePos | Size last passed to ArrangeItem
Returns:
If we inserted the item.

Reimplemented from CIwUILayoutItem.

virtual CIwUILayoutItemContainer* CIwUILayout::InsertOverLayoutItem | ( | CIwUILayoutItem * | pInsertItem,
 |  | const CIwVec2 & | insertPos,
 |  | CIwUILayoutItemContainer * | pContainer |
 | ) |  |  | [protected, virtual]

Attempt to insert item at the position of an existing container item.

Note:
Derived classes can override this function to customise insertion position.

virtual void CIwUILayout::InvalidateLayout ( ) [protected, virtual]

Invalid this items layout. Also invalidates parent's layout.

Reimplemented from CIwUILayoutItem.

bool CIwUILayout::IsAttached ( ) const [inline]

Has layout's parent element called Attach.

virtual bool CIwUILayout::IsChildElement ( CIwUIElement * pElement ) const [protected, virtual]

Is the given element attached to this item, or one of its children.

Reimplemented from CIwUILayoutItem.

bool CIwUILayout::IsLayoutInvalid ( ) const [inline]

Query if the layout needs reapplying.

virtual CIwVec2 CIwUILayout::MeasureItem ( const CIwVec2 & availableSize ) const [protected, virtual]

Calculate desired size given an available size.

Implements CIwUILayoutItem.

bool CIwUILayout::MoveElement | ( | CIwUIElement * | pElement,
 |  | const CIwVec2 & | pos,
 |  | int16 | tolerance
 | ) |  |

Attempt to move an element, which is already contained in this layout, to the given position.

Parameters:
pos Absolute position we wish to insert element at.
Note:
Layout must be valid before calling .

Should only be called on top-level layout attached to an element.

virtual bool CIwUILayout::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwUILayoutItem.

Reimplemented in CIwUILayoutGrid.

virtual void CIwUILayout::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual void CIwUILayout::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Reimplemented in CIwUILayoutGrid.

void CIwUILayout::Populate ( const CIwManagedList & elements )

Call to bind a layout to its element's children. Binds only children which were specified in data somewhere in this layout's hierarchy. The elements should be children of this layout's parent.

virtual bool CIwUILayout::PopulateElement ( CIwUIElement * pElement ) [protected, virtual]

Attempt to attach element to layout item. /return If the element was attached to the layout item.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayout::RemoveChildItem ( CIwUILayoutItem * pChild ) [protected, virtual]

Remove a child item from this item.

Implements CIwUILayoutItem.

virtual bool CIwUILayout::RemoveElement ( CIwUIElement * pElement ) [virtual]

Attempt to detach element from layout item. /return If the element was attached to the item & has been detached.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayout::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwUILayoutItem.

Reimplemented in CIwUILayoutGrid.

virtual void CIwUILayout::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwUILayoutItem.

Reimplemented in CIwUILayoutGrid.

void CIwUILayout::SetElement ( CIwUIElement * pElement )

Set the parent element of this layout.

void CIwUILayout::SetLayoutInvalid ( bool val ) [inline, protected]

Control layout validity flag.

void CIwUILayout::SetSizeToSpace ( bool val )

Set if this layout should size to fit the space available to it to arrange elements within.

static bool CIwUILayout::TestInsertPos | ( | const CIwVec2 & | insertPos,
 |  | int16 | tolerance,
 |  | const CIwVec2 & | rectPos,
 |  | const CIwVec2 & | rectSize |
 | ) |  |  | [static, protected]

Test if insertion position is within given rectangle.

Note:
If area of provided rectangle is zero, then we test if is within of .

The documentation for this class was generated from the following file:
  • IwUILayout.h


Airplay API Reference: CIwUILayoutForm

Airplay API Reference > Data Structures > CIwUILayoutForm >

CIwUILayoutForm Class Reference
[Layout, Layout]

Form type layout. Form has a notional size. Items are positioned and size relative to the forms size. Item's can be placed relative to other items used as guides.

#include <IwUILayoutForm.h>

Inheritance diagram for CIwUILayoutForm:

[legend]

Data Structures

class | Dimension
class | Item

Member Function Documentation

void CIwUILayoutForm::AddElement | ( | CIwUIElement * | pElement,
 |  | const CIwUIStyle & | style,
 |  | const Dimension & | left,
 |  | const Dimension & | top,
 |  | const Dimension & | right,
 |  | const Dimension & | bottom
 | ) |  |

Add an element to form with given position, span & style. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutForm::AddElement | ( | CIwUIElement * | pElement,
 |  | const Dimension & | left,
 |  | const Dimension & | top,
 |  | const Dimension & | right,
 |  | const Dimension & | bottom,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add an element to form at given position, span & alignment. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutForm::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const CIwUIStyle & | style,
 |  | const Dimension & | left,
 |  | const Dimension & | top,
 |  | const Dimension & | right,
 |  | const Dimension & | bottom
 | ) |  |

Add a layout item to form with given position, span & style. The item becomes owned by the form.

void CIwUILayoutForm::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const Dimension & | left,
 |  | const Dimension & | top,
 |  | const Dimension & | right,
 |  | const Dimension & | bottom,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add a layout item to form at given position, span & alignment. The item becomes owned by the form.

CIwVec2 CIwUILayoutForm::GetFormSize ( ) const [inline]

Get size of form layout which items are positioned & sized relative to.

void CIwUILayoutForm::SetFormSize ( const CIwVec2 & formSize )

Set size of form layout.

The documentation for this class was generated from the following file:
  • IwUILayoutForm.h


Airplay API Reference: CIwUILayoutGrid

Airplay API Reference > Data Structures > CIwUILayoutGrid >

CIwUILayoutGrid Class Reference
[Layout, Layout]

Grid type layout. Organises contained items on a grid.

#include <IwUILayoutGrid.h>

Inheritance diagram for CIwUILayoutGrid:

[legend]

Public Member Functions

int | GetNumColumns () const
int | GetNumRows () const
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual void | Resolve ()
virtual void | Serialise ()

Data Structures

class | File
class | Item

Member Function Documentation

void CIwUILayoutGrid::AddColumn | ( | int16 | minSize = 0,
 |  | int16 | maxSize = INT16_MAX
 | ) |  |

Add a column to the right of the grid, with the given size restrictions.

void CIwUILayoutGrid::AddElement | ( | CIwUIElement * | pElement,
 |  | const CIwUIStyle & | style,
 |  | int16 | column,
 |  | int16 | row,
 |  | int16 | columnSpan = 1,
 |  | int16 | rowSpan = 1
 | ) |  |

Add an element to grid with given position, span & style. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutGrid::AddElement | ( | CIwUIElement * | pElement,
 |  | int16 | column,
 |  | int16 | row,
 |  | int16 | columnSpan = 1,
 |  | int16 | rowSpan = 1,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add an element to grid at given position, span & alignment. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutGrid::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const CIwUIStyle & | style,
 |  | int16 | column,
 |  | int16 | row,
 |  | int16 | columnSpan = 1,
 |  | int16 | rowSpan = 1
 | ) |  |

Add a layout item to grid with given position, span & style. The item becomes owned by the grid.

void CIwUILayoutGrid::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | int16 | column,
 |  | int16 | row,
 |  | int16 | columnSpan = 1,
 |  | int16 | rowSpan = 1,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add a layout item to grid at given position, span & alignment. The item becomes owned by the grid.

void CIwUILayoutGrid::AddRow | ( | int16 | minSize = 0,
 |  | int16 | maxSize = INT16_MAX
 | ) |  |

Add a row to the bottom of the grid, with the given size restrictions.

virtual void CIwUILayoutGrid::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out member data but not child objects.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutGrid::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out the full definition of child objects.

Reimplemented from CIwUILayout.

int CIwUILayoutGrid::GetNumColumns ( ) const

Returns:
Number of columns in this grid

int CIwUILayoutGrid::GetNumRows ( ) const

Returns:
Number of rows in this grid

virtual bool CIwUILayoutGrid::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwUILayout.

virtual void CIwUILayoutGrid::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwUILayout.

virtual void CIwUILayoutGrid::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwUILayout.

virtual void CIwUILayoutGrid::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwUILayout.

The documentation for this class was generated from the following file:
  • IwUILayoutGrid.h


Airplay API Reference: CIwUILayoutHorizontal

Airplay API Reference > Data Structures > CIwUILayoutHorizontal >

CIwUILayoutHorizontal Class Reference
[Layout, Layout]

Simple layout which lays out elements in a single row.

#include <IwUILayoutHorizontal.h>

Inheritance diagram for CIwUILayoutHorizontal:

[legend]

Public Member Functions

void | SetOrder (CIwUIElement *pElement, int16 order)

Data Structures

class | Item

Member Function Documentation

void CIwUILayoutHorizontal::AddElement | ( | CIwUIElement * | pElement,
 |  | const CIwUIStyle & | style,
 |  | int16 | order = 0
 | ) |  |

Add an element to this layout, with given order & style. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutHorizontal::AddElement | ( | CIwUIElement * | pElement,
 |  | int16 | order = 0,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add an element to this layout, with given order & alignment. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutHorizontal::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const CIwUIStyle & | style,
 |  | int16 | order = 0
 | ) |  |

Add a layout item to this layout, with given order & style. The item becomes owned by the layout.

void CIwUILayoutHorizontal::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | int16 | order = 0,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add a layout item to this layout, with given order & alignment. The item becomes owned by the layout.

void CIwUILayoutHorizontal::SetOrder | ( | CIwUIElement * | pElement,
 |  | int16 | order
 | ) |  |

Set the positioning of this element for layout. Elements with higher order numbers will be positioned further right (higher x) than elements with lower order numbers. By default elements all have order number 0. Elements with the same order number are sorted in the order they were added to the list.

void CIwUILayoutHorizontal::SetSpacing ( int16 spacing )

Set spacing between layout items.

The documentation for this class was generated from the following file:
  • IwUILayoutHorizontal.h


Airplay API Reference: CIwUILayoutItem

Airplay API Reference > Data Structures > CIwUILayoutItem >

CIwUILayoutItem Class Reference
[Layout, Layout]

UI base class to support layout. Interface supports layout, cloning & parentage.

#include <IwUILayoutItem.h>

Inheritance diagram for CIwUILayoutItem:

[legend]

Public Member Functions

virtual void | ArrangeItem (const CIwVec2 &pos, const CIwVec2 &size)=0
virtual CIwUIElement * | GetParentElement () const
template<class Type>
bool | GetProperty (const char *pName, Type &val, bool allowMissing=false) const
virtual bool | InsertItem (CIwUILayoutItem *pItem, const CIwVec2 &insertPos, int16 tolerance, const CIwVec2 &arrangePos, const CIwVec2 &arrangeSize)
virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual bool | PopulateElement (CIwUIElement *pElement)
virtual bool | RemoveElement (CIwUIElement *pElement)
virtual void | Resolve ()
virtual void | Serialise ()
virtual void | SetName (const char *pName)

Protected Member Functions

virtual void | Clone (CIwUILayoutItem *pTarget) const
template<class Type>
bool | SetProperty (const char *pName, const Type &val)
void | SetStyle (const CIwUIStyle &style)

Member Function Documentation

virtual void CIwUILayoutItem::ArrangeItem | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | size |
 | ) |  |  | [pure virtual]

Provide position and size for item, and ask item to layout children within the given area.

Implemented in CIwUILayout, CIwUILayoutItemContainer, and CIwUILayoutSpacer.

virtual void CIwUILayoutItem::Attach ( ) [virtual]

Attach occurs when parent layout's element is activated.

Reimplemented in CIwUILayout, CIwUILayoutItemContainer, and CIwUILayoutSpacer.

virtual void CIwUILayoutItem::Clone ( CIwUILayoutItem * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the destination object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function and call the base class version.

Reimplemented in CIwUILayout, CIwUILayoutItemContainer, and CIwUILayoutSpacer.

CIwUILayoutItem* CIwUILayoutItem::Clone ( ) const

Clone this item and all its descendants.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out member data but not child objects.

Implements IIwDecomposable.

Reimplemented in CIwUILayoutGrid.

virtual void CIwUILayoutItem::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [inline, virtual]

Implementations of this function should write out the full definition of child objects.

Implements IIwDecomposable.

Reimplemented in CIwUILayout, CIwUILayoutGrid, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Implements IIwDecomposable.

Reimplemented in CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implements IIwDecomposable.

Reimplemented in CIwUILayoutItemContainer.

CIwUIPropertySet& CIwUILayoutItem::ExposePropertySet ( ) [inline, protected]

Expose this layout item's property set.

virtual CIwUIElement* CIwUILayoutItem::GetParentElement ( ) const [virtual]

Returns parent element if we have one. This may not be our immediate parent but rather the element our parent layout is attached to.

Reimplemented in CIwUILayout.

CIwUILayoutItem* CIwUILayoutItem::GetParentItem ( ) const [inline]

Returns parent item if we have one.

template<class Type>
bool CIwUILayoutItem::GetProperty | ( | const char * | pName,
 |  | Type & | val,
 |  | bool | allowMissing = false |
 | ) |  |  | const [inline]

Get the value of a named property.

Parameters:
pName | Name of the property definition we're searching for.
val | Reference to a variable that will store the value upon success.
Returns:
Boolean upon success/failure of search

const CIwUIPropertySet& CIwUILayoutItem::GetPropertySet ( ) const [inline]

Expose this layout item's property set for read-only access.

virtual bool CIwUILayoutItem::InsertItem | ( | CIwUILayoutItem * | pItem,
 |  | const CIwVec2 & | insertPos,
 |  | int16 | tolerance,
 |  | const CIwVec2 & | arrangePos,
 |  | const CIwVec2 & | arrangeSize |
 | ) |  |  | [inline, virtual]

Attempt to add the given item into layout hierarchy. Returns if item was added. Item can be inserted if lies within rectangle defined by & . Tolerance is used when area of is zero.

As layout items do not in general store a concept of their position & size, this information must be provided. However, the layout should be valid before calling so any cached values are correct. The and parameters should be equal to those passed to when the layout was last calculated.

Parameters:
pItem | Layout item to attempt to insert into hierarchy.
insertPos | Position, relative to arrangePos, to insert .
tolerance | Allowed distance from insertPos we can insert .
arrangePos | Position last passed to ArrangeItem
arrangePos | Size last passed to ArrangeItem
Returns:
If we inserted the item.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::InvalidateLayout ( ) [virtual]

Invalid this items layout. Also invalidates parent's layout.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual bool CIwUILayoutItem::IsChildElement ( CIwUIElement * pElement ) const [virtual]

Is the given element attached to this item, or one of its children.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual CIwVec2 CIwUILayoutItem::MeasureItem ( const CIwVec2 & availableSize ) const [pure virtual]

Calculate desired size given an available size.

Implemented in CIwUILayout, CIwUILayoutItemContainer, and CIwUILayoutSpacer.

virtual bool CIwUILayoutItem::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwManaged.

Reimplemented in CIwUILayout, and CIwUILayoutGrid.

virtual bool CIwUILayoutItem::PopulateElement ( CIwUIElement * pElement ) [inline, virtual]

Attempt to attach element to layout item. /return If the element was attached to the layout item.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::RemoveChildItem ( CIwUILayoutItem * pChild ) [protected, pure virtual]

Remove a child item from this item.

Implemented in CIwUILayout, CIwUILayoutItemContainer, and CIwUILayoutSpacer.

virtual bool CIwUILayoutItem::RemoveElement ( CIwUIElement * pElement ) [inline, virtual]

Attempt to detach element from layout item. /return If the element was attached to the item & has been detached.

Reimplemented in CIwUILayout, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

Reimplemented in CIwUILayout, CIwUILayoutGrid, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

Reimplemented in CIwUILayout, CIwUILayoutGrid, and CIwUILayoutItemContainer.

virtual void CIwUILayoutItem::SetName ( const char * pName ) [virtual]

Set name (hashed value)

Parameters:
pName the hashed name of the managed object
Note:
derived classes are responsible for overiding this method
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwUILayoutItem::SetParentItem ( CIwUILayoutItem * pParentItem )

Set parent item. Removes this item from any previous parent.

template<class Type>
bool CIwUILayoutItem::SetProperty | ( | const char * | pName,
 |  | const Type & | val |
 | ) |  |  | [inline, protected]

Set the value of a named property.

Parameters:
pName | Name of the property to set.
val | Value to set on the property.
Returns:
Boolean indicating if the store value changed.

void CIwUILayoutItem::SetStyle ( const CIwUIStyle & style ) [protected]

An layout item's style is used at attachment to look up a parent property set.

Parameters:
style Style to apply to layout item.

Field Documentation

const char* CIwUILayoutItem::s_CloneExpectedClassName [static, protected]

Used by the Clone() method to enforce its declaration at every level of the hierarchy.

The documentation for this class was generated from the following file:
  • IwUILayoutItem.h


Airplay API Reference: CIwUILayoutItemContainer

Airplay API Reference > Data Structures > CIwUILayoutItemContainer >

CIwUILayoutItemContainer Class Reference
[Layout, Layout]

Used as a container around CIwUILayoutItem added to a CIwUILayout. Contains additional data such as alignment for the item. Also provides simple caching system.

#include <IwUILayoutItemContainer.h>

Inheritance diagram for CIwUILayoutItemContainer:

[legend]

Public Member Functions

virtual void | ParseCloseChild (CIwTextParserITX *pParser, CIwManaged *pChild)
virtual bool | PopulateElement (CIwUIElement *pElement)
virtual bool | RemoveElement (CIwUIElement *pElement)
virtual void | Resolve ()
virtual void | Serialise ()

Protected Member Functions

virtual void | ArrangeItem (const CIwVec2 &pos, const CIwVec2 &size)
virtual void | Clone (CIwUILayoutItem *pTarget) const
virtual bool | InsertItem (CIwUILayoutItem *pItem, const CIwVec2 &insertPos, int16 tolerance, const CIwVec2 &arrangePos, const CIwVec2 &arrangeSize)

Member Function Documentation

void CIwUILayoutItemContainer::Arrange | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | area
 | ) |  |

Layout within the given rectangle.

virtual void CIwUILayoutItemContainer::ArrangeItem | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | size |
 | ) |  |  | [protected, virtual]

Provide position and size for item, and ask item to layout children within the given area.

Implements CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::Attach ( ) [virtual]

CIwUILayoutItem virtuals.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::Clone ( CIwUILayoutItem * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the destination object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function and call the base class version.

Reimplemented from CIwUILayoutItem.

CIwUILayoutItemContainer* CIwUILayoutItemContainer::Clone ( ) const

Clone this item.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out the full definition of child objects.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object opened a new scope in then it should be closed here.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Reimplemented from CIwUILayoutItem.

IwUIAlignmentH CIwUILayoutItemContainer::GetAlignmentH ( ) const

Get the horizontal alignment of contained item.

IwUIAlignmentV CIwUILayoutItemContainer::GetAlignmentV ( ) const

Get the vertical alignment of contained item.

CIwSVec2 CIwUILayoutItemContainer::GetBorder ( ) const

Get the border of the contained item.

const CIwVec2& CIwUILayoutItemContainer::GetCachedArrangeArea ( ) const

Get previous arrange area. Asserts if layout is invalid.

const CIwVec2& CIwUILayoutItemContainer::GetCachedArrangePos ( ) const

Get previous arrange position. Asserts if layout is invalid.

CIwUILayoutItem* CIwUILayoutItemContainer::GetItem ( ) const [inline]

Get the item we contain.

virtual bool CIwUILayoutItemContainer::InsertItem | ( | CIwUILayoutItem * | pItem,
 |  | const CIwVec2 & | insertPos,
 |  | int16 | tolerance,
 |  | const CIwVec2 & | arrangePos,
 |  | const CIwVec2 & | arrangeSize |
 | ) |  |  | [protected, virtual]

Attempt to add the given item into layout hierarchy. Returns if item was added. Item can be inserted if lies within rectangle defined by & . Tolerance is used when area of is zero.

As layout items do not in general store a concept of their position & size, this information must be provided. However, the layout should be valid before calling so any cached values are correct. The and parameters should be equal to those passed to when the layout was last calculated.

Parameters:
pItem | Layout item to attempt to insert into hierarchy.
insertPos | Position, relative to arrangePos, to insert .
tolerance | Allowed distance from insertPos we can insert .
arrangePos | Position last passed to ArrangeItem
arrangePos | Size last passed to ArrangeItem
Returns:
If we inserted the item.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::InvalidateLayout ( ) [virtual]

Invalid this items layout. Also invalidates parent's layout.

Reimplemented from CIwUILayoutItem.

virtual bool CIwUILayoutItemContainer::IsChildElement ( CIwUIElement * pElement ) const [virtual]

Is the given element attached to this item, or one of its children.

Reimplemented from CIwUILayoutItem.

CIwVec2 CIwUILayoutItemContainer::Measure ( const CIwVec2 & availableSize ) const

Calculate desired size given an available size.

virtual CIwVec2 CIwUILayoutItemContainer::MeasureItem ( const CIwVec2 & availableSize ) const [protected, virtual]

Calculate desired size given an available size.

Implements CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::ParseCloseChild | ( | CIwTextParserITX * | pParser,
 |  | CIwManaged * | pChild |
 | ) |  |  | [virtual]

Extends CIwParseable interface with this extra function: called on any "parent" object, if the "child" has not implemented ParseClose.

Parameters:
pParser | The parser instance to use.
pChild | The pointer to the child class.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

virtual bool CIwUILayoutItemContainer::PopulateElement ( CIwUIElement * pElement ) [virtual]

Attempt to attach element to layout item. /return If the element was attached to the layout item.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::RemoveChildItem ( CIwUILayoutItem * pChild ) [protected, virtual]

Remove a child item from this item.

Implements CIwUILayoutItem.

virtual bool CIwUILayoutItemContainer::RemoveElement ( CIwUIElement * pElement ) [virtual]

Attempt to detach element from layout item. /return If the element was attached to the item & has been detached.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutItemContainer::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwUILayoutItem.

void CIwUILayoutItemContainer::SetAlignment | ( | IwUIAlignmentH | alignH,
 |  | IwUIAlignmentV | alignV
 | ) |  |

Set alignment to apply to contained item.

void CIwUILayoutItemContainer::SetAlignmentFromPos | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | rectPos,
 |  | const CIwVec2 & | rectSize
 | ) |  |

Set alignment of item from position within a rectangle.

void CIwUILayoutItemContainer::SetBorder ( CIwSVec2 border )

Set border around contained item.

void CIwUILayoutItemContainer::SetItem ( CIwUILayoutItem * pItem )

Set item to contain.

The documentation for this class was generated from the following file:
  • IwUILayoutItemContainer.h


Airplay API Reference: CIwUILayoutSpacer

Airplay API Reference > Data Structures > CIwUILayoutSpacer >

CIwUILayoutSpacer Class Reference
[Layout, Layout]

Layout item to add space into a layout.

#include <IwUILayoutSpacer.h>

Inheritance diagram for CIwUILayoutSpacer:

[legend]

Protected Member Functions

virtual void | ArrangeItem (const CIwVec2 &pos, const CIwVec2 &size)
virtual void | Clone (CIwUILayoutItem *pTarget) const

Member Function Documentation

virtual void CIwUILayoutSpacer::ArrangeItem | ( | const CIwVec2 & | pos,
 |  | const CIwVec2 & | size |
 | ) |  |  | [protected, virtual]

Provide position and size for item, and ask item to layout children within the given area.

Implements CIwUILayoutItem.

virtual void CIwUILayoutSpacer::Attach ( ) [protected, virtual]

Attach occurs when parent layout's element is activated.

Reimplemented from CIwUILayoutItem.

virtual void CIwUILayoutSpacer::Clone ( CIwUILayoutItem * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the destination object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function and call the base class version.

Reimplemented from CIwUILayoutItem.

virtual CIwVec2 CIwUILayoutSpacer::MeasureItem ( const CIwVec2 & availableSize ) const [protected, virtual]

Calculate desired size given an available size.

Implements CIwUILayoutItem.

virtual void CIwUILayoutSpacer::RemoveChildItem ( CIwUILayoutItem * pChild ) [protected, virtual]

Remove a child item from this item.

Implements CIwUILayoutItem.

The documentation for this class was generated from the following file:
  • IwUILayoutSpacer.h


Airplay API Reference: CIwUILayoutVertical

Airplay API Reference > Data Structures > CIwUILayoutVertical >

CIwUILayoutVertical Class Reference
[Layout, Layout]

Simple layout which lays out elements in a single column.

#include <IwUILayoutVertical.h>

Inheritance diagram for CIwUILayoutVertical:

[legend]

Public Member Functions

void | SetOrder (CIwUIElement *pElement, int16 order)

Data Structures

class | Item

Member Function Documentation

void CIwUILayoutVertical::AddElement | ( | CIwUIElement * | pElement,
 |  | const CIwUIStyle & | style,
 |  | int16 | order = 0
 | ) |  |

Add an element to this layout, with given order & style. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutVertical::AddElement | ( | CIwUIElement * | pElement,
 |  | int16 | order = 0,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add an element to this layout, with given order & alignment. Element can only be a child of this layout's ultimate parent.

void CIwUILayoutVertical::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | const CIwUIStyle & | style,
 |  | int16 | order = 0
 | ) |  |

Add a layout item to this layout, with given order & style. The item becomes owned by the layout.

void CIwUILayoutVertical::AddLayoutItem | ( | CIwUILayoutItem * | pLayoutItem,
 |  | int16 | order = 0,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE,
 |  | CIwSVec2 | border = CIwSVec2::g_Zero
 | ) |  |

Add a layout item to this layout, with given order & alignment. The item becomes owned by the layout.

void CIwUILayoutVertical::SetOrder | ( | CIwUIElement * | pElement,
 |  | int16 | order
 | ) |  |

Set the positioning of this element for layout. Elements with higher order numbers will be positioned lower down (higher y) than elements with lower order numbers. By default elements all have order number 0. Elements with the same order number are sorted in the order they were added to the list.

void CIwUILayoutVertical::SetSpacing ( int16 spacing )

Set spacing between layout items.

The documentation for this class was generated from the following file:
  • IwUILayoutVertical.h


Airplay API Reference: CIwUIPositionPolicy

Airplay API Reference > Data Structures > CIwUIPositionPolicy >

CIwUIPositionPolicy Class Reference
[Layout, Layout]

Encapsulates element positional preference.

#include <IwUILayoutPolicy.h>

Public Member Functions

CIwVec2 Apply (const CIwVec2 &size, const CIwVec2 &area, const CIwSVec2 &border=CIwSVec2::g_Zero) const

Member Function Documentation

CIwVec2 CIwUIPositionPolicy::Apply | ( | const CIwVec2 & | size,
 |  | const CIwVec2 & | area,
 |  | const CIwSVec2 & | border = CIwSVec2::g_Zero |
 | ) |  |  | const

Finds a position given constraints.

Parameters:
size | Size of element we are positioning.
area | Containing area to position element.
border | Optional border size to surround element.

void CIwUIPositionPolicy::Setup ( const CIwPropertySet & propertySet )

Read position policy from given property set.

void CIwUIPositionPolicy::Store ( CIwPropertySet & propertySet )

Write position policy to given property set.

The documentation for this class was generated from the following file:
  • IwUILayoutPolicy.h


Airplay API Reference: CIwUIProgressBar

Airplay API Reference > Data Structures > CIwUIProgressBar >

CIwUIProgressBar Class Reference
[Elements, Elements]

0-100% style progress bar. More...

#include <IwUIProgressBar.h>

Inheritance diagram for CIwUIProgressBar:

[legend]

Public Member Functions

iwfixed | GetProgress () const
void | SetProgress (iwfixed prop)

Detailed Description

Progress bars use the following properties:

Type | Name | Description
CIwMaterial* | material | The material to use to render the progress bar's... bar.
CIwUIStyle | background | Drawable style to use for the progress bar's background graphic.

Member Function Documentation

iwfixed CIwUIProgressBar::GetProgress ( ) const

Get progress proportion in 1.12 fixed format.

Returns:
Progress value between 0 and IW_GEOM_ONE.

void CIwUIProgressBar::SetProgress ( iwfixed prop )

Set progress proportion in 1.12 fixed format.

Parameters:
prop Progress value between 0 and IW_GEOM_ONE.

The documentation for this class was generated from the following file:
  • IwUIProgressBar.h


Airplay API Reference: CIwUIPropertySet

Airplay API Reference > Data Structures > CIwUIPropertySet >

CIwUIPropertySet Class Reference
[Properties and Styles, Properties and Styles]

Property set which uses a style to resolve its parent. This extends CIwPropertySet to support style sheets.

#include <IwUIPropertySet.h>

Inheritance diagram for CIwUIPropertySet:

[legend]

Public Member Functions

virtual bool | ParseAttribute (CIwTextParserITX *pParser, const char *pAttrName)
virtual void | ParseClose (CIwTextParserITX *pParser)
virtual void | Resolve ()
virtual void | Serialise ()

Member Function Documentation

virtual void CIwUIPropertySet::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [virtual]

Implementations of this function should write out member data but not child objects.

Reimplemented from CIwPropertySet.

virtual const CIwPropertySet* CIwUIPropertySet::GetParent ( ) const [virtual]

Get this property set's parent.

Reimplemented from CIwPropertySet.

virtual bool CIwUIPropertySet::ParseAttribute | ( | CIwTextParserITX * | pParser,
 |  | const char * | pAttrName |
 | ) |  |  | [virtual]

Parses from text file: parses attribute/value pair.

Parameters:
pParser | The parser instance to use
pAttrName | The name of the attribute to parse
Returns:
true if attribute has been set, false otherwise
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method to support a desired attribute list.

Reimplemented from CIwPropertySet.

virtual void CIwUIPropertySet::ParseClose ( CIwTextParserITX * pParser ) [virtual]

Parses from text file: end block.

Parameters:
pParser The parser instance to use.
See also:
CIwTextParseITX
Note:
Derived classes are responsible for overiding this method.
Required Header Files
IwManaged.h

Reimplemented from CIwPropertySet.

virtual void CIwUIPropertySet::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwPropertySet.

virtual void CIwUIPropertySet::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwPropertySet.

virtual void CIwUIPropertySet::SetParent ( const CIwPropertySet * pPropertySet ) [virtual]

Set a new parent for this property set.

Reimplemented from CIwPropertySet.

The documentation for this class was generated from the following file:
  • IwUIPropertySet.h


Airplay API Reference: CIwUIRadioButton

Airplay API Reference > Data Structures > CIwUIRadioButton >

CIwUIRadioButton Class Reference
[Elements, Elements]

Button with on and off states. To be placed within a tab bar.

#include <IwUIRadioButton.h>

Inheritance diagram for CIwUIRadioButton:

[legend]

Public Member Functions

bool | GetSelected () const
void | SetSelected (bool val)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIRect | GetElementBounds () const
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual bool | IntersectElement (const CIwVec2 &pos) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)

Member Function Documentation

virtual void CIwUIRadioButton::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIButton.

virtual void CIwUIRadioButton::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIButton.

virtual void CIwUIRadioButton::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIButton.

virtual CIwUIRect CIwUIRadioButton::GetElementBounds ( ) const [protected, virtual]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIButton.

bool CIwUIRadioButton::GetSelected ( ) const [inline]

Get current selection value of radio button.

Returns:
True if the radio button is selected.

virtual bool CIwUIRadioButton::HandleEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-handler for all ui elements.

Parameters:
pEvent Event to be handled.
Returns:
Boolean value signifying whether the event was handled.
Return values:
true | If the event was handled and requires no further processing.
false | If the event wasn't handled and so requires further processing.
Note:
Derived classes are encouraged to override one or more of the more specific event handlers, eg. HandleEventClick, etc, rather than this function.

Reimplemented from CIwUIElement.

virtual bool CIwUIRadioButton::IntersectElement ( const CIwVec2 & pos ) const [protected, virtual]

Test whether the specified position intersects with this element.

Note:
Custom elements wishing which wish to be clicked on should override this function.
Return values:
true | If the specified position intersects with this element.
false | If it doesn't.

Reimplemented from CIwUIButton.

virtual void CIwUIRadioButton::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIButton.

virtual void CIwUIRadioButton::OnSizeChanged ( ) [protected, virtual]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIButton.

virtual void CIwUIRadioButton::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIButton.

void CIwUIRadioButton::SetSelected ( bool val )

Set if radio button element is selected.

Parameters:
val Selected value to set.

The documentation for this class was generated from the following file:
  • IwUIRadioButton.h


Airplay API Reference: CIwUIRect

Airplay API Reference > Data Structures > CIwUIRect >

CIwUIRect Class Reference
[Utility Classes, Utility Classes]

Derived from CIwRect. Adds functionality such as intersection.

#include <IwUIRect.h>

Inheritance diagram for CIwUIRect:

[legend]

Public Member Functions

void DebugRender (iwfixed scale=IW_GEOM_ONE, CIwUIColour col=IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT)) const

Member Function Documentation

int32 CIwUIRect::Area ( ) const

Returns:
The product of the width and height of the rect.

void CIwUIRect::Clone ( const CIwUIRect & rect ) [inline]

Clone rectangle.

bool CIwUIRect::Contains ( const CIwUIRect & rect ) const

Returns:
If the given rect is contained wholly within this one.

void CIwUIRect::DebugRender | ( | iwfixed | scale = IW_GEOM_ONE,
 |  | CIwUIColour | col = IwGxGetColFixed(IW_GX_DEBUG_COLOUR_DEFAULT) |
 | ) |  |  | const

Render outline of rect in screen space

Parameters:
scale | Scale to apply to get pixel coordinates.
col | Colour to render lines in.

void CIwUIRect::Decompose ( CIwTextDecomposer * pDecomposer ) const

Decompose value.

CIwUIRect CIwUIRect::Intersection ( const CIwUIRect & rect ) const

Returns:
The rect which intersects this and the given rect.

bool CIwUIRect::Intersects ( const CIwVec2 & pos ) const

Returns:
If the specified position lies within our bounds.

bool CIwUIRect::Intersects ( const CIwUIRect & rect ) const

Returns:
If the given rect intersects with this one.

bool CIwUIRect::IsEmpty ( ) const [inline]

Returns:
If the area of the rect is zero.

CIwUIRect CIwUIRect::operator * ( iwfixed s ) const

Scalar scale operator.

bool CIwUIRect::operator!= ( const CIwUIRect & r ) const

Inequality operator.

CIwUIRect CIwUIRect::operator<< ( int32 s ) const

Scalar shift operator.

CIwRect32& CIwUIRect::operator= ( const CIwRect32 & r )

Set value from a CIwRect.

bool CIwUIRect::operator== ( const CIwUIRect & r ) const

Equality operator.

CIwUIRect CIwUIRect::operator>> ( int32 s ) const

Scalar shift operator.

void CIwUIRect::Parse ( CIwTextParserITX * pParser )

Parse value.

void CIwUIRect::Resolve ( ) [inline]

Empty resolve function.

void CIwUIRect::Serialise ( )

Serialise value.

void CIwUIRect::Translate ( const CIwVec2 & v ) [inline]

Adjusts positional part of rectangle.

CIwUIRect CIwUIRect::Union ( const CIwUIRect & rect ) const

Returns:
The smallest rect which contains this and the given rect.

The documentation for this class was generated from the following file:
  • IwUIRect.h


Airplay API Reference: CIwUIScrollableView

Airplay API Reference > Data Structures > CIwUIScrollableView >

CIwUIScrollableView Class Reference
[Elements, Elements]

Element which allows scrolling across content whose total extents exceed the size of the scrollable view widget, either via explicit interaction with the scrollbars(??), else via gestures in the main content area.

#include <IwUIScrollableView.h>

Inheritance diagram for CIwUIScrollableView:

[legend]

Public Member Functions

Queries
bool | IsScrollingRequired () const
Public interface
void | ScrollToPosition (const CIwVec2 &pos)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual void | Render (const CIwUIGraphics &graphics)
virtual void | Update (int32 deltaMS)

Data Structures

class | ScrollData

Member Function Documentation

virtual void CIwUIScrollableView::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUIScrollableView::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

bool CIwUIScrollableView::IsScrollingRequired ( ) const

Check whether the content within this scrollable view exceeds its frame size, that is, whether scrolling is required.

Returns:
True if content of scrollable view is larger than its size.
Note:
This applies to either axis.

virtual CIwVec2 CIwUIScrollableView::Measure ( const CIwVec2 & availableSize ) const [protected, virtual]

Calculates our desiredSize given an availableSize. Elements can override MeasureElement to provide custom size constraints.

Reimplemented from CIwUIElement.

virtual void CIwUIScrollableView::Render ( const CIwUIGraphics & parentGraphics ) [protected, virtual]

Render this element.

Parameters:
parentGraphics The parent's graphics context, which we should transform into our own frame of reference.
Note:
Overriding Render is not recommended, derived classes wishing to provide their own rendering implementation should override RenderElement().

Reimplemented from CIwUIElement.

void CIwUIScrollableView::ScrollToPosition ( const CIwVec2 & pos )

Scroll the view so that the specified position is at the top-left corner of this element's frame.

Parameters:
pos Sub-frame position to scroll to.

virtual void CIwUIScrollableView::Update ( int32 deltaMS ) [protected, virtual]

Per-frame update.

Parameters:
deltaMS The number of milliseconds since the last update.
Note:
This is only called if the element and its ancestor's are active and updatable.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUIScrollableView.h


Airplay API Reference: CIwUISizePolicy

Airplay API Reference > Data Structures > CIwUISizePolicy >

CIwUISizePolicy Class Reference
[Layout, Layout]

Encapsulates element size restraints. Hint is only applied when result would otherwise be unbounded.

#include <IwUILayoutPolicy.h>

Public Member Functions

CIwVec2 Apply (const CIwVec2 &size, bool applyHint=true, bool shrinkNotExpandToAspect=true) const

Member Function Documentation

CIwVec2 CIwUISizePolicy::Apply | ( | const CIwVec2 & | size,
 |  | bool | applyHint = true,
 |  | bool | shrinkNotExpandToAspect = true |
 | ) |  |  | const

Apply policy to constrain the given size.

Parameters:
size | Size to apply constraints to.
applyHint | Should the hint be set for dimensions for which it is bounded.
shrinkToAspect | Should size be shrunk, not expanded, to fit any aspect ratio that is set
Returns:
Constrained size.

void CIwUISizePolicy::Setup ( const CIwPropertySet & propertySet )

Read size policy from given property set.

void CIwUISizePolicy::Store ( CIwPropertySet & propertySet )

Write size policy to given property set.

The documentation for this class was generated from the following file:
  • IwUILayoutPolicy.h


Airplay API Reference: CIwUISlider

Airplay API Reference > Data Structures > CIwUISlider >

CIwUISlider Class Reference
[Elements, Elements]

Slider widget. If the user drags the button, or presses left/right whilst the slider has focus, it will generate a Slider event with itself as the source.

#include <IwUISlider.h>

Inheritance diagram for CIwUISlider:

[legend]

Public Member Functions

iwfixed | GetProportion () const
int16 | GetValue () const
void | SetProportion (iwfixed prop)
void | SetValue (int16 val)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual bool | FilterEvent (CIwEvent *pEvent)
virtual CIwUIRect | GetElementBounds () const
virtual bool | HandleEventClick (CIwUIEventClick *pEventClick)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | HandleEventPointerMove (CIwUIEventPointerMove *pEventPointerMove)
virtual bool | IntersectElement (const CIwVec2 &pos) const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | RenderElement (CIwUIGraphics &graphics)
virtual bool | WantsFocus () const

Member Function Documentation

virtual void CIwUISlider::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUISlider::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

virtual void CIwUISlider::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

virtual bool CIwUISlider::FilterEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-filter. Calls through to registered event handlers.

See also:
AddEventHandler()
Parameters:
pEvent Event to be filtered.
Returns:
Boolean value signifying whether the event was filtered.

Reimplemented from CIwUIElement.

virtual CIwUIRect CIwUISlider::GetElementBounds ( ) const [protected, virtual]

Returns a bounding rectangle of the elements visual content (drawables).

Note:
Clients should override this to support rectangle intersection testing. The caller is responsible for intersecting the result with the parent element's clipping frame where appropriate. If this function is not overridden, the element's frame is used as a bound
Returns:
Union of bounds of element's drawables - in element's frame of reference.

Reimplemented from CIwUIElement.

iwfixed CIwUISlider::GetProportion ( ) const

Get the slider's 1.12 fixed format values.

Returns:
Current fixed format slider value.

int16 CIwUISlider::GetValue ( ) const

Get the slider's value integer value.

Returns:
Current slider value

virtual bool CIwUISlider::HandleEventClick ( CIwUIEventClick * pEventClick ) [protected, virtual]

Handle a pointer click event.

Parameters:
pEventClick The click event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUISlider::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUISlider::HandleEventPointerMove ( CIwUIEventPointerMove * pEventPointerMove ) [protected, virtual]

Handle the movement of the pointer within our bounds (or a child element's bounds).

Parameters:
pEventPointerMove The pointer move event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUISlider::IntersectElement ( const CIwVec2 & pos ) const [protected, virtual]

Test whether the specified position intersects with this element.

Note:
Custom elements wishing which wish to be clicked on should override this function.
Return values:
true | If the specified position intersects with this element.
false | If it doesn't.

Reimplemented from CIwUIElement.

virtual CIwVec2 CIwUISlider::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUISlider::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

virtual void CIwUISlider::OnSizeChanged ( ) [protected, virtual]

Function which is called when an element's size is changed whilst the element is active.

Reimplemented from CIwUIElement.

virtual void CIwUISlider::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

Render this element (but not its children).

Note:
Custom elements wishing to provide their own rendering should override this function.

Reimplemented from CIwUIElement.

void CIwUISlider::SetProportion ( iwfixed prop )

Set slider value as a 1.12 fixed format value.

Parameters:
prop Slider value between 0 and IW_GEOM_ONE

void CIwUISlider::SetValue ( int16 val )

Set slider value as an integer.

Parameters:
val Slider value between 'sliderMin' and 'slideMax'

virtual bool CIwUISlider::WantsFocus ( ) const [inline, protected, virtual]

Query the element and return whether it supports/wants keyboard focus.

Returns:
By default, returns false. Overridden by derived elements.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUISlider.h


Airplay API Reference: CIwUISoftKeyboard

Airplay API Reference > Data Structures > CIwUISoftKeyboard >

CIwUISoftKeyboard Class Reference
[Text Input, Text Input]

Interface element to display touchable soft keyboard.

#include <IwUISoftKeyboard.h>

Inheritance diagram for CIwUISoftKeyboard:

[legend]

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual bool | HandleEvent (CIwEvent *pEvent)

Member Function Documentation

virtual void CIwUISoftKeyboard::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUISoftKeyboard::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

virtual bool CIwUISoftKeyboard::HandleEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-handler for all ui elements.

Parameters:
pEvent Event to be handled.
Returns:
Boolean value signifying whether the event was handled.
Return values:
true | If the event was handled and requires no further processing.
false | If the event wasn't handled and so requires further processing.
Note:
Derived classes are encouraged to override one or more of the more specific event handlers, eg. HandleEventClick, etc, rather than this function.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUISoftKeyboard.h


Airplay API Reference: CIwUISoftKeyPosition

Airplay API Reference > Data Structures > CIwUISoftKeyPosition >

CIwUISoftKeyPosition Class Reference
[Text Input, Text Input]

Container for a softkey element. Element is positioned next to hardware softkeys buttons on device. If device changes orientation, the contained elements will move into the correct corners to follow the softkeys. More...

#include <IwUISoftKeyPosition.h>

Inheritance diagram for CIwUISoftKeyPosition:

[legend]

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual void | OnPropertyChanged (const char *pName)
virtual void | Update (int32 deltaMS)

Detailed Description

CIwUISoftKeyPosition has the following properties:

Type | Name | Description
bool | isAdvanceKey | If true, position by 'Advance SoftKey', otherwise by 'Back SoftKey'.

Member Function Documentation

virtual void CIwUISoftKeyPosition::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUISoftKeyPosition::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

virtual void CIwUISoftKeyPosition::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

virtual void CIwUISoftKeyPosition::Update ( int32 deltaMS ) [protected, virtual]

Per-frame update.

Parameters:
deltaMS The number of milliseconds since the last update.
Note:
This is only called if the element and its ancestor's are active and updatable.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUISoftKeyPosition.h


Airplay API Reference: CIwUIStyle

Airplay API Reference > Data Structures > CIwUIStyle >

CIwUIStyle Class Reference
[Properties and Styles, Properties and Styles]

A named style, wrapped up in an object for added semantics.

#include <IwUIStyle.h>

Inheritance diagram for CIwUIStyle:

[legend]

Public Member Functions

void | Resolve ()
void | Serialise ()

Member Function Documentation

const char* CIwUIStyle::DebugGetName ( ) const

Debug: get name.

Reimplemented from CIwManaged.

void CIwUIStyle::Resolve ( ) [virtual]

Resolves references to other objects once serialisation is complete. The exact implementation will vary with the overiding class, but broadly it should fix up all member pointers, pointers in member lists or trees hanging off the object.

Note:
Substantially differing child implementations are documented separately.

derived classes are responsible for overiding this method

Required Header Files
IwManaged.h

Reimplemented from CIwManaged.

void CIwUIStyle::Serialise ( ) [virtual]

Reads/writes a binary file using IwSerialise interface.

See also:
IwSerialise
Note:
derived classes are responsible for overiding this method

Reimplemented from CIwManaged.

The documentation for this class was generated from the following file:
  • IwUIStyle.h


Airplay API Reference: CIwUIStyleManager

Airplay API Reference > Data Structures > CIwUIStyleManager >

CIwUIStyleManager Class Reference
[Properties and Styles, Properties and Styles]

Singleton which stores the currently-set stylesheet, and through which style property sets should be queried. If no stylesheet is set, styles are mapped to property sets by direct lookup of same-named property sets through the resource system.

#include <IwUIStyle.h>

Public Member Functions

const CIwPropertySet * | GetPropertySet (const CIwUIStyle &style) const
void | QueueStylesheet (CIwUIStylesheet *pStylesheet)
void | SetStylesheet (CIwUIStylesheet *pStylesheet)

Member Function Documentation

void CIwUIStyleManager::BuildHierarchy ( )

Builds property set hierarchy of the active style sheet and any global property set resources. Also reactivates the view. This is called when the styles sheet is changed.

const CIwPropertySet* CIwUIStyleManager::GetGlobalPropertySet ( const CIwUIStyle & style ) const

Get a pointer to the property set which corresponds to the specified style from the global resource manager.

const CIwPropertySet* CIwUIStyleManager::GetPropertySet ( const CIwUIStyle & style ) const

Get a pointer to the property set which corresponds to the specified style.

Note:
This will vary depending on which stylesheet, if any, is set.

const CIwUIStylesheet* CIwUIStyleManager::GetStylesheet ( ) const [inline]

Get the currently active style sheet, if any.

void CIwUIStyleManager::QueueStylesheet ( CIwUIStylesheet * pStylesheet )

Queue a change of style sheet until is called.

Parameters:
pStylesheet Pointer to style sheet to set as active, or NULL to cancel a previously queued request.

void CIwUIStyleManager::SetQueuedStylesheet ( )

Sets the style sheet to the queued stylesheet, if set. This is called at the beginning of CIwUIView::Update.

void CIwUIStyleManager::SetStylesheet ( CIwUIStylesheet * pStylesheet )

Set a new stylesheet, from which future queries will derive their style properties.

Parameters:
pStylsheet The stylesheet to set.
Note:
Ownership of the passed stylesheet remains with the caller.

The documentation for this class was generated from the following file:
  • IwUIStyle.h


Airplay API Reference: CIwUIStylesheet

Airplay API Reference > Data Structures > CIwUIStylesheet >

CIwUIStylesheet Class Reference
[Properties and Styles, Properties and Styles]

Maps styles to property sets, facilitating the switching of property sets globally.

#include <IwUIStyle.h>

Inheritance diagram for CIwUIStylesheet:

[legend]

Public Member Functions

Public interface
void | AddPropertySet (CIwUIPropertySet *pPropertySet)
void | SetParent (CIwUIStylesheet *pStyleSheet)

Member Function Documentation

void CIwUIStylesheet::AddPropertySet ( CIwUIPropertySet * pPropertySet )

Add a property set to the style sheet, passing ownership to the style sheet.

Note:
This facilitates code-driven property sets, although it is recommended that property set resources are preferred.

void CIwUIStylesheet::BuildPropertySetHierarchy ( )

Iterates over this style sheet, and its parents, and attaches each property sets parent using its associated style.

const CIwUIStylesheet* CIwUIStylesheet::GetParent ( ) const [inline]

Get the parent style sheet, if any, of this one.

const CIwPropertySet* CIwUIStylesheet::GetPropertySet ( const CIwUIStyle & style ) const

Get a pointer to the property set which corresponds to the specified style.

bool CIwUIStylesheet::IsCurrent ( ) const

Is this style sheet the current one, or a parent of the current style sheet in the style manager.

void CIwUIStylesheet::SetParent ( CIwUIStylesheet * pStyleSheet ) [inline]

Set the parent property set of this one.

Note:
If this style sheet is current, then CIwUIStyleManager::BuildPropertySetHierarchy() should be called after changing parentage.

The documentation for this class was generated from the following file:
  • IwUIStyle.h


Airplay API Reference: CIwUITabBar

Airplay API Reference > Data Structures > CIwUITabBar >

CIwUITabBar Class Reference
[Elements, Elements]

Container for a set of radio buttons. One button is always down, the others are always up.

#include <IwUITabBar.h>

Inheritance diagram for CIwUITabBar:

[legend]

Public Member Functions

int16 | GetNumRadioButtons () const
int16 | GetSelected () const
void | SetSelected (int16 selectedIndex)

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwUIElement * | FindWantsFocus ()
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | HandlesFocus () const
virtual CIwVec2 | MeasureElement (const CIwVec2 &availableSize) const
virtual void | OnPropertyChanged (const char *pName)

Member Function Documentation

virtual void CIwUITabBar::Activate ( bool val ) [protected, virtual]

Activate / deactivate this element. Activation occurs when an element is added to the view. Deactivation occurs when an element is removed from the view.

Parameters:
val If true then we are activating. Otherwise deactivating.
Note:
Derived classes shouldn't be calling this except directly within their overridden Activate implementation.

Reimplemented from CIwUIElement.

virtual void CIwUITabBar::Animate ( const CIwUIAnimData & animData ) [protected, virtual]

Update animated properties from the provided animation data.

Reimplemented from CIwUIElement.

virtual void CIwUITabBar::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUIElement.

virtual CIwUIElement* CIwUITabBar::FindWantsFocus ( ) [protected, virtual]

Chooses an appropriate focus element. This can either be the element itself or one of its children.

Returns:
Pointer to element which wants focus, or NULL if none found.

Reimplemented from CIwUIElement.

int16 CIwUITabBar::GetNumRadioButtons ( ) const

Get the number of radio buttons in the tab bar.

Returns:
Value passed to SetSelected should be less than this value.
Note:
Tab bar should be active before calling.

int16 CIwUITabBar::GetSelected ( ) const

Get the index of the currently selected radio button.

Returns:
Index of radio button, or -1 if no radio button is selected.

virtual bool CIwUITabBar::HandleEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-handler for all ui elements.

Parameters:
pEvent Event to be handled.
Returns:
Boolean value signifying whether the event was handled.
Return values:
true | If the event was handled and requires no further processing.
false | If the event wasn't handled and so requires further processing.
Note:
Derived classes are encouraged to override one or more of the more specific event handlers, eg. HandleEventClick, etc, rather than this function.

Reimplemented from CIwUIElement.

virtual bool CIwUITabBar::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUITabBar::HandlesFocus ( ) const [protected, virtual]

This element wants to choose its own focus element where possible.

Returns:
By default, returns true if either the element itself wants focus or it has an attached focus handler which is able to determine a child to have focus.

Reimplemented from CIwUIElement.

virtual CIwVec2 CIwUITabBar::MeasureElement ( const CIwVec2 & availableSize ) const [protected, virtual]

Measure space needed for the content of this element. That is, how much of the given space would we use.

Parameters:
availableSize The space available for use by this element.
Note:
Space required for children is handled by attached layout.

Reimplemented from CIwUIElement.

virtual void CIwUITabBar::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUIElement.

void CIwUITabBar::SetSelected ( int16 selectedIndex )

Set selected radio button by index.

Parameters:
Index of radio button to select
Note:
Tab bar should be active before calling.

The documentation for this class was generated from the following file:
  • IwUITabBar.h


Airplay API Reference: CIwUITable

Airplay API Reference > Data Structures > CIwUITable >

CIwUITable Class Reference
[Elements, Elements]

This is a specialisation of scrollable view which contains a number of row items, and which only allows vertical scrolling. More...

#include <IwUITable.h>

Inheritance diagram for CIwUITable:

[legend]

Public Member Functions

void AddRow (CIwUIElement *pElement, IwUIAlignmentH align)

Detailed Description

I am not yet entirely sure how best to implement this to enable its flexible use. Possibly the way to go is to provide an CIwUITableRow class which (maybe) provides a simple base implementation, but which users should override to display their own custom data.

Something to think about is how to decouple data sources from widgets. How do subwidgets within each row gets their data?

Note:
Setting a layout object on a table view is not a valid operation.

Member Function Documentation

void CIwUITable::AddRow | ( | CIwUIElement * | pElement,
 |  | IwUIAlignmentH | align
 | ) |  |

Add an element as the next row in the table. Ownership of the element transfers to the table.

Parameters:
pElement | Element to add.
align | Horizontal alignment of this element within the row.

void CIwUITable::ClearTable ( )

Destroy all rows in the table.

The documentation for this class was generated from the following file:
  • IwUITable.h


Airplay API Reference: CIwUITextField

Airplay API Reference > Data Structures > CIwUITextField >

CIwUITextField Class Reference
[Text Input, Text Input]

Editable text widget. When selected, this element activates modal text entry. More...

#include <IwUITextField.h>

Inheritance diagram for CIwUITextField:

[legend]

Protected Member Functions

virtual void | Activate (bool val)
virtual void | Clone (CIwUIElement *pTarget) const
virtual CIwVec2 | GetCursorPosition (int32 c)
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual bool | HandleEventClick (CIwUIEventClick *pEventClick)
virtual bool | HandleEventKey (CIwUIEventKey *pEventKey)
virtual bool | HandleEventPointerLeave (CIwUIEventPointerLeave *pEventPointerLeave)
virtual bool | IntersectElement (const CIwVec2 &pos) const
virtual void | OnPropertyChanged (const char *pName)
virtual bool | WantsFocus () const

Detailed Description

See also:
CIwUITextInput

Member Function Documentation

virtual void CIwUITextField::Activate ( bool val ) [protected, virtual]

We hook into the activate call so that we can create / destroy our ui text object appropriately.

Reimplemented from CIwUILabel.

virtual void CIwUITextField::Clone ( CIwUIElement * pTarget ) const [protected, virtual]

Clone this object. All member data should be copied to the target object.

Parameters:
pTarget Object that will become a clone of this object.
Note:
For a class to be cloneable it must override this function, even if there is no data to copy. The IW_UI_CLONE_SUPERCLASS macro must be included in the body of the function.

Derived classes shouldn't be calling this except directly within their overridden Clone implementation.

Reimplemented from CIwUILabel.

virtual CIwVec2 CIwUITextField::GetCursorPosition ( int32 c ) [protected, virtual]

Override this if you use a custom text drawable.

Returns:
Local cursor position for character at index c

virtual bool CIwUITextField::HandleEvent ( CIwEvent * pEvent ) [protected, virtual]

Base event-handler for all ui elements.

Parameters:
pEvent Event to be handled.
Returns:
Boolean value signifying whether the event was handled.
Return values:
true | If the event was handled and requires no further processing.
false | If the event wasn't handled and so requires further processing.
Note:
Derived classes are encouraged to override one or more of the more specific event handlers, eg. HandleEventClick, etc, rather than this function.

Reimplemented from CIwUIElement.

virtual bool CIwUITextField::HandleEventClick ( CIwUIEventClick * pEventClick ) [protected, virtual]

Handle a pointer click event.

Parameters:
pEventClick The click event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUITextField::HandleEventKey ( CIwUIEventKey * pEventKey ) [protected, virtual]

Handle key press events.

Parameters:
pEventKey The key event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUITextField::HandleEventPointerLeave ( CIwUIEventPointerLeave * pEventPointerLeave ) [protected, virtual]

Handle a pointer leave event, which is issued when the pointer moves into a position which doesn't intersect this element (either because it intersects another element before this, or just because it doesn't intersect with this), or in the case of a touchscreen when the screen is 'released'.

Parameters:
pEventPointerLeave The pointer leave event to handle.

Reimplemented from CIwUIElement.

virtual bool CIwUITextField::IntersectElement ( const CIwVec2 & pos ) const [protected, virtual]

Test whether the specified position intersects with this element.

Note:
Custom elements wishing which wish to be clicked on should override this function.
Return values:
true | If the specified position intersects with this element.
false | If it doesn't.

Reimplemented from CIwUIElement.

virtual void CIwUITextField::OnPropertyChanged ( const char * pName ) [protected, virtual]

Function which is called when an element property is changed whilst the element is active.

Parameters:
pName The name of the property which has changed. If NULL, all properties have potentially changed.

Reimplemented from CIwUILabel.

virtual void CIwUITextField::OnSizeChanged ( ) [protected, virtual]

Update size of drawables.

Reimplemented from CIwUILabel.

virtual void CIwUITextField::RenderElement ( CIwUIGraphics & graphics ) [protected, virtual]

We provide a custom render function.

Reimplemented from CIwUILabel.

virtual bool CIwUITextField::WantsFocus ( ) const [protected, virtual]

Query the element and return whether it supports/wants keyboard focus.

Returns:
By default, returns false. Overridden by derived elements.

Reimplemented from CIwUIElement.

The documentation for this class was generated from the following file:
  • IwUITextField.h


Airplay API Reference: CIwUITextInput

Airplay API Reference > Data Structures > CIwUITextInput >

CIwUITextInput Class Reference
[Text Input, Text Input]

Text Input Manager. Handles various forms of text input, including keyboard, on-screen soft keyboard, and numeric pad texting.

#include <IwUITextInput.h>

Inheritance diagram for CIwUITextInput:

[legend]

Public Types

enum EditorMode {
EDITOR_KEYBOARD,
EDITOR_NUMPAD,
EDITOR_INLINE_KEYBOARD,
EDITOR_INLINE_NUMPAD,
EDITOR_OS
}

Public Member Functions

void | CreateSoftKeyboard (const char *pElementName="soft_keyboard")
virtual void | DoTextEntry (CIwUIElement *pTextField=NULL, const char *pOriginalText=NULL)
int32 | GetCursorPosition () const
bool | IsBeingEdited (const CIwUIElement *pTextField)
void | SetCursorDelay (int32 delayMS)
void | SetCursorFlashPeriod (int32 periodMS)
virtual void | SetEditorMode (EditorMode mode)
bool | ShouldAllowFocus (const CIwUIElement *pTextField)
bool | ShouldDisplayCursor (const CIwUIElement *pTextField)
virtual void | Update (int32 deltaMS)

Protected Member Functions

virtual bool | FilterEvent (CIwEvent *pEvent)
virtual bool | HandleEvent (CIwEvent *pEvent)
virtual void | SetSoftKeyboardModal (CIwUISoftKeyboard *pSoftkeyboard)

Member Enumeration Documentation

enum CIwUITextInput::EditorMode

Text Editor modes.

See also:
SetEditorMode
Enumerator:
EDITOR_KEYBOARD | Use on-screen Keyboard to enter text
EDITOR_NUMPAD | Use on-screen Numpad to enter text
EDITOR_INLINE_KEYBOARD | Type directly into TextField using hardware keyboard
EDITOR_INLINE_NUMPAD | Type directly into TextField using hardware numpad
EDITOR_OS | Use native OS determined text entry system

Member Function Documentation

void CIwUITextInput::CreateSoftKeyboard ( const char * pElementName = "soft_keyboard" )

Creates a soft-keyboard for use by the text input system. The keyboard is added to the view, and initially set invisible.

Parameters:
pElementName Element resource to clone as base for keyboard.

virtual void CIwUITextInput::DoTextEntry | ( | CIwUIElement * | pTextField = NULL,
 |  | const char * | pOriginalText = NULL |
 | ) |  |  | [virtual]

Initiate Text Entry.

Parameters:
pTextField | Optional TextField to pass edit events to (or NULL).
pOriginalText | Optional TextField to pass edit events to (or NULL).

virtual bool CIwUITextInput::FilterEvent ( CIwEvent * pEvent ) [protected, virtual]

Called by CIwUIController and CIwUIElement to filter events.

Parameters:
pEvent Event to filter
Returns:
If the event was filtered and shouldn't be propagated.

Implements IIwUIEventHandler.

int32 CIwUITextInput::GetCursorPosition ( ) const [inline]

Return cursor position within edited text string.

Returns:
Cursor position in text string

virtual bool CIwUITextInput::HandleEvent ( CIwEvent * pEvent ) [inline, protected, virtual]

Called by CIwUIController and CIwUIElement to handle events.

Parameters:
pEvent Event to handle
Returns:
If the event was handled and shouldn't be propagated.

Implements IIwUIEventHandler.

bool CIwUITextInput::IsBeingEdited ( const CIwUIElement * pTextField )

Return true if element is being Edited.

Parameters:
pTextField Element to check for active text entry
See also:
DoTextEntry

void CIwUITextInput::SetCursorDelay ( int32 delayMS )

Set delay for numpad entry text cursor.

Parameters:
delayMS The number of milliseconds to wait before moving onto next character.
Note:
Allows last character to be modified during delay in texting mode.

void CIwUITextInput::SetCursorFlashPeriod ( int32 periodMS )

Set flash period for text cursor.

Parameters:
periodMS The number of milliseconds to wait between flashes

virtual void CIwUITextInput::SetEditorMode ( EditorMode mode ) [virtual]

Set editor mode for text entry.

Parameters:
mode The editor mode to set.
See also:
EditorMode

virtual void CIwUITextInput::SetSoftKeyboardModal ( CIwUISoftKeyboard * pSoftkeyboard ) [protected, virtual]

Override default modal showing behaviour.

Parameters:
override_fn Function to use for setting modal elements

bool CIwUITextInput::ShouldAllowFocus ( const CIwUIElement * pTextField )

Return true if element should allow itself to gain focus.

Parameters:
pTextField Element to check.
See also:
DoTextEntry

bool CIwUITextInput::ShouldDisplayCursor ( const CIwUIElement * pTextField )

Return true if element should display a flashing text entry cursor.

Parameters:
pTextField Element to check for active text entry
See also:
DoTextEntry

virtual void CIwUITextInput::Update ( int32 deltaMS ) [virtual]

Per-frame update.

Parameters:
deltaMS The number of milliseconds since the last update.

The documentation for this class was generated from the following file:
  • IwUITextInput.h


Airplay API Reference: CIwUIView

Airplay API Reference > Data Structures > CIwUIView >

CIwUIView Class Reference
[View, View]

IwUI singleton which handles high-level functionality relating to the visual representation of elements - rendering, intersection testing, focus and styles.

#include <IwUIView.h>

Queries

CIwUIElement * | GetChildHashed (uint32 hash, bool permitNull=false) const
CIwUIElement * | GetChildNamed (const char *pName, bool permitNull=false) const
void | GetCloneList (uint32 hash, CIwManagedList &list)

Public Member Functions

Delegates
void | AddDelegate (uint32 className, uint32 objectName, IDelegateQuery *pDelegate)
void | DestroyDelegates (void *pHandler)
IDelegateQuery * | LookupSlot (CIwUIElement *pContext, bool classNotObjectName, uint32 ownerName, uint32 slotName)
void | RemoveDelegate (IDelegateQuery *pDelegate)
Public interface
void | AddElementToLayout (CIwUIElement *pElement, IwUIAlignmentH alignH=IW_UI_ALIGN_CENTRE, IwUIAlignmentV alignV=IW_UI_ALIGN_MIDDLE)
void | SetModal (CIwUIElement *pElement, bool setFocus=true)
Focus
bool | ChooseFocus (CIwUIElement *pElement)
bool | InFocusChain (CIwUIElement *pElement) const
bool | IsFocusable (const CIwUIElement *pElement) const
bool | MoveFocus (CIwUIElement *pElement, IwUIFocusMovement movement)
void | RequestFocus (CIwUIElement *pElement)
Declared virtuals
virtual void | Layout ()
virtual void | Reactivate ()
virtual void | Render ()
virtual void | Update (int32 deltaMS)

Data Structures

struct | DelegateReference
Delegate registry.

Member Function Documentation

void CIwUIView::AddDelegate | ( | uint32 | className,
 |  | uint32 | objectName,
 |  | IDelegateQuery * | pDelegate
 | ) |  |

Use to register an application slot.

Parameters:
ownerName | Hashed name to use when resolving a slot.
pDelegate | Pointer to delegate.
Note:
The view automatically destroys all delegates it still contains when it is destroyed.
See also:
IW_UI_CREATE_VIEW_SLOT

void CIwUIView::AddElement ( CIwUIElement * pElement )

Add the specified element to the interface (passing ownership to the ui view).

void CIwUIView::AddElementToLayout | ( | CIwUIElement * | pElement,
 |  | IwUIAlignmentH | alignH = IW_UI_ALIGN_CENTRE,
 |  | IwUIAlignmentV | alignV = IW_UI_ALIGN_MIDDLE
 | ) |  |

Add an element already in the interface to the root layout.

Note:
The root layout is sized to the screen and hence allows screen size changes to be reflected in the element's layout.

bool CIwUIView::ChooseFocus ( CIwUIElement * pElement )

Attempts to move focus to or within the given element.

Parameters:
pElement Element to choose sub-focus for. If NULL, the root element is used.
Returns:
Either pElement itself, or a child, or NULL if no focusable element can be found.

virtual void CIwUIView::DebugRender ( ) [virtual]

Debug rendering.

void CIwUIView::DestroyDelegates ( void * pHandler )

Use to unregister and destroy all application slots previously registered by AddDelegate for a given handler.

Parameters:
handler The delegates handler.
See also:
IW_UI_DESTROY_VIEW_SLOTS

void CIwUIView::DestroyElements ( )

Remove and destroy all elements from the interface.

CIwUIElement* CIwUIView::GetChildHashed | ( | uint32 | hash,
 |  | bool | permitNull = false |
 | ) |  |  | const

Get child element with the specified name hash.

Parameters:
hash | Name hash of child to search for.
permitNull | If false, an assert will fire if the element isn't found.
Note:
The entire hierarchy of active elements is searched.

If multiple elements with the same hash exist in the hierarchy, this function will return the first found with a depth-first traversal.

CIwUIElement* CIwUIView::GetChildNamed | ( | const char * | pName,
 |  | bool | permitNull = false |
 | ) |  |  | const

Get named child element.

Parameters:
pName | Named child to search for.
permitNull | If false, an assert will fire if the element isn't found.
Note:
The entire hierarchy of active elements is searched.

If multiple elements with the same name exist in the hierarchy, this function will return the first found with a depth-first traversal.

void CIwUIView::GetCloneList | ( | uint32 | hash,
 |  | CIwManagedList & | list
 | ) |  |

Find all children and descendants that were cloned from an item whose name matches this hash.

Parameters:
hash | Name hash of the children to search for.
list | List to put the matching children in.

CIwUIElement* CIwUIView::GetElement ( int index ) const

Get a ptr to the top-level element at the specified index.

CIwUIElement* CIwUIView::GetFocus ( ) const

Query current keyboard focus.

int CIwUIView::GetNumElements ( ) const

Query the number of top-level elements under the root.

bool CIwUIView::InFocusChain ( CIwUIElement * pElement ) const

Parameters:
pElement Element to determine if part of the focus chain.
Returns:
If the given element is the focus element, or a parent of it.

void CIwUIView::Intersect | ( | CIwManagedList & | contained,
 |  | const CIwUIRect & | rect |
 | ) |  |  | const

Find all elements within the given rectangle.

virtual CIwUIElement* CIwUIView::Intersect ( const CIwVec2 & pos ) const [virtual]

Query (lowest-level) element at the specified screen position.

bool CIwUIView::IsFocusable ( const CIwUIElement * pElement ) const

Return if this element is currently focusable (respecting parents).

Parameters:
pElement element to check.
Note:
Check if this element has an unbroken visible chain to the root/modal element

virtual void CIwUIView::Layout ( ) [virtual]

Recalculates layout from top-level element.

Note:
This is called, by default, at the end of if the layout is invalid.

IDelegateQuery* CIwUIView::LookupSlot | ( | CIwUIElement * | pContext,
 |  | bool | classNotObjectName,
 |  | uint32 | ownerName,
 |  | uint32 | slotName
 | ) |  |

Searches upwards through the element hierarchy to find a slot attached to a given object, and with the given name. If no element slot is found, then application slots are searched.

Parameters:
pContext | Element to start looking for slot at.
classNotObjectName | Is the of a class or an object.
ownerName | Hashed name of class or object which owns the slot.
slotName | Hashed name of slot within object.
Returns:
Pointer to delegate if found, otherwise NULL.

bool CIwUIView::MoveFocus | ( | CIwUIElement * | pElement,
 |  | IwUIFocusMovement | movement
 | ) |  |

Attempts to move focus in the given direction, relative to the given element which is a parent of the current focus element.

Parameters:
pElement | Current focus element or a parent of it.
movement | Direction to move focus in.
Returns:
If focus was successfully moved.

virtual void CIwUIView::Reactivate ( ) [virtual]

Reactivate the root element.

Note:
Call Reactivate, then CIwUIView::Update, then CIwUIView::Render to ensure correct layout.

void CIwUIView::RemoveDelegate ( IDelegateQuery * pDelegate )

Use to unregister an application slot.

Parameters:
Pointer to delegate previously added.

void CIwUIView::RemoveElement ( CIwUIElement * pElement )

Remove the specified element from the interface (ui view loses ownership).

virtual void CIwUIView::Render ( ) [virtual]

Render the ui view.

Parameters:
The default implementation creates a default CIwUIGraphics object to render to the whole screen, and then renders each top-level element in turn.

void CIwUIView::RequestFocus ( CIwUIElement * pElement )

Request that the keyboard focus be switched to the specified element.

Parameters:
pElement Element to gain focus. If NULL, clears focus chain.

void CIwUIView::SetModal | ( | CIwUIElement * | pElement,
 |  | bool | setFocus = true
 | ) |  |

Set modal element. Only this element and its descendants will be intersected with.

Parameters:
pElement | Top-level element which is to gain modal focus.
setFocus | Should we set focus to/away from the modal element.
Note:
Pass NULL to clear modality.

virtual void CIwUIView::Update ( int32 deltaMS ) [virtual]

Update the ui view.

Parameters:
deltaMS The number of milliseconds since the last update.

The documentation for this class was generated from the following file:
  • IwUIView.h


Airplay API Reference: CIwUncopyable

Airplay API Reference > Data Structures > CIwUncopyable >

CIwUncopyable Class Reference

#include <IwUncopyable.h>

Inheritance diagram for CIwUncopyable:

[legend]

Detailed Description

Classes may privately inherit from this class if they are not safe to be copied.
Required Header Files
IwUncopyable.h
The documentation for this class was generated from the following file:
  • IwUncopyable.h


Airplay API Reference: CIwURI

Airplay API Reference > Data Structures > CIwURI >

CIwURI Class Reference
[URI Object]

#include <IwURI.h>

Public Types

enum | PROTOCOL

Public Member Functions

CIwURI (const char *URI)
CIwURI (const CIwURI &that)
const char * | GetAll () const
const char * | GetHost () const
uint16 | GetPort () const
CIwURI::PROTOCOL | GetProtocol () const
const char * | GetTail ()
CIwURI & | operator= (const CIwURI &that)
CIwURI & | operator= (const char *URI)

Detailed Description

URI Class

Member Enumeration Documentation

enum CIwURI::PROTOCOL

The protocol (or rather the scheme, to use the official naming). Note that currently the CIwHTTP class only supports HTTP.

Enumerator:
HTTP | The Hypertext transfer protocol.
HTTPS | HTTP running over SSL or TLS.
FTP | The File Transfer Protocol.
FILE | A local file.
UNKNOWN | An unknown scheme.

Constructor & Destructor Documentation

CIwURI::CIwURI ( )

Constructs the object but doesn't assign a value to it.

CIwURI::CIwURI ( const CIwURI & that )

Copy constructor

Parameters:
that The URI to copy

CIwURI::CIwURI ( const char * URI )

Construct from a string

Parameters:
URI The string

virtual CIwURI::~CIwURI ( ) [virtual]

Destructor.

Member Function Documentation

const char* CIwURI::GetAll ( ) const

Returns the entire URI. The returned string is owned by the CIwURI class and is only valid for the lifetime of the CIwURI or until any other accessor is called.

Returns:
The URI

const char* CIwURI::GetHost ( ) const [inline]

Returns the host, if present or NULL otherwise. The returned string is owned by the CIwURI object and only remains valid for the lifetime of the CIwURI or until the next call to any other accesor

Returns:
The host

uint16 CIwURI::GetPort ( ) const [inline]

Returns the port, if present or 0 otherwise.

Returns:
the port, if present or 0 otherwise.

CIwURI::PROTOCOL CIwURI::GetProtocol ( ) const [inline]

Returns the protocol, or UNKNOWN if it is missing or unknown. The protocol is also known as the scheme.

Returns:
The protocol.

const char* CIwURI::GetTail ( ) [inline]

Returns everything after the host and the port. In URI terms this is the path, the query and the fragment, not the query.

Returns:
The tail

CIwURI& CIwURI::operator= ( const CIwURI & that )

Assignment operator

Parameters:
that The string to assign to the URI
Returns:
this

CIwURI& CIwURI::operator= ( const char * URI )

Assignment operator

Parameters:
URI The string to assign to the URI
Returns:
this

The documentation for this class was generated from the following file:
  • IwURI.h


Airplay API Reference: CIwUriEscape

Airplay API Reference > Data Structures > CIwUriEscape >

CIwUriEscape Class Reference
[IwHTTP API Reference]

A class for URI-escaping functions.

#include <IwUriEscape.h>

Static Public Member Functions

static std::string Escape (std::string in)

Member Function Documentation

static std::string CIwUriEscape::Escape ( std::string in ) [static]

URI-escapes a string, for use in the middle of a query. in other words, the text is turned into something20like20this.

Parameters:
in The string to escape
Returns:
The escaped string

The documentation for this class was generated from the following file:
  • IwUriEscape.h


Airplay API Reference: CIwVec2

Airplay API Reference > Data Structures > CIwVec2 >

CIwVec2 Class Reference
[IwGeomVec2]

#include <IwGeomVec2.h>

Public Member Functions

CIwVec2 (int32 _x, int32 _y)
CIwVec2 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER int32 | Dot (CIwVec2 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwVec2 | GetNormalised () const
CIwVec2 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwVec2 | operator * (iwfixed l) const
CIwVec2 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwVec2 | operator- () const
VALUE_IN_REGS CIwVec2 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec2 | operator<< (const int s) const
VALUE_IN_REGS CIwVec2 | operator<<= (const int s)
VALUE_IN_REGS CIwVec2 | operator>> (const int s) const
VALUE_IN_REGS CIwVec2 | operator>>= (const int s)
VALUE_IN_REGS int32 | operator[] (const int n) const
VALUE_IN_REGS int32 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwVec2 const &v) const
bool | operator!= (CIwVec2 const &v) const
VALUE_IN_REGS CIwVec2 | operator+ (CIwVec2 const &v) const
CIwVec2 & | operator+= (CIwVec2 const &v)
VALUE_IN_REGS CIwVec2 | operator- (CIwVec2 const &v) const
CIwVec2 & | operator-= (CIwVec2 const &v)
CIwVec2 & | operator= (CIwVec2 const &v)
bool | operator== (CIwVec2 const &v) const
VALUE_IN_REGS CIwVec2 | operator^ (CIwVec2 const &v) const

Static Public Attributes

static CIwVec2 | g_AxisX
static CIwVec2 | g_AxisY
static CIwVec2 | g_Zero

Detailed Description

CIwVec2

Constructor & Destructor Documentation

CIwVec2::CIwVec2 ( ) [inline]

Constructor: creates a new vector.

CIwVec2::CIwVec2 | ( | int32 | _x,
 |  | int32 | _y |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component

Member Function Documentation

INLINE_MEMBER int32 CIwVec2::Dot ( CIwVec2 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwVec2::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec2::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec2::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec2::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec2::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwVec2 CIwVec2::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwVec2 CIwVec2::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwVec2::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwVec2::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwVec2::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwVec2::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwVec2::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwVec2::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwVec2 CIwVec2::g_AxisX [static]

World X-axis.

CIwVec2 CIwVec2::g_AxisY [static]

World Y-axis.

CIwVec2 CIwVec2::g_Zero [static]

Zero vector.

int32 CIwVec2::x

x-coordinate of the vector

int32 CIwVec2::y

y-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomVec2.h


Airplay API Reference: CIwVec3

Airplay API Reference > Data Structures > CIwVec3 >

CIwVec3 Class Reference
[IwGeomVec3]

#include <IwGeomVec3.h>

Public Member Functions

CIwVec3 (int32 _x, int32 _y, int32 _z)
CIwVec3 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

VALUE_IN_REGS INLINE_MEMBER CIwVec3 | Cross (CIwVec3 const &v) const
INLINE_MEMBER int32 | Dot (CIwVec3 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwVec3 | GetNormalised () const
CIwVec3 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwVec3 | operator * (iwfixed l) const
CIwVec3 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwVec3 | operator- () const
VALUE_IN_REGS CIwVec3 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec3 | operator<< (const int s) const
VALUE_IN_REGS CIwVec3 | operator<<= (const int s)
VALUE_IN_REGS CIwVec3 | operator>> (const int s) const
VALUE_IN_REGS CIwVec3 | operator>>= (const int s)
VALUE_IN_REGS int32 | operator[] (const int n) const
VALUE_IN_REGS int32 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwVec3 const &v) const
bool | operator!= (CIwVec3 const &v) const
VALUE_IN_REGS CIwVec3 | operator+ (CIwVec3 const &v) const
CIwVec3 & | operator+= (CIwVec3 const &v)
VALUE_IN_REGS CIwVec3 | operator- (CIwVec3 const &v) const
CIwVec3 & | operator-= (CIwVec3 const &v)
CIwVec3 & | operator= (CIwVec3 const &v)
bool | operator== (CIwVec3 const &v) const
VALUE_IN_REGS CIwVec3 | operator^ (CIwVec3 const &v) const

Static Public Attributes

static CIwVec3 | g_AxisX
static CIwVec3 | g_AxisY
static CIwVec3 | g_AxisZ
static CIwVec3 | g_Zero

Detailed Description

CIwVec3

Constructor & Destructor Documentation

CIwVec3::CIwVec3 ( ) [inline]

Constructor: creates a new vector.

CIwVec3::CIwVec3 | ( | int32 | _x,
 |  | int32 | _y,
 |  | int32 | _z |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component

Member Function Documentation

VALUE_IN_REGS INLINE_MEMBER CIwVec3 CIwVec3::Cross ( CIwVec3 const & v ) const [inline]

Cross product.

Parameters:
Vector for cross product operation.
Returns:
Resulting vector.

INLINE_MEMBER int32 CIwVec3::Dot ( CIwVec3 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwVec3::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec3::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec3::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec3::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec3::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwVec3 CIwVec3::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwVec3 CIwVec3::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwVec3::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwVec3::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwVec3::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwVec3::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwVec3::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwVec3::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwVec3 CIwVec3::g_AxisX [static]

World X-axis.

CIwVec3 CIwVec3::g_AxisY [static]

World Y-axis.

CIwVec3 CIwVec3::g_AxisZ [static]

World Z-axis.

CIwVec3 CIwVec3::g_Zero [static]

Zero vector.

int32 CIwVec3::x

x-coordinate of the vector

int32 CIwVec3::y

y-coordinate of the vector

int32 CIwVec3::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomVec3.h


Airplay API Reference: CIwVec4

Airplay API Reference > Data Structures > CIwVec4 >

CIwVec4 Class Reference
[IwGeomVec4]

#include <IwGeomVec4.h>

Public Member Functions

CIwVec4 (int32 _x, int32 _y, int32 _z, int32 _w)
CIwVec4 ()
Miscellaneous
The following are helper functions that implement the most commonly used operations.

INLINE_MEMBER int32 | Dot (CIwVec4 const &v) const
bool | IsZero () const
void | Serialise (void)
Length
The following functions calculate the length of a vector. Variations include optimisations for speed, security and fixed points.

int32 | GetLength () const
int32 | GetLengthSafe () const
int32 | GetLengthSquared () const
int32 | GetLengthSquaredSafe () const
int32 | GetLengthSquaredUnshifted () const
Normalise
The following functions normalise vectors, thus producing an output vector that retains its orientation with a length equal to 1.

CIwVec4 | GetNormalised () const
CIwVec4 | GetNormalisedSafe () const
bool | IsNormalised () const
void | Normalise ()
void | NormaliseSafe ()
void | NormaliseSlow ()
Operator overloads
Using scalar values.

VALUE_IN_REGS CIwVec4 | operator * (iwfixed l) const
CIwVec4 & | operator *= (iwfixed l)
VALUE_IN_REGS CIwVec4 | operator- () const
VALUE_IN_REGS CIwVec4 | operator/ (const iwfixed s) const
VALUE_IN_REGS CIwVec4 | operator<< (const int s) const
VALUE_IN_REGS CIwVec4 | operator<<= (const int s)
VALUE_IN_REGS CIwVec4 | operator>> (const int s) const
VALUE_IN_REGS CIwVec4 | operator>>= (const int s)
VALUE_IN_REGS int32 | operator[] (const int n) const
VALUE_IN_REGS int32 & | operator[] (const int n)
Operator overloads.
Using vectors as operators.

int32 | operator * (CIwVec4 const &v) const
bool | operator!= (CIwVec4 const &v) const
VALUE_IN_REGS CIwVec4 | operator+ (CIwVec4 const &v) const
CIwVec4 & | operator+= (CIwVec4 const &v)
VALUE_IN_REGS CIwVec4 | operator- (CIwVec4 const &v) const
CIwVec4 & | operator-= (CIwVec4 const &v)
CIwVec4 & | operator= (CIwVec4 const &v)
bool | operator== (CIwVec4 const &v) const
VALUE_IN_REGS CIwVec4 | operator^ (CIwVec4 const &v) const

Static Public Attributes

static CIwVec4 | g_AxisW
static CIwVec4 | g_AxisX
static CIwVec4 | g_AxisY
static CIwVec4 | g_AxisZ
static CIwVec4 | g_Zero

Detailed Description

CIwVec4

Constructor & Destructor Documentation

CIwVec4::CIwVec4 ( ) [inline]

Constructor: creates a new vector.

CIwVec4::CIwVec4 | ( | int32 | _x,
 |  | int32 | _y,
 |  | int32 | _z,
 |  | int32 | _w |
 | ) |  |  | [inline]

Constructor: creates a new vector.

Parameters:
_x | X-component
_y | Y-component
_z | Z-component
_w | W-component

Member Function Documentation

INLINE_MEMBER int32 CIwVec4::Dot ( CIwVec4 const & v ) const [inline]

Dot product.

Parameters:
Vector for dot product operation.
Returns:
Resulting scalar value.

int32 CIwVec4::GetLength ( ) const

Supplies the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec4::GetLengthSafe ( ) const

Supplies the length of the vector with extra checking done in order to prevent overflows.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec4::GetLengthSquared ( ) const

Calculates the length of the vector.

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec4::GetLengthSquaredSafe ( ) const

Calculates the length of the vector (multiplied in 64 Bit in order to prevent overflows).

Returns:
The length of the vector shifted (to fixed point representation).

int32 CIwVec4::GetLengthSquaredUnshifted ( ) const

Calculates the length of the vector.

Returns:
The length of the vector unshifted.

CIwVec4 CIwVec4::GetNormalised ( ) const

Supplies a normalised vector - using Normalise().

Returns:
A normalised version of the vector.

CIwVec4 CIwVec4::GetNormalisedSafe ( ) const

Supplies a normalised vector (using NormaliseSafe).

Returns:
A normalised version of the vector.

bool CIwVec4::IsNormalised ( ) const

Checks if a vector is normalised. The margin allowed is less than 0.36% (chosen based on the accuracy of the Normalise() function), so the error should be < 0.18%.

Returns:
true if normalised, false otherwise.

bool CIwVec4::IsZero ( ) const

Checks if all vector components are zero.

Returns:
true if zero, otherwise false.

void CIwVec4::Normalise ( )

Calculates 1 / sqrt(x) using a lookup table. This makes it approximately five times faster than the Normalise() function. The resulting vector's length will be normalised within a margin of about +/- 12 / 2^12, whereas the result of the Normalise() function will have an inaccuracy of about +/- 4 / 2^12.

void CIwVec4::NormaliseSafe ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- 4 / 2^12.

Remarks:
An additional checking mechanism is implemented in order to prevent overflows.

void CIwVec4::NormaliseSlow ( )

Normalises a given vector to a vector having the same direction, but with a length equal to 1 +/- approximately 4/2^12.

void CIwVec4::Serialise ( void )

Functionality for writing/reading to a storage device.

Field Documentation

CIwVec4 CIwVec4::g_AxisW [static]

World W-axis.

CIwVec4 CIwVec4::g_AxisX [static]

World X-axis.

CIwVec4 CIwVec4::g_AxisY [static]

World Y-axis.

CIwVec4 CIwVec4::g_AxisZ [static]

World Z-axis.

CIwVec4 CIwVec4::g_Zero [static]

Zero vector.

int32 CIwVec4::w

w-coordinate of the vector

int32 CIwVec4::x

x-coordinate of the vector

int32 CIwVec4::y

y-coordinate of the vector

int32 CIwVec4::z

z-coordinate of the vector

The documentation for this class was generated from the following file:
  • IwGeomVec4.h


Airplay API Reference: IIwDecomposable

Airplay API Reference > Data Structures > IIwDecomposable >

IIwDecomposable Interface Reference
[Text Decomposer, Text Decomposer]

Interface to allow an object to participate in text decomposition. The interface allows for writing out only the need parts of an objects definition.

#include <IwDecomposable.h>

Inheritance diagram for IIwDecomposable:

[legend]

Member Function Documentation

static void IIwDecomposable::AddHashString | ( | uint32 | hash,
 |  | const char * | pString |
 | ) |  |  | [static]

Store a hash-string lookup entry in the current .

virtual void IIwDecomposable::DecomposeAttributes ( CIwTextDecomposer * pDecomposer ) const [pure virtual]

Implementations of this function should write out member data but not child objects.

Implemented in CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUIElementEventHandler, CIwUIFocusHandler, CIwUILayoutGrid, CIwUILayoutItem, CIwUIPropertySet, CIwPropertySet, and CIwPropertySetBinding.

virtual void IIwDecomposable::DecomposeChildren ( CIwTextDecomposer * pDecomposer ) const [pure virtual]

Implementations of this function should write out the full definition of child objects.

Implemented in CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUIElementEventHandler, CIwUIFocusHandler, CIwUILayout, CIwUILayoutGrid, CIwUILayoutItem, CIwUILayoutItemContainer, CIwPropertySet, and CIwPropertySetBinding.

virtual void IIwDecomposable::DecomposeClose ( CIwTextDecomposer * pDecomposer ) const [pure virtual]

If the object opened a new scope in then it should be closed here.

Implemented in CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUIElementEventHandler, CIwUIFocusHandler, CIwUILayoutItem, CIwUILayoutItemContainer, CIwPropertySet, and CIwPropertySetBinding.

virtual void IIwDecomposable::DecomposeOpen ( CIwTextDecomposer * pDecomposer ) const [pure virtual]

If the object wishes to be decomposed, the implementation of this function should write out the class name, open a new scope (possibly inline) and write the name of the object.

Implemented in CIwUIAnimKeyFrame, CIwUIAnimation, CIwUIElement, CIwUIElementEventHandler, CIwUIFocusHandler, CIwUILayoutItem, CIwUILayoutItemContainer, CIwPropertySet, and CIwPropertySetBinding.

static const char* IIwDecomposable::GetHashString ( uint32 hash ) [static]

Look up the string for a hash which has previously been registered in a 's hash-string table.

The documentation for this interface was generated from the following file:
  • IwDecomposable.h


Airplay API Reference: IIwFocusResolver

Airplay API Reference > Data Structures > IIwFocusResolver >

IIwFocusResolver Class Reference
[Focus Handlers, Focus Handlers]

Helper interface to determine an element which to give focus to.

#include <IwUIFocusHandler.h>

Member Function Documentation

virtual void IIwFocusResolver::ProcessElement ( CIwUIElement * pElement ) [pure virtual]

Called by Resolve() for each element which returns true to CIwUIElement::HandlesFocus().

void IIwFocusResolver::Resolve ( CIwUIElement * pRoot )

Recurses from the provided root element, down the hierarchy, searching for potential elements to gain focus.

The documentation for this class was generated from the following file:
  • IwUIFocusHandler.h


Airplay API Reference: IIwPropertySetObserver

Airplay API Reference > Data Structures > IIwPropertySetObserver >

IIwPropertySetObserver Class Reference
[Property Set, Property Set]

Interface to allow an observer to be informed of property changes. It is used with property set bindings (implementations of CIwPropertySetBinding) to allow a consumer of a property set to be informed when external changes cause property values to change.

#include <IwPropertySetBinding.h>

Inheritance diagram for IIwPropertySetObserver:

[legend]

Public Member Functions

virtual void NotifyPropertyChanged (const char *pName)=0

Member Function Documentation

virtual void IIwPropertySetObserver::NotifyPropertyChanged ( const char * pName ) [pure virtual]

Interface to allow an observer to be informed of changed which have caused a property value has changed.

Parameters:
pName String name of property which has changed.

The documentation for this class was generated from the following file:
  • IwPropertySetBinding.h


Airplay API Reference: IIwUIAnimatorObserver

Airplay API Reference > Data Structures > IIwUIAnimatorObserver >

IIwUIAnimatorObserver Class Reference
[Animation, Animation]

Interface to allow an observation of the state changes of a playing animation.

#include <IwUIAnimManager.h>

Inheritance diagram for IIwUIAnimatorObserver:

[legend]

Public Member Functions

Declared virtuals
virtual void | NotifyProgress (CIwUIAnimator *pAnimator)=0
virtual void | NotifyStopped (CIwUIAnimator *pAnimator)=0

Member Function Documentation

virtual void IIwUIAnimatorObserver::NotifyProgress ( CIwUIAnimator * pAnimator ) [pure virtual]

Parameters:
pAnimator Ptr to animator which has just been updated.

virtual void IIwUIAnimatorObserver::NotifyStopped ( CIwUIAnimator * pAnimator ) [pure virtual]

Parameters:
pAnimator Ptr to animator which has just been stopped.

The documentation for this class was generated from the following file:
  • IwUIAnimManager.h


Airplay API Reference: IIwUIDrawable

Airplay API Reference > Data Structures > IIwUIDrawable >

IIwUIDrawable Class Reference
[Drawables, Drawables]

Interface for drawable objects such as text, images, borders.

#include <IwUIDrawable.h>

Inheritance diagram for IIwUIDrawable:

[legend]

Public Member Functions

virtual void | Animate (const CIwUIAnimData &animData)=0
virtual void | Draw (CIwUIGraphics &graphics) const =0
virtual CIwUIRect | GetBounds () const =0
virtual CIwColour | GetColour () const =0
virtual CIwVec2 | GetPosition () const =0
virtual CIwVec2 | GetSize () const =0
virtual bool | Intersects (const CIwVec2 &pos) const =0
virtual CIwVec2 | Measure (const CIwVec2 &availableSize) const =0
virtual void | SetColour (const CIwColour &colour)=0
virtual void | SetPosition (const CIwVec2 &pos)=0
virtual void | SetSize (const CIwVec2 &size)=0

Member Function Documentation

virtual void IIwUIDrawable::Animate ( const CIwUIAnimData & animData ) [pure virtual]

Update animated properties from the provided animation data.

Parameters:
animData Animation data to read interpolated properties from.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual void IIwUIDrawable::Draw ( CIwUIGraphics & graphics ) const [pure virtual]

Draw this object to the specified graphics context.

Parameters:
graphics Graphics context to draw to

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual CIwUIRect IIwUIDrawable::GetBounds ( ) const [pure virtual]

Query the bounding rectangle covered by the drawable.

Returns:
Rectangle covered by drawable. This maybe be smaller than the area provided to the drawable its set size and position. For example, text may not require all the size available to it.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual CIwColour IIwUIDrawable::GetColour ( ) const [pure virtual]

Query the colour of this object.

Returns:
Colour drawable uses to draw with.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual CIwVec2 IIwUIDrawable::GetPosition ( ) const [pure virtual]

Query the position of this object.

Returns:
Position drawable has been set to draw to.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual CIwVec2 IIwUIDrawable::GetSize ( ) const [pure virtual]

Query the size of this object.

Returns:
Size drawable has been given to occupy.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual bool IIwUIDrawable::Intersects ( const CIwVec2 & pos ) const [pure virtual]

Test intersection of this object with specified position.

Parameters:
pos Position vector relative to the frame used to set the drawable's size and position.
Returns:
True if the given position lies within the drawable's bounds.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual CIwVec2 IIwUIDrawable::Measure ( const CIwVec2 & availableSize ) const [pure virtual]

Query how much space drawable would use given a size to layout within.

Parameters:
availableSize Available layout space.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual void IIwUIDrawable::SetColour ( const CIwColour & colour ) [pure virtual]

Set the colour of this object.

Parameters:
Colour to draw with.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual void IIwUIDrawable::SetPosition ( const CIwVec2 & pos ) [pure virtual]

Set the position of this object on the graphics context.

Parameters:
Position drawable should draw to.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

virtual void IIwUIDrawable::SetSize ( const CIwVec2 & size ) [pure virtual]

Set the size of this object on the graphics context.

Parameters:
Size available to the drawable to occupy.

Implemented in CIwUIDrawableBorder, CIwUIDrawableImage, and CIwUIDrawableText.

The documentation for this class was generated from the following file:
  • IwUIDrawable.h


Airplay API Reference: IIwUIEventHandler

Airplay API Reference > Data Structures > IIwUIEventHandler >

IIwUIEventHandler Class Reference
[Events, Events]

Interface to handle or filter events.

#include <IwUIEventHandler.h>

Inheritance diagram for IIwUIEventHandler:

[legend]

Public Member Functions

Declared virtuals
virtual bool | FilterEvent (CIwEvent *pEvent)=0
virtual bool | HandleEvent (CIwEvent *pEvent)=0

Member Function Documentation

virtual bool IIwUIEventHandler::FilterEvent ( CIwEvent * pEvent ) [pure virtual]

Called by CIwUIController and CIwUIElement to filter events.

Parameters:
pEvent Event to filter
Returns:
If the event was filtered and shouldn't be propagated.

Implemented in CIwUIElement, CIwUIElementEventHandler, CIwUISlider, and CIwUITextInput.

virtual bool IIwUIEventHandler::HandleEvent ( CIwEvent * pEvent ) [pure virtual]

Called by CIwUIController and CIwUIElement to handle events.

Parameters:
pEvent Event to handle
Returns:
If the event was handled and shouldn't be propagated.

Implemented in CIwUIElement, CIwUIElementEventHandler, CIwUIRadioButton, CIwUISoftKeyboard, CIwUITabBar, CIwUITextField, and CIwUITextInput.

The documentation for this class was generated from the following file:
  • IwUIEventHandler.h


Airplay API Reference: s3eAudioCallbackData

Airplay API Reference > Data Structures > s3eAudioCallbackData >

s3eAudioCallbackData Struct Reference
[Audio API Reference]

#include <s3eAudio.h>

Detailed Description

Audio callback data.
Required Header Files:
s3eAudio.h

Field Documentation

uint32 s3eAudioCallbackData::m_ChannelID

ID of audio channel this callback pertains to.

The documentation for this struct was generated from the following file:
  • s3eAudio.h


Airplay API Reference: s3eDecompressionInput

Airplay API Reference > Data Structures > s3eDecompressionInput >

s3eDecompressionInput Struct Reference
[Compression API Reference]

#include <s3eCompression.h>

Detailed Description

Structure used by callback for s3eCompressionDecompInit() and s3eCompressionDecompRead()
Required Header Files
s3eCompression.h

Field Documentation

void* s3eDecompressionInput::m_Data

Input data buffer. The user should copy up to m_Size bytes of input data here.

int32 s3eDecompressionInput::m_Size

Size of input data buffer.

The documentation for this struct was generated from the following file:
  • s3eCompression.h


Airplay API Reference: s3eDeviceStateChangeInfo

Airplay API Reference > Data Structures > s3eDeviceStateChangeInfo >

s3eDeviceStateChangeInfo Struct Reference
[Device Interface API Reference]

#include <s3eDevice.h>

Data Fields

int32 m_State

Detailed Description

This structure is passed as the systemData paramater to the S3E_DEVICE_MAINS_POWER callback.

Field Documentation

int32 s3eDeviceStateChangeInfo::m_State

New state referred to by callback.

The documentation for this struct was generated from the following file:
  • s3eDevice.h


Airplay API Reference: s3eDeviceVolChangeInfo

Airplay API Reference > Data Structures > s3eDeviceVolChangeInfo >

s3eDeviceVolChangeInfo Struct Reference
[Device Interface API Reference]

#include <s3eDevice.h>

Data Fields

s3eBool | m_OverrideDefaultBehaviour
s3eBool | m_VolUp

Detailed Description

This structure is passed as the systemData paramater to the S3E_DEVICE_VOL_UP and S3E_DEVICE_VOL_DOWN callbacks.

This structure informs the user whether the callback came from S3E_DEVICE_VOL_UP or S3E_DEVICE_VOL_DOWN (so the same function may be registered for both) and allows the user to override S3E's default volume-change behaviour.

Field Documentation

s3eBool s3eDeviceVolChangeInfo::m_OverrideDefaultBehaviour

[out] This is set to S3E_FALSE on entry to the callback.

If the user sets this to S3E_TRUE, S3E will not perform its default handling action for the event.

The default handling action is to add or subtract a fixed amount (usually 32, but may vary between platforms) from each of the sound, audio and video device volumes.

Note that if multiple callbacks are registered for either volume change event, the second and subsequent callbacks will receive the s3eDeviceVolChangeInfo from the previous callback. The value of m_OverrideDefaultBehaviour is taken from that set by the last callback in the chain.

s3eBool s3eDeviceVolChangeInfo::m_VolUp

This is set to S3E_TRUE if the callback is a volume up notification (S3E_DEVICE_VOL_UP), or S3E_FALSE if it is a volume down notification (S3E_DEVICE_VOL_DOWN)

The documentation for this struct was generated from the following file:
  • s3eDevice.h


Airplay API Reference: s3eExtMetricsInfo

Airplay API Reference > Data Structures > s3eExtMetricsInfo >

s3eExtMetricsInfo Struct Reference
[Metrics Extension API Reference]

#include <s3eExt_Metrics.h>

Detailed Description

This is the system paramater supplied to a callback registered by s3eExtMetricsRegister

The m_Name member of this structure points to a NULL-terminated string containing the full name of the metric.

The callback should write the new value of the metric into the m_Value member of this structure.

The return value of the callback is ignored.

Required Header Files:
s3eSurface.h

Field Documentation

int64 s3eExtMetricsInfo::m_Value

[out] Value of integer metric

The documentation for this struct was generated from the following file:
  • s3eExt_Metrics.h


Airplay API Reference: s3eFileUserCallbacks

Airplay API Reference > Data Structures > s3eFileUserCallbacks >

s3eFileUserCallbacks Struct Reference
[File System API Reference]

#include <s3eFile.h>

Detailed Description

This structure specifies the user callbacks to be used when the corresponding file system calls are made. Using this structure you can set specialised functions to deal with compressed or platform specific file types. The user can register one or more of these structures via s3eFileAddUserFileSys().

s3eFileOpen() runs through the list of registered s3eFileUserCallbacks calling the m_Open member of each with the same parameters as the call to s3eFileOpen(). If any m_Open member returns non-NULL then the resulting handle is saved and s3eFileOpen() returns a s3eFile handle that is set to 'user mode'. If no user file system opens the file then s3eFileOpen() attempts to open the file from the system.

Once a file handle is in user mode calls to s3eFileRead(), s3eFileWrite(), s3eFileEOF(), s3eFileSeek(), s3eFileTell() and s3eFileClose() will be redirected to the m_Read, m_Write, m_EOF, m_Seek, m_Tell and m_Close members of the corresponding s3eFileUserCallbacks structure, using the handle returned by the m_Open member.

s3eFileListDirectory() will call the m_ListDir, m_ListNext and m_ListClose members of all registered s3eFileUserCallbacks to obtain the complete list of files in a directory that s3eFileOpen() would succeed on. It will also append any system files that appear in the specified directory. The result is then be read out via s3eFileListNext().

s3eFileDelete() will call the (non-NULL) m_Delete members of all registered s3eFileUserCallbacks until one succeeds.

The m_Write and m_Delete members may be NULL to implement a read-only file system.

Required Header Files
s3eFile.h

Field Documentation

s3eUserCloseFn s3eFileUserCallbacks::m_Close

Called from s3eFileClose().

s3eUserDeleteFn s3eFileUserCallbacks::m_Delete

Called from s3eFileDelete() (may be NULL for a read-only file system).

s3eUserEOFFn s3eFileUserCallbacks::m_EOF

Called from s3eFileEOF().

s3eUserListCloseFn s3eFileUserCallbacks::m_ListClose

Called from s3eFileListClose().

s3eUserListDirFn s3eFileUserCallbacks::m_ListDir

Called from s3eFileListDirectory().

s3eUserListNextFn s3eFileUserCallbacks::m_ListNext

Called from s3eFileListNext().

s3eUserOpenFn s3eFileUserCallbacks::m_Open

Called from s3eFileOpen().

s3eUserReadFn s3eFileUserCallbacks::m_Read

Called from s3eFileRead().

void* s3eFileUserCallbacks::m_Reserved[5]

Reserved.

s3eUserSeekFn s3eFileUserCallbacks::m_Seek

Called from s3eFileSeek().

s3eUserTellFn s3eFileUserCallbacks::m_Tell

Called from s3eFileTell().

s3eUserWriteFn s3eFileUserCallbacks::m_Write

Called from s3eFileWrite() (may be NULL for a read-only file system).

The documentation for this struct was generated from the following file:
  • s3eFile.h


Airplay API Reference: s3eInetAddress

Airplay API Reference > Data Structures > s3eInetAddress >

s3eInetAddress Struct Reference
[Socket API Reference]

#include <s3eSocket.h>

Data Fields

char | m_Abstract
s3eInetIPAddress m_IPAddress
char | m_LocalAddress [128]
uint16 | m_Port
char | m_String [128]

Detailed Description

Representation of internet address. This is used in socket calls that require the specification of an address. On systems that support local sockets both absolute and abstract local socket names are supported.

See also:
s3eSocketBind, s3eSocketGetLocalName
Required Header Files
s3eSocket.h

Field Documentation

char s3eInetAddress::m_Abstract

local socket name.

s3eInetIPAddress s3eInetAddress::m_IPAddress

Indicates whether or not local socket is abstract.

char s3eInetAddress::m_LocalAddress[128]

Indicates whether or not the socket is local.

uint16 s3eInetAddress::m_Port

32-bit IP address in network byte order

char s3eInetAddress::m_String[128]

16-bit port number in network byte order

The documentation for this struct was generated from the following file:
  • s3eSocket.h


Airplay API Reference: s3eKeyboardCharEvent

Airplay API Reference > Data Structures > s3eKeyboardCharEvent >

s3eKeyboardCharEvent Struct Reference
[Keyboard API Reference]

#include <s3eKeyboard.h>

Detailed Description

Structure passed to the S3E_KEYBOARD_CHAR_EVENT callback as systemData
Required Header Files
s3eKeyboard.h
The documentation for this struct was generated from the following file:
  • s3eKeyboard.h


Airplay API Reference: s3eKeyboardEvent

Airplay API Reference > Data Structures > s3eKeyboardEvent >

s3eKeyboardEvent Struct Reference
[Keyboard API Reference]

#include <s3eKeyboard.h>

Detailed Description

Structure passed to the S3E_KEYBOARD_KEY_EVENT callback as systemData
Required Header Files
s3eKeyboard.h

Field Documentation

s3eKey s3eKeyboardEvent::m_Key

Key that was pressed or released.

uint32 s3eKeyboardEvent::m_Pressed

Whether the key was pressed (1) or released (0).

The documentation for this struct was generated from the following file:
  • s3eKeyboard.h


Airplay API Reference: s3eLocation

Airplay API Reference > Data Structures > s3eLocation >

s3eLocation Struct Reference
[Location API Reference]

#include <s3eLocation.h>

Detailed Description

Describes a position on the earth.
See also:
s3eZeroConfStartSearch
Required Header Files
s3eExt_Location.h

Field Documentation

uint64 s3eLocation::m_TimeStampUTC

When this location was recorded.

The documentation for this struct was generated from the following file:
  • s3eLocation.h


Airplay API Reference: s3eMemoryUsrMgr

Airplay API Reference > Data Structures > s3eMemoryUsrMgr >

s3eMemoryUsrMgr Struct Reference
[Memory API Reference]

#include <s3eMemory.h>

Detailed Description

Structure represting the user memory manager interface.
The documentation for this struct was generated from the following file:
  • s3eMemory.h


Airplay API Reference: s3ePaymentRequest

Airplay API Reference > Data Structures > s3ePaymentRequest >

s3ePaymentRequest Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

Structure identifying a payment request, for a quantity of a certain product
The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: s3ePaymentTransaction

Airplay API Reference > Data Structures > s3ePaymentTransaction >

s3ePaymentTransaction Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

The s3ePaymentTransaction structure describes a payment in the queue. It contains the request and payment status information.

Field Documentation

s3ePaymentRequest* s3ePaymentTransaction::m_Request

Payment request that orginated this transaction.

The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: s3ePointerEvent

Airplay API Reference > Data Structures > s3ePointerEvent >

s3ePointerEvent Struct Reference
[Pointer API Reference]

#include <s3ePointer.h>

Detailed Description

Structure passed to the S3E_POINTER_BUTTON_EVENT callback as systemData.
Required Header Files
s3ePointer.h

Field Documentation

s3ePointerButton s3ePointerEvent::m_Button

Button that was pressed or released.

uint32 s3ePointerEvent::m_Pressed

Whether the button was pressed (1) or released (0).

int32 s3ePointerEvent::m_x

Position X.

int32 s3ePointerEvent::m_y

Position Y.

The documentation for this struct was generated from the following file:
  • s3ePointer.h


Airplay API Reference: s3ePointerMotionEvent

Airplay API Reference > Data Structures > s3ePointerMotionEvent >

s3ePointerMotionEvent Struct Reference
[Pointer API Reference]

#include <s3ePointer.h>

Detailed Description

Structure passed to the S3E_POINTER_MOTION_EVENT callback as systemData.

Field Documentation

int32 s3ePointerMotionEvent::m_x

Position X.

int32 s3ePointerMotionEvent::m_y

Position Y.

The documentation for this struct was generated from the following file:
  • s3ePointer.h


Airplay API Reference: s3ePointerTouchEvent

Airplay API Reference > Data Structures > s3ePointerTouchEvent >

s3ePointerTouchEvent Struct Reference
[Pointer API Reference]

#include <s3ePointer.h>

Detailed Description

Structure passed to the S3E_POINTER_TOUCH_EVENT callback as systemData.
Required Header Files
s3ePointer.h

Field Documentation

uint32 s3ePointerTouchEvent::m_Pressed

Whether the touch started (1) or ended (0).

uint32 s3ePointerTouchEvent::m_TouchID

Opaque ID of the touch.

int32 s3ePointerTouchEvent::m_x

Position X.

int32 s3ePointerTouchEvent::m_y

Position Y.

The documentation for this struct was generated from the following file:
  • s3ePointer.h


Airplay API Reference: s3ePointerTouchMotionEvent

Airplay API Reference > Data Structures > s3ePointerTouchMotionEvent >

s3ePointerTouchMotionEvent Struct Reference
[Pointer API Reference]

#include <s3ePointer.h>

Detailed Description

Structure passed to the S3E_POINTER_TOUCH_MOTION_EVENT callback as systemData.

Field Documentation

uint32 s3ePointerTouchMotionEvent::m_TouchID

Opaque ID of the touch.

int32 s3ePointerTouchMotionEvent::m_x

Position X.

int32 s3ePointerTouchMotionEvent::m_y

Position Y.

The documentation for this struct was generated from the following file:
  • s3ePointer.h


Airplay API Reference: s3eProductIdentifier

Airplay API Reference > Data Structures > s3eProductIdentifier >

s3eProductIdentifier Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

A product identifer string that has previously been registered with the Store.

Field Documentation

const char* s3eProductIdentifier::m_ID

Globally unique (in the Store) string identifying the product.

The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: s3eProductInformation

Airplay API Reference > Data Structures > s3eProductInformation >

s3eProductInformation Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

Response from the MicroTransaction store, which gives a localized product title, description and price.

Field Documentation

s3eProductIdentifier* s3eProductInformation::m_ProductID

Global product identifier.

The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: s3eSoundEndSampleInfo

Airplay API Reference > Data Structures > s3eSoundEndSampleInfo >

s3eSoundEndSampleInfo Struct Reference
[Sound API Reference]

#include <s3eSound.h>

Data Fields

int32 | m_Channel
int16 * | m_NewData
uint32 | m_NumSamples
int32 | m_RepsRemaining

Detailed Description

This structure is passed as the systemData paramater to the S3E_CHANNEL_END_SAMPLE callback and the S3E_CHANNEL_STOP_AUDIO callback. The S3E_CHANNEL_END_SAMPLE callback can be used to notify the application that a channel has finished playing its audio data; therefore, allowing the user to supply more data to keep it playing.

The S3E_CHANNEL_STOP_AUDIO callback notifies the user that the channel is changing state from playing to stopped.

If the callback is from a S3E_CHANNEL_END_SAMPLE notification, then the user can control what happens to the channel.

If the callback returns non zero then the channel will repeat the data it has just played. If the callback returns zero the channel will stop. This overrides the current repeat count of the channel (although the repeat count is still decremented by the sound mixer). The m_RepsRemaining member can be used to determine this return value. The channel repeat count is decremented before this callback is called; therefore the first time the callback is called the m_RepsRemaining will be one less than the repeat paramater supplied to s3eSoundChannelPlay().

This callback can also supply more data to the channel. To do this, the user should set the m_NewData and m_NumSamples members to the new data it wishes to play, and return 1. The channel will play the new audio seamlessly

  • there will be no 'gap' in the output data. This is useful for e.g. joining music samples, or providing a continuous stream of automatically generated audio.

If the callback is from a S3E_CHANNEL_STOP_AUDIO notification, then the m_RepsRemaining, m_NewData and m_NumSamples fields will be zero. The system will ignore anything the user writes to these fields, as well as the return value of a S3E_CHANNEL_STOP_AUDIO callback. If a S3E_CHANNEL_END_SAMPLE callback returns zero (instructs the channel to stop), it will immediately be followed by a S3E_CHANNEL_STOP_AUDIO callback (channel has stopped).

Remarks:
These callbacks are usually called by system-level sound devices, which may be in a separate thread to normal S3E application execution. The S3E API is not thread-safe so no S3E API functions should be called from within either of these callbacks, with the exception of s3eSoundChannelGetInt and s3eSoundGetInt.

Field Documentation

int32 s3eSoundEndSampleInfo::m_Channel

The ID of the channel that generated this callback.

int16* s3eSoundEndSampleInfo::m_NewData

[out] Pointer to the start of the audio source. Set the contents of this to non-null to play a new sample. This variable should be set by the registered callback.

uint32 s3eSoundEndSampleInfo::m_NumSamples

[out] This is number of samples of audio data to be played. This variable should be set by the registered callback.

int32 s3eSoundEndSampleInfo::m_RepsRemaining

The number of times the sample is to be repeated before it should finish.

The documentation for this struct was generated from the following file:
  • s3eSound.h


Airplay API Reference: s3eSoundGenAudioInfo

Airplay API Reference > Data Structures > s3eSoundGenAudioInfo >

s3eSoundGenAudioInfo Struct Reference
[Sound API Reference]

#include <s3eSound.h>

Detailed Description

This structure is passed as the systemData paramater to the S3E_CHANNEL_GEN_AUDIO callback.

Remarks:
If a S3E_CHANNEL_GEN_AUDIO callback is registered, the sound mixer no longer reads the audio data supplied to s3eSoundChannelPlay(), and instead calls the S3E_CHANNEL_GEN_AUDIO callback to obtain and mix audio data.

The handler should write up to m_NumSamples samples of audio data to m_Target. If m_Mix is 0, then m_Target must be overwritten with new audio data. If m_Mix is 1, then new audio data must be mixed (added with saturation) to the data already present in m_Target. If m_Stereo if ture then m_NumSamples is the number of pairs of left/right interleaved samples.

Note that the data written to m_Target will be played directly out of the device's speaker, and will be played at the output device audio frequency (S3E_SOUND_OUTPUT_FREQ). When generating audio, the handler will likely wish to take into account the current channel frequency (S3E_CHANNEL_RATE) and the current channel volume (S3E_CHANNEL_VOLUME). As the output device frequency cannot be predicted, the handler should be prepared to rate convert to any output frequency.

The m_OrigStart, m_OrigNumSamples and m_OrigRepeat are provided for convenience; they are the start, numsamples and repeat parameters passed to the last call to s3eSoundChannelPlay() on this channel. If the end of the sample is reached, and either loopfrom passed to s3eSoundChannelPlay() is non-zero or S3E_CHANNEL_END_SAMPLE callback is called and returns a new audio data, m_OrigStart and m_OrigNumSamples will be updated to reflect this change

The handler should return the number of samples it wrote to m_Target. If the handler wishes to stop generating audio it must set the m_EndSample member to S3E_TRUE. In this case the repeat count for the channel is decremented, the S3E_CHANNEL_END_SAMPLE is called and audio playing will resume again if there are repetitions remaining.

When unregistering a generate audio callback via s3eSoundChannelUnRegister() is an asychronous process as the sound runs in a separate thread. This means it cannot be assumed that immediately after a call to s3eSoundChannelUnRegister(), that the callback will no longer be called. This can have implications if the callback reads dynamically allocated data that is freed immediately after a call to s3eSoundChannelUnRegister(). To free such data safely, free it in the S3E_CHANNEL_STOP_AUDIO callback, after which it can be guaranteed that * no more callbacks will take place.

This callback is usually called by a system-level sound device, which may be in a separate thread to normal S3E application execution. The S3E API is not thread-safe so no S3E API functions should be called from within this callback, with the exception of s3eSoundChannelGetInt and s3eSoundGetInt.

Field Documentation

int32 s3eSoundGenAudioInfo::m_Channel

The ID of the channel that generated this callback.

s3eBool s3eSoundGenAudioInfo::m_EndSample

[out] The handler reached the end of its sample.

int32 s3eSoundGenAudioInfo::m_Mix

If this is 0, then m_Target may be overwritten with new samples; otherwise, it must be mixed with the incoming audio.

uint32 s3eSoundGenAudioInfo::m_NumSamples

The number of samples to mix into m_Target.

uint32 s3eSoundGenAudioInfo::m_OrigNumSamples

The sample length passed as numsamples to s3eSoundChannelPlay().

uint32 s3eSoundGenAudioInfo::m_OrigRepeat

The number of repetitions passed as repeat to s3eSoundChannelPlay().

int16* s3eSoundGenAudioInfo::m_OrigStart

The sample data passed as start to s3eSoundChannelPlay().

s3eBool s3eSoundGenAudioInfo::m_Stereo

true for stereo callbacks registered with S3E_CHANNEL_GEN_AUDIO_STEREO.

int16* s3eSoundGenAudioInfo::m_Target

The target sound buffer into which the user sample should be written or mixed.

The documentation for this struct was generated from the following file:
  • s3eSound.h


Airplay API Reference: s3eSurfaceCopyupInfo

Airplay API Reference > Data Structures > s3eSurfaceCopyupInfo >

s3eSurfaceCopyupInfo Struct Reference
[Surface API Reference]

#include <s3eSurface.h>

Detailed Description

This is the system paramater supplied to the copyup callback function.
Remarks:
This callback is called when the system is about to display the current surface. This callback should copy the data from m_SrcSurface to m_DestSurface, performing any necessary pitch and colour conversion, as well as any desired post-processing effects.

If s3eSurfaceSetup() has not been called - i.e. the s3eSurfacePtr() returns the current display surface in its native format - then this callback will still be called, but with m_SrcSurface == m_DestSurface (the same surface as returned by s3eSurfacePtr()) If s3eSurfaceSetup() has been called with a specified user surface pointer, then it is guaranteed that m_SrcSurface != m_DestSurface. blitDirection must be noted, if a 90 degree rotation is specified then it should be assumed that the destination surface is a rotated version of the current surface, and it will therefore have its width and height swapped. The callback function should return 1 if copy was performed, and 0 if copy did not occur and system copyup should take place.

Required Header Files:
s3eSurface.h

Field Documentation

s3eSurfaceBlitDirection s3eSurfaceCopyupInfo::m_BlitDirection

Blit-direction information.

s3eSurfaceInfo s3eSurfaceCopyupInfo::m_DestSurface

Destination surface information. This is the surface to which data is to be copied.

uint32 s3eSurfaceCopyupInfo::m_Height

Height of rectangle to be copied to on the destination surface.

s3eSurfaceInfo s3eSurfaceCopyupInfo::m_SrcSurface

Source surface information. This is the surface from which data is to be copied.

uint32 s3eSurfaceCopyupInfo::m_Width

Width of rectangle to be copied to on the destination surface.

uint32 s3eSurfaceCopyupInfo::m_X

X-coordinate of rectangle to be copied to on the destination surface.

uint32 s3eSurfaceCopyupInfo::m_Y

Y-coordinate of rectangle to be copied to on the destination surface.

The documentation for this struct was generated from the following file:
  • s3eSurface.h


Airplay API Reference: s3eSurfaceInfo

Airplay API Reference > Data Structures > s3eSurfaceInfo >

s3eSurfaceInfo Struct Reference
[Surface API Reference]

#include <s3eSurface.h>

Detailed Description

Surface information.
Required Header Files:
s3eSurface.h

Field Documentation

void* s3eSurfaceInfo::m_Data

Pointer to surface data area.

uint32 s3eSurfaceInfo::m_Height

Height of surface.

uint32 s3eSurfaceInfo::m_Pitch

Pitch of surface.

s3eSurfacePixelType s3eSurfaceInfo::m_PixelType

Pixel type of surface. This can be any of those listed as part of s3eSurfacePixelType.

uint32 s3eSurfaceInfo::m_Width

Width of surface.

The documentation for this struct was generated from the following file:
  • s3eSurface.h


Airplay API Reference: s3eSurfaceOrientation

Airplay API Reference > Data Structures > s3eSurfaceOrientation >

s3eSurfaceOrientation Struct Reference
[Surface API Reference]

#include <s3eSurface.h>

Detailed Description

Surface Orientation. When the display size or orientation has changed the callback notification (S3E_SURFACE_SCREENSIZE) receives a pointer to an object of this type.

This callback will come from a call to s3eSurfaceShow() or eglSwapBuffers() if the application is using GLES.

Field Documentation

s3eSurfaceBlitDirection s3eSurfaceOrientation::m_DeviceBlitDirection

New device blit direction.

uint32 s3eSurfaceOrientation::m_Height

New user surface height.

s3eBool s3eSurfaceOrientation::m_OrientationChanged

True if orientation has changed.

uint32 s3eSurfaceOrientation::m_Pitch

New user surface pitch.

uint32 s3eSurfaceOrientation::m_Width

New user surface width.

The documentation for this struct was generated from the following file:
  • s3eSurface.h


Airplay API Reference: s3eTransactionIdentifier

Airplay API Reference > Data Structures > s3eTransactionIdentifier >

s3eTransactionIdentifier Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

A globally unique transaction identifier string, genereated by the Store.

Field Documentation

const char* s3eTransactionIdentifier::m_ID

Globally unique (string identifying the transaction.

The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: s3eTransactionReceipt

Airplay API Reference > Data Structures > s3eTransactionReceipt >

s3eTransactionReceipt Struct Reference
[Micro Transaction Extension API Reference]

#include <s3eExt_MicroTransaction.h>

Detailed Description

The receipt is a signed chunk of data that can be used to verify with the Store that the payment was successfully processed. This is useful because the device typically can not be trusted and your server can use this to verify that the payment actually occured.

Field Documentation

const void* s3eTransactionReceipt::m_ReceiptData

Receipt data.

The documentation for this struct was generated from the following file:
  • s3eExt_MicroTransaction.h


Airplay API Reference: Graph Legend

Airplay API Reference > Data Structures > Graph Legend >

Graph Legend

This page explains how to interpret the graphs that are generated by doxygen.

Consider the following example:

/*! Invisible class because of truncation */
class Invisible { };

/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };

/* Class not documented with doxygen comments */
class Undocumented { };

/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };

/*! A template class */
template<class T> class Templ { };

/*! Class that is inherited using protected inheritance */
class ProtectedBase { };

/*! Class that is inherited using private inheritance */
class PrivateBase { };

/*! Class that is used by the Inherited class */
class Used { };

/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
                  protected ProtectedBase,
                  private PrivateBase,
                  public Undocumented,
                  public Templ<int>
{
  private:
    Used *m_usedClass;
};
If the MAX_DOT_GRAPH_HEIGHT tag in the configuration file is set to 240 this will result in the following graph:

The boxes in the above graph have the following meaning:

  • A filled gray box represents the struct or class for which the graph is generated.
  • A box with a black border denotes a documented struct or class.
  • A box with a grey border denotes an undocumented struct or class.
  • A box with a red border denotes a documented struct or class forwhich not all inheritance/containment relations are shown. A graph is truncated if it does not fit within the specified boundaries.
The arrows have the following meaning:
  • A dark blue arrow is used to visualize a public inheritance relation between two classes.
  • A dark green arrow is used for protected inheritance.
  • A dark red arrow is used for private inheritance.
  • A purple dashed arrow is used if a class is contained or used by another class. The arrow is labeled with the variable(s) through which the pointed class or struct is accessible.
  • A yellow dashed arrow denotes a relation between a template instance and the template class it was instantiated from. The arrow is labeled with the template parameters of the instance.


Airplay API Reference: Class Hierarchy

Airplay API Reference > Class Hierarchy >

Airplay API Reference Class Hierarchy

This inheritance list is sorted roughly, but not completely, alphabetically:
  • CIw2DFont
  • CIw2DImage
  • CIw2DSurface
  • CIwAnimBlendSource
  • CIwArray< X, A, REALLOCATE >
  • CIwArray< Type >
  • CIwAutoFile
  • CIwBBoxT< V >
  • CIwBuffer::ByteProxy
  • CIwColour
    • CIwUIColour
  • CIwEvent
    • CIwUIEventAlertDialogButton
    • CIwUIEventButton
    • CIwUIEventCheckbox
    • CIwUIEventClick
    • CIwUIEventFocus
    • CIwUIEventKey
    • CIwUIEventLayout
    • CIwUIEventPointerEnter
    • CIwUIEventPointerLeave
    • CIwUIEventPointerMove
    • CIwUIEventRadioButton
    • CIwUIEventSlider
    • CIwUIEventSoftKey
    • CIwUIEventTabBarButton
    • CIwUIEventTextInput
  • CIwFBBox
  • CIwFMat
  • CIwFMat2D
  • CIwFQuat
  • CIwFSphere
  • CIwFVec2
  • CIwFVec3
  • CIwFVec4
  • CIwGxFontPreparedData
  • CIwGxShaderUniform
  • CIwGxStream
  • CIwGxSurface
  • CIwHTTP
  • CIwImage
  • CIwList< X >
  • CIwList< X >::Store
  • CIwListNode
  • CIwManagedList
  • CIwMat
  • CIwMat2D
  • CIwMenu
  • CIwMenuItem
    • CIwMenuItemEditValue
      • CIwMenuItemDisplayValue
        • CIwMenuItemDisplayBool
        • CIwMenuItemDisplayFloat
        • CIwMenuItemDisplayInt16
        • CIwMenuItemDisplayInt32
        • CIwMenuItemDisplayInt8
        • CIwMenuItemDisplayUInt16
        • CIwMenuItemDisplayUInt32
        • CIwMenuItemDisplayUInt8
      • CIwMenuItemEditAngle
      • CIwMenuItemEditBool
      • CIwMenuItemEditFixed
      • CIwMenuItemEditFloat
      • CIwMenuItemEditInt16
      • CIwMenuItemEditInt32
      • CIwMenuItemEditInt8
      • CIwMenuItemEditUInt16
      • CIwMenuItemEditUInt32
        • CIwMenuItemEditEnum
        • CIwMenuItemEditFlags
      • CIwMenuItemEditUInt8
    • CIwMenuItemManagedList
    • CIwMenuItemString
    • CIwMenuItemTitle
  • CIwMenuManager
  • CIwParseable
    • CIwManaged
      • CIwAnimBone
      • CIwAnimPlayer
      • CIwManagedRefCount
        • CIwResource
          • CIwAnim
          • CIwAnimSkel
          • CIwAnimSkin
          • CIwGxShaderTechnique
          • CIwMaterial
          • CIwModel
          • CIwPropertyDefine
          • CIwPropertySet
            • CIwUIPropertySet
          • CIwPropertySetBinding
          • CIwTexture
          • CIwUIAnimation
          • CIwUIElement
            • CIwUIAlertDialog
            • CIwUIButton
              • CIwUIRadioButton
            • CIwUICheckbox
            • CIwUIImage
            • CIwUILabel
              • CIwUITextField
            • CIwUIProgressBar
            • CIwUIScrollableView
              • CIwUITable
            • CIwUISlider
            • CIwUISoftKeyboard
            • CIwUISoftKeyPosition
            • CIwUITabBar
          • CIwUIElementEventHandler
          • CIwUIFocusHandler
            • CIwUIFocusHandler2D
            • CIwUIFocusHandlerTab
          • CIwUILayoutItem
            • CIwUIElementItem
            • CIwUILayout
              • CIwUILayoutForm
              • CIwUILayoutGrid
              • CIwUILayoutHorizontal
              • CIwUILayoutVertical
            • CIwUILayoutItemContainer
            • CIwUILayoutSpacer
          • CIwUIStylesheet
      • CIwModelBlock
      • CIwModelExt
        • CIwModelExtPos
        • CIwModelExtSelSet
          • CIwModelExtSelSetEdge
          • CIwModelExtSelSetFace
          • CIwModelExtSelSetVert
        • CIwModelExtSphere
      • CIwPropertyBase
        • CIwProperty< Type >
      • CIwResGroup
      • CIwResHandler
        • CIwResHandlerANIM
        • CIwResHandlerGEO
        • CIwResHandlerGROUP
        • CIwResHandlerImage
        • CIwResHandlerITX
        • CIwResHandlerMTL
        • CIwResHandlerSKEL
        • CIwResHandlerSKIN
      • CIwResList
      • CIwResTemplate
        • CIwResTemplateANIM
        • CIwResTemplateGEO
        • CIwResTemplateGROUP
        • CIwResTemplateImage
        • CIwResTemplateMTL
        • CIwResTemplateSKEL
        • CIwResTemplateSKIN
      • CIwUIAnimKeyFrame
      • CIwUIStyle
    • CIwPropertyList< Type >
  • CIwPlane
  • CIwPropertyDataType< Type >
  • CIwPropertyString
  • CIwPropertyTypeMap< Key >
  • CIwQuat
  • CIwRect
  • CIwRect32
    • CIwUIRect
  • CIwResManager
  • CIwSphereT< V, R >
  • CIwSQuat
  • CIwString< N >
  • CIwSVec2
  • CIwSVec3
  • CIwSVec4
  • CIwTextDecomposer
  • CIwTextParser
    • CIwTextParserITX
  • CIwUIAnimator
  • CIwUIAnimData
  • CIwUIAnimDataLocator
  • CIwUIAnimDataType< Type >
  • CIwUIAnimManager
  • CIwUIController
  • CIwUIElementPtr
  • CIwUIGraphics
  • CIwUIPositionPolicy
  • CIwUISizePolicy
  • CIwUIStyleManager
  • CIwUIView
  • CIwUncopyable
    • CIwUIDrawableText
    • CIwUIElement
    • CIwUIFocusHandler
    • CIwUIHoldingPtr< Type >
    • CIwUIStylesheet
  • CIwURI
  • CIwUriEscape
  • CIwVec2
  • CIwVec3
  • CIwVec4
  • IIwDecomposable
    • CIwPropertySet
    • CIwPropertySetBinding
    • CIwUIAnimation
    • CIwUIAnimKeyFrame
    • CIwUIElement
    • CIwUIElementEventHandler
    • CIwUIFocusHandler
    • CIwUILayoutItem
  • IIwFocusResolver
  • IIwPropertySetObserver
    • CIwUIElement
  • IIwUIAnimatorObserver
  • IIwUIDrawable
    • CIwUIDrawableBorder
    • CIwUIDrawableImage
    • CIwUIDrawableText
  • IIwUIEventHandler
    • CIwUIElement
    • CIwUIElementEventHandler
    • CIwUITextInput
  • s3eAudioCallbackData
  • s3eDecompressionInput
  • s3eDeviceStateChangeInfo
  • s3eDeviceVolChangeInfo
  • s3eExtMetricsInfo
  • s3eFileUserCallbacks
  • s3eInetAddress
  • s3eKeyboardCharEvent
  • s3eKeyboardEvent
  • s3eLocation
  • s3eMemoryUsrMgr
  • s3ePaymentRequest
  • s3ePaymentTransaction
  • s3ePointerEvent
  • s3ePointerMotionEvent
  • s3ePointerTouchEvent
  • s3ePointerTouchMotionEvent
  • s3eProductIdentifier
  • s3eProductInformation
  • s3eSoundEndSampleInfo
  • s3eSoundGenAudioInfo
  • s3eSurfaceCopyupInfo
  • s3eSurfaceInfo
  • s3eSurfaceOrientation
  • s3eTransactionIdentifier
  • s3eTransactionReceipt


Airplay API Reference: Namespace List

Airplay API Reference > Namespace List >

Airplay API Reference Namespace List

Here is a list of all documented namespaces with brief descriptions:
IwUIAtlas Utility functions for handling atlas materials


Airplay API Reference: IwUIAtlas

Airplay API Reference > Namespace List > IwUIAtlas >

IwUIAtlas Namespace Reference
[Rendering, Rendering]

Utility functions for handling atlas materials. More...

Functions

CIwSVec2 | GetAtlasMaterialSize (CIwMaterial *pMaterial)
CIwSVec2 | GetMaterialSize (CIwMaterial *pMaterial)
CIwRect | GetTextureUVMap (CIwTexture *pTexture)
CIwMaterial * | MapToAtlasMaterial (CIwMaterial *pMaterial, CIwRect *pUVMap)
const CIwSVec2 | MapToFixedUV (const CIwRect &uvMap, const CIwSVec2 &uv, bool offset=true)

Function Documentation

CIwSVec2 IwUIAtlas::GetAtlasMaterialSize ( CIwMaterial * pMaterial )

Returns true size of an atlased material. This is different from the material's texture size.

Parameters:
pMaterial Material which is atlas or not part of atlas.

CIwSVec2 IwUIAtlas::GetMaterialSize ( CIwMaterial * pMaterial )

As materials which have been moved into an atlas no longer know how big they are, we use this general method to get its size.

Returns:
Pixel size of material.

CIwRect IwUIAtlas::GetTextureUVMap ( CIwTexture * pTexture )

Returns UV mapping for texture which can be passed to MapToFixedUV.

Parameters:
pTexture Texture to query size of.

CIwMaterial* IwUIAtlas::MapToAtlasMaterial | ( | CIwMaterial * | pMaterial,
 |  | CIwRect * | pUVMap
 | ) |  |

Search for a corresponding atlas material and return UV mapping. Returned values can be passed to MapToFixedUV even if no atlas material was found.

Parameters:
pMaterial | Material for which to search for atlas material.
uvMap | Reference to return UV pixel offset and texture size.
Returns:
Atlas material if one exists, else original material.

const CIwSVec2 IwUIAtlas::MapToFixedUV | ( | const CIwRect & | uvMap,
 |  | const CIwSVec2 & | uv,
 |  | bool | offset = true
 | ) |  |

Scales to fixed point, and optionally offsets, using value returned by MapToAtlasMaterial.

Parameters:
uvMap | Pixel UV offset and scale to apply.
uv | Pixel UV to map to fixed UV.
offset | If UV offset should be applied. True for absolute UVs, false for UV delta.
Returns:
Fixed uv


Airplay API Reference: Namespace Members

Airplay API Reference > Namespace Members >

Namespace Members

  • All
  • Functions
Here is a list of all documented namespace members with links to the namespaces they belong to:

  • GetAtlasMaterialSize() : IwUIAtlas
  • GetMaterialSize() : IwUIAtlas
  • GetTextureUVMap() : IwUIAtlas
  • MapToAtlasMaterial() : IwUIAtlas
  • MapToFixedUV() : IwUIAtlas


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- a -

  • a : CIwColour
  • A_8 : CIwImage
  • ABGR_1555 : CIwImage
  • ABGR_2AAA : CIwImage
  • ABGR_4444 : CIwImage
  • ABGR_6666 : CIwImage
  • ABGR_8888 : CIwImage
  • Activate() : CIwUIAlertDialog , CIwUIScrollableView , CIwUISlider , CIwUIButton , CIwUISoftKeyboard , CIwUISoftKeyPosition , CIwUICheckbox , CIwUITabBar , CIwUITextField , CIwUIElement , CIwUIElementEventHandler , CIwUIImage , CIwUILabel , CIwUIRadioButton
  • Add() : CIwManagedList
  • AddBlock() : CIwModel
  • AddChild() : CIwResGroup , CIwUIElement
  • AddColumn() : CIwUILayoutGrid
  • AddDelegate() : CIwUIElement , CIwUIView
  • AddElement() : CIwUILayoutForm , CIwUILayoutGrid , CIwUILayoutHorizontal , CIwUILayoutVertical , CIwUIView , CIwUILayout , CIwUILayoutForm
  • AddElementToLayout() : CIwUIView
  • AddEventHandler() : CIwUIController , CIwUIElement
  • AddExt() : CIwModel
  • AddGroup() : CIwResManager
  • AddHandler() : CIwResManager
  • AddHashString() : IIwDecomposable
  • AddLayoutItem() : CIwUILayout , CIwUILayoutForm , CIwUILayoutGrid , CIwUILayoutHorizontal , CIwUILayoutVertical
  • AddMenu() : CIwMenuManager
  • AddMenuOrDestroy() : CIwMenuManager
  • AddProperty() : CIwUIAnimKeyFrame , CIwPropertySet
  • AddPropertySet() : CIwUIStylesheet
  • AddRes() : CIwResManager , CIwResGroup
  • AddRow() : CIwUILayoutGrid , CIwUITable
  • AddTemplate() : CIwResHandler
  • ALPHA_ADD : CIwMaterial
  • ALPHA_BLEND : CIwMaterial
  • ALPHA_DEFAULT : CIwMaterial
  • ALPHA_F : CIwGxSurface
  • ALPHA_HALF : CIwMaterial
  • ALPHA_NONE : CIwMaterial
  • ALPHA_SUB : CIwMaterial
  • AlphaMode : CIwMaterial
  • ALPHATEST_ALWAYS : CIwMaterial
  • ALPHATEST_DISABLED : CIwMaterial
  • ALPHATEST_EQUAL : CIwMaterial
  • ALPHATEST_GEQUAL : CIwMaterial
  • ALPHATEST_GREATER : CIwMaterial
  • ALPHATEST_LEQUAL : CIwMaterial
  • ALPHATEST_LESS : CIwMaterial
  • ALPHATEST_NEVER : CIwMaterial
  • ALPHATEST_NOTEQUAL : CIwMaterial
  • AlphaTestMode : CIwMaterial
  • Animate() : CIwUIAlertDialog , CIwUICheckbox , IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableText , CIwUIElement , CIwUIImage , CIwUIButton , CIwUIRadioButton , CIwUISlider , CIwUITabBar , CIwUIDrawableImage , CIwUILabel
  • AnimateDrawableStyle() : CIwUIAnimData
  • AnimateProperty() : CIwUIAnimData
  • append() : CIwArray< X, A, REALLOCATE > , CIwList< X > , CIwArray< X, A, REALLOCATE >
  • Apply() : CIwUISizePolicy , CIwResTemplateImage , CIwResTemplateSKIN , CIwResTemplateANIM , CIwResTemplateSKEL , CIwResTemplateMTL , CIwResTemplate , CIwUIPositionPolicy , CIwResTemplateGROUP
  • ApplyScale() : CIwModelExt , CIwAnim , CIwAnimSkin , CIwAnimSkel , CIwModelBlock
  • ApplySettings() : CIwResHandler
  • Area() : CIwUIRect
  • ARGB_8888 : CIwImage
  • Arrange() : CIwUILayoutItemContainer , CIwUIElement
  • ArrangeItem() : CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayout , CIwUILayoutSpacer
  • ATITC : CIwImage
  • Attach() : CIwUILayoutItemContainer , CIwUILayout , CIwUILayoutItem , CIwUILayoutSpacer
  • AttachButtonClickSlot() : CIwUIAlertDialog
  • AttachClickSlot() : CIwUIButton
  • ATTACHED_TO_SURFACE_F : CIwTexture
  • AttachPropertySets() : CIwUIAnimation
  • AttachSignalSlot() : CIwUIElement


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- k -

  • k : CIwPlane
  • KEEP_DATA_AFTER_UPLOAD_F : CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- l -

  • Layout() : CIwUIElement , CIwUIView
  • length() : CIwString< N >
  • Lerp() : CIwFQuat , CIwQuat , CIwSQuat
  • LoadFromFile() : CIwImage , CIwTexture
  • LoadGroup() : CIwResManager
  • LoadGroupFromMemory() : CIwResManager
  • LoadTemp() : CIwGxShaderTechnique
  • LockSize() : CIwManagedList , CIwArray< X, A, REALLOCATE >
  • LookAt() : CIwMat , CIwFMat
  • LookupChildHashed() : CIwUIElement
  • LookupChildNamed() : CIwUIElement
  • LookupSlot() : CIwUIView
  • LOOPED_F : CIwAnimBlendSource
  • LOOPED_LAST_ADVANCE_F : CIwAnimBlendSource
  • LOOPING_F : CIwAnimBlendSource


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- m -

  • m : CIwFMat , CIwFMat2D , CIwMat2D , CIwMat
  • m_Abstract : s3eInetAddress
  • m_Altitude : s3eLocation
  • m_AtlasAllMaterials : CIwResTemplateGROUP
  • m_AtlasPadding : CIwResTemplateGROUP
  • m_BlitDirection : s3eSurfaceCopyupInfo
  • m_Blocks : CIwModel
  • m_BSphere : CIwModel
  • m_Button : s3ePointerEvent
  • m_Channel : s3eSoundEndSampleInfo , s3eSoundGenAudioInfo
  • m_ChannelID : s3eAudioCallbackData
  • m_Close : s3eFileUserCallbacks
  • m_ColourID : CIwMenuItem
  • m_Data : s3eDecompressionInput , s3eSurfaceInfo
  • m_Delete : s3eFileUserCallbacks
  • m_DestSurface : s3eSurfaceCopyupInfo
  • m_DeviceBlitDirection : s3eSurfaceOrientation
  • m_Edges : CIwModelExtSelSetEdge
  • m_EndSample : s3eSoundGenAudioInfo
  • m_EOF : s3eFileUserCallbacks
  • m_Ext : CIwResHandler
  • m_Exts : CIwModel
  • m_FaceIDs : CIwModelExtSelSetFace
  • m_Flags : CIwTexture , CIwModelBlock , CIwModelExtSelSetFace
  • m_FlagsHW : CIwModelExtSelSetFace
  • m_FlagsSW : CIwModelExtSelSetFace
  • m_FormatHW : CIwTexture
  • m_FormatSW : CIwTexture
  • m_formattedPrice : s3eProductInformation
  • m_GLOTIndex : CIwTexture
  • m_H : CIwMenuItem
  • m_Hash : CIwManaged
  • m_Height : s3eSurfaceInfo , s3eSurfaceOrientation , s3eSurfaceCopyupInfo
  • m_HorizontalAccuracy : s3eLocation
  • m_HWID : CIwTexture
  • m_ID : s3eProductIdentifier , s3eTransactionIdentifier
  • m_IPAddress : s3eInetAddress
  • m_Key : s3eKeyboardEvent
  • m_Latitude : s3eLocation
  • m_ListClose : s3eFileUserCallbacks
  • m_ListDir : s3eFileUserCallbacks
  • m_ListNext : s3eFileUserCallbacks
  • m_LocalAddress : s3eInetAddress
  • m_LocalizedDescription : s3eProductInformation
  • m_LocalizedTitle : s3eProductInformation
  • m_Longitude : s3eLocation
  • m_Materials : CIwModel
  • m_Max : CIwBBoxT< V >
  • m_MaxAreaPerTexture : CIwResTemplateGROUP
  • m_MaxAtlasTargets : CIwResTemplateGROUP
  • m_Min : CIwBBoxT< V >
  • m_Mix : s3eSoundGenAudioInfo
  • m_Name : CIwMenuItem , s3eExtMetricsInfo
  • m_NewData : s3eSoundEndSampleInfo
  • m_NumFaces : CIwModelExtSelSetFace
  • m_NumItems : CIwModelBlock
  • m_NumSamples : s3eSoundEndSampleInfo , s3eSoundGenAudioInfo
  • m_Open : s3eFileUserCallbacks
  • m_OrientationChanged : s3eSurfaceOrientation
  • m_OrigNumSamples : s3eSoundGenAudioInfo
  • m_OrigRepeat : s3eSoundGenAudioInfo
  • m_OrigStart : s3eSoundGenAudioInfo
  • m_OTZOfsSW : CIwModelExtSelSetFace
  • m_OverrideDefaultBehaviour : s3eDeviceVolChangeInfo
  • m_Owner : CIwModelBlock , CIwModelExt
  • m_PageSize : CIwResTemplateGROUP
  • m_PaletteCacheRGBs : CIwTexture
  • m_Pitch : s3eSurfaceInfo , s3eSurfaceOrientation
  • m_PixelType : s3eSurfaceInfo
  • m_Port : s3eInetAddress
  • m_Pos : CIwModelExtPos
  • m_Pressed : s3eKeyboardEvent , s3ePointerEvent , s3ePointerTouchEvent
  • m_price : s3eProductInformation
  • m_priceLocal : s3eProductInformation
  • m_ProductID : s3eProductInformation
  • m_Read : s3eFileUserCallbacks
  • m_ReceiptData : s3eTransactionReceipt
  • m_ReceiptSize : s3eTransactionReceipt
  • m_RenderFn : CIwModelBlock
  • m_RepsRemaining : s3eSoundEndSampleInfo
  • m_Request : s3ePaymentTransaction
  • m_Reserved : s3eFileUserCallbacks
  • m_ResName : CIwResTemplate
  • m_Resources : CIwResList
  • m_ResType : CIwResHandler
  • m_Seek : s3eFileUserCallbacks
  • m_Settings : CIwResHandler
  • m_Size : s3eDecompressionInput , CIwModelBlock
  • m_Sphere : CIwModelExtSphere
  • m_SrcSurface : s3eSurfaceCopyupInfo
  • m_State : s3eDeviceStateChangeInfo
  • m_Stereo : s3eSoundGenAudioInfo
  • m_String : s3eInetAddress
  • m_Target : s3eSoundGenAudioInfo
  • m_Tell : s3eFileUserCallbacks
  • m_TemplateCurr : CIwResHandler
  • m_TemplateInit : CIwResHandler
  • m_Templates : CIwResHandler
  • m_Text : CIwMenuItem
  • m_TileSpecs : CIwResTemplateGROUP
  • m_TimeStampUTC : s3eLocation
  • m_TouchID : s3ePointerTouchEvent , s3ePointerTouchMotionEvent
  • m_TransactionID : s3ePaymentTransaction
  • m_TransactionReceipt : s3ePaymentTransaction
  • m_TransactionStatus : s3ePaymentTransaction
  • m_UShiftFactor : CIwTexture
  • m_Value : s3eExtMetricsInfo
  • m_VerticalAccuracy : s3eLocation
  • m_VertIDs : CIwModelExtSelSetVert
  • m_VolUp : s3eDeviceVolChangeInfo
  • m_VRAMInfo : CIwTexture
  • m_VShiftFactor : CIwTexture
  • m_W : CIwMenuItem
  • m_Width : s3eSurfaceCopyupInfo , s3eSurfaceInfo , s3eSurfaceOrientation
  • m_WorldSet : CIwModelExtSelSetFace
  • m_Write : s3eFileUserCallbacks
  • m_X : CIwMenuItem
  • m_x : s3ePointerMotionEvent , s3ePointerEvent , s3ePointerTouchEvent , s3ePointerTouchMotionEvent
  • m_X : s3eSurfaceCopyupInfo
  • m_y : s3ePointerEvent
  • m_Y : CIwMenuItem
  • m_y : s3ePointerTouchMotionEvent , s3ePointerTouchEvent
  • m_Y : s3eSurfaceCopyupInfo
  • m_y : s3ePointerMotionEvent
  • MainFn : CIwMenuManager
  • Make() : CIwRect , CIwRect32
  • MakeAlphaPalZero() : CIwImage
  • MakeCurrent() : CIwGxSurface
  • MakeDisplayCurrent() : CIwGxSurface
  • MAT2 : CIwGxShaderUniform
  • MAT3 : CIwGxShaderUniform
  • MAT4 : CIwGxShaderUniform
  • maxV : CIwFBBox
  • Measure() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIScrollableView , CIwUILayoutItemContainer , CIwUIDrawableImage , CIwUIElement , CIwUIDrawableText
  • MeasureElement() : CIwUIAlertDialog , CIwUISlider , CIwUILabel , CIwUIImage , CIwUIButton , CIwUICheckbox , CIwUITabBar
  • MeasureItem() : CIwUILayoutItemContainer , CIwUILayoutSpacer , CIwUILayoutItem , CIwUILayout
  • MemoryUsage() : CIwArray< X, A, REALLOCATE >
  • Minus() : CIwMenuItem
  • minV : CIwFBBox
  • MODE_BUILD : CIwResManager
  • MODE_LOAD : CIwResManager
  • MODULATE_NONE : CIwMaterial
  • MODULATE_R : CIwMaterial
  • MODULATE_RGB : CIwMaterial
  • ModulateColour() : CIwUIGraphics
  • ModulateMode : CIwMaterial
  • MountGroup() : CIwResManager
  • MoveCharacters() : CIwGxFontPreparedData
  • MoveElement() : CIwUILayout
  • MoveFocus() : CIwUIFocusHandler2D , CIwUIFocusHandlerTab , CIwUIFocusHandler , CIwUIView


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- n -

  • NATIVE_16BIT_F : CIwTexture
  • NEEDS_SW_TRANSPARENCY_F : CIwTexture
  • NEVER_SW_F : CIwTexture
  • NO_FILTER_F : CIwTexture
  • NO_MIPMAPPING_F : CIwTexture
  • NO_SCROLL_F : CIwMenuItem
  • NO_TRANSPARENCY_F : CIwTexture
  • Normalise() : CIwFMat , CIwSVec3 , CIwSVec4 , CIwFMat2D , CIwVec2 , CIwVec3 , CIwFVec2 , CIwVec4 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwSVec2
  • NormaliseInPlace() : CIwFQuat , CIwQuat , CIwSQuat
  • NormaliseSafe() : CIwVec2 , CIwVec4 , CIwSVec3 , CIwSVec2 , CIwSVec4 , CIwVec3
  • NormaliseSlow() : CIwVec3 , CIwSVec2 , CIwSVec4 , CIwSVec3 , CIwVec2 , CIwVec4
  • Notify() : CIwUIController
  • NotifyProgress() : IIwUIAnimatorObserver
  • NotifyPropertyChanged() : IIwPropertySetObserver , CIwPropertySetBinding
  • NotifyStopped() : IIwUIAnimatorObserver


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- o -

  • OFS_ANIM_LOOPED_F : CIwAnimPlayer
  • OnPropertyChanged() : CIwUIAlertDialog , CIwUICheckbox , CIwUIRadioButton , CIwUISlider , CIwUIElement , CIwUISoftKeyPosition , CIwUITabBar , CIwUIButton , CIwUIImage , CIwUITextField , CIwUILabel
  • OnSizeChanged() : CIwUIImage , CIwUILabel , CIwUIRadioButton , CIwUISlider , CIwUITextField , CIwUIAlertDialog , CIwUIButton , CIwUICheckbox
  • OpenAttribute() : CIwTextDecomposer
  • OpenScope() : CIwTextDecomposer
  • operator *() : CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwColour , CIwVec2 , CIwFMat , CIwVec3 , CIwFMat2D , CIwVec4 , CIwFQuat , CIwUIColour , CIwUIRect , CIwFQuat , CIwFVec2 , CIwFVec3
  • operator *=() : CIwMat2D , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIColour , CIwColour , CIwFMat , CIwFMat2D , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat
  • operator CIwFMat() : CIwFQuat
  • operator CIwMat() : CIwQuat , CIwSQuat
  • operator s3eFile *() : CIwAutoFile
  • operator!=() : CIwColour , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIRect
  • operator+() : CIwColour , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • operator+=() : CIwVec2 , CIwVec3 , CIwVec4 , CIwColour , CIwFMat , CIwFMat2D , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwSVec2 , CIwSVec3 , CIwSVec4
  • operator-() : CIwVec4 , CIwFQuat , CIwFVec2 , CIwVec2 , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwPlane , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • operator-=() : CIwColour , CIwFVec2 , CIwFVec3 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwFVec4
  • operator/() : CIwSVec4 , CIwFVec2 , CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwVec2 , CIwVec3 , CIwVec4 , CIwFVec3
  • operator<<() : CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIRect , CIwQuat
  • operator<<=() : CIwVec4 , CIwMat , CIwMat2D , CIwSVec2 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwSVec3
  • operator=() : CIwURI , CIwSVec3 , CIwVec4 , CIwFVec4 , CIwQuat , CIwSVec4 , CIwColour , CIwArray< X, A, REALLOCATE > , CIwFQuat , CIwFVec3 , CIwFVec2 , CIwSVec2 , CIwVec3 , CIwUIColour , CIwUIRect , CIwSQuat , CIwVec2 , CIwURI
  • operator==() : CIwVec3 , CIwSVec4 , CIwUIRect , CIwFMat2D , CIwFVec2 , CIwSVec2 , CIwMat , CIwFQuat , CIwColour , CIwFMat , CIwFVec3 , CIwPlane , CIwSVec3 , CIwVec2 , CIwVec4 , CIwQuat , CIwSQuat , CIwColour , CIwMat2D , CIwFVec4
  • operator>>() : CIwSVec3 , CIwVec4 , CIwSQuat , CIwSVec4 , CIwQuat , CIwSVec2 , CIwVec3 , CIwUIRect , CIwVec2
  • operator>>=() : CIwSVec2 , CIwVec2 , CIwSVec3 , CIwMat2D , CIwVec3 , CIwSVec4 , CIwVec4 , CIwMat
  • operator[]() : CIwVec3 , CIwSVec2 , CIwVec3 , CIwFVec3 , CIwSVec2 , CIwFVec4 , CIwFVec2 , CIwSVec3 , CIwVec2 , CIwSVec4 , CIwFVec2 , CIwFVec3 , CIwVec4 , CIwArray< X, A, REALLOCATE > , CIwSVec4 , CIwVec4 , CIwFVec4 , CIwVec2 , CIwSVec3 , CIwManagedList
  • operator^() : CIwFVec2 , CIwVec3 , CIwFVec4 , CIwVec2 , CIwSVec4 , CIwFVec3 , CIwVec4 , CIwSVec3 , CIwSVec2
  • optimise_capacity() : CIwArray< X, A, REALLOCATE >
  • OPTIMISE_INCLUDE_UNUSED_RES_F : CIwResManager
  • OPTIMISE_MOUNTED_BINARIES_F : CIwResManager
  • OptimizeCapacity() : CIwManagedList
  • OVERFLOW_CORRECTION_F : CIwAnimPlayer
  • OWNS_HW_TEXELS_F : CIwTexture
  • OWNS_PALETTE_CACHE_RGBS_F : CIwTexture
  • OWNS_PALETTE_F : CIwTexture
  • OWNS_TEXELS_F : CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- z -

  • z : CIwFVec3 , CIwFVec4 , CIwSVec4 , CIwVec3 , CIwSVec3 , CIwVec4
  • Zero() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- ~ -

  • ~CIwAutoFile() : CIwAutoFile
  • ~CIwHTTP() : CIwHTTP
  • ~CIwImage() : CIwImage
  • ~CIwMaterial() : CIwMaterial
  • ~CIwModel() : CIwModel
  • ~CIwTextParserITX() : CIwTextParserITX
  • ~CIwTexture() : CIwTexture
  • ~CIwURI() : CIwURI


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- b -

  • b : CIwColour
  • Back() : CIwMenuItem
  • back() : CIwList< X > , CIwArray< X, A, REALLOCATE >
  • begin() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • BGR_332 : CIwImage
  • BGR_565 : CIwImage
  • BGR_888 : CIwImage
  • BLEND_ADD : CIwMaterial
  • BLEND_BLEND : CIwMaterial
  • BLEND_COMPLETE_F : CIwAnimBlendSource
  • BLEND_DECAL : CIwMaterial
  • BLEND_MODULATE : CIwMaterial
  • BLEND_REPLACE : CIwMaterial
  • BlendMode : CIwMaterial
  • BOUND_TO_ACTIVE_SURFACE_F : CIwTexture
  • BoundVec() : CIwBBoxT< V > , CIwFBBox
  • BoundVecs() : CIwSphereT< V, R > , CIwBBoxT< V > , CIwFBBox , CIwFSphere
  • BroadcastEvent() : CIwUIController
  • Build() : CIwResHandlerITX , CIwResHandlerSKEL , CIwResHandlerImage , CIwResHandlerSKIN , CIwResHandlerGROUP , CIwResHandler , CIwResHandlerANIM , CIwResHandlerMTL , CIwResHandlerGEO
  • BuildGroupCallbackPost : CIwResManager
  • BuildGroupCallbackPre : CIwResManager
  • BuildHierarchy() : CIwUIStyleManager
  • BuildPropertySetHierarchy() : CIwUIStylesheet


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- c -

  • c_str() : CIwString< N >
  • Cancel() : CIwHTTP
  • CanResize() : CIwArray< X, A, REALLOCATE >
  • capacity() : CIwArray< X, A, REALLOCATE > , CIwString< N >
  • ChangePalette() : CIwTexture
  • ChangeTexels() : CIwTexture
  • ChooseFocus() : CIwUIView
  • CIwArray() : CIwArray< X, A, REALLOCATE >
  • CIwAutoFile() : CIwAutoFile
  • CIwBBoxT() : CIwBBoxT< V >
  • CIwFMat() : CIwFMat
  • CIwFMat2D() : CIwFMat2D
  • CIwFQuat() : CIwFQuat
  • CIwFVec2() : CIwFVec2
  • CIwFVec3() : CIwFVec3
  • CIwFVec4() : CIwFVec4
  • CIwGxShaderUniformType : CIwGxShaderUniform
  • CIwGxStream() : CIwGxStream
  • CIwGxSurfaceImplementation : CIwGxSurface
  • CIwHTTP() : CIwHTTP
  • CIwImage() : CIwImage
  • CIwMat() : CIwMat
  • CIwMat2D() : CIwMat2D
  • CIwMaterial() : CIwMaterial
  • CIwMenuItemDisplayBool() : CIwMenuItemDisplayBool
  • CIwMenuItemDisplayFloat() : CIwMenuItemDisplayFloat
  • CIwMenuItemDisplayInt16() : CIwMenuItemDisplayInt16
  • CIwMenuItemDisplayInt32() : CIwMenuItemDisplayInt32
  • CIwMenuItemDisplayInt8() : CIwMenuItemDisplayInt8
  • CIwMenuItemDisplayUInt16() : CIwMenuItemDisplayUInt16
  • CIwMenuItemDisplayUInt32() : CIwMenuItemDisplayUInt32
  • CIwMenuItemDisplayUInt8() : CIwMenuItemDisplayUInt8
  • CIwMenuItemEditAngle() : CIwMenuItemEditAngle
  • CIwMenuItemEditBool() : CIwMenuItemEditBool
  • CIwMenuItemEditEnum() : CIwMenuItemEditEnum
  • CIwMenuItemEditFixed() : CIwMenuItemEditFixed
  • CIwMenuItemEditFlags() : CIwMenuItemEditFlags
  • CIwMenuItemEditFloat() : CIwMenuItemEditFloat
  • CIwMenuItemEditInt16() : CIwMenuItemEditInt16
  • CIwMenuItemEditInt32() : CIwMenuItemEditInt32
  • CIwMenuItemEditInt8() : CIwMenuItemEditInt8
  • CIwMenuItemEditUInt16() : CIwMenuItemEditUInt16
  • CIwMenuItemEditUInt32() : CIwMenuItemEditUInt32
  • CIwMenuItemEditUInt8() : CIwMenuItemEditUInt8
  • CIwMenuItemString() : CIwMenuItemString
  • CIwMenuItemTitle() : CIwMenuItemTitle
  • CIwModel() : CIwModel
  • CIwModelBlock() : CIwModelBlock
  • CIwModelExt() : CIwModelExt
  • CIwPlane() : CIwPlane
  • CIwProperty() : CIwProperty< Type >
  • CIwQuat() : CIwQuat
  • CIwRect() : CIwRect
  • CIwRect32() : CIwRect32
  • CIwResGroup() : CIwResGroup
  • CIwResHandler() : CIwResHandler
  • CIwSphereT() : CIwSphereT< V, R >
  • CIwSQuat() : CIwSQuat
  • CIwSVec2() : CIwSVec2
  • CIwSVec3() : CIwSVec3
  • CIwSVec4() : CIwSVec4
  • CIwTextParserITX() : CIwTextParserITX
  • CIwTexture() : CIwTexture
  • CIwUIDrawableBorder() : CIwUIDrawableBorder
  • CIwUIDrawableImage() : CIwUIDrawableImage
  • CIwUIDrawableText() : CIwUIDrawableText
  • CIwUIGraphics() : CIwUIGraphics
  • CIwURI() : CIwURI
  • CIwVec2() : CIwVec2
  • CIwVec3() : CIwVec3
  • CIwVec4() : CIwVec4
  • CLAMP_UV_F : CIwTexture
  • CLAMP_UV_SET_F : CIwTexture
  • ClassFactory() : CIwProperty< Type >
  • Clear() : CIwAnimBlendSource
  • clear() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • Clear() : CIwManagedList , CIwGxFontPreparedData
  • clear_optimised() : CIwArray< X, A, REALLOCATE >
  • ClearAndFree() : CIwManagedList
  • ClearFlags() : CIwModel , CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer
  • ClearSubAnim() : CIwAnimPlayer
  • ClearTable() : CIwUITable
  • CLIPPED_F : CIwModelBlock
  • ClipToFrustrum() : CIwSphereT< V, R >
  • ClipToPlane() : CIwSphereT< V, R >
  • Clone() : CIwUISlider , CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUIFocusHandler2D , CIwUIFocusHandlerTab , CIwUIImage , CIwUILabel , CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUIRadioButton , CIwUIRect , CIwUIScrollableView , CIwUISoftKeyboard , CIwUISoftKeyPosition , CIwUITabBar , CIwPropertySetBinding , CIwProperty< Type > , CIwPropertySet , CIwPropertyBase , CIwUITextField , CIwUILayoutSpacer , CIwUILayoutItem , CIwUIFocusHandler , CIwUIElement
  • CloneWithNewMaterials() : CIwModel
  • CloseAttribute() : CIwTextDecomposer
  • CloseScope() : CIwTextDecomposer
  • COLOUR : CIwGxStream
  • ColourID : CIwMenuItem
  • ColumnX() : CIwFMat2D , CIwFMat , CIwMat2D , CIwMat
  • ColumnY() : CIwFMat2D , CIwFMat , CIwMat2D , CIwMat
  • ColumnZ() : CIwFMat , CIwMat
  • Combine() : CIwFSphere
  • COMPLETE_F : CIwAnimBlendSource
  • COMPONENTS_1 : CIwGxStream
  • COMPONENTS_2 : CIwGxStream
  • COMPONENTS_3 : CIwGxStream
  • COMPONENTS_4 : CIwGxStream
  • ComposeTransform() : CIwUIGraphics
  • COMPRESSED : CIwImage
  • ConstructFullPathname() : CIwResHandler
  • ContainerFactory() : CIwUILayout
  • Contains() : CIwUIRect , CIwManagedList
  • contains() : CIwArray< X, A, REALLOCATE >
  • ContainsProperty() : CIwUIAnimKeyFrame
  • ContainsVec() : CIwBBoxT< V > , CIwFBBox , CIwSphereT< V, R >
  • ContentExpected() : CIwHTTP
  • ContentFinished() : CIwHTTP
  • ContentLength() : CIwHTTP
  • ContentReceived() : CIwHTTP
  • ConvertToCIwFMat() : CIwMat
  • ConvertToCIwFMat2D() : CIwMat2D
  • ConvertToCIwMat() : CIwFMat
  • ConvertToCIwMat2D() : CIwFMat2D
  • ConvertToImage() : CIwImage
  • Copy() : CIwMaterial , CIwResTemplateImage , CIwResTemplateGROUP , CIwProperty< Type > , CIwPropertyBase , CIwResTemplateSKIN , CIwResTemplate , CIwResTemplateMTL , CIwResTemplateSKEL , CIwResTemplateANIM
  • CopyFromBuffer() : CIwTexture
  • CopyFromImage() : CIwTexture
  • CopyList() : CIwManagedList
  • CopyRot() : CIwMat , CIwFMat , CIwMat2D , CIwFMat2D
  • CopyTrans() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D
  • CORRECT_OVERFLOW_F : CIwAnimBlendSource
  • CountColours() : CIwImage
  • CREATE_565_SURFACE_F : CIwGxSurface
  • CREATE_8888_SURFACE_F : CIwGxSurface
  • CREATE_FOR_2D_API_F : CIwTexture
  • CREATE_FOR_3D_API_F : CIwTexture
  • CreateAnim() : CIwMaterial
  • CreateDestination() : CIwUIAnimDataLocator
  • CreateDrawable() : CIwUIElement
  • CreateFromResource() : CIwUIElement
  • CreateProperty() : CIwPropertyDefine
  • CreateSoftKeyboard() : CIwUITextInput
  • CreateSurface() : CIwGxSurface
  • Cross() : CIwFVec3 , CIwVec3 , CIwSVec3
  • CTI : CIwGxSurface
  • CULL_BACK : CIwMaterial
  • CULL_FRONT : CIwMaterial
  • CULL_NONE : CIwMaterial
  • CullMode : CIwMaterial


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- d -

  • data() : CIwArray< X, A, REALLOCATE >
  • DEBUG_RENDER_BONE_AXES_F : CIwAnimPlayer
  • DEBUG_RENDER_BONE_LINKS_F : CIwAnimPlayer
  • DEBUG_RENDER_BONE_NAMES_F : CIwAnimPlayer
  • DebugAddMenuItems() : CIwModelBlock , CIwModelExt , CIwMaterial , CIwModelExtSelSetFace , CIwAnim , CIwManaged , CIwAnimPlayer , CIwAnimSkel , CIwModel , CIwAnimSkin
  • DebugDrawRect() : CIwUIGraphics
  • DebugGetName() : CIwManaged , CIwUIStyle
  • DebugGetPropertyDefine() : CIwPropertyBase
  • DebugRender() : CIwManaged , CIwModel , CIwModelExtPos , CIwModelExtSphere , CIwModelExtSelSetVert , CIwModelExtSelSetEdge , CIwModelExtSelSetFace , CIwAnimPlayer , CIwUIElement , CIwUIRect , CIwUIView
  • DebugRenderChildren() : CIwUIElement
  • DebugRenderElement() : CIwUILabel
  • Decompose() : CIwUIRect , CIwProperty< Type > , CIwPropertyBase
  • DecomposeAttributes() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutGrid , CIwUILayoutItem , CIwUIPropertySet , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding
  • DecomposeChild() : CIwTextDecomposer
  • DecomposeChildren() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayout , CIwUILayoutGrid , CIwUILayoutItem , CIwUILayoutItemContainer , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding
  • DecomposeClose() : CIwUILayoutItem , CIwUILayoutItemContainer , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding , CIwUIFocusHandler , CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler
  • DecomposeOpen() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutItem , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding , CIwUILayoutItemContainer , CIwUIElement
  • DecomposeToFile() : CIwTextDecomposer
  • DecrementCurrent() : CIwUIAnimDataLocator
  • Delete() : CIwManagedList
  • DEPTH_WRITE_DISABLED : CIwMaterial
  • DEPTH_WRITE_NORMAL : CIwMaterial
  • DepthWriteMode : CIwMaterial
  • DestroyChildren() : CIwUIElement
  • DestroyDelegates() : CIwUIElement , CIwUIView
  • DestroyElements() : CIwUIView
  • DestroyGroup() : CIwResManager
  • DestroyMenu() : CIwMenuManager
  • DestroyMenus() : CIwMenuManager
  • DetachButtonClickSlot() : CIwUIAlertDialog
  • DetachClickSlot() : CIwUIButton
  • DetachSignalSlot() : CIwUIElement
  • DO_HW_F : CIwTexture
  • DO_SW_F : CIwTexture
  • DONT_LOAD_CHILD_GROUPS_F : CIwResManager
  • DONT_SERIALISE_BLOCK_SIZES_F : CIwResManager
  • DONT_SERIALISE_IMAGE_F : CIwTexture
  • Dot() : CIwVec2 , CIwSVec3 , CIwFVec4 , CIwFVec2 , CIwSVec2 , CIwFVec3 , CIwVec4 , CIwVec3 , CIwSVec4
  • DoTextEntry() : CIwUITextInput
  • Draw() : CIwUIDrawableBorder , IIwUIDrawable , CIwUIDrawableImage , CIwUIDrawableText
  • DrawImage() : CIwUIGraphics
  • DrawText() : CIwUIGraphics


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- e -

  • EDITOR_INLINE_KEYBOARD : CIwUITextInput
  • EDITOR_INLINE_NUMPAD : CIwUITextInput
  • EDITOR_KEYBOARD : CIwUITextInput
  • EDITOR_NUMPAD : CIwUITextInput
  • EDITOR_OS : CIwUITextInput
  • EditorMode : CIwUITextInput
  • EFFECT_CONSTANT_COLOUR_CHANNEL : CIwMaterial
  • EFFECT_DEFAULT : CIwMaterial
  • EFFECT_LIGHTMAP_POST_PROCESS : CIwMaterial
  • EFFECT_NORMAL_MAPPING : CIwMaterial
  • EFFECT_NORMAL_MAPPING_SPECULAR : CIwMaterial
  • EFFECT_REFLECTION_MAPPING : CIwMaterial
  • EFFECT_TEXTURE0_ONLY : CIwMaterial
  • EffectPreset : CIwMaterial
  • EGL_10 : CIwGxSurface
  • EGL_11 : CIwGxSurface
  • element_at() : CIwList< X >
  • empty() : CIwArray< X, A, REALLOCATE >
  • end() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • Enter() : CIwMenuItem
  • erase() : CIwList< X >
  • Erase() : CIwManagedList
  • erase() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • erase_fast() : CIwArray< X, A, REALLOCATE >
  • EraseFast() : CIwManagedList
  • Escape() : CIwUriEscape
  • ETC : CIwImage
  • EXACT_MATCH_F : CIwGxSurface
  • Exit() : CIwMenuItem
  • ExposeData() : CIwPropertyBase , CIwProperty< Type >
  • ExposePropertySet() : CIwUIAnimKeyFrame , CIwUILayoutItem
  • ExtractSubTexture() : CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- f -

  • FBO : CIwGxSurface
  • FBO_OES : CIwGxSurface
  • Field : CIwTextParserITX
  • FieldArray : CIwTextParserITX
  • FieldArrayIt : CIwTextParserITX
  • FieldStripQuotes() : CIwTextParserITX
  • FILE : CIwURI
  • FilterEvent() : CIwUIController , CIwUIElement , IIwUIEventHandler , CIwUIElementEventHandler , CIwUISlider , CIwUITextInput
  • FilterString() : CIwTextParserITX
  • FilterStringGetEnum() : CIwTextParserITX
  • FilterStringGetEnumAsserted() : CIwTextParserITX
  • FilterStringGetFlags() : CIwTextParserITX
  • FilterStringResetFlags() : CIwTextParserITX
  • FilterStringSetFlags() : CIwTextParserITX
  • Finalise() : CIwResGroup
  • Find() : CIwManagedList
  • find() : CIwArray< X, A, REALLOCATE >
  • find_and_remove() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • find_and_remove_fast() : CIwArray< X, A, REALLOCATE >
  • FindWantsFocus() : CIwUIElement , CIwUIAlertDialog , CIwUIFocusHandler , CIwUITabBar
  • FixedBufferAvailable() : CIwImage
  • FixedBufferCheckOverflow() : CIwImage
  • FixedBufferFree() : CIwImage
  • FixedBufferSetSize() : CIwImage
  • Flags : CIwTexture
  • FLOAT : CIwGxShaderUniform
  • Format : CIwImage
  • FORMAT_UNDEFINED : CIwImage
  • FormatColour() : CIwImage
  • Free() : CIwGxStream
  • FREE_ASPECT_F : CIwGxSurface
  • front() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • FTP : CIwURI


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- g -

  • g : CIwColour
  • g_AxisW : CIwFVec4 , CIwVec4 , CIwSVec4
  • g_AxisX : CIwSVec2 , CIwSVec3 , CIwFVec2 , CIwSVec4 , CIwVec2 , CIwFVec3 , CIwVec3 , CIwVec4 , CIwFVec4
  • g_AxisY : CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwFVec2 , CIwFVec3
  • g_AxisZ : CIwFVec3 , CIwFVec4 , CIwSVec3 , CIwSVec4 , CIwVec3 , CIwVec4
  • g_Context : CIwModel
  • g_Identity : CIwFQuat , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwFMat , CIwFMat2D
  • g_Norms : CIwModel
  • g_Verts : CIwModel
  • g_XY : CIwPlane
  • g_XZ : CIwPlane
  • g_YZ : CIwPlane
  • g_Zero : CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • Get() : CIwColour , CIwHTTP , CIwProperty< Type >
  • GetAlignmentH() : CIwUILayoutItemContainer
  • GetAlignmentV() : CIwUILayoutItemContainer
  • GetAll() : CIwURI
  • GetAlphaMode() : CIwMaterial
  • GetAlphaTestMode() : CIwMaterial
  • GetAlphaTestRefVal() : CIwMaterial
  • GetAnim() : CIwAnimBlendSource
  • GetAnimationTime() : CIwUIAnimator
  • GetAnimCelH() : CIwMaterial
  • GetAnimCelID() : CIwMaterial
  • GetAnimCelNum() : CIwMaterial
  • GetAnimCelNumU() : CIwMaterial
  • GetAnimCelPeriod() : CIwMaterial
  • GetAnimCelW() : CIwMaterial
  • GetAnimOfsU() : CIwMaterial
  • GetAnimOfsV() : CIwMaterial
  • GetArraySize() : CIwGxShaderUniform
  • GetAtlasMaterial() : CIwResManager
  • GetBase() : CIwUIAnimDataLocator
  • GetBegin() : CIwManagedList , CIwPropertySet
  • GetBinding() : CIwPropertySet
  • GetBiTangents() : CIwModel
  • GetBitDepth() : CIwImage
  • GetBlendMode() : CIwMaterial
  • GetBlendParam() : CIwAnimBlendSource
  • GetBlockNamed() : CIwModel
  • GetBoneFromID() : CIwAnimPlayer , CIwAnimSkel
  • GetBoneHashed() : CIwAnimPlayer , CIwAnimSkel
  • GetBoneList() : CIwAnimSkel
  • GetBoneNamed() : CIwAnimPlayer , CIwAnimSkel
  • GetBorder() : CIwUILayoutItemContainer
  • GetBounds() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText
  • GetBSphere() : CIwModel
  • GetBuildStyleCurrName() : CIwResManager
  • GetByteDepth() : CIwImage
  • GetByteWidth() : CIwImage
  • GetCachedArrangeArea() : CIwUILayoutItemContainer
  • GetCachedArrangePos() : CIwUILayoutItemContainer
  • GetCapacity() : CIwManagedList
  • GetCaption() : CIwUILabel
  • GetCentre() : CIwBBoxT< V > , CIwFBBox
  • GetCharacterArea() : CIwGxFontPreparedData , CIwUIDrawableText
  • GetChecked() : CIwUICheckbox
  • GetChild() : CIwUIElement
  • GetChildBounds() : CIwUIElement
  • GetChildHashed() : CIwUIElement , CIwUIView
  • GetChildNamed() : CIwUIElement , CIwUIView
  • GetChildren() : CIwResGroup
  • GetClamping() : CIwMaterial , CIwTexture
  • GetClientHeight() : CIwGxSurface
  • GetClientUVExtent() : CIwGxSurface
  • GetClientWidth() : CIwGxSurface
  • GetCloneList() : CIwUIElement , CIwUIView
  • GetColAmbient() : CIwMaterial
  • GetColDiffuse() : CIwMaterial
  • GetColEmissive() : CIwMaterial
  • GetColour() : CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIGraphics , CIwGxStream , IIwUIDrawable
  • GetCols() : CIwModel
  • GetColSpecular() : CIwMaterial
  • GetCullMode() : CIwMaterial
  • GetCurrent() : CIwUIAnimDataLocator
  • GetCurrentGroup() : CIwResManager
  • GetCursorPosition() : CIwUITextField , CIwUITextInput
  • GetData() : CIwGxStream
  • GetDataType() : CIwProperty< Type > , CIwPropertyBase
  • GetDataTypeHash() : CIwPropertyDefine
  • GetDataTypeString() : CIwProperty< Type > , CIwPropertyBase
  • GetDelegate() : CIwUIElement
  • GetDepth() : CIwTexture
  • GetDistSqFromLine() : CIwSphereT< V, R >
  • GetDrawColour() : CIwUIGraphics
  • GetDuration() : CIwAnim
  • GetEffectPreset() : CIwMaterial
  • GetElement() : CIwUIElementEventHandler , CIwUIView
  • GetElementBounds() : CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIImage , CIwUILabel , CIwUIRadioButton , CIwUISlider
  • GetElementItem() : CIwUIElementItem
  • GetElementSize() : CIwGxShaderUniform
  • GetElementType() : CIwGxShaderUniform
  • GetEnd() : CIwManagedList , CIwPropertySet
  • GetExt() : CIwResHandler
  • GetExtHashed() : CIwModel
  • GetExtNamed() : CIwModel
  • GetFiltering() : CIwMaterial , CIwTexture
  • GetFlags() : CIwTexture , CIwImage , CIwModel , CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer
  • GetFocus() : CIwUIElement , CIwUIView
  • GetFocusHandler() : CIwUIElement
  • GetFormat() : CIwTexture , CIwImage
  • GetFormatData() : CIwImage
  • GetFormatHW() : CIwTexture
  • GetFormatSW() : CIwTexture
  • GetFormSize() : CIwUILayoutForm
  • GetFrame() : CIwUIElement
  • GetFrameBounds() : CIwUIGraphics
  • GetGlobalPropertySet() : CIwUIStyleManager
  • GetGroup() : CIwResManager
  • GetGroupHashed() : CIwResManager
  • GetGroupNamed() : CIwResManager
  • GetHandle() : CIwUIAnimator
  • GetHandler() : CIwResManager
  • GetHashString() : IIwDecomposable
  • GetHeader() : CIwHTTP
  • GetHeight() : CIwGxSurface , CIwTexture , CIwImage , CIwGxFontPreparedData , CIw2DImage , CIw2DFont
  • GetHost() : CIwURI
  • GetImplementation() : CIwGxSurface
  • GetInverse() : CIwFMat2D , CIwMat2D
  • GetItem() : CIwUILayoutItemContainer
  • GetItemSize() : CIwModelBlock
  • GetKeyFrame() : CIwAnim , CIwUIAnimation , CIwUIAnimator
  • GetKeyFrameData() : CIwUIAnimator
  • GetKeyFrameTime() : CIwUIAnimator
  • GetLastSearchGroup() : CIwResManager
  • GetLayout() : CIwUIElement
  • GetLayoutItem() : CIwUILayout
  • GetLayoutItemIndex() : CIwUILayout
  • GetLayoutItems() : CIwUILayout
  • GetLength() : CIwGxStream , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSafe() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSquared() : CIwVec3 , CIwSVec2 , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwQuat , CIwSQuat , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec4
  • GetLengthSquaredSafe() : CIwVec2 , CIwVec3 , CIwVec4 , CIwSVec4 , CIwSVec2 , CIwSVec3
  • GetLengthSquaredUnshifted() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec4 , CIwVec3
  • GetLineEnd() : CIwGxFontPreparedData
  • GetLineStart() : CIwGxFontPreparedData
  • GetListHashed() : CIwResGroup
  • GetListNamed() : CIwResGroup
  • GetMat() : CIwAnimBone
  • GetMatOfs() : CIwAnimPlayer
  • GetMatOfsFinal() : CIwAnimPlayer
  • GetMatOfsInitial() : CIwAnimPlayer
  • GetMemSize() : CIwGxStream
  • GetMenu() : CIwMenuItem
  • GetMergeGeom() : CIwMaterial
  • GetMipMapping() : CIwTexture
  • GetMode() : CIwResManager
  • GetModel() : CIwAnimSkin
  • GetModifiable() : CIwTexture
  • GetModulateColour() : CIwUIGraphics
  • GetModulateMode() : CIwMaterial
  • GetModulatesColour() : CIwUIElement
  • GetNext() : CIwUIAnimDataLocator
  • GetNextCharacterPosition() : CIwGxFontPreparedData
  • GetNormalised() : CIwFVec2 , CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwFVec3
  • GetNormalisedSafe() : CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec4 , CIwVec3 , CIwSVec2
  • GetNorms() : CIwModel
  • GetNumBones() : CIwAnim , CIwAnimSkel
  • GetNumChars() : CIwGxFontPreparedData
  • GetNumChildren() : CIwAnimBone , CIwUIElement
  • GetNumChunks() : CIwModel
  • GetNumCols() : CIwModel
  • GetNumColumns() : CIwUILayoutGrid
  • GetNumElements() : CIwUIView
  • GetNumGroups() : CIwResManager
  • GetNumKeyFrames() : CIwAnim , CIwUIAnimation , CIwUIAnimator
  • GetNumLayoutItems() : CIwUILayout
  • GetNumLines() : CIwGxFontPreparedData
  • GetNumNorms() : CIwModel
  • GetNumProperties() : CIwPropertySet
  • GetNumRadioButtons() : CIwUITabBar
  • GetNumRows() : CIwUILayoutGrid
  • GetNumUVs() : CIwModel
  • GetNumVerts() : CIwModel
  • GetNumVertsUnique() : CIwModel
  • GetObject() : CIwTextDecomposer , CIwTextParserITX
  • GetObjHashed() : CIwManagedList
  • GetObjHashedNextIt() : CIwManagedList
  • GetObjNamed() : CIwManagedList
  • GetObserver() : CIwUIAnimator
  • GetOffset() : CIwGxStream
  • GetOverflow() : CIwAnimBlendSource
  • GetOwner() : CIwResGroup
  • GetPalette() : CIwTexture , CIwImage
  • GetPaletteCacheRGBs() : CIwTexture
  • GetPaletteMemSize() : CIwImage , CIwTexture
  • GetPaletteNumEntries() : CIwTexture
  • GetPaletteSize() : CIwImage
  • GetParam() : CIwGxShaderTechnique
  • GetParent() : CIwUIElement , CIwAnimBone , CIwUIPropertySet , CIwPropertySet , CIwUIStylesheet
  • GetParentElement() : CIwUILayout , CIwUILayoutItem
  • GetParentItem() : CIwUILayoutItem
  • GetPerpDist() : CIwPlane
  • GetPitch() : CIwImage , CIwTexture
  • GetPort() : CIwURI
  • GetPos() : CIwAnimBone , CIwUIElement
  • GetPosAbsolute() : CIwUIElement
  • GetPosition() : CIwUIDrawableText , CIwUIDrawableBorder , CIwUIDrawableImage , IIwUIDrawable
  • GetProgress() : CIwUIProgressBar
  • GetProperty() : CIwUIElement , CIwPropertySet , CIwPropertySetBinding , CIwUILayoutItem
  • GetPropertyByHash() : CIwPropertySet
  • GetPropertyByIndex() : CIwPropertySet
  • GetPropertyDefineID() : CIwPropertyBase
  • GetPropertySet() : CIwUILayoutItem , CIwUIAnimKeyFrame , CIwUIStylesheet , CIwUIStyleManager
  • GetPropertySetBinding() : CIwUIElement
  • GetProportion() : CIwUISlider
  • GetProtocol() : CIwURI
  • GetRadius() : CIwSphereT< V, R >
  • GetRenderSlot() : CIwUIElement
  • GetResHashed() : CIwResGroup , CIwResManager
  • GetResName() : CIwResTemplate
  • GetResNamed() : CIwResManager , CIwResGroup
  • GetResponseCode() : CIwHTTP
  • GetResType() : CIwResManager , CIwResHandler
  • GetRot() : CIwAnimBone
  • GetRotationAngle() : CIwQuat , CIwSQuat , CIwFQuat
  • GetRotationAxis() : CIwSQuat , CIwQuat , CIwFQuat
  • GetSelected() : CIwUITabBar , CIwUIRadioButton
  • GetSettings() : CIwResHandler
  • GetShadeMode() : CIwMaterial
  • GetSize() : CIwUIDrawableBorder , CIwManagedList , CIwUIDrawableImage , CIwUIElement , IIwUIDrawable , CIwUIDrawableText
  • GetSizeHint() : CIwUIElement
  • GetSizeMax() : CIwUIElement
  • GetSizeMin() : CIwUIElement
  • GetSizeToContent() : CIwUIElement
  • GetSizeToSpace() : CIwUILayout
  • GetSkel() : CIwAnimSkin , CIwAnimPlayer , CIwAnim
  • GetSkelID() : CIwAnimBone
  • GetSourceCurr() : CIwAnimPlayer
  • GetSourcePrev() : CIwAnimPlayer
  • GetSourceSub() : CIwAnimPlayer
  • GetSpecularPower() : CIwMaterial
  • GetSpeed() : CIwAnimBlendSource
  • GetStatus() : CIwHTTP
  • GetStride() : CIwGxStream
  • GetStyle() : CIwUIElement
  • GetStylesheet() : CIwUIStyleManager
  • GetSurfaceInfo() : CIwGxSurface
  • GetSVec2() : CIwGxStream
  • GetSVec3() : CIwGxStream
  • GetTail() : CIwURI
  • GetTangents() : CIwModel
  • GetTarget() : CIwUIAnimator
  • GetTemplate() : CIwResHandler
  • GetTemplateNamed() : CIwResHandler
  • GetTexelBitDepth() : CIwImage
  • GetTexels() : CIwImage , CIwTexture
  • GetTexelsMemSize() : CIwTexture , CIwImage
  • GetText() : CIwUILabel
  • GetTextSize() : CIwUIDrawableText
  • GetTexture() : CIwGxSurface , CIwMaterial
  • GetTime() : CIwAnimBlendSource , CIwAnimPlayer , CIwUIAnimator , CIwUIAnimKeyFrame
  • GetTop() : CIwManagedList
  • GetTotalSize() : CIwModelBlock
  • GetTrans() : CIwMat , CIwFMat2D , CIwMat2D , CIwSphereT< V, R > , CIwFMat
  • GetTransform() : CIwUIElement , CIwUIGraphics
  • GetTranspose() : CIwMat , CIwFMat , CIwMat2D , CIwFMat2D
  • GetType() : CIwGxStream
  • GetUInt16() : CIwGxStream
  • GetUserFlags() : CIwMaterial
  • GetUVOfs() : CIwMaterial
  • GetUVs() : CIwModel
  • GetValue() : CIwUISlider
  • GetVerts() : CIwModel
  • GetViewMat() : CIwUIGraphics
  • GetWidth() : CIwTexture , CIwGxSurface , CIwGxFontPreparedData , CIwImage , CIw2DImage
  • GetWrapMode() : CIwUIFocusHandler
  • GetZDepthFixed() : CIwModel
  • GetZDepthOfs() : CIwModel , CIwMaterial
  • GetZDepthOfsHW() : CIwMaterial
  • GlobalMode : CIwResManager


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- h -

  • h : CIwRect , CIwRect32
  • HandleEvent() : CIwUIController , CIwUIRadioButton , CIwUISoftKeyboard , CIwUIElement , CIwUITabBar , CIwUITextField , CIwManaged , IIwUIEventHandler , CIwUITextInput , CIwUIElementEventHandler
  • HandleEventClick() : CIwUISlider , CIwUITextField , CIwUIButton , CIwUICheckbox , CIwUIElement
  • HandleEventFocus() : CIwUIButton , CIwUIElement
  • HandleEventKey() : CIwUIButton , CIwUICheckbox , CIwUIElement , CIwUISlider , CIwUITabBar , CIwUITextField
  • HandleEventLayout() : CIwUIElement
  • HandleEventPointerEnter() : CIwUIButton , CIwUIElement
  • HandleEventPointerLeave() : CIwUITextField , CIwUIButton , CIwUIElement
  • HandleEventPointerMove() : CIwUIElement , CIwUISlider
  • HandlesFocus() : CIwUIAlertDialog , CIwUITabBar , CIwUIElement
  • HasAlpha() : CIwTexture , CIwImage
  • HasAlphaChannel() : CIwGxSurface
  • HasFocus() : CIwUIElement , CIwMenuManager
  • HasIdentityAmbient() : CIwMaterial
  • HasIdentityCols() : CIwMaterial
  • HasIdentityDiffuse() : CIwMaterial
  • HasIdentityEmissive() : CIwMaterial
  • HasPointerCapture() : CIwUIController
  • HTTP : CIwURI
  • HTTPS : CIwURI


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- i -

  • IncrementNext() : CIwUIAnimDataLocator
  • InFocusChain() : CIwUIView
  • Insert() : CIwManagedList
  • insert_slow() : CIwArray< X, A, REALLOCATE >
  • InsertElement() : CIwUILayout
  • InsertIntoLayout() : CIwUILayout
  • InsertIntoLayoutItem() : CIwUILayout
  • InsertItem() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • InsertOverLayoutItem() : CIwUILayout
  • INT : CIwGxShaderUniform
  • Interpolate() : CIwUIAnimDataType< Type >
  • InterpolatePos() : CIwFMat2D , CIwMat , CIwMat2D , CIwFMat
  • InterpolateRot() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • InterpRot() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • InterpTrans() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • Intersect() : CIwUIElement , CIwUIView , CIwUIElement
  • IntersectElement() : CIwUIButton , CIwUICheckbox , CIwUIRadioButton , CIwUISlider , CIwUITextField
  • IntersectFrame() : CIwUIGraphics
  • Intersection() : CIwUIRect
  • Intersects() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIRect
  • IntersectsLine() : CIwSphereT< V, R >
  • InvalidateLayout() : CIwUIElement , CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • IsActive() : CIwUIElement
  • IsAncestor() : CIwUIElement
  • IsAnim() : CIwMaterial
  • IsAnimPaused() : CIwMaterial
  • IsAnimPlaying() : CIwUIAnimManager
  • IsAttached() : CIwUILayout
  • IsBeingEdited() : CIwUITextInput
  • IsChildElement() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • IsClipped() : CIwUIElement
  • IsCloned() : CIwModel
  • IsCurrent() : CIwUIStylesheet
  • IsCurrentAnimComplete() : CIwAnimPlayer
  • IsCurrentBlendComplete() : CIwAnimPlayer
  • isDataType() : CIwProperty< Type > , CIwPropertyBase
  • isDefineMatch() : CIwPropertyBase
  • IsDescendant() : CIwUIElement
  • IsEmpty() : CIwUIRect
  • IsEnabled() : CIwGxShaderTechnique
  • IsEquivalent() : CIwMaterial
  • IsFilteringEvent() : CIwUIController
  • IsFocusable() : CIwUIView
  • IsFrameEmpty() : CIwUIGraphics
  • IsHandlingEvent() : CIwUIController
  • IsIdentity() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • IsInvisible() : CIwMaterial
  • IsLayoutInvalid() : CIwUIElement , CIwUILayout
  • IsNormalised() : CIwFVec3 , CIwFVec2 , CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwVec2 , CIwVec3 , CIwVec4 , CIwSVec4
  • IsRotIdentity() : CIwFMat2D , CIwMat , CIwMat2D , CIwFMat
  • IsRotSame() : CIwFMat2D , CIwMat , CIwMat2D , CIwFMat
  • IsRotZero() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D
  • IsScrollingRequired() : CIwUIScrollableView
  • IsShared() : CIwResGroup
  • IsTransIdentity() : CIwMat , CIwFMat2D , CIwMat2D , CIwFMat
  • IsTransSame() : CIwMat , CIwFMat , CIwFMat2D , CIwMat2D
  • IsTransZero() : CIwMat , CIwFMat , CIwFMat2D , CIwMat2D
  • IsUpdatable() : CIwUIElement
  • IsValid() : CIwGxSurface
  • IsVisible() : CIwUIElement
  • IsWithinLayout() : CIwUIElement
  • IsZero() : CIwFVec2 , CIwFVec3 , CIwFMat , CIwFMat2D , CIwSVec3 , CIwVec4 , CIwMat , CIwVec3 , CIwFVec4 , CIwMat2D , CIwSVec4 , CIwVec2 , CIwSVec2
  • IVEC2 : CIwGxShaderUniform
  • IVEC3 : CIwGxShaderUniform
  • IVEC4 : CIwGxShaderUniform
  • IW_GX_ALLOC_MATERIAL : CIwMaterial
  • IwGxDrawPrims : CIwMaterial
  • IwGxFlush : CIwMaterial
  • IwGxSetMaterial : CIwTexture
  • IwGxSetRasterisationHW : CIwMaterial
  • IwModelBlockRender : CIwModelBlock
  • IwResManagerInit : CIwResManager
  • IwResManagerTerminate : CIwResManager
  • IwUIInit : CIwUIElement
  • IwUITerminate : CIwUIElement


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- p -

  • PALETTE4_ABGR_4444 : CIwImage
  • PALETTE4_ARGB_8888 : CIwImage
  • PALETTE4_RGB_565 : CIwImage
  • PALETTE4_RGB_888 : CIwImage
  • PALETTE4_RGBA_4444 : CIwImage
  • PALETTE4_RGBA_5551 : CIwImage
  • PALETTE4_RGBA_8888 : CIwImage
  • PALETTE5_ABGR_1555 : CIwImage
  • PALETTE6_ABGR_1555 : CIwImage
  • PALETTE7_ABGR_1555 : CIwImage
  • PALETTE8_ABGR_4444 : CIwImage
  • PALETTE8_ARGB_8888 : CIwImage
  • PALETTE8_RGB_565 : CIwImage
  • PALETTE8_RGB_888 : CIwImage
  • PALETTE8_RGBA_4444 : CIwImage
  • PALETTE8_RGBA_5551 : CIwImage
  • PALETTE8_RGBA_8888 : CIwImage
  • PARAGRAPH_END_F : CIwMenuItem
  • Parse() : CIwUIColour , CIwUIRect , CIwProperty< Type > , CIwPropertyBase
  • ParseAttribute() : CIwModelExtSelSetFace , CIwResTemplateGEO , CIwResTemplateANIM , CIwResTemplateSKEL , CIwResTemplateSKIN , CIwResTemplate , CIwResTemplateGROUP , CIwResTemplateImage , CIwUIAnimKeyFrame , CIwUIElement , CIwUILayout , CIwUILayoutGrid , CIwUILayoutItem , CIwUIPropertySet , CIwGxShaderTechnique , CIwPropertyDefine , CIwPropertySet , CIwMaterial , CIwResTemplateMTL , CIwManaged , CIwModelExt , CIwModelExtPos , CIwModelExtSphere , CIwModelExtSelSetVert , CIwModelExtSelSetEdge
  • ParseClose() : CIwPropertySetBinding , CIwGxShaderTechnique , CIwMaterial , CIwManaged , CIwModel , CIwModelBlock , CIwModelExt , CIwModelExtSelSetFace , CIwResTemplate , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayout , CIwUIPropertySet , CIwPropertyDefine , CIwPropertySet
  • ParseCloseChild() : CIwManaged , CIwUIAnimation , CIwUIElement , CIwUILayout , CIwUILayoutGrid , CIwUILayoutItemContainer , CIwPropertySet
  • ParseFile() : CIwTextParserITX
  • ParseOpen() : CIwMaterial , CIwResTemplateMTL , CIwModelExtSelSetVert , CIwModelExtSelSetEdge , CIwManaged
  • Pause() : CIwAnimBlendSource , CIwAnimPlayer
  • PauseAnim() : CIwMaterial
  • PAUSED_F : CIwAnimBlendSource
  • PeekString() : CIwTextParserITX
  • PERSISTENT_F : CIwGxSurface
  • PlayAnim() : CIwAnimBlendSource , CIwAnimPlayer , CIwUIAnimManager
  • PlayOfsAnim() : CIwAnimPlayer
  • PlaySubAnim() : CIwAnimPlayer
  • Plus() : CIwMenuItem
  • Pop() : CIwManagedList
  • pop_back() : CIwArray< X, A, REALLOCATE >
  • pop_back_get() : CIwArray< X, A, REALLOCATE >
  • PopObject() : CIwTextParserITX
  • Populate() : CIwUILayout
  • PopulateElement() : CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayout
  • Post() : CIwHTTP
  • PostEvent() : CIwUIController
  • PostMult() : CIwFMat2D , CIwFMat , CIwMat , CIwMat2D
  • PostMultiply() : CIwMat , CIwFMat2D , CIwFMat , CIwMat2D
  • PostRender() : CIwModelBlock
  • PostRotate() : CIwMat , CIwFMat , CIwFMat2D , CIwMat2D
  • PreMult() : CIwFMat2D , CIwFMat , CIwMat , CIwMat2D
  • PreMultiply() : CIwFMat , CIwMat , CIwFMat2D , CIwMat2D
  • PreRotate() : CIwFMat , CIwMat , CIwMat2D , CIwFMat2D
  • PRESERVE_FRAME_BUFFER_F : CIwGxSurface
  • ProcessElement() : IIwFocusResolver
  • PROTOCOL : CIwURI
  • Push() : CIwManagedList
  • push_back() : CIwArray< X, A, REALLOCATE > , CIwList< X > , CIwArray< X, A, REALLOCATE >
  • push_back_qty() : CIwArray< X, A, REALLOCATE >
  • PushObject() : CIwTextParserITX
  • PVRTC_2 : CIwImage
  • PVRTC_4 : CIwImage


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- q -

  • QueueStylesheet() : CIwUIStyleManager


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- r -

  • r : CIwColour , CIwFSphere , CIwSphereT< V, R >
  • r2 : CIwFSphere , CIwSphereT< V, R >
  • Reactivate() : CIwUIView
  • ReadAngleDegrees() : CIwTextParserITX
  • ReadAngleRadians() : CIwTextParserITX
  • ReadBool() : CIwTextParserITX
  • ReadContent() : CIwHTTP
  • ReadDouble() : CIwTextParserITX
  • ReadDoubleArray() : CIwTextParserITX
  • ReadFile() : CIwImage
  • ReadFixed() : CIwTextParserITX
  • ReadFixedArray() : CIwTextParserITX
  • ReadFloat() : CIwTextParserITX
  • ReadFloatArray() : CIwTextParserITX
  • ReadInt16() : CIwTextParserITX
  • ReadInt16Array() : CIwTextParserITX
  • ReadInt32() : CIwTextParserITX
  • ReadInt32Array() : CIwTextParserITX
  • ReadInt8() : CIwTextParserITX
  • ReadInt8Array() : CIwTextParserITX
  • ReadLine() : CIwTextParserITX
  • ReadPalette() : CIwImage
  • ReadScope() : CIwTextParserITX
  • ReadString() : CIwTextParserITX
  • ReadStringHash() : CIwTextParserITX
  • ReadTexels() : CIwImage
  • ReadUInt16() : CIwTextParserITX
  • ReadUInt16Array() : CIwTextParserITX
  • ReadUInt32() : CIwTextParserITX
  • ReadUInt32Array() : CIwTextParserITX
  • ReadUInt8() : CIwTextParserITX
  • ReadUInt8Array() : CIwTextParserITX
  • RebuildMenu() : CIwMenuManager
  • RecreateSurface() : CIwGxSurface
  • REDUNDANT_F : CIwModelExt
  • RemakeMipmaps() : CIwTexture
  • RemapVertexIDs() : CIwModelExt , CIwModelExtSelSetVert , CIwModelExtSelSetEdge
  • RemoveChild() : CIwUIElement
  • RemoveChildItem() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayoutSpacer
  • RemoveDelegate() : CIwUIElement , CIwUIView
  • RemoveElement() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUIView
  • RemoveEventHandler() : CIwUIController , CIwUIElement
  • RemoveExt() : CIwModel
  • RemoveFast() : CIwManagedList
  • RemoveHandler() : CIwResManager
  • RemoveSlow() : CIwManagedList
  • Render() : CIwMenuManager , CIwMenuItemString , CIwMenuItemEditFlags , CIwMenuItemEditEnum , CIwModel , CIwModelBlock , CIwMenuItemEditFixed , CIwMenuItemEditAngle , CIwUIElement , CIwUIScrollableView , CIwUIView , CIwMenuItem
  • RenderChildren() : CIwUIElement
  • RenderElement() : CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIImage , CIwUILabel , CIwUIRadioButton , CIwUISlider , CIwUITextField
  • ReplaceAlpha() : CIwImage
  • ReplaceAlphaColourWithSurrounding() : CIwImage
  • ReplaceColour() : CIwImage
  • ReplacePalette() : CIwImage
  • RequestFocus() : CIwUIElement , CIwUIView
  • Reserve() : CIwManagedList , CIwGxFontPreparedData
  • reserve() : CIwArray< X, A, REALLOCATE >
  • reserve_optimised() : CIwArray< X, A, REALLOCATE >
  • ReserveExtraChildren() : CIwResGroup
  • ReserveGroups() : CIwResManager
  • ReserveHandlers() : CIwResManager
  • Reset() : CIwResTemplate , CIwMaterial , CIwResTemplateMTL , CIwResTemplateGEO , CIwResTemplateANIM , CIwResTemplateSKEL , CIwResTemplateSKIN , CIwResHandler , CIwResTemplateGROUP , CIwResTemplateImage
  • RESET_IF_SAME_F : CIwAnimBlendSource
  • ResetCurrent() : CIwUIAnimDataLocator
  • ResetNext() : CIwUIAnimDataLocator
  • ResetSkinCache() : CIwAnimSkel
  • resize() : CIwArray< X, A, REALLOCATE >
  • resize_optimised() : CIwArray< X, A, REALLOCATE >
  • resize_quick() : CIwArray< X, A, REALLOCATE >
  • Resolve() : CIwUILayoutItem , CIwUILayoutItemContainer , CIwUIPropertySet , CIwUIStyle , CIwProperty< Type > , CIwPropertyBase , CIwModelBlock , CIwTexture , CIwUILayout , CIwUIElement , CIwUIAnimKeyFrame , CIwResGroup , CIwModel , CIwManagedList , CIwUIRect , CIwPropertySet , CIwUIAnimation , CIwMaterial , CIwManaged , CIwUILayoutGrid , CIwAnimPlayer , IIwFocusResolver
  • ResolvePtrs() : CIwManagedList
  • ResolveResPtr() : CIwResManager
  • RestartAnim() : CIwMaterial
  • RGB_332 : CIwImage
  • RGB_565 : CIwImage
  • RGB_888 : CIwImage
  • RGBA_4444 : CIwImage
  • RGBA_5551 : CIwImage
  • RGBA_6666 : CIwImage
  • RGBA_8888 : CIwImage
  • RGBA_AAA2 : CIwImage
  • RotateVec() : CIwMat , CIwFMat2D , CIwMat2D , CIwMat , CIwMat2D , CIwFMat
  • RotateVecSafe() : CIwMat2D , CIwMat
  • RotateVector() : CIwQuat , CIwSQuat , CIwFQuat
  • RotateVecX() : CIwFMat , CIwMat , CIwMat2D , CIwFMat2D , CIwMat , CIwMat2D
  • RotateVecY() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D , CIwMat2D
  • RotateVecZ() : CIwFMat , CIwMat
  • RowX() : CIwMat2D , CIwFMat2D , CIwMat , CIwFMat
  • RowY() : CIwFMat2D , CIwMat , CIwMat2D , CIwFMat
  • RowZ() : CIwFMat , CIwMat
  • Run() : CIwMenuItem


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- s -

  • s : CIwFQuat , CIwQuat , CIwSQuat
  • s3eFileGet() : CIwAutoFile
  • s_CloneExpectedClassName : CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutItem
  • SaveBmp() : CIwImage
  • SaveTemp() : CIwGxShaderTechnique
  • Scale() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • ScaleRot() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D
  • ScaleTrans() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • ScrollToPosition() : CIwUIScrollableView
  • Select() : CIwMenuItemManagedList , CIwMenuItem
  • SelectMenu() : CIwMenuManager
  • SendEvent() : CIwUIController
  • Serialise() : CIwManaged , CIwUIColour , CIwUIElement , CIwManagedList , CIwUILayout , CIwUILayoutGrid , CIwModel , CIwUILayoutItem , CIwUILayoutItemContainer , CIwModelBlock , CIwUIPropertySet , CIwUIRect , CIwModelExt , CIwUIStyle , CIwProperty< Type > , CIwModelExtPos , CIwPropertyBase , CIwPropertyDefine , CIwModelExtSphere , CIwPropertySet , CIwModelExtSelSetVert , CIwModelExtSelSetEdge , CIwModelExtSelSetFace , CIwBBoxT< V > , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSphereT< V, R > , CIwSQuat , CIwColour , CIwSVec2 , CIwSVec3 , CIwGxShaderTechnique , CIwSVec4 , CIwVec2 , CIwMaterial , CIwVec3 , CIwVec4 , CIwTexture , CIwAnimPlayer , CIwResList , CIwImage , CIwUIAnimKeyFrame , CIwUIAnimation
  • SerialiseHeader() : CIwManagedList , CIwArray< X, A, REALLOCATE >
  • SerialisePtrs() : CIwManagedList
  • SerialiseResPtr() : CIwResManager
  • Set() : CIwColour , CIwGxShaderUniform , CIwProperty< Type >
  • SetAlignment() : CIwUILayoutItemContainer
  • SetAlignmentFromPos() : CIwUILayoutItemContainer
  • SetAlphaMode() : CIwMaterial
  • SetAlphaTestMode() : CIwMaterial
  • SetAlphaTestRefVal() : CIwMaterial
  • SetAnimCelH() : CIwMaterial
  • SetAnimCelID() : CIwMaterial
  • SetAnimCelNum() : CIwMaterial
  • SetAnimCelNumU() : CIwMaterial
  • SetAnimCelPeriod() : CIwMaterial
  • SetAnimCelW() : CIwMaterial
  • SetAnimOfsU() : CIwMaterial
  • SetAnimOfsV() : CIwMaterial
  • SetAssertOnUnrecognisedTokens() : CIwTextParserITX
  • SetAxisAngle() : CIwFMat , CIwFQuat , CIwMat , CIwQuat , CIwSQuat
  • SetBinding() : CIwPropertySet
  • SetBlendMode() : CIwMaterial
  • SetBorder() : CIwUILayoutItemContainer
  • SetBuildGroupCallbackPost() : CIwResManager
  • SetBuildGroupCallbackPre() : CIwResManager
  • SetBuildStyle() : CIwResManager
  • SetCaption() : CIwUIButton , CIwUILabel
  • SetCaptionLocalised() : CIwUILabel
  • SetChecked() : CIwUICheckbox
  • SetClamping() : CIwMaterial , CIwTexture
  • SetClipped() : CIwUIElement
  • SetColAmbient() : CIwMaterial
  • SetColDiffuse() : CIwMaterial
  • SetColEmissive() : CIwMaterial
  • SetColour() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIElement , CIwUIGraphics
  • SetColourFixed() : CIwUIColour
  • SetColSpecular() : CIwMaterial
  • SetCullMode() : CIwMaterial
  • SetCurrentGroup() : CIwResManager
  • SetCursorDelay() : CIwUITextInput
  • SetCursorFlashPeriod() : CIwUITextInput
  • SetEditorMode() : CIwUITextInput
  • SetEffectPreset() : CIwMaterial
  • SetElement() : CIwUILayout
  • SetEnabled() : CIwGxShaderTechnique , CIwUIButton
  • SetFiltering() : CIwMaterial , CIwTexture
  • SetFlags() : CIwModel , CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer
  • SetFocus() : CIwMenuManager
  • SetFocusHandler() : CIwUIElement
  • SetFocusKey() : CIwMenuManager
  • SetFormat() : CIwImage
  • SetFormatHW() : CIwTexture
  • SetFormatSW() : CIwTexture
  • SetFormSize() : CIwUILayoutForm
  • SetFrame() : CIwUIGraphics
  • SetGrey() : CIwColour
  • SetHeight() : CIwImage
  • SetIdentity() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • SetImage() : CIwTexture
  • SetInvisible() : CIwMaterial
  • SetItem() : CIwUILayoutItemContainer
  • SetLayout() : CIwUIElement
  • SetLayoutInvalid() : CIwUILayout
  • setLength() : CIwString< N >
  • SetMainMenuFn() : CIwMenuManager
  • SetMenuCharWH() : CIwMenuManager
  • SetMenuDefaultW() : CIwMenuManager
  • SetMenuDefaultXY() : CIwMenuManager
  • SetMergeGeom() : CIwMaterial
  • SetMipMapping() : CIwTexture
  • SetModal() : CIwUIView
  • SetMode() : CIwResManager
  • SetModel() : CIwAnimSkin
  • SetModelMatrix() : CIwAnimBone
  • SetModifiable() : CIwTexture
  • SetModulateColour() : CIwUIGraphics
  • SetModulateMode() : CIwMaterial
  • SetModulatesColour() : CIwUIElement
  • SetName() : CIwMaterial , CIwManaged , CIwUIAnimKeyFrame , CIwUIElement , CIwUILayoutItem
  • SetObserver() : CIwUIAnimator , CIwUIAnimManager
  • SetOpaque() : CIwColour
  • SetOrder() : CIwUILayoutHorizontal , CIwUILayoutVertical
  • SetOwnedBuffers() : CIwImage
  • SetPaletteCacheRGBs() : CIwTexture
  • SetParent() : CIwUIPropertySet , CIwUIStylesheet , CIwPropertySet
  • SetParentItem() : CIwUILayoutItem
  • SetPitch() : CIwImage
  • SetPointerCapture() : CIwUIController
  • SetPos() : CIwAnimBone , CIwUIElement
  • SetPosAbsolute() : CIwUIElement
  • SetPosition() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText
  • SetProgress() : CIwUIProgressBar
  • SetProperty() : CIwUIAnimKeyFrame , CIwUIElement , CIwUILayoutItem , CIwPropertySet , CIwPropertySetBinding , CIwUIElement
  • SetPropertyDefine() : CIwPropertyBase
  • SetPropertySetBinding() : CIwUIElement
  • SetProportion() : CIwUISlider
  • SetQueuedStylesheet() : CIwUIStyleManager
  • SetRadius() : CIwSphereT< V, R >
  • SetRedundant() : CIwModelExt
  • SetRenderSlot() : CIwUIElement
  • SetRequestHeader() : CIwHTTP
  • SetRot() : CIwMat2D , CIwFMat2D , CIwAnimBone
  • SetRotX() : CIwMat , CIwFMat
  • SetRotY() : CIwFMat , CIwMat
  • SetRotZ() : CIwMat , CIwFMat
  • SetSelectable() : CIwMenuItem
  • SetSelected() : CIwUITabBar , CIwUIRadioButton
  • SetShadeMode() : CIwMaterial
  • SetShared() : CIwResGroup
  • SetSize() : CIwUIDrawableBorder , CIwUIDrawableText , CIwUIDrawableImage , IIwUIDrawable , CIwUIElement
  • SetSizeHint() : CIwUIElement
  • SetSizeMax() : CIwUIElement
  • SetSizeMin() : CIwUIElement
  • SetSizeToContent() : CIwUIElement
  • SetSizeToSpace() : CIwUILayout
  • SetSkel() : CIwAnimPlayer , CIwAnimSkin
  • SetSoftKeyboardModal() : CIwUITextInput
  • SetSpacing() : CIwUILayoutVertical , CIwUILayoutHorizontal
  • SetSpecularPower() : CIwMaterial
  • SetSpeed() : CIwAnimBlendSource
  • SetStyle() : CIwUILayoutItem , CIwUIElement
  • SetStylesheet() : CIwUIStyleManager
  • SetTemplate() : CIwResHandler
  • SetTextCallback() : CIwMenuManager
  • SetTexture() : CIwMaterial
  • SetTime() : CIwAnimBlendSource , CIwAnimPlayer , CIwUIAnimManager , CIwUIAnimKeyFrame , CIwUIAnimator
  • SetTimeFraction() : CIwAnimBlendSource , CIwAnimPlayer
  • SetTrans() : CIwMat2D , CIwFMat2D , CIwMat , CIwMat2D , CIwMat , CIwFMat
  • SetTransform() : CIwUIElement , CIwUIGraphics
  • SetTransformPos() : CIwUIElement
  • Setup() : CIwUISizePolicy , CIwUIPositionPolicy
  • SetUpdatable() : CIwUIElement
  • SetUserFlags() : CIwMaterial
  • SetUVOfs() : CIwMaterial
  • SetValue() : CIwUISlider
  • SetViewMat() : CIwUIGraphics
  • SetVisible() : CIwUIElement
  • SetWidth() : CIwImage
  • SetWorldSpace() : CIwGxShaderUniform
  • SetWorldSpaceDirection() : CIwGxShaderUniform
  • SetZDepthFixed() : CIwModel
  • SetZDepthOfs() : CIwMaterial , CIwModel
  • SetZDepthOfsHW() : CIwMaterial
  • SetZero() : CIwMat2D , CIwMat , CIwFMat2D , CIwFMat
  • SHADE_FLAT : CIwMaterial
  • SHADE_GOURAUD : CIwMaterial
  • ShadeMode : CIwMaterial
  • Share() : CIwArray< X, A, REALLOCATE >
  • SHARED_SOURCE_F : CIwTexture
  • SHARES_TEXELS_F : CIwTexture
  • ShouldAllowFocus() : CIwUITextInput
  • ShouldDisplayCursor() : CIwUITextInput
  • size() : CIwString< N > , CIwArray< X, A, REALLOCATE >
  • SKIPPED_MIPMAP_GENERATION : CIwTexture
  • SkipScope() : CIwTextParserITX
  • Slerp() : CIwFQuat , CIwSQuat , CIwQuat
  • SplitPathName() : CIwResManager
  • Start() : CIwAnimPlayer , CIwAnimBlendSource
  • Stop() : CIwUIAnimator , CIwAnimPlayer , CIwAnimBlendSource
  • StopAllAnims() : CIwUIAnimManager
  • StopAnim() : CIwUIAnimManager
  • Store() : CIwUIPositionPolicy , CIwUISizePolicy
  • SVEC2 : CIwGxStream
  • SVEC3 : CIwGxStream
  • SW : CIwGxSurface
  • swap() : CIwArray< X, A, REALLOCATE >


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- t -

  • t : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D , CIwFSphere , CIwSphereT< V, R >
  • TestInsertPos() : CIwUILayout
  • TextCallback : CIwMenuManager
  • TransformVec() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • TransformVecSafe() : CIwMat , CIwMat2D , CIwMat
  • TransformVecShift() : CIwMat , CIwMat2D
  • Translate() : CIwUIRect
  • TranslateTransform() : CIwUIGraphics
  • Transpose() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • TransposeRotateVec() : CIwMat2D , CIwFMat , CIwFMat2D , CIwMat
  • TransposeRotateVecSafe() : CIwMat , CIwMat2D
  • TransposeTransformVec() : CIwFMat2D , CIwMat , CIwMat2D , CIwFMat
  • Type : CIwGxStream
  • TYPE_FIXED : CIwGxStream
  • TYPE_FLOAT : CIwGxStream
  • TYPE_INT16 : CIwGxStream
  • TYPE_INT8 : CIwGxStream
  • TYPE_UINT16 : CIwGxStream
  • TYPE_UINT8 : CIwGxStream


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- u -

  • UINT16 : CIwGxStream
  • Union() : CIwUIRect
  • UNKNOWN : CIwURI
  • UNSELECTABLE_F : CIwMenuItem
  • Update() : CIwAnimPlayer , CIwUIView , CIwUIAnimator , CIwMenuItem , CIwUIAnimManager , CIwUIController , CIwMenuManager , CIwUIElement , CIwUIScrollableView , CIwAnimBone , CIwUISoftKeyPosition , CIwUITextInput
  • UPDATE_XFORMS_F : CIwAnimBlendSource
  • UpdateMatrices() : CIwAnimPlayer
  • UpdateParameters() : CIwAnimBlendSource , CIwAnimPlayer
  • UpdateSource() : CIwAnimBlendSource
  • UpdateSources() : CIwAnimPlayer
  • Upload() : CIwGxStream , CIwTexture
  • UPLOAD_ON_LOAD_F : CIwTexture
  • UPLOADED_F : CIwTexture
  • UseAsHandle() : CIwTexture
  • USER_F : CIwModelBlock
  • USES_TRANSPARENCY_F : CIwTexture
  • UsesAlpha() : CIwImage , CIwTexture
  • UsesChromakey() : CIwImage , CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- v -

  • v : CIwPlane
  • VEC2 : CIwGxShaderUniform
  • VEC3 : CIwGxShaderUniform
  • VEC4 : CIwGxShaderUniform
  • VertCopiesAreIDs() : CIwModel


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- w -

  • w : CIwRect , CIwRect32 , CIwSVec4 , CIwVec4 , CIwFVec4
  • WantsFocus() : CIwUIElement , CIwUISlider , CIwUITextField , CIwUIButton , CIwUICheckbox
  • Write() : CIwResGroup
  • WriteAttibuteNameHash() : CIwTextDecomposer
  • WriteAttribute() : CIwTextDecomposer
  • WriteAttributeHash() : CIwTextDecomposer
  • WriteAttributeName() : CIwTextDecomposer
  • WriteAttributeNameVal() : CIwTextDecomposer
  • WriteAttributeNameValArray() : CIwTextDecomposer
  • WriteAttributeVal() : CIwTextDecomposer
  • WriteAttributeValArray() : CIwTextDecomposer
  • WriteClassName() : CIwTextDecomposer
  • WriteFlags() : CIwModel
  • WriteObjectName() : CIwTextDecomposer


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- x -

  • x : CIwRect , CIwVec4 , CIwVec3 , CIwVec2 , CIwSVec4 , CIwSVec3 , CIwSVec2 , CIwFVec4 , CIwFVec3 , CIwFVec2 , CIwRect32


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • x
  • y
  • z
  • ~

Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:

- y -

  • y : CIwRect , CIwVec4 , CIwVec3 , CIwVec2 , CIwSVec4 , CIwSVec3 , CIwSVec2 , CIwFVec4 , CIwFVec3 , CIwFVec2 , CIwRect32


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions

  • AlphaMode : CIwMaterial
  • AlphaTestMode : CIwMaterial
  • BlendMode : CIwMaterial
  • CIwGxShaderUniformType : CIwGxShaderUniform
  • CIwGxSurfaceImplementation : CIwGxSurface
  • ColourID : CIwMenuItem
  • CullMode : CIwMaterial
  • DepthWriteMode : CIwMaterial
  • EditorMode : CIwUITextInput
  • EffectPreset : CIwMaterial
  • Flags : CIwTexture
  • Format : CIwImage
  • GlobalMode : CIwResManager
  • ModulateMode : CIwMaterial
  • PROTOCOL : CIwURI
  • ShadeMode : CIwMaterial
  • Type : CIwGxStream


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • h
  • i
  • k
  • l
  • m
  • n
  • o
  • p
  • r
  • s
  • t
  • u
  • v

- a -

  • A_8 : CIwImage
  • ABGR_1555 : CIwImage
  • ABGR_2AAA : CIwImage
  • ABGR_4444 : CIwImage
  • ABGR_6666 : CIwImage
  • ABGR_8888 : CIwImage
  • ALPHA_ADD : CIwMaterial
  • ALPHA_BLEND : CIwMaterial
  • ALPHA_DEFAULT : CIwMaterial
  • ALPHA_F : CIwGxSurface
  • ALPHA_HALF : CIwMaterial
  • ALPHA_NONE : CIwMaterial
  • ALPHA_SUB : CIwMaterial
  • ALPHATEST_ALWAYS : CIwMaterial
  • ALPHATEST_DISABLED : CIwMaterial
  • ALPHATEST_EQUAL : CIwMaterial
  • ALPHATEST_GEQUAL : CIwMaterial
  • ALPHATEST_GREATER : CIwMaterial
  • ALPHATEST_LEQUAL : CIwMaterial
  • ALPHATEST_LESS : CIwMaterial
  • ALPHATEST_NEVER : CIwMaterial
  • ALPHATEST_NOTEQUAL : CIwMaterial
  • ARGB_8888 : CIwImage
  • ATITC : CIwImage
  • ATTACHED_TO_SURFACE_F : CIwTexture

- b -

  • BGR_332 : CIwImage
  • BGR_565 : CIwImage
  • BGR_888 : CIwImage
  • BLEND_ADD : CIwMaterial
  • BLEND_BLEND : CIwMaterial
  • BLEND_COMPLETE_F : CIwAnimBlendSource
  • BLEND_DECAL : CIwMaterial
  • BLEND_MODULATE : CIwMaterial
  • BLEND_REPLACE : CIwMaterial
  • BOUND_TO_ACTIVE_SURFACE_F : CIwTexture

- c -

  • CLAMP_UV_F : CIwTexture
  • CLAMP_UV_SET_F : CIwTexture
  • CLIPPED_F : CIwModelBlock
  • COLOUR : CIwGxStream
  • COMPLETE_F : CIwAnimBlendSource
  • COMPONENTS_1 : CIwGxStream
  • COMPONENTS_2 : CIwGxStream
  • COMPONENTS_3 : CIwGxStream
  • COMPONENTS_4 : CIwGxStream
  • COMPRESSED : CIwImage
  • CORRECT_OVERFLOW_F : CIwAnimBlendSource
  • CREATE_565_SURFACE_F : CIwGxSurface
  • CREATE_8888_SURFACE_F : CIwGxSurface
  • CREATE_FOR_2D_API_F : CIwTexture
  • CREATE_FOR_3D_API_F : CIwTexture
  • CTI : CIwGxSurface
  • CULL_BACK : CIwMaterial
  • CULL_FRONT : CIwMaterial
  • CULL_NONE : CIwMaterial

- d -

  • DEBUG_RENDER_BONE_AXES_F : CIwAnimPlayer
  • DEBUG_RENDER_BONE_LINKS_F : CIwAnimPlayer
  • DEBUG_RENDER_BONE_NAMES_F : CIwAnimPlayer
  • DEPTH_WRITE_DISABLED : CIwMaterial
  • DEPTH_WRITE_NORMAL : CIwMaterial
  • DO_HW_F : CIwTexture
  • DO_SW_F : CIwTexture
  • DONT_LOAD_CHILD_GROUPS_F : CIwResManager
  • DONT_SERIALISE_BLOCK_SIZES_F : CIwResManager
  • DONT_SERIALISE_IMAGE_F : CIwTexture

- e -

  • EDITOR_INLINE_KEYBOARD : CIwUITextInput
  • EDITOR_INLINE_NUMPAD : CIwUITextInput
  • EDITOR_KEYBOARD : CIwUITextInput
  • EDITOR_NUMPAD : CIwUITextInput
  • EDITOR_OS : CIwUITextInput
  • EFFECT_CONSTANT_COLOUR_CHANNEL : CIwMaterial
  • EFFECT_DEFAULT : CIwMaterial
  • EFFECT_LIGHTMAP_POST_PROCESS : CIwMaterial
  • EFFECT_NORMAL_MAPPING : CIwMaterial
  • EFFECT_NORMAL_MAPPING_SPECULAR : CIwMaterial
  • EFFECT_REFLECTION_MAPPING : CIwMaterial
  • EFFECT_TEXTURE0_ONLY : CIwMaterial
  • EGL_10 : CIwGxSurface
  • EGL_11 : CIwGxSurface
  • ETC : CIwImage
  • EXACT_MATCH_F : CIwGxSurface

- f -

  • FBO : CIwGxSurface
  • FBO_OES : CIwGxSurface
  • FILE : CIwURI
  • FLOAT : CIwGxShaderUniform
  • FORMAT_UNDEFINED : CIwImage
  • FREE_ASPECT_F : CIwGxSurface
  • FTP : CIwURI

- h -

  • HTTP : CIwURI
  • HTTPS : CIwURI

- i -

  • INT : CIwGxShaderUniform
  • IVEC2 : CIwGxShaderUniform
  • IVEC3 : CIwGxShaderUniform
  • IVEC4 : CIwGxShaderUniform

- k -

  • KEEP_DATA_AFTER_UPLOAD_F : CIwTexture

- l -

  • LOOPED_F : CIwAnimBlendSource
  • LOOPED_LAST_ADVANCE_F : CIwAnimBlendSource
  • LOOPING_F : CIwAnimBlendSource

- m -

  • MAT2 : CIwGxShaderUniform
  • MAT3 : CIwGxShaderUniform
  • MAT4 : CIwGxShaderUniform
  • MODE_BUILD : CIwResManager
  • MODE_LOAD : CIwResManager
  • MODULATE_NONE : CIwMaterial
  • MODULATE_R : CIwMaterial
  • MODULATE_RGB : CIwMaterial

- n -

  • NATIVE_16BIT_F : CIwTexture
  • NEEDS_SW_TRANSPARENCY_F : CIwTexture
  • NEVER_SW_F : CIwTexture
  • NO_FILTER_F : CIwTexture
  • NO_MIPMAPPING_F : CIwTexture
  • NO_SCROLL_F : CIwMenuItem
  • NO_TRANSPARENCY_F : CIwTexture

- o -

  • OFS_ANIM_LOOPED_F : CIwAnimPlayer
  • OPTIMISE_INCLUDE_UNUSED_RES_F : CIwResManager
  • OPTIMISE_MOUNTED_BINARIES_F : CIwResManager
  • OVERFLOW_CORRECTION_F : CIwAnimPlayer
  • OWNS_HW_TEXELS_F : CIwTexture
  • OWNS_PALETTE_CACHE_RGBS_F : CIwTexture
  • OWNS_PALETTE_F : CIwTexture
  • OWNS_TEXELS_F : CIwTexture

- p -

  • PALETTE4_ABGR_4444 : CIwImage
  • PALETTE4_ARGB_8888 : CIwImage
  • PALETTE4_RGB_565 : CIwImage
  • PALETTE4_RGB_888 : CIwImage
  • PALETTE4_RGBA_4444 : CIwImage
  • PALETTE4_RGBA_5551 : CIwImage
  • PALETTE4_RGBA_8888 : CIwImage
  • PALETTE5_ABGR_1555 : CIwImage
  • PALETTE6_ABGR_1555 : CIwImage
  • PALETTE7_ABGR_1555 : CIwImage
  • PALETTE8_ABGR_4444 : CIwImage
  • PALETTE8_ARGB_8888 : CIwImage
  • PALETTE8_RGB_565 : CIwImage
  • PALETTE8_RGB_888 : CIwImage
  • PALETTE8_RGBA_4444 : CIwImage
  • PALETTE8_RGBA_5551 : CIwImage
  • PALETTE8_RGBA_8888 : CIwImage
  • PARAGRAPH_END_F : CIwMenuItem
  • PAUSED_F : CIwAnimBlendSource
  • PERSISTENT_F : CIwGxSurface
  • PRESERVE_FRAME_BUFFER_F : CIwGxSurface
  • PVRTC_2 : CIwImage
  • PVRTC_4 : CIwImage

- r -

  • REDUNDANT_F : CIwModelExt
  • RESET_IF_SAME_F : CIwAnimBlendSource
  • RGB_332 : CIwImage
  • RGB_565 : CIwImage
  • RGB_888 : CIwImage
  • RGBA_4444 : CIwImage
  • RGBA_5551 : CIwImage
  • RGBA_6666 : CIwImage
  • RGBA_8888 : CIwImage
  • RGBA_AAA2 : CIwImage

- s -

  • SHADE_FLAT : CIwMaterial
  • SHADE_GOURAUD : CIwMaterial
  • SHARED_SOURCE_F : CIwTexture
  • SHARES_TEXELS_F : CIwTexture
  • SKIPPED_MIPMAP_GENERATION : CIwTexture
  • SVEC2 : CIwGxStream
  • SVEC3 : CIwGxStream
  • SW : CIwGxSurface

- t -

  • TYPE_FIXED : CIwGxStream
  • TYPE_FLOAT : CIwGxStream
  • TYPE_INT16 : CIwGxStream
  • TYPE_INT8 : CIwGxStream
  • TYPE_UINT16 : CIwGxStream
  • TYPE_UINT8 : CIwGxStream

- u -

  • UINT16 : CIwGxStream
  • UNKNOWN : CIwURI
  • UNSELECTABLE_F : CIwMenuItem
  • UPDATE_XFORMS_F : CIwAnimBlendSource
  • UPLOAD_ON_LOAD_F : CIwTexture
  • UPLOADED_F : CIwTexture
  • USER_F : CIwModelBlock
  • USES_TRANSPARENCY_F : CIwTexture

- v -

  • VEC2 : CIwGxShaderUniform
  • VEC3 : CIwGxShaderUniform
  • VEC4 : CIwGxShaderUniform


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- a -

  • Activate() : CIwUIAlertDialog , CIwUIButton , CIwUIElement , CIwUIRadioButton , CIwUIScrollableView , CIwUIElementEventHandler , CIwUISlider , CIwUISoftKeyboard , CIwUICheckbox , CIwUIImage , CIwUISoftKeyPosition , CIwUITabBar , CIwUILabel , CIwUITextField
  • Add() : CIwManagedList
  • AddBlock() : CIwModel
  • AddChild() : CIwResGroup , CIwUIElement
  • AddColumn() : CIwUILayoutGrid
  • AddDelegate() : CIwUIElement , CIwUIView
  • AddElement() : CIwUIView , CIwUILayout , CIwUILayoutForm , CIwUILayoutGrid , CIwUILayoutHorizontal , CIwUILayoutVertical
  • AddElementToLayout() : CIwUIView
  • AddEventHandler() : CIwUIController , CIwUIElement
  • AddExt() : CIwModel
  • AddGroup() : CIwResManager
  • AddHandler() : CIwResManager
  • AddHashString() : IIwDecomposable
  • AddLayoutItem() : CIwUILayout , CIwUILayoutForm , CIwUILayoutGrid , CIwUILayoutHorizontal , CIwUILayoutVertical
  • AddMenu() : CIwMenuManager
  • AddMenuOrDestroy() : CIwMenuManager
  • AddProperty() : CIwUIAnimKeyFrame , CIwPropertySet
  • AddPropertySet() : CIwUIStylesheet
  • AddRes() : CIwResGroup , CIwResManager
  • AddRow() : CIwUITable , CIwUILayoutGrid
  • AddTemplate() : CIwResHandler
  • Animate() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIElement , CIwUIImage , CIwUILabel , CIwUISlider , CIwUITabBar , CIwUIRadioButton , CIwUICheckbox , CIwUIAlertDialog , CIwUIButton
  • AnimateDrawableStyle() : CIwUIAnimData
  • AnimateProperty() : CIwUIAnimData
  • append() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • Apply() : CIwResTemplateMTL , CIwResTemplateANIM , CIwResTemplateSKEL , CIwResTemplateGROUP , CIwUISizePolicy , CIwUIPositionPolicy , CIwResTemplate , CIwResTemplateSKIN , CIwResTemplateImage
  • ApplyScale() : CIwAnimSkin , CIwAnimSkel , CIwModelBlock , CIwModelExt , CIwAnim
  • ApplySettings() : CIwResHandler
  • Area() : CIwUIRect
  • Arrange() : CIwUIElement , CIwUILayoutItemContainer
  • ArrangeItem() : CIwUILayoutItem , CIwUILayoutSpacer , CIwUILayoutItemContainer , CIwUILayout
  • Attach() : CIwUILayoutItemContainer , CIwUILayoutSpacer , CIwUILayout , CIwUILayoutItem
  • AttachButtonClickSlot() : CIwUIAlertDialog
  • AttachClickSlot() : CIwUIButton
  • AttachPropertySets() : CIwUIAnimation
  • AttachSignalSlot() : CIwUIElement


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- l -

  • Layout() : CIwUIElement , CIwUIView
  • length() : CIwString< N >
  • Lerp() : CIwFQuat , CIwQuat , CIwSQuat
  • LoadFromFile() : CIwImage , CIwTexture
  • LoadGroup() : CIwResManager
  • LoadGroupFromMemory() : CIwResManager
  • LoadTemp() : CIwGxShaderTechnique
  • LockSize() : CIwArray< X, A, REALLOCATE > , CIwManagedList
  • LookAt() : CIwMat , CIwFMat
  • LookupChildHashed() : CIwUIElement
  • LookupChildNamed() : CIwUIElement
  • LookupSlot() : CIwUIView


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- m -

  • Make() : CIwRect , CIwRect32
  • MakeAlphaPalZero() : CIwImage
  • MakeCurrent() : CIwGxSurface
  • MakeDisplayCurrent() : CIwGxSurface
  • Measure() : CIwUIDrawableImage , CIwUIDrawableText , CIwUIElement , CIwUILayoutItemContainer , IIwUIDrawable , CIwUIScrollableView , CIwUIDrawableBorder
  • MeasureElement() : CIwUIImage , CIwUILabel , CIwUISlider , CIwUITabBar , CIwUIAlertDialog , CIwUIButton , CIwUICheckbox
  • MeasureItem() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayoutSpacer
  • MemoryUsage() : CIwArray< X, A, REALLOCATE >
  • Minus() : CIwMenuItem
  • ModulateColour() : CIwUIGraphics
  • MountGroup() : CIwResManager
  • MoveCharacters() : CIwGxFontPreparedData
  • MoveElement() : CIwUILayout
  • MoveFocus() : CIwUIFocusHandlerTab , CIwUIFocusHandler2D , CIwUIFocusHandler , CIwUIView


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- n -

  • Normalise() : CIwFMat , CIwFMat2D , CIwFVec3 , CIwSVec2 , CIwSVec3 , CIwFVec4 , CIwSVec4 , CIwVec2 , CIwFVec2 , CIwMat , CIwVec3 , CIwVec4 , CIwMat2D
  • NormaliseInPlace() : CIwSQuat , CIwFQuat , CIwQuat
  • NormaliseSafe() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • NormaliseSlow() : CIwVec2 , CIwSVec4 , CIwVec3 , CIwVec4 , CIwSVec3 , CIwSVec2
  • Notify() : CIwUIController
  • NotifyProgress() : IIwUIAnimatorObserver
  • NotifyPropertyChanged() : CIwPropertySetBinding , IIwPropertySetObserver
  • NotifyStopped() : IIwUIAnimatorObserver


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- o -

  • OnPropertyChanged() : CIwUIAlertDialog , CIwUIButton , CIwUIElement , CIwUISlider , CIwUISoftKeyPosition , CIwUIImage , CIwUITabBar , CIwUITextField , CIwUICheckbox , CIwUILabel , CIwUIRadioButton
  • OnSizeChanged() : CIwUILabel , CIwUIRadioButton , CIwUISlider , CIwUITextField , CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIImage
  • OpenAttribute() : CIwTextDecomposer
  • OpenScope() : CIwTextDecomposer
  • operator *() : CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwColour , CIwSVec4 , CIwVec2 , CIwFMat , CIwVec2 , CIwVec3 , CIwFMat2D , CIwVec3 , CIwVec4 , CIwFQuat , CIwVec4 , CIwUIColour , CIwFQuat , CIwUIRect , CIwFVec2 , CIwFVec3 , CIwFVec4
  • operator *=() : CIwMat2D , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIColour , CIwColour , CIwFMat , CIwFMat2D , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D
  • operator CIwFMat() : CIwFQuat
  • operator CIwMat() : CIwQuat , CIwSQuat
  • operator s3eFile *() : CIwAutoFile
  • operator!=() : CIwColour , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIRect
  • operator+() : CIwColour , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • operator+=() : CIwVec3 , CIwVec4 , CIwColour , CIwFMat , CIwFMat2D , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwMat , CIwMat2D , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2
  • operator-() : CIwFQuat , CIwFVec2 , CIwFVec3 , CIwSVec2 , CIwFVec3 , CIwFVec4 , CIwPlane , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwVec3
  • operator-=() : CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwSVec2 , CIwColour
  • operator/() : CIwFVec2 , CIwFVec3 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec3 , CIwVec4 , CIwVec2 , CIwFVec4
  • operator<<() : CIwQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwUIRect , CIwSQuat
  • operator<<=() : CIwMat , CIwVec2 , CIwVec4 , CIwVec3 , CIwMat2D , CIwSVec2 , CIwSVec3 , CIwSVec4
  • operator=() : CIwSVec4 , CIwURI , CIwQuat , CIwSQuat , CIwVec2 , CIwFVec4 , CIwArray< X, A, REALLOCATE > , CIwFQuat , CIwFVec2 , CIwUIColour , CIwColour , CIwSVec3 , CIwVec4 , CIwUIRect , CIwFVec3 , CIwSVec2 , CIwVec3
  • operator==() : CIwVec2 , CIwSVec3 , CIwSQuat , CIwSVec2 , CIwVec3 , CIwVec4 , CIwFMat , CIwSVec4 , CIwMat , CIwColour , CIwFVec3 , CIwFMat2D , CIwFVec4 , CIwQuat , CIwMat2D , CIwFQuat , CIwUIRect , CIwFVec2 , CIwColour , CIwPlane
  • operator>>() : CIwQuat , CIwSVec2 , CIwUIRect , CIwVec4 , CIwSVec4 , CIwVec3 , CIwSVec3 , CIwSQuat , CIwVec2
  • operator>>=() : CIwVec2 , CIwMat2D , CIwVec3 , CIwMat , CIwSVec2 , CIwVec4 , CIwSVec4 , CIwSVec3
  • operator[]() : CIwFVec2 , CIwArray< X, A, REALLOCATE > , CIwVec2 , CIwVec4 , CIwFVec3 , CIwVec4 , CIwSVec3 , CIwFVec2 , CIwSVec2 , CIwFVec3 , CIwSVec3 , CIwManagedList , CIwFVec4 , CIwSVec4 , CIwSVec2 , CIwFVec4 , CIwVec2 , CIwVec3
  • operator^() : CIwVec3 , CIwSVec3 , CIwFVec2 , CIwFVec4 , CIwSVec2 , CIwVec4 , CIwVec2 , CIwFVec3 , CIwSVec4
  • optimise_capacity() : CIwArray< X, A, REALLOCATE >
  • OptimizeCapacity() : CIwManagedList


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- z -

  • Zero() : CIwFMat , CIwMat2D , CIwMat , CIwFMat2D


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- ~ -

  • ~CIwAutoFile() : CIwAutoFile
  • ~CIwHTTP() : CIwHTTP
  • ~CIwImage() : CIwImage
  • ~CIwMaterial() : CIwMaterial
  • ~CIwModel() : CIwModel
  • ~CIwTextParserITX() : CIwTextParserITX
  • ~CIwTexture() : CIwTexture
  • ~CIwURI() : CIwURI


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- b -

  • Back() : CIwMenuItem
  • back() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • begin() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • BoundVec() : CIwBBoxT< V > , CIwFBBox
  • BoundVecs() : CIwBBoxT< V > , CIwFBBox , CIwFSphere , CIwSphereT< V, R >
  • BroadcastEvent() : CIwUIController
  • Build() : CIwResHandlerGEO , CIwResHandlerSKIN , CIwResHandlerITX , CIwResHandlerSKEL , CIwResHandlerImage , CIwResHandlerGROUP , CIwResHandler , CIwResHandlerANIM , CIwResHandlerMTL
  • BuildHierarchy() : CIwUIStyleManager
  • BuildPropertySetHierarchy() : CIwUIStylesheet


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- c -

  • c_str() : CIwString< N >
  • Cancel() : CIwHTTP
  • CanResize() : CIwArray< X, A, REALLOCATE >
  • capacity() : CIwArray< X, A, REALLOCATE > , CIwString< N >
  • ChangePalette() : CIwTexture
  • ChangeTexels() : CIwTexture
  • ChooseFocus() : CIwUIView
  • CIwArray() : CIwArray< X, A, REALLOCATE >
  • CIwAutoFile() : CIwAutoFile
  • CIwBBoxT() : CIwBBoxT< V >
  • CIwFMat() : CIwFMat
  • CIwFMat2D() : CIwFMat2D
  • CIwFQuat() : CIwFQuat
  • CIwFVec2() : CIwFVec2
  • CIwFVec3() : CIwFVec3
  • CIwFVec4() : CIwFVec4
  • CIwGxStream() : CIwGxStream
  • CIwHTTP() : CIwHTTP
  • CIwImage() : CIwImage
  • CIwMat() : CIwMat
  • CIwMat2D() : CIwMat2D
  • CIwMaterial() : CIwMaterial
  • CIwMenuItemDisplayBool() : CIwMenuItemDisplayBool
  • CIwMenuItemDisplayFloat() : CIwMenuItemDisplayFloat
  • CIwMenuItemDisplayInt16() : CIwMenuItemDisplayInt16
  • CIwMenuItemDisplayInt32() : CIwMenuItemDisplayInt32
  • CIwMenuItemDisplayInt8() : CIwMenuItemDisplayInt8
  • CIwMenuItemDisplayUInt16() : CIwMenuItemDisplayUInt16
  • CIwMenuItemDisplayUInt32() : CIwMenuItemDisplayUInt32
  • CIwMenuItemDisplayUInt8() : CIwMenuItemDisplayUInt8
  • CIwMenuItemEditAngle() : CIwMenuItemEditAngle
  • CIwMenuItemEditBool() : CIwMenuItemEditBool
  • CIwMenuItemEditEnum() : CIwMenuItemEditEnum
  • CIwMenuItemEditFixed() : CIwMenuItemEditFixed
  • CIwMenuItemEditFlags() : CIwMenuItemEditFlags
  • CIwMenuItemEditFloat() : CIwMenuItemEditFloat
  • CIwMenuItemEditInt16() : CIwMenuItemEditInt16
  • CIwMenuItemEditInt32() : CIwMenuItemEditInt32
  • CIwMenuItemEditInt8() : CIwMenuItemEditInt8
  • CIwMenuItemEditUInt16() : CIwMenuItemEditUInt16
  • CIwMenuItemEditUInt32() : CIwMenuItemEditUInt32
  • CIwMenuItemEditUInt8() : CIwMenuItemEditUInt8
  • CIwMenuItemString() : CIwMenuItemString
  • CIwMenuItemTitle() : CIwMenuItemTitle
  • CIwModel() : CIwModel
  • CIwModelBlock() : CIwModelBlock
  • CIwModelExt() : CIwModelExt
  • CIwPlane() : CIwPlane
  • CIwProperty() : CIwProperty< Type >
  • CIwQuat() : CIwQuat
  • CIwRect() : CIwRect
  • CIwRect32() : CIwRect32
  • CIwResGroup() : CIwResGroup
  • CIwResHandler() : CIwResHandler
  • CIwSphereT() : CIwSphereT< V, R >
  • CIwSQuat() : CIwSQuat
  • CIwSVec2() : CIwSVec2
  • CIwSVec3() : CIwSVec3
  • CIwSVec4() : CIwSVec4
  • CIwTextParserITX() : CIwTextParserITX
  • CIwTexture() : CIwTexture
  • CIwUIDrawableBorder() : CIwUIDrawableBorder
  • CIwUIDrawableImage() : CIwUIDrawableImage
  • CIwUIDrawableText() : CIwUIDrawableText
  • CIwUIGraphics() : CIwUIGraphics
  • CIwURI() : CIwURI
  • CIwVec2() : CIwVec2
  • CIwVec3() : CIwVec3
  • CIwVec4() : CIwVec4
  • ClassFactory() : CIwProperty< Type >
  • clear() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • Clear() : CIwManagedList , CIwGxFontPreparedData , CIwAnimBlendSource
  • clear_optimised() : CIwArray< X, A, REALLOCATE >
  • ClearAndFree() : CIwManagedList
  • ClearFlags() : CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer , CIwModel
  • ClearSubAnim() : CIwAnimPlayer
  • ClearTable() : CIwUITable
  • ClipToFrustrum() : CIwSphereT< V, R >
  • ClipToPlane() : CIwSphereT< V, R >
  • Clone() : CIwUIScrollableView , CIwProperty< Type > , CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIElement , CIwUISoftKeyboard , CIwUITextField , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUIFocusHandler2D , CIwPropertySetBinding , CIwUIFocusHandlerTab , CIwUITabBar , CIwUIElementEventHandler , CIwUISlider , CIwUIRadioButton , CIwUILayoutSpacer , CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayoutItem , CIwUIRect , CIwUISoftKeyPosition , CIwUILabel , CIwPropertyBase , CIwPropertySet , CIwUIFocusHandler , CIwUIImage , CIwUIElement
  • CloneWithNewMaterials() : CIwModel
  • CloseAttribute() : CIwTextDecomposer
  • CloseScope() : CIwTextDecomposer
  • ColumnX() : CIwFMat2D , CIwMat , CIwFMat , CIwMat2D
  • ColumnY() : CIwFMat , CIwMat , CIwMat2D , CIwFMat2D
  • ColumnZ() : CIwFMat , CIwMat
  • Combine() : CIwFSphere
  • ComposeTransform() : CIwUIGraphics
  • ConstructFullPathname() : CIwResHandler
  • ContainerFactory() : CIwUILayout
  • contains() : CIwArray< X, A, REALLOCATE >
  • Contains() : CIwManagedList , CIwUIRect
  • ContainsProperty() : CIwUIAnimKeyFrame
  • ContainsVec() : CIwSphereT< V, R > , CIwFBBox , CIwBBoxT< V >
  • ContentExpected() : CIwHTTP
  • ContentFinished() : CIwHTTP
  • ContentLength() : CIwHTTP
  • ContentReceived() : CIwHTTP
  • ConvertToCIwFMat() : CIwMat
  • ConvertToCIwFMat2D() : CIwMat2D
  • ConvertToCIwMat() : CIwFMat
  • ConvertToCIwMat2D() : CIwFMat2D
  • ConvertToImage() : CIwImage
  • Copy() : CIwResTemplateANIM , CIwProperty< Type > , CIwPropertyBase , CIwResTemplateGROUP , CIwResTemplateMTL , CIwResTemplate , CIwMaterial , CIwResTemplateSKEL , CIwResTemplateSKIN , CIwResTemplateImage
  • CopyFromBuffer() : CIwTexture
  • CopyFromImage() : CIwTexture
  • CopyList() : CIwManagedList
  • CopyRot() : CIwFMat , CIwMat , CIwFMat2D , CIwMat2D
  • CopyTrans() : CIwFMat , CIwMat2D , CIwFMat2D , CIwMat
  • CountColours() : CIwImage
  • CreateAnim() : CIwMaterial
  • CreateDestination() : CIwUIAnimDataLocator
  • CreateDrawable() : CIwUIElement
  • CreateFromResource() : CIwUIElement
  • CreateProperty() : CIwPropertyDefine
  • CreateSoftKeyboard() : CIwUITextInput
  • CreateSurface() : CIwGxSurface
  • Cross() : CIwFVec3 , CIwVec3 , CIwSVec3


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- d -

  • data() : CIwArray< X, A, REALLOCATE >
  • DebugAddMenuItems() : CIwMaterial , CIwModel , CIwAnim , CIwAnimPlayer , CIwModelBlock , CIwAnimSkel , CIwAnimSkin , CIwManaged , CIwModelExt , CIwModelExtSelSetFace
  • DebugDrawRect() : CIwUIGraphics
  • DebugGetName() : CIwManaged , CIwUIStyle
  • DebugGetPropertyDefine() : CIwPropertyBase
  • DebugRender() : CIwManaged , CIwModel , CIwModelExtPos , CIwModelExtSphere , CIwModelExtSelSetVert , CIwModelExtSelSetEdge , CIwModelExtSelSetFace , CIwAnimPlayer , CIwUIElement , CIwUIRect , CIwUIView
  • DebugRenderChildren() : CIwUIElement
  • DebugRenderElement() : CIwUILabel
  • Decompose() : CIwUIRect , CIwProperty< Type > , CIwPropertyBase
  • DecomposeAttributes() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutGrid , CIwUILayoutItem , CIwUIPropertySet , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding
  • DecomposeChild() : CIwTextDecomposer
  • DecomposeChildren() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayout , CIwUILayoutGrid , CIwUILayoutItem , CIwUILayoutItemContainer , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding
  • DecomposeClose() : IIwDecomposable , CIwPropertySet , CIwPropertySetBinding , CIwUIElementEventHandler , CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIFocusHandler , CIwUILayoutItem , CIwUILayoutItemContainer
  • DecomposeOpen() : CIwUIAnimKeyFrame , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutItemContainer , IIwDecomposable , CIwPropertySet , CIwPropertySetBinding , CIwUILayoutItem
  • DecomposeToFile() : CIwTextDecomposer
  • DecrementCurrent() : CIwUIAnimDataLocator
  • Delete() : CIwManagedList
  • DestroyChildren() : CIwUIElement
  • DestroyDelegates() : CIwUIView , CIwUIElement
  • DestroyElements() : CIwUIView
  • DestroyGroup() : CIwResManager
  • DestroyMenu() : CIwMenuManager
  • DestroyMenus() : CIwMenuManager
  • DetachButtonClickSlot() : CIwUIAlertDialog
  • DetachClickSlot() : CIwUIButton
  • DetachSignalSlot() : CIwUIElement
  • Dot() : CIwSVec3 , CIwVec2 , CIwFVec4 , CIwFVec2 , CIwVec3 , CIwFVec3 , CIwVec4 , CIwSVec2 , CIwSVec4
  • DoTextEntry() : CIwUITextInput
  • Draw() : CIwUIDrawableImage , CIwUIDrawableBorder , CIwUIDrawableText , IIwUIDrawable
  • DrawImage() : CIwUIGraphics
  • DrawText() : CIwUIGraphics


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- e -

  • element_at() : CIwList< X >
  • empty() : CIwArray< X, A, REALLOCATE >
  • end() : CIwList< X > , CIwArray< X, A, REALLOCATE >
  • Enter() : CIwMenuItem
  • erase() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • Erase() : CIwManagedList
  • erase() : CIwList< X > , CIwArray< X, A, REALLOCATE >
  • erase_fast() : CIwArray< X, A, REALLOCATE >
  • EraseFast() : CIwManagedList
  • Escape() : CIwUriEscape
  • Exit() : CIwMenuItem
  • ExposeData() : CIwPropertyBase , CIwProperty< Type >
  • ExposePropertySet() : CIwUILayoutItem , CIwUIAnimKeyFrame
  • ExtractSubTexture() : CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- f -

  • FieldStripQuotes() : CIwTextParserITX
  • FilterEvent() : CIwUIController , IIwUIEventHandler , CIwUIElementEventHandler , CIwUIElement , CIwUISlider , CIwUITextInput
  • FilterString() : CIwTextParserITX
  • FilterStringGetEnum() : CIwTextParserITX
  • FilterStringGetEnumAsserted() : CIwTextParserITX
  • FilterStringGetFlags() : CIwTextParserITX
  • FilterStringResetFlags() : CIwTextParserITX
  • FilterStringSetFlags() : CIwTextParserITX
  • Finalise() : CIwResGroup
  • find() : CIwArray< X, A, REALLOCATE >
  • Find() : CIwManagedList
  • find_and_remove() : CIwArray< X, A, REALLOCATE > , CIwList< X >
  • find_and_remove_fast() : CIwArray< X, A, REALLOCATE >
  • FindWantsFocus() : CIwUITabBar , CIwUIAlertDialog , CIwUIFocusHandler , CIwUIElement
  • FixedBufferAvailable() : CIwImage
  • FixedBufferCheckOverflow() : CIwImage
  • FixedBufferFree() : CIwImage
  • FixedBufferSetSize() : CIwImage
  • FormatColour() : CIwImage
  • Free() : CIwGxStream
  • front() : CIwArray< X, A, REALLOCATE > , CIwList< X >


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- g -

  • Get() : CIwColour , CIwHTTP , CIwProperty< Type >
  • GetAlignmentH() : CIwUILayoutItemContainer
  • GetAlignmentV() : CIwUILayoutItemContainer
  • GetAll() : CIwURI
  • GetAlphaMode() : CIwMaterial
  • GetAlphaTestMode() : CIwMaterial
  • GetAlphaTestRefVal() : CIwMaterial
  • GetAnim() : CIwAnimBlendSource
  • GetAnimationTime() : CIwUIAnimator
  • GetAnimCelH() : CIwMaterial
  • GetAnimCelID() : CIwMaterial
  • GetAnimCelNum() : CIwMaterial
  • GetAnimCelNumU() : CIwMaterial
  • GetAnimCelPeriod() : CIwMaterial
  • GetAnimCelW() : CIwMaterial
  • GetAnimOfsU() : CIwMaterial
  • GetAnimOfsV() : CIwMaterial
  • GetArraySize() : CIwGxShaderUniform
  • GetAtlasMaterial() : CIwResManager
  • GetBase() : CIwUIAnimDataLocator
  • GetBegin() : CIwManagedList , CIwPropertySet
  • GetBinding() : CIwPropertySet
  • GetBiTangents() : CIwModel
  • GetBitDepth() : CIwImage
  • GetBlendMode() : CIwMaterial
  • GetBlendParam() : CIwAnimBlendSource
  • GetBlockNamed() : CIwModel
  • GetBoneFromID() : CIwAnimPlayer , CIwAnimSkel
  • GetBoneHashed() : CIwAnimPlayer , CIwAnimSkel
  • GetBoneList() : CIwAnimSkel
  • GetBoneNamed() : CIwAnimPlayer , CIwAnimSkel
  • GetBorder() : CIwUILayoutItemContainer
  • GetBounds() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText
  • GetBSphere() : CIwModel
  • GetBuildStyleCurrName() : CIwResManager
  • GetByteDepth() : CIwImage
  • GetByteWidth() : CIwImage
  • GetCachedArrangeArea() : CIwUILayoutItemContainer
  • GetCachedArrangePos() : CIwUILayoutItemContainer
  • GetCapacity() : CIwManagedList
  • GetCaption() : CIwUILabel
  • GetCentre() : CIwBBoxT< V > , CIwFBBox
  • GetCharacterArea() : CIwGxFontPreparedData , CIwUIDrawableText
  • GetChecked() : CIwUICheckbox
  • GetChild() : CIwUIElement
  • GetChildBounds() : CIwUIElement
  • GetChildHashed() : CIwUIElement , CIwUIView
  • GetChildNamed() : CIwUIView , CIwUIElement
  • GetChildren() : CIwResGroup
  • GetClamping() : CIwMaterial , CIwTexture
  • GetClientHeight() : CIwGxSurface
  • GetClientUVExtent() : CIwGxSurface
  • GetClientWidth() : CIwGxSurface
  • GetCloneList() : CIwUIElement , CIwUIView
  • GetColAmbient() : CIwMaterial
  • GetColDiffuse() : CIwMaterial
  • GetColEmissive() : CIwMaterial
  • GetColour() : CIwGxStream , IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIGraphics
  • GetCols() : CIwModel
  • GetColSpecular() : CIwMaterial
  • GetCullMode() : CIwMaterial
  • GetCurrent() : CIwUIAnimDataLocator
  • GetCurrentGroup() : CIwResManager
  • GetCursorPosition() : CIwUITextField , CIwUITextInput
  • GetData() : CIwGxStream
  • GetDataType() : CIwProperty< Type > , CIwPropertyBase
  • GetDataTypeHash() : CIwPropertyDefine
  • GetDataTypeString() : CIwProperty< Type > , CIwPropertyBase
  • GetDelegate() : CIwUIElement
  • GetDepth() : CIwTexture
  • GetDistSqFromLine() : CIwSphereT< V, R >
  • GetDrawColour() : CIwUIGraphics
  • GetDuration() : CIwAnim
  • GetEffectPreset() : CIwMaterial
  • GetElement() : CIwUIElementEventHandler , CIwUIView
  • GetElementBounds() : CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIImage , CIwUILabel , CIwUIRadioButton , CIwUISlider
  • GetElementItem() : CIwUIElementItem
  • GetElementSize() : CIwGxShaderUniform
  • GetElementType() : CIwGxShaderUniform
  • GetEnd() : CIwManagedList , CIwPropertySet
  • GetExt() : CIwResHandler
  • GetExtHashed() : CIwModel
  • GetExtNamed() : CIwModel
  • GetFiltering() : CIwMaterial , CIwTexture
  • GetFlags() : CIwTexture , CIwImage , CIwModel , CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer
  • GetFocus() : CIwUIView , CIwUIElement
  • GetFocusHandler() : CIwUIElement
  • GetFormat() : CIwTexture , CIwImage
  • GetFormatData() : CIwImage
  • GetFormatHW() : CIwTexture
  • GetFormatSW() : CIwTexture
  • GetFormSize() : CIwUILayoutForm
  • GetFrame() : CIwUIElement
  • GetFrameBounds() : CIwUIGraphics
  • GetGlobalPropertySet() : CIwUIStyleManager
  • GetGroup() : CIwResManager
  • GetGroupHashed() : CIwResManager
  • GetGroupNamed() : CIwResManager
  • GetHandle() : CIwUIAnimator
  • GetHandler() : CIwResManager
  • GetHashString() : IIwDecomposable
  • GetHeader() : CIwHTTP
  • GetHeight() : CIwGxSurface , CIwTexture , CIwImage , CIwGxFontPreparedData , CIw2DImage , CIw2DFont
  • GetHost() : CIwURI
  • GetImplementation() : CIwGxSurface
  • GetInverse() : CIwFMat2D , CIwMat2D
  • GetItem() : CIwUILayoutItemContainer
  • GetItemSize() : CIwModelBlock
  • GetKeyFrame() : CIwAnim , CIwUIAnimation , CIwUIAnimator
  • GetKeyFrameData() : CIwUIAnimator
  • GetKeyFrameTime() : CIwUIAnimator
  • GetLastSearchGroup() : CIwResManager
  • GetLayout() : CIwUIElement
  • GetLayoutItem() : CIwUILayout
  • GetLayoutItemIndex() : CIwUILayout
  • GetLayoutItems() : CIwUILayout
  • GetLength() : CIwGxStream , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSafe() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSquared() : CIwFQuat , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwQuat , CIwSQuat , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSquaredSafe() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLengthSquaredUnshifted() : CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetLineEnd() : CIwGxFontPreparedData
  • GetLineStart() : CIwGxFontPreparedData
  • GetListHashed() : CIwResGroup
  • GetListNamed() : CIwResGroup
  • GetMat() : CIwAnimBone
  • GetMatOfs() : CIwAnimPlayer
  • GetMatOfsFinal() : CIwAnimPlayer
  • GetMatOfsInitial() : CIwAnimPlayer
  • GetMemSize() : CIwGxStream
  • GetMenu() : CIwMenuItem
  • GetMergeGeom() : CIwMaterial
  • GetMipMapping() : CIwTexture
  • GetMode() : CIwResManager
  • GetModel() : CIwAnimSkin
  • GetModifiable() : CIwTexture
  • GetModulateColour() : CIwUIGraphics
  • GetModulateMode() : CIwMaterial
  • GetModulatesColour() : CIwUIElement
  • GetNext() : CIwUIAnimDataLocator
  • GetNextCharacterPosition() : CIwGxFontPreparedData
  • GetNormalised() : CIwSVec2 , CIwFVec2 , CIwFVec3 , CIwFVec4 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4
  • GetNormalisedSafe() : CIwSVec4 , CIwSVec2 , CIwSVec3 , CIwVec2 , CIwVec3 , CIwVec4
  • GetNorms() : CIwModel
  • GetNumBones() : CIwAnim , CIwAnimSkel
  • GetNumChars() : CIwGxFontPreparedData
  • GetNumChildren() : CIwUIElement , CIwAnimBone
  • GetNumChunks() : CIwModel
  • GetNumCols() : CIwModel
  • GetNumColumns() : CIwUILayoutGrid
  • GetNumElements() : CIwUIView
  • GetNumGroups() : CIwResManager
  • GetNumKeyFrames() : CIwAnim , CIwUIAnimator , CIwUIAnimation
  • GetNumLayoutItems() : CIwUILayout
  • GetNumLines() : CIwGxFontPreparedData
  • GetNumNorms() : CIwModel
  • GetNumProperties() : CIwPropertySet
  • GetNumRadioButtons() : CIwUITabBar
  • GetNumRows() : CIwUILayoutGrid
  • GetNumUVs() : CIwModel
  • GetNumVerts() : CIwModel
  • GetNumVertsUnique() : CIwModel
  • GetObject() : CIwTextParserITX , CIwTextDecomposer
  • GetObjHashed() : CIwManagedList
  • GetObjHashedNextIt() : CIwManagedList
  • GetObjNamed() : CIwManagedList
  • GetObserver() : CIwUIAnimator
  • GetOffset() : CIwGxStream
  • GetOverflow() : CIwAnimBlendSource
  • GetOwner() : CIwResGroup
  • GetPalette() : CIwTexture , CIwImage , CIwTexture
  • GetPaletteCacheRGBs() : CIwTexture
  • GetPaletteMemSize() : CIwImage , CIwTexture
  • GetPaletteNumEntries() : CIwTexture
  • GetPaletteSize() : CIwImage
  • GetParam() : CIwGxShaderTechnique
  • GetParent() : CIwUIStylesheet , CIwAnimBone , CIwPropertySet , CIwUIPropertySet , CIwUIElement
  • GetParentElement() : CIwUILayoutItem , CIwUILayout
  • GetParentItem() : CIwUILayoutItem
  • GetPerpDist() : CIwPlane
  • GetPitch() : CIwImage , CIwTexture
  • GetPort() : CIwURI
  • GetPos() : CIwAnimBone , CIwUIElement
  • GetPosAbsolute() : CIwUIElement
  • GetPosition() : CIwUIDrawableText , CIwUIDrawableImage , CIwUIDrawableBorder , IIwUIDrawable
  • GetProgress() : CIwUIProgressBar
  • GetProperty() : CIwUIElement , CIwPropertySet , CIwUILayoutItem , CIwPropertySetBinding
  • GetPropertyByHash() : CIwPropertySet
  • GetPropertyByIndex() : CIwPropertySet
  • GetPropertyDefineID() : CIwPropertyBase
  • GetPropertySet() : CIwUIAnimKeyFrame , CIwUILayoutItem , CIwUIStyleManager , CIwUIStylesheet
  • GetPropertySetBinding() : CIwUIElement
  • GetProportion() : CIwUISlider
  • GetProtocol() : CIwURI
  • GetRadius() : CIwSphereT< V, R >
  • GetRenderSlot() : CIwUIElement
  • GetResHashed() : CIwResGroup , CIwResManager , CIwResGroup
  • GetResName() : CIwResTemplate
  • GetResNamed() : CIwResGroup , CIwResManager
  • GetResponseCode() : CIwHTTP
  • GetResType() : CIwResHandler , CIwResManager
  • GetRot() : CIwAnimBone
  • GetRotationAngle() : CIwFQuat , CIwQuat , CIwSQuat
  • GetRotationAxis() : CIwQuat , CIwFQuat , CIwSQuat
  • GetSelected() : CIwUIRadioButton , CIwUITabBar
  • GetSettings() : CIwResHandler
  • GetShadeMode() : CIwMaterial
  • GetSize() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIElement , CIwManagedList , CIwUIDrawableText , CIwUIDrawableImage
  • GetSizeHint() : CIwUIElement
  • GetSizeMax() : CIwUIElement
  • GetSizeMin() : CIwUIElement
  • GetSizeToContent() : CIwUIElement
  • GetSizeToSpace() : CIwUILayout
  • GetSkel() : CIwAnim , CIwAnimSkin , CIwAnimPlayer
  • GetSkelID() : CIwAnimBone
  • GetSourceCurr() : CIwAnimPlayer
  • GetSourcePrev() : CIwAnimPlayer
  • GetSourceSub() : CIwAnimPlayer
  • GetSpecularPower() : CIwMaterial
  • GetSpeed() : CIwAnimBlendSource
  • GetStatus() : CIwHTTP
  • GetStride() : CIwGxStream
  • GetStyle() : CIwUIElement
  • GetStylesheet() : CIwUIStyleManager
  • GetSurfaceInfo() : CIwGxSurface
  • GetSVec2() : CIwGxStream
  • GetSVec3() : CIwGxStream
  • GetTail() : CIwURI
  • GetTangents() : CIwModel
  • GetTarget() : CIwUIAnimator
  • GetTemplate() : CIwResHandler
  • GetTemplateNamed() : CIwResHandler
  • GetTexelBitDepth() : CIwImage
  • GetTexels() : CIwImage , CIwTexture
  • GetTexelsMemSize() : CIwTexture , CIwImage
  • GetText() : CIwUILabel
  • GetTextSize() : CIwUIDrawableText
  • GetTexture() : CIwGxSurface , CIwMaterial
  • GetTime() : CIwAnimBlendSource , CIwUIAnimator , CIwUIAnimKeyFrame , CIwAnimPlayer
  • GetTop() : CIwManagedList
  • GetTotalSize() : CIwModelBlock
  • GetTrans() : CIwMat , CIwFMat , CIwSphereT< V, R > , CIwMat2D , CIwFMat2D
  • GetTransform() : CIwUIGraphics , CIwUIElement
  • GetTranspose() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • GetType() : CIwGxStream
  • GetUInt16() : CIwGxStream
  • GetUserFlags() : CIwMaterial
  • GetUVOfs() : CIwMaterial
  • GetUVs() : CIwModel
  • GetValue() : CIwUISlider
  • GetVerts() : CIwModel
  • GetViewMat() : CIwUIGraphics
  • GetWidth() : CIwGxFontPreparedData , CIwImage , CIwTexture , CIw2DImage , CIwGxSurface
  • GetWrapMode() : CIwUIFocusHandler
  • GetZDepthFixed() : CIwModel
  • GetZDepthOfs() : CIwModel , CIwMaterial
  • GetZDepthOfsHW() : CIwMaterial


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- h -

  • HandleEvent() : CIwManaged , CIwUIController , IIwUIEventHandler , CIwUITabBar , CIwUITextField , CIwUIElementEventHandler , CIwUITextInput , CIwUIElement , CIwUIRadioButton , CIwUISoftKeyboard
  • HandleEventClick() : CIwUIButton , CIwUICheckbox , CIwUIElement , CIwUISlider , CIwUITextField
  • HandleEventFocus() : CIwUIButton , CIwUIElement
  • HandleEventKey() : CIwUIButton , CIwUICheckbox , CIwUIElement , CIwUISlider , CIwUITabBar , CIwUITextField
  • HandleEventLayout() : CIwUIElement
  • HandleEventPointerEnter() : CIwUIButton , CIwUIElement
  • HandleEventPointerLeave() : CIwUIButton , CIwUIElement , CIwUITextField
  • HandleEventPointerMove() : CIwUISlider , CIwUIElement
  • HandlesFocus() : CIwUIAlertDialog , CIwUIElement , CIwUITabBar
  • HasAlpha() : CIwImage , CIwTexture
  • HasAlphaChannel() : CIwGxSurface
  • HasFocus() : CIwMenuManager , CIwUIElement
  • HasIdentityAmbient() : CIwMaterial
  • HasIdentityCols() : CIwMaterial
  • HasIdentityDiffuse() : CIwMaterial
  • HasIdentityEmissive() : CIwMaterial
  • HasPointerCapture() : CIwUIController


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- i -

  • IncrementNext() : CIwUIAnimDataLocator
  • InFocusChain() : CIwUIView
  • Insert() : CIwManagedList
  • insert_slow() : CIwArray< X, A, REALLOCATE >
  • InsertElement() : CIwUILayout
  • InsertIntoLayout() : CIwUILayout
  • InsertIntoLayoutItem() : CIwUILayout
  • InsertItem() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • InsertOverLayoutItem() : CIwUILayout
  • Interpolate() : CIwUIAnimDataType< Type >
  • InterpolatePos() : CIwMat , CIwMat2D , CIwFMat , CIwFMat2D
  • InterpolateRot() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • InterpRot() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • InterpTrans() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • Intersect() : CIwUIView , CIwUIElement
  • IntersectElement() : CIwUIButton , CIwUICheckbox , CIwUIRadioButton , CIwUISlider , CIwUITextField
  • IntersectFrame() : CIwUIGraphics
  • Intersection() : CIwUIRect
  • Intersects() : IIwUIDrawable , CIwUIDrawableBorder , CIwUIDrawableImage , CIwUIDrawableText , CIwUIRect
  • IntersectsLine() : CIwSphereT< V, R >
  • InvalidateLayout() : CIwUIElement , CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • IsActive() : CIwUIElement
  • IsAncestor() : CIwUIElement
  • IsAnim() : CIwMaterial
  • IsAnimPaused() : CIwMaterial
  • IsAnimPlaying() : CIwUIAnimManager
  • IsAttached() : CIwUILayout
  • IsBeingEdited() : CIwUITextInput
  • IsChildElement() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer
  • IsClipped() : CIwUIElement
  • IsCloned() : CIwModel
  • IsCurrent() : CIwUIStylesheet
  • IsCurrentAnimComplete() : CIwAnimPlayer
  • IsCurrentBlendComplete() : CIwAnimPlayer
  • isDataType() : CIwProperty< Type > , CIwPropertyBase
  • isDefineMatch() : CIwPropertyBase
  • IsDescendant() : CIwUIElement
  • IsEmpty() : CIwUIRect
  • IsEnabled() : CIwGxShaderTechnique
  • IsEquivalent() : CIwMaterial
  • IsFilteringEvent() : CIwUIController
  • IsFocusable() : CIwUIView
  • IsFrameEmpty() : CIwUIGraphics
  • IsHandlingEvent() : CIwUIController
  • IsIdentity() : CIwFMat , CIwMat , CIwMat2D , CIwFMat2D
  • IsInvisible() : CIwMaterial
  • IsLayoutInvalid() : CIwUIElement , CIwUILayout
  • IsNormalised() : CIwVec2 , CIwFVec2 , CIwFVec3 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec3 , CIwVec4 , CIwFVec4
  • IsRotIdentity() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • IsRotSame() : CIwMat2D , CIwFMat , CIwMat , CIwFMat2D
  • IsRotZero() : CIwMat2D , CIwMat , CIwFMat , CIwFMat2D
  • IsScrollingRequired() : CIwUIScrollableView
  • IsShared() : CIwResGroup
  • IsTransIdentity() : CIwMat , CIwFMat , CIwMat2D , CIwFMat2D
  • IsTransSame() : CIwMat , CIwMat2D , CIwFMat2D , CIwFMat
  • IsTransZero() : CIwMat , CIwFMat , CIwFMat2D , CIwMat2D
  • IsUpdatable() : CIwUIElement
  • IsValid() : CIwGxSurface
  • IsVisible() : CIwUIElement
  • IsWithinLayout() : CIwUIElement
  • IsZero() : CIwSVec4 , CIwMat2D , CIwVec4 , CIwFVec2 , CIwVec2 , CIwFVec4 , CIwFMat2D , CIwVec3 , CIwFMat , CIwMat , CIwSVec3 , CIwSVec2 , CIwFVec3


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- p -

  • Parse() : CIwUIColour , CIwUIRect , CIwPropertyBase , CIwProperty< Type >
  • ParseAttribute() : CIwManaged , CIwResTemplateANIM , CIwResTemplateSKEL , CIwModelExt , CIwResTemplateSKIN , CIwResTemplate , CIwGxShaderTechnique , CIwModelExtPos , CIwResTemplateGROUP , CIwResTemplateImage , CIwModelExtSphere , CIwUIAnimKeyFrame , CIwUIElement , CIwMaterial , CIwModelExtSelSetVert , CIwUILayout , CIwUILayoutGrid , CIwModelExtSelSetEdge , CIwUILayoutItem , CIwUIPropertySet , CIwResTemplateMTL , CIwModelExtSelSetFace , CIwPropertyDefine , CIwPropertySet , CIwResTemplateGEO
  • ParseClose() : CIwManaged , CIwModel , CIwModelBlock , CIwModelExt , CIwModelExtSelSetFace , CIwResTemplate , CIwUIAnimation , CIwUIElement , CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayout , CIwUIPropertySet , CIwPropertyDefine , CIwPropertySet , CIwPropertySetBinding , CIwGxShaderTechnique , CIwMaterial
  • ParseCloseChild() : CIwManaged , CIwUIAnimation , CIwUIElement , CIwUILayout , CIwUILayoutGrid , CIwUILayoutItemContainer , CIwPropertySet
  • ParseFile() : CIwTextParserITX
  • ParseOpen() : CIwModelExtSelSetEdge , CIwMaterial , CIwResTemplateMTL , CIwManaged , CIwModelExtSelSetVert
  • Pause() : CIwAnimBlendSource , CIwAnimPlayer
  • PauseAnim() : CIwMaterial
  • PeekString() : CIwTextParserITX
  • PlayAnim() : CIwAnimBlendSource , CIwAnimPlayer , CIwUIAnimManager
  • PlayOfsAnim() : CIwAnimPlayer
  • PlaySubAnim() : CIwAnimPlayer
  • Plus() : CIwMenuItem
  • Pop() : CIwManagedList
  • pop_back() : CIwArray< X, A, REALLOCATE >
  • pop_back_get() : CIwArray< X, A, REALLOCATE >
  • PopObject() : CIwTextParserITX
  • Populate() : CIwUILayout
  • PopulateElement() : CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayout
  • Post() : CIwHTTP
  • PostEvent() : CIwUIController
  • PostMult() : CIwMat2D , CIwMat , CIwFMat , CIwFMat2D
  • PostMultiply() : CIwFMat , CIwMat2D , CIwFMat2D , CIwMat
  • PostRender() : CIwModelBlock
  • PostRotate() : CIwFMat2D , CIwMat2D , CIwMat , CIwFMat
  • PreMult() : CIwMat , CIwMat2D , CIwFMat2D , CIwFMat
  • PreMultiply() : CIwFMat2D , CIwFMat , CIwMat2D , CIwMat
  • PreRotate() : CIwMat2D , CIwFMat2D , CIwMat , CIwFMat
  • ProcessElement() : IIwFocusResolver
  • Push() : CIwManagedList
  • push_back() : CIwList< X > , CIwArray< X, A, REALLOCATE >
  • push_back_qty() : CIwArray< X, A, REALLOCATE >
  • PushObject() : CIwTextParserITX


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- q -

  • QueueStylesheet() : CIwUIStyleManager


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- r -

  • Reactivate() : CIwUIView
  • ReadAngleDegrees() : CIwTextParserITX
  • ReadAngleRadians() : CIwTextParserITX
  • ReadBool() : CIwTextParserITX
  • ReadContent() : CIwHTTP
  • ReadDouble() : CIwTextParserITX
  • ReadDoubleArray() : CIwTextParserITX
  • ReadFile() : CIwImage
  • ReadFixed() : CIwTextParserITX
  • ReadFixedArray() : CIwTextParserITX
  • ReadFloat() : CIwTextParserITX
  • ReadFloatArray() : CIwTextParserITX
  • ReadInt16() : CIwTextParserITX
  • ReadInt16Array() : CIwTextParserITX
  • ReadInt32() : CIwTextParserITX
  • ReadInt32Array() : CIwTextParserITX
  • ReadInt8() : CIwTextParserITX
  • ReadInt8Array() : CIwTextParserITX
  • ReadLine() : CIwTextParserITX
  • ReadPalette() : CIwImage
  • ReadScope() : CIwTextParserITX
  • ReadString() : CIwTextParserITX
  • ReadStringHash() : CIwTextParserITX
  • ReadTexels() : CIwImage
  • ReadUInt16() : CIwTextParserITX
  • ReadUInt16Array() : CIwTextParserITX
  • ReadUInt32() : CIwTextParserITX
  • ReadUInt32Array() : CIwTextParserITX
  • ReadUInt8() : CIwTextParserITX
  • ReadUInt8Array() : CIwTextParserITX
  • RebuildMenu() : CIwMenuManager
  • RecreateSurface() : CIwGxSurface
  • RemakeMipmaps() : CIwTexture
  • RemapVertexIDs() : CIwModelExt , CIwModelExtSelSetVert , CIwModelExtSelSetEdge
  • RemoveChild() : CIwUIElement
  • RemoveChildItem() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUILayoutSpacer
  • RemoveDelegate() : CIwUIElement , CIwUIView
  • RemoveElement() : CIwUILayout , CIwUILayoutItem , CIwUILayoutItemContainer , CIwUIView
  • RemoveEventHandler() : CIwUIController , CIwUIElement
  • RemoveExt() : CIwModel
  • RemoveFast() : CIwManagedList
  • RemoveHandler() : CIwResManager
  • RemoveSlow() : CIwManagedList
  • Render() : CIwMenuItemEditFixed , CIwMenuItemEditAngle , CIwUIElement , CIwUIScrollableView , CIwUIView , CIwMenuItem , CIwMenuManager , CIwMenuItemString , CIwMenuItemEditFlags , CIwMenuItemEditEnum , CIwModel , CIwModelBlock
  • RenderChildren() : CIwUIElement
  • RenderElement() : CIwUIAlertDialog , CIwUIButton , CIwUICheckbox , CIwUIImage , CIwUILabel , CIwUIRadioButton , CIwUISlider , CIwUITextField
  • ReplaceAlpha() : CIwImage
  • ReplaceAlphaColourWithSurrounding() : CIwImage
  • ReplaceColour() : CIwImage
  • ReplacePalette() : CIwImage
  • RequestFocus() : CIwUIElement , CIwUIView
  • Reserve() : CIwManagedList , CIwGxFontPreparedData
  • reserve() : CIwArray< X, A, REALLOCATE >
  • reserve_optimised() : CIwArray< X, A, REALLOCATE >
  • ReserveExtraChildren() : CIwResGroup
  • ReserveGroups() : CIwResManager
  • ReserveHandlers() : CIwResManager
  • Reset() : CIwResTemplateSKEL , CIwMaterial , CIwResTemplateMTL , CIwResTemplateGEO , CIwResTemplateANIM , CIwResTemplateSKIN , CIwResTemplate , CIwResHandler , CIwResTemplateGROUP , CIwResTemplateImage
  • ResetCurrent() : CIwUIAnimDataLocator
  • ResetNext() : CIwUIAnimDataLocator
  • ResetSkinCache() : CIwAnimSkel
  • resize() : CIwArray< X, A, REALLOCATE >
  • resize_optimised() : CIwArray< X, A, REALLOCATE >
  • resize_quick() : CIwArray< X, A, REALLOCATE >
  • Resolve() : CIwPropertySet , CIwUIPropertySet , CIwUILayoutItemContainer , CIwManaged , CIwUIAnimKeyFrame , CIwManagedList , CIwModel , CIwProperty< Type > , CIwUILayout , CIwPropertyBase , CIwUIStyle , CIwUILayoutItem , CIwUIElement , IIwFocusResolver , CIwTexture , CIwModelBlock , CIwAnimPlayer , CIwResGroup , CIwUIAnimation , CIwMaterial , CIwUILayoutGrid , CIwUIRect
  • ResolvePtrs() : CIwManagedList
  • ResolveResPtr() : CIwResManager
  • RestartAnim() : CIwMaterial
  • RotateVec() : CIwMat , CIwFMat , CIwMat2D , CIwFMat2D , CIwMat , CIwMat2D
  • RotateVecSafe() : CIwMat2D , CIwMat
  • RotateVector() : CIwQuat , CIwSQuat , CIwFQuat
  • RotateVecX() : CIwMat , CIwFMat , CIwMat2D , CIwFMat2D , CIwMat2D
  • RotateVecY() : CIwFMat , CIwFMat2D , CIwMat2D , CIwMat , CIwMat2D , CIwMat
  • RotateVecZ() : CIwMat , CIwFMat
  • RowX() : CIwMat2D , CIwFMat2D , CIwFMat , CIwMat
  • RowY() : CIwMat2D , CIwFMat2D , CIwMat , CIwFMat
  • RowZ() : CIwMat , CIwFMat
  • Run() : CIwMenuItem


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- s -

  • s3eFileGet() : CIwAutoFile
  • SaveBmp() : CIwImage
  • SaveTemp() : CIwGxShaderTechnique
  • Scale() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • ScaleRot() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • ScaleTrans() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • ScrollToPosition() : CIwUIScrollableView
  • Select() : CIwMenuItemManagedList , CIwMenuItem
  • SelectMenu() : CIwMenuManager
  • SendEvent() : CIwUIController
  • Serialise() : CIwModelExtSphere , CIwUIPropertySet , CIwUIRect , CIwModelExtSelSetVert , CIwUIStyle , CIwProperty< Type > , CIwModelExtSelSetEdge , CIwPropertyBase , CIwPropertyDefine , CIwModelExtSelSetFace , CIwPropertySet , CIwBBoxT< V > , CIwFMat , CIwFMat2D , CIwFQuat , CIwFVec2 , CIwFVec3 , CIwColour , CIwFVec4 , CIwMat , CIwGxShaderTechnique , CIwMat2D , CIwQuat , CIwMaterial , CIwSphereT< V, R > , CIwSQuat , CIwTexture , CIwSVec2 , CIwSVec3 , CIwImage , CIwSVec4 , CIwVec2 , CIwManaged , CIwVec3 , CIwVec4 , CIwManagedList , CIwAnimPlayer , CIwResList , CIwModel , CIwUIAnimKeyFrame , CIwUIAnimation , CIwModelBlock , CIwUIColour , CIwUIElement , CIwModelExt , CIwUILayout , CIwUILayoutGrid , CIwModelExtPos , CIwUILayoutItem , CIwUILayoutItemContainer
  • SerialiseHeader() : CIwManagedList , CIwArray< X, A, REALLOCATE >
  • SerialisePtrs() : CIwManagedList
  • SerialiseResPtr() : CIwResManager
  • Set() : CIwColour , CIwGxShaderUniform , CIwProperty< Type >
  • SetAlignment() : CIwUILayoutItemContainer
  • SetAlignmentFromPos() : CIwUILayoutItemContainer
  • SetAlphaMode() : CIwMaterial
  • SetAlphaTestMode() : CIwMaterial
  • SetAlphaTestRefVal() : CIwMaterial
  • SetAnimCelH() : CIwMaterial
  • SetAnimCelID() : CIwMaterial
  • SetAnimCelNum() : CIwMaterial
  • SetAnimCelNumU() : CIwMaterial
  • SetAnimCelPeriod() : CIwMaterial
  • SetAnimCelW() : CIwMaterial
  • SetAnimOfsU() : CIwMaterial
  • SetAnimOfsV() : CIwMaterial
  • SetAssertOnUnrecognisedTokens() : CIwTextParserITX
  • SetAxisAngle() : CIwFMat , CIwFQuat , CIwMat , CIwQuat , CIwSQuat
  • SetBinding() : CIwPropertySet
  • SetBlendMode() : CIwMaterial
  • SetBorder() : CIwUILayoutItemContainer
  • SetBuildGroupCallbackPost() : CIwResManager
  • SetBuildGroupCallbackPre() : CIwResManager
  • SetBuildStyle() : CIwResManager
  • SetCaption() : CIwUIButton , CIwUILabel
  • SetCaptionLocalised() : CIwUILabel
  • SetChecked() : CIwUICheckbox
  • SetClamping() : CIwMaterial , CIwTexture
  • SetClipped() : CIwUIElement
  • SetColAmbient() : CIwMaterial
  • SetColDiffuse() : CIwMaterial
  • SetColEmissive() : CIwMaterial
  • SetColour() : CIwUIDrawableImage , CIwUIDrawableText , CIwUIElement , CIwUIGraphics , IIwUIDrawable , CIwUIDrawableBorder
  • SetColourFixed() : CIwUIColour
  • SetColSpecular() : CIwMaterial
  • SetCullMode() : CIwMaterial
  • SetCurrentGroup() : CIwResManager
  • SetCursorDelay() : CIwUITextInput
  • SetCursorFlashPeriod() : CIwUITextInput
  • SetEditorMode() : CIwUITextInput
  • SetEffectPreset() : CIwMaterial
  • SetElement() : CIwUILayout
  • SetEnabled() : CIwGxShaderTechnique , CIwUIButton
  • SetFiltering() : CIwMaterial , CIwTexture
  • SetFlags() : CIwModel , CIwModelExt , CIwAnimBlendSource , CIwAnimPlayer
  • SetFocus() : CIwMenuManager
  • SetFocusHandler() : CIwUIElement
  • SetFocusKey() : CIwMenuManager
  • SetFormat() : CIwImage
  • SetFormatHW() : CIwTexture
  • SetFormatSW() : CIwTexture
  • SetFormSize() : CIwUILayoutForm
  • SetFrame() : CIwUIGraphics
  • SetGrey() : CIwColour
  • SetHeight() : CIwImage
  • SetIdentity() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • SetImage() : CIwTexture
  • SetInvisible() : CIwMaterial
  • SetItem() : CIwUILayoutItemContainer
  • SetLayout() : CIwUIElement
  • SetLayoutInvalid() : CIwUILayout
  • setLength() : CIwString< N >
  • SetMainMenuFn() : CIwMenuManager
  • SetMenuCharWH() : CIwMenuManager
  • SetMenuDefaultW() : CIwMenuManager
  • SetMenuDefaultXY() : CIwMenuManager
  • SetMergeGeom() : CIwMaterial
  • SetMipMapping() : CIwTexture
  • SetModal() : CIwUIView
  • SetMode() : CIwResManager
  • SetModel() : CIwAnimSkin
  • SetModelMatrix() : CIwAnimBone
  • SetModifiable() : CIwTexture
  • SetModulateColour() : CIwUIGraphics
  • SetModulateMode() : CIwMaterial
  • SetModulatesColour() : CIwUIElement
  • SetName() : CIwUIAnimKeyFrame , CIwMaterial , CIwManaged , CIwUIElement , CIwUILayoutItem
  • SetObserver() : CIwUIAnimManager , CIwUIAnimator
  • SetOpaque() : CIwColour
  • SetOrder() : CIwUILayoutHorizontal , CIwUILayoutVertical
  • SetOwnedBuffers() : CIwImage
  • SetPaletteCacheRGBs() : CIwTexture
  • SetParent() : CIwUIPropertySet , CIwUIStylesheet , CIwPropertySet
  • SetParentItem() : CIwUILayoutItem
  • SetPitch() : CIwImage
  • SetPointerCapture() : CIwUIController
  • SetPos() : CIwUIElement , CIwAnimBone
  • SetPosAbsolute() : CIwUIElement
  • SetPosition() : IIwUIDrawable , CIwUIDrawableImage , CIwUIDrawableText , CIwUIDrawableBorder
  • SetProgress() : CIwUIProgressBar
  • SetProperty() : CIwPropertySet , CIwUIElement , CIwUILayoutItem , CIwPropertySetBinding , CIwUIAnimKeyFrame
  • SetPropertyDefine() : CIwPropertyBase
  • SetPropertySetBinding() : CIwUIElement
  • SetProportion() : CIwUISlider
  • SetQueuedStylesheet() : CIwUIStyleManager
  • SetRadius() : CIwSphereT< V, R >
  • SetRedundant() : CIwModelExt
  • SetRenderSlot() : CIwUIElement
  • SetRequestHeader() : CIwHTTP
  • SetRot() : CIwMat2D , CIwFMat2D , CIwAnimBone , CIwMat2D
  • SetRotX() : CIwFMat , CIwMat
  • SetRotY() : CIwFMat , CIwMat
  • SetRotZ() : CIwFMat , CIwMat
  • SetSelectable() : CIwMenuItem
  • SetSelected() : CIwUIRadioButton , CIwUITabBar
  • SetShadeMode() : CIwMaterial
  • SetShared() : CIwResGroup
  • SetSize() : CIwUIElement , CIwUIDrawableText , CIwUIDrawableBorder , IIwUIDrawable , CIwUIDrawableImage
  • SetSizeHint() : CIwUIElement
  • SetSizeMax() : CIwUIElement
  • SetSizeMin() : CIwUIElement
  • SetSizeToContent() : CIwUIElement
  • SetSizeToSpace() : CIwUILayout
  • SetSkel() : CIwAnimSkin , CIwAnimPlayer
  • SetSoftKeyboardModal() : CIwUITextInput
  • SetSpacing() : CIwUILayoutVertical , CIwUILayoutHorizontal
  • SetSpecularPower() : CIwMaterial
  • SetSpeed() : CIwAnimBlendSource
  • SetStyle() : CIwUILayoutItem , CIwUIElement
  • SetStylesheet() : CIwUIStyleManager
  • SetTemplate() : CIwResHandler
  • SetTextCallback() : CIwMenuManager
  • SetTexture() : CIwMaterial
  • SetTime() : CIwUIAnimKeyFrame , CIwAnimBlendSource , CIwAnimPlayer , CIwUIAnimManager , CIwUIAnimator
  • SetTimeFraction() : CIwAnimPlayer , CIwAnimBlendSource
  • SetTrans() : CIwMat2D , CIwMat , CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • SetTransform() : CIwUIGraphics , CIwUIElement
  • SetTransformPos() : CIwUIElement
  • Setup() : CIwUIPositionPolicy , CIwUISizePolicy
  • SetUpdatable() : CIwUIElement
  • SetUserFlags() : CIwMaterial
  • SetUVOfs() : CIwMaterial
  • SetValue() : CIwUISlider
  • SetViewMat() : CIwUIGraphics
  • SetVisible() : CIwUIElement
  • SetWidth() : CIwImage
  • SetWorldSpace() : CIwGxShaderUniform
  • SetWorldSpaceDirection() : CIwGxShaderUniform
  • SetZDepthFixed() : CIwModel
  • SetZDepthOfs() : CIwMaterial , CIwModel
  • SetZDepthOfsHW() : CIwMaterial
  • SetZero() : CIwMat , CIwFMat2D , CIwFMat , CIwMat2D
  • Share() : CIwArray< X, A, REALLOCATE >
  • ShouldAllowFocus() : CIwUITextInput
  • ShouldDisplayCursor() : CIwUITextInput
  • size() : CIwString< N > , CIwArray< X, A, REALLOCATE >
  • SkipScope() : CIwTextParserITX
  • Slerp() : CIwSQuat , CIwQuat , CIwFQuat
  • SplitPathName() : CIwResManager
  • Start() : CIwAnimBlendSource , CIwAnimPlayer
  • Stop() : CIwAnimBlendSource , CIwUIAnimator , CIwAnimPlayer
  • StopAllAnims() : CIwUIAnimManager
  • StopAnim() : CIwUIAnimManager
  • Store() : CIwUISizePolicy , CIwUIPositionPolicy
  • swap() : CIwArray< X, A, REALLOCATE >


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- t -

  • TestInsertPos() : CIwUILayout
  • TransformVec() : CIwFMat , CIwMat , CIwFMat2D , CIwMat2D
  • TransformVecSafe() : CIwMat , CIwMat2D
  • TransformVecShift() : CIwMat , CIwMat2D
  • Translate() : CIwUIRect
  • TranslateTransform() : CIwUIGraphics
  • Transpose() : CIwFMat , CIwFMat2D , CIwMat , CIwMat2D
  • TransposeRotateVec() : CIwMat2D , CIwMat , CIwFMat , CIwMat , CIwFMat2D , CIwMat2D
  • TransposeRotateVecSafe() : CIwMat , CIwMat2D
  • TransposeTransformVec() : CIwFMat2D , CIwMat , CIwFMat , CIwMat2D


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- u -

  • Union() : CIwUIRect
  • Update() : CIwMenuItem , CIwAnimBone , CIwUIController , CIwUIElement , CIwAnimPlayer , CIwUIScrollableView , CIwUISoftKeyPosition , CIwMenuManager , CIwUIAnimator , CIwUITextInput , CIwUIView , CIwUIAnimManager
  • UpdateMatrices() : CIwAnimPlayer
  • UpdateParameters() : CIwAnimPlayer , CIwAnimBlendSource
  • UpdateSource() : CIwAnimBlendSource
  • UpdateSources() : CIwAnimPlayer
  • Upload() : CIwGxStream , CIwTexture
  • UseAsHandle() : CIwTexture
  • UsesAlpha() : CIwTexture , CIwImage
  • UsesChromakey() : CIwImage , CIwTexture


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- v -

  • VertCopiesAreIDs() : CIwModel


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • c
  • d
  • e
  • f
  • g
  • h
  • i
  • l
  • m
  • n
  • o
  • p
  • q
  • r
  • s
  • t
  • u
  • v
  • w
  • z
  • ~

- w -

  • WantsFocus() : CIwUIButton , CIwUICheckbox , CIwUISlider , CIwUITextField , CIwUIElement
  • Write() : CIwResGroup
  • WriteAttibuteNameHash() : CIwTextDecomposer
  • WriteAttribute() : CIwTextDecomposer
  • WriteAttributeHash() : CIwTextDecomposer
  • WriteAttributeName() : CIwTextDecomposer
  • WriteAttributeNameVal() : CIwTextDecomposer
  • WriteAttributeNameValArray() : CIwTextDecomposer
  • WriteAttributeVal() : CIwTextDecomposer
  • WriteAttributeValArray() : CIwTextDecomposer
  • WriteClassName() : CIwTextDecomposer
  • WriteFlags() : CIwModel
  • WriteObjectName() : CIwTextDecomposer


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions

  • IW_GX_ALLOC_MATERIAL : CIwMaterial
  • IwGxDrawPrims : CIwMaterial
  • IwGxFlush : CIwMaterial
  • IwGxSetMaterial : CIwTexture
  • IwGxSetRasterisationHW : CIwMaterial
  • IwResManagerInit : CIwResManager
  • IwResManagerTerminate : CIwResManager
  • IwUIInit : CIwUIElement
  • IwUITerminate : CIwUIElement


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions

  • BuildGroupCallbackPost : CIwResManager
  • BuildGroupCallbackPre : CIwResManager
  • Field : CIwTextParserITX
  • FieldArray : CIwTextParserITX
  • FieldArrayIt : CIwTextParserITX
  • IwModelBlockRender : CIwModelBlock
  • MainFn : CIwMenuManager
  • TextCallback : CIwMenuManager


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- a -

  • a : CIwColour


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- k -

  • k : CIwPlane


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- m -

  • m : CIwFMat , CIwFMat2D , CIwMat2D , CIwMat
  • m_Abstract : s3eInetAddress
  • m_Altitude : s3eLocation
  • m_AtlasAllMaterials : CIwResTemplateGROUP
  • m_AtlasPadding : CIwResTemplateGROUP
  • m_BlitDirection : s3eSurfaceCopyupInfo
  • m_Blocks : CIwModel
  • m_BSphere : CIwModel
  • m_Button : s3ePointerEvent
  • m_Channel : s3eSoundEndSampleInfo , s3eSoundGenAudioInfo
  • m_ChannelID : s3eAudioCallbackData
  • m_Close : s3eFileUserCallbacks
  • m_ColourID : CIwMenuItem
  • m_Data : s3eDecompressionInput , s3eSurfaceInfo
  • m_Delete : s3eFileUserCallbacks
  • m_DestSurface : s3eSurfaceCopyupInfo
  • m_DeviceBlitDirection : s3eSurfaceOrientation
  • m_Edges : CIwModelExtSelSetEdge
  • m_EndSample : s3eSoundGenAudioInfo
  • m_EOF : s3eFileUserCallbacks
  • m_Ext : CIwResHandler
  • m_Exts : CIwModel
  • m_FaceIDs : CIwModelExtSelSetFace
  • m_Flags : CIwTexture , CIwModelBlock , CIwModelExtSelSetFace
  • m_FlagsHW : CIwModelExtSelSetFace
  • m_FlagsSW : CIwModelExtSelSetFace
  • m_FormatHW : CIwTexture
  • m_FormatSW : CIwTexture
  • m_formattedPrice : s3eProductInformation
  • m_GLOTIndex : CIwTexture
  • m_H : CIwMenuItem
  • m_Hash : CIwManaged
  • m_Height : s3eSurfaceInfo , s3eSurfaceOrientation , s3eSurfaceCopyupInfo
  • m_HorizontalAccuracy : s3eLocation
  • m_HWID : CIwTexture
  • m_ID : s3eProductIdentifier , s3eTransactionIdentifier
  • m_IPAddress : s3eInetAddress
  • m_Key : s3eKeyboardEvent
  • m_Latitude : s3eLocation
  • m_ListClose : s3eFileUserCallbacks
  • m_ListDir : s3eFileUserCallbacks
  • m_ListNext : s3eFileUserCallbacks
  • m_LocalAddress : s3eInetAddress
  • m_LocalizedDescription : s3eProductInformation
  • m_LocalizedTitle : s3eProductInformation
  • m_Longitude : s3eLocation
  • m_Materials : CIwModel
  • m_Max : CIwBBoxT< V >
  • m_MaxAreaPerTexture : CIwResTemplateGROUP
  • m_MaxAtlasTargets : CIwResTemplateGROUP
  • m_Min : CIwBBoxT< V >
  • m_Mix : s3eSoundGenAudioInfo
  • m_Name : CIwMenuItem , s3eExtMetricsInfo
  • m_NewData : s3eSoundEndSampleInfo
  • m_NumFaces : CIwModelExtSelSetFace
  • m_NumItems : CIwModelBlock
  • m_NumSamples : s3eSoundEndSampleInfo , s3eSoundGenAudioInfo
  • m_Open : s3eFileUserCallbacks
  • m_OrientationChanged : s3eSurfaceOrientation
  • m_OrigNumSamples : s3eSoundGenAudioInfo
  • m_OrigRepeat : s3eSoundGenAudioInfo
  • m_OrigStart : s3eSoundGenAudioInfo
  • m_OTZOfsSW : CIwModelExtSelSetFace
  • m_OverrideDefaultBehaviour : s3eDeviceVolChangeInfo
  • m_Owner : CIwModelBlock , CIwModelExt
  • m_PageSize : CIwResTemplateGROUP
  • m_PaletteCacheRGBs : CIwTexture
  • m_Pitch : s3eSurfaceInfo , s3eSurfaceOrientation
  • m_PixelType : s3eSurfaceInfo
  • m_Port : s3eInetAddress
  • m_Pos : CIwModelExtPos
  • m_Pressed : s3ePointerEvent , s3eKeyboardEvent , s3ePointerTouchEvent
  • m_price : s3eProductInformation
  • m_priceLocal : s3eProductInformation
  • m_ProductID : s3eProductInformation
  • m_Read : s3eFileUserCallbacks
  • m_ReceiptData : s3eTransactionReceipt
  • m_ReceiptSize : s3eTransactionReceipt
  • m_RenderFn : CIwModelBlock
  • m_RepsRemaining : s3eSoundEndSampleInfo
  • m_Request : s3ePaymentTransaction
  • m_Reserved : s3eFileUserCallbacks
  • m_ResName : CIwResTemplate
  • m_Resources : CIwResList
  • m_ResType : CIwResHandler
  • m_Seek : s3eFileUserCallbacks
  • m_Settings : CIwResHandler
  • m_Size : CIwModelBlock , s3eDecompressionInput
  • m_Sphere : CIwModelExtSphere
  • m_SrcSurface : s3eSurfaceCopyupInfo
  • m_State : s3eDeviceStateChangeInfo
  • m_Stereo : s3eSoundGenAudioInfo
  • m_String : s3eInetAddress
  • m_Target : s3eSoundGenAudioInfo
  • m_Tell : s3eFileUserCallbacks
  • m_TemplateCurr : CIwResHandler
  • m_TemplateInit : CIwResHandler
  • m_Templates : CIwResHandler
  • m_Text : CIwMenuItem
  • m_TileSpecs : CIwResTemplateGROUP
  • m_TimeStampUTC : s3eLocation
  • m_TouchID : s3ePointerTouchEvent , s3ePointerTouchMotionEvent
  • m_TransactionID : s3ePaymentTransaction
  • m_TransactionReceipt : s3ePaymentTransaction
  • m_TransactionStatus : s3ePaymentTransaction
  • m_UShiftFactor : CIwTexture
  • m_Value : s3eExtMetricsInfo
  • m_VerticalAccuracy : s3eLocation
  • m_VertIDs : CIwModelExtSelSetVert
  • m_VolUp : s3eDeviceVolChangeInfo
  • m_VRAMInfo : CIwTexture
  • m_VShiftFactor : CIwTexture
  • m_W : CIwMenuItem
  • m_Width : s3eSurfaceCopyupInfo , s3eSurfaceOrientation , s3eSurfaceInfo
  • m_WorldSet : CIwModelExtSelSetFace
  • m_Write : s3eFileUserCallbacks
  • m_x : s3ePointerMotionEvent , s3ePointerTouchMotionEvent
  • m_X : s3eSurfaceCopyupInfo
  • m_x : s3ePointerEvent , s3ePointerTouchEvent
  • m_X : CIwMenuItem
  • m_y : s3ePointerMotionEvent
  • m_Y : s3eSurfaceCopyupInfo
  • m_y : s3ePointerTouchEvent , s3ePointerTouchMotionEvent
  • m_Y : CIwMenuItem
  • m_y : s3ePointerEvent
  • maxV : CIwFBBox
  • minV : CIwFBBox


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- z -

  • z : CIwFVec3 , CIwVec4 , CIwVec3 , CIwSVec4 , CIwSVec3 , CIwFVec4


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- b -

  • b : CIwColour


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- g -

  • g : CIwColour
  • g_AxisW : CIwFVec4 , CIwVec4 , CIwSVec4
  • g_AxisX : CIwSVec2 , CIwSVec3 , CIwFVec2 , CIwSVec4 , CIwVec2 , CIwFVec3 , CIwVec3 , CIwVec4 , CIwFVec4
  • g_AxisY : CIwFVec4 , CIwSVec2 , CIwSVec3 , CIwSVec4 , CIwVec2 , CIwVec3 , CIwVec4 , CIwFVec2 , CIwFVec3
  • g_AxisZ : CIwFVec3 , CIwFVec4 , CIwSVec3 , CIwSVec4 , CIwVec3 , CIwVec4
  • g_Context : CIwModel
  • g_Identity : CIwFMat2D , CIwFQuat , CIwMat , CIwMat2D , CIwSQuat , CIwQuat , CIwFMat
  • g_Norms : CIwModel
  • g_Verts : CIwModel
  • g_XY : CIwPlane
  • g_XZ : CIwPlane
  • g_YZ : CIwPlane
  • g_Zero : CIwVec4 , CIwSVec2 , CIwFVec4 , CIwSVec4 , CIwSVec3 , CIwFVec2 , CIwVec2 , CIwFVec3 , CIwVec3


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- h -

  • h : CIwRect , CIwRect32


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- r -

  • r : CIwColour , CIwFSphere , CIwSphereT< V, R >
  • r2 : CIwFSphere , CIwSphereT< V, R >


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- s -

  • s : CIwFQuat , CIwQuat , CIwSQuat
  • s_CloneExpectedClassName : CIwUIElementEventHandler , CIwUIFocusHandler , CIwUILayoutItem


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- t -

  • t : CIwFMat , CIwSphereT< V, R > , CIwMat2D , CIwMat , CIwFSphere , CIwFMat2D


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- v -

  • v : CIwPlane


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- w -

  • w : CIwRect , CIwVec4 , CIwSVec4 , CIwFVec4 , CIwRect32


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- x -

  • x : CIwRect , CIwVec4 , CIwVec3 , CIwVec2 , CIwSVec4 , CIwSVec3 , CIwSVec2 , CIwFVec4 , CIwFVec3 , CIwFVec2 , CIwRect32


Airplay API Reference: Data Fields

Airplay API Reference > Data Fields >

Data Fields

  • All
  • Functions
  • Variables
  • Typedefs
  • Enumerations
  • Enumerator
  • Related Functions
  • a
  • b
  • g
  • h
  • k
  • m
  • r
  • s
  • t
  • v
  • w
  • x
  • y
  • z

- y -

  • y : CIwRect , CIwVec4 , CIwVec3 , CIwVec2 , CIwSVec4 , CIwSVec3 , CIwSVec2 , CIwFVec4 , CIwFVec3 , CIwFVec2 , CIwRect32


Airplay API Reference: Namespace Members

Airplay API Reference > Namespace Members >

Namespace Members

  • All
  • Functions

  • GetAtlasMaterialSize() : IwUIAtlas
  • GetMaterialSize() : IwUIAtlas
  • GetTextureUVMap() : IwUIAtlas
  • MapToAtlasMaterial() : IwUIAtlas
  • MapToFixedUV() : IwUIAtlas