User Guide Volume I Vol1
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 280
| Download | |
| Open PDF In Browser | View PDF |
User Guide
Volume I
Copyright © 2003 – Criterion Software Ltd.
User Guide
Contact Us
Criterion Software Ltd.
For general information about RenderWare Graphics e-mail info@csl.com.
Developer Relations
For information regarding Support please email devrels@csl.com.
Sales
For sales information contact: rw-sales@csl.com
Acknowledgements
Contributors
RenderWare Graphics Development and Documentation
Teams
The information in this document is subject to change without notice and does not represent a commitment on the part
of Criterion Software Ltd. The software described in this document is furnished under a license agreement or a nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is
against the law to copy the software on any medium except as specifically allowed in the license or non-disclosure
agreement. No part of this manual may be reproduced or transmitted in any form or by any means for any purpose
without the express written permission of Criterion Software Ltd.
Copyright © 1993 - 2003 Criterion Software Ltd. All rights reserved.
Canon and RenderWare are registered trademarks of Canon Inc. Nintendo is a registered trademark and NINTENDO
GAMECUBE a trademark of Nintendo Co., Ltd. Microsoft is a registered trademark and Xbox is a trademark of Microsoft
Corporation. PlayStation is a registered trademark of Sony Computer Entertainment Inc. All other trademark mentioned
herein are the property of their respective companies.
I-2
22 April 2003
Foreword
Foreword
About the User Guide
This is the RenderWare User Guide for release 3.5. The documentation has been
updated for 3.5 and is organized into three volumes of general, platform independent
material. Volume III includes Maestro documentation and a Recommended Reading
appendix .
Xbox, GameCube and PlayStation 2 have a separate platform specific addendum,
containing material which is only useful for that platform and which has been updated
for 3.5.
Volume I contains the core library and the world library, giving basic immediate mode
and retained mode functionality.
•
Introduction
From the core library:
• Fundamental Types
• Initialization & Resource Management
• Plugin Creation and Usage
• The Camera, covering the basics of rendering
• Rasters, Images and Textures
• Immediate Mode
• Serialization
• Debugging & Error Handling
From the world library:
• World and Static Models
• Dynamic Models
• Lights
In Volume II elements of the animation systems, special effects and world management
functionality are discussed
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Skinning
Fundamental Types for Animation
The Animation Toolkit
Hierarchical Animation
Morph
Delta Morphing
Material Effects
Lightmaps
PTank
Standard Particles (RpPrtStd)
B-splines and Bézier Patches
Collision Detection
Potentially Visible Sets (PVS)
Geometry Conditioning
RenderWare Graphics 3.5
I-3
Foreword
Volume III covers the utility libraries, which offer a variety of useful functionality and
an in-depth coverage of PowerPipe, the key to customizing RenderWare for ultimate
performance and unique functionality for your application.
•
•
•
•
•
2D Graphics Toolkits
Maestro
The User Data Plugin, on exporting user data
PowerPipe Overview
Pipeline Nodes
Platform specific documentation is included for PlayStation 2, Xbox and GameCube.
PlayStation 2:
• PS2All Overview
• Pipeline Delivery System (PDS)
Xbox:
• Multi-texturing in MatFX
• Multi-texturing on Xbox
• Xbox State Cache
• Xbox Pixel Shaders
• Xbox Vertex Format Compression
GameCube:
• Multi-texturing in MatFX
• Multi-texturing on GameCube
We realize that this User Guide does not cover every single feature in RenderWare
Graphics, but we hope you will find it useful.
Please let us know what you think and feel free to offer any suggestions.
Regards,
The RenderWare Graphics Team
I-4
22 April 2003
Table of Contents
Table of Contents
Chapter 1 - Introduction ....................................................................................... 11
1.1
1.2
1.3
1.4
Welcome to RenderWare Graphics .................................................................12
1.1.1
What you Should Know ...................................................................... 12
1.1.2
What is RenderWare Graphics? ........................................................... 13
1.1.3
Design philosophy ............................................................................. 14
The RenderWare Graphics SDK ......................................................................16
1.2.1
Libraries and Header Files .................................................................. 16
1.2.2
Examples ......................................................................................... 17
1.2.3
Documentation ................................................................................. 18
1.2.4
Artists Tools ..................................................................................... 18
1.2.5
Open Export Framework .................................................................... 19
RenderWare Graphics Architecture .................................................................20
1.3.1
The Core Library, Plugins and Toolkits ................................................. 20
1.3.2
PowerPipe ........................................................................................ 23
1.3.3
Namespaces ..................................................................................... 23
1.3.4
Just Graphics.................................................................................... 24
1.3.5
Objects ............................................................................................ 24
Creating A Scene .........................................................................................26
1.4.1
Step-by-Step.................................................................................... 26
1.4.2
Platform Abstraction .......................................................................... 27
Part A - Core Library ............................................................................................. 29
Chapter 2 - Fundamental Types............................................................................. 31
2.1
Introduction ................................................................................................32
2.2
RenderWare Graphics & Objects ....................................................................33
2.2.1
RenderWare Graphics Objects............................................................. 33
2.2.2
Object Instantiation........................................................................... 33
2.2.3
Object Destruction & Reference Counters ............................................. 34
2.3
The Boolean Type ........................................................................................36
2.4
Characters ..................................................................................................37
2.5
Integer Types..............................................................................................38
2.6
Real Types ..................................................................................................40
2.7
Vectors.......................................................................................................41
2.7.1
Two Dimensional Vectors ................................................................... 41
2.7.2
Three Dimensional Vectors ................................................................. 42
2.8
Coordinate Systems .....................................................................................43
2.9
Coordinate Systems .....................................................................................44
2.9.1
Right-handed Coordinates .................................................................. 44
2.9.2
Object Space .................................................................................... 46
2.9.3
World Space ..................................................................................... 47
2.9.4
Camera Space .................................................................................. 47
2.9.5
Device Space.................................................................................... 47
RenderWare Graphics 3.5
I-5
User Guide
2.10 Matrices ..................................................................................................... 49
2.10.1
Matrix Mathematics in RenderWare Graphics ...................................... 49
2.11 Frames....................................................................................................... 51
2.11.1
Hierarchical Models & RenderWare Graphics ....................................... 52
2.11.2
Traversing Frame Hierarchies ........................................................... 53
2.11.3
Matrix Combination Flags in RenderWare Graphics .............................. 54
2.12 Bounding Boxes........................................................................................... 56
2.13 Lines.......................................................................................................... 57
2.14 Rectangles .................................................................................................. 58
2.15 Spheres...................................................................................................... 59
2.16 Colors ........................................................................................................ 60
Chapter 3 - Initialization & Resource Management ............................................... 61
3.1
Introduction ................................................................................................ 62
3.2
Basic Housekeeping ..................................................................................... 63
3.3
3.4
3.2.1
Initialization ..................................................................................... 63
3.2.2
Shutting down RenderWare Graphics................................................... 68
3.2.3
Changing Video Modes after Initialization ............................................. 69
Memory Management................................................................................... 70
3.3.1
The OS-level Memory Interface........................................................... 70
3.3.2
FreeLists .......................................................................................... 71
3.3.3
Resource Arenas ............................................................................... 73
3.3.4
Locking and Unlocking data ................................................................ 74
Summary ................................................................................................... 76
3.4.1
Starting The Engine........................................................................... 76
3.4.2
Shutting Down The Engine ................................................................. 76
3.4.3
Memory Handling .............................................................................. 77
3.4.4
Plugins ............................................................................................ 77
Chapter 4 - Plugin Creation & Usage ..................................................................... 79
4.1
Introduction ................................................................................................ 80
4.2
Using Plugins .............................................................................................. 81
4.2.1
4.3
4.4
Attaching Plugins .............................................................................. 81
Creating Your Own Plugins............................................................................ 83
4.3.1
Introduction ..................................................................................... 83
4.3.2
Anatomy of a Plugin .......................................................................... 83
4.3.3
The "Plugin" Example ........................................................................ 83
4.3.4
Using the Physics Plugin .................................................................... 86
Plugin Design .............................................................................................. 89
4.4.1
Introduction ..................................................................................... 89
4.4.2
Extension vs. Derivation .................................................................... 89
4.4.3
Deriving new objects ......................................................................... 89
4.4.4
Plugins & C++ .................................................................................. 90
Chapter 5 - The Camera ........................................................................................ 93
5.1
Introduction ................................................................................................ 94
5.1.1
I-6
The Camera Example ......................................................................... 94
22 April 2003
Table of Contents
5.2
The RenderWare Graphics Camera object .......................................................95
5.2.1
Camera Properties............................................................................. 95
5.2.2
The View Frustum ............................................................................. 96
5.2.3
The View Window .............................................................................. 97
5.2.4
The View Offset .............................................................................. 100
5.2.5
Fog ............................................................................................... 100
5.3
The Camera View Matrix ............................................................................. 103
5.4
Rasters & Cameras .................................................................................... 104
5.5
Creating a Camera ..................................................................................... 105
5.5.1
Orienting and Positioning a Camera in Scene Space............................. 105
5.6
Rendering to a Camera............................................................................... 107
5.7
Sub-Rasters .............................................................................................. 109
5.8
Other Features .......................................................................................... 110
5.9
World Plugin Extensions.............................................................................. 111
5.9.1
Automatic & Manual Culling .............................................................. 111
5.9.2
Clump Cameras .............................................................................. 111
5.9.3
Iterators ........................................................................................ 111
Chapter 6 - Rasters, Images and Textures .......................................................... 113
6.1
Introduction .............................................................................................. 114
6.2
Bitmaps & Textures.................................................................................... 115
6.3
6.2.1
Bitmaps ......................................................................................... 115
6.2.2
Images .......................................................................................... 115
6.2.3
Rasters .......................................................................................... 115
6.2.4
Textures ........................................................................................ 116
The Image Object ...................................................................................... 117
6.3.1
Image Dimensions .......................................................................... 117
6.3.2
Stride ............................................................................................ 117
6.3.3
Palettes ......................................................................................... 117
6.3.4
Gamma Correction .......................................................................... 117
6.3.5
Creating Images ............................................................................. 118
6.3.6
Example: Reading a BMP file ............................................................ 119
6.3.7
Reading the Image .......................................................................... 120
6.3.8
Image Processing............................................................................ 121
6.3.9
Raster Conversion ........................................................................... 123
6.3.10
6.4
6.5
Destroying Images ........................................................................ 123
The Raster Object ...................................................................................... 124
6.4.1
Basic Properties .............................................................................. 124
6.4.2
The Raster as a Display Device ......................................................... 127
6.4.3
Rendering Rasters ........................................................................... 128
6.4.4
Accessing Rasters ........................................................................... 129
6.4.5
Reading Rasters from disk................................................................ 129
Textures & Rasters..................................................................................... 130
6.5.1
Introducing Textures ....................................................................... 130
6.5.2
Loading Textures ............................................................................ 134
6.5.3
Texture Dictionaries ........................................................................ 136
6.5.4
Using Texture Dictionaries................................................................ 137
RenderWare Graphics 3.5
I-7
User Guide
6.5.5
Platform independent texture dictionaries .......................................... 138
6.5.6
Using PI texture dictionaries............................................................. 138
6.5.7
Non-fixed hardware issues with texture dictionaries ............................ 139
6.5.8
Textures & Binary Streams............................................................... 139
Chapter 7 - Immediate Mode ...............................................................................141
7.1
Introduction .............................................................................................. 142
7.1.1
7.2
7.3
7.4
Properties & Render States .............................................................. 142
2D Immediate Mode................................................................................... 143
7.2.1
Basic Concepts ............................................................................... 143
7.2.2
Initializing an RwIm2DVertex object .................................................. 145
7.2.3
Primitives....................................................................................... 147
7.2.4
Triangle Winding Order .................................................................... 148
7.2.5
Primitives vs. Indexed Primitives....................................................... 149
7.2.6
Example 1: Rendering A Line............................................................ 150
3D Immediate Mode................................................................................... 152
7.3.1
Preparation for Rendering ................................................................ 152
7.3.2
Rendering ...................................................................................... 154
7.3.3
Closing the pipeline ......................................................................... 156
7.3.4
3D Immediate Mode & PowerPipe...................................................... 156
7.3.5
Platform Specific Information ........................................................... 157
7.3.6
Camera-space and Z-buffer depth equations ...................................... 158
7.3.7
Rt2D ............................................................................................. 159
Render States ........................................................................................... 160
7.4.1
Key Features .................................................................................. 160
7.4.2
API................................................................................................ 160
7.4.3
Blending ........................................................................................ 163
7.4.4
Sorting Alpha Primitives................................................................... 164
7.4.5
164
Chapter 8 - Serialization ......................................................................................165
8.1
Introduction .............................................................................................. 166
8.2
File I/O API ............................................................................................... 167
8.3
RenderWare Binary Streams ....................................................................... 169
8.4
8.3.1
Binary Stream Structure .................................................................. 169
8.3.2
Serializing Objects .......................................................................... 171
8.3.3
Explicit Streaming Functions............................................................. 176
8.3.4
RWS files ....................................................................................... 180
8.3.5
Stream Types ................................................................................. 182
Summary ................................................................................................. 183
8.4.1
File I/O API .................................................................................... 183
8.4.2
RenderWare Binary Streams............................................................. 183
Chapter 9 - Debugging and Error Handling...........................................................185
I-8
9.1
RenderWare Graphics Errors ....................................................................... 186
9.2
RenderWare Graphics Builds ....................................................................... 187
9.3
The Debug Object ...................................................................................... 188
22 April 2003
Table of Contents
9.3.1
The Default Debug Stream Handler ................................................... 188
9.3.2
Sending a Message to the Debug Stream ........................................... 189
9.4
Tracing RenderWare Graphics Activity .......................................................... 190
9.5
Replacing The Stream Handler.......................................................................... 192
9.5.1
Example ........................................................................................ 192
Part B - World Library ......................................................................................... 195
Chapter 10 - World and Static Models ................................................................. 197
10.1 Introduction .............................................................................................. 198
10.2 Scenes & Static Models............................................................................... 199
10.2.1
Scenes ......................................................................................... 199
10.2.2
RpWorld Object ............................................................................. 199
10.2.3
RpWorldSector Object .................................................................... 200
10.3 Iterator Functions ...................................................................................... 201
10.3.1
RpWorld Iterators.......................................................................... 201
10.3.2
RpWorldSector Iterators ................................................................. 202
10.3.3
Collision Detection ......................................................................... 202
10.4 Modeling Tools .......................................................................................... 203
10.4.1
Viewers ........................................................................................ 203
10.5 Creating Worlds......................................................................................... 204
10.5.1
Creating Worlds from Foreign Data .................................................. 204
10.5.2
What is Pre-lighting?...................................................................... 210
10.6 Rendering ................................................................................................. 212
10.6.1
How to Render Worlds ................................................................... 212
10.6.2
Instancing .................................................................................... 212
10.6.3
Pre-instancing Static Geometry ....................................................... 213
10.7 Serialization .............................................................................................. 215
10.7.1
Writing......................................................................................... 216
10.7.2
Reading ....................................................................................... 217
10.8 Destruction ............................................................................................... 218
Chapter 11 - Dynamic Models.............................................................................. 219
11.1 Introduction .............................................................................................. 220
11.2 The World Plugin ....................................................................................... 221
11.2.1
The Geometry Object..................................................................... 221
11.2.2
The Atomic Object ......................................................................... 221
11.2.3
The Clump Object.......................................................................... 222
11.2.4
Clump Destruction ......................................................................... 224
11.3 Creation of Dynamic Models ........................................................................ 225
11.3.1
Model Creation Overview ................................................................ 225
11.4 Modeling Tools .......................................................................................... 226
11.4.1
Exporters ..................................................................................... 226
11.4.2
Viewers ........................................................................................ 226
11.4.3
Procedural Model Creation .............................................................. 227
11.4.4
Vertices & Triangles ....................................................................... 227
11.4.5
Textures & Materials ...................................................................... 229
RenderWare Graphics 3.5
I-9
User Guide
11.4.6
Surface Properties & Geometry ....................................................... 231
11.4.7
Morph Targets .............................................................................. 232
11.4.8
Pentagons & Hexagons .................................................................. 233
11.4.9
Bounding Spheres & Transformations .............................................. 234
11.4.10 Atomics and Clumps ...................................................................... 236
11.5 Objects in more detail ................................................................................ 237
11.5.1
Reference Counting ....................................................................... 237
11.5.2
Texture coordinates....................................................................... 237
11.5.3
Prelighting.................................................................................... 238
11.5.4
Surface properties ......................................................................... 238
11.5.5
Meshes ........................................................................................ 238
11.6 Atomics, Clumps & Transformations ............................................................. 240
11.6.1
Worlds ......................................................................................... 240
11.6.2
Cloning ........................................................................................ 240
11.6.3
Iterator functions .......................................................................... 241
11.6.4
Sorting Geometry objects by Material .............................................. 243
11.6.5
Animation .................................................................................... 244
11.6.6
Skinned Models............................................................................. 245
11.7 Optimization ............................................................................................. 246
11.8 Rendering................................................................................................. 247
11.8.1
How to Render Dynamic Objects ..................................................... 247
11.8.2
Instancing .................................................................................... 248
11.8.3
Pre-instancing Dynamic Geometry................................................... 249
11.8.4
Converting Model Data to RenderWare Graphics................................ 251
Chapter 12 - Lights ..............................................................................................253
12.1 Introduction .............................................................................................. 254
12.1.1
Other Documentation .................................................................... 254
12.2 Dynamic Lights.......................................................................................... 255
12.2.1
Dynamic Lights Representation ....................................................... 256
12.2.2
Creating a dynamic light ................................................................ 257
12.2.3
Clump Lights & Streaming .............................................................. 260
12.2.4
Platform-Specific Lighting Models .................................................... 260
12.3 Static Lights using RpLight.......................................................................... 262
12.3.1
Creating Static Lights .................................................................... 262
12.3.2
Static Lighting Techniques .............................................................. 263
12.4 Related Examples ...................................................................................... 265
12.5 Summary ................................................................................................. 268
12.5.1
Dynamic Lights ............................................................................. 268
12.5.2
Static Lights ................................................................................. 269
Index ...................................................................................................................271
I-10
22 April 2003
Chapter 1
Introduction
Chapter 1 - Introduction
1.1Welcome to RenderWare Graphics
Welcome to the RenderWare Graphics User Guide!
RenderWare Graphics is a powerful 3D graphics library. This User Guide is
aimed at helping newcomers to RenderWare Graphics become familiar with
the product. This is in addition to the on-line help, and support that is
offered with the purchase of any RenderWare Platform component.
RenderWare Graphics is the result of many years of development, which
began in 1991. The power and flexibility of the product has been increased
with every release. RenderWare Graphics is a multi-platform Application
Programming Interface (API), which is constantly being improved and
updated to keep it at the cutting edge of 3D graphics.
To support the community of developers in the field, we offer our Fully
Managed Support System. Accessible via a personalized web interface, this
allows our technical support personnel to be contacted, the status of
outstanding queries to be tracked, and our knowledge base to be searched
and viewed, plus lots of other useful information. To find out more and
register for the service, point your browser at
https://support.renderware.com/.
If you are new to RenderWare Graphics, it is strongly suggested that you
read this User Guide as you go along to acquaint yourself with its
operation.
Similarly, if you've already been using RenderWare Graphics for a while,
stick around! The User Guide is written by the people who created the
library, so you might gain new insights, tricks and tips. Additionally it has
been revised and expanded to cover all our latest new technology.
RenderWare Graphics is a module of Criterion Software's RenderWare
Platform, the tailored set of open and extensible middleware tools which
allows you to focus on content and gameplay. For further information on
the other Components (including RenderWare Audio, RenderWare AI and
RenderWare Physics) please visit www.renderware.com or contact your
account manager.
1.1.1
What you Should Know
This User Guide makes some assumptions about your level of proficiency
with real-time 3D graphics programming:
•
I-12
This Guide is not aimed at complete newcomers to the field of computer
graphics. If you are new to all this, check out the Recommended
Reading appendix for links to online articles and books you can use as
a starting point.
22 April 2003
Welcome to RenderWare Graphics
•
Secondly, this User Guide will not go into detail about the mathematics
upon which most 3D graphics programming is founded. The whole
point of graphics libraries such as RenderWare Graphics is to do the
math for you.
That said, some college-level math is required to understand some
concepts. If your knowledge of the principles and practices of matrix
and vector manipulation is limited, the Recommended Reading
appendix contains pointers to relevant texts that can help you with this
area.
1.1.2
•
This User Guide assumes you are an experienced programmer with a
thorough knowledge of the C (or C++) programming language. You
should also be comfortable with the concepts behind object-oriented
programming.
•
The User Guide is platform-neutral so it will not cover any specific
development environment. Platform-specific variations and optimization
notes will be provided in an appendix.
What is RenderWare Graphics?
•
A graphics library
RenderWare Graphics is a 2D and 3D graphics API. It is used by
programmers to create real-time 3D graphics applications, such as
computer games and simulations.
•
Multi-platform
RenderWare Graphics has multi-platform, portable API that allows high
level functionality to be achieved on all platforms, with platform specific
optimizations to get the best from the hardware pipelines.
RenderWare Graphics is available for Sony PlayStation 2, Microsoft
Xbox, NINTENDO GAMECUBE, Microsoft Windows (Direct3D 8),
Microsoft Windows (OpenGL) and Apple MacOS (OpenGL).
•
Customizable
RenderWare Graphics has a component-based approach to its
architecture based around a small-footprint, thin-layer core library,
supplemented by a number of Plugins and Toolkits.
Plugins are the key to RenderWare Graphics' power; they can extend
existing objects and add new objects of their own that can also be
further extended.
Even the Retained Mode API is a Plugin, which gives RenderWare
Graphics the unique feature of being the only 3D graphics library that
can support any number of Retained Mode APIs.
RenderWare Graphics 3.5
I-13
Chapter 1 - Introduction
Further, this Plugin mechanism is fully exposed. You can write your
own Plugins, extending and adding objects, for your own requirements we even encourage you to do so, as we do not claim to have thought of
everything!
•
Compatible with many third-party tools and middleware
RenderWare Graphics is a module of Criterion Software's RenderWare
Platform, the tailored set of middleware tools offering a tightly
integrated game development framework, which includes graphics,
audio and physics modules, with other Components planned for
availability in the future.
1.1.3
Design philosophy
The design brief for RenderWare Graphics was to create a 3D graphics
library that would never be obtrusive. We have tried hard to make sure the
library is the most powerful multi-platform 3D library available.
Platform Independent Development
RenderWare Graphics has been designed from the ground up to let you get
the most out of all its supported platforms – with no compromises. APIs are
provided which expose low-level features and optimization opportunities to
the developer, so the best performance can be obtained from your projects.
The price for this is a little extra work during the porting process: each
platform has different hardware, and different advantages and
disadvantages. RenderWare Graphics gives you the freedom to choose how
far you go down the optimization route:
•
Need to create a product quickly for more than one platform? No
problem: use the common API features – the facilities provided as
standard across all platforms – and treat it as an ordinary crossplatform library.
•
Alternatively, writing custom PowerPipe nodes and plugins enables
RenderWare Graphics to be fine-tuned to specialized performance
requirements. The purchase of a source code license gives the developer
ultimate control over RenderWare Graphics.
RenderWare Graphics gives you the freedom to take either route, or indeed
any path between these two extremes.
Such flexibility does come at a price: where platform-specific features of
RenderWare Graphics are chosen, the code for each target platform will
need to be changed when porting.
C vs. C++
One of the most common questions asked about RenderWare Graphics is
the choice of programming language: C.
I-14
22 April 2003
Welcome to RenderWare Graphics
There are two reasons for choosing to write RenderWare Graphics in the C
programming language. The first is that there is no standard for C++
libraries; RenderWare Graphics would have to be shipped as a separate set
of libraries for each supported compiler, as well as each platform. Clearly,
this would complicate product support.
Secondly, while C++ has many, many great features, most new platforms –
particularly consoles – don't get a stable, mature C++ compiler until long
after they get a good C compiler. In order for a new platform to be worked
on as soon as possible, the fastest way to achieve this is to use a mixture of
highly optimized C and assembly language.
That said, it is quite possible to mix C and C++. The Plugin mechanism lets
you add space for 'this' pointers to RenderWare Graphics objects with
minimal fuss, and all RenderWare Graphics' header files have the requisite
"extern 'C'" directives to allow the two languages to mix seamlessly.
Several of our licensees have also produced their own C++ wrapper classes
to encapsulate RenderWare Graphics in order to develop in a 'pure' C++
environment.
RenderWare Graphics 3.5
I-15
Chapter 1 - Introduction
1.2The RenderWare Graphics SDK
1.2.1
Libraries and Header Files
RenderWare Graphics is supplied as a number of libraries on the Software
Development Kit (SDK). Applications will need to link against these libraries
and #include the associated header files.
All RenderWare Graphics libraries are static.
Each platform is provided with its own headers and libraries. In addition,
the SDK contains null libraries, which are used by exporters and other
tools. These are provided with all platforms. The null libraries contain all
the PC functionality, but do not perform any rendering.
A NULL target DLL is also provided that the art tools exporters make use of.
This DLL contains almost all of the static NULL libraries.
Null Libraries
✎
On Xbox, GameCube and PlayStation 2 null and nullplatform libraries are also built. For
example, PlayStation 2 RenderWare Graphics SDK is supplied with null and nullsky
libraries. These PC libraries are required for certain tools that process platform specific
data. They can be used for the generation of texture dictionaries.
It should be noted that nullplatform libraries can not create pre-instanced and geometry
data.
Debug, Metrics and Release Libraries
For each platform, separate debug, metrics and release builds of the
RenderWare Graphics libraries are also provided. Debug, release and
metrics libraries live in separate folders inside the rwsdk/lib folder.
RWDEBUG and RWMETRICS preprocessor symbols must be used to indicate
which build is being used.
It is crucial that you do not mix symbols and libraries between these
builds. To illustrate, some API calls are implemented in release builds as
macros. In debug builds these calls are really implemented as functions.
This can mean that if you define the RWDEBUG preprocessor symbol, but link
with the release build of the library you will get numerous "undefined
symbol" link errors.
Compilers supported
Please see the appropriate platform specific top-level readme files supplied
with the RenderWare Graphics SDK for information on the compilers
supported by RenderWare Graphics.
SN Systems, Visual Studio IDE integration and Project Files
The RenderWare Graphics SDK provides full support for the SN Systems
Visual Studio Integration features.
I-16
22 April 2003
The RenderWare Graphics SDK
Project Build Target settings are included for all platforms supported via
Visual Studio. Developers should ensure the correct Project Build Target is
selected.
1.2.2
Examples
The SDK contains nearly 50 source code examples. Examples are small and
designed to illustrate a particular technique or feature of the RenderWare
Graphics API. They are intended as a means of education: we encourage
you to look through the source code and play with them.
Tools & Viewers
Also included are tools and viewers for you to use during development. Of
particular note is the RenderWare Visualizer viewer, which allows you to
easily view RenderWare Graphics artwork on any target hardware.
Two other viewers are also available for viewing artwork: 'wrldview', and
'clmpview'. 'wrldview' displays static models created for the Retained
Mode API, and 'clmpview' displays dynamic models.
RenderWare Graphics uses a single file format, using chunk-IDs, which is
capable of storing any one or more RenderWare Graphics objects. The
RenderWare Graphics Binary Stream format can be viewed using the
'strview' applet supplied with the SDK.
A Microsoft Visual Studio 6 AppWizard is also supplied with RenderWare
Graphics that can be used to generate an MFC framework-based clump or
world viewer. This AppWizard can be incorporated into Microsoft Visual
C++ and used in the same manner as the standard Microsoft AppWizards.
Please see the accompanying documentation describing how to build a
RenderWare Graphics viewer.
Building the Examples
The examples that are shipped on the SDK should not need compiling to
run them. If you modify them, you will want to re-build the executables.
The Project files provided with the tools and examples are not necessarily
set for your particular platform so make sure you select the correct build
configuration prior to compilation. The two screen shots below show the
Integrated Development Environments (IDEs) and the build targets that
they offer. In Visual Studio, you will need to select the correct Project
Configuration; in CodeWarrior, you must select the correct Target. Further,
there are separate release, debug, and metrics builds. Unless you have
good reason not to, it is suggested that you select:
•
Win32 D3D8 Release project in Visual Studio for the PC
•
Xbox Release in Visual Studio for Xbox.
RenderWare Graphics 3.5
I-17
Chapter 1 - Introduction
•
PS2 Release in CodeWarrior for the PlayStation 2
•
GCN Release in CodeWarrior for GameCube
Visual Studio
1.2.3
CodeWarrior
Documentation
Documentation is provided in both online and PDF formats. The PDF
format is intended for printing only and is not hyperlinked. The PDF files
have been setup for double sided printing.
The following documentation is provided in the SDK:
•
This User Guide
•
API Reference
•
Tutorials (PC only)
•
White Papers
•
Exporter Guides for artists and programmers
•
Tools and Viewers documentation
•
Examples document listing all examples with brief explanation
•
readme_xxx.pdf
All the examples and tools have a related readme.txt file. It is highly
recommended that you read these for information about any last-minute
changes or features.
There is also the top-level SDK readme_xx.pdf file, where xxx is the
platform name, which lists last-minute changes, fixes and known issues
and can be found in the root of the SDK.
1.2.4
Artists Tools
The RenderWare Graphics installer can be used to install the artists' tools.
These tools are exporter plugins for exporting 3D model data from packages
such as 3ds max and Maya.
I-18
22 April 2003
The RenderWare Graphics SDK
When installed, artists will find:
✎
1.2.5
•
The modeling package's RenderWare Graphics exporter plugin(s)
•
Sample artwork demonstrating optimal modeling techniques
•
Documentation covering how to create and export models successfully
for RenderWare Graphics.
It is strongly recommended that programmers also read the documentation supplied with
the artists tools. The installer adds links to these docs from the start menu.
Open Export Framework
The RenderWare Graphics programmer installer can be used to install the
Open Export SDK that gives you a powerful way of extending the exporters.
Consisting of a series of modular libraries and custom code hooks, you
could soon be introducing new common classes to the modelers, changing
behaviors or creating new object handlers under our plugin architecture.
To get you started, we have provided the Getting Started section in the
Open Export API Reference document. In addition, we have included six
examples of what you can do with the SDK:
•
ExportObject - An example of a custom object exporter optimizes
the exported textures, by making sure that all texture sizes are beneath
a certain threshold.
•
MaxSimple - An example of how to write your own custom builder
and export application. To demonstrate this we used a simplified
3dsmax exporter.
•
PostProcess – An example demonstrates how to post process the
entire list of exported RenderWare Graphics assets, and how to
customize the stream process for streaming them out.
•
ScaleAnim - This example adds support for animated scale to the
RwExp layer.
•
TravAction - Demonstrates the use of traverse actions together
with traverse lists that filters out all nodes containing a certain name.
•
VertexFilter - An example of a vertex filter which pre-lights a
scene by applying per vertex operations.
RenderWare Graphics 3.5
I-19
Chapter 1 - Introduction
1.3RenderWare Graphics Architecture
The diagram below shows how the RenderWare Graphics library fits into a
typical application.
Application
RW Plugin
Toolkit
Plugin
RW Plugin
RW Toolkit
RW Toolkit
RpWorld
RwCore
Hardware
Abstracting the underlying hardware is the RenderWare Graphics Core
Library. Above this is the world plugin. This is the largest and most widely
used of the optional RenderWare Graphics modules. Various plugins
provided with the SDK are shown adding functionality. Also shown are
toolkits, both supplied with the SDK, and non-RenderWare Graphics
Toolkits supplied by third parties. A third party plugin is also shown. Above
these components is the application which uses the services (functions)
exposed by the various components.
The gray boxes above that labeled RwCore are optional. Unlike monolithic
3D graphics libraries, most of the higher-level features can be omitted.
Although it's not explicitly stated in the diagram, RpWorld, which provides
the Retained Mode API, is itself just a Plugin.
1.3.1
The Core Library, Plugins and Toolkits
The RenderWare Graphics components can be broken down:
1. Core Library
2. Plugins
3. Toolkits
The first is the Core Library. The Core Library must always be linked into
your application as it provides the glue that joins all the components
together, as well as basic rendering functionality.
I-20
22 April 2003
RenderWare Graphics Architecture
Plugins
These are the keys to RenderWare Graphics extensibility. Plugins can
extend existing objects in both the Core Library and other Plugins – and
add their own objects. This feature is what differentiates them from
ordinary libraries. RenderWare Graphics' high-level APIs are all
implemented as Plugins.
Supplied Plugins
The following Plugins are supplied as standard with all releases of the SDK:
PLUGIN
DESCRIPTION
RpADC
RpAnisot
RpCollision
RpDMorph
RpHAnim
RpLODAtomic
Address Control flag generation
Anisotropy extension for extending textures
Collision-detection extensions
Delta morphing and delta animation extensions
Hierarchical animation plugin
Level Of Detail extensions for RpWorld's "RpAtomic"
object
Render geometry using detailed static lighting
information from lightmap textures.
Multi-pass special effects, such as environmental
mapping, bump mapping, 2-pass
Texture mipmap "K" and "L" value extensions
Morph-target animation extensions
Bézier patch rendering engine
Particle animation plugin
Creation, management and rendering of user
customizable particles
Fast visibility culling extension for RpWorld, using
Potentially Visible Sets
Platform-neutral random number generator
Skinned model rendering extensions with multiple bone
weights per vertex
Spline manipulation extensions
Provides functionality for storing user defined data with
geometry
Provides RenderWare Graphics' Retained Mode API –
specifically, the scene graph portion of it
RpLtMap
RpMatFX
RpMipmapKL
RpMorph
RpPatch
RpPrtStd
RpPTank
RpPVS
RpRandom
RpSkin
RpSpline
RpUserData
RpWorld
RenderWare Graphics 3.5
I-21
Chapter 1 - Introduction
Toolkits
A Toolkit is an ordinary library that just happens to make use of
RenderWare Graphics features. A Toolkit usually provides conversion
functions or other utilities.
Supplied Toolkits
The following Toolkits are supplied as standard with all releases of the SDK:
TOOLKIT
DESCRIPTION
Rt2d
Advanced 2D Graphics API utilizing underlying 3D
graphics hardware
Animation of 2D objects
Create, stream and play keyframe animation.
Mapping points between the barycentric space and
Cartesian space
Bézier patch generation utility library
Microsoft® Windows® Bitmap image format handling
A bitmapped character library
Keyframe system supporting compressed matrix
animation
Geometry Conditioning
Polygon and line intersection testing functions
Generation of lightmap textures - used with RpLtMap
Texture mipmap "K" value calculation functions
Object-picking functions
Platform independent texture dictionary streaming
Portable Network Graphics image format handling
Quaternion manipulation functions
Sun® Raster image format handling
Ray-casting functions used for picking
Skin & Geometry splitter for large bone count models
Spherical Linear Interpolation functions
Utility functions to allow PVS generation using spline
paths
Tag Image File Format image format handling
Tiled rendering functions (used mainly for very highresolution renderings)
Table Of Contents for a stream
Vertex Cache Aware Tri-stripper
Winged edge/half-edge
Utility functions to be used in conjunction with RpWorld
Utilities for creating RpWorld objects from foreign data
formats
Rt2dAnim
RtAnim
RtBary
RtBezPat
RtBMP
RtCharset
RtCmpKey
RtGCond
RtIntersection
RtLtMap
RtMipK
RtPick
RtPITexd
RtPNG
RtQuat
RtRAS
RtRay
RtSkinSplit
RtSlerp
RtSplinePVS
RtTIFF
RtTile
RtTOC
RtVCAT
RtWing
RtWorld
RtWorldImport
I-22
22 April 2003
RenderWare Graphics Architecture
1.3.2
PowerPipe
PowerPipe provides a means of overloading the rendering subsystem either
wholly or piecemeal. You can replace or even create entirely new rendering
pipeline nodes and clusters.
1.3.3
Namespaces
All the RenderWare Graphics functions and objects carry two-letter prefixes
to prevent naming clashes with your own code. This has been used to
provide the best compromise between readability and name length.
The prefixes depend on whether the object in question is part of the Core
Library, part of a Plug-in, or part of a Toolkit. They are:
PREFIX
DESCRIPTION
'Rw'
Indicates a function situated in the RenderWare Graphics
Core Library ("rwcore.h" / "rwcore.lib"). These functions
are always available as long as the core RenderWare
Graphics library is linked to your application.
Examples:
RwEngineStart()
RwCameraCreate()
'Rp'
Indicates a function situated in a Plugin library (e.g.
RpMorph.) In most cases, the name of the Plugin follows the
prefix, but this guideline is sometimes ignored to keep
function names sensible.
The appropriate Plugin must be attached if you intend to use
these functions and linked to the appropriate header and
library files.
Examples:
RpMorphPluginAttach()
'Rt'
RpPVSAtomicVisible()
Indicates a Toolkit. Syntax is similar to that of Plugins,
described above.
Many Toolkits rely on one or more Plugins being attached,
but Toolkits themselves do not need to be attached.
Examples:
RtSlerpCreate()
'Rx'
RtTileRender()
Used by the PowerPipe API.
Examples:
RxHeapFree()
RxPipelineExecute()
'Rs'
Source code to a simple (and very basic) platform abstraction
layer used for all examples is provided. Major functions in
this layer use an 'Rs' prefix.
Exceptions
These include constants, such as #defines and enum
values. These generally use the same prefixes as above, but
entirely in lower case, followed by an all-caps name, such as:
rwRASTERTYPECAMERA.
RenderWare Graphics 3.5
I-23
Chapter 1 - Introduction
1.3.4
Just Graphics
This may seem obvious, but it is important to remember that RenderWare
Graphics only provides multi-platform 3D graphics features. While some
utilities are provided, such as an abstraction layer known as the 'Skeleton',
this code is not officially supported.
Most developers will create their own abstraction layers and write suitable
plugins for RenderWare Graphics to provide a consistent programming
interface across their supported platforms.
1.3.5
Objects
As RenderWare Graphics is written in C and assembler, it makes objectoriented design that little bit harder to implement. C++ classes might need
to be written to wrap the RenderWare Graphics API.
One important issue to consider is the definition of an object in RenderWare
Graphics.
In C++, objects are an explicit part of the language's design. RenderWare
Graphics 'objects' are either intrinsic, such as int and char, or an ordinary
C struct. These usually have a noun for a name – e.g. World, Clump, and
Vector. The methods or member functions associated with these objects are
ordinary C functions that live outside these structures, but with names
that begin with the same name as the 'object'.
For instance, a hypothetical object called RwThing might have methods
with names like RwThingGetProperty().
RenderWare Graphics objects have been designed to operate in much the
same way as C++ objects. The main difference is that there are no member
selection operators to separate object names from their associated methods.
I-24
22 April 2003
RenderWare Graphics Architecture
Objects & Properties
Transparent vs. Opaque Objects
RenderWare Graphics developers sometimes make a simple object
transparent. This means that you will find complete documentation of the
internals of said object in the API Reference and (usually) no propertyaccess functions. The point of this is to reduce unnecessary function calling
overheads: you are free to directly change the individual object elements.
This reveals the element of trust enshrined with RenderWare Graphics'
design: where a data structure is not explicitly documented, it should be
considered an opaque object. Usually, such objects will have no
documentation for their individual members; so only their associated
property access methods (using the traditional 'Get' and 'Set' convention)
should be used.
The table below shows some examples of opaque objects and access to their
members:
OBJECT
PROPERTY
'METHOD' NAME
RwCamera
ViewWindow
RpAtomic
Geometry
RwCameraGetViewWindow()
RwCameraSetViewWindow()
RpAtomicGetGeometry()
RpAtomicSetGeometry()
The objects name always forms the root of the function name. This pattern
is followed consistently throughout the RenderWare Graphics API.
Obviously, the various header files document all members of a particular
struct. In general, these members should not be modified in your code,
but instead use the functions that are supplied in the library.
✎
Of course, C doesn't automatically pass the object instance to the functions, so you still
have to do this explicitly. Usually, the first parameter of a function will be a pointer to the
object.
RenderWare Graphics 3.5
I-25
Chapter 1 - Introduction
1.4Creating A Scene
1.4.1
Step-by-Step
To render scenes in RenderWare Graphics applications, a number of steps
need to be performed:
1. Create assets in a modeling package.
This includes the background scenery and all the characters, props and
other animated models that will populate that scenery. Textures may
need creating in a paint package.
2. Export assets in the RenderWare Graphics format.
The RenderWare Graphics Retained Mode API supports two kinds of
model: static models that live in World objects, and dynamic models that
live in Atomic objects.
Backgrounds and other fixed scenery models are generally considered
static; all other models are dynamic. To add dynamic scenery elements, you
should use dynamic models and position them in the scene accordingly.
These objects are part of the high-level RpWorld Plugin that encapsulates
our Retained Mode API. More on this powerful Plugin can be found in the
two chapters: Worlds & Static Models and Dynamic Models.
3. Load assets into the RenderWare Graphics application.
RenderWare Graphics includes a multi-platform file serialization API –
RwStream – that is used for this purpose.
4. Position them using frames.
Frames, described in the Fundamental Types chapter, are an essential
feature of the RenderWare Graphics architecture. They are attached to
objects so they can be positioned in world space. Frames also manage
model hierarchies.
5. Create lights.
RenderWare Graphics supports a number of lighting models, as well as
both static and dynamic lights, and the standard light model can be
overridden.
6. Create a camera object and orient it.
RenderWare Graphics uses the standard virtual camera metaphor in
the Retained Mode API. This API, and Cameras in general, can be found
in the following chapters: Cameras; Worlds & Static Models and
Dynamic Models.
7. Take a picture.
I-26
22 April 2003
Creating A Scene
This process involves the actual rendering of the scene.
8. Update the scene.
If you're producing real-time animation in 3D, you will need to update
the models between renderings.
9. Repeat steps 7 and 8 until the user tells the application to quit.
This is the rendering process in short. Aside from some of the
terminology specific to RenderWare Graphics, this is much the same as
in any other 3D graphics API.
1.4.2
Platform Abstraction
In order to be able to write our examples and other sample code just once,
without the need to rewrite it for each target platform, the hardware
abstraction layer called the 'Skeleton' has been developed. Almost all the
sample code supplied with the SDK will use this code as its foundation.
The Skeleton was developed for our sample code. It is not suitable for
anything other than similarly simplistic test-beds and prototyping. It is
absolutely, categorically not intended for use as the basis for a professional
application. However, it does provide a convenient set of functions that can
be used for rapid prototyping of games.
The Skeleton code is completely unsupported. The source code to it is
provided to show you that (a) it can be done, and (b) so that all our tools
and examples can be presented in a consistent way.
Put another way: the Skeleton is provided as-is and with no guarantee for
any suitability or fitness for purpose. You use it entirely at your own risk.
File I/O
File handling is an important facet of RenderWare Graphics and for this
reason, we provide a file system that can be overloaded. The
RwOsGetFileInterface() can be used to obtain a structure containing
the pointers to the file operation functions. The file pointers in this
structure can be replaced by pointers to your own, which makes it easier to
divert file-handling to the DVD, host machine and possibly even over a
TCP/IP link.
RenderWare Graphics 3.5
I-27
Part A
Core Library
Chapter 2
Fundamental
Types
Chapter 2 - Fundamental Types
2.1Introduction
This chapter covers many of the basic types that are exposed by
RenderWare Graphics.
Some types are simple and transparent, meaning you can access them and
their elements directly. Others may be opaque and you should use the API
provided to manipulate them.
If your development is intended to run on multiple platforms then it is
suggested that you use RenderWare Graphics' data types throughout your
application. The Core Library implements a number of basic data types,
such as RwChar, RwUInt16 and so on, which means that you can rely on
RenderWare Graphics to ensure that on the different platforms the sizes of
these types are correct.
For example, you can rely on the RwChar to be the correct size on a
particular platform to store characters as these are not guaranteed to be
eight bits on all supported platforms.
I-32
22 April 2003
RenderWare Graphics & Objects
2.2RenderWare Graphics & Objects
The first chapter explained that RenderWare Graphics is designed along
object-oriented principles. As a result, the concept of objects plays an
important part in understanding how the API works.
Before covering the basic data types then, it is worth looking at the
ramifications of this design in a little more detail.
2.2.1
RenderWare Graphics Objects
C is not an object-oriented language, so one question frequently asked of
the development team is why use C? This question was answered in the
previous chapter, but it leaves open the question of how an object-oriented
design is implemented.
By design, the API looks rather like a C++ based one, without all the extra
punctuation. By necessity, the API supports a plugin mechanism which is
used to extend the "objects". This extension mechanism is managed
programmatically rather than as an intrinsic feature of the programming
language.
For example, a look at the RpWorld plugin's API will reveal a number of
base objects: RwTexture, RpClump, RpWorld and so on. Each of these
objects is actually defined as a standard C struct datatype with their
"methods" – functions – defined as ordinary functions separate from the
data structure.
2.2.2
Object Instantiation
This is usually a two-stage process. The first is to define a variable of the
object's type. For example:
RwTexture myTexture;
It is rare for developers to create automatic instances; allocation on the
heap is far more common. This example therefore defines myTexture as an
object of type RwTexture.
However, C does not support a constructor mechanism in the way C++
does, so myTexture has no valid data in it.
To reduce bugs caused by referencing uninitialized objects, RenderWare
Graphics' API usually provides some form of default object creation
function. In the case of Texture objects, the function is
RwTextureCreate(), which generates a new Texture from the given Raster
object and returns a pointer to the Texture on success.
RwTexture myTexture;
RwTexture * pmyTexture = RwTextureCreate();
RenderWare Graphics 3.5
I-33
Chapter 2 - Fundamental Types
Similar creator functions are provided for most RenderWare Graphics
objects and it is advisable to use them where possible.
2.2.3
Object Destruction & Reference Counters
As in C++, RenderWare Graphics objects must be destroyed when you are
finished with them. This is particularly important if you are working on
platforms with limited memory available. However, care is needed to ensure
that you do not destroy objects that are still being referenced elsewhere in
your code…
Although the documentation for RenderWare Graphics talks about things
like container objects, these just boil down to objects that contain lists of
pointers to the objects they contain. The word pointer is emphasized here
because it implies that an object can be referenced by more than one
object.
For example, a Texture can be "contained" by multiple Materials (part of the
World Plugin and a useful container object for Textures), but this just
means these Materials would each contain a pointer to the same Texture.
So far, so obvious, but multiple references can be a problem when it comes
to destroying objects. If a Texture is referenced by multiple objects, some
method is needed to prevent it being destroyed before the other objects
have finished with it.
To avoid this, RenderWare Graphics uses a fairly standard reference
counting system.
For example, if a Texture is referenced by another object, the Texture's
reference counter will be incremented using a call to the Texture's
…AddRef() method. (RwTextureAddRef()) When the Texture is removed
from that object, its counter is decremented. So if the Texture is referenced
by, say, five other objects, its counter will be equal to five.
When the Texture is no longer needed by an object, it should be destroyed
by calling the object's …Destroy() method. (For Textures, the full function
name is RwTextureDestroy().) This function will decrement the reference
counter and, if it is zero, finally destroy the object referred to.
It is important to note that the reference counting system is not fully
automatic. For example, you will need to call …AddRef() and …Destroy()
methods directly if you add a reference to a RenderWare Graphics object to
a structure of your own.
Destruction & Destruction Order
The order in which objects are destroyed is an important consideration.
RenderWare Graphics programming often involves the use of a number of
container objects. A common bug can be brought about by deleting such
containers before deleting the contained objects.
I-34
22 April 2003
RenderWare Graphics & Objects
For example, take the Clump and Atomic objects. These are part of the
scene graph API provided by the World Plugin (RpWorld). For now, it's
important to know only that Clumps are container objects for Atomics.
A common cause of bugs is to destroy a Clump, then destroy each of its
contained objects by referencing through the Clump. Obviously, the Clump
no longer exists at this point, but many programmers assume that the
pointer is still valid as no code has been executed to overwrite the data yet.
This is a bad assumption to make: some platforms, including Microsoft
Windows, have background tasks running which can easily trigger the
overwriting of such data. This is a common cause of intermittent bugs and
crashes, so you should always destroy objects in the correct order.
RenderWare Graphics 3.5
I-35
Chapter 2 - Fundamental Types
2.3The Boolean Type
RenderWare Graphics supports one Boolean type:
I-36
TYPE
DESCRIPTION
RANGE
SIZE
RwBool
A standard Boolean type with the
usual two states
FALSE,
TRUE
32 bits
22 April 2003
Characters
2.4Characters
TYPE
DESCRIPTION
RwChar
Character type, in either ANSI or
Unicode format
RANGE
SIZE
8 bits (ANSI
char) or 16
bits (Unicode)
RwChar is intended solely for storing individual characters and character
strings (usually 8-bit for ANSI libraries and 16-bit for Unicode libraries).
✎
You should never use RwChar * as pointers to memory as it is wrong to assume it will be
equivalent to the C Language "char" type.
Use RwInt8 * or RwUInt8 * instead.
RenderWare Graphics 3.5
I-37
Chapter 2 - Fundamental Types
2.5Integer Types
RenderWare Graphics is intended to run on a number of platforms. To
ensure consistent behavior, new types are defined to replace the base C
Language ones. The RenderWare Graphics replacements are designed to
behave as consistently as possible over all supported platforms.
RenderWare Graphics defines a number of integer types for specific bit
widths, which are shown in the table on the following page.
These data types are designed to behave identically across all supported
platforms. It therefore makes sense to use these instead of the standard C
data types in your own applications.
I-38
22 April 2003
Integer Types
Integer types:
TYPE
DESCRIPTION
RANGE
RwInt8
RwUInt8
RwInt16
signed byte (8 bits)
unsigned byte (8 bits)
signed word (16 bits)
RwUInt16
unsigned word (16 bits)
RwInt32
signed long (32 bits)
RwUInt32
unsigned long (32 bits)
RwInt64
64 bit, signed integers should only ever be
used on platforms with native and
compiler support for 64 bit data types.
On other platforms, this data type is
defined using a struct so no mathematical
operations are available.
64 bit, unsigned integers should only ever
be used on platforms with native and
compiler support for 64-bit data types.
On other platforms, this data type is
defined using a struct so no mathematical
operations are available.
128 bit, signed integers should only ever
be used on platforms with native and
compiler support for 128 bit data types.
On other platforms, this data type is
defined using a struct so no mathematical
operations are available.
128 bit, unsigned integers should only
ever be used on platforms with native and
compiler support for 128 bit data types.
On other platforms, this data type is
defined using a struct so no mathematical
operations are available.
-128 to +127
0 to 255
RwInt16MINVAL (-32768) to
RwInt16MAXVAL (32767)
RwUInt16MINVAL (0) to
RwUInt16MAXVAL (65535)
RwInt32MINVAL (-231) to
RwInt32MAXVAL (231-1)
RwUInt32MINVAL (0) to
RwUInt32MAXVAL (232-1)
-263 to 263-1. No range
defining macros are
defined.
RwUInt64
RwInt128
RwUInt128
RenderWare Graphics 3.5
0 to 264-1. No range
defining macros are
defined.
-2127 to 2127-1. No range
defining macros are
defined.
0 to 2128-1. No range
defining macros are
defined.
I-39
Chapter 2 - Fundamental Types
2.6Real Types
RenderWare Graphics supports the following real number types:
TYPE
DESCRIPTION
RANGE
SIZE
RwReal
Usually equivalent to the C
Language's single-precision
"float" type.
16 bit integer, 16 bit fractional
fixed point value.
Rarely used, as true floatingpoint math is usually faster in
current hardware.
RwRealMINVAL to
RwRealMAXVAL
32
bits
RWFIX_MIN to
RWFIX_MAX
32
bits
RwFixed
A common mistake is to forget to provide a trailing "f" on floating point
constants. Some platforms have no double precision hardware support. If
the "f" is omitted from an expression compiled for these platforms the
expression will be assumed to be double precision and it will be emulated
in software. This can dramatically reduce performance. It is recommended
that you get into the habit of either using type prefixes:
RwReal g = 9.8f;
RwReal f = m * g;
or make use of type-casting in expressions, which is more portable:
RwReal g = 9.8;
RwReal f = m * (RwReal)g
I-40
22 April 2003
Vectors
2.7Vectors
RenderWare Graphics supports two and three dimensional vector types and
arithmetic.
These types should be considered opaque as they can sometimes map
directly onto underlying hardware vector processing units.
2.7.1
Two Dimensional Vectors
The 2D Vector type is RwV2d. It contains x and y coordinates.
The following functions are provided to manipulate 2D Vectors:
FUNCTION
OPERATION
RwV2dAssign()
Assignment (Copy) from a source vector to a
target vector
Addition
Subtraction
Length
Return a unit normal vector calculated from the
original vector
Find a Unit Normal line between two vectors
Scale
Calculate Dot Product
Calculate a 2D vector perpendicular to the given
2D vector
RwV2dAdd()
RwV2dSub()
RwV2dLength()
RwV2dNormalize()
RwV2dLineNormal()
RwV2dScale()
RwV2dDotProduct()
RwV2dPerp()
RenderWare Graphics 3.5
I-41
Chapter 2 - Fundamental Types
2.7.2
Three Dimensional Vectors
The 3D Vector type is RwV3d. It contains x, y and z coordinates.
The table below shows the functions available to work with these vectors:
FUNCTION
OPERATION
RwV3dAssign()
Assignment (Copy) from a source vector
to a target vector
Addition
Subtraction
Length
Calculate unit normal vector from the
original vector
Scale
Multiplies the second 3D vector by the
given scalar then adds the resulting
vector to the first vector
Calculate Dot Product
Calculate Cross Product
Negation
Transform an array of points or vertices
by the specified matrix
Transform an array of vectors or normals
by the specified matrix
RwV3dAdd()
RwV3dSub()
RwV3dLength()
RwV3dNormalize()
RwV3dScale()
RwV3dIncrementScaled()
RwV3dDotProduct()
RwV3dCrossProduct()
RwV3dNegate()
RwV3dTransformPoints()
RwV3dTransformVectors()
I-42
22 April 2003
Coordinate Systems
2.8Coordinate Systems
3D graphics programming requires understanding of a number of common
coordinate systems, known as spaces. Some basic conventions need to be
covered.
RenderWare Graphics 3.5
I-43
Chapter 2 - Fundamental Types
2.9Coordinate Systems
3D graphics programming requires understanding of a number of common
coordinate systems, known as spaces. Some basic conventions need to be
covered.
2.9.1
Right-handed Coordinates
RenderWare Graphics uses an orthogonal right-handed coordinate system
for its 3D spaces.
Typical right-handed coordinate system
The figure above displays the positive directions of x, y, and z axes with z
pointing away from the screen.
Rotate right-handed coordinate
system about y axis
RenderWare Graphics right-handed
coordinate system
The RenderWare Graphics coordinate system is rotated about the y axis as
and the figure on the right displays the positive directions of the x, y and z
axes. The positive z axis points into the screen and the positive x axis
points to the left.
As all the axes are rotated together the coordinate system is always
right-handed.
I-44
22 April 2003
Coordinate Systems
Axis Naming Conventions
The three axes are defined in RenderWare Graphics by three vectors. By
convention, the axis names used are:
AXIS
VECTOR REPRESENTATION
X
Y
Z
"Right"
"Up"
"At"
The vector is sometimes prefixed with the work "look", as in "look-at". This is
commonly used when referring to the camera object which "looks" along the
z axis.
The RenderWare Graphics' coordinate system is right-handed and the x
axis is represented by the right vector. However, as the RenderWare
Graphics coordinate system is rotated the x axis positive direction points to
the left.
For example, the RenderWare Graphics camera faces into the screen,
therefore we're effectively standing behind it. The camera's right vector
points left as the RenderWare Graphics coordinate system has been rotated
about the y axis so that z is pointing into the screen. Therefore moving the
camera, by incrementing its x axis, results in the camera moving further to
the left, along the positive x axis.
✎
In 3D Graphics terminology, the z axis, represented by the "at" vector, is sometimes
referred to as the "front" vector.
RenderWare Graphics 3.5
I-45
Chapter 2 - Fundamental Types
2.9.2
Object Space
Dynamic models in RenderWare Graphics are defined in terms of Object
Space. This means that the vertices that define the model are relative to an
arbitrary origin.
For example, the front face of a cube of unit size could be defined thus:
(0,1,0)
(1,1,0)
(0,0,0)
(1,0,0)
The origin in this case is the lower-left corner of the front face. However, the
origin could be anywhere – even the center of the cube. This could be
achieved by subtracting (0.5, 0.5, 0.5) from each vertex.
The location of the origin can be important, as it is easier to align models if
their origins are on a shared edge or a corner rather than at some arbitrary
point in the middle or outside the models.
I-46
22 April 2003
Coordinate Systems
2.9.3
World Space
Dynamic models, defined in Object Space, need to have a frame of reference
so that they can be positioned relative to other models and scene graph
objects. This frame of reference is World Space.
Objects positioned relative to this system are said to reside in world space.
This coordinate system is used, for example, to specify the position of
cameras and lights. Geometry can be positioned in world space using
transformations described later.
A bounding box defines the World Space limits. This is either generated by
a modeling package exporter when exporting World data, or explicitly by the
developer when calling RpWorldCreate().
Frames
The RenderWare Graphics object that allows us to position objects in World
Space is called the Frame (RwFrame). Many RenderWare Graphics objects
require a Frame to be attached before they can be positioned within a
World.
2.9.4
Camera Space
Cameras, like many RenderWare Graphics objects, require a Frame to
define their position and orientation. However, there is another system
called Camera Space which defines the Camera's viewing coordinate
system. A normalized Camera Frustum defines Camera Space as follows:
•
for a parallel projection model the Camera Frustum space has side
planes at x = 0, x = 1, y = 0 and y = 1
•
for a Perspective Projection model, it has side planes at x = 0, x = z, y =
0 and y = z
Camera Space is also a right-handed system with an origin at the Camera's
position (given by the Frame's pos vector). The positive z axis of Camera
Space is given by the view direction, which points in the direction of the
Frame's at vector. The units of Camera Space z coordinates are the same as
those for World Space.
RenderWare Graphics also recognizes a two-dimensional coordinate
system.
2.9.5
Device Space
The device coordinate system defines a device space. Its units are those of
the display (screen or window) to which the camera's image buffer is copied
and as such, it has coordinates that only take discrete (or integer) values.
RenderWare Graphics 3.5
I-47
Chapter 2 - Fundamental Types
The origin of device space is located at the top-left of the display with the xvalues running from left to right and the y-values running from top to
bottom, as shown in the diagram:
(0,0)
+X
+Y
Device space can also be considered to have a depth component that is
used in the Z buffer.
I-48
22 April 2003
Matrices
2.10 Matrices
RenderWare Graphics defines a pseudo-4x4 homogeneous Matrix
(RwMatrix) object to represent 3D transformations. The Frame object, see
2.11 below, makes heavy use of matrices. Matrices in RenderWare Graphics
appear as shown below:
R x R y Rz
U x U y U z
A A
Az
y
x
P P
Pz
y
x
0
0
0
1
The row vector (Rx, Ry, Rz) contains the components of the look-right vector,
(Ux, Uy, Uz) are those of the look-up vector, (Ax, Ay, Az) for the look-at vector
and (Px, Py, Pz) are the components of the pos vector. The components of a
matrix are available to the application programmer by using
RwMatrixGetRight(), RwMatrixGetUp(), RwMatrixGetAt() and
RwMatrixGetPos().
2.10.1 Matrix Mathematics in RenderWare Graphics
Matrices are treated as quadruples of row vectors. Each row vector is a
triple of real values. The vectors are the right, up and at vectors, which
orient a Cartesian coordinate system, and the pos vector that positions this
coordinate system with respect to a parent coordinate system. In
conventional 4×4 matrix form, there is an implied last column of (0,0,0,1)T.
The equations for matrix multiplication can then be expanded as shown
below.
C = A×B
RxA ⋅ RxB + RyA ⋅ UxB + RzA ⋅ AxB
A B
Ux ⋅ Rx + U yA ⋅U xB + UzA ⋅ AxB
A B
A
B
A
B
Ax ⋅ Rx + Ay ⋅ Ux + Az ⋅ Ax
P A ⋅ RB + PA ⋅ U B + PA ⋅ AB + PB
y
x
z
x
x
x x
RxA ⋅ RyB + RyA ⋅ U yB + RzA ⋅ AyB
UxA ⋅ RyB + U yA ⋅U yB + UzA ⋅ AyB
RxA ⋅ RzB + RyA ⋅ UzB + RzA ⋅ AzB
UxA ⋅ RzB + U yA ⋅UzB + U zA ⋅ AzB
AxA ⋅ RyB + AyA ⋅ U yB + AzA ⋅ AyB
AxA ⋅ RzB + AyA ⋅ UzB + AzA ⋅ AzB
PxA ⋅ RyB + PyA ⋅ U yB + PzA ⋅ AyB + PyB PxA ⋅ RzB + PyA ⋅ UzB + PzA ⋅ AzB + PzB
RxA
A
Ux
A
Ax
PA
x
RyA
U yA
AyA
PyA
RzA
U zA
AzA
PzA
0
0
=
0
1
0 RxB RyB RzB
0 UxB U yB U zB
×
0 AxB AyB AzB
1 PxB PyB PzB
Matrix multiplication is not commutative so, the order of the arguments
passed to RwMatrixMultiply() is significant. Transformation of a position
is performed mathematically in the following manner:
RenderWare Graphics 3.5
I-49
0
0
0
1
Chapter 2 - Fundamental Types
v = u×M
T
u x ⋅ Rx + u y ⋅ U x + u z ⋅ Ax + Px
u x ⋅ R y + u y ⋅ U y + u z ⋅ Ay + Py
u ⋅ R + u ⋅ U + u ⋅ A + P = (u x
y
z
z
z
z
x z
1
uy
uz
Rx R y Rz
U x U y U z
1)×
A Ay Az
x
P P P
y
z
x
0
0
0
1
This is the operation performed by RwV3dTransformPoints(). This
function is used to transform position vectors. There is also an
RwV3dTransformVectors() function, which transforms vectors (e.g.
normals). In this case, the matrix is assumed to contain a zero position
vector and so does not contribute to the output vectors.
✎
Put another way: a direction vector is never translated, but only rotated.
Using RwV3dTransformPoints() with normals, or RwV3dTransformVectors() with
vertices will give strange results.
The order of matrix transformations has an effect on the visible orientation
of Atomics, as discussed (see 2.11.3 below).
I-50
22 April 2003
Frames
2.11 Frames
RwFrame objects contain two matrices. These are the Local Transformation
Matrix (or LTM), and the Modeling Matrix. These two matrices can be
retrieved using RwFrameGetLTM() and RwFrameGetMatrix(), respectively.
When transformations are performed on a frame (see next paragraph), it is
the Modeling Matrix that is affected. (The LTM describes the total
transformation from Object Space to World Space.) Unless the Frame
belongs to a hierarchy, the Modeling and Local Transformation Matrices are
identical. Otherwise, the Modeling Matrix is relative to the Frame's parent.
Frames can be transformed using RwFrameTranslate(),
RwFrameRotate(), RwFrameScale() and RwFrameTransform(). Rotation
and scaling is accrued in the top-left 3x3 sub-matrix, while translation is
accumulated in the bottom row.
Given a transformation matrix, individual points and vectors (both of type
RwV3d) can be transformed using RwV3dTransformPoints() and
RwV3dTransformVectors().
Hierarchical modeling is the process of building models that preserve the
hierarchical structure of objects and allow the position and orientation of
an object in the hierarchy to be specified relative to its parent.
RenderWare Graphics 3.5
I-51
Chapter 2 - Fundamental Types
2.11.1 Hierarchical Models & RenderWare Graphics
Hierarchical modeling explicitly models articulation, or joints, connecting
objects. In RenderWare Graphics, these joints are represented by frames
(RwFrame). These only define the hierarchy itself. The model data itself is
sectioned, with each section stored in an atomic (RpAtomic). An atomic
can be linked to a frame, with collections of atomics and frames thus
forming a hierarchical model.
Consider, for example, the modeling of a robot arm consisting of an upperarm, lower-arm and a hand represented by three atomics. We wish to
model the arm so that movement of the upper-arm is transferred to the
lower-arm and hand whilst movement of the lower-arm only affects the
hand. Assume each atomic has its own frame (see API function
RpAtomicSetFrame()). Then the required articulation can be achieved by
attaching the lower-arm's frame as a child of the upper-arm's frame and,
similarly, attaching the hand's frame as a child of the lower-arm's frame.
The API function RwFrameAddChild is used to accomplish this.
Upper Arm
Lower Arm
Hand
Frame1
Frame 2
Frame 3
Atomic1
Atomic2
Atomic3
The modeling matrix of each frame is now described relative to the Frame's
parent Frame object and the corresponding LTM becomes the
concatenation of all the modeling matrices up to the root Frame, in this
case the Frame on the upper-arm's atomic.
For each case we have:
LTM1=MM1
LTM2=MM2⊗LTM1
LTM3=MM3⊗LTM2
(where LTM = local transformation matrix and MM = modeling matrix.)
Only the root Frame's modeling and local transformation matrices are
identical.
The object hierarchy is shown schematically above. Frame1 is the parent of
Frame2 (therefore, Frame2 is the child of Frame1), while Frame2 is the
parent of Frame3. Note that the arrangement of the Atomics is determined
entirely by the frame hierarchy. If these Atomics were all added to a single
Clump object, the Clump would impose no organization. Because a Clump
is designed as a container for Atomics, it can be assumed that the Clump
must order its Atomics but, as you can see, this is not how it works.
I-52
22 April 2003
Frames
To model the robot hand in more detail by adding some fingers:
•
give the hand three fingers represented by three more Atomics.
•
build the hand hierarchy by attaching all the fingers' Frames as children
of the hand's Frame (see diagram above).
All the fingers' Frames (frame4, frame5, frame6) are child frames of the
hand's frame and siblings of each other. In terms of the LTMs we have, for
example:
LTM4=MM4⊗ LTM3
This means the LTM of frame4 is the concatenation of the modeling
matrices of Frames Frame1, Frame2, Frame3 and Frame4 – this is the same
for the other fingers. Movement of the hand is now automatically
transferred to all the fingers.
It is recommended, though it is by no means required, that the hierarchy is
encapsulated within a Clump which has its own Frame – see
RpClumpSetFrame() – acting as the root of the Frame hierarchy. For
example, Frame1 would be attached to the Clump's frame (say, Frame0,) as
a child of that Frame. Also, each of the Atomics must be added the Clump
using RpClumpAddAtomic() for this organization to work correctly.
Frames and the Local Transformation Matrix
Frame objects contain a matrix called the Local Transformation Matrix,
(usually abbreviated to "LTM"). This matrix is used when working with
hierarchies of Frame objects.
Local Transformation Matrices are constructed by traversing the hierarchy
from top to bottom. At each level in the hierarchy, the modeling matrix is
pre-multiplied into the local transformation matrix from the level above to
form the LTM for the current level. Because the LTM is used to post
multiply vectors this means that the transformation stored in the lowest
frame in the hierarchy affects the vertex first of all:
U = V ⋅ M n ⋅ M n −1 ⋅ Λ ⋅ M 1 ⋅ M 0
In this equation, the Local Transformation Matrix at the root of the
hierarchy is M0 and that at the bottom of the hierarchy is Mn, where there
are n+1 levels in the hierarchy.
2.11.2 Traversing Frame Hierarchies
There are two methods for traversing an object hierarchy depending on
whether it is Frames or the objects hanging from them. It is assumed that a
hierarchy of Frames and Atomics assembled into a Clump where the
Clump's Frame acts as the root of the hierarchy.
RenderWare Graphics 3.5
I-53
Chapter 2 - Fundamental Types
All Frames in the hierarchy may be iterated over using the
RwFrameForAllChildren() iterator. Starting at the root Frame, this
function will apply a user-defined callback to all first generation child
Frames. Repeating RwFrameForAllChildren() on each callback will then
iterate over all second generation, i.e. grandchild, frames, and so on. Also,
for each Frame encountered a call to RwFrameForAllObjects() applies a
callback to each object attached to the Frame.
✎
RwFrameForAllChildren() will only take you down one level in a hierarchy. You must
use your callback function to call RwFrameForAllChildren()again to go down the
hierarchy another level, so your callback should be designed for recursion.
If the Frame hierarchy is not important, a call to the
RpClumpForAllAtomics() iterator will iterate over all the Atomics
registered with a Clump. The supplied user-defined callback function will
be applied to each Atomic in turn.
2.11.3 Matrix Combination Flags in RenderWare
Graphics
Matrix and frame transformation functions in RenderWare Graphics (for
example, RwFrameTransform()and RwMatrixRotate()) take a parameter,
combineOp. This parameter is used to control the order in which the
transform is applied to the matrix or Frame.
The available combine operators are: replace, pre-concatenate, and postconcatenate.
•
rwCOMBINEREPLACE assigns the new transformation to the matrix.
The original contents of the matrix are entirely replaced by the new
transform.
RwMatrixTranslate(M, t, rwCOMBINEREPLACE) builds a new
matrix containing only a translation, and stores this matrix in M. Any
rotation component in the matrix M is overwritten with a 3x3 identity
sub-matrix. This is true for all matrix-transforming functions where
the rwCOMBINEREPLACE flag is used.
I-54
•
rwCOMBINEPRECONCAT causes the transform matrix to be preconcatenated onto the matrix. This has the effect of applying the
transformation before the transformation already in the matrix. Put
another way: this operator causes the transformation to be made in
object space (or the coordinate space of the matrix).
•
rwCOMBINEPOSTCONCAT instructs RenderWare Graphics to postmultiply the transformation into the matrix. The new transformation
will take effect after the transform already in the matrix. In other
words, the transformation takes place in world space.
22 April 2003
Frames
Example
Consider a call made to RwFrameScale() with a Frame F, and a vector S
encoding the scale. The effect of changing the combination operator will be
looked at. Firstly, however, it should be pointed out that the function alters
the modeling matrix in the frame.
✎
A RenderWare Graphics application should never modify the LTM matrix directly, since
the library is responsible for computing this matrix from the Modeling Matrix and the
LTMs of the Frame hierarchy.
In this example the modeling matrix, denoted M, is stored in Frame F.
Notionally, the RwFrameScale() function computes a scale transformation
matrix, S. This will be a 4x4 zero matrix with a diagonal encoding the
elements from the scale vector, and 1:
sx
0
S=
0
0
0
sy
0
0
0
0
sz
0
0
0
0
1
The table below illustrates the result of varying the combine operator on the
matrix M.
OPERATOR
RESULTING MATRIX (M)
rwCOMBINEREPLACE
rwCOMBINEPRECONCAT
rwCOMBINEPOSTCONCAT
S
SM
MS
RenderWare Graphics 3.5
I-55
Chapter 2 - Fundamental Types
2.12 Bounding Boxes
The Bounding Box (RwBBox) object defines a bounding box using two
points: sup (supremum) and inf (infimum). These two points define
diametrically opposite corners of the box, such that for any axis, the value
in the inf coordinate is never larger than the value in the sup coordinate.
The illustration below shows how this works in practice:
Sup
Inf
The resulting box therefore represents a 3D axis aligned cuboid volume.
Bounding boxes provide the basis for simple tests to determine whether
specific coordinates in the coordinate space are bounded by the volume.
The box may also be expanded to include another point within its volume,
using the RwBBoxAddPoint() function.
Another test available is RwBBoxContainsPoint(), which can be used to
check if a vertex is inside or outside a Bounding Box.
RwBBoxAddPoint() can also be used together with the
RwBBoxInitialize() function. This takes a single vertex and initializes
both the inf and sup elements to this point. RwBBoxAddPoint() can be
called repeatedly to expand the Bounding Box to contain any arbitrary
number of points. This technique is useful if the number of points involved
is unknown.
If, on the other hand, you do have a fixed-length array of vertices, you can
use the RwBBoxCalculate() function to perform a similar operation to the
above. This function is usually the more efficient of the two systems.
I-56
22 April 2003
Lines
2.13 Lines
RenderWare Graphics naturally supports a basic line type. This is called
RwLine and it is defined by two RwV3d objects denoting the start and end
vertices. The RwLine object is used typically as an intersection primitive. Do
not confuse the RwLine object with an immediate mode line, which is a
renderable object.
RenderWare Graphics 3.5
I-57
Chapter 2 - Fundamental Types
2.14 Rectangles
Rectangles are defined by the RwRect type. This type takes a positioning
vector to locate the rectangle, as well as two parameters defining its width
and height. As with lines above, the RwRect object is not renderable.
Rectangles are typically used to define sub-regions of the screen.
I-58
22 April 2003
Spheres
2.15 Spheres
RenderWare Graphics defines the RwSphere type. This contains both a
center and a radius as elements to define the location and size of the
sphere.
Spheres are heavily used during Retained Mode rendering to determine
which models are within the Camera Frustum. Using spheres for the initial
tests makes for rapid culling. Once this coarse-level checking has been
performed, the remaining models can then be tested and clipped more
accurately.
Note that this object is not renderable, and is used primarily for
intersection testing.
RenderWare Graphics 3.5
I-59
Chapter 2 - Fundamental Types
2.16 Colors
RenderWare Graphics defines two color representation types: RwRGBA,
which is an integer-based primitive for describing colors, and RwRGBAReal,
which defines colors using real numbers rather than integers.
The RwRGBA form is the most used as it corresponds closely with most of
our supported platforms. This structure contains four RwUInt8 elements,
one for each of the Red, Green, Blue and Alpha components.
Although the RwRGBA format is fixed, the bitmap facilities offered by
RenderWare Graphics are not and may differ widely in color element
format. It is therefore possible that conversion may be needed when
extracting or modifying individual pixels in a bitmap and such processing
should thus be kept to a minimum.
See the chapter on Rasters, Images and Textures for information on these
items and their colors.
RwRGBAReal defines four RwReal elements for red, green, blue and alpha.
It is intended to be used in cases where high orders of accuracy are needed
while processing colors. Values range from 0.0f to 1.0f.
I-60
22 April 2003
Chapter 3
Initialization
& Resource
Management
Chapter 3 - Initialization & Resource Management
3.1Introduction
RenderWare Graphics Core Library contains the base feature-set of the API.
All other features are optional, provided in the form of either Plugins or
Toolkits.
The Core Library's functionality is divided up into the following broad
categories:
•
Memory management
•
OS-level file and memory management
•
Plugin management
• Basic objects and intrinsic types, such as RwInt32, RwBBox, RwMatrix,
RwImage, etc.
•
2D and 3D immediate modes
•
PowerPipe extensible rendering pipeline
•
Platform-Specific APIs (where applicable)
•
Managing rendering time through the Lock and Unlock commands.
This chapter focuses on the memory management, plugin management and
file management features of the core library.
I-62
22 April 2003
Basic Housekeeping
3.2Basic Housekeeping
At the heart of RenderWare Graphics is the RwEngine object. This engine
performs a number of housekeeping functions, including:
• Initialization and shut-down procedures
• Selecting the display device and video mode
• Querying the underlying hardware about its capabilities
• Updating metrics information (when linked to the Metrics libraries)
• Managing Plugins
All RenderWare Graphics applications have to initialize the engine before
calling any other RenderWare Graphics functions. We'll look at this process
next.
3.2.1
Initialization
Getting the RenderWare Graphics engine up and running is a three-step
process:
1. Initialization of memory management and default file system interface
2. Setting the video mode
3. Plugins and starting RenderWare Graphics
and there are three functions you need to call:
1. RwEngineInit()
2. RwEngineOpen()
3. RwEngineStart()
These functions must be called in the above order and you cannot start
rendering until after the RwEngineStart() call.
Why the three steps?
RenderWare Graphics has to make allowances for the many platforms it
supports. Splitting the start-up process into three stages lets us open up
such features as file and memory management, as well enabling the plugin
architecture to operate properly.
Let's look at these steps in terms of what they're for…
RenderWare Graphics 3.5
I-63
Chapter 3 - Initialization & Resource Management
Step 1 - Initialization of Memory Management and Default
File System Interface
This first step concerns the API function RwEngineInit() and involves
setting up the memory and file-handling subsystems.
Why Does the Engine need to be Initialized First?
RwEngineInit() must always be the first RenderWare Graphics function
your application calls as all other functions assume the memory
management facilities have been set up. For example, the plugin
mechanism needs to access these memory functions, so they need to be set
up before any Plugins are attached.
Similarly, the display device your application will use may also need some
memory allocated for it. So again, we have to make sure the memory
subsystem is ready first.
The Memory Functions
By default, RenderWare Graphics uses the standard ANSI memory
functions, as implemented by the target platform's compiler, so any
replacement functions must have identical prototypes to their ANSI
counterparts.
In theory, the application can replace the default RenderWare Graphics
handlers with its own at any time. In practice the application should
change the memory handler only at this initialization stage, rather than
later.
Changing the memory and file handling subsystems within the main loop of
your application is possible, but not recommended as it can make
debugging much more difficult.
Pointers to the functions are stored in the RwMemoryFunctions structure
returned by RwOsGetMemoryInterface(). If necessary, the entries in this
structure can be overwritten directly with your own function pointers, but
this is not recommended as the change takes place immediately—if memory
has already been allocated with the original functions, then it is likely that
memory will be "lost" to your application.
Your application should create a new RwMemoryFunctions structure with
pointers to your own functions, then pass a pointer to the structure to
RwEngineInit().
The File Functions
The file system is implemented in a similar way to the memory system, with
a structure containing pointers to default POSIX functions used by default.
Again, any replacement functions will need to share the same prototypes as
the functions they will be replacing.
I-64
22 April 2003
Basic Housekeeping
A file functions structure filled with the default functions can be retrieved
using RwOsGetFileInterface(). To replace these default function
pointers with your own, overwrite the entries in the structure. Your
functions will then be used when accessing files.
Step 2 - Setting the Video Mode
At this stage, you will need to:
•
Open the RenderWare Graphics Engine
•
Determine which graphics subsystem the application should be
using, as some platforms can support more than one
•
Determine the video display mode the application should use.
Video hardware varies greatly from platform to platform, so this procedure
requires some additional steps of its own.
Opening the RenderWare Graphics Engine
The RenderWare Graphics Engine can be opened using RwEngineOpen().
Choosing the Graphics Subsystem
The RenderWare Graphics API represents a graphics device as a graphics
subsystem.
The application must first determine how many graphics subsystems are
available. This requires a call to RwEngineGetNumSubSystems().
With this information, the application iterates through the available
subsystems, checking each one for suitability. This is achieved by calling
RwEngineGetSubSystemInfo() and interrogating the structure returned.
The following code fragment illustrates this process by printing out the
identifying names of all graphics subsystems on a particular platform:
RwInt32 numSubSystems, i;
RwSubSystemInfo ssInfo;
numSubSystems = RwEngineGetNumSubSystems();
for(i=0; izScale and camera->zShift for Z and offZ respectively.
This is the technique used by the non-hardware T&L version of RenderWare
Graphics.
I-144
22 April 2003
2D Immediate Mode
Vertices
While the result of working with 2D Immediate Mode is primitives rendered
on a display, your code will actually work directly with vertices, so let's take
a look at these now.
The vertex is the main data type for RenderWare Graphics' Immediate Mode
APIs. There are two such types, one each for 2D and 3D Modes.
The 2D Immediate Mode form is RwIm2DVertex. As with its RwIm3DVertex
counterpart, this data type's physical format is platform-dependent, so you
shouldn't try to access it directly. Instead, the API provides a complete set
of functions to prepare and manipulate the vertex. Note: These functions
are implemented as C Macros in most cases to provide optimum
performance.
7.2.2
Initializing an RwIm2DVertex object
As mentioned earlier, this object is defined in a platform-specific way. This
prevents us from documenting its structure. Initializing such objects is
therefore performed entirely through the API.
An RwIm2DVertex object contains the following properties:
• Red, Green, Blue and Alpha components
• Camera-space coordinates (X, Y and Z)
• Reciprocal of Camera's Z coordinate
• Screen-space coordinates (X, Y and Z)
• U and V coordinates
Setting & Retrieving Coordinates
2D Immediate Mode vertices are usually in screen space and this means
the RwIm2DVertex objects are also known as "device vertices". Since this
vertex object is not exposed as a structure, you need to use the API
functions, RwIm2DVertexSetScreenX(), RwIm2DVertexSetScreenY() and
RwIm2DVertexSetScreenZ(), to set these coordinates programmatically.
These functions have counterparts that can be used to retrieve these same
values: RwIm2DVertexGetScreenX(), RwIm2DVertexGetScreenY() and
RwIm2DVertexGetScreenZ().
It is also possible to specify coordinates in terms of camera space – the
functions are: RwIm2DVertexSetCameraX(), RwIm2DVertexSetCameraY(),
RwIm2DVertexGetCameraX() and RwIm2DVertexGetCameraY().
RenderWare Graphics 3.5
I-145
Chapter 7 - Immediate Mode
Reciprocal Camera Z, Texture Coordinates & Platform
Dependence
The underlying platform's hardware has a great impact on the vertex object.
Often, the RwIm2DVertex (and its 3D Immediate Mode counterpart) are
simply wrappers for a hardware-specific data type.
This means that even the format of the colors can change. For instance,
some platforms require colors to be specified in floating point form while
others prefer integer values. This is why, if you look at the API Reference
entries for the two Immediate Mode APIs, you'll find color setting functions
that accept both formats. This gives you the option of either sticking to one
color format – the functions will convert where necessary – or changing the
format from platform to platform if you prefer that level of control.
In order for some rendering techniques, including Gouraud shading and
perspective-correct texture mapping, to work correctly, you may need to
specify the reciprocal camera-space Z coordinate of a vector and/or the
actual camera-space Z coordinate itself.
This is an important facet of Immediate Mode programming: some functions
simply don't exist on some platforms; on others, different functions may be
required to achieve the same effects.
In the case of the reciprocal of Camera Z, the function (if available) to
obtain this is RwIm2DVertexGetRecipCameraZ(). (There is an equivalent
RwIm2DVertexSetRecipCameraZ() function too if the former is available.)
The reciprocal camera Z value is generally required to enforce perspectivecorrect texture mapping. Texture coordinates can therefore also be specified
if your primitive(s) are to be so rendered. Currently, the vertex object will
only support one texture – multi-texturing is planned – so setting the U and
V coordinates is a matter of calling the appropriate RwIm2DVertexSetU()
and RwIm2DVertexSetV() functions respectively.
✎
I-146
The API Reference is rebuilt specifically for each platform so it will only contain the
relevant platform-specific entries. Other platforms have different builds of the API
Reference with different platform-specific entries as appropriate.
22 April 2003
2D Immediate Mode
7.2.3
Primitives
RenderWare Graphics supports two major types of primitive: Lines and
Triangles. These are in turn split into subtypes. Lines are split into line lists
and poly-lines.
Line Lists
These are lists of vertex pairs defining the start and endpoints of lines. This
data format is ideal for rendering groups of unconnected lines.
Poly-lines
This is a list consisting of one start point, followed by any number of
endpoints. The Immediate Mode rendering engine will start at the first
point, draw a line to the first endpoint and draw another from the end of
that line to the next endpoint in the list. This primitive is ideal for
sequences of connected lines.
Except for the first line, the poly-line primitive type does not require two
vertices to be processed per line. This means it needs the least data to work
and is therefore the most efficient of the line primitives. If possible, use this
primitive type when working with lines.
✎
Rendering individual lines can be done using RwIm2DRenderLine(). This function allows
you to draw individual lines between arbitrary vertices. (See the API Reference for more
details.)
It should be noted, however, that drawing individual lines in this way is not recommended
as it can be slow.
RenderWare Graphics also supports a number of triangle primitives:
Triangle Lists ("Tri-List")
These are similar to the Line Lists mentioned earlier. They consist of triplets
of vertices defining individual triangles. This implies that triangles in a trilist are entirely independent of each other.
Triangle Strips ("Tri-Strip")
These define strips of adjacent triangles, each sharing an edge with
another. This form requires fewer vertices than the Triangle Lists type as,
after the first triangle is defined, only one additional vertex is needed to
define each subsequent triangle. This has significant performance benefits
on most platforms.
RenderWare Graphics 3.5
I-147
Chapter 7 - Immediate Mode
The diagram to the right demonstrates the advantage of tri-strips. Once the
first three vertices (shown as rings in the
diagram) have defined the first triangle, only
one additional vertex is required to add each
new triangle to the strip.
In the diagram, the second step shows a fourth
vertex defining the second triangle (shown in
red) and in the third step, we have just five
vertices defining three triangles.
Obviously, this format is more efficient as you
add more triangles.
Triangle Fans ("Tri-fan")
These are similar in concept to triangle
strips, relying on contiguous triangles to
reduce the number of vertices that need to
moved around and processed.
As you can see from the example to the
right, a triangle fan requires that all
triangles share a vertex and are
contiguous. This form has much the same
advantages as triangle strips.
Both the strip and fan forms are popular with transform and lighting
processing hardware, so RenderWare Graphics is biased somewhat in their
favor on most supported platforms.
✎
7.2.4
The triangle fan and triangle strip primitives are not built on the fly by RenderWare
Graphics' rendering engine. The RenderWare Graphics modeler exporter plugins allow you
to export geometry optimized for triangle strips and/or fans.
Triangle Winding Order
Throughout RenderWare Graphics, the ordering of the vertices defining a
triangle – the winding order – also define its visibility. RenderWare
Graphics' use of a right-handed coordinate system means triangles with
vertices defined in clockwise order (relative to the camera) have a normal
pointing away from the camera and are therefore not visible, so they will
not be drawn.
In summary: visible Triangles must have vertices defined in anti-clockwise
order, relative to the camera, as the normal to the Triangle is pointing
towards the camera.
I-148
22 April 2003
2D Immediate Mode
7.2.5
Primitives vs. Indexed Primitives
2D Immediate Mode can work directly with arrays of primitives, which are
in any case just arrays of vertices. It can also work with arrays of indices to
such arrays of vertices. This second technique is particularly important as
it opens up more efficient use of system memory. In particular, it lets you
re-use vertices rather than having define duplicates.
The SDK includes a number of Examples, including the im2d Example.
This illustrates 2D Immediate Mode by rendering a number of different
primitives, including indexed and non-indexed forms.
RenderWare Graphics 3.5
I-149
Chapter 7 - Immediate Mode
7.2.6
Example 1: Rendering A Line.
This code fragment renders a single, simple, opaque red line:
RwIm2DVertex vertex[2];
// Set up the vertices...
RwIm2DVertexSetScreenX(&vertex[0], 20.0f );
RwIm2DVertexSetScreenY(&vertex[0], 20.0f );
RwIm2DVertexSetScreenZ(&vertex[0], 3276.0f );
RwIm2DVertexSetRecipCameraZ(&vertex[0], (1.0f/6.0f) );
RwIm2DVertexSetScreenX(&vertex[1], 620.0f );
RwIm2DVertexSetScreenY(&vertex[1], 460.0f );
RwIm2DVertexSetScreenZ(&vertex[1], 3276.0f );
RwIm2DVertexSetRecipCameraZ(&vertex[1], 1.0f/6.0f );
// Opaque red...
RwIm2DVertexSetIntRGBA(&vertex[0], 255, 0, 0, 255);
// ...and the same for the second vertex.
RwIm2DVertexSetIntRGBA(&vertex[1], 255, 0, 0, 255);
// Texturing off...
RwRenderStateSet(rwRENDERSTATETEXTURERASTER, NULL);
// Flat shading on...
RwRenderStateSet(rwRENDERSTATESHADEMODE, (void
*)rwSHADEMODEFLAT);
// Alpha-transparency off...
RwRenderStateSet(rwRENDERSTATEVERTEXALPHAENABLE, (void
*)FALSE);
//Render line...
RwIm2DRenderLine(vertex, 2, 0, 1);
✎
Release Builds
There appear to be a lot of function calls involved in this code, but the overhead is not as
bad as it first appears.
The RenderWare Graphics libraries are supplied in three builds: Release, Metrics and
Debug.
Release builds redefine many trivial functions as macros. The upshot is that almost all
property setting and access functions, such as those above, are inlined.
I-150
22 April 2003
2D Immediate Mode
Example 2: Rendering A Triangle.
This code fragment renders a simple, yellow, flat shaded triangle:
RwIm2DVertex vertex[3];
//Set up the vertices...
RwIm2DVertexSetScreenX(&vertex[0], 20.0f );
RwIm2DVertexSetScreenY(&vertex[0], 20.0f );
RwIm2DVertexSetScreenZ(&vertex[0], 3276.0f );
RwIm2DVertexSetRecipCameraZ(&vertex[0], (1.0f/6.0f) );
RwIm2DVertexSetScreenX(&vertex[1], 20.0f );
RwIm2DVertexSetScreenY(&vertex[1], 40.0f );
RwIm2DVertexSetScreenZ(&vertex[1], 3276.0f );
RwIm2DVertexSetRecipCameraZ(&vertex[1], (1.0f/6.0f) );
RwIm2DVertexSetScreenX(&vertex[2], 40.0f );
RwIm2DVertexSetScreenY(&vertex[2], 40.0f );
RwIm2DVertexSetScreenZ(&vertex[2], 3276.0f );
RwIm2DVertexSetRecipCameraZ(&vertex[2], (1.0f/6.0f) );
// Opaque yellow...
RwIm2DVertexSetIntRGBA(&vertex[0], 255, 255, 0, 255);
// Opaque yellow...
RwIm2DVertexSetIntRGBA(&vertex[1], 255, 255, 0, 255);
// ...and, once again, opaque yellow...
RwIm2DVertexSetIntRGBA(&vertex[2], 255, 255, 0, 255);
// Texturing off...
RwRenderStateSet(rwRENDERSTATETEXTURERASTER, NULL);
// Flat shading mode...
RwRenderStateSet(rwRENDERSTATESHADEMODE, (void
*)rwSHADEMODEFLAT);
// Alpha-transparency off...
RwRenderStateSet(rwRENDERSTATEVERTEXALPHAENABLE, (void
*)FALSE);
// Render triangle...
RwIm2DRenderTriangle(vertex, 3, 0, 1, 2);
As you can see from the examples above, there is an overhead involved in
setting up the RenderState data. Because of this, it makes sense to group
all your primitives by RenderState to speed up the rendering process.
RenderWare Graphics 3.5
I-151
Chapter 7 - Immediate Mode
7.33D Immediate Mode
3D Immediate Mode provides low-level 3D rendering facilities. It is designed
around the same concepts as its 2D counterpart, including the concepts of
vertex lists, index lists and primitives. In addition, it makes heavy use of
RenderWare Graphics' Render State API to control the rendering process.
7.3.1
Preparation for Rendering
Vertices & Indices
3D Immediate Mode has its own vertex object: RwIm3DVertex. This holds
coordinates defined using either world space (also known as 'scene space'),
or in object space. This distinction is covered in more detail later.
As with the 2D Immediate Mode's own vertex object, RwIm3DVertex is also
an opaque, platform-dependent type. Access is entirely through the API.
In fact, there isn't all that much to say about the 3D vertex object: aside
from the extra dimension, it's relatively straightforward and the API is
similar to that for 2D Immediate Mode's own RwIm2DVertex object.
Where the 3D Immediate Mode API does differ slightly from the 2D one is
that setting coordinates is done through a single function call:
RwIm3DVertexSetPos(). This takes the X, Y and Z coordinates as well as a
pointer to the RwIm3DVertex where they are to be stored. A retrieval
function, RwIm3DVertexGetPos(), is also provided.
As with the 2D Immediate Mode, 3D Immediate Mode expects vertices to be
stored in arrays. These arrays can be referenced either directly or using an
index array. The latter has the expected advantage of requiring fewer
vertices, but can cause problems if your model geometry is to be adjusted
in real-time.
✎
Unlike its 2D counterpart, the 3D Immediate Mode API provides clipping.
Transforming Space
To determine how a particular vertex maps to the display device, the 3D
Immediate Mode API provides a function that takes an array of 3D vertices
and transforms them to camera space (which is much the same thing as
device space).
The function that performs this feat is the RwIm3DTransform() function.
This takes four parameters, the third of which is an optional parameter
specifying an additional transformation matrix to be applied.
This transformation matrix should be set when working with vertex arrays,
which use object space. The matrix will be used to map the object to world
space and then to camera/device space.
I-152
22 April 2003
3D Immediate Mode
The RwIm3DTransform() function normally produces two new arrays, one
of camera space vertices and – for those vertices that lie within the camera
frustum – an array of device space (device-dependent) vertices.
Access to these intermediate data representations should be performed very
carefully. They are platform-dependent, some hardware accelerators may
store these new arrays in strange formats – or even not at all.
Additional Vertex Properties
As well as the usual three coordinates, each 3D Immediate Mode vertex can
store RGBA values. These are set using the RwIm3DVertexSetRGBA()
function. (The function accepts 8-bit unsigned integers, so floating point
RGBA formats will need to be converted first.)
The remaining two properties are U and V coordinates for texturing. The
functions for setting these are RwIm3DVertexSetU() and
RwIm3DVertexSetV() respectively. Both functions take an RwReal value for
the texture coordinates.
☛
The 'impick' Example
This example lets you pick and drag vertices in wireframe 3D Immediate Mode models.
The commented code therefore illustrates a wide variety of Immediate Mode programming
techniques.
Lighting
Lights are not supported in 3D Immediate Mode. You can simulate them by
manipulating the vertex colors in accordance with a custom lighting model.
RenderWare Graphics 3.5
I-153
Chapter 7 - Immediate Mode
7.3.2
Rendering
Rendering in 3D Immediate Mode requires following this sequence:
1. Transform the primitives into camera space
2. Perform any rendering with the primitives
3. Terminate pipeline execution
The primitives supported by 3D Immediate Mode are simply extensions of
those found in the 2D mode: line lists, polylines, triangle lists, triangle
strips and triangle fans. Again, the same trade-offs apply.
The screenshots below illustrate some of the primitives in action. All are
from the im3d Example.
This first shot is the polyline form in action. (The code used to display this
is contained within the polyline.c source file.)
The next shot shows the triangle list primitive. (The code that exercises this
primitive can be found in trilist.c.)
I-154
22 April 2003
3D Immediate Mode
We recommend you take a look through and modify the code that makes up
this Example as it illustrates the salient features of this particular API.
Render States
3D Immediate Mode rendering makes heavy use of render state settings.
More on these in 7.4 Render States. As with the 2D Immediate Mode API,
the most efficient way to handle render states is to group primitives with
the same state and render them in batches, switching render states
between each batch.
Rendering primitives
Two rendering functions are available for this: RwIm3DRenderPrimitive(),
which renders non-indexed primitive types, and its counterpart
RwIm3DRenderIndexedPrimitive(), which renders indexed ones.
For instance, the following line…
RwIm3DRenderIndexedPrimitive(rwPRIMTYPETRILIST, myIndices, 8);
…would be used to render an indexed triangle list. The relevant array
indices are stored in the myIndices array, and there are 8 such indices to
render.
✎
Remember that the RwIm3DTransform() function has already taken this array and
transformed it into camera-space vertices. The PowerPipe Transform node caches these
internally. It is these converted vertices that are referenced during any rendering.
If your target platform allows it, it may be possible to access these converted vertex arrays
using RenderWare Graphics' platform-specific API. The exact functionality available will
likely vary from platform to platform.
RenderWare Graphics 3.5
I-155
Chapter 7 - Immediate Mode
7.3.3
Closing the pipeline
Once rendering of your array of primitives is complete, you must call
RwIm3DEnd() to close and flush the rendering pipeline.
7.3.4
3D Immediate Mode & PowerPipe
3D Immediate Mode rendering makes use of RenderWare Graphics'
PowerPipe rendering technology. When you transform an array of vertices
with RwIm3DTransform(), you are actually firing up PowerPipe and calling
its default pipeline.
✎
Many of our platforms are provided only with generic transform and render nodes. These
nodes do not support all of the primitives. For instance, the generic transform node will
expand triangle fans into ordinary triangle lists.
The transform node also does not support unindexed primitives and will create indices for
them, so you should use indexed rendering wherever possible.
However, all PowerPipe nodes can be overridden by your own, so two functions are
provided to give you direct access to the Transform and Rendering nodes. They are,
respectively, RwIm3DGetTransformPipeline() and RwIm3DGetRenderPipeline().
Should you wish to revert to the generic nodes, you can obtain pointers to the generic
transform and render nodes using RwIm3DGetGenericTransformPipeline() and
RwIm3DgetGenericRenderPipeline().
On platforms that support Transform & Lighting in hardware, overloading the generic node
will cause a software pipeline to be used. This will have a negative impact on performance
so you may need to write your own hardware T&L node.
Once the pipeline is fired up, it transforms and renders the supplied
vertices.
It's important to understand that the only way to transform some more
vertices at this stage is to close down the pipeline using RwIm3DEnd() and
restart it with RwIm3DTransform(). This is not the obstacle it appears, as
you will usually render batches of primitives sorted by Render State
anyway. It is not possible to nest Transform/End sequences.
As you can see, efficient management of this process is the key to getting
maximum performance out of RenderWare Graphics' 3D Immediate Mode.
Uses for 3D Immediate Mode
RenderWare Graphics provides a very rich Retained Mode API, which would
lead many to suspect 3D Immediate Mode of being of relatively little use.
Nothing could be further from the truth!
3D Immediate Mode is ideally suited to the rendering of program-generated
data. For example, particle system explosions and other scenery effects are
often added to a scene using this API.
Other techniques include producing pseudo-3D imagery, such as that seen
in some real-time strategy games. (Although produced long before
RenderWare Graphics was released, Cavedog's "Total Annihilation" series is
a good example of pseudo-3D.)
I-156
22 April 2003
3D Immediate Mode
An important use is for rendering of scientific data or mathematical models
that don't map easily to traditional modeling paradigms. One of our
developers has taken advantage of this aspect of 3D Immediate Mode to
create a groovy multicolor lava lamp simulator using a marching cube
algorithm.
7.3.5
Platform Specific Information
Some platforms do their vertex transforms in hardware and cannot provide
access to the transformed vertices. You should refer to the platform-specific
documentation to see what functionality is available in this regard.
Similarly, texture coordinates may have restrictions imposed by their
underlying hardware. Again, you should refer to the platform-specific
documentation to see if this applies to your target platform.
RenderWare Graphics 3.5
I-157
Chapter 7 - Immediate Mode
7.3.6
Camera-space and Z-buffer depth equations
The mapping functions that convert from camera space to screen depth
space are provided here for information:
Perspective Camera:
Z − Z min
R
( z − Rmin ) max
Z ( z ) = Z min + max
z
Rmax − Rmin
Parallel Camera:
Z − Z min
( z − Rmin )
Z ( z ) = Z min + max
Rmax − Rmin
Where:
• Z(z) is the Z-buffer value corresponding to a camera space z-coordinate z.
• Zmax, Zmin are the maximum and minimum Z-buffer values, respectively.
They correspond to the Z-buffer values given by Z(Rmax) and Z(Rmin). Their
values may be queried using the API functions
RwIm2DGetFarScreenZ() and RwIm2DGetNearScreenZ().
• Rmin, Rmax are the distances to the far and near clip planes, respectively.
Their values may be queried using the API functions
RwCameraGetFarClipPlane() and RwCameraGetNearClipPlane().
I-158
22 April 2003
3D Immediate Mode
7.3.7
Rt2D
This Toolkit provides a 2D graphics API. Its power is such that it could
justifiably be considered a kind of Retained Mode API for 2D graphics.
Unlike 2D Immediate Mode, which deals solely with the most basic
rendering chores, the 2D Toolkit also supports features such as resolutionindependence, scaleable fonts, paths, textured polygons, anti-aliasing,
alpha blending effects, free rotation and scaling, clipping, rendering to any
arbitrary Camera object, and more.
Its power is derived from RenderWare Graphics' 3D graphics capabilities.
This means it can make full use of any 3D graphics acceleration hardware
to produce great 2D imagery.
So why use 2D Immediate Mode?
2D Immediate Mode is a thin API. This makes it much better suited to fast,
simple 2D operations of the type often required to create a user interface.
Icons, debugging messages, quick bitmap font routines, side-panels, simple
sprites and so forth are generally easier to produce using the 2D Immediate
Mode API.
RenderWare Graphics 3.5
I-159
Chapter 7 - Immediate Mode
7.4Render States
Briefly, the Render State object is a basic state machine. It is an opaque
object, with two API functions provided to access its properties:
RwRenderStateSet() and RwRenderStateGet().
7.4.1
Key Features
•
Render States are a shared hardware resource.
There is only one Render State structure and it is shared throughout
RenderWare Graphics. Therefore, 2D Immediate Mode shares this with
both the 2D and 3D Retained Mode APIs – Rt2D and RpWorld,
respectively.
•
There is no multi-platform default setting for the Render State
structure.
This is because some platforms may not support all the Render State
settings, or support them in different ways. Instead, the default setting
for the Render State varies from platform to platform.
•
The application is responsible for ensuring any required state(s) are set
correctly.
Some high-level portions of the RenderWare Graphics API, such as
RpWorld, may change the Render State settings if they need to. You
should not assume that a particular Render State has been left
untouched by, say, a call to RpWorldRender().
•
Some Render State settings are unsupported on certain platforms.
RenderWare Graphics does not provide any software emulation as such,
so if a platform does not support a particular Render State feature,
setting it will have no effect.
7.4.2
API
The Render State API (RwRenderState) differs from most other APIs in that
there is only one Set/Get pair of functions. They are RwRenderStateSet()
and RwRenderStateGet() respectively.
Both functions take two parameters: an enumerated type and a void
pointer. The enum or 'render state specifier' determines which render state
the function is to set or get. The void pointer holds the data. So the void
pointer is used as an arbitrary 32-bit value whose contents depend on the
value of the render state specifier. The programmer is responsible for
checking the type of this parameter as the compiler will not check the type
of void pointers. (Types cast to void in these function calls include
RwRaster *, RwBool, and other enumerated types.)
I-160
22 April 2003
Render States
Currently, the following render states are supported:
• rwRENDERSTATETEXTURERASTER
Use this render state to set the Raster object to texture with.
For example:
RwRaster * myRaster;
RwRasterCreate( myRaster );
RwRenderStateSet( rwRENDERSTATETEXTURERASTER,
(void *)myRaster);
• rwRENDERSTATETEXTUREADDRESS
Use this render state to tell RenderWare Graphics how to handle the
texture coordinate space. The options are: rwTEXTUREADDRESSWRAP,
rwTEXTUREADDRESSCLAMP, rwTEXTUREADDRESSMIRROR or
rwTEXTUREADDRESSBORDER.
The values to pass as the void pointer are those described in the API
Reference under RwTextureGetAddressing().
This render state will set both U and V handling to the same operation.
The following two enumerated values can be used to set the U and V
spaces individually so you can have different behavior for each:
-
rwRENDERSTATETEXTUREADDRESSU,
-
rwRENDERSTATETEXTUREADDRESSV,
Example 1: Set both U and V coordinate spaces to Clamp mode:
RwRenderStateSet( rwRENDERSTATETEXTUREADDRESS, (void *)
rwTEXTUREADDRESSCLAMP);
Example 2: Set V coordinate space to Wrap mode:
RwRenderStateSet( rwRENDERSTATETEXTUREADDRESSV, (void *)
rwTEXTUREADDRESSWRAP);
• rwRENDERSTATETEXTUREPERSPECTIVE
Pass TRUE or FALSE in the void pointer. TRUE enables perspective
correction.
• rwRENDERSTATEZTESTENABLE
Pass TRUE or FALSE in the void pointer. TRUE enables Z-buffer tests.
• rwRENDERSTATESHADEMODE
Can be set to either rwSHADEMODEFLAT or rwSHADEMODEGOURAUD.
• rwRENDERSTATEZWRITEENABLE
Pass TRUE or FALSE in the void pointer. TRUE enables Z-buffer writes.
RenderWare Graphics 3.5
I-161
Chapter 7 - Immediate Mode
• rwRENDERSTATETEXTUREFILTER
Texture filtering method. The values you can pass are as follows:
-
rwFILTERNEAREST,
-
rwFILTERLINEAR,
-
rwFILTERMIPNEAREST,
-
rwFILTERMIPLINEAR,
-
rwFILTERLINEARMIPNEAREST,
-
rwFILTERLINEARMIPLINEAR
See the Rasters, Images and Textures chapter for more detailed
information on these.
• rwRENDERSTATESRCBLEND
Used to set the source blending factor.
• rwRENDERSTATEDESTBLEND
Used to set the destination blending factor.
• rwRENDERSTATEVERTEXALPHAENABLE
Pass TRUE or FALSE in the void pointer. TRUE enables vertex alpha
transparency.
• rwRENDERSTATEBORDERCOLOR
Border color for texturing with borders. The argument should be RGBA
components packed into an RwRGBA value and cast to a void pointer.
• rwRENDERSTATEFOGENABLE
Pass TRUE or FALSE in the void pointer. TRUE enables fogging effects. (All
polygons rendered from this point on until this is set to FALSE will be
affected.)
• rwRENDERSTATEFOGCOLOR
Color used for fogging. The argument should be RGBA components
packed into an RwRGB value cast to a void pointer.
• rwRENDERSTATEFOGTYPE
Select the type of fogging to use. Valid arguments are:
-
rwFOGTYPELINEAR,
-
rwFOGTYPEEXPONENTIAL,
-
rwFOGTYPEEXPONENTIAL2
The precise algorithms used vary from platform to platform, but are
broadly similar. Read the documentation supplied with your target
platform for more details on how fogging is implemented.
I-162
22 April 2003
Render States
On current platforms, linear fog will be faster than exponential forms.
✎
Not all platforms support all three fogging formats.
• rwRENDERSTATEFOGDENSITY
Defines the density of exp and exp2 fogging. The density should be an
RwReal value cast to a void pointer. See the platform-specific
documentation for the range(s) allowed.
✎
7.4.3
In all cases, the RwRenderStateGet() and RwRenderStateSet() functions will return
FALSE if a particular render state is unsupported.
Blending
The Render State structure includes two blending settings,
rwRENDERSTATESRCBLEND and rwRENDERSTATEDESTBLEND. These functions
are used to control the blending of the rendered imagery with the data
already extant in the target Raster.
The components of the final pixel color value in the frame buffer are
obtained according to the formula:
(i )
(i )
(i )
(i )
(i )
C Out
= B Src
C Src
+ B Dest
C Dest
(for i = R, G, B, A)
B Src : source blend factor
C Src : source color
B Dest : destination blend factor
C Dest : destination color (frame buffer)
Several options are available for the source and destination blend factors,
but there are some platform specific restrictions.The following are available
for all platforms:
rwBLENDZERO
rwBLENDONE
rwBLENDSRCALPHA
rwBLENDINVSRCALPHA
rwBLENDDESTALPHA
rwBLENDINVDESTALPHA
(0, 0, 0, 0)
(1, 1, 1, 1)
(As, As, As, As)
(1-As, 1-As, 1-As, 1-As)
(Ad, Ad, Ad, Ad)
(1-Ad, 1-Ad, 1-Ad, 1-Ad)
As and Ad are the source and destination alpha values respectively. On
PlayStation 2, certain combinations of these factors for source and
destination cannot be used together due to the underlying blend equation.
See the API reference for more details. Note also that the DESTALPHA
modes are only valid when the frame buffer actually contains an alpha
channel.
The following color blend factors are supported in any combination in
RenderWare Graphics for Xbox and D3D8 but have more limited availability
on other platforms:-
RenderWare Graphics 3.5
I-163
Chapter 7 - Immediate Mode
rwBLENDSRCCOLOR
rwBLENDINVSRCCOLOR
rwBLENDDESTCOLOR
rwBLENDINVDESTCOLOR
(Rs, Gs, Bs, As)
(1-Rs, 1-Gs, 1-Bs, 1-As)
(Rd, Gd, Bd, Ad)
(1-Rd, 1-Gd, 1-Bd, 1-Ad)
PlayStation 2 does not support them at all. OpenGL and GameCube only
support DESTCOLOR factors for SRCBLEND and SRCCOLOR factors for
DESTBLEND.
One further mode is supported for Xbox and D3D8:
•
rwBLENDSRCALPHASAT (f, f, f, 1), where f = min(As, 1- Ad)
7.4.4
Sorting Alpha Primitives
Current versions of RenderWare Graphics do not support sorting of alpha
primitives for you. It is therefore necessary to perform such processing
explicitly in your application. This issue is explored in one of our FAQs.
7.4.5
I-164
22 April 2003
Chapter 8
Serialization
Chapter 8- Serialization
8.1Introduction
RenderWare Graphics supports both a low-level file I/O API and a highlevel streaming API which is used for serialization of objects.
This chapter covers the low-level file I/O API, which is similar in design to
most ANSI-based operating system APIs. However, the main focus is on the
streaming API.
I-166
22 April 2003
File I/O API
8.2File I/O API
The low-level file I/O API deals with file-level access to storage devices. It
exposes a file I/O interface based on the standard ANSI interface included
with most C compilers.
The interface is exposed through the RwFileFunctions structure, a pointer
to which can be obtained through a call to RwOsGetFileInterface(). This
structure contains pointers to the file I/O functions and a default set is
installed by default by RenderWare Graphics upon initialization.
The default functions implement the functionality either by using the
platform's C compiler's default implementation (if available), or by passing
the file I/O requests to a platform's underlying operating system.
The following table lists the RwFileFunctions element names, its
associated ANSI file I/O function, and its purpose. Due to the popularity of
the ANSI file I/O interface, it is assumed developers are familiar with these
functions and their usage.
STRUCTURE
ENTRY
ANSI NAME
PURPOSE
rwfexist
rwfopen
rwfclose
rwfread
rwfwrite
rwfgets()
fexist()
fopen ()
fclose ()
fread ()
fwrite ()
fgets ()
rwfputs()
fputs ()
rwfeof()
feof ()
rwfseek()
fseek ()
rwfflush()
fflush ()
rwftell()
ftell ()
Returns TRUE if the file exists
Opens a file for reading/writing
Closes an opened file
Reads data from a file
Writes data to a file
Reads a null-terminated string from a
file
Writes a null-terminated string to a
file
Returns TRUE if the end of the file has
been passed
Moves the file pointer to the specified
point in the file
Flushes any data written to a file from
the internal cache
Returns the current position of the file
pointer in a file
The application can replace the default functions by overwriting the entries
in the RwFileFunctions structure with pointers to custom functions.
The replacements must use the relevant function prototype. For this
purpose, suitable prototype typedefs have been defined. These typedefs
are highlighted in bold within the function prototypes given in the table
below.
RenderWare Graphics 3.5
I-167
Chapter 8- Serialization
ANSI NAME
PROTOTYPE
fexist()
fopen()
RwBool (*rwFnFexist)(const RwChar *name);
fclose()
fread()
fwrite()
fgets()
fputs()
feof()
fseek()
fflush()
ftell()
I-168
void *(*rwFnFopen)(const RwChar *name, const
RwChar *access);
int (*rwFnFclose)(void *fptr);
size_t (*rwFnFread)(void *addr, size_t size,
size_t count, void *fptr);
size_t (*rwFnFwrite)(const void *addr, size_t
size, size_t count, void *fptr);
RwChar *(*rwFnFgets)(RwChar *buffer, int maxLen,
void *fptr);
int (*rwFnFputs)(const RwChar *buffer, void
*fptr);
int (*rwFnFeof)(void *fptr);
int (*rwFnFseek)(void *fptr, long offset, int
origin);
int (*rwFnFflush)(void *fptr);
int (*rwFnFtell)(void *fptr);
22 April 2003
RenderWare Binary Streams
8.3RenderWare Binary Streams
RenderWare Graphics supports the concept of binary streams.
A binary stream is a data format which allows data to be streamed to files
or through a network connection. Only the former is supported explicitly.
The binary stream mechanism is also used to support serialization of
objects and this API relies on the low-level file I/O API described earlier, in
section 1.2.
8.3.1
Binary Stream Structure
The binary stream format is used when serializing all serializable objects.
For example, static worlds (RpWorld) can be serialized to a binary stream
and so can dynamic models (RpClump).
Binary streams are normally written to, or read from, files. Such files can
contain one or more serializable objects, so a system of chunk IDs—also
known as object type IDs—is used to identify the specific entities within the
stream.
For example, the RenderWare Graphics SDK comes with a number of
demonstrations and examples. Most of these load model geometry and
other related data from individual files with an extension of either ".dff"
for dynamic models, or ".bsp" for static models. Both of these file
extensions are used purely to remind the programmer what is in each file.
Both file types are fundamentally the same: both are binary streams and
accessed using the same binary stream API.
Note that from RenderWare Graphics 3.5, some file types are now
considered "legacy": .dff and .bsp are among these. The default file type
for new RenderWare Graphics binary streams is .rws. These .rws files
encapsulate the data that the legacy file types would have contained and
group related binary data together into a single container. The binary
streaming methods remain unchanged however. See 8.3.4 RWS files for
more information on .rws files.
✎
The meaning of "legacy" file types is that in the future, RenderWare Graphics exporters
may not export to these file types. However, the binary format of these files continue to be
supported, and RenderWare Graphics 3.5 will continue to read them. There is no need to
re-export existing DFF/BSP/etc. artwork as RWS files.
Although the examples provided with the SDK use individual files for each
dynamic model or world, an application could keep all its data in a single
binary stream if needed. This is one such use for an .rws file.
The Header
When an object is serialized, the data is preceded by a chunk header,
represented by the RwChunkHeaderInfo structure:
RenderWare Graphics 3.5
I-169
Chapter 8- Serialization
• length – length of the chunk data in bytes
• type – chunk ID, which can either be one of the following or a custom
application-created ID:
−
rwID_ATOMIC - an atomic (type RpAtomic).
−
rwID_CAMERA - a camera (type RwCamera).
−
rwID_CLUMP - a clump (type RpClump).
−
rwID_GEOMETRY - a geometry (type RpGeometry).
−
rwID_IMAGE - an image (type RwImage).
−
rwID_LIGHT - a light (type RpLight).
−
rwID_MATERIAL - a material (type RpMaterial).
−
rwID_MATRIX - a matrix (type RwMatrix).
−
rwID_TEXDICTIONARY - a texture dictionary (type
RwTexDictionary).
−
rwID_TEXTURE - a texture (type RwTexture).
−
rwID_WORLD - a world (type RpWorld).
• version – version of the chunk data
Chunk Types
The key to the streaming mechanism is in the type element. This element
denotes the type of object stored in the chunk referred to by the chunk
header. When a plugin is attached, it registers its supported object type IDs
with the streaming API.
The type ID should be created using the MAKECHUNKID macro. This macro is
also used to create plugin IDs, but plugins rarely implement more than one
serializable object, so the plugin ID can also be used as the object type ID.
✎
If a custom plugin does implement more than one object, you should ensure that the
additional object IDs are unique. If you need more than 256 unique IDs, you should
contact Criterion Software Ltd. to obtain additional Vendor IDs, each of which can be used
to create a further 256 unique IDs.
Complex Chunks
Chunks can contain other chunks, so a complete stream can be parsed as
a tree-like hierarchy. Such chunks are known as complex chunks.
I-170
22 April 2003
RenderWare Binary Streams
The strview applet, which can be located in [SDK-ROOT]/tool/strview,
illustrates this aspect of RenderWare Graphics' binary streams by
displaying the structure of any valid stream as a hierarchical view. An
example of the stream viewer in action can be seen in the screenshot on the
next page.
Complex chunks are handled transparently by callbacks which are
registered with the streaming API. In the screenshot below, the structure of
a typical RpClump container object is clearly visible, with its list of RwFrame
objects, RpGeometry objects and RpAtomic objects.
The stream viewer applet
8.3.2
Serializing Objects
Although there is a trend towards originating 3D graphics data
algorithmically, most 3D graphics data is streamed into memory from a
storage device. Given RenderWare Graphics' target market, this is usually
either a CD, DVD or hard disk.
The streaming of extended or derived object data requires the creation of
additional functions. We saw these in the Plugin example (see the Plugins:
Creation & Usage chapter), but didn't see them in action.
Look for TestPluginStream() in the ClumpPhysics example's main.c file.
This function, which is predicated on a build-time #define called
TESTSTREAM, was included in this source code so you can see how the
RenderWare Graphics Binary Stream facility is used.
RenderWare Graphics 3.5
I-171
Chapter 8- Serialization
You may want to activate it, by defining the TESTSTREAM constant, and step
through the code in your debugger to watch what it does.
Registering the Stream Functions
If you look at the source code, you'll notice that none of the three stream
functions created for the new plugin appear to be called directly. This is
because these functions are called directly by the clump object's own
stream functions.
Objects that support extension via the plugin mechanism and support for
binary streams have two registration functions. Respectively, these are:
• Rp[PLUGIN-NAME]RegisterPlugin()
• Rp[PLUGIN-NAME]RegisterPluginStream()
In the ClumpPhysics plugin example, both functions are called in the
RpClumpPhysicsPluginAttach() function. The second of the two
registration functions, RpClumpRegisterPluginStream(), is the one that
tells the clump object about our own stream functions.
The RpClumpRegisterPluginStream() function accepts three function
pointers. Respectively, these are for reading, writing and returning the size
of the additional data our functions will place into the stream.
✎
It is important to note that RpClumpRegisterPluginStream()is part of the RpClump
plugin, not the ClumpPhysics plugin. All plugins that need to support extension of their
binary streams must implement their own registration function to allow this. For example,
the ClumpPhysics plugin would need to implement an
RpClumpPhysicsRegisterPluginStream() function.
Determining the Size of a Chunk
A stream chunk is not assumed to be fixed in size.
One reason for this is that plugins may extend existing chunk types rather
than utilizing their own. Another issue is that some platforms work better if
data is padded to a certain minimum block size. (This is often the case on
consoles which make heavy use of caches and other hardware tricks.)
Every chunk type needs to have its own chunk size function. This function
will call the chunk size functions for any extensions within that chunk so, if
another plugin extends the same chunk, it too must implement a chunk
size function.
This gives RenderWare Graphics a means by which it can determine the full
size of a chunk: adding up the results of all the chunk size functions
implemented for a chunk type gives the total size of the complex chunk.
I-172
22 April 2003
RenderWare Binary Streams
Reading and Writing
Writing platform independent data to a stream is not as straightforward as
it sounds. RenderWare Graphics' multi-platform nature means we have to
take into account such things as packing sizes, default datatype sizes and
even the endian-ness of the data. Otherwise, data written out on one
platform may not be readable on another.
Endian-ness
Depending on the processor used at the heart of your target platform, data
can be stored in one of two formats: big-endian or little-endian. This defines
the byte-order of datatypes larger than a single byte when these are stored
in RAM.
The table below uses hexadecimal notation to show the difference between
the two forms when storing the hexadecimal 4-byte number "0x12345678":
BIG-ENDIAN
LITTLE-ENDIAN
0x12 0x34 0x56 0x78
0x78 0x56 0x34 0x12
As you can see, all the endian-ness means is which order bytes are stored.
Little-endian format places the least significant byte ("LSB") first, while bigendian format places the most significant byte ("MSB") first.
This means you cannot simply throw your data structures at the stream as
there's no guarantee that the raw bytes will be read back correctly on
another platform. The solution is to standardize on some basic datatypes
and make sure the endian-ness of the streamed data is consistent across
all platforms.
In RenderWare Graphics, we've chosen little-endian format as our
standard. This was picked mainly because we use PCs to develop on and
these use little-endian format. This standard is used for all streams,
regardless of platform, so streams written on a big-endian platform will be
converted to little-endian form. On platforms that use little-endian format,
no endian-ness conversion takes place.
The table below shows which of our key platforms uses which storage
format:
PLATFORM
CPU
STORAGE FORMAT
Sony PlayStation 2
Microsoft Xbox
PC
(Direct3D / OpenGL)
MacOS (OpenGL)
MIPS-based core
Intel Pentium III
Various x86compatible CPUs
Little-endian
Little-endian
Little-endian
Motorola / IBM
PowerPC
Motorola / IBM
PowerPC
Big-endian
NINTENDO
GAMECUBE
RenderWare Graphics 3.5
Big-endian
I-173
Chapter 8- Serialization
Endian-ness Conversion
The endian-ness of individual platforms makes it impossible to create data
streams that are cross-platform compatible without some conversion work.
The RwMem part of the core library API provides such conversion functions.
Some of the streaming functions—see the next section—perform these
conversions internally. However, you must use the conversion functions
described here if your application uses only the basic
RwStreamRead()/RwStreamWrite() functions.
An important point to note is that none of the RwMem conversion functions
will change the physical size of the data being converted, so a "Float32"
occupies the same number of bytes as an RwReal value. This makes
calculating the size of the data to be read or written easier.
The functions are:
•
RwMemFloat32ToReal()
Used when reading from the stream: this function reverses the
conversion process performed by RwMemRealToFloat32() and gives you
back your original array of RwReal values. The RwMemNative32()
function should be called first.
•
RwMemLittleEndian32()
RwMemLittleEndian16()
Used when writing to the stream: this function converts the integer data
you've pointed it at and converts the data to little-endian format if
necessary. (On platforms that natively use little-endian format, this
function has no effect.)
•
RwMemNative32()
RwMemNative16()
Used when reading from the stream: this function converts the littleendian data read in from the stream into the native endian-ness of the
platform. (As with its counterpart, this function has no effect if the
platform uses little-endian format.)
•
RwMemRealToFloat32()
Used when writing to the stream: this function converts an array of
RwReals to a standard 32-bit floating point format for streaming. The
appropriate RwMemLittleEndian32() function should be called after
this.
Reading & Writing to a Stream
Once the data has been converted, the RwStream API is used to write the
individual data elements to the stream. When reading data, the process is
reversed.
I-174
22 April 2003
RenderWare Binary Streams
Endian-ness Conversion
Endian-ness conversion must be performed explicitly if using the
RwStreamRead()/RwStreamWrite() functions. However, when using the
streaming functions that know about their type—such as
RwStreamReadInt32() or RwStreamWriteReal()—you do not need to
perform explicit endian-ness conversion: these functions perform the
conversion internally. It is usual for developers to avoid using
RwStreamRead()/RwStreamWrite() wherever possible.
The following two tables list the read and write functions respectively.
Stream Reading Functions
These functions read data from a binary stream. Those functions with an
explicit datatype as part of their name will perform any endian-ness
conversions internally, if necessary.
READ FUNCTION
PURPOSE
RwStreamRead()
Reads the specified number of
bytes from the specified stream
into the given data buffer.
RwStreamReadChunkHeaderInfo()
RwStreamReadInt16()
RwStreamReadInt32()
RwStreamReadReal()
RwStreamSkip()
RenderWare Graphics 3.5
This function requires explicit
endian-ness conversion.
Reads the Chunk Header
information and stores it into the
RwChunkHeaderInfo structure
provided. (Intended mainly for
diagnostics.)
Reads an array of 16-bit RwInt16
values from the stream into the
specified buffer.
Reads an array of 32-bit RwInt32
values from the stream into the
specified buffer.
Used to read an array of RwReal
data values from the stream into
the specified buffer.
Used to skip the specified number
of bytes in the given stream.
I-175
Chapter 8- Serialization
Stream Writing Functions
These functions write data to a binary stream. Those functions with an
explicit datatype as part of their name will perform any endian-ness
conversions internally, if necessary.
WRITE FUNCTION
PURPOSE
RwStreamWrite()
Writes the specified number of bytes
to the specified stream from the given
data buffer.
This function requires explicit endianness conversion.
Used to write a chunk header to the
specified stream. This function would
typically be used by an application
wishing to write application specific
data to a file.
Writes an array of 16-bit RwInt16
values to the stream from the specified
buffer.
Writes an array of 32-bit RwInt32
values to the stream from the specified
buffer.
Used to write an array of RwReal
values to the stream from the specified
buffer.
RwStreamWriteChunkHeader()
RwStreamWriteInt16()
RwStreamWriteInt32()
RwStreamWriteReal()
8.3.3
Explicit Streaming Functions
In many cases, RenderWare Graphics' supplied plugins implement and
expose streaming functions to serialize their objects explicitly. The
RpClumpStreamRead() function is an example of such a function.
When developing custom plugins and objects, it is worth considering
exposing similar, high-level functions. This makes it easier for developers
using the plugin to stream the plugin's data without having to explicitly
parse its individual components—a task which becomes a chore if the
plugin is a complex one.
Another, very important, advantage of implementing high-level functions in
this way is so that the function can perform any required pre- or postprocessing transparently. This avoids the need for developers to remember
to perform such processes explicitly.
In most cases, you will have already implemented the necessary low-level
functionality needed to implement high-level functions, so adding them to
your plugin's API is usually trivial.
I-176
22 April 2003
RenderWare Binary Streams
Using Explicit Streaming Functions
In the previous section, 8.3.2 Serializing Objects, we looked at serialization
from within a plugin. This is important to know, but what if your
application needs to read or write an object to a stream directly?
Although it is not entirely necessary for it to do so, it is good practice for
your plugin to implement high-level stream-read and stream-write
functions. The application to which the plugin is attached should be
responsible for managing the streams.
This is best illustrated with an example.
Reading a Clump Object
The clump (RpClump) object, part of the World plugin (RpWorld), is a
complex object, containing additional objects such as frames (RwFrame) and
atomics (RpAtomic).
All this complexity is handled by callback functions set up by the plugin
itself when it is attached to your application. This makes reading a clump
object very simple.
First, we need to declare our stream and clump objects:
RwStream *stream;
RpClump *newClump;
Next, we open our binary stream:
stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD,
"myclump.rws");
(Remember, the .rws filename extension is purely a reminder that this is a
RenderWare Graphics binary stream.)
Now we can check that the stream was opened and locate our clump object
within the stream:
if( stream )
{
if( RwStreamFindChunk(stream, rwID_CLUMP, NULL, NULL) )
The RwStreamFindChunk() function call above locates the first occurrence
of a chunk with a chunk ID of rwID_CLUMP. An .rws file may contain more
than one clump, so it may be necessary to identify each clump unless the
developer is aware of the exact contents of the file. One method by which
the identification may take place is by using a table of contents (TOC). See
8.3.4 RWS files for information about TOCs in .rws files.
RenderWare Graphics 3.5
I-177
Chapter 8- Serialization
With the correct chunk located, the application can now read the clump
data.
{
newClump = RpClumpStreamRead(stream);
}
Finally, we should close the stream as we no longer need to read anything
else from it.
RwStreamClose(stream, NULL);
}
Writing a Clump Object
This process is rare within a game, but applications written as part of a
tool-chain, such as an exporter for a modeling package, will need to
perform this operation frequently.
Writing an object is very similar to reading one. Again, we'll use a clump
object for our example, which will assume that myClump contains a valid
clump object for writing.
First, we need to declare our stream object:
RwStream *stream;
Next, we need to open a stream for writing. This uses the same function as
for reading, but with a different flag. (These flags are covered in section
8.3.5, Stream Types.)
stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMWRITE,
"myclump.rws");
At this point we should check that the stream was opened:
if( stream )
{
Now the data can be written to the stream:
RpClumpStreamWrite( myClump, stream );
}
Finally, the stream should be closed:
RwStreamClose(stream, NULL);
Designing an Explicit Streaming API
It is not a requirement that a plugin exposes a high-level streaming API as
there are a number of different ways in which a plugin can be implemented.
Two examples of plugins that may not need such an API are:
•
Plugins that extend existing objects – if a plugin extends an existing object, there is
usually no need for a high-level API. This is because streaming the original object
will automatically cause RenderWare Graphics' streaming API to call the
appropriate callbacks for the extended data.
I-178
22 April 2003
RenderWare Binary Streams
•
Plugins that implement objects that do not need to be streamed – for instance, a
plugin designed for run-time diagnostics may not need to serialize its objects at all.
If there is nothing to be gained by allowing your plugin to stream its
objects, don't implement a streaming API for it. However, if you decide your
plugin does need to support explicit serialization of its objects, you will
need to use the RwStreamRead() and RwStreamWrite() functions—as
outlined in 8.3.2 Serializing Objects.
Chunk Headers
Any object that supports streaming must explicitly write a header chunk by
calling RwStreamWriteChunkHeader() with both the chunk ID (discussed
in 8.3.1 Binary Stream Structure) and the size of the object's data.
It is important to note that reading the object data from a stream does not
require the reading of the chunk header as the call to
RwStreamFindChunk()—made by the calling application—performs this
process.
RenderWare Graphics 3.5
I-179
Chapter 8- Serialization
8.3.4
RWS files
RWS files, identified by the .rws extension, extend the concept of
RenderWare Graphics' binary streams to group related streams together
into a single stream. An .rws file is designed to contain any number of
clumps, worlds, texture dictionaries, etc. For example, it would be common
to find a world and it's textures together in an .rws file.
There are no specific streaming functions for .rws files. The developer
should just use the standard RenderWare Graphics read/write streaming
functions described in this chapter on a single stream.
The default export option in the RenderWare Graphics exporters for
3dsmax and Maya are to save .rws files. The Visualizer viewer also is
capable of reading .rws files.
Given broad uses of grouping related streams together, a single .rws file
may contain many objects. Hence, .rws files usually contain another type
of object at their head called an RtTOC, or Table of Contents (TOC), to keep
track of what the .rws file contains.
Table of Contents Creation
Given an existing stream containing many chunks, a TOC may be created
using RtTOCCreate() that parses this stream constructing an entry per
chunk. This TOC may then be prefixed to the original stream using
RtTOCStreamWrite().
The entries in the TOC contain the ID of the chunk and a byte offset from
the beginning of the stream to the entry's chunk header. This convention is
used so that if a TOC entry's offset is used to skip through a stream, the
usual RenderWare Graphics stream reading conventions can then be used
to read the required chunk, as if the stream had been read sequentially.
✎
The TOC entries also contain a GUID that uniquely identifies the chunk. A GUID is
automatically created by the RenderWare Graphics exporters for each new asset created
in a supported modeling package. One such use of the GUID is to identify a unique chunk
in an RWS file that contains many chunks of the same ID.
Using a Table of Contents
There are several uses and usage approaches for the TOC in an .rws file.
The first is to quickly scan what an .rws file contains.
1. Open the .rws file for reading using RwStreamOpen() and the rwSTREAMREAD flag.
2. Find the TOC using RwStreamFindChunk() with the rwID_TOC ID.
3. Read the RtTOC using RtTOCStreamRead().
4. Close the stream using RwStreamClose().
I-180
22 April 2003
RenderWare Binary Streams
RtTOCGetNumEntries() can be used to query how many entries there are
in the TOC. RtTOCGetEntry() can be used to obtain an entry in the TOC,
identified by it's zero-based index. The use of this entry is then application
specific. For example, an ordered list of the chunk types can be obtained by
simply looping through all TOC entries enumerating their ID.
The second use for a TOC is to read entries from the stream. The
application should be aware of whether the entries are to be read
sequentially or non-sequentially.
For a sequential read, the TOC need only be used to predetermine the
chunk ID of the next entry. A single RWS load function would only be
needed to cater for all chunk types, rather than individual load functions
per chunk type.
For a non-sequential read, the TOC can be used to skip regions of the
stream to gain access to a specific chunk without having to perform a
search using RwStreamFindChunk(). The usefulness of this becomes
apparent when an .rws file contains multiple instances of the same chunk
ID, e.g. two (rwID_WORLD) worlds, as you can preprocess the TOC entry
without having to perform expensive stream operations.
The byte offset of the TOC entry's chunk header is relative to the beginning
of the stream. Hence, before that offset can be used in RwStreamSkip(),
the stream position must be reset to the beginning. To do this, the stream
must be closed and then re-opened.
After a skip has been performed, the chunk should be read in the same
manner as if it had been read sequentially from the stream. This is because
the offset is to the chunk's header, as mentioned earlier.
Whatever the TOC may be used for, it should be destroyed with
RtTOCDestroy once finished with.
RenderWare Graphics 3.5
I-181
Chapter 8- Serialization
8.3.5
Stream Types
RenderWare binary streams are not limited to file-based streams.
The RwStreamOpen() function therefore has two flag parameters. The first
defines the type of stream to use and the possible flags are listed in the
table below:
FLAG
PURPOSE
rwSTREAMFILE
The stream is to a disk file that has been set
up by the user. The access mode should
match that used when the file was opened.
The type-specific argument should be set to
the file's pointer (usually of type FILE *).
rwSTREAMFILENAME
The stream is to a disk file that has not been
set up by the user. The type-specific
argument should be set to the desired
filename.
The stream is to a chunk of memory. If
access type is rwSTREAMAPPEND then the
chunk of memory must have been created
using RwMalloc as RenderWare may
subsequently try to use RwRealloc to gain
more memory. The type specific argument
should be a pointer to the memory chunk
(RwMemory *) giving the position and size of
the chunk to use.
rwSTREAMMEMORY
The second flag parameter determines how the stream is opened:
FLAG
PURPOSE
rwSTREAMREAD
rwSTREAMWRITE
Opens a stream for reading only.
Opens a stream for writing only. If the
stream is of type rwSTREAMFILE or
rwSTREAMFILENAME the file size will be
reduced to zero when the stream is opened.
Opens a stream to which data will be
appended.
rwSTREAMAPPEND
I-182
22 April 2003
Summary
8.4 Summary
RenderWare Graphics supports both a low-level file I/O API and a highlevel streaming API.
8.4.1
File I/O API
Low-level access to files on disk is accessed through the RwFileFunctions
structure. This structure, which can be overwritten with custom functions,
exposes an ANSI-compliant set of file I/O functions:
8.4.2
RenderWare Binary Streams
Binary streams can contain simple objects, or complex ones. Complex
objects can contain other objects—including other complex objects—so a
stream's structure can be viewed as a tree.
The Stream Viewer application, strview.exe, can be used to examine
binary streams. It can be found in the [SDK-ROOT]/tool/strview/ folder.
Stream Types
RenderWare binary streams are usually file-based, but memory-based
streams are also supported.
Chunk IDs
All objects are stored in chunks, which are the building-blocks of
RenderWare binary stream. A chunk for a particular object is identified by
its chunk ID.
Chunk IDs are generated using the MAKECHUNKID() macro, which takes
your vendor ID (used to log-in to the developer support website) and an
object ID—between 0 and 255—which identifies the object itself. This is the
same mechanism used for plugin IDs, so care should be taken not to
confuse the two.
Serializing Objects
Object serialization is the responsibility of the plugin within which the
object resides.
Serializable objects must implement the three callback functions necessary
for RwRegisterPluginStream(). These functions are:
•
a chunk read function;
•
a chunk write function;
RenderWare Graphics 3.5
I-183
Chapter 8- Serialization
•
a function that returns the size of the chunk.
The developer can choose to implement an object as either:
•
a container object, (e.g. RpClump and RpWorld)
•
an extension to another object, (e.g. RpMatFX)
•
a stand-alone object (e.g. RpLight).
Container objects should expose a high-level serialization API, as should
stand-alone objects. Objects that extend an existing object rarely need to
expose a high-level serialization API, unless the object can also be used as a
stand-alone object.
In all cases, callback functions for serialization are necessary if the object is
to support serialization at all.
Registering the Stream Functions
Plugin objects that support both the RenderWare Graphics binary stream
API and extension via the plugin mechanism must call two plugin
registration functions.
The first function will be either one of two choices:
•
RwRegisterPlugin(), which registers the plugin with the core
directly and is used only if the plugin does not extend other objects
itself, or
•
...RegisterPlugin(), which belongs to the API of the object
which the plugin is to extend.
The second function, ...RegisterPluginStream(), belongs to the API of
the plugin that contains the object to be extended. It registers the
serialization callback functions with that base object, so that it knows how
to load the extended data.
Endian-ness
Data in a stream uses a little-endian storage format, so conversion
functions—supplied by the RwMem API—must be used to ensure all the
streamed data is in the right format.
RWS files
The concept of the RenderWare Graphics binary stream can be extended to
RWS files that may contain all art assets packaged together. To keep track
of the contents of an RWS file, a Table of Contents is attached to the
beginning of the file.
I-184
22 April 2003
Chapter 9
Debugging and
Error Handling
Chapter 9- Debugging and Error Handling
9.1RenderWare Graphics Errors
RenderWare Graphics functions return error codes using the RwError API.
This is a simple, minimal impact, general-purpose error reporting
mechanism that has minimal impact on application performance even if
heavily used.
The API has two functions, RwErrorSet() and RwErrorGet(), which are
used to set or retrieve error codes respectively.
By convention, most RenderWare Graphics functions will return:
• a pointer to an object if successful;
• NULL to represent failure.
Should an API function fail, developers can check what the error code of the
last function was using RwErrorGet().
Error codes take the form of an integer matching an enumerated value,
such as E_RW_INVRASTERSIZE, ("Invalid Raster Size").
Error code enumerations can be found in the appropriate [SDKROOT]/rwsdk/include/ folder corresponding to the build target. The files
have one of two extensions:
• .def – for common error codes and those used by the core library;
• .rpe – for error codes used by specific plugins and toolkits.
I-186
22 April 2003
RenderWare Graphics Builds
9.2RenderWare Graphics Builds
RenderWare Graphics libraries are supplied in three different builds:
Release, Metrics and Debug.
Release Build, as its name implies, is for release builds of your
applications. It has no debugging information or unnecessary hooks; it's a
lean, mean rendering machine.
Metrics Build is a modified version of the Release Build, exposing hooks in
the rendering engine that can be queried with RwEngineGetMetrics(). The
metrics structure accumulates values since the last call to either
RwCameraShowRaster() or RwRasterShowRaster(), and is most useful
when examined immediately before calls to these functions.
The format of the data structure returned by this function will vary by
platform – on Sony's PlayStation 2, for instance, it will cover aspects such
as DMA and Vector Unit utilization.
Finally, we come to the Debug Build. This set of libraries has been built
with debug message logging enabled, so that a log file (with a file extension
of .log) is created while running. This log file lists assert messages, errors,
bad arguments and similar reports generated by the RenderWare Graphics
API.
The log file is generated through the RwDebug object, which we'll look at
shortly.
RenderWare Graphics 3.5
I-187
Chapter 9- Debugging and Error Handling
9.3The Debug Object
When using a Debug Build of RenderWare Graphics, the RwDebug object
becomes active. In the other library builds, the object does nothing.
This object maintains a simple debugging information reporting system,
with output being handled by a Debug Stream Handler function. The
default function simply diverts the messages to a file called "rwdebug.log",
or, in the case of some console platforms, it sends the data across a
network or other target/host link.
This handler can be replaced by your own function with the
RwDebugSetHandler() function. This function controls output for all
RenderWare Graphics messages, including those emitted by assert and
trace (covered in 9.4) messages. These messages are all disabled in release
and metrics builds.
An important, but often missed, point to understand is that a Debug Build
of RenderWare Graphics is designed to behave exactly as if it were a
Release Build. The only difference is the activation of the RwDebug API and
the logging of any asserts and errors raised while running.
This is an intentional design feature. Our view is that if an application is
going to crash in Release Build, it should also crash in Debug Build. This
may sound extreme, but it has the advantage of dramatically reducing
unpleasant surprises when you're ready to build a release. In particular, it
avoids the problem of bugs that cannot be repeated in a debug build.
It is also important to note that overuse of the RwDebug functionality is very
likely to affect performance, particularly if the output is being streamed to a
file. For example, we do not advise placing long, descriptive messages in the
stream for functions likely to be frequently called within the inner loop of a
rendering cycle.
9.3.1
The Default Debug Stream Handler
As we saw earlier, the default Debug Stream Handler outputs to a log file
named "rwdebug.log". This file is either stored in the current working
directory, or, on platforms where this isn't possible, is transmitted to the
host (development) computer.
If you have replaced the default debug stream handler with your own
functionality, then passing NULL to RwDebugSetHandler() will re-instate
it.
I-188
22 April 2003
The Debug Object
9.3.2
Sending a Message to the Debug Stream
The Debug Stream is not limited to RenderWare Graphics' own functions:
you can send your own messages to the stream using
RwDebugSendMessage(). These messages will be chronologically ordered
with any other messages, including those resulting from asserts and the
trace message mechanism.
The function takes the following parameters:
Type – Signifies whether this message is an Assert, an Error message, an
informational Message, or a simple Trace ("where am I?") message. These
are defined as rwDEBUGASSERT, rwDEBUGERROR, rwDEBUGMESSAGE and
rwDEBUGTRACE respectively.
Filename – The filename from where the message was sent. Usually, this is
the source file containing the function sending the message and can be
obtained using the ANSI C compiler directive __FILE__.
Line – The line number where this particular call to
RwDebugSendMessage() is taking place. Again, this is usually obtained
using the ANSI C compiler directive __LINE__.
Function Name – The name of the function from whence the message was
sent.
Message – The message itself.
These are the arguments passed to RwDebugSendMessage(). Most of this
information is combined before passing to the Debug Stream Handler itself.
The stream handler only receives two parameters: the Type and a Message.
The Message is a single string, usually containing the information outlined
above.
RenderWare Graphics 3.5
I-189
Chapter 9- Debugging and Error Handling
9.4Tracing RenderWare Graphics Activity
RenderWare Graphics' functions can be made to output simple Trace
messages using the RwDebugSendMessage() mechanism.
Trace messages are simple, informational "I Am Here" messages which can
be used during debugging to track the flow of execution of your application.
They are specified by passing rwDEBUGTRACE as the Type parameter to
RwDebugSendMessage().
To enable these Trace messages, use:
RwDebugSetTraceState(TRUE);
Passing FALSE will disable them.
All of RenderWare Graphics public API will output Trace messages when
the Trace State is TRUE. (This can impact performance, so the default
Trace State is FALSE.) Messages are output both on entry to and on exit
from each function.
The text below is an extract from an example Debug log with Trace enabled:
...
D:/rel/rwsdk/world/baclump.c(1740): TRACE: RpClumpForAllAtomics:
Enter
d:/rel/rwsdk/plugin/morph/rpmorph.c(1151): TRACE:
RpMorphAtomicAddTime: Enter
d:/rel/rwsdk/plugin/morph/rpmorph.c(1203): TRACE:
RpMorphAtomicAddTime: Exit
D:/rel/rwsdk/world/baclump.c(1763): TRACE: RpClumpForAllAtomics: Exit
D:/rel/rwsdk/src/bacamera.c(1580): TRACE: RwCameraClear: Enter
D:/rel/rwsdk/src/bacamera.c(1592): TRACE: RwCameraClear: Exit
D:/rel/rwsdk/src/bacamera.c(957): TRACE: RwCameraBeginUpdate: Enter
D:/rel/rwsdk/src/bacamera.c(961): TRACE: RwCameraBeginUpdate: Exit
D:/rel/rwsdk/world/baworobj.c(331): TRACE: WorldCameraBeginUpdate:
Enter
D:/rel/rwsdk/world/baworobj.c(342): TRACE: WorldCameraBeginUpdate:
Exit
D:/rel/rwsdk/src/bacamera.c(776): TRACE: CameraBeginUpdate: Enter
D:/rel/rwsdk/src/bacamera.c(810): TRACE: CameraBeginUpdate: Exit
D:/rel/rwsdk/world/baworld.c(1874): TRACE: RpWorldRender: Enter
D:/rel/rwsdk/world/baworld.c(1885): TRACE: RpWorldRender: Exit
D:/rel/rwsdk/src/bacamera.c(1118): TRACE: RwCameraGetRaster: Enter
D:/rel/rwsdk/src/bacamera.c(1123): TRACE: RwCameraGetRaster: Exit
D:/rel/rwsdk/src/baraster.c(347): TRACE: RwRasterGetWidth: Enter
D:/rel/rwsdk/src/baraster.c(351): TRACE: RwRasterGetWidth: Exit
D:/rel/rwsdk/src/bacamera.c(1118): TRACE: RwCameraGetRaster: Enter
D:/rel/rwsdk/src/bacamera.c(1123): TRACE: RwCameraGetRaster: Exit
D:/rel/rwsdk/src/baraster.c(371): TRACE: RwRasterGetHeight: Enter
D:/rel/rwsdk/src/baraster.c(375): TRACE: RwRasterGetHeight: Exit
I-190
22 April 2003
Tracing RenderWare Graphics Activity
d:/rel/rwsdk/tool/charse/rtcharse.c(943): TRACE: RtCharsetGetDesc:
Enter
d:/rel/rwsdk/tool/charse/rtcharse.c(953): TRACE: RtCharsetGetDesc:
Exit
...
RenderWare Graphics 3.5
I-191
Chapter 9- Debugging and Error Handling
9.5Replacing The Stream Handler
We saw earlier that the Debug Stream Handler can be replaced by your own
code. This is achieved through a standard callback mechanism.
The callback function prototype is defined by a typedef named
RwDebugHandler. Your callback function's prototype must match this.
Secondly, either your main program or your handler will need to open or
create any files it intends to use. Disabling the default handler will close the
"rwdebug.log" file it uses automatically, so your new handler cannot make
the assumption that it is still open for writing.
To replace the default RenderWare Graphics handler with your own, you
should call RwDebugSetHandler(), passing a pointer to your replacement
callback function as the parameter.
9.5.1
Example
The following code replaces the existing handler with a dummy handler that
outputs the supplied text only if it is an rwDEBUGTRACE type.
(This example assumes your program's global data is stored in a structure
called GlobalData and that this structure has an entry named debugFile
representing a FILE * type.)
static void
MyDebugHandler(RwDebugType type, const RwChar * debugText)
{
/* First check if output file is available... */
if ( !GlobalData.debugFile )
{
/*
* output file not initialized, better create it...
*/
GlobalData.debugFile) = RwFopen(RWSTRING("bug_out.txt"),
RWSTRING("at"));
}
/* Output message if it's the right type... */
if ( (GlobalData.debugFile) && (rwDEBUGTRACE == type) )
{
RwFwrite(debugText, (rwstrlen(debugText) * sizeof (RwChar)), 1,
RWSRCGLOBAL(debugFile));
RwFwrite(cr, (rwstrlen(cr) * sizeof (RwChar)), 1,
I-192
22 April 2003
Replacing The Stream Handler
RWSRCGLOBAL(debugFile));
RwFflush(RWSRCGLOBAL(debugFile));
}
return;
}
✎
This example handler is for illustration purposes only and has little error checking of its
own. Naturally you will want to remedy this in production code.
Setting the above handler in your RenderWare Graphics application would
be achieved by adding the following line to your code after the Engine has
been initialized:
RwDebugSetHandler(MyDebugHandler);
We can reset the default debug handler by passing NULL to the above
function, therefore there is no need to store the returned function pointer
unless you are using multiple handlers.
RenderWare Graphics 3.5
I-193
Part B
World Library
Chapter 10
World and Static
Models
Chapter 10 - World and Static Models
10.1 Introduction
This chapter explains scenes and static models, which are represented by
RpWorld and RpWorldSector. These objects are part of the World plugin
(RpWorld) which provides RenderWare Graphics' Retained Mode API.
This Plugin provides the following objects:
RpAtomic; RpClump; RpGeometry; RpInterpolator; RpLight;
RpMaterial; RpMorphTarget; RpWorld and RpWorldSector. It also adds
some extensions to the Core Library's RwCamera API.
These objects can be further extended through the plugin mechanism.
I-198
22 April 2003
Scenes & Static Models
10.2 Scenes & Static Models
10.2.1 Scenes
A typical scene will consist of:
•
Static models – the ‘scenery’
•
Dynamic models – objects that can be moved or animated
•
Dynamic lights
•
Cameras – one or more depending on the number of views required
This chapter is primarily concerned with static models. Separate chapters
are devoted to dynamic models (Atomics), Lights and Cameras.
10.2.2 RpWorld Object
The RpWorld object is a container for scenes. It links the dynamic and
static components and provides a cohesive world space in which they can
exist.
A World is bounded by a single box, which is internally subdivided into
static sectors (RpWorldSector objects). Each of these defines a cuboid
volume within the scene, and encloses a section of the static scenery.
The sectors are created by dividing up the static scenery using a binary
space partition (BSP) tree and this sectorization process is usually
performed at the exporter stage using the functions supplied by the
RtWorldImport Toolkit. This structure is used to speed up the rendering
process.
Dynamic objects such as Atomics, Lights and Cameras can be added to a
World and this allows links to be maintained between the objects and any
World Sectors to which they are relevant. When dynamic objects are moved
around, the World plugin will decide which World Sector(s) they should be
linked to, based on their location. This makes the rendering process more
efficient since:
•
Only World Sectors that are visible from the Camera need be rendered.
•
Dynamic objects that lie entirely within non-visible sectors can be
eliminated.
•
Only the dynamic lights affecting visible sectors need be considered in
lighting calculations.
RenderWare Graphics 3.5
I-199
Chapter 10 - World and Static Models
10.2.3 RpWorldSector Object
A World Sector is the static counterpart to the Geometry object, which is
used for dynamic models.
A World Sector performs two tasks:
1. Contains all Vertices, Triangles, Materials and other data that define
the scenery within the World Sector's space.
2. Maintains links with Atomics, Cameras and Lights that have been
positioned within the World Sector.
The data for the static scenery is usually divided up across multiple World
Sectors to increase the rendering engine's efficiency. This division is in the
form of a binary space partitioning ('BSP') tree.
Binary Space Partitioning
The World is sectorized by recursively slicing the geometry along axisaligned planes to produce a BSP tree. The resulting box regions are sectors.
Geometry cannot always be cleanly divided and sectors often overlap
slightly.
RenderWare Graphics uses a modified form of BSP, known as a K
Dimensional Tree (KD-tree). The difference between the two forms is that
KD-trees are always axis-aligned.
Normals & Bounding Boxes
Normals and bounding boxes are encountered when creating import and
conversion tools for World and World Sector objects.
•
Normals
These are required for lighting calculations. During the world creation
process, the normals are stored as RwV3d for full floating-point
precision, but in the final World Sectors they are compressed to triples
of type RwInt8.
•
Bounding Box
World Sectors have bounding boxes (RwBBox). Since models can rarely
be cut into neat, straight lines, the bounding boxes of neighboring
World Sectors often overlap.
I-200
22 April 2003
Iterator Functions
10.3 Iterator Functions
A number of simple iterator functions are provided to access the contents of
both RpWorld and RpWorldSector objects:
10.3.1 RpWorld Iterators
There are four RpWorld iterators:
1. RpWorldForAllClumps()
This function takes a callback (type RpClumpCallBack()), which is
called for each Clump within the specified RpWorld object. This function
will only locate Clumps that have been added to the World using
RpWorldAddClump().
2. RpWorldForAllLights()
This function takes a callback (type RpLightCallBack()), which is
called for each Light within the specified RpWorld object. This function
will only locate Lights that have been added to the World using
RpWorldAddLight().
3. RpWorldForAllMaterials()
This function takes a callback (type RpMaterialCallBack()), which is
called for each Material object within the specified RpWorld object. This
function iterates only through Materials contained within World Sectors.
Materials define how a model's surface should be rendered and are
covered in more detail in the Dynamic Models chapter.
4. RpWorldForAllWorldSectors()
This function takes a callback (type RpWorldSectorCallBack()), which
is called for each World Sector within the specified RpWorld object.
☛
This function is one of the most often-used iterators and it is often used together with
RpWorldSectorForAllAtomics().
RenderWare Graphics 3.5
I-201
Chapter 10 - World and Static Models
10.3.2 RpWorldSector Iterators
There are three RpWorldSector iterators:
1. RpWorldSectorForAllAtomics()
This function takes a callback (type RpAtomicCallBack()), which is
called for each Atomic within the specified RpWorldSector object. This
function will only locate Atomics that have been added to the World
either explicitly, using RpWorldAddAtomic(), or implicitly using
RpWorldAddClump(). It is often used in conjunction with
RpWorldForAllWorldSectors() to access all Atomics with in a World.
2. RpWorldSectorForAllLights()
This function takes a callback (type RpLightCallBack()), which is
called for each Light within the specified RpWorldSector object. This
function will only locate Lights that have been added to the World using
RpWorldAddLight().
3. RpWorldSectorForAllMeshes()
This function takes a callback (type RpMeshCallBack()), which is called
for each Mesh within the specified RpWorldSector object. This function
will only locate Meshes that are part of the static model data.
10.3.3 Collision Detection
Originally, the RpWorld API contained some basic collision detection
functionality. This has now been moved into a separate RenderWare
Graphics Plugin: RpCollision.
I-202
22 April 2003
Modeling Tools
10.4 Modeling Tools
The RenderWare Graphics modeling package exporters supplied with the
SDK can be used to export static models. Artists should read the associated
documentation installed with these exporters for details on how they work.
Developers are also advised to read these documents, as exporters for
particular modelers may not necessarily support all features.
Exported files can be read by applications.
10.4.1 Viewers
The static models exported by artists can be tested using the RenderWare
Visualizer viewer supplied with the RenderWare Graphics SDK. Using the
RenderWare Visualizer is covered in the RenderWare Visualizer Viewers
document.
The screenshot below shows this viewer displaying a static model of a
building's interior.
This viewer can display most serialized RenderWare Graphics objects
including those supported directly by the World Plugin.
RenderWare Graphics 3.5
I-203
Chapter 10 - World and Static Models
10.5 Creating Worlds
10.5.1 Creating Worlds from Foreign Data
This process is essentially the same as that performed by the RenderWare
Graphics modeling package exporters, the main difference is that such
modeling packages usually supply their own API to assist in the process.
The exporters take the model data, in the format the modeling package
exposes it, and converts it into RenderWare Graphics Worlds, Clumps,
Atomics, Morph Targets, Skinning data, etc.
The source code for these exporters is provided to give some insight into
how to write your own converter tools.
Creating Worlds
The SDK contains the World Import Toolkit (RtWorldImport). This Toolkit
provides API functions for creating an RtWorldImport object.
A RtWorldImport object is a fully exposed, un-optimized, uncompressed
format of a world. It is suitable for easy creation of a new World and its
static model data. The model data is exposed in the form of RenderWare
Graphics Vertices, Triangles, Materials, Normals etc.
The RtWorldImport object can then be converted by the World Import
Toolkit into an optimized, compressed RpWorld structure, and written to
disk. The toolkit provides controls for how this process is performed. In
addition, an optional callback is available to provide progress information
as the compression and optimization processing may take some time.
This process is illustrated by the world SDK-Example supplied with the
SDK. This creates a "buckyball" static model given the raw data and uses
the model to create a valid RpWorld object.
First, locate the world project files and open the world.c source file in
your preferred editor. The first part of the file contains model data, stored
in a bunch of ordinary arrays.
The first function in the source code is CreateWorldImport().
The steps involved are explained below:
1. Create an RtWorldImport object by calling RtWorldImportCreate().
This is the very first thing the CreateWorldImport() function does.
Once it's defined all the variables it needs, we see the following code:
worldImport = RtWorldImportCreate();
if( worldImport == NULL )
{
return NULL;
I-204
22 April 2003
Creating Worlds
}
2. Interrogate the modeling tool to find the number of triangles and
vertices in the model to be exported then call
RtWorldImportAddNumTriangles() and
RtWorldImportAddNumVertices() to create memory for your data.
The world Example is working with its own arbitrary, hand-typed data
rather than from a modeling package's internal data structures, but the
procedure remains the same…
/*
* Allocate the memory to store the world's vertices and
triangles...
*/
RtWorldImportAddNumVertices(worldImport, NOV);
RtWorldImportAddNumTriangles(worldImport, NOT);
NOV - defines the number of vertices; NOT – defines the number of
triangles
3. Call RtWorldImportGetVertices() and
RtWorldImportGetTriangles() to obtain pointers to the vertex and
triangle arrays.
4. The world example has to first generate some Textures and some
Materials to put them in, so the vertices and triangles get added later:
vertices = RtWorldImportGetVertices(worldImport);
triangles = RtWorldImportGetTriangles(worldImport);
These lines appear immediately after the two loops that generate the
texture U/V coordinates for each vertex. If you are working with a
modeling package's own data, you may be able to take these coordinates
straight out of an existing data structure.
5. Iterate over the vertex array, copying the required data from your
modeler data into the RtWorldImport object's vertices.
In the Example, this copying takes place in the middle of two long for…
loops, which also define surface normals. The code looks like this
fragment, taken from the first (pentagons) loop:
/*
* Initialize the vertices with a world-space vertex
position,
* a normal, texture coordinates and a material...
*/
vertices->OC = VertexList[PentagonList[i]];
vertices->normal = normal;
vertices->texCoords = uvPentagon[0];
vertices->matIndex = pentagonMatIndex;
vertices++;
…etc.
RenderWare Graphics 3.5
I-205
Chapter 10 - World and Static Models
6. Similarly, iterate through the triangles and store these in the triangle
array.
The same for… loops also have code like this for the triangles:
/*
* Initialize the triangles with indices into the vertex list
* and a material...
*/
triangles->vertIndex[0] = j;
triangles->vertIndex[1] = j + 2;
triangles->vertIndex[2] = j + 1;
triangles->matIndex = pentagonMatIndex;
triangles++;
…etc.
This is only a small fragment of the triangle copying code; refer to the
source code to see the full code.
7. Use the RtWorldImportAddMaterial() and
RtWorldImportForAllMaterials() functions to manage adding
Materials to the RtWorldImport object. The return value from
RtWorldImportAddMaterial() is the Material index. Materials are
linked to triangles, so Material indices need to be copied to the
appropriate elements in the RtWorldImport triangles array.
The world Example actually performs this before the vertex copying
steps. The programmer creates a standard RpMaterial object and
populates it with the Texture loaded earlier…
hexagonMaterial = RpMaterialCreate();
RpMaterialSetTexture(hexagonMaterial, hexagonTexture);
Now the Material is added to the World Import data structure…
hexagonMatIndex = RtWorldImportAddMaterial(worldImport,
hexagonMaterial);
And the process is repeated for the pentagons. (Buckyballs are built out
of hexagons and pentagons)…
pentagonMaterial = RpMaterialCreate();
RpMaterialSetTexture(pentagonMaterial, pentagonTexture);
pentagonMatIndex = RtWorldImportAddMaterial(worldImport,
pentagonMaterial);
The following two steps are optional and the world Example only
performs Step 8 as the model takes very little time to convert.
8. You can now optionally establish a callback procedure to handle the
messages sent by the converter to advise on progress. To do this, you
can use the RtWorldImportSetProgressCallback() function to
specify the function that your exporter provides. The API Reference lists
the messages that are sent.
I-206
22 April 2003
Creating Worlds
9. Modify the parameters used to control the export process, using
RtWorldImportParametersInit().
This is done in the CreateWorld() function which is also in the same
source file. The relevant code is reproduced below:
static RtWorldImportParameters params;
RtWorldImportParametersInit(¶ms);
params.flags = rpWORLDTEXTURED | rpWORLDNORMALS |
rpWORLDLIGHT;
params.conditionGeometry = FALSE;
params.calcNormals = FALSE;
10. Call RtWorldImportCreateWorld() to perform the conversion of the
RtWorldImport object into an optimized, compressed RpWorld object.
A single line of code performs this task in the Example:
world = RtWorldImportCreateWorld(worldImport, ¶ms);
This will build your world with the default scheme, one that tries to
balance the world and reduce splits to geometry and materials.
The default scheme works by examining a number of candidate
partitions for each axis, the default is 20. To change this value, to 50 in
the example below, the following code should be called before
RtWorldImportCreateWorld():
RwInt32 maxClosestCheck = 50; /* required value */
RtWorldImportSetStandardBuildPartitionSelector(
rwBUILDPARTITIONSELECTOR_DEFAULT,
(void*)&maxClosestCheck);
RtWorldImport provides the mechanisms necessary to create a world
that is partitioned in a way that is specific to your own requirements
and there are a diverse set of functions that let you partition the world
as controllably as you want. Details of these are in the white paper "BSP
trees".
RenderWare Graphics 3.5
I-207
Chapter 10 - World and Static Models
The params structure is defined as follows:
PARAMETER
PURPOSE
WorldSectorMaxSize
(RwReal)
Defines the maximum size of World
Sector.
This is generally a trade-off between
storage space and speed.
Maximum number of polygons in a
World Sector.
Set to TRUE to check the world for
validity during the build process
MaxWorldSectorPolygons
(RwInt32)
TerminatorCheck (RwBool)
CalcNormals (RwBool)
Set to TRUE to recalculate all normals.
MaxOverlapPercent
(RwReal)
Maximum amount by which World
Sectors are allowed to overlap.
Set to TRUE to perform welding and other
optimizations. (See the geometry
conditioning white paper.)
Set to TRUE if you want to specify a
minimum Bounding Box for the World.
Minimum Bounding Box (See above).
Set to TRUE to enable fixing of
T-junctions created during World
generation.
Flags to be used for the World. These
are:
rpWORLDLIGHT
rpWORLDNORMALS
rpWORLDTRISTRIP
rpWORLDTEXTURED
rpWORLDMODULATEMATERIALCOLOR
rpWORLDPRELIT
ConditionGeometry
(RwBool)
UserSpecifiedBBox
(RwBool)
UserBBox (RwBool)
FixTJunctions
(RwBool)
Flags
(RwInt32)
Finally, the RpWorld object can be serialized.
Converting custom formats
You can use a custom file format for your models, or have legacy objects for
which the original modeling tool files have become lost or incompatible with
newer tools. In such cases, it is more convenient to write a format converter
and the world Example explained earlier in this chapter.
✎
I-208
RenderWare Graphics separates static and dynamic geometry into Worlds and
Atomics/Clumps. It would therefore make little sense to convert a legacy car model into an
RpWorld object, or a complex building into an RpAtomic. RenderWare Graphics can
perform intelligent scene management with an RpWorld, and can efficiently animate
dynamic RpAtomics.
22 April 2003
Creating Worlds
Creating an Empty World
It is sometimes useful to create a "blank" World object that contains no
scenery data. Such usage is common in viewer utilities and many of the
viewers supplied with the RenderWare Graphics SDK do use empty Worlds.
These Worlds contain only an empty World Sector that fills the entire world
space and can be easily created using the RpWorldCreate() function. This
takes a bounding box (RwBBox) parameter, which defines the extents of the
single World Sector. You will find this function used frequently in the many
SDK Examples supplied on the CD.
Creation Flags
A World's model data can be handled in a number of different ways. For
instance, you might want to avoid lighting it dynamically using Lights and
just use pre-lit vertices. Or, you may want to tell the rendering pipeline that
the data is organized as triangle strips so it can run faster on the target
platform.
✎
It is not normal to change these flags once the World has been created or loaded. Doing so
may have a detrimental effect on performance.
These and other settings are made using the RpWorldSetFlags() function.
This exposes the following flags:
•
rpWORLDTEXTURED
The World has textures applied. Texture coordinates are specified on a
per vertex basis.
If reading the World data from a stream, you will need to either set up
the search path for the Textures using RwImageSetPath(), or load a
Texture Dictionary containing said Textures first.
•
rpWORLDPRELIT
The World has prelit colors.
The modeling package exporters provide full support for prelights. See
the Artists Guides supplied with the exporters for details.
•
rpWORLDNORMALS
The World has vertex normals.
Normals are a requirement if you intend to have dynamic Light objects
that affect the scenery. The rpWORLDLIGHT flag should also be set in
such cases.
•
rpWORLDLIGHT
Dynamic Light objects will light the World.
RenderWare Graphics 3.5
I-209
Chapter 10 - World and Static Models
Setting this flag tells RenderWare Graphics to allow dynamic Lights to
affect the static geometry. As this form of lighting requires additional
processing, you should take care when using this.
Dynamic Lights also need normals for the lighting calculations, so you
should also set the rpWORLDNORMALS flag as well.
Using dynamic Lights does not preclude the use of prelights, but you
may need to set the rpWORLDMODULATEMATERIALCOLOR flag if you intend
to mix the two forms to best effect.
•
rpWORLDTRISTRIP
World's static geometry can be rendered as triangle strips.
This is a hint to the rendering pipeline that the model data is optimized
as triangle strips. Triangle strips are an option available on the
RenderWare Graphics modeling package exporters.
•
rpWORLDMODULATEMATERIALCOLOR
This flag tells the rendering pipeline to take (a) lighting, (b) prelights and
(c) Material colors into account when rendering the model data. This
usually gives the most accurate rendering results, but can be expensive
in terms of processing power.
10.5.2 What is Pre-lighting?
The distinction between static and dynamic models is not the only such
division. RenderWare Graphics also supports both dynamic and static
lights.
Static lighting doesn't actually involve a separate object, as the data is
stored directly in the vertex data as arrays of RwRGBA color values. During
the rendering cycle, the pipeline will simply combine this vertex prelight
data with the Material for that vertex and extrapolate across the surface of
the triangles.
Prelights are defined by the artist in their modeling package. The artist can
position supported lighting types at the appropriate locations in their
model. Artists must then tag all static lights using a "prelight" tag (the exact
method for doing this varies from modeling package to modeling package).
At the export stage, the artist selects the appropriate option in the
RenderWare Graphics exporter's options dialog box and the exporter then
sets up the vertex lighting arrays and writes them out with the rest of the
model data.
✎
I-210
The nature of the pre-lighting processing means only some of the modeling package's full
complement of lights can be used for this purpose. See the artist documentation for
modeler-specific details.
22 April 2003
Creating Worlds
Creating Prelights using the World Import Toolkit
The World Import Toolkit exposes the RtWorldImportVertex object. This is
defined as follows:
typedef struct RtWorldImportVertexTAG
{
RwV3d OC;
/* World space vertex position */
RwV3d normal;
/* World space vertex normal */
RwRGBA preLitCol;
/* Vertex Pre-light color */
RwTexCoords texCoords; /* Vertex texture coordinates */
RwInt32 clipFlags;
/* Internal use only */
RwInt32 matIndex;
/* Vertex material index */
} RtWorldImportVertex;
As you can see, setting the prelight color is simply a case of modifying the
preLitCol element.
Static Lights
Static model prelights work a little differently compared to its dynamic
model variant. RenderWare Graphics assumes static models are completely
static – including any prelight data – so prelight colors cannot be
manipulated directly.
If you need lights that flicker, or any similar such effects, you will need to
use either dynamic lights or Atomics placed over the static model.
RenderWare Graphics 3.5
I-211
Chapter 10 - World and Static Models
10.6 Rendering
10.6.1 How to Render Worlds
Rendering a World object will render its contents. This means that, usually,
rendering a complete scene can be achieved with a single call to
RpWorldRender().
The Rendering Process
When you call RpWorldRender(), the BSP tree is searched and the visible
World Sectors are rendered in turn.
The following points should be taken into consideration:
✎
•
When each World Sector is rendered, each Atomic and Light in that
sector is rendered before the next visible World Sector is processed.
•
Rendering is performed either back-to-front, or front-to-back depending
on which is faster on that particular platform.
•
Local dynamic Light objects may only affect some World Sectors. Use
the bounding-box-to-sphere intersection collision detection functions to
identify these.
Rendering World Sectors
World Sectors are rendered automatically by calls to RpWorldRender(). It is not possible
to explicitly render a specific World Sector object.
Render Callback
It is possible to hook into the World Sector rendering process by providing a
callback function to RpWorldSetSectorRenderCallBack(). This callback
function, of type RpWorldSectorCallBackRender(), will then be triggered
prior to rendering each sector.
This allows you to include your own optimization techniques. The RpPVS
visibility culling Plugin uses this hook.
10.6.2 Instancing
A static geometry in RenderWare Graphics has two representations: a
platform-independent (PI) representation (also known as platform neutral)
and a platform-specific (PS) representation (also known as native data)
optimized for the underlying hardware. The process of converting from
platform neutral data to native data is called instancing. This process
normally happens only during the first rendering of the world.
I-212
22 April 2003
Rendering
Native data is not actually stored within the geometry itself. Instead, it is
allocated space in the Resource Arena. This is a cache that only stores
native data. The caching metaphor is particularly apt since existing native
data can be thrown out if there isn't enough space left to create new
instances of other geometries that need to be rendered. This can result in a
problem known as arena thrashing, whereby performance is crippled by the
need to re-instance the geometry every frame.
The Resource Arena's size is set during the start-up phase by calling the
RwEngineInit() function. Exactly what size you should set is heavily
dependent on your application, so you will need to experiment to get a good
balance between speed and efficiency. The ideal is as small as possible
without arena thrashing ever occurring during application execution.
10.6.3 Pre-instancing Static Geometry
One optimization of the above instancing scheme can be performed if it is
known that the platform independent (PI) representation will not be used at
run-time, and that is to use solely pre-instanced platform specific (PS)
representation, rather than creating it at run-time. This has the advantages
that no CPU cycles are used to instance data on their first rendering, which
gives a minor performance improvement, but also means that space is not
required for storage of the platform neutral data. In the case of static
geometry this is strongly recommended.
The RpWorldInstance() function is used to generate a persistent copy of
the native data, so at that time both representations of the world exist. The
PI representation exists as before and the PS representation both exist
outside the resource arena. When rendering occurs the platform specific
representation is always used and the resource arena is now not used by
the world during rendering.
The platform specific data generated should be considered opaque and
highly volatile as the format is subject to change between versions.
Worlds with pre-instanced geometry are serialized slightly differently from
those without. If the world is serialized, the function for writing the
geometry to the stream RpWorldStreamWrite() does not export platform
neutral data when persistent native data is present, and consequently
when the world is loaded into memory with RpGeometryStreamRead()the
PI data is lost. This is where the memory saving occurs.
As the instancing process has already been performed and is not performed
at run-time, the resource arena is never used, and the resource arena size
may be reduced accordingly. The resource arena may be eliminated
altogether if no instancing occurs, which would require any dynamic
geometry to be pre-instanced too, see the Dynamic Models chapter of this
guide.
This does mean that features which use the PI data will no longer work and
functions to get PI data will return failure codes. For instance static PVS
creation should be undertaken before pre-instancing. Collision detection is
not possible, though a lower resolution collision geometry, which is never
rendered could be used to test for collisions.
RenderWare Graphics 3.5
I-213
Chapter 10 - World and Static Models
The only exceptions to this is that the number of vertices in the geometry is
and the number of triangles in the geometry are preserved and can be read
using RpGeometryGetNumVertices() and
RpGeometryGetNumTriangles() respectively. These are stored mainly so
that sensible metrics can be observed with PS data, and the actual PI
triangle data itself is not present.
Using RpWorldInstance()
Firstly the availability of pre-instancing of worlds varies from platform to
platform, and so please check the platform specific documentation for your
platform to determine if this feature is supported for your platform.
To pre-instance a world, it is required that the world plugin is attached.
Also the correct rendering pipelines must be attached to the world and any
materials it uses before the RpWorldInstance() function is called. These
rendering pipelines may introduce PS data which is required to give the
desired effect during rendering
The RpWorldInstance() function must be called within the
RwCameraBeginUpdate() and RwCameraEndUpdate() pair of calls
within the rendering loop, as the render pipelines must be
executed to ensure that all the relevant data is created. In
practice the RpWorldInstance() function is similar to the
RpWorldRender() function but that the PS data is not created
in the resource arena but allocated from the heap, ensuring
that the data is persistent. Clipping and culling are never
performed so that all instanced data is generated even if not
inside the camera’s view frustum.
Save the world to disk using serialization functions as described below and
use this as the asset for loading from the game disk. If loading of the PS
data fails, it is sensible during development to automatically fallback to
loading a platform independent version of the asset, and flag it for preinstancing in the render loop. Then save the new pre-instanced version over
the top of the one that failed to load. This will cope with any changes to the
binary format of pre-instanced data caused by updating your version of
RenderWare Graphics.
✎
I-214
Pre-instancing should not be attempted when PVS is enabled.
22 April 2003
Serialization
10.7 Serialization
The RpWorld object supports serialization through the standard
RenderWare Graphics Binary Stream system.
Filename Extensions
✎
The ".BSP" file extension is not obligatory. RenderWare Graphics has only one file format
as such: the RenderWare Graphics Binary Stream. Different extensions are used as a
memory aid.
The functions provided by the RpWorld API for this purpose are:
•
RpWorldStreamGetSize()
This returns the size, in bytes, of the binary stream representation of
the given RpWorld object excluding dynamic objects.
✎
The size returned by this function is not the same as the size of an actual RpWorld object.
•
RpWorldStreamRead()
Reads an RpWorld object, and all the RpWorldSector objects it
contains, from the specified RenderWare Graphics binary stream.
•
RpWorldStreamWrite()
Writes an RpWorld object, all the RpWorldSector objects it contains, to
the specified RenderWare Graphics binary stream.
•
RpWorldSetStreamAlwaysCallBack()
You provide a callback function, which will be called after any
RpWorldStreamRead() operations. This function is designed to allow
plugins that extend RpWorld to initialize structures based on data read
from the stream.
The callback is called after all World Sectors have been read.
There is also an equivalent function for RpWorldSector objects, named
RpWorldSectorSetStreamAlwaysCallBack(). This exists for similar
reasons to the RpWorld function, but is called after each World Sector is
read.
✎
It is important to remember that only the static model data is referenced when serializing
RpWorld objects. Dynamic models must be written separately by explicit calls to the
appropriate …StreamRead/Write() functions.
RenderWare Graphics 3.5
I-215
Chapter 10 - World and Static Models
10.7.1 Writing
The world SDK Example includes the code needed to serialize the World
object it creates. This code is near the end of the world.c file. (The code
fragments below show only the relevant code for clarity.)
First, open a RenderWare Graphics binary stream…
RwStream *stream;
RwChar *path;
path = RsPathnameCreate(RWSTRING ("./world.bsp"));
stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMWRITE, path);
…the stream needs to be writeable, hence the rwSTREAMWRITE flag…
RsPathnameDestroy(path);
if( stream )
{
RpWorldStreamWrite(world, stream);
…now the RpWorldStreamWrite() function to write the RpWorld's static
model data to the stream.
✎
It is important to note that this function only writes static model data – the World Sectors
– to the stream. No dynamic model data is written.
At this point, all that is left is to close the stream thus:
RwStreamClose(stream, NULL);
}
These steps should result in a file on disk with the name specified in the
RwStreamOpen(). (In the code fragment above, the file would be named
"world.bsp".)
Dragging this file onto the "clmpview" viewer or the "RenderWare
Visualizer" viewer should also display the buckyball.
✎
I-216
Note that the textures are not saved with the World data as they are treated separately. In
most cases, they are already on the disk as either individually-serialized Textures (rare) or
stored together in groups as a Texture Dictionary.
22 April 2003
Serialization
10.7.2 Reading
The most common use of static models is as scenery. Normally, you will
want to read such models from a RenderWare Graphics binary stream and
render the resulting RpWorld object.
The process is:
1. Ensure the path to any Texture images has been set using
RwImageSetPath().
2. Open a RenderWare Graphics binary stream using the standard
RwStreamOpen() API.
3. Read the RpWorld object from the stream.
4. Close the stream.
5. Render the object.
RenderWare Graphics 3.5
I-217
Chapter 10 - World and Static Models
10.8 Destruction
C does not provide intrinsic support for object destructors, which means
that any objects created in a program must be destroyed explicitly.
Any objects associated with a World - the Atomics, Lights, Cameras and
static scenery - will need to be destroyed and it is important that this is
done in the correct order, as follows:
1. Remove and destroy any Clumps. These may contain collections of
Atomics, Lights, and Cameras that are automatically removed from a
World and destroyed during this process.
2. Remove and destroy any remaining Atomics, Lights, and Cameras that
were added individually to the World.
3. Finally destroy the World itself. This automatically destroys the World
Sectors and the static geometry they contain.
I-218
22 April 2003
Chapter 11
Dynamic Models
Chapter 11 - Dynamic Models
11.1 Introduction
RenderWare Graphics' Retained Mode API distinguishes between two types
of model: static and dynamic. For example, in a theater, static models are
the "scenery" and dynamic models are the "actors". A racing game would
therefore use a static model for the racing track and dynamic models for
the cars.
RenderWare Graphics assumes that a dynamic model is likely to be
manipulated in real time by the application. For example, they may be
moved around a world by animating the position and rotation of their
frames, or their vertex colors or vertex normals could be changed to adjust
the appearance of the object.
Most real-time 3D graphics programming will make use of dynamic models.
I-220
22 April 2003
The World Plugin
11.2 The World Plugin
RenderWare Graphics' Retained Mode API is contained within the world
plugin (RpWorld). This plugin defines many new object types. In this
chapter, however, we are interested in the three primary dynamic model
objects: the clump (RpClump), the atomic (RpAtomic) and the geometry
(RpGeometry). Of these new objects, only the geometry object actually
stores vertex and polygon information. The clump and atomic object are
used to help manage the geometry.
11.2.1 The Geometry Object
The geometry object contains the vertices, triangle indices, texture
coordinates and all other necessary components needed to create a model.
It represents a model, or, a part of one, and is the actual object that is
rendered.
The geometry, however, has no linkage for a frame (RwFrame) object, which
is required for positioning within a scene.
(Frames are covered in detail in the Fundamental Types chapter.)
11.2.2 The Atomic Object
An atomic contains pointers to a geometry object and a frame object. It also
contains a bounding sphere. This helps RenderWare Graphics determine
quickly whether the atomic (strictly the geometry it points to) is visible.
The atomic object provides the link between the geometry and a frame,
which allows a geometry to be located within the scene.
It is important to realize the difference between the atomic and the
geometry. The atomic is a container for geometry. The geometry defines the
data.
RenderWare Graphics 3.5
I-221
Chapter 11 - Dynamic Models
11.2.3 The Clump Object
Models tend to be quite complex and it is common for them to be broken
down into smaller separate parts, particularly with hierarchical models. In
RenderWare Graphics, a complete model is constructed from more than one
geometry object. This means that multiple atomics need to be kept track of
to manage complex models.
A clump is a container for dynamic objects that are associated with a frame
hierarchy. This usually just means atomics, but a clump might also contain
cameras and lights. A clump is a convenient place to store, say, a football
player's hierarchical model data together in one place. A clump can:
1. Add and remove atomics using RpClumpAddAtomic()and
RpClumpRemoveAtomic().
2. Render atomics in a clump using RpClumpRender().
3. Get and Set frames in a clump using RpClumpGetFrame() and
RpClumpSetFrame().
4. Load and save clumps.
We can attach a frame to a clump and link that frame to the top frame in
the model's hierarchy. This way, transforming the clump's frame will
transform the clump and the hierarchical model it contains. Be careful to
avoid falling into the trap of thinking that the clump defines the
relationship between atomics it holds. In fact, the hierarchical relationship
is determined completely by the frame hierarchy.
A Typical Clump Hierarchy of Atomics
I-222
atomic
frame
clump
atomic
frame
atomic
frame
frame
atomic
22 April 2003
The World Plugin
In the figure above, a relationship between clumps, atomics and frames is
shown. A single clump contains four atomics. The clump and first atomic
share their frame. This frame is itself a parent of a hierarchy of frames and
the clump points at the root frame for convenience. The frames in the tree
are used by the remaining three atomics. Any changes made to clump's
frame since it's the root frame, in this example, will affect all atomics.
Frames are parents of atomics, clumps and other objects, for example,
camera and lights and more information on frames can be found in the
Fundamental Types chapter.
A Complicated Clump Hierarchy of Atomics
Clump 1
clump
Clump 2
frame
atomic
atomic
clump
atomic
frame
frame
frame
frame
atomic
atomic
The figure above illustrates a more complicated clump hierarchy of atomics.
The figure above shows a clump containing atomics, although the objects
could just as easily be lights or cameras. Clumps and atomics can be
attached to frames. A clump's frame can be the parent of an atomic's frame
or a frame can be the parent of multiple atomics and multiple clumps.
Why Use Clumps?
It is not written in stone that atomics must be grouped in clumps. If you
prefer to manage atomics yourself, you are perfectly free to do so; clumps
were designed merely as a convenient container object.
That said, it can be useful to group atomics of a certain type together, even
if they are not otherwise related. For instance, you may want to keep track
of all atomics that use a particular Material so that you can get at them
easily, or you may have atomics that have special attributes – e.g., they
represent collectable items in a game. Again, clumps can be used for this.
Attaching a frame to a clump is only required if you intend to render it
using RpClumpRender(). You do not need to set up a frame otherwise.
RenderWare Graphics 3.5
I-223
Chapter 11 - Dynamic Models
The main reason for using clumps is to make use of their iterator functions,
which usually make managing hierarchies and arbitrary groups of atomics
easier.
✎
".DFF" Files
Files with the extension DFF are considered to be legacy file types from RenderWare
Graphics 3.5. These files were generally used to store clumps, but could actually contain
anything that could be streamed through the RenderWare Graphics Binary Stream API. By
definitions, a DFF would contain a single clump.
RWS files are the default binary stream file type now. These files may contain many
clumps. See the Serialization chapter for more details on RWS files.
11.2.4 Clump Destruction
RpClumpDestroy() destroys all atomics (and other objects) in the clump,
and all the frames in the hierarchy of the clump, but will not destroy the
frames of the atomics in the clump if those frames are not in the clump
hierarchy.
I-224
22 April 2003
Creation of Dynamic Models
11.3 Creation of Dynamic Models
11.3.1 Model Creation Overview
Clumps, atomics and dynamic model geometry must be created before they
can be used in a RenderWare Graphics application. Although these objects
can be created dynamically at run time, it is more common to create them
offline. Typically, one of the supported modeling packages will be used for
this process. The steps involved in exporting dynamic models from
modeling package to a file that can be read by a RenderWare Graphics
application are described in the documentation supplied with the
appropriate exporter plugins. This documentation is supplied with the Art
Tools and covers the model creation and export processes.
The end result of the export process is, by default, an ".RWS" file of the kind
we looked at briefly in the previous section. By convention, these files may
contain any number of clump objects. The RenderWare Graphics streaming
API can be used to find a clump in this RWS file. This clump will contain
one or more atomics and frames.
☛
You can test whether the export process worked by clicking RenderWareÆView in 3ds
max or Maya to launch the RenderWare Visualizer.
RenderWare Graphics 3.5
I-225
Chapter 11 - Dynamic Models
11.4 Modeling Tools
Most developers will be working with models built in a professional
modeling package by an artist. To this end, RenderWare Graphics is
supplied with a set of exporters for popular modeling packages, as well as
some tools to view and test the output from these exporters.
11.4.1 Exporters
Our modeling package exporters are available for the following:
•
Discreet 3ds max - support for versions 4 and 5.
•
Alias|Wavefront Maya - support for versions 3 and 4.
Exporters for the other packages have broadly similar functionality,
although the user interfaces and supported features do vary from package
to package.
We do not support other modeling packages directly, but we have provided
a number of RenderWare Graphics Toolkits to make it much easier to
develop your own exporters and tools.
A separate set of Artists' Tools documentation is supplied with the SDK.
Select the appropriate option in the installer to have it copied to your
computer from the CD-ROM.
11.4.2 Viewers
The RenderWare Graphics SDK comes with three viewer applets. The
viewers are RenderWare Visualizer, wrldview and clmpview. RenderWare
Visualizer allows you to easily view RenderWare Graphics artwork on any
target hardware. wrldview and clmpview deal with static and dynamic
model data respectively, using the legacy file types .BSP and .DFF.
✎
The meaning of “legacy” file types is that in the future, RenderWare Graphics exporters
may not export to these file types. However, the binary format of these files continue to be
supported, and RenderWare Graphics 3.5 will continue to read them. There is no need to
re-export existing DFF/BSP/etc. artwork as RWS files.
All viewers will accept files for viewing on the target platform. The Win32
builds for wrldview and clmpview are drag-and-drop enabled for legacy
file types. You can drop a .BSP (for wrldview) or .DFF file (for clmpview)
onto the window to view the file.
These viewers are a useful means of testing your artists' exported models to
ensure they look the way they're supposed to and contain valid data.
I-226
22 April 2003
Modeling Tools
11.4.3 Procedural Model Creation
Creating models during the execution of your game (procedural generation)
is rare. Normally, you will only ever need to load models exported from a
modeling package. However, it is always useful to understand why an
object works as it does or needs to be used in a particular way. Also, it is
important to realize that the exporters supplied with the RenderWare
Graphics SDK are regular RenderWare Graphics applications that make
calls into the API. To this end, this section will walk you through the
"geometry" SDK example. This example shows you how to build a clump
using the API function calls.
For simplicity, we will ignore the rendering process of the example, and
concentrate on the clump creation code.
Overview
The code in the example/geometry the geometry.c source file concerns
itself with the construction of a simple buckyball object, as shown in the
screen shot below. The "buckyball" is a "truncated icosahedron". The model
is built from interconnected hexagons and pentagons.
buckyball
11.4.4 Vertices & Triangles
The first stage in model creation is to define the data.
RenderWare Graphics 3.5
I-227
Chapter 11 - Dynamic Models
All 3D geometry is defined in terms of vertices. These vertices are linked
together to form polygons. The RenderWare Graphics geometry object
supports only triangles, which is why the RenderWare Graphics' geometry
objects are defined in terms of triangle (RpTriangle) objects.
The first section of the geometry.c source file therefore consists of long
lists of coordinates (vertices) and array indices, which define our buckyball
object. The first list defines 60 vertices:
static RwV3d BuckyBallVertexList[60] =
{
{
0.00f, 145.60f,
30.00f },
{
0.00f, 145.60f, -30.00f },
This list of vertices is indexed by subsequent arrays that use these vertices
to define pentagons and hexagons in terms of triangles:
static RwUInt16 BuckyBallPentagonList[5*NOP] =
{
0, 2, 4, 6, 8,
and:
static RwUInt16 BuckyBallHexagonList[6*NOH] =
{
0, 1, 20, 21, 3, 2,
Note that at this point in the example we are not defining the polygons
(triangles) that RenderWare Graphics will use, merely defining data that we
shall later use.
Object Space
The vertices that make up the buckyball model are defined in object space.
This means they are relative to the origin of the object itself and have no
relationship with the world coordinate system. The result, in this case, is
that the origin of the buckyball model is in the center of the model.
I-228
22 April 2003
Modeling Tools
11.4.5 Textures & Materials
Textures
The geometry.c source file contains one long function:
CreateBuckyBall(). This function processes the data and creates the
objects.
The first step is to load in the textures that will decorate the buckyball.
First, the programmer sets the search path for the texture data. This is
done using the Skeleton's RsPathnameCreate() function to create a valid,
platform-dependent path. This path is then fed to the RwImageSetPath()
function so that RenderWare Graphics knows where to search for the
texture map files. RenderWare Graphics will use the path name(s) to
determine where on the file system to look for images. (This is similar in
concept to the PATH variable found in many CLI-based operating systems.)
In RenderWare Graphics, multiple locations can be specified, by separating
the paths by semi-colons.
Next comes the actual creation of the texture objects with the
RwTextureRead() function. The calls to RwTextureSetFilterMode() tells
RenderWare Graphics that these textures are to use the "linear" filter mode.
The filter mode that is set for each triangle is used by the rendering
hardware to control how to texture map the surface. A linear filter mode
helps "soften" the texture.
In the code below, we load two textures from disk. These textures will be
used to texture map the pentagon polygons, and the hexagon polygons
respectively.
/*
* Create the bucky-ball textures...
*/
path = RsPathnameCreate(RWSTRING("./textures/"));
RwImageSetPath(path);
RsPathnameDestroy(path);
pentagonTexture = RwTextureRead(RWSTRING("dai"), NULL);
RwTextureSetFilterMode(pentagonTexture, rwFILTERLINEAR);
hexagonTexture = RwTextureRead(RWSTRING("whiteash"), NULL);
RwTextureSetFilterMode(hexagonTexture, rwFILTERLINEAR);
Textures are no use on their own. They need to be linked to the model data
in some way so that RenderWare Graphics knows when and how they
should be rendered.
RenderWare Graphics 3.5
I-229
Chapter 11 - Dynamic Models
Materials
Textures require two links with the model data. The first are the texture
coordinates (U and V) defining where the texture is applied. Texture
coordinates are stored on a per-vertex basis.
For RenderWare Graphics' Retained Mode API, the remaining link is the
material (RpMaterial) object and we can see that, indeed, the textures are
being added to two such material objects just after they are loaded:
/*
* ...and materials...
*/
pentagonMaterial = RpMaterialCreate();
RpMaterialSetTexture(pentagonMaterial, pentagonTexture);
hexagonMaterial = RpMaterialCreate();
RpMaterialSetTexture(hexagonMaterial, hexagonTexture);
A buckyball is made up of pentagons and hexagons and the example's
designer has decided to define two material objects, one each for the
pentagons and hexagons. Pentagons will therefore all share one material
(and its texture), while hexagons will share the other.
With the textures now added to a material object, the texture coordinates
need calculating for use later. These are calculated in the two subsequent
for… loops. (This is documented in the function's source code.)
Material Color
To use material colors the rpGEOMETRYMODULATEMATERIALCOLOR flag needs
to be set (see RpGeometryFlag). If a model is exported with material color
255, 255, 255, 255 the rpGEOMETRYMODULATEMATERIALCOLOR flag is not set
and the material color will not be used.
✎
I-230
Using the RenderWare Graphics exporters (3ds max or Maya), if all the materials used are
colored white, then the rpGEOMETRYMODULATEMATERIALCOLOR flag is set to OFF, otherwise
the flag is set to ON.
For worlds and patches, the flags rpWORLDMODULATEMATERIALCOLOR and
rpPATCHMESHMODULATEMATERIALCOLOR are used respectively. They are applied in the
same way as rpGEOMETRYMODULATEMATERIALCOLOR.
22 April 2003
Modeling Tools
11.4.6 Surface Properties & Geometry
The instantiation of the actual geometry object is trivial, although it is
worth noting the flags parameter. The full set of available flags is as follows:
•
rpGEOMETRYTRISTRIP
This geometry's meshes can be rendered as strips of triangles. This is
an optimization technique available on a number of platforms.
☛
Sony PlayStation2 Optimization Tip
Tri-strips are practically mandatory on this platform due to the hardware's design.
•
rpGEOMETRYTEXTURED
This geometry has textures applied. Including this flag means the
renderer will expect texture objects to be used.
•
rpGEOMETRYPRELIT
This geometry has pre-calculated lighting data.
•
rpGEOMETRYNORMALS
This geometry has normals. If your model is never going to be lit by
RenderWare Graphics' dynamic light (RpLight) objects, you can save on
system resources by not storing normals. This is particularly useful for
pre-lit models.
•
rpGEOMETRYLIGHT
This geometry will be lit by dynamic light objects.
•
rpGEOMETRYMODULATEMATERIALCOLOR
Modulate material color with vertex colors (pre-lit + lit), allowing
prelight vertex colors and dynamic lighting to be blended with the
underlying material color.
Also defined in this part of the source code is the surface property
(RwSurfaceProperty) data for the model.
Surface properties define how surfaces reflect light. The three components,
as you can see from the code, are ambient, specular and diffuse.
Respectively, they determine how much ambient light is reflected by the
object, how smooth and shiny the surface is, and how the light is spread
over the surface.
Surface properties are stored in material objects. Currently in RenderWare
Graphics, the lighting does not compute a specular contribution.
RenderWare Graphics 3.5
I-231
Chapter 11 - Dynamic Models
11.4.7 Morph Targets
Geometry objects are essentially containers, similar to atomics. Their
design is such that geometry will contain all the necessary data for a model,
or portion of a model. One of the objects the geometry contains is the morph
target (RpMorphTarget) object.
RenderWare Graphics' Retained Mode Plugin, RpWorld, is intended to
provide scene graph facilities with support for animation plugins. The
morph target object plays a part in this by supporting morph-target (also
known as "keyframe-interpolated") animation. While it is possible to
perform morph-target animation directly with RpWorld, most will use the
Morph plugin (RpMorph) to perform this kind of animation.
For morph-target animation to work, all geometry objects have at least one
morph target object. If there was no keyframe-interpolated animation
sequence exported from the modeling package then the geometry object will
contain exactly one morph target object.
The morph target and geometry objects divide the model data between
them. The triangle objects, which only reference vertices, are stored in the
geometry object. The actual vertex positions and normals themselves are
stored in the morph target(s). The prelight and UV texture coordinates for
each vertex live in the geometry object.
☛
I-232
Why?
Morph Targets exist because only the vertices need to be manipulated, not the model
topology itself.
22 April 2003
Modeling Tools
11.4.8 Pentagons & Hexagons
After retrieving the necessary pointers to the data structures, the
geometry.c then proceeds to set up the data for the pentagons. The for…
loop runs through each pentagon in the BuckyBallPentagonList array.
The loop is divided into three parts:
1. Calculate the normal for the pentagon;
2. Initialize the vertex, normal and texture coordinates for each vertex in
the polygon;
3. Assign the vertices to the triangles, which will define the pentagon, and
assign the Material object to these triangles.
These processes are performed in the next for… loop for the hexagons as
well and the result of all this processing is an almost-complete geometry.
Triangle Winding Order
It is important that triangles are defined in a specific order. During
rendering, RenderWare Graphics looks at the vertices of a Triangle and will
only render those with coordinates arranged in a counter-clockwise
sequence relative to the camera. If the sequence is clockwise, the triangle is
assumed to be facing away from the virtual camera and is not rendered
(culled).
RenderWare Graphics 3.5
I-233
Chapter 11 - Dynamic Models
11.4.9 Bounding Spheres & Transformations
In this example, we want to condition the geometry such that it has an
origin at the center of the model, and has a known physical size. The next
steps perform these tasks.
The next section of code finishes off the construction of the geometry object.
It is worth closer inspection…
if( normalize )
(The calling function sets this to TRUE.)
{
/*
* Center and scale to unit size...
*/
RwSphere boundingSphere;
RwMatrix *matrix;
RwV3d temp;
RpMorphTargetCalcBoundingSphere(morphTarget,
&boundingSphere);
This function calculates a sphere that is just big enough to contain the
entire buckyball model. The RenderWare Graphics core library and the
world plugin both use bounding spheres heavily. In particular, the
bounding sphere is used to determine whether the object is within the
camera object's view frustum.
Also, if you are making use of the static geometry functionality provided by
RpWorld, the sphere is used to check which world sector(s) the model
resides in.
✎
RwSphere is a simple exposed data-type. You can find its definition in the API Reference.
Continuing with the bounding sphere calculations:
matrix = RwMatrixCreate();
RwV3dScale(&temp, &boundingSphere.center, (RwReal)-1.0f);
RwMatrixTranslate(matrix, &temp, rwCOMBINEREPLACE);
temp.x = temp.y = temp.z = (RwReal)1.0f /
boundingSphere.radius;
RwMatrixScale(matrix, &temp, rwCOMBINEPOSTCONCAT);
At this point, we have a matrix that contains two operations:
1. A translation that positions the object coordinate system origin at the
center of the buckyball;
2. A scaling operation that will shrink our buckyball model to a unit size.
I-234
22 April 2003
Modeling Tools
This means that we now have a matrix that can be used to translate and
rescale our buckyball model ready for viewing.
✎
This scaling is being done because the vertex list was calculated with paper and pen,
rather than a 3D-modeling package.
The next step is to apply the transformation matrix to our geometry object
and then to destroy the matrix itself as we no longer need it. The call into
RpGeometryTransform() will compute and set the bounding sphere for all
morph targets on our behalf.
/*
* This will re-calculate and set the new bounding sphere
* and also unlock the geometry...
*/
RpGeometryTransform(geometry, matrix);
RwMatrixDestroy(matrix);
}
If you take a look at the code branch that is taken if normalize is not set,
then you can see what code is necessary to compute and set bounding
spheres:
RwSphere boundingSphere;
RpMorphTargetCalcBoundingSphere(morphTarget, &boundingSphere);
RpMorphTargetSetBoundingSphere(morphTarget, &boundingSphere);
Note that each separate morph target in a model requires a bounding
sphere to be calculated and set. In this example, the code assumes
(correctly) that there is only a single morph target.
Locking, Unlocking
Geometry objects are created in a locked state. Geometry objects have to be
locked while they are having their actual content changed. (They can be
translated and transformed using frames without locking them.)
Unlocking the geometry will usually result in RenderWare Graphics
creating new mesh (RpMesh) objects if the model data has been
fundamentally changed. Mesh objects are covered in detail later in this
chapter.
RenderWare Graphics 3.5
I-235
Chapter 11 - Dynamic Models
11.4.10 Atomics and Clumps
We've only created a geometry object so far.
The next few lines of code put the geometry in a clump.
/*
* That's it...stick it in a single-atomic clump and return..
*/
clump = RpClumpCreate();
frame = RwFrameCreate();
RpClumpSetFrame(clump, frame);
At this point, we have an empty clump object with a frame. Clumps need
frames so that they can be moved around.
Now for the atomic…
atomic = RpAtomicCreate();
frame = RwFrameCreate();
RpAtomicSetFrame(atomic, frame);
This code has been used to create an empty atomic object with its own
frame.
RpAtomicSetGeometry(atomic, geometry, 0);
This line links the geometry to the atomic. Atomics can only contain one
geometry, so for a more complex model, multiple atomics would be needed,
each with their own geometry.
✎
The third parameter to RpAtomicSetGeometry is a flag which should only be set to TRUE if
you want to retain the bounding sphere from a previous geometry object stored in the
atomic. This is an unusual situation, and possibly, one you will never encounter.
RpClumpAddAtomic(clump, atomic);
This links the atomic with the clump, so now we have our clump, atomic
and geometry all nicely packaged. One final step remains:
RwFrameAddChild(RpClumpGetFrame(clump), frame);
This line links the clump's frame to that of the atomic.
Without this, moving the clump around will have no effect whatsoever on
the model itself; frames must be linked hierarchically like this for
transformations to grow correctly.
✎
This point is an important one. Clumps do not actually manage hierarchies themselves;
they're just dumb containers that make it easier to manage complex models.
Our clump has been now completed and the only thing left to do is to
return it to the calling function.
return clump;
I-236
22 April 2003
Objects in more detail
11.5 Objects in more detail
In this section, we'll examine some of the objects we've encountered and
look at them in more detail.
11.5.1 Reference Counting
Many RenderWare Graphics objects use a reference counting system to
avoid being destroyed prematurely. This involves objects maintaining a
counter that is incremented whenever a reference is made to said object
and the counter decremented when a reference is removed.
RenderWare Graphics provides an …AddRef() function for each object
which supports a reference counter. This function must be called when
adding a reference to an object.
To delete an object, use the equivalent …Destroy() function. This function
will only destroy the object if the reference count is at zero, otherwise it just
decrements the count.
All objects defined by the World plugin must be destroyed explicitly after
use.
For example, you cannot simply destroy an RpWorld object on the
assumption that it will automatically destroy all objects it contains as the
results of this are undefined.
Instead, you must iterate through all the contained objects, call the
appropriate RpWorldRemove…() method on each, destroy it (if required)
using the object's own …Destroy() method, and repeat for the remaining
objects in the World.
While this sounds overly complicated, it does allow objects to be reused
more easily. In the end, the benefits outweigh the costs.
11.5.2 Texture coordinates
By default, RenderWare Graphics' 3D Immediate Mode and Retained Mode
supports only one (U,V) pair per vertex. A geometry does, however, have the
ability to store up to 8 sets of UV pairs. If you need more than this, which is
highly unlikely, the plugin mechanism can be used to extend the geometry
structure.
A textured geometry must be created by passing in the appropriate flags to
RpGeometryCreate. For a single texture, use rpGEOMETRYTEXTURED. For
more textures, use rpGEOMETRYTEXCOORDSETS(n) where n is the number of
required texture coordinate sets. After the geometry is created, the storage
for each set of texture coordinates specified can be access by calling the
RpGeometryGetVertexTexCoords() API. This returns a pointer to an array
of texture coordinate pairs, RwTexCoord. There is no equivalent “set”
function.
RenderWare Graphics 3.5
I-237
Chapter 11 - Dynamic Models
Whenever the geometry is locked, you have write access to the contents of
this array. (Note however that the geometry must be locked in a mode that
supports access to texture coordinates, i.e. rpGEOMETRYLOCKTEXCOORDS,
rpGEOMETRYLOCKTEXCOORDSn, rpGEOMETRYLOCKTEXCOORDSALL, or
rpGEOMETRYLOCKALL). At all times, you have read access to this array.
How you use texture coordinates (RwTexCoords) is heavily influenced by
the target platform as well as the modeling package. For instance, ranges
might be different from platform to platform because some consoles place
limits according to their specific chipset designs.
11.5.3 Prelighting
This is a form of static lighting and full details are given in the Worlds &
Static Models chapter.
In brief, prelighting involves pre-calculating the lighting values of vertices at
design-time and storing the colors in the geometry. No further calculation is
then required for the rendering.
The major problem with this technique is that the lighting isn't "real" in any
sense: if you position another model nearby, the prelit model will not cast
any light or shadow upon it.
As we saw in the example earlier, a simple flag setting can be used to
determine if an atomic should be affected by dynamic lighting. This applies
equally to prelit and unlit models.
It should be noted that if the models are animated or transformed then
prelighting data may no longer be valid. RenderWare Graphics will continue
to use this data however.
11.5.4 Surface properties
These are stored in material objects.
Surface properties (RwSurfaceProperties) are used in dynamic lighting
calculations and basically describe how lighting reflects from the surface of
a model: whether it's shiny and just leaves a bright spot of color, or
whether it's matte and spreads the light around a bit more.
This mechanism is becoming superseded by PowerPipe API provided by
RenderWare Graphics. This API gives more control over the rendering
process.
11.5.5 Meshes
The mesh (RpMesh) object is elusive. It hides inside the geometry object and
is only barely exposed.
I-238
22 April 2003
Objects in more detail
This object is actually an internal, optimized representation of the model
topology. It is the reason why geometry objects have to be locked and
unlocked. When the model is unlocked by the application, RenderWare
Graphics will take the model data and convert it into one or more mesh
objects.
Each mesh contains a group of triangles sharing the same material object.
This minimizes render state changes required during rendering since
RenderWare Graphics will render each mesh to completion before rendering
the next.
The mesh is stored as triangle lists, triangle fans or triangle strips. The API
function RpMeshSetTristripMethod() lets you supply a callback function
to perform the tri-stripping according to your own requirements.
The choice between using tri-lists and tri-strips can be made using the
RpGeometrySetFlags() function. If rpGEOMETRYTRISTRIP is set, triangle
strips will be used, otherwise triangle lists will be used. At this time, you
cannot construct meshes that use triangle fans to represent the object.
Note that triangle strips may result in the creation of degenerate triangles,
as shown in the diagram below.
A
C
B
ABC
BCC
CCX
CXX
XXY
XYZ
X
Z
Y
In this example, there are two geometrically partitioned sections of the
strip, the ends of which are shown: one on the left and one on the right.
Since the triangle strip has to be continuous, four additional degenerate
triangles are created, the vertices of which are listed in gray. Each new
degenerate triangle introduces a duplicated vertex. RenderWare Graphics
relies on graphics hardware being accurate enough to know that a zeroarea triangle cannot cover any pixel. This is certainly true on PlayStation2.
RenderWare Graphics 3.5
I-239
Chapter 11 - Dynamic Models
11.6 Atomics, Clumps & Transformations
Frames are important when dealing with atomics and clumps. They define
the links that join hierarchical model elements together. They also give the
atomics – and therefore, their contained geometry objects – a sense of place
by giving them storage for position and orientation.
The clump, atomic and frame objects have already been covered in some
detail. This section will look at them in the context of Dynamic Models.
11.6.1 Worlds
In order to render a clump or an atomic, we usually need to add the object
to a world. Doing this gives RenderWare Graphics a frame of reference to
work with and lets RenderWare Graphics work out whether the object is
visible.
For more information on the world object, read the World & Static Models
chapter.
✎
One important point to note is that RenderWare Graphics relies on the bounding sphere
defined for each atomic to determine (a) whether it is within the World, and (b) whether it
should be rendered. A common mistake when creating atomics is to forget the calculation
of the bounding sphere and this will often result in their not being rendered, no matter
what you try and do with them!
11.6.2 Cloning
Clumps and atomics cannot be copied directly, but they can be cloned. The
functions for this are RpClumpClone() and RpAtomicClone().
What is Cloning?
The cloning process will copy the interpolator, bounding sphere, render
callback and a reference to (i.e. pointers to) the geometry object. The fact
that pointers are copied means that a cloned object will share the exact
same geometry object as the original. Changes made to the geometry affect
all clones that reference it.
✎
Cloned atomics will have no attached frame: you'll need to create and add one yourself.
Cloned clumps will copy the entire frame hierarchy.
The RpClumpClone version naturally calls RpAtomicClone for all atomics
contained in the original clump.
I-240
22 April 2003
Atomics, Clumps & Transformations
11.6.3 Iterator functions
General Iterators
RenderWare Graphics supplies iterator functions for accessing atomics
within clumps, materials within geometry objects, and so on. It is extremely
common for these iterator functions to be used together.
•
RpClumpForAllAtomics()
This iterator will call your supplied callback function on each atomic
the clump contains. You can pass a (void *) data pointer to your
callback through the iterator function to support user data. A simple
use of this iterator function would be to visit every atomic that a clump
contained, and increment a variable for each. This is a simple way to
determine how many atomics the clump contains. It is common for a
clump to contain just a single atomic. In this scenario, using the
callback mechanism is the only way to get from the clump to the
atomic. This can be inconvenient, although it is easy for an application
to extend the clump object to contain a pointer to the (single) atomic.
•
RpAtomicForAllWorldSectors()
We learned earlier that atomics, when added to worlds, are linked to
world sectors so that RenderWare Graphics can work out which
atomics can be ignored during the rendering process.
This function will iterate through all the world sectors with which the
atomic intersects, calling your supplied callback function. An example
use of this iterator would be to examine which world sectors the atomic
spans. Other iterator functions can get from a world sector to any lights
that it contains, and so these functions can locate lights that affect the
atomic.
•
RpWorldForAllClumps()
This iterator will call your supplied callback function on each clump the
world contains. You can pass a (void *) data pointer to your callback
through the iterator function to support user data. If in your game you
wanted to fade out every dynamic object, at the end of a level, say, you
could use this function to visit every clump. Other callback functions
could then be used to modify every material that each clump used.
RenderWare Graphics 3.5
I-241
Chapter 11 - Dynamic Models
•
RpWorldSectorForAllAtomics()
This iterator will call your supplied callback function on each atomic
intersecting the specified world sector. You can pass a (void *) data
pointer to your callback through the iterator function to support user
data.
•
RpGeometryForAllMaterials()
This iterator will call your supplied callback function on each material
object within the specified geometry. You can pass a (void *) data
pointer to your callback through the iterator function to support user
data. This function is typically used by an application as it gets access
to the texture that each material holds.
•
RpGeometryForAllMeshes()
This iterator will call your supplied callback function on each mesh
object within the specified geometry. You can pass a (void *) data
pointer to your callback through the iterator function to support user
data.
•
RwCameraForAllClumpsInFrustum()
This iterator will call each clump's registered callback function on all
clumps that can be seen by the specified camera object. You can pass a
(void *) data pointer to your callback through the iterator function to
support user data.
The clump's callback function is specified by the
RpClumpSetCallBack() function. You will need to set this to an
appropriate callback of your own for all clumps that you need to
intercept.
Intersection test iterator
The atomic object supports some collision-detection functionality in the
form of the following iterator:
•
RpAtomicForAllIntersections()
Requires a callback defined as type
RpIntersectionCallBackAtomic().
This callback function is triggered for each intersection found between
the atomic and the requested collision type, defined as an
RpIntersectionType enumeration.
RpIntersection defined
The collision type mentioned above is an enumeration that identifies the
type of collision primitive to test for. The types currently supported are:
I-242
22 April 2003
Atomics, Clumps & Transformations
• rpINTERSECTLINE:
Line intersections.
• rpINTERSECTPOINT:
Point intersections.
• rpINTERSECTSPHERE:
Sphere intersections.
• rpINTERSECTBOX:
Box intersection.
• rpINTERSECTATOMIC:
Atomic intersections
Atomic Rendering Callback
It is possible to set a rendering callback for individual atomics. This
callback, RpAtomicCallBackRender(), will be triggered when the atomic is
about to be rendered, either by the RpWorldRender() function, or directly
via RpAtomicRender(). This callback can be used, for example, to handle
animations on a per-atomic basis.
The callback is set using RpAtomicSetRenderCallBack().
Using atomic render callbacks can produce some very powerful techniques.
Typically an application will want to store away the atomic render callback
that is currently being used (with RpAtomicGetRenderCallBack()). This
gives the application a way to continue with the atomic rendering. In
RenderWare Graphics, this technique is called chaining function calls, or
hooking functions. One example use might be if the application wanted to
perform some high level culling. The application would store the current
atomic render function and selectively call the stored function pointer if it
wanted the atomic to be drawn. It might make the decision based on the
distance of the atomic from the viewer or some other parameter. (In fact,
this technique is exactly how the PVS plugin is implemented.)
11.6.4 Sorting Geometry objects by Material
RpGeometrySortByMaterial() is used to create a modified clone of the
specified geometry object. The modification involves sorting vertices by
material and duplicating them along material boundaries where necessary.
If the source geometry contains any RenderWare Graphics plugin
extensions, the application must provide an
RpGeometrySortByMaterialCallBack() callback function to update the
extended data as appropriate. The callback will receive pointers to:
• the original geometry;
• the new geometry;
• a mapping array that links every vertex in the new geometry with that of
the corresponding vertex in the source geometry using vertex indices,
and…
RenderWare Graphics 3.5
I-243
Chapter 11 - Dynamic Models
• the length of the mapping array, the number of vertices in the new
geometry.
On completion, each material's mesh references an independent set of
vertices within the larger vertex array of the geometry. No vertices are
shared between materials. The new geometry is returned in an unlocked
state.
11.6.5 Animation
RenderWare Graphics supports a number of animation techniques. The
World plugin itself supports only a subset of these directly: other plugins
need to be attached to use the others.
In this section, we'll look at the forms of animation available directly to the
World plugin.
Frame-based
We have already seen how frames affect the position and orientation of their
associated atomic or clump. It is worth reiterating that hierarchies of
frames can also be animated, either in whole or in part, by simply applying
transformations and rotations to the individual frames.
Using this technique, it is possible to animate hierarchical models
procedurally by simply adjusting the appropriate frame objects.
Vertex-based
Vertex-based animation is usually best left to the morph target plugin
(RpMorph). This plugin uses keyframes, defined in terms of morph target
objects, with linear interpolation between these simple animations of an
atomic.
The API does expose some functionality that will let you access the vertex
data directly. A number of animation techniques can be applied using this
API, such as UV morphing, procedural vertex animations etc.
However, there are some important notes that you need to read before you
attempt such animation:
• Geometry objects must be locked before you change any vertices.
• Geometry objects must be unlocked after you've made your changes.
• This lock-unlock cycle can be very slow. RenderWare Graphics may have
to convert and/or re-instance the model data during the cycle and this
can drastically impact performance.
I-244
22 April 2003
Atomics, Clumps & Transformations
• The only time the lock-unlock cycle is not needed is when changing
material data. The only exception to this is for PC targets, when you
want to change the material color and the modulate flag is set; this
requires the geometry prelight to be locked.
11.6.6 Skinned Models
"Skinning" is a form of model representation that applies weights to vertices
and uses these weights to morph vertices. The technique is particularly
applicable to organic character models such as humans, animals and
others with flexible skin. This form of model representation is provided by
the skin plugin (RpSkin).
RenderWare Graphics 3.5
I-245
Chapter 11 - Dynamic Models
11.7 Optimization
A RenderWare Graphics Toolkit, RtWorld, exists to provide a number of
functions for world objects.
Usually, the modeling package's RenderWare Graphics exporter plugin will
use these when writing models out in RenderWare Graphics format.
However, you can also use the functionality yourself in your own tools and
utilities.
The function of interest to us at this point is:
•
RtGeometryCalculateVertexNormals()
This function is used to calculate a normal vector for each vertex
defining the specified geometry. The geometry must have been created
with the rpGEOMETRYNORMALS flag so that the data array holding the
vertex normals is available.
A vertex normal is calculated by averaging the face normals of all
connecting polygons that share the vertex, weighted by the angle
subtended by each polygon at the vertex. If the vertex is not shared, a
normal equal to the face normal is used. The resulting vertex normals
are set to unit length.
Note that the geometry is unlocked after the vertex normals have been
calculated.
I-246
22 April 2003
Rendering
11.8 Rendering
11.8.1 How to Render Dynamic Objects
There are two ways to render a dynamic object: directly or indirectly. In
either case, the functions described need to be called between
RwCameraBeginUpdate() and RwCameraEndUpdate() pair.
Rendering Atomics and Clumps directly
Assuming you have a camera to render into, you can render directly using
either RpAtomicRender() or RpClumpRender(). You don't need to create a
world object first, although rendering without one is rare.
If you do have a world, some platforms will apply dynamic lighting to your
model, regardless of whether you added it to the world object. See the
platform-specific documentation supplied with the SDK for more details on
this.
✎
RenderWare Graphics assumes you have handled visibility calculations when rendering
directly, so it will attempt to render the model regardless of whether it is actually visible.
Although rendering the model when it isn't visible will not cause any crashes, this can be
a common cause of inefficient rendering and generally strange behavior.
Render CallBack issues
It is important to realize that rendering models with these functions will
trigger any attached render callbacks regardless of visibility. If your
callback functions are being called, but you cannot see the model on
screen, this is probably the reason.
RpWorldRender()
This function is among the most powerful, most useful functions within the
RenderWare Graphics API.
A glance at the API Reference for RpWorld will reveal functions for adding
clumps, atomics, lights and even cameras to a specified world object. When
these functions are used, they add references to the specified object to any
World Sectors within which they are located or intersect.
✎
Local & Global Lights
There are two kinds of dynamic lights: local lights, which need to have a frame attached to
them, and global lights, which do not.
Local lights include spotlights and point lights. These need a frame object to define
position and orientation. These lights are added to a world sector in the same way as an
atomic, camera or clump. This allows the rendering engine to determine which world
sector(s) are affected by the light. The number of world sector(s) affected by a Local light
depends upon their radius of effect.
Global lights include ambient and directional lights, which are assumed to affect the entire
world. These should still be added to a world, but on some platforms, they will affect all
worlds, regardless of whether they have been added to them or not.
RenderWare Graphics 3.5
I-247
Chapter 11 - Dynamic Models
The RpWorldRender() function can then be used to render an entire scene
with a single function call.
It first determines where the target camera is so it can then iterate through
all visible world sector objects within the world and render them. As it
renders each world sector, it checks it for any references to atomics,
clumps and so forth and renders any it finds.
This makes rendering a lot easier as you can just add clumps and atomics
to a world and not have to worry about render order, frustum testing,
culling, visibility etc: the RpWorldRender() function will do this for you.
✎
There is an exception to this: models with transparent materials often need a second
rendering cycle for those materials on some platforms to ensure that models are rendered
in the right order. Z sorting on the fly is not done by RenderWare Graphics.
See the "alphasrt" example to see how this situation is handled.
11.8.2 Instancing
A model in RenderWare Graphics has two representations: the platformindependent geometry/morph target data you get to play with and apply for
collision detection, and an internal, platform-dependent "instanced" form
optimized for the underlying hardware. This instantiation process usually
happens once, on first rendering the model. RenderWare Graphics performs
best when the vertices of your models stay put so it doesn't have to convert
them to the platform-specific internal form again.
Changing vertices is possible, but you have to lock the geometry first and
inform RenderWare Graphics how – or if – the data is about to change
using the lock flags. You are then free to change the vertices within the
constraints you set yourself. Once you've done that, you must unlock the
geometry. At this point, the platform-specific data is in a kind of limbo: only
when – or, indeed, if – it is rendered will RenderWare Graphics'
instantiation process kick in to convert your changed vertices into the
platform-specific form needed to keep things running fast.
Instanced data is not actually stored within the geometry itself. Instead, it
is allocated space in the Resource Arena. This is a cache that only stores
instanced data. Some platforms may store portions of instanced data in
dedicated hardware video memory for efficiency.
The caching metaphor is particularly apt since existing instanced data can
be thrown out if there isn't enough space left to create new instances. This
can result in a problem known as arena thrashing, whereby performance is
crippled by the need to repeatedly re-instance the same geometry data
during a rendering cycle because there isn't enough space to store a full
scene's instanced data.
The Resource Arena's size is set during the start-up phase by calling the
RwEngineInit() function. Exactly what size you should set is heavily
dependent on your application, so you will need to experiment to get a good
balance between speed and efficiency.
I-248
22 April 2003
Rendering
Optimizing with a Metrics Build
Determining the best Resource Arena size requires knowing how it is being
used. The metrics build of the RenderWare Graphics libraries can help you
decide on the best trade-off between speed and hardware resources by
displaying resource usage on your target platform.
The RwMetrics structure varies from platform to platform so you should
see the platform-specific documentation for more details on what is
supported on your target hardware.
This screenshot shows the Win32, Direct3D metrics build in use in the
"world" example.
11.8.3 Pre-instancing Dynamic Geometry
One optimization of the above instancing scheme can be performed if it is
known that the platform independent (PI) representation will not be used at
run-time, and that is to use solely pre-instanced platform specific (PS)
representation, rather than creating it at run-time. This has the advantages
that no CPU cycles are used to instance data on their first rendering, which
gives a minor performance improvement, but also means that space is not
required for storage of the platform independent copy of the data.
The RpAtomicInstance() function is used to generate a persistent copy of
the platform specific data, so at that time, two representations of the atomic
exist. The platform independent data and the platform specific data both
exist outside the resource arena. When rendering occurs the platform
specific representation is always used and the resource arena is now not
used by the atomic during rendering.
The platform specific data generated should be considered opaque and
highly volatile as the format is subject to change between versions.
RenderWare Graphics 3.5
I-249
Chapter 11 - Dynamic Models
Atomics with pre-instanced geometry are serialized slightly differently from
those without. If the atomic is serialized, the function for writing the
geometry to the stream RpGeometryStreamWrite() is called internally
from RpAtomicStreamWrite(). RpGeometryStreamWrite() does not
export PI data when persistent PS data is present, and consequently when
the atomic is loaded into memory with RpAtomicStreamRead() or
RpGeometryStreamRead() only the PI data is lost. This is where the
memory saving occurs.
As the instancing process has already been performed offline, and is not
performed at run-time, the resource arena is never used, and the resource
arena size may be reduced accordingly. The resource arena may be
eliminated altogether if no instancing occurs, which would require any
static geometry to be pre-instanced too, see the Worlds and Static Models
Chapter of this guide.
This does mean that features which use the PI data will no longer work and
functions to get PI data will return failure codes. For instance RpMorph and
RpDMorph will not function, and static PVS creation should be undertaken
before pre-instancing. Collision detection is not possible, though a lower
resolution collision atomic which is never rendered could be used to test for
collisions.
The only exceptions to this is that the number of vertices in the geometry,
and the number of triangles in the geometry, are preserved and can be read
using RpGeometryGetNumVertices() and
RpGeometryGetNumTriangles() respectively. These are stored mainly so
that sensible metrics can be observed with PS data, and the actual PI
triangle data itself is not present.
Using RpAtomicInstance()
Firstly the availability of pre-instancing of atomics varies from platform to
platform, and so please check the platform specific documentation for your
platform to determine if this feature is supported for your platform.
To pre-instance an atomic, it is required that the world plugin is attached.
Also the correct rendering pipelines are attached to the atomic and
materials before the RpAtomicInstance() function is called. Those
rendering pipelines may introduce PS data which is required to give the
desired effect during rendering.
The RpAtomicInstance() function must be called within the
RwCameraBeginUpdate() and RwCameraEndUpdate() pair of calls within
the rendering loop, as the render pipelines must be executed to ensure that
all the relevant data is created. In practice the RpAtomicInstance()
function is similar to the RpAtomicRender() function but that the PS data
is not created in the resource arena but allocated from the heap, ensuring
that the data is persistent. Clipping and culling are never performed so that
all instanced data is generated even if not inside the camera’s view frustum.
I-250
22 April 2003
Rendering
Save the atomic and use this as the asset for loading from the game disk. If
loading of the PS data fails, it is sensible during development to
automatically fallback to loading a platform independent version of the
asset, and flag it for pre-instancing in the render loop. Then save the new
pre-instanced version over the top of the one that failed to load. This will
cope with any changes to the binary format of pre-instanced data caused by
updating your version of RenderWare Graphics.
11.8.4 Converting Model Data to RenderWare
Graphics
RenderWare Graphics' reliance on its own data format means you may have
data that needs to be converted. This is not a particularly difficult task as a
number of utility functions are provided to assist in the conversion process.
Usually, you will want to feed in the data in one format and have valid
clump or atomic data produced as a result. This is explained below.
Conversion Overview
The steps necessary to create an atomic or clump are roughly similar. No
intermediate data type is necessary, and the exporter can create atomics
directly.
The steps involved are:
1. Create an atomic by calling RpAtomicCreate().
2. Create a geometry object by calling RpGeometryCreate().
This function requires the number of vertices and triangles needed by
the model, as well as a set of flags.
The number of vertices and triangles can be obtained from the source
data or, if developing an exporter for a modeling package, a suitable
conversion API function.
The flags should also be set up as required. For the purposes of
simplicity, it is assumed that the geometry contains normals, texture
coordinates and lighting values.
3. Obtain the default morph target object (which has an index of zero)
from the geometry using RpGeometryGetMorphTarget(). This is where
the vertices and normals are stored.
4. The UV coordinates are shared across all key-frames and can be found
in the geometry object itself, so get a pointer to them using
RpGeometryGetVertexTexCoords(). There is a one-to-one relationship
between these and the vertex array in any related morph targets.
5. Obtain the vertex and normal arrays from the morph target using
RpMorphTargetGetVertices(), and
RpMorphTargetGetVertexNormals() respectively.
RenderWare Graphics 3.5
I-251
Chapter 11 - Dynamic Models
6. Iterate over the vertices in your model, copying vertex, normal and
texture co-ordinate data from the model into the geometry arrays.
7. Create all the material objects that your model requires, taking care to
read any textures necessary from disk and setting material colors
correctly. (255 indicates a full intensity color RGB component and also
a fully opaque (non-alpha) material.)
✎
You may wish to build a Texture Dictionary object if the Null driver supports your target
platform's bitmap formats. Alternatively, you may build a Platform Independent Texture
Dictionary that can be used on any target platform. See the Rasters, Images and Textures
chapter in this guide.
8. Iterate over the triangles in your model, setting the vertex indices and
materials for all triangles in the geometry. You will need to use
RpGeometryGetTriangles() to obtain the start address in memory
where triangles are stored, and the various triangle object API functions
to prepare and store them.
9. Calculate and set a bounding sphere for your morph target, using the
API calls RpMorphTargetCalcBoundingSphere() and
RpMorphTargetSetBoundingSphere(). (This step is often forgotten,
but it is absolutely essential.)
10. Unlock the geometry.
11. Attach the geometry to the atomic with RpAtomicSetGeometry().
Take a look at the geometry example in examples folder to see the
above construction process in action on hand-made model data.
✎
Null Libraries
The Null Libraries supplied on the SDK are specifically designed for conversion work. For
instance, we use them to build our modeling package exporters.
These libraries are almost identical to the standard Release ones, with the exception that
all actual rendering functionality is removed or diverted to a null driver. This is because
conversion programs rarely need to render their output to the display while the conversion
is taking place.
In addition, it means that functionality or output formats that may not otherwise be
supported on a particular platform can be included.
Null libraries for each platform are also supplied with the SDK (for example, nullxbox).
These are PC libraries used for building certain tools that process platform specific data.
They can be used to build platform specific texture dictionaries.
It should be noted that Null platform libraries can not create pre-instanced world and
geometry data.
I-252
22 April 2003
Chapter 12
Lights
Chapter 12- Lights
12.1 Introduction
RenderWare Graphics has two kinds of lighting models: dynamic and static.
This chapter covers static lighting using RpLight. Static lighting can also be
achieved using RpLtMap.
The dynamic lighting model is the closest in behavior to real-world lighting,
with lights being independent from the model geometry.
Five light types are supported by the dynamic lighting model:
•
ambient
•
point
•
directional
•
spot
•
soft spot
Static lighting—not to be confused with static geometry—is less flexible, but
requires far fewer resources to use. This lighting model is tied to model
geometry and is implemented in one of two ways, depending on whether the
geometry itself is static or dynamic.
12.1.1 Other Documentation
I-254
•
See the API Reference Lighting section for more information about lights
and lightmaps.
ModulesÆLighting
•
Lightmaps user guide chapter
22 April 2003
Dynamic Lights
12.2 Dynamic Lights
Dynamic lights represent the most flexible light model in RenderWare
Graphics. They can:
•
be fully controlled and manipulated at run-time
•
be positioned at will and oriented in any direction
•
selectively illuminate both static and dynamic models
•
support a number of light types
•
make use of hardware transform and lighting features
Dynamic lights have one important disadvantage: the processing power
needed to implement them. On platforms with no hardware transform and
lighting support, dynamic lights will eat up a substantial proportion of
processing time, effectively limiting the number of dynamic lights your
application can use.
Another disadvantage is that hardware transform and lighting stages on
different platforms generally make use of different algorithms. The result is
that the same settings for a particular light can produce varied results
across different platforms. RenderWare Graphics therefore supports both
reference and platform-specific forms of dynamic lighting.
The reference set supports all five light types. The platform-specific models
usually support the same light types, but use the light types defined in the
underlying hardware to perform the illumination calculations. This means
the platform-specific lighting models are unlikely to give the same results
across different platforms.
The reference set light types are designed to produce very similar results
across all supported platforms. On some platforms, they may be wholly or
partially implemented using hardware lighting facilities. In other cases, the
light types are implemented in software.
Platform-specific dynamic lighting is provided mainly to enable access to all
the light types available on the platform's hardware.
✎
There are no platform-specific APIs for static lighting.
RenderWare Graphics 3.5
I-255
Chapter 12- Lights
12.2.1 Dynamic Lights Representation
Objects
RenderWare Graphics dynamic lighting models are controlled through two
objects: RpLight and RpMaterial.
The first object, RpLight, provides control over the light source itself. By
linking this to an RwFrame, the light can be positioned within an RpWorld
and, if necessary, oriented towards its target. In addition, the RpLight
object exposes a number of functions, which allow the developer to modify
the light's properties.
Effective lighting requires consideration of both the light itself and the
materials of the models it is illuminating.
The RpMaterial object defines materials that are applied to models and
therefore defines how models reflect light. This object is covered in detail in
the Dynamic Models chapter, so this chapter will only touch upon the
features that directly apply to dynamic lights.
Dynamic Lighting Models
A dynamic light is created using the RpLightCreate() function. This
function takes a constant defining the light types to be used when
processing the dynamic light.
The table on the following page lists the constants and describes the
reference light types. These are always available, regardless of the platform.
Platform-specific lighting models
Platform-specific light types are documented in the relevant section of the
API Reference and usually map directly onto light types implemented in the
platform's hardware.
✎
I-256
On the PlayStation 2 platform, all lighting models, including the reference models listed in
the table below, are implemented using custom VU code.
22 April 2003
Dynamic Lights
Reference Dynamic Light Types
NAME
LIGHTING TYPES
rpLIGHTAMBIENT
Ambient light type.
This type provides lighting from all
directions. The light source is omnipresent.
Cannot be positioned or oriented.
Directional light type.
This model simulates a light source at
infinite distance from the world.
Cannot be positioned, but can be oriented.
Point light type.
This type simulates a point source of
lighting. The light is emitted from this
source in a sphere.
Cannot be oriented, but can be positioned.
Spot light type.
This light type simulate spotlight sources,
which emit a cone of light from a specific
source in a particular direction, resulting in
a spot of light on the target.
Can be positioned and oriented.
Soft spot light type.
As rpLIGHTSPOT.
rpLIGHTDIRECTIONAL
rpLIGHTPOINT
rpLIGHTSPOT
rpLIGHTSOFTSPOT
The "soft spot" type adds a soft edge so that
the light falls off smoothly at the edge of the
spot.
Can be positioned and oriented.
12.2.2 Creating a dynamic light
The following code fragment creates an RpLight object named myLight. It
contains a dynamic light using the soft spot light (rpLIGHTSOFTSPOT)
reference light type:
RpLight *myLight;
myLight = RpLightCreate( rpLIGHTSOFTSPOT );
At this point, myLight has been created, but has not yet been initialized.
Initialization
The initialization necessary for a particular light depends on the light types
it is using. For instance, the ambient reference light type (rpLIGHTAMBIENT)
needs only a color to be set.
RenderWare Graphics 3.5
I-257
Chapter 12- Lights
In most cases however, the first step will be to attach a frame object to the
RpLight object, so it can be positioned and/or oriented within a world. Of
all the reference light types, only the ambient light type can be used
without a frame.
Position & Orientation
Assuming the myFrame frame object contains a valid, initialized RwFrame
object, the following code fragment would attach it to the light:
RpLightSetFrame( myLight, myFrame );
Attaching a frame to a light allows you to move and orient the light as
required. The features of the RwFrame object also mean this light could
easily be included in an RwFrame hierarchy along with model geometry.
Color
The next step is to set the color of the light. The RpLightSetColor()
function performs this task. It takes an RwRGBAReal value defining the RGB
and Alpha components.
Assuming that lightColor has been initialized to the required color, our
initialization continues:
RpLightSetColor( myLight, &lightColor );
Sphere of illumination
Aside from those using the ambient and directional light types, most lights
affect models within a finite sphere of illumination. This sphere is defined by
the light object's radius, an RwReal value. This can be set thus:
RpLightSetRadius( myLight, 5.0f );
This radius defines the distance over which the lighting model acts, with
the light falling off over distance according to the formula:
intensity = max
, 0 )
(radius – distance
radius
When the distance is zero, the light's intensity is at its highest. The
intensity is zero when the distance traveled is equal to the radius.
Cone Angle
Spotlights also have a cone angle property, which defines the angle of the
light cone. A wide angle results in a wide spot of light; a narrow angle gives
a smaller spot of light.
The cone angle is an RwReal value and may be set as follows:
/* 0.785 is equivalent to PI / 4, about 45 degrees */
RpLightSetConeAngle( myLight, 0.785f );
I-258
22 April 2003
Dynamic Lights
Adding the light to a world
At this stage, the light is ready. All that remains is to add it to an RpWorld
object. The fragment below assumes that the world object has been
initialized:
RpWorldAddLight( myWorld, myLight );
The application is now free to move and orient the light within the world as
well as modify its other properties.
Dynamic Lights & World Sectors
When a dynamic light is added to a world, the RpWorldAddLight()
function positions the light within a world sector object.
The light's sphere of illumination is used to determine which world sectors
the light affects. As such, a light may be referenced by more than one world
sector.
Light object flags
Light objects also include a flags property. Currently, this can be used to
inform the rendering engine which geometry types the light will affect: static
and/or dynamic.
Two flags are defined: rpLIGHTLIGHTATOMICS and rpLIGHTLIGHTWORLD.
The former, if enabled, means the light will affect dynamic models. The
latter, if enabled, means the light will affect static models. The flags should
be logically ORed together if both are needed.
The function to set or reset the flags is RpLightSetFlags(). An example of
its use appears below. The example sets the light created earlier to
illuminate both static and dynamic models:
RpLightSetFlags( myLight, rpLIGHTLIGHTATOMICS | rpLIGHTLIGHTWORLD);
Dynamic Lights, Geometry & Materials
It is possible to modify the behavior of lighting at the RpGeometry level by
manipulating the geometry flags. This lets applications enable or disable
lighting for individual atomics. The flags are exposed by the RpGeometry
object through the RpGeometrySetFlags() function.
It is important to understand that these flags are specific to the geometry
object, not an atomic. The geometry will always be illuminated according to
these flag settings.
There are two geometry flags relevant to lighting, as shown in the table
below:
RenderWare Graphics 3.5
I-259
Chapter 12- Lights
FLAG
DESCRIPTION
rpGEOMETRYLIGHT
If set, dynamic lights will illuminate the
geometry.
If cleared, dynamic lights will not
illuminate the geometry.
If set, the geometry will reflect
illumination appropriately by combining
both dynamic and static lighting to
render the correct colors.
If cleared, the geometry will not be lit at
all. Instead, the geometry will be
rendered using its material object's own
color property alone.
rpGEOMETRYMODULATEM
ATERIALCOLOR
Iterator functions
The RpLight object exposes an iterator function,
RpLightForAllWorldSectors(), which will call a user-supplied callback
function for each world sector the light affects.
12.2.3 Clump Lights & Streaming
An RpClump is a container for dynamic objects that are associated with a
Frame hierarchy, and this includes dynamic Lights. Lights can be added to
Clumps using the RpClumpAddLight() function.
•
They will be automatically streamed with the Clump and their position
within the Frame hierarchy of the Clump preserved.
•
They will be automatically destroyed with the Clump when
RpClumpDestroy() is called.
•
They will be added to and removed from Worlds with the Clump when
the functions RpWorldAddClump() and RpWorldRemoveClump() are
used.
This mechanism is used whenever dynamic Lights are exported from one of
the modeling packages. The artist is able to set up and position Lights
within a world. Once exported within a Clump, the positions are stored in
the Frame hierarchy.
12.2.4 Platform-Specific Lighting Models
Many platforms support hardware acceleration for lighting. However this
support is not identical across platforms. Such hardware often provides its
own implementation of lighting and this means lights can produce different
results on different platforms, even though they are initialized with the
same values.
I-260
22 April 2003
Dynamic Lights
The reference light types provide a means of ensuring consistent lighting
across supported platforms, but their performance will vary from platform
to platform.
RenderWare Graphics therefore exposes any platform-specific lighting
models using the same API—only the lighting type constant changes.
Platform-specific lighting types are available for Nintendo GameCube,
Microsoft DirectX (both Windows and Xbox) and OpenGL. The Sony
PlayStation 2 supports the reference lighting models in hardware.
The RenderWare Graphics API for PlayStation 2 uses VU code to perform all
rendering, so the reference lighting models are all accelerated.
RenderWare Graphics 3.5
I-261
Chapter 12- Lights
12.3 Static Lights using RpLight
Regardless of whether they are supported in hardware or software, dynamic
lights require substantial processing. So, it is wise to avoid using too many
dynamic lights.
Static lights—also known as prelights—provide a form of lighting that
avoids high processing overheads. They are a much simpler, faster,
alternative to dynamic lights. The trade-off is that static lights are very
limited in their abilities.
Static lighting can be applied to:
•
Static models – i.e. worlds. The data is stored in RpWorldSector objects.
•
Dynamic models – i.e. atomics, clumps, etc. The data is stored in
RpGeometry objects.
The first usage is by far the most common as RenderWare Graphics
modeling package exporter tools support static lighting features directly.
Artists tag model geometry and apply lighting to it. When the model is
exported, the RenderWare Graphics exporter encodes vertex lighting data
right into the geometry.
✎
The exact tagging mechanism used varies from package to package. See the art tools
documentation for full details.
At run-time, all that is needed is to load and render the geometry. The
static lighting is applied automatically when the relevant RpWorld object is
rendered.
For dynamic models, there is currently no support for exporting static
lighting data directly from the modeling package. Exporters will allocate the
necessary space for an array of RwRGBA values, but initialization of these
values must be performed explicitly, either in a custom tool, in a modified
build of the exporter, or at run-time.
Static lighting is decreasing in importance as modern graphics hardware
transform and light engines are reducing the need for processing dynamic
lighting in the CPU.
12.3.1 Creating Static Lights
Static models
Static lighting is stored as fixed vertex lighting values. In static models—i.e.
RpWorldSector data—these values are completely fixed and not exposed by
the RenderWare Graphics API. This is a requirement of the static model
rendering optimizations of RenderWare Graphics.
I-262
22 April 2003
Static Lights using RpLight
Developers building their own tools or creating static models from scratch
will find that the RtWorld and RtWorldImport toolkits support creation of
static lighting data as well as the model geometry itself.
Dynamic models
For dynamic models, static lighting is stored within RpGeometry objects.
The data is represented by an array of RwRGBA values, which can be
retrieved using RpGeometryGetPreLightColors().
The array only exists if the geometry has been created using the
rpGEOMETRYPRELIT flag. Space for the prelight array must be explicitly
allocated if you are creating geometry objects, as setting the flag will not
perform this procedure automatically.
The prelighting colors reside within the geometry's topology, at one color
per vertex, and are therefore shared between all morph targets.
12.3.2 Static Lighting Techniques
Static lights are very fast, using a negligible amount of processing power
regardless of how many such lights are used. However, limitations in their
design means that they are most often used in tandem with dynamic lights.
Some common techniques are covered next, illustrating how the illusion of
full lighting can be created without using too many dynamic lights.
Interactive static lighting
One of the most important limitations of static lighting models is that static
lights do not actually cast any light. The process creates the illusion that
light is striking the model. Static lighting affects only the vertices of the
world sector or geometry objects in which the lighting information resides.
As a result, a dynamic model passing through a statically-lit world will not
be illuminated by static lighting.
If you need to create the effect of static lights casting lights on other
models, you will need to use a dynamic light as well. In most cases, the
dynamic light can be a temporary creation, used only when the light would
be visible to the camera and an object is near enough to it.
Modifying static lights on static models
There are occasions when static lights need to be disabled or modified in
some way at run-time. This is trivial when working with statically-lit
dynamic models, but the most common use for static lights is to light static
models.
The fixed nature of static lights in static models means modification is
impossible so the effect must be achieved by using dynamic models for
areas where the static lights need to be modifiable.
RenderWare Graphics 3.5
I-263
Chapter 12- Lights
Static lights in dynamic models
Static lighting in geometry objects can be modified at run-time to simulate
glowing or pulsating lights and other similar lighting effects.
I-264
22 April 2003
Related Examples
12.4 Related Examples
Static lights are not demonstrated by any one specific example. However, a
model which has been exported from a modeling package with static
lighting can be found in the texdict example. The model can be found in
models/dungeon.bsp. RenderWare Visualizer can be used to view the
model.
RenderWare Visualizer showing a model with static lighting
The SDK includes two examples covering dynamic lights: lights and
lights2.
RenderWare Graphics 3.5
I-265
Chapter 12- Lights
The lights example illustrates the different light types available for
dynamic lights. Use the menu options to choose different types and
combinations.
The lights example
I-266
22 April 2003
Related Examples
The lights2 example illustrates how lights interact with world sectors.
When run, you will see a small landscape overlaid by wire-frame
representations of the world sectors into which it has been divided.
The lights2 example
Move the dynamic light around the scene to see how RenderWare Graphics
links the light to world sectors according to the radius of its sphere of
illumination.
✎
The world sectors shown in the lights2 example were created deliberately to show this
effect; in normal usage, such a simple landscape would not make use of more than one
world sector.
RenderWare Graphics 3.5
I-267
Chapter 12- Lights
12.5 Summary
12.5.1 Dynamic Lights
Properties table
The table below lists the main properties of the reference dynamic lighting
models. Additional properties may be added for platform-specific dynamic
lighting models.
PROPERTY
AMB.
DIR.
9
9
Color
Flags
Frame
POINT
9
9
9
Radius
SPOT
9
9
9
9
ConeAngle
SOFTSPOT
9
9
9
9
9
9
9
9
9
9
Dynamic Lighting: Main Features
•
Five reference light types:
•
rpLIGHTAMBIENT – ambient
•
rpLIGHTDIRECTIONAL – directional
•
rpLIGHTPOINT – point-source
•
rpLIGHTSPOT – spot
•
rpLIGHTSOFTSPOT – soft-edged spot
•
Platform-specific light types are provided where necessary for access to hardware
lighting.
•
Ambient lights do not require frames.
•
Directional, point lights, spot lights and soft spot lights always require frames.
•
All lights must be added to a world using RpWorldAddLight() if they are to affect
the geometry within that world.
•
All lights can selectively illuminate both static and dynamic geometry.
•
The default light settings are intended to be "safe" on all supported platforms, but of
little use in practice: you should explicitly set all of a dynamic light's properties on
creation.
I-268
22 April 2003
Summary
12.5.2 Static Lights
Static Lights: Main Features
•
Also known as prelights or prelighting.
•
A statically-lit model is known as a prelit model.
•
Cheaper in terms of processing power.
•
Prelit static models can be readily exported from modeling packages.
•
Prelit dynamic models must have their prelight data initialized by the
developer either in a custom tool, or at run-time.
•
Prelights are not real lights. They are fixed vertex illumination levels and
have no effect on nearby models.
•
Prelights in static models cannot be changed or modified in any way
whatsoever. They are not exposed.
•
A pointer to the prelight data in dynamic models can be retrieved using
RpGeometryGetPreLightColors().
RenderWare Graphics 3.5
I-269
Index
Index
Index
Page numbers in bold face indicate the most important reference to the subject, where
multiple references exist. The page numbers shown below refer to Volume I of the User
Guide.
2
C
2D graphics toolkit........................................159
C standard data types .....................................38
3
3ds max ..................................................18, 226
C++ wrapper classes .......................................15
plugins........................................................90
camera.................................................... 93, 199
anamorphic lens effect ................................99
A
cloning ......................................................110
actors............................... See dynamic geometry
destruction of ............................................108
animation .....................................................244
frame buffer ..............................................104
morph target .............................................244
orientation ................................................105
of the frame hierarchy ...............................244
orthographic views ......................................97
of vertices..................................................244
positioning ................................................105
creation of .................................................105
ANSI character strings ....................................37
projection .................................. See projection
aspect ratio .....................................................98
raster ........................................................104
at vector..........................................................49
space ........................................................144
atomic.......................................................... 221
sub-rasters .............................See sub-rasters
animation..................................................244
telephoto zoom ............................................99
bounding sphere .......................................240
view matrix ...............................................103
cloning ......................................................240
view offset .................................................100
culling from frustum ......................See culling
view window ................................................97
frame .............................................. See frame
viewpoint.....................................................96
geometry .................................... See geometry
camera space .................... 47, 96, 143, 152, 158
intercepting rendering ...............................243
chaining function calls ..................................243
iterating over ............................. 202, 241, 242
character data type .........................................37
rendering directly ......................................247
clipping
B
2D immediate mode ..................................143
immediate mode........................................152
bilinear filtering.............................................132
clipping planes................................................96
binary space partition (BSP) ..................199, 200
clmpview viewer ...................................... 17, 226
binary streams ...........................See serialization
clump .......................................................... 222
bitmap .......................115. See raster. See raster
adding to worlds........................................240
blend modes..................................................163
atomic, adding an......................................236
blitting ................................ See raster rendering
cloning ......................................................240
bounding box ......................................... 56, 200
culling from frustum ...................... See culling
bounds test .................................................56
destroying .................................................224
enlarging .....................................................56
hierarchy of atomics..................................222
build
debug..................................................16, 187
metrics ........................................ 16, 187, 249
release.................................................16, 187
iterating over ..................... 112, 201, 241, 242
procedural generation ...............................227
rendering directly ......................................247
clumps
using.........................................................223
CodeWarrior.................................. See compilers
collision detection .........................................202
I-272
22 April 2003
Index
color............................................................... 60
documentation ................................................18
alpha component........................................ 60
artists'.................................................19, 203
blending ................................................... 163
artists' tools...............................................226
palettes .................................................... 117
double buffering ............................................107
compilers
double precision arithmetic .............................40
CodeWarrior ............................................... 17
dynamic geometry .................................220, 237
Microsoft Visual C ...................................... 17
bounding...................................................234
context stack................................................ 107
example.....................................................227
converting model data .................................. 251
platform independent representation .........249
co-ordinate systems...................................43, 44
platform specific representation.........213, 249
axes ........................................................... 45
prelighting.................................................238
camera space ...................... See camera space
dynamic lights....................................... See light
device space .......................... See device space
dynamic models ............... See dynamic geometry
handedness ................................................ 44
E
object space........................... See object space
scene space ............................ See world space
screen space.......................... See device space
world space ............................ See world space
core library, the.............................................. 20
culling .......................................................... 111
D
data types
engine
closing...................................................68, 69
initializing .......................................63, 64, 69
opening ...........................................63, 65, 69
shut down .............................................68, 76
starting .................................................63, 76
stopping ................................................68, 69
terminating .................................................68
fixed point .................................................. 40
error handling ...............................................186
floating point .............................................. 40
examples
integer........................................................ 38
building.......................................................17
RwBool ....................................................... 36
camera ........................................................94
RwChar .................................................32, 37
geometry ...................................................227
RwFixed ..................................................... 40
im2d .........................................................149
RwIm2DVertex ................................. 143, 145
im3d .........................................................154
RwIm3DVertex ......................................... 152
images.......................................................119
RwInt128 ................................................... 39
lights.................................................265, 267
RwInt16 ..................................................... 39
mipmap.....................................................133
RwInt32 ..................................................... 39
plugin .........................................................83
RwInt64 ..................................................... 39
SDK ............................................................17
RwInt8 ....................................................... 39
texadrss ............................................132, 134
RwReal ....................................................... 40
world.................................................204, 249
RwRGBA .................................................. 210
exporters.................................................19, 226
RwUInt128 ................................................. 39
3ds max ....................................................226
RwUInt16 ..............................................32, 39
Maya .........................................................226
RwUInt32 ................................................... 39
Open Export framework...............................19
RwUInt64 ................................................... 39
writing.......................................................204
RwUInt8 ..................................................... 39
debugging .................................................... 188
extensions
object ..........................................................90
build ........................................................ 187
F
messages.................................................. 189
trace messages ..................................... 190
streaming ......................................... 188, 189
degenerate triangles ..................................... 239
device space ............................................47, 143
displaying models........................................... 17
RenderWare Graphics 3.5
file format
Aldus Tag Image File Format (*.TIF) ...........119
image handlers
registration ............................................119
writing...................................................119
I-273
Index
Microsoft Windows bitmap (*.BMP) ............119
test sphere ................................................111
Portable Document Format (*.PDF) ..............18
Fully Managed Support Services (FMSS)..........12
Portable Network Graphics (*.PNG) ....119, 123
website........................................................12
RenderWare Dive File Format (*.DFF) ........224
G
RenderWare Stream Format (*.RWS) ..........180
Sun Microsystems Raster Format (*.RAS) ..119
Targa (*.TGA).............................................119
file I/O function ............................................167
fclose.........................................................167
feof............................................................167
fexist .........................................................167
fflush ........................................................167
fgets ..........................................................167
fopen.........................................................167
fputs .........................................................167
fread .........................................................167
fseek .........................................................167
ftell ...........................................................167
fwrite.........................................................167
serialization...............................................183
file system .......................................................27
overloading..................................................27
files
image search paths ...................................120
gamma correction .........................................117
geometry ...................................................... 221
bounding...................................................234
dynamic lighting flag .................................231
example ....................................................227
flags ..........................................................231
locking ......................................................235
material color modulation flag ...................231
mesh................................................. 235, 238
morph target ........................ See morph target
normals flag ..............................................231
offline generation.......................................225
prelighting flag ..........................................231
texture co-ordinates ..................................237
texturing flag.............................................231
tri-strip flag...............................................231
tri-strip method.........................................239
unlocking ..................................................235
ISO 9660 convention .................................136
H
fog................................................................ 100
density ......................................................101
hardware abstraction ................................20, 27
distance ....................................................101
hooking functions .........................................243
enabling ....................................................101
exponential ...............................................101
I
fog table ....................................................102
image....................................................115, 117
linear ........................................................101
attaching bitmap to ...................................121
setting color ..............................................101
conversion
frame
from raster ............................................123
dirty ..........................................................107
to raster ........................................ 123, 125
hierarchy..................................... 52, 222, 240
copying .....................................................122
child frame ..............................................52
creating............................................. 118, 121
parent frame............................................52
destruction................................................123
root frame................................................52
example ....................................................119
siblings....................................................53
file format handlers
traversal ..................................................53
registration............................................119
local transformation matrix (LTM)..........51, 53
writing...................................................119
modeling matrix ..........................................51
loading .............................................. 118, 120
synchronizing LTMs ..................................107
mask.................................................121, 123
frame buffer ............................................98, 127
multiply referencing bitmaps .....................122
clearing .....................................................110
quantization..............................................122
frames............................................................ 51
resampling ................................................122
freelists ...........................................................71
resizing .....................................................122
front vector ..................................... See at vector
saving .......................................................120
frustum.................................................... 47, 96
search path ...............................................120
clipping ............................. See clipping planes
size ...........................................................122
culling from....................................See culling
stride ................................................ 117, 122
I-274
22 April 2003
Index
immediate mode ........................................... 142
intersection ...................................................242
2D ............................................................ 143
iterating over .............................................242
2D line lists .............................................. 147
iterators ................................................111, 241
2D polylines ............................................. 147
atomic ....................................... 202, 241, 242
2D primitives............................................ 147
clump................................ 112, 201, 241, 242
2D tri-fans................................................ 148
frame ..........................................................54
2D trilists ................................................. 147
intersection ...............................................242
2D tri-strips ............................................. 147
light ..................................................201, 202
2D vertices ............................................... 145
material.............................................201, 242
3D ............................................................ 152
mesh .................................................202, 242
3D example .............................................. 154
world.........................................................201
3D indexed primitives ........................152, 155
world sector....................... 111, 201, 202, 241
3D line lists .............................................. 154
K
3D pipeline ............................................... 156
3D polylines ............................................. 154
3D primitives.....................................154, 155
K dimensional (KD) tree.............See binary space
partition
3D tri-fans................................................ 154
L
3D tri-lists ................................................ 154
3D tri-strips ............................................. 154
3D vertex positioning ................................ 152
3D vertices ............................................... 152
lighting ................................................. 153
properties ............................................. 153
3D, applications for .................................. 156
clipping .............................................143, 152
destruction, 3D ........................................ 156
im2d example ........................................... 149
index lists................................................. 152
indexed primitives .................................... 149
platform dependence issues...................... 146
primitives ................................................. 152
render states ............................................ 142
rendering a line example........................... 150
rendering a triangle example..................... 151
rendering cycle ......................................... 154
rendering primitives ................................. 155
rendering transformed points ................... 154
transforming 3D primitives ....................... 152
vertex lists ................................................ 152
z-buffer .................................................... 144
indexed primitives ........................................ 149
infinite loop ................................... See recursion
initialization ................................................... 63
attaching plugins........................................ 68
file management ......................................... 64
plugins ....................................................... 83
subsystem .................................................. 65
video mode ................................................. 65
changing................................................. 69
enumeration ........................................... 66
setting .................................................... 66
instancing .............................................212, 248
RenderWare Graphics 3.5
language
ANSI C ........................................................14
C++ .............................................................14
libraries
dynamically linked ......................................16
null .....................................................16, 252
statically linked ...........................................16
library
core, the ...........................See core library, the
light
color..........................................................258
dynamic ............................ 212, 254, 255, 268
ambient .........................................254, 257
cone angle .............................................258
creating .................................................256
directional .....................................254, 257
initializing .............................................257
point..............................................254, 257
processing time .....................................255
soft spot ........................................254, 257
sphere of illumination............................258
spot ...............................................254, 257
example.....................................................265
geometry dynamic lighting flag ..................231
geometry prelit flag ....................................231
iterating over .....................................201, 202
light types .................................................257
models ......................................................254
platform-specific........................................260
static ......................................... 254, 262, 269
changing ...............................................263
creating .................................................262
world
I-275
Index
adding to ...............................................259
geometry normals flag ...............................231
world dynamic lighting flag........................209
vertex, calculating .....................................246
world normals flag.....................................209
vertex, smoothing......................................246
world prelit flag .........................................209
O
line .................................................................57
link errors .......................................................16
M
object space .................................... 46, 152, 228
objects
destroying ...................................................34
material ........................................................230
member functions .......................................24
geometry material modulation flag.............231
methods ......................................................24
iterating over .....................................201, 242
opaque ........................................................25
world modulate material flag .....................210
passing instances to functions ....................25
matrix ............................................................ 49
property access methods .............................25
post-concatenate .........................................54
reference counters.......................................34
pre-concatenate...........................................54
RenderWare ................................................24
replace ........................................................54
RpAtomic ..................................................221
transformation ............................................49
RpClump...................................................222
combining ...................................52, 53, 54
RpGeometry ...................................... 221, 259
transforming points .................................50
RpIntersection...........................................242
transforming vectors................................50
RpLight ............................................. 256, 260
Maya.......................................................18, 226
RpMaterial ................................................256
memory
RpMorphTarget .........................................232
freelists .......................................................71
RpTriangle ................................................228
management ...............................................70
RpWorld....................................................199
OS-level...................................................70
RpWorldSector ..........................................200
plugins........................................................81
RwBBox ....................................................200
resource arena ............................................73
RwDebug ..................................................188
memory management ......................................77
RwEngine....................................................63
mesh.....................................................235, 238
RwError ....................................................186
iterating over .....................................202, 242
RwFrame...................................................256
tri-strip method.........................................239
RwIm2d ....................................................142
metrics..........................................................249
RwIm3d ....................................................142
Microsoft Visual C ......................... See compilers
RwImage ...................................114, 115, 117
mipmaps...................................................... 132
RwRaster .......................................... 114, 115
automatic generation.................................125
RwResources...............................................74
example.....................................................133
RwSurfaceProperty....................................231
filtering .....................................................132
RwTexDictionary ....................... 114, 115, 136
generation .................................................135
RwTexture.................................114, 115, 130
loading ......................................................135
RwVideoMode..............................................66
manual generation ....................................125
transparent .................................................25
mip levels ..................................................132
optimization ..................................................246
number of levels ........................................126
P
writing a mip level generator......................136
models
creating .......................................................19
exporting .....................................................19
morph target .................................................232
palettes .........................................................117
parallax scrolling.............................................97
PI data .................................................. 212, 249
platform
N
Apple Macintosh..........................................13
native data ....................................................212
Microsoft Windows ......................................13
normals ........................................................200
Microsoft Xbox ............................................13
I-276
Direct3D 8 ..................................................13
22 April 2003
Index
NINTENDO GAMECUBE ............................. 13
OpenGL...................................................... 13
Sony PlayStation 2 ..................................... 13
platform independent
texture dictionaries................................... 138
plugins........................................................... 21
attaching .........................................68, 81, 83
memory .................................................. 81
creating ...................................................... 83
defining ...................................................... 83
dependencies.............................................. 82
example...................................................... 83
exposed ...................................................... 83
initialization ............................................... 83
registering .................................................. 85
RpADC ....................................................... 21
RpAnisot .................................................... 21
RpCollision ..........................................21, 202
RpDMorph.................................................. 21
RpHAnim.................................................... 21
RpLODAtomic............................................. 21
RpLtMap .................................................... 21
RpMaterialEffects ....................................... 21
RpMipmapKL.............................................. 21
RpMorph .................................................... 21
RpPatch ..................................................... 21
RpPrtStd .................................................... 21
RpPTank .................................................... 21
RpPVS ........................................................ 21
RpRandom ................................................. 21
RpSkin ................................................21, 245
RpSpline..................................................... 21
RpUserData................................................ 21
RpWorld ......................................21, 198, 221
shut down .................................................. 83
supplied ..................................................... 21
using .......................................................... 81
porting ........................................................... 14
pos vector....................................................... 49
PowerPipe....................................................... 23
pre-instancing .......................................213, 249
atomics .................................................... 249
worlds ...................................................... 213
pre-lighting .................................................. 210
static geometry ......................................... 211
using RtWorldImport ................................ 211
projection
parallel ..........................................47, 97, 158
perspective ............................47, 97, 144, 158
shadows ..................................................... 97
PS data ........................................................ 212
RenderWare Graphics 3.5
R
raster ................................................... 115, 124
camera ................................See camera raster
clearing .....................................................129
context stack.....................................107, 127
conversion
from image ............................................123
from images...........................................125
to image ................................................123
creating .....................................................124
determining valid formats ..........................125
format .......................................................127
loading ......................................................129
lock modes ................................................129
locking ......................................................129
locking palettized.......................................129
mipmaps ...................................................125
number of Mipmap levels...........................126
platform dependence .................................124
rendering ..................................................128
sub-rasters............................. See sub-rasters
unlocking ..................................................129
unlocking palettized ..................................129
reciprocal camera Z.......................................146
rectangle .........................................................58
recursion.................................... See infinite loop
registering
extensions ...................................................86
plugins ........................................................85
render callback .....................................243, 247
render state.......................................... 142, 160
exhaustive list ...........................................160
getting.......................................................160
rwRENDERSTATEBORDERCOLOR............162
rwRENDERSTATEDESTBLEND .........162, 163
rwRENDERSTATEFOGCOLOR...................162
rwRENDERSTATEFOGDENSITY ................163
rwRENDERSTATEFOGENABLE .................162
rwRENDERSTATEFOGTYPE ......................162
rwRENDERSTATESHADEMODE................161
rwRENDERSTATESRCBLEND ...........162, 163
rwRENDERSTATETEXTUREADDRESS ......161
rwRENDERSTATETEXTUREADDRESSU....161
rwRENDERSTATETEXTUREADDRESSV ....161
rwRENDERSTATETEXTUREFILTER...........162
rwRENDERSTATETEXTUREPERSPECTIVE161
rwRENDERSTATETEXTURERASTER .........161
rwRENDERSTATEVERTEXALPHAENABLE 162
rwRENDERSTATEZTESTENABLE ..............161
rwRENDERSTATEZWRITEENABLE............161
setting .......................................................160
I-277
Index
render states .................................................155
SDK
fog.............................................................101
examples........................... See examples, SDK
using.........................................................102
serialization ..................................................166
rendering ..................................................... 107
atomics ............................................. 171, 177
a step by step guide.....................................26
binary streams ..........................................169
atomics directly .........................................247
chunk ID...............................................169
begin an update ................................107, 247
BSP...........................................................169
clumps directly..........................................247
chunk headers .................................. 169, 179
cycle, the...................................................107
chunk IDs .................................................183
double buffering ........................................127
chunk size.................................................172
end an update ...................................107, 247
chunk type................................................170
immediate mode ........................................107
clumps...................................... 171, 177, 178
intercepting for atomics .............................243
DFF...........................................................169
rasters...........................See rasters, rendering
endian-ness ...................................... 175, 184
static geometry ..........................................212
big-endian .............................................173
to multiple viewports ...............See sub-rasters
little-endian...........................................173
worlds .......................................................247
file functions .............................................167
RenderWare
file I/O function ........................ 166, 167, 183
components........................................... 20–25
fclose.....................................................167
RenderWare AI ................................................12
feof ........................................................167
RenderWare Audio ..........................................12
fexist .....................................................167
RenderWare Graphics .....................................12
fflush ....................................................167
RenderWare Physics........................................12
fgets ......................................................167
RenderWare Platform ......................................12
fopen.....................................................167
resource arena .................. 73, 77, 213, 248, 249
fputs .....................................................167
right vector................................................45, 49
fread .....................................................167
RtTOC.................................See table of contents
fseek .....................................................167
RtWorldImport, using....................................204
ftell........................................................167
RwBBox ......................................................... 56
fwrite.....................................................167
RwCamera ......................................................95
file interface ..............................................167
RwEngineClose ...................................68, 69, 76
frames............................................... 171, 177
RwEngineInit ................................ 63, 64, 69, 76
geometry ...................................................171
RwEngineOpen.............................. 63, 65, 69, 76
reading worlds...........................................217
RwEngineStart ..........................................63, 76
rws.................................................... 180, 184
RwEngineStop.....................................68, 69, 76
streaming.................................. 172, 178, 183
RwEngineTerm..........................................68, 76
reading.................................. 173, 174, 175
RwLine............................................................57
registering .............................................184
RwRect............................................................58
types ............................................. 182, 183
RwRGBA .........................................................60
writing................................... 173, 174, 176
rws (RenderWare stream file format) ..............180
strview viewer............................................171
RwSphere........................................................59
RwVideoMode..................................................66
S
saving memory ......................................213, 249
scaleable fonts ..............................................159
scene creation .................................................26
scene space................................ See world space
scenes........... See static geometry or world sector
screen dump .................................................129
screen space ............................. See device space
I-278
writing worlds ...........................................216
shut down
plugins........................................................83
RenderWare Graphics .................................68
skeleton ..........................................................27
skinning........................................................245
SN Systems Visual Studio Integration .............16
sorting
by material................................................243
customizing ...........................................243
sorting alpha primitives.................................164
source code
22 April 2003
Index
skeleton...................................................... 27
platform independent ................................138
source code license......................................... 14
streaming ..................................................137
sphere ............................................................ 59
TOC ....................................See table of contents
split screen................................. See sub-rasters
toolkits........................................................... 22
static geometry ............................................. 198
Rt2d ....................................................22, 143
platform independent representation .212, 213
Rt2D .........................................................159
pre-lighting............................................... 211
Rt2dAnim....................................................22
rendering.................................................. 212
RtAnim........................................................22
sectors .................................. See world sector
RtBary.........................................................22
tools ......................................................... 203
RtBezPat .....................................................22
viewing ..................................................... 203
RtBMP.................................................22, 118
static lighting ........................................ See light
RtCharset....................................................22
static models .........................See static geometry
RtCmpKey ...................................................22
streaming .................................. See serialization
RtGCond .....................................................22
string data type .............................................. 37
RtIntersection..............................................22
strview viewer..........................................17, 171
RtLtMap ......................................................22
sub-rasters............................................109, 127
RtMipK........................................................22
subsystem
RtPick .........................................................22
enumeration............................................... 65
RtPITexD ...................................................138
initialization ............................................... 65
RtPNG .................................................22, 118
surface properties..................................231, 238
RtQuat ........................................................22
T
table of contents........................................... 180
creating .................................................... 180
streaming ................................................. 180
texture ......................................... 116, 130, 229
addressing example ...........................132, 134
addressing modes............................. 130, 133
addressing U axis independently .............. 134
addressing V axis independently............... 134
bordering.................................................. 134
clamping .................................................. 134
filtering..............................................130, 132
geometry textured flag .............................. 231
geometry, storage of co-ordinates in.......... 237
immediate mode ....................................... 146
loading ..............................................134, 139
mipmap.................................................... 135
mirroring ...........................................132, 134
saving....................................................... 139
streaming ................................................. 139
stretching ................................................. 131
tiling......................................................... 131
world texturing flag................................... 209
wrapping .................................................. 134
RtRAS .................................................22, 118
RtRay ..........................................................22
RtSkinSplit..................................................22
RtSlerp........................................................22
RtSplinePVS ................................................22
RtTIFF.................................................22, 118
RtTile ..........................................................22
RtTOC .................................................22, 180
RtVCAT .......................................................22
RtWing ........................................................22
RtWorld...............................................22, 246
RtWorldImport ........................... 22, 199, 204
supplied ......................................................22
tools
artists'.........................................................19
skeleton, the................................................24
topology ................................................232, 239
triangles........................................................228
winding order ............................................233
trilinear filtering ............................................132
tri-strip
method......................................................239
world tri-strip flag......................................210
U
texture co-ordinates ..................................... 130
Unicode character strings................................37
texture dictionary ................................. 136, 137
up vector...................................................45, 49
adding textures to .................................... 138
UV co-ordinates ............................................130
current ..................................................... 137
immediate mode ........................................146
finding textures ........................................ 138
RenderWare Graphics 3.5
I-279
Index
V
vectors ............................................................41
2D operations..............................................41
3D operations..............................................42
at See at vector
pos............................................See pos vector
right ........................................See right vector
three dimensional........................................42
two dimensional ..........................................41
up ..............................................See up vector
vertical blank interrupt (VBI) .........................128
vertices .........................................................228
video mode
changing .....................................................69
enumeration................................................66
flags ............................................................66
initialization ................................................65
setting .........................................................66
viewers
clmpview .............................................17, 226
strview ................................................17, 171
visualizer.....................................................17
Visualizer ..................................................226
wrldview ......................................................17
wrldview ....................................................226
Visual Studio Integration.................................16
visualizer ........................................................17
visualizer viewer ............................................226
vsync pulse .............. See vertical blank interrupt
W
winding order................................................233
world.............................................................199
adding
I-280
atomics .................................................199
cameras ................................................199
lights.....................................................199
adding clumps ..........................................240
creating.....................................................204
creating empty ..........................................209
destroying .................................................218
dynamic lighting........................................209
example ....................................................204
flags ..........................................................209
importing data ..........................................204
loading ......................................................217
modulating material color..........................210
normals.....................................................209
prelit .........................................................209
properties..................................................209
rendering .......................................... 212, 247
saving .......................................................216
serialization...............................................215
texturing ...................................................209
tri-stripping...............................................210
world sector ..................................................200
culling from frustum ...................... See culling
iterating over ............................. 111, 201, 241
modeling ...................................................203
world space............................................. 47, 152
placing in using frames ...............................47
wrldview viewer .............................................226
wrldview viewer ...............................................17
Z
z sorting........................................................164
z-buffer ................................................. 104, 158
immediate mode........................................144
resolution............................................ 96, 104
22 April 2003
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : Yes Producer : Acrobat Distiller 4.05 for Windows Creator : Microsoft Word 9.0 Modify Date : 2003:04:22 17:23:50+01:00 Author : Criterion Software Ltd. Subject : RenderWare Documentation Title : User Guide Volume I Create Date : 2003:04:22 17:23:14 Page Count : 280 Page Mode : UseOutlinesEXIF Metadata provided by EXIF.tools