Chapter 5. Overview

Table of Contents

Introduction
Application Framework
Graphics
Audio
File I/O
Controls
Memory and Resource Management
Network
Development Platform Requirements
Symbian Platforms
Microsoft PocketPC and Smartphone Platforms
Tapwave Zodiac

Introduction

This document provides an overview of the X-Forge Core API. The X-Forge Core is the low-level layer of the whole X-Forge, providing platform-independent services for the game engine, along with any hardware acceleration features that can be accessed.

The X-Forge Engine is built on top of the X-Forge Core, and is completely platform-independent. It is possible to create a game applicatin directly on top of the X-Forge Core. This way, the game developer may develop its own game engine and still remain the platform-independency that the X-Forge Core provides.

In addition to having an overview of all of the major APIs in the X-Forge Core, this document contains short descriptions of the development platform requirements. These can be found in 'development platform requirements'.

The design philosophy behind the X-Forge Core has been to hide as much of the platform complexity from the developer, while keeping interfaces as thin as possible in order to avoid any performance penalties.

The code base is written in C++, but it is closer to "C with objects" than full-blown C++. Exceptions, for instance, have not been used due to the problems certain compilers have with them. Template use is also minimal. Operators have been overloaded only in cases where their use should be obvious (such as addition of fixed point values, as opposed to performing dot product via the pipe operator).

The recommended main development platform is Windows 2000 or later, with Visual Studio 6. Using this development environment the developer can use our 'desktop Windows' platform to rapidly develop the game code without using any target devices at all. This is also recommended due to the debugging tools available on the desktop windows platform, while some mobile platforms do not support any kind of debugging. Currently Visual Studio 6 is also required for all Symbian and Tapwave development.

Application Framework

The application flow is designed to work, without any changes, on multiple platforms, some of which are more restrictive than others. The second important design goal was to keep the application complexity as low as possible and to shield the application developers from most of the complexity that happens behind the scenes on some platforms.

Some of the complexity cannot be hidden, such as the lack of explicit "show this on screen" commands, and the fact that the "main loop" is not inside the application. Additionally, the application must not use any global data in order to be portable to Symbian platforms.

The application framework consists of two global functions and three interface classes. The two functions are xfcAppPref and xfcAppInit. The xfcAppPref function is called to request information such as required memory from the application, and the xfcAppInit is the initialization function where the application creates the objects it needs to execute.

The three interface classes are XFcApp (the application object), XFcRender (renderer object) and XFcInput (controller object). These three classes receive callbacks whenever things happen, such as the rendering phase of the main loop.

More through explanation of the application framework can be found in the 'Application Framework' chapter.

Graphics

All graphics output in X-Forge Core is handled through the XFcGL object. The XFcGL itself connects to some rendering device. Currently available devices include the default rasterizer with assembler-optimized polygon fillers, full-screen antialiased rasterizer which performs 2x2 supersampling and 2x2 upsample rasterizer. Other devices, using hardware capabilities for acceleration, are also under development, and will be included in the package once consumer devices become available.

More throughout explanation of the application framework can be found in the '2D Graphics' and '3D Graphics' chapters.

Audio

The audio API supports multi-channel digital audio, using either static audio buffers (with optional looping) or streaming audio (such as the XM module player).

The API was designed so that simple fire-and-forget sound effect would be easy, while letting the user control the sound dynamically if required. Playing speed, volume and panning can be altered.

When the audio library is initialized, the application sets the audio format and desired number of simultaneous audio channels.

Whenever some audio is triggered, the application can set its playing speed, panning, volume and priority. If all channels are in use, but some active sound has lower priority than the one being triggered, the lower priority sound is stopped and the new sound plays in its place.

The system returns a handle to the playing instance, and this handle can be used to dynamically alter the sound's properties.

Note

The returned handle can be safely ignored if sounds are used in fire-and-forget mode. A handle is returned regardless of whether the sound actually plays (if, for example, all channels are already in use). Handles are also valid even after the sound has stopped. All of the audio library calls have been designed to do nothing if a non-active handle is used.

