QSDK 1.1 Documentation

Code

Contents

• Introduction
• Easy to Use Object Databases
• A Complete API
• The Flavors of the API
• Change History
• Content Management
• Lighting and Shaders
• Textures
• Levels of Detail
• Particle Effects
• Environmental Effects
• Animation
• Audio
• 2D Graphics
• Exporters

• Reference Documentation

• API Reference

• Tutorials

• Sample Applications
  All with complete source code.

• Demos
  All with complete source code.

• Tools
  Some with complete source code.

• Error Codes

• Scripting Reference

• QCOM

• Texture Management

• Render Cache Technical Note

• Streaming

Introduction

The Q engine includes a number of technical innovations to make a coder's life easier, including easy to use object databases, integrated background loading and streaming, a complete API, tutorials, demos with source code and more.

Easy to Use Object Databases

Q's object databases mean you don't need to write your own loading code, it's all been done for you. Open a database, then simply look up objects by name. Don't worry about the size of your databases: objects are demand loaded, so they only occupy memory once they're used. If you know you're going to need an object soon, a single API call will load the object in the background for you; store your own data in a database using Clip objects. To optimise background loading performance, master your world for your target platform and take full advantage of the built-in streaming.

A Complete API

The QSDK API provides access to all functionality, both editing and runtime. All the tools, including the exporters and QStudio, are built on top of the public, documented API. Even parts of the Q engine itself, such as Puppets and scripting, are built entirely on top of the public QServer API. There are no cryptic file formats to master, no hidden API functions. Anything that can be done at authoring time can be done at runtime.

The Flavors of the API

The core of the Q engine is driven by an object handle system, the QServer API.

Functionality built on top of the core uses a COM-like API, QCOM.

Change History

• QSDK 1.1.0
• QSDK 1.0.1

Content Management

The QSDK provides the ability to create large worlds by connecting multiple Zones together using Portals. Geometry is explicitly parented to Zones, it does not need to be closed, sealed, or satisfy any other abstract requirement. Memory usage and loading are driven by the active Zones to minimize the content required at any time and ensure that neighbouring content is streamed in and made available for seamless transitions between Zones.

Lighting and Shaders

The Q engine supports a variety of real time lighting and shader features:

• Spot lights.
• Omni-directional lights.
• Ambient lighting.
• Optional ambient vertex coloring.
• Emissive (self-illuminating) shaders.
• Phong diffuse lighting with optional texture mapping and texture coordinate animation.
• Optional diffuse vertex coloring.
• Phong specular lighting with a given specular color and optional specular map.
• Optional diffuse channel transparency, with boolean transparency detection and optimisation.
• Optional additive blending.
• Optional per-object shader overrides.

The current version of the QSDK has no public low level graphics API, so there is no support for user-defined vertex or pixel shaders. These features will be available in a future release.

Textures

All Q engine textures are mip-mapped to maximize use of video resources and improve support for video cards with little memory. Our innovative texture management scheme ensures texture quality is always as high as it can be.

In addition to standard image-based textures, the Q engine also supports:

• CameraTextures: textures can be created from a given Camera view, then mapped onto geometry, displayed as a static image or saved to a database.
• FrameTextures: a single image can be treated as a grid of distinct images. The frame displayed is under programmatic control.
• Texture coordinate animation: texture coordinates can be animated to give smooth translation, rotation and scaling of the texture map.

Levels of Detail

Multiple levels of detail are supported for meshes and skins. These may be authored entirely within the tools; at runtime, Q decides which geometry to display based on authored apparent distance values. This is handled through Q::LodHolder objects.

Particle Effects

Complex particle effects can be authored in QStudio, by creating behaviors for the particles, chaining together the behaviors, and connecting them to an emitter. Textures, colors and transparency may be used to create convincing smoke, flame and sparkle effects.

Environmental Effects

The following effects are supported per-Zone through Environment objects:

• Fogging: between a near fog distance and a far fog distance, geometry is blended toward a specified color.
• A skybox mesh: the skybox is always rendered behind all other objects in the Zone, so can be used to represent the sky or background scenery. Emissive and ambient lighting are optional.
• Ambient lighting.
• Multi-channel ambient sounds.

Animation

The positions, orientations, scales and texture coordinates of all objects in the scene may be animated.

Audio

Q supports both positonal and non-positional audio on all platforms.

Positional audio involves placing mono Sounds in a scene, and Q calculates the output based on their positions relative to any active Microphones and any relevant AudioEffects. Sounds have authored falloff distances for realistic volume calculation.

Non-positional audio, through SimpleSounds, can be used for spot audio effects or a Zone's ambient sound.

All sounds support fade-in and fade-out times for smooth volume transitions. Volume may be controlled on individual Microphones, positional and non-positional sounds or the master volume setting.

Pitch-shifting and reverb audio effects are implemented on all platforms. In addition, platform-specific audio effects are also available.

The audio system can be extended to decode other audio formats using user-supplied codecs.

The details of Q's audio capabilities are limited by the host platform's hardware, it is not a lowest common denominator API.

2D Graphics

Rectangular Layers may be individually sized and positioned on the Screen. There are several types of Layer:

• CameraLayer: 3D content rendered through a Camera.
• ImageLayer: images, with optional corner coloring and transparency.
• TextLayer: text, composed from TrueType font glyphs rendered into a texture.
• LogLayer: error reports, useful for development.
• StatsLayer: performance statistics, useful for development.

Input events can be distributed to individual Layers, making them suitable for building complex User Interfaces.

Exporters

The QSDK ships with exporters for 3D Studio MAX versions 3.x, 4.x and 5.x, and Maya versions 2.5, 3, 4, 4.5 and 5 on Microsoft Windows platforms. The source code is supplied, so the exporters can be extended or converted to other authoring packages as required.

		Qube Software Limited © 2000-2004