As audio sources, the X-Forge Utils library contains RIFF Wave file (.wav) loader which only supports non-compressed audio formats for the time being, and the XM (eXtended Module) player, which uses the note, instrument and sample data inside .XM files to play music. The open XM format was selected due to its compactness, without sacrificing the musical quality.

More throughout explanation of the application framework can be found in the 'Audio' chapter.

File I/O

The file I/O library in X-Forge is called XFcFile. It has been modeled after the standard C library fopen/fclose style file handling. No C++ file stream extensions are included.

In addition to disk files, the file library transparently supports compressed virtual filesystem called CFL (compressed file library).

More information about the filesystem and CFL can be found in the 'File I/O' chapter.

Controls

All user controls are handled via the XFcInput control library interface. This interface provides callbacks for button and pointer events. On desktop, the mouse is used to emulate the stylus.

In addition to reporting raw scancodes, the interface also supports control codes which can be remapped to different scancodes at runtime.

More about the controls can be found in the 'Application Framework' chapter.

Memory and Resource Management

At application startup, the application requests certain amount of memory. This memory is allocated as one memory pool, which is managed by the X-Forge memory manager, thus preventing any surprising out of memory situations. It also provides consistent memory allocation performance across all platforms.

Additionally the system supports a specialized form of memory management in the form of resource management. Resources are stored in two parts; the resource itself, and the information on how to create the resource if needed. If the system is running low on memory, resources are destroyed and will be recreated whenever they are called upon next. This makes it possible, for example, to have a 3D scene with far more textures than would fit in memory otherwise, at the expense of performance hit whenever a texture is recreated.

Note

Textures are only one possible use for resource management. Other good candidates for resource management would be large 2D graphics, sound effects and large meshes.

Network

The networking API hides all the differences of all the supported network methods behind a simple sockets API. The currently supported networks are bluetooth and WLAN.

The developer can choose from 4 different types of packet which are "guaranteed", "nonguaranteed", "quickguaranteed" and "recentstate". Guaranteed packets are resent until they reach their destination. Nonguaranteed packets are only sent once, regardless of whether they reach their destination. Quickguaranteed packets are put in front of the guaranteed packet queue, and finally recentstate packets are resent at certain intervals and the application can still change its contents. The recentstate packets could be considered as distributed variables.

Additionally, a simplified higher-level networking API is built on top of this, which makes it easier for the developers to make networked games. This is found in X-Forge Utility Library

Development Platform Requirements

The recommended base development platform contains the following:

  • PIII-class PC
  • Windows 2000
  • Microsoft Visual Studio 6 with Service Pack 4 or later

A PIII/866 is enough to run X-Forge applications in debug mode a bit faster speed than they run on a Nokia 7650 Imaging Phone.

The base development platform is required in order to build desktop PC versions of the applications, which is typically a much more rapid way of developing the game as compared to only developing on the target device itself.

The desktop version can also be embedded into some other application, enabling the developer to create tools with which games can be tuned with realtime preview.

Symbian Platforms

In addition to the base development environment (see above), you will need one or more Symbian SDKs. Currently supported platforms are Series 60 with the Series 60 SDK v1.0 and UIQ with the Symbian OS V7.0 UIQ SDK.

For more information on getting started with Symbian development see the 'Getting started' chapter.

Microsoft PocketPC and Smartphone Platforms

In order to develop for a PocketPC or Smartphone2002, Microsoft eVC is required. This can be downloaded, for free, from Microsoft at: http://www.microsoft.com/mobile/developer/downloads/

Additionally the SDK for the target device is required. The SDK for PocketPC2000 is included in the eVC package; this is all you need to make software that works on both PocketPC2000 and PocketPC2002.

One or more of the target devices are also required to ensure playability and performance.

For more information about getting started with the PocketPC development, see the 'Getting started' chapter.

Tapwave Zodiac

In order to develop for a Tapwave Zodiac, Codewarrior 9.2. for Palm and Tapwave SDK is required.