Copyright: Copyright Criterion Software Ltd 1994.


Help Contents
Contents

Using the Library

Data Types

Function Reference

The Scripting Language

MS Windows 3.1 Specific Information

Error Codes

The Texture File Formats

Library Defaults


Using the Library

This section presents an overview of the main concepts of RenderWare. The following topics are discussed

Overview

Coordinate Systems

Matrices

The Virtual Camera Model

Hierarchical Modelling

The Structure of a RenderWare Program

Error Reporting

Debugging


Data Types

Public Types

Numeric Types

Structure Types

Enumerated Types

Bitfield Types

Opaque Types


The Scripting Language

Script Keywords

Miscellaneous Notes

"Object Builder" API Functions


MS Windows 3.1 Specific Information

Requirements

Environment Variables

RenderWare Library Configuration

Include Files

Device-Specific API Parameters


Error Codes

Error Descriptions

Error Identifiers and Codes


Library Defaults

Cameras

Clumps

Debugging

Device Information

Errors

Library Global Defaults

Lights

Materials

Matrices

Polygons

Rasters

Scenes

Splines

System Information

Textures

Texture Dictionaries

UserDraw

Vertices


Overview

A Clump is a collection of Polygons and Vertices. Clump objects allow applications to handle large numbers of related polygons and vertices as a single, atomic entity. This greatly simplifies application construction.

Each polygon has an associated Material object, which defines the appearance of the polygon. Material objects encapsulate the following surface properties: geometry sampling type, light sampling type, RGB color; ambient, diffuse and specular coefficients of reflection, opacity, texture and texture modes.

A Light source illuminates objects in a scene. Three types of light source are supported:

•	A directional light source (or "distant" light source) emits light in a specified direction and is assumed to be an infinite distance from a scene. The sun is an example of a directional light source.

•	A point light source emits light of equal intensity in all directions from a specified position. The intensity of this light decays with distance. Hence, distant objects receive less illumination. A light bulb is an example of a point light source.

•	A conical light source emits a cone of light centred about a specified axial direction from a specified position. A spot light is an example of a conical light source.

A Camera captures an image of the objects in a 3D scene projected onto an image plane (or view plane). The projection may be either perspective or parallel. A rectangular region of this plane (called the view window) is stored as a 2D image in the camera's image buffer. The rectangular region of pixels on the output device onto which a camera's view window is mapped is the camera's viewport.

A Scene is a collection of clumps and lights. A scene may be viewed through one or more cameras. At any instant, however, only one camera is active (the current camera) and the results of rendering are stored in the image buffer of this camera.


Coordinate Systems

RenderWare recognizes the following coordinate systems:

•	Object Space

Each clump has a local coordinate system (or Object Space). This is the coordinate system in which geometry being added to a clump is specified. For example:

RwAddVertexToClump(Clump, 1.0, 1.0, 1.0);

adds a new vertex to Clump at (1.0, 1.0, 1.0) in the clump's object space.

When constructing geometry using a script file or RenderWare's "Object Builder" API functions, the coordinates specified are transformed by the current transform matrix (CTM) before being added to the clump.

•	World Space

The coordinate system of a scene is known as the world coordinate system (or World Space). This is the coordinate system that is used for specifying the positions of lights and cameras.

RenderWare uses a right-handed world coordinate system. This has the same orientation as that given by taking the thumb, first and second fingers of your right hand as the X, Y and Z axes respectively. The positive X axis points to the right, the positive Y axis points up, whilst the positive Z axis points forwards (out of the screen).

•	Camera Space

Each camera has a viewing coordinate system (or Camera Space). Camera space has its origin at the camera's position. The positive Z axis of camera space is given by the view direction (or "Look At" vector). Unlike world space, camera space is left-handed. The units of camera space are the same as those of world space.

Camera space is primarily used in the API function RwVCMoveCamera() which moves the camera a certain number of units left, right, up, down, forwards or backwards relative to the current camera position.

•	Device Space

The device coordinate system (or Device Space) is a two dimensional coordinate system. Its units are those of the display (screen or window) to which the camera's image buffer is copied when RwShowCameraImage() is called. Device space is primarily used for specifying the position and extent of camera viewports. Device space is closely related to viewport space as described below.

•	Viewport Space

The coordinate system of a camera's viewport is the viewport coordinate system (or Viewport Space). Viewport space is used when picking, when damaging or undamaging the camera's viewport, when specifying a portion of the viewport into which a backdrop should be copied and when rendering user-draws. The units of viewport space are the same as those of device space. The terms device space units and viewport space units will be used interchangably throughout this document.

To convert a point in device space to the viewport space of a camera, simply subtract the X and Y coordinates of the camera's viewport from the X and Y coordinates of the point. This conversion is often useful when attempting to pick an object under the mouse pointer. The mouse position will normally be returned to the application in device (screen or window) coordinates. However, viewport coordinates are needed for the pick operation and so the above conversion should be performed. This conversion is not necessary if the viewport's origin is the same as the origin of device space (as is often the case).


Using the Library - Matrices
Matrices

RenderWare uses 4 x 4 homogeneous matrices to represent 3D transformations. Rotation and scaling are encoded in the top-left 3 x 3 sub-matrix, and translation in the final row:

Such matrices are available to the application programmer through the opaque data type RwMatrix4d.

In addition to various high-level matrix operations (such as multiplication) the elements of a matrix can be set or retrieved either individually or as a whole. For example, the API function RwGetMatrixElements() copies the elements of a matrix into a 4 x 4 array of real numbers:

RwMatrix4d *matrix;
RwReal elements[4][4];

matrix = RwCreateMatrix();
RwGetMatrixElements(matrix, elements);

The first index of the elements array is the row number and the second is the column number. Thus, the X, Y and Z values of the translation component of matrix are elements[3][0], elements[3][1] and elements[3][2] respectively.


The Virtual Camera Model

The purpose of a camera is to project the objects in a 3D scene onto an image plane (or view plane), a rectangular region of which, called the view plane window (or view window), is output as a 2D image. The rectangular portion of the display surface onto which a camera's view window is mapped is called the viewport. RenderWare supports both perspective and parallel projections.

A camera can be positioned anywhere in world coordinate space and can be pointed in any direction.   RenderWare's viewing model is illustrated below:

Note that:

•	The camera position is the origin of camera space. It is also the center of projection, except when the view offset has been specified. When a view offset is specified, the center of projection is moved parallel to the view plane, from the camera position.

•	The Z axis of camera space (N) is defined by the camera's "Look At" vector. This is normal to the view plane.

•	The view plane is defined to be one unit away from the camera position, along the N axis.

•	The viewing direction is defined by a vector from the center of projection to the center of the view plane.

•	The camera or viewing coordinate system (VCS) is left-handed.

•	The view up vector (V) specifies the "up" direction, i.e., where the top of the screen is. Together with N, it establishes the orientation of the camera and of the view plane window within the view plane. RenderWare refers to this vector as the "Look Up" vector.

•	The U vector gives the direction of the positive X axis in the camera coordinate system. There is no need to explicitly set this parameter since RenderWare can compute U as the cross-product of V and N. RenderWare calls this the "Look Right" vector.

•	The view window determines image content, i.e., the rectangular region of the view plane that appears in the image produced by the camera. It is centered about (0.0, 0.0, 1.0) in camera space.

•	Changing the view window is analogous to changing the setting of a zoom lens in a real camera and can simulate the effects of wide angle or telephoto lenses (by specifying larger and smaller extents for the view window respectively). To get objects to appear in their "normal" size, the view window extent should be set to one. Increasing the size of the view window widens the field of view, which means that a larger proportion of the scene will appear in the image and therefore the objects in the scene appear smaller.

•	The user can also change the position of the front (or near) clipping plane, which is co-planar with the view plane, by specifying it as a distance from the camera position. This value should be a positive real number greater than 0.025.


Hierarchical Modelling

Hierarchical modelling 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.

Related Topics:

Hierarchical Modelling in RenderWare

Constructing Hierarchical Models in Scripts

Traversing Clump Hierarchies

Finding a Particular Clump In a Hierarchy


Hierarchical Modelling in RenderWare

RenderWare's hierarchical modelling support provides the ability to explicitly model articulation or "joints" connecting objects.

A clump may have a parent and zero or more children.

Each clump has its own independent, local coordinate system. A clump has three associated matrices: a modelling transformation matrix, a joint (or articulation) transformation matrix, and a local transformation matrix (LTM).

The modelling and joint transformations of a child clump together specify the mapping from its the local coordinate system to that of the parent clump. The joint transformation specifies the rotation of the child clump about its local origin; clumps are therefore always "hinged" about their local origin (the joint is always at the origin of the child clump). The modelling transformation specifies where the origin of the child clump is with respect to the origin of the parent clump.

Typically, the geometry being added to a clump is positioned with respect to that clump's origin by applying translation, rotation or scaling to the current transformation matrix.

The local transformation matrix (LTM) of a clump maps from the local coordinate system of the clump to the world coordinate system of the scene to which it belongs. It may be calculated by initialization to the identity matrix followed by an ascent from that clump to the root of its hierarchy with post transformation first by the joint and then the modelling transformation at each level. Note that a clump's local transformation is computed by RenderWare and can be retrieved by RwGetClumpLTM(). It cannot (and need not) be set directly by the application programmer.


Constructing Hierarchical Models in Scripts

This section gives a simple example of building a hierarchical model in a RenderWare script (.rwx) file. The example is equally applicable to RenderWare's "Object Builder" API functions.

The following is an example of a script defining a simple hierarchical model forming part of a robot's body:

ModelBegin
ClumpBegin
Color 1.0 0.0 0.0
Surface 0.5 0.5 0.5

Block 0.6 0.8 0.3

Translate 0.3 0.4 0.15
ClumpBegin
Color 1.0 1.0 1.0

Translate 0.1 -0.4 0.0
Block 0.2 0.8 0.2
ClumpEnd
ClumpEnd
ModelEnd

The top-level ClumpBegin … ClumpEnd block defines a clump representing the central section of a robot's body. One arm of the robot is then modelled by a child of this clump.

The Translate keyword applies a translation to the current transformation matrix (CTM).

When the definition of the child clump is begun (with ClumpBegin), the modelling matrix for the child clump is set to the CTM. The first Translate keyword positions the child clump in relation to its parent; the child's local origin is displaced by [0.3 0.4 0.15] from that of the parent.

Before adding the second block corresponding to the child clump, a translation is applied to the CTM. This specifies the position of the block relative to the origin of the clump.

The rotation of the arm about the "shoulder joint" requires only one additional line in the script: RotateJointTM. This keyword should be inserted immediately before the ClumpBegin … ClumpEnd defining the child clump. The command specifies the direction of the axis of rotation about the joint (in the child's local space) and the angle of rotation in degrees:

RotateJointTM 1.0 0.0 0.0 30

The above rotates the arm about the X axis of the child's local space by 30 degrees.


Traversing Clump Hierarchies

There are two ways of traversing clump hierarchies:

1	Starting from any clump in a clump hierarchy, every other clump in that hierarchy may be visited with clump access functions such as RwGetClumpParent(), RwGetNextClump() and RwGetFirstChildClump().

2	All clumps in a hierarchy may be iterated over by the API function RwForAllClumpsInHierarchy() and its variants. This family of functions is convenient in situations when the same operation is to be applied to each clump in a hierarchy.


Finding a Particular Clump In a Hierarchy

There are two main techniques for finding a particular clump:

1	RenderWare allows an integer tag to be attached to each clump. A clump's tag can be set by the API function RwSetClumpTag() or the script keyword Tag and retrieved by the API function RwGetClumpTag(). Tags are convenient for marking parts of a hierarchical model for identification and manipulation by an application program. A tagged clump may be found with RwFindTaggedClump().

2	The second, more general technique involves RwFindClump() or one of its variants. These functions apply a boolean (predicate) call-back function to each clump in a hierarchy in turn until the call-back function returns non-zero. Iteration is then terminated. The clump passed as the argument to the call-back function is returned.


The Structure of a RenderWare Program

The include file rwlib.h contains the prototypes for all RenderWare API functions. Any application program exploiting RenderWare should include this include file.

There are three other important include files: rwtypes.h, rwmacros.h and rwerrors.h. rwtypes.h contains the declarations of RenderWare's data types; rwmacros.h contains macro functions for fixed-point arithmetic and rwerrors.h contains the RenderWare error codes. Each of these files is included by rwlib.h, there is no need to explicitly include them.

The first and last RenderWare API functions called by an application program must be RwOpen() (or its variant RwOpenExt()) and RwClose() respectively.

A typical RenderWare application:

•	initializes the library

•	creates and initializes a camera

•	creates a scene

•	creates and initializes one or more lights and adds them to a scene

•	creates or reads one or more clumps and add them to a scene.

•	repeatedly renders a scene

•	closes the library

Each of these tasks is discussed in more detail below. Code fragments are given to illustrate each operation. These code fragments are sections of a floating-point, RenderWare application targeted at the Microsoft Windows 3.1 operating system.

The code fragments are from a program which displays a clump read from a script file.

For the sake of clarity the following code fragments omit the various macros necessary for compatibility with the fixed-point RenderWare libraries. Furthermore, variable declarations and some error checking have been omitted.

Related Topics:

Initializing the Library

Creating and Initializing a Camera

Creating a Scene

Creating a Light Source and adding it to a Scene

Creating a Clump and adding it to a Scene

Rendering a Scene

Closing the Library


Initializing the Library

RwOpen() initializes the library for a particular output device.

if (RwOpen("MSWindows", NULL))
{
/*
 * Since the return value was non-zero,
 * the application can continue...
 */


Creating and Initializing a Camera

A new camera can be created with RwCreateCamera(). This requires the maximum width and height of the camera's viewport and a device-specific parameter as its arguments:

cam = RwCreateCamera(320, 200, NULL);
if (cam)
{
/*
 * As NULL was not returned the call
 * was successful and the application can
 * continue...
 */

The above code fragment creates a camera cam with a maximum viewport size of 320 by 200 pixels.

By default, the camera is positioned at the origin of world space, looking down the world space Z axis in the direction of decreasing Z. The camera has a view window of 1.0 unit by 1.0 unit and has a viewport background color of black (0.0, 0.0, 0.0). The default projection model is perspective.

To move the camera back 10.0 units down the Z axis from its initial position:

RwVCMoveCamera(cam, 0.0, 0.0, -10.0);

Note that, by default, the camera's viewport has a width and height of zero. The application program must explicitly set the viewport of each new camera to a non-zero width and height. This viewport should be set with the API function RwSetCameraViewport() as soon as the desired size is established.

The following code fragment sets the camera's viewport in response to a WM_SIZE message from MS Windows:

case WM_SIZE:
width = LOWORD(lParam);
height = HIWORD(lParam);
RwSetCameraViewport(cam, 0, 0, width, height);


Creating a Scene

RwCreateScene() creates a scene (the default scene) which holds all clumps and lights when they are first created. The default scene can be viewed and rendered with a camera in the same way as any other scene. However, it is recommended that an application creates a specific scene for rendering and only uses the default scene to hold currently unused clumps and lights.

if (scene = RwCreateScene())
{
/*
 * Since NULL was not returned,
 * the call was successful and the
 * application can continue...
 */


Creating a Light Source and adding it to a Scene

A light source is created by calling RwCreateLight().

if (light = RwCreateLight(rwPOINT,
0.0, 10.0, 0.0, 1.0))
{
/*
 * Since NULL was not returned,
 * the call was successful and the
 * application can continue...
 */

The above code fragment creates a point light source of maximum brightness (1.0) positioned at (0.0, 10.0, 0.0) in world space.

To add the light to the scene:

RwAddLightToScene(scene, light);


Creating a Clump and adding it to a Scene

A clump is read from a RenderWare script file as follows:

ball = RwReadShape("ball.rwx");
if (ball)
{
/*
 * Since NULL was not returned,
 * the call was successful and the
 * application can continue...
 */

If the application wishes to replace the surface properties of the clump defined in the script file it can do so via the RenderWare API functions which deal with polygons and materials:

RwForAllPolygonsInClumpInt(ball,
RwSetPolygonGeometrySampling, rwSOLID);

RwForAllPolygonsInClumpInt(ball,
RwSetPolygonLightSampling, rwVERTEX);

RwForAllPolygonsInClumpReal(ball,
RwSetPolygonAmbient, 0.7);

color.r = 1.0;
color.g = 0.0;
color.b = 1.0;
RwForAllPolygonsInClumpPointer(ball,
RwSetPolygonColorStruct, &color);

The above code fragment sets the geometry sampling type, light sampling type, ambient reflection coefficient, and color of all the clump's polygons.

To add the clump to the scene:

RwAddClumpToScene(scene, box);


Rendering a Scene

At some point, the application must render the scene and display the results of that rendering. Under MS Windows the application may do this in response to a WM_PAINT message:

case WM_PAINT:
hdc = BeginPaint(window, &ps);

RwBeginCameraUpdate(cam);
RwClearCameraViewport(cam);
RwRenderScene(scene);
RwEndCameraUpdate(cam);
RwShowCameraImage(cam, MAKELONG(window, hdc));

EndPaint(window, &ps);


Closing the Library

Finally, when all rendering is complete, the RenderWare library is closed:

RwClose();


Error Reporting

RenderWare reports errors by setting a global error status. The majority of API functions have a distinguished return value which indicates that the global error status has been set by that function.

The global error status may is interrogated by RwGetError(). This returns E_RW_NOERROR if no error has occurred. Otherwise, an error code is returned representing the first error encountered since the global error status was last cleared. The global error code is cleared to E_RW_NOERROR by calling RwGetError().

The global error status is set when an error occurs and the global error status is E_RW_NOERROR. The actual error code set indicates the type of the error. Once set, the error status is not set by any subsequent error until RwGetError() is called. This ensures that the first error encountered is not over written by subsequent errors.

As previously described, the majority of API functions have a distinguished return value which indicates that the global error status has been set by that function. However, there are functions where this is not possible. For example, the function RwGetClumpParent() can return NULL as a legal value (when the clump is the root of a hierarchy). The documentation for any such function directs the application to call RwGetError() to determine whether an error occurred.

It is strongly recommend that application programs test the return values of library functions to check for errors. This is particularly important in the case of RenderWare's constructor functions such as RwCreateMatrix() or RwCreateCamera().

The range of error codes that may be returned by RwGetError() is given in Error Codes.

Finally, note that application programs may set RenderWare's global error status using RwSetUserError(). This signals that an error was encountered in an application supplied call back function. Its primary function is to prematurely terminate the iteration performed by one of RenderWare's RwForAll...() functions.


Using the Library - Debugging
Debugging

Two forms of the RenderWare library are available. The production version, with which all final, production quality systems should be linked and the debugging version which aids in the development of RenderWare applications.

Although slower than the production version, the debugging version performs more error checking and issues messages to alert the application programmer to potential problems. A set of API functions are provided to control the type of tracing and debugging information generated. In the production version of the library, these functions are simply null operations. Applications can, therefore, switch between debugging and production libraries by simply re-linking.

Debugging messages are associated with three levels of severity:

•	Informational	A control flow annotation.

•	Warning	A recoverable error was encountered.

•	Error	A fatal error was encountered.

The above are listed in ascending order of severity. The items in the list correspond to values (rwINFORM, rwWARNING, and rwERROR) of the enumerated type RwDebugSeverity. The messages dispatched to the debugging stream may be filtered according to their severity by setting the minimum severity level. For example, setting the severity level to rwWARNING would filter out informational messages whilst retaining warning and error messages.

There are three categories of debugging messages:

•	Assertion failure messages.

•	Script trace messages.

•	Miscellaneous messages.

All messages share the following format:

RW <severity level> [xx:yyyy] <text of the message>

The <xx:yyyy> is a code comprising a two- and four-digit number. This code is of no significance to the application programmer, but is informative to RenderWare's technical support staff when investigating problems.

Related Topics:

Assertion Failure Messages

Scripting Trace Messages

Miscellaneous Messages


Assertion Failure Messages

These messages report the failure of assertions made within the library functions. For example, the RwCreateCamera() function asserts that its maximum width and height arguments should have positive values. If either the width or height is negative the assertion fails and a message is issued.

An assertion failure message takes one of the following two forms:

RW INFORM  [xx:yyyy] ASSERT FAILED

RW WARNING [xx:yyyy] ASSERT FAILED

Assertion failure messages can have either informational or warning level severity.

Assertion failure messages are informative to RenderWare's technical support staff but contain no significant information for the application programmer.

Note that the execution of an API function continues after the detection of an assertion failure. The debugging version of the library behaves in the same way as the standard version.


Scripting Trace Messages

These messages trace the parsing of a script file. This is useful in finding problems in script files that fail to load.

The format of a scripting trace message is:

RW INFORM [xx:yyyy] SCRIPT Line <line number>: Parsing <scripting keyword>

For example:

RW INFORM [12:3324] SCRIPT Line:25 Parsing ClumpEnd

Note that scripting trace messages always have severity level rwINFORM.


Miscellaneous Messages

The remainder of the debugging and tracing messages (including all API level errors) fall into this category. Two examples are:

RW ERROR  [15:8463] E_RW_INV_LIGHT: Invalid light type passed to library function

RW INFORM [92:3425] RwCurrentMatrix is obsolete. Please use RwScratchMatrix.

Miscellaneous messages can be of any severity level. API level error messages are always at severity level rwERROR.

The above message classes can be enabled or disabled individually or collectively. By default, assertion failure and miscellaneous messages are enabled whilst script trace messages are disabled.

Some example scenarios for controlling debugging messages are given below:

Scenario 1: Report Everything

RwSetDebugSeverity(rwINFORM);
RwSetDebugOutputState(rwENABLE);

Scenario 2: Report Only API-level Errors

RwSetDebugSeverity(rwERROR);
RwSetDebugOutputState(rwENABLE);

Scenario 3: Report Only Script Tracing Information

RwSetDebugSeverity(rwINFORM);
RwSetDebugAssertionState(rwDISABLE);
RwSetDebugMessageState(rwDISABLE);
RwSetDebugTraceState(rwENABLE);

Scenario 4: Report All Warnings and Errors

RwSetDebugSeverity(rwWARNING);
RwSetDebugOutputState(rwENABLE);

The RenderWare library exports a small number of data types and associated functions which operate there on.

All RenderWare API functions and data types are prefixed with "Rw". For example:

RwRenderScene()

RwClump *

All RenderWare enumerated type values are prefixed with "rw". For example:

rwWIREFRAME

From the programmer's perspective, there are two major categories of data types within the RenderWare library: public types and opaque types.

Public types may be created and manipulated by the standard C language mechanisms. For example, a field in an object of the public structure type RwV3d can be set directly:

RwV3d point;

point.x = 1.0;

Unlike instances of the public types, opaque objects, such as matrices, cameras, clumps and lights, can only be created and accessed by RenderWare API functions which identify those objects by opaque object pointers. The implementation of opaque types is hidden from the application programmer in much the same manner as the C language standard library FILE structure. For example, a field in an object of the opaque type RwClump can only be set with the appropriate RenderWare API function:

RwClump *clump;

clump = RwCreateClump(10, 10);
RwSetClumpTag(clump, 23);


Public Types

This category consists of:

•	Numeric types (RwReal and RPARAM).

•	Structure types (such as RwV3d).

•	Enumerated types (such as RwCameraProjection).

•	Bitfield types (such as RwClumpHints).


Numeric Types

RwReal and RPARAM

RenderWare provides both fixed-point and floating-point libraries. Two data types, RwReal and RPARAM and a set of arithmetic and type conversion macros are provided to allow the development of "library numeric type independent" programs.

The RwReal type should be used to represent real values - those with fractional parts - within the "body" of code. Real values may also be passed by reference through a function call with type RwReal *. However, any real value passed by value through a function call should be of type RPARAM.

There are three possible scenerios in which an application program may exploit the RenderWare library.

•	If the application is only to be used with the fixed point version of the library, then:

(i)	The RenderWare arithmetic macros, e.g., RMul and RAdd, must be used instead of C's corresponding arithmetic operators.

(ii)	C's built-in types - int, long, float and double - should be converted to RenderWare's RwReal and RPARAM as appropriate in function calls with the conversion macros, e.g., CREAL and INT2REAL. Prototypes for RenderWare API functions use RwReal * and RPARAM rather than float * and double.

(iii)	RwReal and RPARAM are 32-bit fixed point numbers, with a signed "two's complement" representation. The top 16 bits hold the integer part of a real number whilst the bottom 16 bits hold the fractional part.

•	If the application program is to be portable across both versions of the library, then points (i)—(ii) above apply, but not (iii); in the floating point version of the library. RwReal and RPARAM correspond to float and double respectively.

•	If the floating point version of the library is to be used exclusively, then:

(iv)	RwReal and RPARAM are interpreted by the library as float and double respectively. Renderware API functions may be called with types of float * where the prototype specifies RwReal * and double where RPARAM is specified.

(v)	there is no need to use either the conversion macros or the arithmetic macros

However,   the conversion and arithmetic macros will perform correctly with the floating point version of the library and do not incur any run-time performance penalty. Application programmers are encouraged to apply the macros consistently to facilitate any future port between fixed- and floating-point libraries.

The RPARAM type supplements the RwReal type to allow floating point versions of the RenderWare library to be linked with application object code generated with either an ANSI or K&R compiler. The former class of compilers pass a float by value "as is", whilst the latter promote floats to doubles. In RenderWare, all real values are passed by value as RPARAM - a double in the floating point version, whatever the dialect of the native compiler.

•	Two distinct real types are needed to correspond to types float and its promoted counterpart double because of the implicit type casting performed by K&R C when handling arguments to function calls.

•	RwReal requires only half of the amount of storage required for RPARAM (in the case of the floating point version of the library).

To facilitate the use of these two real types, several conversion macros are provided:

•	CREAL(x) takes an integer or floating-point constant x as an argument and returns an RwReal

•	INT2REAL(x) takes an int or long variable x as an argument and returns an RwReal

•	FL2REAL(x) takes a float or double variable x as an argument and returns an RwReal

•	REAL2INT(x) takes an RwReal or RPARAM variable x as an argument and returns an int

•	REAL2FL(x) takes an RwReal or RPARAM variable x as an argument and returns a float

In addition, there are several arithmetic macros that take RwReal or RPARAM arguments and return an RwReal result:

•	RAdd(x, y) c.f. x + y

•	RSub(x, y) c.f. x - y

•	RMul(x, y) c.f. x * y

•	RDiv(x, y) c.f. x / y

•	RAbs(x)    c.f. fabs(x)

•	RSqrt(x)   c.f. sqrt(x)

In floating-point versions of the library, the arithmetic macros handle over- and under-flow exactly as their C counterparts. In fixed-point versions of the library, RAdd and RSub work "modulo 2^16" - so that overflow results in "wrapping"; RMul and RDiv return the value of greatest possible absolute value and correct sign on overflow; RMul returns zero on underflow whilst RDiv returns the numerator on division by zero.

Note that the arguments passed to the above type conversion and arithmetic macros may be evaluated multiple times. Therefore, applications should avoid passing arguments that have evaluation side-effects.

The following code fragment demonstrates the application of some of these macros. It is compatible with both fixed-and floating-point versions of the library:

#define PI 3.14159265358979323846

RPARAM
sinangle(RPARAM degrees)
{
RwReal radians;
RwReal sine;

/*
 * Convert to radians.
 */
radians =
RMul(degrees, RDiv(CREAL(PI),CREAL(180)));

/*
 * Find sin by call to double sin(double x).
 */
sine = FL2REAL(sin(REAL2FL(radians)));

return sine;
}

The smallest and largest positive real numbers that can be represented are available via the macros REAL_MIN and REAL_MAX respectively.


Structure Types

Structure types are normal C structures. Their fields can be set and retrieved directly. Structure types are always passed to RenderWare API functions by reference.

Related Topics:

RwV3d

RwUV

RwRect

RwRGBColor

Pick Related Structures

RwOpenArgument


RwV3d

The type RwV3d represents points and vectors. It is defined as follows:

typedef struct

{

RwReal x, y, z;	x, y and z coordinates of a 3D point or the x, y and z components of a 3D vector

} RwV3d;


RwUV

The type RwUV represents the texture coordinates of a vertex. It is defined as follows:

typedef struct

{

RwReal u, v;	u and v texture coordinates in the range CREAL(0.0) … CREAL(1.0)

} RwUV;


RwRect

The type RwRect represents a rectangular region. It is defined as follows:

typedef struct

{

int x, y, w, h;	x,y - offset; w,h - size

} RwRect;


RwRGBColor

The type RwRGBColor represents RGB color triples. It is defined as follows:

typedef struct

{

 RwReal r, g, b;	Intensities in the range CREAL(0.0) … CREAL(1.0)

} RwRGBColor;


Pick Related Structures

Applications often need to identify the object lying under a specified position in the camera's viewport. This can be accomplished with RenderWare's pick functions. These return a pointer to an RwPickRecord structure, which provides information about the object (if any) which was "picked".

A RwPickRecord structure is defined as follows:

typedef struct

{

RwPickObject type;	Type of object picked

union

{

RwPickClumpData clump;	Picked clump data

RwPickVertexData vertex;	Picked vertex data

}object

} RwPickRecord

The type field describes the type of object picked. Depending on the value of this field, either the clump or vertex pick data records should be examined.

RwPickVertexData and RwPickClumpData are respectively defined as follows:

typedef struct

{

int vindex;	Index of vertex closest to the pick position

int d2;	Distance squared (in viewport space units) from the pick position to closest vertex

} RwPickVertexData;

Fields vindex and d2 specify the index of the closest viewpoint space vertex to the pick position and the square of distance (in viewport space units) from that vertex to the actual pick position.

typedef struct

{

RwClump *clump;	Pointer to picked clump

RwPolygon3d *polygon;	Pointer to polygon picked

RwPickVertexData vertex;	Picked vertex data

RwV3d wcpoint;	World coordinate of pick position

}	RwPickClumpData;

This structure specifies the clump picked, the polygon picked, the vertex picked, and the pick position on this polygon in world space.


RwOpenArgument

The type RwOpenArgument identifies a library configuration option when opening the library with the RwOpenExt() API function. It is defined as follows:

typedef struct

{

RwOpenOption option;	Option identifier

void *value;	Parameter value

} RwOpenArgument;

The field option identifies the open option and value is a device specific parameter associated with that option. The available options are described in MS Windows 3.1 Specific Information.


Enumerated Types

Enumerated types are used when one of a small range of options must be specified. It should be noted that for all the enumerated types defined by RenderWare, the first value in the list is reserved to indicate errors.

Where the list of possible options is fixed in a device and platform independent way the C enum construct defines the enumerated type. However, certain RenderWare enumerated types have options which are device or platform specific. In those cases the C enum construct is not adopted. A new type name is introduced based on a C integral type and the values of the type are defined as macros.

Related Topics:

Camera Projection Type

State Type

Light Type

Light State Type

Light Sampling Type

Geometry Sampling Type

Spline Type

Spline Path Type

Search Mode Type

Texture Dither Mode Type

Combination Type

Pick Object Type

Debug Severity Type

Debug State Type

User-Draw Types

Device Information Type

Device Action Type

Library Open Options


Camera Projection Type

Cameras project according to either a perspective or parallel model. The projection type is as follows:

RwCameraProjection

•	rwNACAMERAPROJECTION    Error code

•	rwPERSPECTIVE    Perspective projection

•	rwPARALLEL    Parallel projection


State Type

Lights and clumps may be switched on or off. The state of a light or clump is as follows:

RwState

•	rwNASTATE    Error code

•	rwOFF    Object is turned off

•	rwON    Object is turned on


Light Type

Lights may be directional, point, or conical sources. The light type is as follows:

RwLightType

•	rwNALIGHTTYPE    Error code

•	rwDIRECTIONAL    Directional light source

•	rwPOINT    Point light source

•	rwCONICAL    Conical light source


Light State Type

Previous versions of RenderWare provided a type (RwLightState) to explicitly represent the state of a light. In RenderWare 1.3 a light's state is represented by the new generic state type, RwState. To maintain backwards compatibility RwLightState has been retained as a synonym for RwState. As RwLightState will be removed from the API in the next release of RenderWare, references to RwLightState should be replaced by RwState. RwLightState is as follows:

RwLightState

•	rwNALIGHTSTATE    Error code (synonym for rwNASTATE)

•	rwON    Light is on

•	rwOFF    Light is off


Light Sampling Type

The lighting of a polygon in clump can be calculated in either of two ways: a single lighting sample per polygon at the polygon's centre, or several lighting samples per polygon - one at each polygon vertex. The former is called flat shading (shading is constant over a polygon's entire surface). The latter is called smooth shading (shading may vary over the polygon to yield an apparently smooth surface). These options may be selected by setting the light sampling type of a polygon's material to rwFACET or rwVERTEX respectively.

The light sampling type is as follows:

RwLightSampling

•	rwNALIGHTSAMPLING    Error code

•	rwFACET    Flat shading

•	rwVERTEX    Smooth shading


Geometry Sampling Type

Geometry may be visualised in one of three ways: as a "cloud" of points representing polygon vertices, as a wireframe of polygon edges, or as a solid enclosed by filled polygons. The geometry sampling type is as follows:

RwGeometrySampling

•	rwNAGEOMETRYSAMPLING    Error code

•	rwPOINTCLOUD    Render vertices

•	rwWIREFRAME    Render edges

•	rwSOLID    Render polygons


Spline Type

A spline is described by a set of control points through which the spline passes. The spline can be open or closed. In the former case the curve starts at the first control point and ends at the last point. In the later case the last point is joined to the first point. The spline type is as follows:

RwSplineType

•	rwNASPLINETYPE    Error code

•	rwOPENLOOP    "Open" spline (end points not joined)

•	rwCLOSEDLOOP    "Closed" spline (end points joined)

RenderWare splines are interpolatory, non-rational, cubic B-splines. The rwOPENLOOP type is open in having disjoint start and end points whilst the rwCLOSEDLOOP type is closed in forming a complete circuit.


Spline Path Type

Once created, a spline can be sampled as a parametric curve. Points on the spline may be computed by specifying a parameter in the range [CREAL(0.0) … CREAL(1.0)]. The spline path type specifies the manner of interpolation. An rwSMOOTH path will have the control points uniformly distributed in parameter space, whilst a rwNICEENDS path will have zero differential at its ends. The spline path type is as follows:

RwSplinePath

•	rwNASPLINEPATHTYPE    Error code

•	rwSMOOTH    Uniformly distributed control points

•	rwNICEENDS    Zero differential at ends.


Search Mode Type

Several API functions operate on the texture dictionary stack. The behaviour of some of these, e.g., RwGetNamedTexture(), is determined by the current search mode. This can have either of two values: rwLOCAL, specifying a search limited to the top dictionary on the stack or rwGLOBAL, specifying a search through all dictionaries on the stack. The search mode type is as follows:

RwSearchMode

•	rwNASEARCHMODE    Error code

•	rwLOCAL    Search locally (top-most dictionary only)

•	rwGLOBAL    Search globally (all dictionaries)


Texture Dither Mode Type

The RwTextureDitherMode type controls whether the apparent color resolution of textures should be enhanced by dithering. It is important to note that textures are dithered when being read but not during rendering. These flags, therefore, only apply when a texture is first read from disk.

Dithering is only appropriate if the texture being read has not already been dithered. Previous versions of RenderWare attempted to avoid re-dithering by examining the size and depth of the texture being read. If the texture did not have to be resized and was already of the correct depth then it would not be dithered. Otherwise was dithering was performed.

RenderWare V 1.3 provides finer grain control over texture dithering. There are three texture dithering modes; rwDITHERON forces textures to be dithered when loaded, rwDITHEROFF prevents textures from being dithered and rwAUTODITHER provides backwards compatibility by deciding whether to dither according to the size and depth of the image read.

The texture dither mode is as follows:

RwTextureDitherMode

•	rwNATEXTUREDITHER    Error code

•	rwDITHERON    Always dither

•	rwDITHEROFF    Never dither

•	rwAUTODITHER    Dither if "necessary"


Combination Type

A "combination operator" can be applied to several objects, most commonly matrices. The operator determines the order in which one object is combined with another: pre-concatenation, post-concatenation, or replacement. The combination operator is as follows:

RwCombineOperation

•	rwNACOMBINEOPERATION    Error code

•	rwREPLACE    Assignment (replace existing value)

•	rwPRECONCAT    Pre-concatenation

•	rwPOSTCONCAT    Post-concatenation


Pick Object Type

RenderWare's pick functions return information about a pick operation in a pick record (supplied by reference as an argument). The pick type identifies this record as either a vertex pick data record or clump pick data record, and is as follows:

RwPickObject

•	rwNAPICKOBJECT    Error code

•	rwPICKCLUMP    Clump picked

•	rwPICKVERTEX    Vertex picked


Debug Severity Type

Debugging or trace messages from debugging libraries are output to a debugging stream. Each message can be issued at one of three levels of severity: informational, warning or error. The severity level is as follows:

RwDebugSeverity

•	rwNADEBUGMESSAGESEVERITY    Error code

•	rwINFORM    Control flow annotation

•	rwWARNING    Non-fatal exception

•	rwERROR    Fatal exception


Debug State Type

It is possible, using the type RwDebugState and its related API functions, to enable or disable each of three categories of debugging messages: assertion failure messages, script trace messages and miscellaneous messages. The debug message state is as follows:

RwDebugState

•	rwNADEBUGMESSAGESTATUS    Error code

•	rwDISABLE    Disable messages

•	rwENABLE    Enable messages


User-Draw Types

An application may supplement the image generated by RenderWare's 3D rendering with 2D graphics such as labels. Such composition is supported via call-back functions known as User-Draws. The enumerated type RwUserDrawType represents the alignment of the user-draw object relative to the associated RenderWare object. A user-draw object may be aligned with the origin of the owning clump, with a vertex of the owning clump, with the bounding box of the owning clump or with a camera's viewport. The user-draw type is defined as follows:

RwUserDrawType

•	rwNAUSERDRAWTYPE    Error code

•	rwCLUMPALIGN    Align to a clump's origin

•	rwVERTEXALIGN    Align to a clump's vertex

•	rwBBOXALIGN    Align to a clump's viewport bounding box

•	rwVPALIGN    Align to a camera's viewport


Device Information Type

The API function RwGetDeviceInfo() returns information about the current RenderWare device driver. Values of the type RwDeviceInfo identify what device information RwGetDeviceInfo() returns.

The device information type is as follows:

RwDeviceInfo

•	rwNADEVICEINFO    Error code

•	rwRENDERDEPTH    Current render depth

•	rwINDEXEDRENDERING    Is rendering with an index color scheme (color table) or direct color.

•	rwPALETTEBASED    Does the output device have a palette that RenderWare will attempt to modify.

The following options only apply to indexed color rendering:

•	rwINDEXEDCOLORMODEL    The organization of color table used in indexed rendering. The only currently supported value is rwRAMPBASED which indicates that the color table is organized as a series of ramps of different hues.

The following options only apply to indexed rendering using color ramps:

•	rwNUMCOLRAMPS    Number of color ramps used

•	rwCOLRAMPSIZE    Number of entries in each ramp

The following options only apply to palette based devices.

•	rwPALETTE    Return the RenderWare palette

•	rwPALETTESIZE    The number of entries in the entire palette

•	rwFIRSTPALETTEENTRY    Index of the first palette entry used by RenderWare

•	rwLASTPALETTEENTRY    Index of the last palette entry used by RenderWare

Specific device drivers may define additional information types. The platform specific documentation in MS Windows 3.1 Specific Information describes any additional options.


Device Action Type

The RenderWare API function RwDeviceControl() performs device specific actions. Values of the type RwDeviceAction identify what action RwDeviceControl() performs.

The device information type is as follows:

RwDeviceAction

•	rwNADEVICEACTION    Error code

The following options only apply to palette based devices using color ramps:

•	rwSETCOLRAMP    Set the base hue and saturation of a color ramp without affecting color matching

Specific device drivers may define additional device actions. See MS Windows 3.1 Specific Information for any additional actions.


Library Open Options

Library configuration options may be specified when opening the library with the RwOpenExt() API function. Values of the type RwOpenOption identify the various options.

The open options are as follows:

RwOpenOption

•	rwNAOPENOPTION    Error code

•	rwNOOPENOPTION    Null (ignored) option

•	rwGAMMACORRECT    Enable gamma correction

The following options only apply to palette based devices using color ramps:

•	rwSETCOLRAMPSIZE    Set the number of entries in each color ramp (in the range 10-23)

Specific device drivers may define additional open options. See MS Windows 3.1 Specific Information for any additional actions.


Bitfield Types

Like enumerated types, bitfields are used when selecting from a small number of alternatives. Unlike enumerated types, however, bitfields allow the selection of several independent options simultaneously.

The bitfield types can be manipulated with the C bitwise manipulation operators: | (or), & (and), ~ (not) and ^ (xor). Furthermore, 0 is a valid value for any bitfield and indicates that none of the available options have been selected.

Related Topics:

Raster Options

Clump Hints

Texture Modes

UserDraw Alignments


Raster Options

The bitfield type RwRasterOptions controls several aspects of raster loading, these being resizing, color matching, dithering and gamma correction. These options are specified when loading a raster with RwReadRaster() or when creating a raster from a platform specific bitmap with RwBitmapRaster().

To understand the effect of raster options the size and depth constraints of rasters should be appreciated. The depth of a raster is always equal to RenderWare's current rendering depth (8 or 16 bits in version 1.3). If the source of a raster (either a bitmap file or a platform specific bitmap object) is of a depth to the rendering depth the source pixels will be converted to that depth. Furthermore, if a raster is to be employed as the pixel source for a texture map it may have to be changed in size. Single frame texture maps have a fixed width and height of 128 pixels. Multi-frame texture maps have a fixed width of 128 pixels and a height of n * 128 pixels (where n is the number of frames).

The raster options are as follows:

•	rwFITRASTER will resize the raster to texture map dimensions. Specify this option if the raster is to be selected into a texture with RwCreateTexture() or RwSetTextureRaster().

•	rwGAMMARASTER will gamma correct the raster. Do not specify this option if the source of the raster has already been gamma corrected.

•	rwINDEXRASTER suppresses color matching. Normally rasters read by RenderWare are remapped to the RenderWare color palette. In certain circumstances this may not be desirable - for example, if the raster employs unused portions of the RenderWare colormap. Specifying rwINDEXRASTER will suppress color matching and the color indices in the raster will be used directly. If rwINDEXRASTER is specified no other raster options should be given. Furthermore, rwINDEXRASTER is only meaningful when rendering using an indexed color model (this is normally the case for 8 bit rendering). When rendering using a direct color devices (such as 16 bit rendering) this option will be ignored.

•	rwAUTODITHERRASTER dithers a raster only if it has been resized (the source bitmap was not of texture map size and rwFITIMAGE was specified) or changed in depth. This option mirrors the rwAUTODITHER texture dither mode. rwAUTODITHERRASTER must not be specified with rwDITHERRASTER.

•	rwDITHERASTER forces dithering of a raster. If neither rwAUTODITHERRASTER nor rwDITHERRASTER is specified the raster will not be dithered.

RwRasterOptions

•	rwAUTODITHERRASTER    Dither the raster if "necessary"

•	rwDITHERRASTER    Dither the raster

•	rwFITRASTER    Resize the raster to the appropriate size for a texture

•	rwGAMMARASTER    Gamma correct the raster

•	rwINDEXRASTER    Use color indices (do not color match the raster)


Clump Hints

The bitfield type RwClumpHints optimizes rendering by passing hints to RenderWare about the nature of a clump and the environment in which it is to be rendered.

The clump hints are as follows:

rwCONTAINER marks the clump as a container - a clump which spatially contains other clumps. For example, a clump representing a room should normally have the rwCONTAINER hint set.

rwHS specifies that hidden surfaces should be removed when the clump is rendered.

rwEDITABLE marks the clump as being editable (its vertices may be moved and new vertices and polygons added).

RwClumpHints

•	rwCONTAINER    Clump is a container

•	rwHS    Apply hidden surface removal to the clump

•	rwEDITABLE    Clump's geometry may be edited


Texture Modes

The bitfield type RwTextureModes provides fine grain control over the rendering of textures.

Two textures modes are defined: rwLIT and rwFORESHORTEN.

If rwLIT is specified, the associated texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX). If it is not specified, the texture will not be affected by lighting; its luminance will be as tabulated in the texture's bitmap data.

rwFORESHORTEN controls the interpolation of texture coordinates. A texture image is applied by assigning a texel colour to each pixel within a projected polygon from an associated position within that image. This position is specified by a pair of texture coordinates, conventionally called (u, v). These coordinates are each in the range [0 … 1] and measure how far to the right and below the upper left corner of the image, respectively, to take the texel colour. Each vertex in a clump may be assigned a pair of texture coordinates. A textured image is "wrapped" over a polygon by interpolating texture coordinates defined at the vertices over the polygon's projection.

By default, the texture coordinates specified at the vertices are interpolated bilinearly over the screen projection of a polygon. This method of texture coordinate interpolation is analogous to the luminance interpolation of Gouraud shading, and gives high speed performance. For perspective views however, this bilinear interpolation is only mathematically correct if the polygon is at a constant depth from - and therefore lies in a plane parallel to - the view plane. The bilinear screen space interpolation of texture coordinates over the projection of a polygon which is not parallel to the view plane will "drift" away from their true values when the interpolation is distant from the projected vertices, although the interpolation always synchronizes with exact values at the vertices. Such inaccuracies are often negligible, but can be noticeable if a polygon extends over a significant depth range relative to the screen or projects to a large screen area. A large depth range introduces inaccuracies into the bilinear interpolation, whilst a large projected area allows plenty of screen "real estate" away from vertices over which these may accumulate. Such inaccuracies manifest themselves by the applied texture not being foreshortened as would be expected in a perspective image.

The rwFORESHORTEN texture mode will ensure that exact texture coordinates are interpolated over the entire screen projection of a polygon, thereby rendering the expected foreshortening. However, the arithmetic underlying this interpolation can be significantly more involved than that for bilinear interpolation. The indiscriminate application of this texture mode can degrade performance to an unacceptable level. The rwFORESHORTEN texture mode should only applied when texturing polygons for which bilinear interpolation is significantly inaccurate - those extending over a significant depth range relative to the screen plane and projecting to a large screen area. The interpolation adopted in the rwFORESHORTEN texture mode has been optimized for polygons projecting to a large screen area, so that visual and performance integrity may be ensured simultaneously.

RwTextureModes

•	rwLIT    Texture is illuminated by lights sources

•	rwFORESHORTEN    Texture is foreshortened in a persepctively correct manner


UserDraw Alignments

The bitfield type RwUserDrawAlignmentTypes controls the justification of a user draw relative to the object with which it is associated - clump vertex, clump bounding box, clump origin or camera viewport. The four options, rwALIGNTOP, rwALIGNBOTTOM, rwALIGNLEFT and rwALIGNRIGHT, respectively justify the top, bottom, left or right edge of a user draw with the associated object. These options may be combined; for example, specifying rwALIGNTOP | rwALIGNLEFT, will align the top left hand corner of the user draw with the associated object. Two simplification options are provided for common types of alignment, rwALIGNTOPLEFT and rwALIGNBOTTOMRIGHT. Specifying both rwALIGNTOP and rwALIGNBOTTOM is not permitted. Specifying both rwALIGNLEFT and rwALIGNRIGHT is not permitted. If no options are selected the user draw will be centered about the associated object.

RwUserDrawAlignmentTypes

•	rwALIGNTOP    Align to top edge

•	rwALIGNBOTTOM    Align to bottom edge

•	rwALIGNLEFT    Align to left edge

•	rwALIGNRIGHT    Align to right edge

•	rwALIGNTOPLEFT    Align to top and left edges

•	rwALIGNBOTTOMRIGHT    Align to bottom and right edges


Opaque Types

Most RenderWare objects are opaque - their implementation is hidden from the user. These objects are created by RenderWare API functions which return pointers thereto. Such opaque objects can only be accessed through RenderWare API functions. These functions require that the target object is identified by its opaque object pointer. As such, opaque objects are similar to the C standard library FILE structure.

The opaque object types are:

•	RwCamera *    A camera

•	RwClump *    A collection of polygons and vertices

•	RwLight *    A light

•	RwMaterial *    A set of attributes defining a surface material

•	RwMatrix4d *    A 4 x 4 transformation matrix

•	RwPolygon3d *    A polygon

•	RwRaster *    A bitmap (used by textures or as a camera backdrop)

•	RwScene *    A scene

•	RwSpline *    A spline

•	RwTexture *    A texture (single or multi-frame)

•	RwUserDraw *    A 2D, application drawn object


Script Keywords

This section gives a brief summary of each scripting language keyword. For further information on the operation of each keyword see the description of the keyword's associated "Object Builder" API function.

Related Topics:

AddHint <hint>

AddTextureMode <mode>

Ambient <ka>

AxisAlignment <alignment>

Block <width> <height> <depth>

ClumpBegin

ClumpEnd

Color <red> <green> <blue>

Cone <height> <radius> <nsides>

Cylinder <height> <baserad> <toprad> <nsides>

Diffuse <kd>

Disc <height> <radius> <nsides>

GeometrySampling <sampling>

Hemisphere <radius> <density>

Hints <hints>

Identity

IdentityJoint

Include <filename>

IncludeGeometry <filename>

JointTransformBegin

JointTransformEnd

LightSampling <sampling>

MaterialBegin

MaterialEnd

ModelBegin

ModelEnd

Opacity <opacity>

Polygon <nsides> <v1> ... <vn>

PolygonExt <nsides> <v1> ... <vn> [ Tag <tag> ]

ProtoBegin <name>

ProtoEnd

ProtoInstance <name>

ProtoInstanceGeometry <name>

Quad <v1> <v2> <v3> <v4>

QuadExt <v1> <v2> <v3> <v4> [ Tag <tag> ]

RemoveHint <hint>

RemoveTextureMode <mode>

Rotate <x> <y> <z> <angle>

RotateJoint <x> <y> <z> <angle>

Scale <x> <y> <z>

Specular <ks>

Sphere <radius> <density>

Surface <ka> <kd> <ks>

Tag <tag>

Texture <name>

TextureDithering <mode>

TextureExt <name> [ Mask <mask filename> ]

TextureGammaCorrection <mode>

TextureModes <modes>

Trace <mode>

Transform   <elements>

TransformBegin

TransformEnd

TransformJoint <elements>

Translate <x> <y> <z>

Triangle <v1> <v2> <v3>

TriangleExt <v1> <v2> <v3> [ Tag <tag> ]

Vertex <x> <y> <z>

VertexExt <x> <y> <z> [ Normal <i> <j> <k> ]   [ UV <u> <v> ]


AddHint <hint>

Description

Adds the specified hint (or hints) to the set of hints of the current clump under construction.

Arguments

hint	A space separated list of hints where each hint is one of Container, HS or Editable.

API Equivalent

RwAddHint()


AddTextureMode <mode>

Description

Adds the specified texture mode (or modes) to the set of texture modes of the current material.

Arguments

mode	A space separated list of texture modes where each texture mode is one of Lit or Foreshorten.

API Equivalent

RwAddTextureModeToSurface()


Ambient <ka>

Description

Sets the ambient coefficient of reflectance of the current material.

Arguments

ka	The ambient coefficient.

API Equivalent

RwSetSurfaceAmbient()


AxisAlignment <alignment>

Description

Sets the axis alignment type of the current clump under construction.

Arguments

alignment	The clump axis alignment. One of None, ZOrientX, ZOrientY or XYZ.

API Equivalent

RwSetAxisAlignment()


Block <width> <height> <depth>

Description

Adds polygons representing a block of the given dimensions to the current clump under construction.

Arguments

width	The width of the block.

height	The height of the block.

depth	The depth of the block.

Comments

The vertices of the block are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the block.

It is not legal to specify a block dimension of zero.

API Equivalent

RwBlock()


ClumpBegin

Description

Begins the construction of a new clump.

Arguments

None.

Comments

The clump begun with ClumpBegin will be the target of all operations on the current clump under construction until a matching ClumpEnd is found.

If ClumpBegin is nested within another ClumpBegin or ProtoBegin block a new child clump will be created.

API Equivalent

RwClumpBegin()


ClumpEnd

Description

Ends the construction of the current clump.

Arguments

None.

API Equivalent

RwClumpEnd()


Color <red> <green> <blue>

Description

Sets the color of the current material to the given color.

Arguments

red	The red component of the color

green	The green component of the color.

blue	The blue component of the color.

API Equivalent

RwSetSurfaceColor()


Cone <height> <radius> <nsides>

Description

Adds polygons representing a cone to the current clump under construction.

Arguments

height	The height of the cone (up the Y axis).

radius	The radius of the cone (in the X-Z plane).

nsides	The number of sides.

Comments

The vertices of the cone are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the cone.

If a negative radius is given, the polygons forming the cone will face towards the axis of the cone.

API Equivalent

RwCone()


Cylinder <height> <baserad> <toprad> <nsides>

Description

Adds polygons representing a cylinder to the current clump under construction.

Arguments

height	The height of the cylinder (up the Y axis).

baserad	The radius of the cylinder base (in the X-Z plane).

toprad	The radius of the cylinder top.

nsides	The number of sides.

Comments

The vertices of the cylinder are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the cylinder.

If a negative radius is given, the polygons forming the cylinder will face towards the axis of the cylinder.

API Equivalent

RwCylinder()


Diffuse <kd>

Description

Sets the diffuse coefficient of reflectance of the current material.

Arguments

kd	The diffuse coefficient.

API Equivalent

RwSetSurfaceDiffuse()


Disc <height> <radius> <nsides>

Description

Adds polygons representing a disc to the current clump under construction.

Arguments

height	The displacement (up the Y axis) of the disc.

radius	The radius of the disc.

nsides	The number of sides.

Comments

This keyword is normally used for capping cones and cylinders.

The vertices of the disc are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the disc.

If a negative radius is given the polygons forming the disc will face downwards.

API Equivalent

RwDisc()


GeometrySampling <sampling>

Description

Sets the geometry sampling type of the current material to the type specified.

Arguments

sampling	The geometry sampling type. One of PointCloud, WireFrame or Solid.

API Equivalent

RwSetSurfaceGeometrySampling()


Hemisphere <radius> <density>

Description

Adds polygons representing a hemisphere to the current clump under construction.

Arguments

radius	The radius of the hemisphere.

density	Controls the accuracy of the hemisphere.

Comments

The base of the hemisphere lies on the X-Z plane.

The density controls the number of polygons used to approximate the hemisphere. A density of 0 results in a pyramid. The number of polygons used for the approximation varies exponentially with density.

The vertices of the hemisphere are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the hemisphere.

If a negative radius is given the polygons forming the hemisphere will face inward.

API Equivalent

RwHemisphere()


Hints <hints>

Description

Sets the set of hints of the current clump under construction to those specified.

Arguments

hints	NULL or a space separated list of hints where each hint is one of Container, HS or Editable.

API Equivalent

RwSetHints()


Identity

Description

Sets the current transformation matrix (CTM) to the identity matrix.

Arguments

None.

API Equivalent

RwIdentityCTM()


IdentityJoint

Description

Sets the current joint transformation matrix to the identity matrix.

Arguments

None.

API Equivalent

RwIdentityJointTM()


Include <filename>

Description

Merges the clump constructed by reading the specified script file with the current clump under construction.

Arguments

filename	Filename of the script file to read.

Comments

Include does not create a new child clump. It merges the polygons of the clump read with the polygons of the current clump under construction. If a new child clump is desired surround the Include keyword with a ClumpBegin … ClumpEnd block.

The materials of the polygons read from the script file are preserved.

API Equivalent

RwInclude()


IncludeGeometry <filename>

Description

Merges the clump constructed by reading the specified script file with the current clump under construction. The materials of the merged polygons are replaced with the current material.

Arguments

filename	Filename of the script file to read.

Comments

IncludeGeometry does not create a new child clump. It merges the polygons of the clump read with the polygons of the current clump under construction. If a new child clump is desired surround the IncludeGeometry keyword with a ClumpBegin … ClumpEnd block.

The materials of the polygons read from the script file are replaced with the current material.

API Equivalent

RwIncludeGeometry()


JointTransformBegin

Description

Pushes a copy of the current joint transformation matrix onto the joint matrix stack in order that the existing value may be restored at a later stage.

Arguments

None.

API Equivalent

RwJointTransformBegin()


JointTransformEnd

Description

Restores the current joint transformation matrix from the last matrix pushed onto the joint matrix stack with JointTransformBegin. This discards any modifications to the current joint transformation matrix made since the last JointTransformBegin.

Arguments

None.

API Equivalent

RwJointTransformEnd()


LightSampling <sampling>

Description

Sets the light sampling type of the current material to the type specified.

Arguments

sampling	The light sampling type. One of Facet or Vertex.

API Equivalent

RwSetSurfaceLightSampling()


MaterialBegin

Description

Pushes a copy of the current material onto the material stack in order that the existing value may be restored at a later stage.

Arguments

None.

API Equivalent

RwMaterialBegin()


MaterialEnd

Description

Restores the current material from the last material pushed onto the material stack with MaterialBegin. This discards any modifications to the current material made since the last MaterialBegin.

Arguments

None.

API Equivalent

RwMaterialEnd()


ModelBegin

Description

Begins a new modelling context.

Arguments

None.

Comments

With the exception of the Trace keyword, ModelBegin must be the first keyword in a script file.

API Equivalent

RwModelBegin()


ModelEnd

Description

Ends a modelling context.

Arguments

None.

Comments

ModelEnd must be the last keyword in a script file.

API Equivalent

RwModelEnd()


Opacity <opacity>

Description

Sets the opacity of the current material.

Arguments

opacity	The opacity of the material.

Comments

A value of 1.0 yields an entirely opaque material. A value of 0.0 yields an entirely transparent material. Intermediate values yield varying degrees of semi-transparency.

API Equivalent

RwSetSurfaceOpacity()


Polygon <nsides> <v1> ... <vn>

Description

Creates a new polygon with the given vertices and adds it to the current clump under construction.

Arguments

nsides	The number of sides of the polygon.

v1 ... vn	The indices of the polygon's vertices.

Comments

v1 ... vn are indices into the vertex list of the current clump under construction. The number of indices specified must be equal to nsides.

The current material is applied to the new polygon.

Polygon is a synonym of PolygonExt. The optional integer tag may also be specified when using the Polygon keyword.

API Equivalent

RwPolygon()


PolygonExt <nsides> <v1> ... <vn> [ Tag <tag> ]

Description

Creates a new polygon with the given vertices and adds it to the current clump under construction. An integer tag may be specified in order to mark the polygon.

Arguments

nsides	The number of sides of the polygon.

v1 ... vn	The indices of the polygon's vertices.

tag	An optional integer tag to assign to the polygon.

Comments

v1 ... vn are indices into the vertex list of the current clump under construction. The number of indices specified must be equal to nsides.

The current material is applied to the new polygon.

The integer tag is optional. To specify a tag use the optional keyword modifier Tag followed by an integer.

API Equivalent

RwPolygonExt()


ProtoBegin <name>

Description

Begins the definition of a prototype.

Arguments

name	The name of the prototype.

Comments

The prototype begun with ProtoBegin will be the target of all operation on the current clump under construction until a matching ProtoEnd is found.

ProtoBegin must not be nested within a ClumpBegin … ClumpEnd or ProtoBegin … ProtoEnd block.

The new prototype will override the definition of any existing prototype with the same name.

API Equivalent

RwProtoBegin()


ProtoEnd

Description

Ends the definition of the current prototype.

Arguments

None.

API Equivalent

RwProtoEnd()


ProtoInstance <name>

Description

Merges the prototype of the given name with the current clump under construction.

Arguments

name	The name of the prototype to merge.

Comments

ProtoInstance does not create a new child clump. It merges the polygons of the prototype with the polygons of the current clump under construction. If a new child clump is desired, surround the ProtoInstance keyword with a ClumpBegin … ClumpEnd block.

The materials of the polygons of the prototype are preserved.

API Equivalent

RwProtoInstance()


ProtoInstanceGeometry <name>

Description

Merges the prototype of the specified name with the current clump under construction. The materials of the merged polygons are replaced with the current material.

Arguments

name	The name of the prototype to merge.

Comments

ProtoInstanceGeometry does not create a new child clump. It merges the polygons of the prototype with the polygons of the current clump under construction. If a new child clump is desired, surround the ProtoInstanceGeometry keyword with a ClumpBegin … ClumpEnd block.

The materials of the polygons of the prototype are replaced with the current material.

API Equivalent

RwProtoInstanceGeometry()


Quad <v1> <v2> <v3> <v4>

Description

Creates a new quadrilateral with the given vertices and adds it to the current clump under construction.

Arguments

v1	The first vertex index of the quadrilateral.

v2	The second vertex index of the quadrilateral.

v3	The third vertex index of the quadrilateral.

v4	The fourth vertex index of the quadrilateral.

Comments

v1, v2, v3 and v4 are indices into the vertex list of the current clump under construction.

The current material is applied to the new quadrilateral.

Quad is a synonym of QuadExt. The optional integer tag may also be specified when using the Quad keyword.

This keyword is semantically identical to Polygon 4 <v1> <v2> <v3> <v4>

API Equivalent

RwQuad()


QuadExt <v1> <v2> <v3> <v4> [ Tag <tag> ]

Description

Creates a new quadrilateral with the given vertices and adds it to the current clump under construction. An integer tag may be specified in order to mark the polygon.

Arguments

v1	The first vertex index of the quadrilateral.

v2	The second vertex index of the quadrilateral.

v3	The third vertex index of the quadrilateral.

v4	The fourth vertex index of the quadrilateral.

tag	An optional integer tag to assign to the quadrilateral.

Comments

v1, v2, v3 and v4 are indices into the vertex list of the current clump under construction.

The current material is applied to the new quadrilateral.

The integer tag is optional. To specify a tag use the optional keyword modifier Tag followed by an integer.

This keyword is semantically identical to PolygonExt 4 <v1> <v2> <v3> <v4> Tag <tag>

API Equivalent

RwQuadExt()


RemoveHint <hint>

Description

Removes the specified hint (or hints) from the set of hints of the current clump under construction.

Arguments

hint	A space separated list of hints where each hint is one of Container, HS or Editable.

API Equivalent

RwRemoveHint()


RemoveTextureMode <mode>

Description

Removes the texture mode (or modes) specified from the set of texture modes of the current material.

Arguments

mode	A space separated list of texture modes where each texture mode is one of Lit or Foreshorten.

API Equivalent

RwRemoveTextureModeFromSurface()


Rotate <x> <y> <z> <angle>

Description

Build a transformation matrix representing a rotation of angle degrees about the specified vector and pre-concatenate it onto the current transformation matrix (CTM).

Arguments

x	The X component of the vector to rotate about.

y	The Y component of the vector to rotate about.

z	The Z component of the vector to rotate about.

angle	The angle of rotation (in degrees).

API Equivalent

RwRotateCTM()


RotateJoint <x> <y> <z> <angle>

Description

Builds a transformation matrix representing a rotation of angle degrees about the specified vector and pre-concatenate it onto the current joint transformation matrix.

Arguments

x	The X component of the vector to rotate about.

y	The Y component of the vector to rotate about.

z	The Z component of the vector to rotate about.

angle	The angle (in degrees) of rotation.

API Equivalent

RwRotateJointTM()


Scale <x> <y> <z>

Description

Builds a scale matrix and pre-concatenates it onto the current transformation matrix (CTM).

Arguments

x	The scale factor along the X axis.

y	The scale factor along the Y axis.

z	The scale factor along the Z axis.

API Equivalent

RwScaleCTM()


Specular <ks>

Description

Sets the specular coefficient of reflectance of the current material.

Arguments

ks	The specular coefficient.

API Equivalent

RwSetSurfaceSpecular()


Sphere <radius> <density>

Description

Adds polygons representing a sphere to the current clump under construction.

Arguments

radius	The radius of the sphere.

density	Controls the accuracy of the sphere.

Comments

The density controls the number of polygons used to approximate the sphere. A density of zero results in a cube. The number of polygons used for the approximation varies exponentially with density.

The vertices of the sphere are transformed by the current transformation matrix (CTM). The current material is applied to the polygons of the sphere.

If a negative radius is given the polygons forming the sphere will face inward.

API Equivalent

RwSphere()


Surface <ka> <kd> <ks>

Description

Sets the ambient, diffuse and specular coefficients of reflectance of the current material.

Arguments

ka	The ambient coefficient.

kd	The diffuse coefficient.

ks	The specular coefficient.

API Equivalent

RwSetSurface()


Tag <tag>

Description

Sets the integer tag of the current clump under construction to the specified value.

Arguments

tag	The integer tag.

API Equivalent

RwSetTag()


Texture <name>

Description

Sets the texture of the current material to the texture with the name specified. The current material's texture can be removed by specifying a texture name of NULL.

Arguments

name	The texture name (or NULL).

Comments

The texture is found by searching the current texture dictionary stack and shape path. For a discussion of the algorithm used to find the texture see the description of RwGetNamedTexture().

Texture is a synonym of TextureExt. A mask may be also be specified (using the Mask keyword modifier) with the Texture keyword.

API Equivalent

RwSetSurfaceTexture()


TextureDithering <mode>

Description

Sets the global texture dithering mode applied to all subsequently loaded textures.

Arguments

mode	The texture dithering mode. One of Auto, On or Off.

API Equivalent

RwSetTextureDithering()


TextureExt <name> [ Mask <mask filename> ]

Description

Sets the texture of the current material to the texture with the name specified. The texture is masked by the mask raster with the given filename.

Arguments

name	The texture name.

mask filename	The filename of the mask raster.

Comments

The texture is found by searching the current texture dictionary stack and search path. For a discussion of the algorithm used to find the texture see the description of RwGetNamedTexture().

The raster is found by searching the current shape path. For a discussion of method used to find the mask raster and to apply it to the texture see the descriptions of RwReadMaskRaster() and RwMaskTexture() respectively.

API Equivalent

RwSetSurfaceTextureExt()


TextureGammaCorrection <mode>

Description

Sets the global texture gamma correction mode applied to all subsequently loaded textures.

Arguments

mode	The texture gamma correction mode. One of On or Off.

API Equivalent

RwSetTextureGammaCorrection()


TextureModes <modes>

Description

Sets the current material's set of texture modes to the modes specified.

Arguments

modes	NULL or a space separated list of texture modes where each texture modes is one of Lit or Foreshorten.

API Equivalent

RwSetSurfaceTextureModes()


Trace <mode>

Description

Sets the script tracing mode.

Arguments

mode	The script tracing mode. One of On or Off.

Comments

Script tracing is only available under debugging versions of the RenderWare library. This keyword has no effect under production versions of the library.

The Trace keyword is the only keyword permitted in a file before ModelBegin.

API Equivalent

None.


Transform   <elements>

Description

Replaces the elements of the current transformation matrix (CTM) with the specified matrix elements.

Arguments

elements	A space separated list of sixteen real matrix elements.

API Equivalent

RwTransformCTM()


TransformBegin

Description

Pushes a copy of the current transformation matrix (CTM) onto the   matrix stack in order that the existing value may be restored at a later stage.

Arguments

None.

API Equivalent

RwTransformBegin()


TransformEnd

Description

Restores the current transformation matrix (CTM) from the last transformation pushed onto the matrix stack with TransformBegin. This discards any modifications to the current transformation matrix (CTM) made since the last TransformBegin.

Arguments

None.

API Equivalent

RwTransformEnd()


TransformJoint <elements>

Description

Replaces the elements of the current joint transformation matrix with the specified matrix elements.

Arguments

elements	A space separated list of sixteen real matrix elements.

API Equivalent

RwTransformJointTM()


Translate <x> <y> <z>

Description

Builds a translation matrix and pre-concatenates it onto the current transformation matrix (CTM).

Arguments

x	The translation along the X axis.

y	The translation along the Y axis.

z	The translation along the Z axis.

API Equivalent

RwTranslateCTM()


Triangle <v1> <v2> <v3>

Description

Creates a new triangle with the given vertices and adds it to the current clump under construction.

Arguments

v1	The first vertex index of the triangle.

v2	The second vertex index of the triangle.

v3	The third vertex index of the triangle.

Comments

v1, v2 and v3 are indices into the vertex list of the current clump under construction.

The current material is applied to the new triangle.

Triangle is a synonym of TriangleExt. The integer tag may also be specified when using the Triangle keyword.

API Equivalent

RwTriangle()


TriangleExt <v1> <v2> <v3> [ Tag <tag> ]

Description

Creates a new triangle with the given vertices and adds it to the current clump under construction. An integer tag may be specified in order to mark the polygon.

Arguments

v1	The first vertex index of the triangle.

v2	The second vertex index of the triangle.

v3	The third vertex index of the triangle.

tag	An optional integer tag to assign to the triangle.

Comments

v1, v2 and v3 are indices into the vertex list of the current clump under construction.

The current material is applied to the new triangle.

The integer tag is optional. To specify a tag use the optional keyword modifier Tag followed by an integer.

API Equivalent

RwTriangleExt()


Vertex <x> <y> <z>

Description

Creates a new vertex and adds it to the current clump under construction.

Arguments

x	The X coordinate of the vertex.

y	The Y coordinate of the vertex.

z	The Z coordinate of the vertex.

Comments

The vertex is transformed by the current transformation matrix (CTM).

Vertex is a synonym of VertexExt. The texture coordinates and unit shading normal may also be specified (with the optional keyword modifiers UV and Normal respectively) with the Vertex keyword.

API Equivalent

RwVertex()


VertexExt <x> <y> <z> [ Normal <i> <j> <k> ]   [ UV <u> <v> ]

Description

Creates a new vertex and adds it to the current clump under construction. The unit shading normal and texture coordinates are set to the specified values.

Arguments

x	The X coordinate of the vertex.

y	The Y coordinate of the vertex.

z	The Z coordinate of the vertex.

i	The X component of the optional unit shading normal.

j	The Y component of the optional unit shading normal.

k	The Z component of the optional unit shading normal.

u	The U coordinate of the optional texture coordinates.

v	The V coordinate of the optional texture coordinates.

Comments

The vertex is transformed by the current transformation matrix (CTM).

The unit shading normal and texture coordinates are optional. To specify a normal use the optional keyword modifier Normal.To specify texture coordinates use the optional keyword modifier UV.

API Equivalent

RwVertexExt()


Miscellaneous Notes

This section contains certain important notes concerning the use of the scripting language.

•	Scripts are read using the RenderWare API function RwReadShape() which returns a pointer to the clump built by the script.

•	All of the scripting keywords are case-insensitive, i.e., upper and lower case may be freely mixed. Keyword values are also case-insensitive with the exception of filename. The case sensitivity of filenames is dependent upon the host operating system.

•	Every script file should have exactly one top-level ModelBegin … ModelEnd block. Within such a block, zero or more ProtoBegin … ProtoEnd blocks followed by one top-level ClumpBegin … ClumpEnd block are expected. The ProtoBegin … ProtoEnd blocks are prototype declarations, and the top-level ClumpBegin … ClumpEnd block is an actual clump being constructed by the script.

•	The keywords Vertex and VertexExt are exactly equivalent. Both may be used to specify a vertex with texture coordinates and a unit shading normal. This is in contrast to the API level object builder functions where only RwVertexExt() may be used to specify a vertex with texture coordinates and unit shading normal.

•	The keywords Polygon and PolygonExt are exactly equivalent. Both may be used to specify a polygon with an integer tag. This is in contrast to the API level object builder functions where only RwPolygonExt() may be used to specify a polygon with an integer tag. This also applies to Quad and QuadExt and Triangle and TriangleExt.

•	Scripting keywords which take vertices as arguments, such as Triangle, require a vertex to be identified by its vertex number. Vertex numbers start at one and each time that the Vertex (or VertexExt) keyword is used within a script, they are incremented by one. The number of the first vertex created by the Vertex (or VertexExt) keyword is one, the second is two, and so on. Note that the vertex numbering is not affected by any scripting keywords which add vertices (such as Include or Sphere) other than Vertex (or VertexExt).

•	Scripting keyword that take a 4 x 4 transformation matrix as an argument, e.g., Transform, require the matrix to be specified by a sequence of sixteen real numbers (separated by spaces) representing its elements. The Transform and TransformJoint scripting keywords expect the matrix elements to be specified in row-major order, i.e., the first four elements specify the first row of the matrix, and so on.

•	Rotation, translation and scaling are performed by pre-concatenation.

•	The Tag keyword is mainly useful for identifying parts of a hierarchical model so that they may be located and manipulated in an application program. A RenderWare application can then locate a particular clump within a clump hierarchy by using the RwFindTaggedClump() function.

•	PolygonExt, QuadExt and TriangleExt allow an optional integer tag to be specified using the keyword modifier Tag. This tagging of polygons serves a similar purpose as the tagging of clumps. Application clumps can use the tags to identify and modify particular polygons in a script. The API function RwFindTaggedPolygon() searches for a polygon with a particular tag in the polygon list of a clump.

•	The Texture keyword accepts NULL as its argument, in which case any texture associated with the current material is removed. From that point on, no texture is applied to the geometry created.

The following is a simple, example script which builds a clump that consists of a red cube:

ModelBegin
ClumpBegin
Surface 0.2 0.3 0.7 # shiny
Color 1.0 0.0 0.0   # red
Block 0.5 0.5 0.5
ClumpEnd
ModelEnd

The Surface keyword sets ambient, diffuse, and specular reflection coefficients of the current material to 0.2, 0.3 and 0.7 respectively.

The current material's color is set to red using the Color keyword.

The Block keyword adds a block (whose width, height, and depth are all 0.5) to the current clump under construction. The current transformation (in this case the identity) is applied to the polygons being added and the materials of these polygons are set to the current material.


"Object Builder" API Functions

The following table summarizes the "Object Builder" API functions which mirror each script keyword. For a detailed description of each "Object Builder" API function see the Function Reference section of this manual.

API Function Equivalents of Script Keywords

Script Keyword	API Function
AddHint	RwAddHint()
AddTextureMode	RwAddTextureModeToSurface()
Ambient	RwSetSurfaceAmbient()
AxisAlignment	RwSetAxisAlignment()
Block	RwBlock()
ClumpBegin	RwClumpBegin()
ClumpEnd	RwClumpEnd()
Color	RwSetSurfaceColor()
Cone	RwCone()
Cylinder	RwCylinder()
Diffuse	RwSetSurfaceDiffuse()
Disc	RwDisc()
GeometrySampling	RwSetSurfaceGeometrySampling()
Hemisphere	RwHemisphere()
Hints	RwSetHints()
Identity	RwIdentityCTM()
IdentityJoint	RwIdentityJointTM()
Include	RwInclude()
IncludeGeometry	RwIncludeGeometry()
JointTransformBegin	RwJointTransformBegin()
JointTransformEnd	RwJointTransformEnd()
LightSampling	RwSetSurfaceLightSampling()
MaterialBegin	RwMaterialBegin()
MaterialEnd	RwMaterialEnd()
ModelBegin	RwModelBegin()
ModelEnd	RwModelEnd()
Opacity	RwSetSurfaceOpacity()
Polygon	RwPolygon()
PolygonExt	RwPolygonExt()
ProtoBegin	RwProtoBegin()
ProtoEnd	RwProtoEnd()
ProtoInstance	RwProtoInstance()
ProtoInstanceGeometry	RwProtoInstanceGeometry()
Quad	RwQuad()
QuadExt	RwQuadExt()
RemoveHint	RwRemoveHint()
RemoveTextureMode	RwRemoveTextureModeFromSurface()
Rotate	RwRotateCTM()
RotateJoint	RwRotateJointTM()
Scale	RwScaleCTM()
Specular	RwSetSurfaceSpecular()
Sphere	RwSphere()
Surface	RwSetSurface()
Tag	RwSetTag()
Texture	RwSetSurfaceTexture()
TextureDithering	RwSetTextureDithering()
TextureExt	RwSetSurfaceTextureExt()
TextureGammaCorrection	RwSetTextureGammaCorrection()
TextureModes	RwSetSurfaceTextureModes()
Trace	None
Transform	RwTransformCTM()
TransformBegin	RwTransformBegin()
TransformEnd	RwTransformEnd()
TransformJoint	RwTransformJointTM()
Translate	RwTranslateCTM()
Triangle	RwTriangle()
TriangleExt	RwTriangleExt()
Vertex	RwVertex()
VertexExt	RwVertexExt()


Requirements

The fixed-point RenderWare library requires an IBM PC compatible with an Intel Pentium, 80486DX, 80486SX, 80386DX or 80386SX CPU (or equivalent), 4Mb of memory, and a color VGA or SuperVGA display adapter.

The recommended minimum configuration for the fixed-point RenderWare library is an Intel 80486SX/25 with 8Mb of memory. For highest performance rendering a display adapter running in 8-bit (256 color) mode is recommended. For highest quality rendering a display adapter running in 16-bit (65536 color) mode is recommended.

The floating-point RenderWare library requires an IBM PC compatible with an Intel Pentium, 80486DX or 80386 and 387 math co-processor (or equivalent), 4Mb of memory, and a color VGA or SuperVGA display adapter.

The recommended minimum configuration for the floating-point RenderWare library is an Intel 80486DX/25 with 8Mb of memory. For highest performance rendering a display adapter running in 8-bit (256 color) mode is recommended. For highest quality rendering a display adapter running in 16-bit (65536 color) mode is recommended.

For optimum performance, choose a CPU with a fast external clock speed over a clock-doubled CPU (e.g., 486DX/50 rather than 486DX2/66), 256K external cache, 70ns memory and a fast PCI or VESA-Local Bus display adapter.


Environment Variables

The RenderWare library makes use of several environment variables, RWDEVICE, RWSHAPEPATH etc. These environment variables are optional. The library will operate correctly if they are not set.

However, if the environment variables are to be employed they must be set before entering MS Windows. Setting the environment variable from a DOS window running under MS Windows 3.1 will not work. It is strongly recommended that the necessary environment variables be set in the host machine's AUTOEXEC.BAT.


RenderWare Library Configuration

Previous versions of RenderWare provided control over certain aspects of library configuration, such as gamma correction and color ramp size, by reading an initialization file, winrw.ini. Although this did allow the modification of library configuration without application recompilation there were two main problems with this approach:

•	It was difficult to run two different RenderWare applications, requiring different configurations, simultaneously.

•	As the initialization file was plain ASCII text, it was possible for an end user to modify the file and, hence, adversely effect the operation of the RenderWare application.

RenderWare V1.3 addresses these problem by providing API level control over library configuration with the new RwOpenExt() function. This function, an alternative to RwOpen(), supports the specification of additional, optional arguments controlling library configuration. RwOpenExt() is the recommended way of controlling library configuration. However, to ensure backwards compatibility and continued ease of configuration modification, the function RwOpen() still parses the RenderWare configuration file.

RenderWare looks for its configuration file, winrw.ini in the Windows directory. The format of the configuration file is as follows:

[General]
Colormap=large | medium | small
Gamma=yes | no

The General line is always placed at the beginning of the configuration file by RenderWare's setup program. Its only purpose is to make the format of the configuration file comply with the format required by Windows for initialization (".ini") files.

The Gamma keyword is to specify whether RenderWare is to produce a gamma corrected palette. VGA cards usually perform gamma correction but some recent Windows drivers allow gamma correction to be turned off.

The default value is no.

The Colormap keyword controls the amount of the 256 entry color palette that is used by RenderWare. This line is optional. For RenderWare V1.3, small, medium and large give ramp sizes of 16, 19 and 23 entries respectively. These values are, however, subject to change in future releases of RenderWare. Do not make assumptions based upon these values.

The default setting is large.


Include Files

For the purposes of describing how to build programs, the following assumptions are made:

•	the RenderWare include files are installed in \rw\include.

•	the RenderWare library files are installed in \rw\lib.

Source files must include the RenderWare include file:

#include <rwlib.h>

Version 1.3 of RenderWare introduces a new, MS Windows 3.1 specific, include file, rwwin31.h. This include file is only necessary if your application uses platform specific RwOpenExt() options or RwGetDeviceInfo() information types. However, it is recommended that, to ensure future compatibility, all source files which use RenderWare API functions include rwwin31.h after including the standard RenderWare include file:

#include <rwlib.h>
#include <rwwin31.h>


Device-Specific API Parameters

A small number of RenderWare API functions have device dependent parameters or return values. This section describes these device dependent parameters and return values under MS Windows 3.1.

Related Topics:

RwBitmapRaster()

RwCreateCamera()

RwDeviceControl()

RwDuplicateCamera()

RwGetCameraImage()

RwGetDeviceInfo()

RwOpen()

RwOpenExt()

RwOpenDebugStream()

RwShowCameraImage()


RwBitmapRaster()

RwRaster *

RwBitmapRaster(void *bitmap, RwRasterOptions options);

Arguments

bitmap	bitmap is a long word which holds the handles of both a device context and a device dependent bitmap. The long word is constructed using the MS Windows 3.1 macro function, MAKELONG(), as follows:

(void *)MAKELONG(hdc, hBitmap)

The device dependent bitmap can be of any size but should have a depth equal to the depth of display adapter on which MS Windows is running.

The device context must have a palette object selected into it. The palette object provides the color table of the device dependent bitmap.

It is essential that the device dependent bitmap is not selected into device context when RwBitmapRaster() is invoked.


RwCreateCamera()

RwCamera *

RwCreateCamera(int maxwidth, int maxheight, void *param);

Arguments

param	param must be either NULL or the image buffer of an existing camera (as returned by RwGetCameraImage()).

If param is NULL the new camera will allocate its own image buffer of the given width and height. For example, in the typical case of output to a window that can be maximized, the following code fragment could be used:

cam = RwCreateCamera(
GetSystemMetrics(SM_CXFULLSCREEN),
GetSystemMetrics(SM_CYFULLSCREEN),
NULL);

If param is the value returned by calling RwGetCameraImage() with an existing camera as an argument, then the new camera will not allocate its own image buffer but will share the image buffer of the existing camera. The existing camera must have exactly the same maximum width and height as those specified in the call to RwCreateCamera(). For example, to create a new camera (cam2) sharing the image buffer of the camera (cam) created above the following code fragment could be used:

cam2 = RwCreateCamera(
GetSystemMetrics(SM_CXFULLSCREEN),
GetSystemMetrics(SM_CYFULLSCREEN),
RwGetCameraImage(cam));

Sharing image buffers can reduce resource (particularly memory) consumption considerably when multiple cameras are employed. However, it does incur additional application housekeeping. Specifically, each time the shared image buffer is to be used by a different camera the entire viewport must be invalidated to prevent image data from the previous camera persisting. Furthermore, it is essential that the camera which created the image buffer, i.e., the camera that was created by a call to RwCreateCamera() with NULL passed as param, is destroyed after all other cameras sharing the image buffer.

It is strongly recommended, therefore, that, except in exceptional circumstances, each camera should create its own image buffer (NULL passed as the value of param).


RwDeviceControl()

int

RwDeviceControl(RwDeviceAction action, long param1, void *param2);

Arguments

action	Under MS Windows 3.1, RenderWare provides a single device control action, rwSETCOLRAMP. This action modifies a portion of the RenderWare color palette corresponding to a single color ramp in order to create special effects such as flashing colors. rwSETCOLRAMP is only available when RenderWare is rendering using indexed color and a ramp based color model.

Please note, this control action is highly device dependent and, as such, it may be significantly modified or even dropped from future releases of RenderWare.

It is important to note that rwSETCOLRAMP does not modify the internal rendering of RenderWare. It simply modifies a range of entries in the output color palette. Therefore, rwSETCOLRAMP cannot be used to tune RenderWare's rendering to a particular set of colors. It is provided only as a way of producing special effects such as colormap cycling or flashing.

When modifying a ramp, the arguments to RwDeviceControl() are as follows:

•	action	rwSETCOLRAMP

•	param1	The index of the color ramp to modify. The minimum ramp index is  0 and the maximum ramp index is the number of ramps less 1.

•	param2	A pointer to an array of two real numbers. The first number is the base hue of the ramp (in the range CREAL(0.0) to CREAL(1.0)). The second number is the base saturation of the ramp in the range (CREAL(0.0) to CREAL(1.0)).

For example, to change the hue of ramp 1 to cyan:

RwReal hueandsat[2];

hueandsat[0] = CREAL(0.5);
hueandsat[1] = CREAL(0.0);

RwDeviceControl(rwSETCOLRAMP, 1L,
&hueandsat[0]);

For RenderWare V1.3 FCS under MS Windows 3.1 the hues and saturations for each ramp are as follows:

Initial Color Ramp Settings

Ramp	Hue	Saturation	Color
0	CREAL(-1.0)	CREAL(0.0)	Gray
1	CREAL(0.0)	CREAL(1.0)	Red
2	CREAL(0.0)	CREAL(0.5)	Pink
3	CREAL(0.08333)	CREAL(1.0)	Orange
4	CREAL(0.16666)	CREAL(1.0)	Yellow
5	CREAL(0.33333)	CREAL(1.0)	Green
6	CREAL(0.33333)	CREAL(0.5)	Pale Green
7	CREAL(0.5)	CREAL(1.0)	Cyan
8	CREAL(0.66666)	CREAL(1.0)	Blue
9	CREAL(0.83333)	CREAL(1.0)	Magenta
Please note that the information in the above table is highly device dependent and subsequent to change with any subsequent release of RenderWare. Criterion Software Ltd. does not guarantee that the information given above will be relevant to any future release of RenderWare. The hue and saturation of each ramp, the number of ramps and even the existence of a ramp based color model is subject to change without prior notification.


RwDuplicateCamera()

RwCamera *

RwDuplicateCamera(RwCamera *cam, void *param);

Arguments

param	NULL or the image buffer of an existing camera (as returned by calling RwGetCameraImage()).

The duplicated camera will not share the image buffer of the camera being duplicated unless the image buffer of the existing camera is passed as param. If NULL is passed as param the new camera will create its own image buffer.

For an example of how to specify param, see the discussion of RwCreateCamera() in this section.


RwGetCameraImage()

void *

RwGetCameraImage(RwCamera *cam);

Return Value

The image buffer of a RenderWare camera can be either a memory device contact with a memory bitmap selected into it or a device independent bitmap (DIB).

When the depth of the output device is equal to the current rendering depth a memory device context is used.

Otherwise, a DIB is used.

To determine whether RwGetCameraImage() returns a memory device context or DIB call RwGetDeviceInfo(). For example:

RwCamera *cam;

int imageIsDIB;
HDC hdc;
BITMAPINFOHEADER *dib;

...

RwGetDeviceInfo(rwWINIMAGEISDIB, &imageIsDIB);
if (imageIsDIB)
dib = (BITMAPINFOHEADER*)RwGetCameraImage(cam);
else
hdc = (HDC)RwGetCameraImage(cam);


RwGetDeviceInfo()

int

RwGetDeviceInfo(RwDeviceInfo info, void *value);

Comments

The MS Windows 3.1 specific aspects of each device information type are as follows:

•	rwRENDERDEPTH    If the video adapter on which MS Windows is running is in 16-bit mode then the render depth will be 16. In all other cases the render depth will be 8.

•	rwINDEXEDRENDERING     As the generic RwGetDeviceInfo().

•	rwPALETTEBASED    Rendering is palette based if and only if the video adapter on which MS Windows is running is palette based. This will normally be the case if the video adapter is in 8-bit (256) color mode. In other modes rendering will not be palette based.

The following options apply if the device is rendering using an indexed color scheme:

•	rwINDEXEDCOLORMODEL     As the generic RwGetDeviceInfo().

The following options apply to devices rendering using indexed color with a ramp based color model:

•	rwNUMCOLRAMPS    As the generic RwGetDeviceInfo().

•	rwCOLRAMPSIZE    The default ramp size can be set at library open time either by RwOpenExt() or by the initialization file winrw.ini.

The following options apply when the output device is palette based:

•	rwPALETTE    Returns the GDI palette object RenderWare selects into the output device context.

value	should point to a variable of type HPALETTE. On return from RwGetDeviceInfo() this variable will contain the handle of the GDI palette object.

The palette entries used by RenderWare must not be modified. However, any unused entries may be modified using the MS Windows 3.1 API function SetPaletteEntries().

•	rwPALETTESIZE	As the generic RwGetDeviceInfo().

•	rwFIRSTPALETTEENTRY	 As the generic RwGetDeviceInfo().

•	rwLASTPALETTEENTRY	 As the generic RwGetDeviceInfo().

RenderWare V1.3 supports one MS Windows 3.1 specific information type:

•	rwWINIMAGEISDIB	A pointer to integer (boolean) which will be non-zero if RwGetCameraImage() returns a device independent bitmap (DIB) and zero if a memory device context is returned., See RwGetCameraImage() in this section for further details.


RwOpen()

int

RwOpen(char *devname, void *param);

Arguments

devname	The device name as a null-terminated string. Names currently supported under MS Windows 3.1 are:

•	"MSWindows"

•	"NullDevice"

The "NullDevice" driver allows the library to be used when output to a display is not required (for instance, when reading from or writing to files).

param	Previous versions of RenderWare required the instance handle of the application opening the library to be passed as param. RenderWare V1.3 has removed this requirement. The calling application's instance handle is no longer required. NULL should be passed as the argument param.

Comments

RwOpen() parses the RenderWare initialization file winrw.ini as described in "RenderWare Library Configuration" on page 3.


RwOpenExt()

int

RwOpenExt(char *devname, void *param, int numargs, RwOpenArgument *args);

Arguments

devname	The device name as a null-terminated string. Names currently supported under MS Windows 3.1 are:

 "MSWindows"

 "NullDevice"

The "NullDevice" driver allows the library to be used when output to a display is not required (for instance, when reading from or writing to files).

param	Previous versions of RenderWare required the instance handle of the application opening the library to be passed as param. RenderWare V1.3 has removed this requirement. The calling application's instance handle is no longer required. NULL should be passed as the argument param.

numargs	The number of optional arguments specified.

args	An array of optional open arguments.

Comments

As discussed in "RenderWare Library Configuration" on page 3, RwOpenExt() does not read the RenderWare initialization file winrw.ini. Library configuration control is achieved by specifying a number of additional arguments to RwOpenExt().

RwOpenExt() takes a pointer to an array of RwOpenArgument structures. RwOpenArgument is defined as follows:

typedef struct
{
RwOpenOption option;
void *value;
} RwOpenArgument;

option is one of the identifiers defined below and value is a parameter specific to the option type. If the parameter type is integer, the integer value should be cast to a void *. For example:

args[0].value = (void*)10;

The configuration options supported under MS Windows 3.1 are:

•	rwGAMMACORRECT	Controls whether RenderWare performs gamma correction on its color palette. value should be non-zero to enable gamma correction and zero to disable gamma correction.

•	rwSETCOLRAMPSIZE	Controls the number of colormap entries in each color ramp in the RenderWare palette. This option is primarily used to free color map entries for application use.

Reducing the ramp size releases palette entries for application use. However, it also has the effect of lowering the quality of 3D rendering. When choosing a ramp size examine the quality of the 3D rendering carefully to ensure it is of an acceptable standard.

value should be an integer giving the number entries in each ramp. The minimum permitted value is 10 and the maximum permitted value is 23.

This option is ignored if RenderWare is not rendering using indexed color and a ramp based color model.

The following example demonstrates opening the RenderWare library with gamma correction enabled and a ramp size of 16:

RwOpenArgument args[2];

args[0].option = rwGAMMACORRECT;
args[0].value  = (void *)1;
args[1].option = rwSETCOLRAMPSIZE;
args[1].value  = (void *)16
RwOpenExt("MSWindows", NULL, 2, &args[0]);


RwOpenDebugStream()

int

RwOpenDebugStream(char *filename);

Arguments

filename	Specifying "DEBUG:" as the name of a debugging stream
will result in debugging output being issued by the Windows API function OutputDebugString(). By default, debugging messages will be sent to the debugger if present.

Note that when linking against the debugging version of the library, the default debugging stream is "\rw.log".


RwShowCameraImage()

RwCamera *

RwShowCameraImage(RwCamera *cam, void *param);

Arguments

param	A long word, where the handle of the output window is in the low word and the handle to the output device context in the high word. The handles are combined using the MS Windows 3.1 macro function MAKELONG(). For example:

hdc = GetDC(hwnd);
RwShowCameraImage(cam, (void*)
MAKELONG(hwnd, hdc));
ReleaseDC(hwnd, hdc);


Error Descriptions

Note that in the discussion of the following error codes, the comments involving "Object Builder" functions RwModelBegin(), RwModelEnd(), RwProtoBegin(), RwProtoEnd(), RwClumpBegin(), RwClumpEnd(), RwTransformBegin() and RwTransformEnd() also apply to their script keyword counterparts.

Related Topics:

E_RW_BADOPEN

E_RW_COMPLEXPOLYGON

E_RW_DEFSCENE

E_RW_DEGEN

E_RW_DEGENPOLYGON

E_RW_INTERNAL

E_RW_INVAXISALIGNMENT

E_RW_INVCAMERAPROJECTION

E_RW_INVCOP

E_RW_INVDEVICE

E_RW_INVDEVICEACTION

E_RW_INVDEVICEINFO

E_RW_INVFRAME

E_RW_INVFRAMESTEP

E_RW_INVGEOMETRYSAMPLING

E_RW_INVHINT

E_RW_INVIMAGEFILE

E_RW_INVLIGHT

E_RW_INVLIGHTSAMPLING

E_RW_INVMATERIAL

E_RW_INVOPENOPTION

E_RW_INVPROTOTYPE

E_RW_INVRASTEROPTIONS

E_RW_RASTERSIZE

E_RW_INVSEARCHMODE

E_RW_INVSPP

E_RW_INVSPT

E_RW_INVSTATE

E_RW_INVSYSTEMINFO

E_RW_INVTEXTUREDITHERMODE

E_RW_INVTEXTUREHEIGHT

E_RW_INVTEXTUREMODE

E_RW_INVTEXTURENAME

E_RW_INVTEXTUREWIDTH

E_RW_INVUSERDRAWALIGN

E_RW_INVUSERDRAWTYPE

E_RW_INVVERTEXINDEX

E_RW_NESTEDMODEL

E_RW_NESTEDPROTOTYPE

E_RW_NOCLUMP

E_RW_NOCLUMPBUILT

E_RW_NOERROR

E_RW_NOFILE

E_RW_NOMATCHBEGIN

E_RW_NOMATCHEND

E_RW_NOMEM

E_RW_NOMODELBEGIN

E_RW_NOPROTOTYPEFOUND

E_RW_NOTROOT

E_RW_NULLP

E_RW_RANGE

E_RW_RASTERINUSE

E_RW_READ

E_RW_RSINVAXISALIGNMENT

E_RW_RSINVDITHERMODE

E_RW_RSINVGAMMAMODE

E_RW_RSINVGEOMETRYSAMPLING

E_RW_RSINVHINT

E_RW_RSINVLIGHTSAMPLING

E_RW_RSINVTEXTUREMODE

E_RW_RSINVTRACESTATE

E_RW_RSNOHINTS

E_RW_RSNOTEXTUREMODES

E_RW_RSPARSE

E_RW_RSREAD

E_RW_SHPPATH

E_RW_TEXTURENOTFOUND

E_RW_USER

E_RW_WRITE

E_RW_WSWRITE

E_RW_ZEROVEC


E_RW_BADOPEN

An error occurred while opening the specified file.


E_RW_COMPLEXPOLYGON

The specified polygon has too many sides. The maximum number of sides a polygon can have in RenderWare V1.3 is 255.


E_RW_DEFSCENE

An attempt was made to destroy the default scene or explicitly remove a clump or light from it.


E_RW_DEGEN

An attempt was made to create a degenerate clump (a clump with no children and no geometry).


E_RW_DEGENPOLYGON

A degenerate polygon (one with less than three sides) was specified.


E_RW_INTERNAL

An internal (library) error has occurred. Contact RenderWare technical support.


E_RW_INVAXISALIGNMENT

An invalid clump axis alignment type was specified. The legal values are rwNOAXISALIGNMENT, rwALIGNAXISZORIENTX, rwALIGNAXISZORIENTY, and rwALIGNAXISXYZ.


E_RW_INVCAMERAPROJECTION

An invalid camera projection type was specified. The legal values are rwPERSPECTIVE and rwPARALLEL.


E_RW_INVCOP

An invalid RwCombineOperation was specified. The legal values are rwREPLACE, rwPRECONCAT and rwPOSTCONCAT.


E_RW_INVDEVICE

An invalid device name was specified in a call to RwOpen() or RwOpenExt().


E_RW_INVDEVICEACTION

An invalid action was specified in a call to RwDeviceControl(). For a description of legal actions see MS Windows 3.1 Specific Information.


E_RW_INVDEVICEINFO

An invalid information type was specified in a call to RwGetDeviceInfo(). For a description of legal information types see the description of RwGetDeviceInfo() in MS Windows 3.1 Specific Information.


E_RW_INVFRAME

An invalid texture frame number was specified. A valid frame index is greater than or equal to zero and less than the number of frames in the texture.


E_RW_INVFRAMESTEP

An invalid texture frame step was specified. A valid step size is less than the absolute number of frames in the texture.


E_RW_INVGEOMETRYSAMPLING

An invalid geometry sampling type was specified. The legal values are rwPOINTCLOUD, rwWIREFRAME and rwSOLID.


E_RW_INVHINT

An invalid clump hint was specified. The legal values are rwCONTAINER, rwHS and rwEDITABLE.


E_RW_INVIMAGEFILE

An image file (MS Window's bitmap file or Sun Rasterfile) being read by RwReadRaster(), RwReadMaskRaster(), RwReadTexture() or RwReadNamedTexture() was not valid. This code indicates an error in the image data in the file.


E_RW_INVLIGHT

An invalid light type was specified. The legal values are rwDIRECTIONAL, rwPOINT and rwCONICAL.


E_RW_INVLIGHTSAMPLING

An invalid light sampling type was specified. The legal values are rwFACET and rwVERTEX.


E_RW_INVMATERIAL

An attempt was made to destroy a material whose handle was not obtained by calling RwCreateMaterial(), e.g., a material obtained by calling RwGetPolygonMaterial().


E_RW_INVOPENOPTION

An invalid option was specified in a call to RwOpenExt(). For a description of legal options see MS Windows 3.1 Specific Information.


E_RW_INVPROTOTYPE

A prototype attempted to create an instance of itself.


E_RW_INVRASTEROPTIONS

An invalid raster processing option (or combination of options) was specified. The valid options are rwGAMMARASTER, rwDITHERRASTER, rwFITRASTER and rwINDEXRASTER. If rwINDEXRASTER is specified no other options should be specified.


E_RW_RASTERSIZE

A raster of an invalid size was specified. If the raster was being selected into a texture with RwSetTextureRaster() the raster must have a width of 128 and a height of n * 128 where n is the number of frames in a multi-frame texture. If the raster is receiving a copy of a camera's viewport via RwGetCameraViewportRaster() the raster must be the same size as the camera's viewport.


E_RW_INVSEARCHMODE

An invalid search mode was specified. The legal values are rwLOCAL and rwGLOBAL.


E_RW_INVSPP

An invalid spline path type was specified. The legal values are rwSMOOTH and rwNICEENDS.


E_RW_INVSPT

An invalid spline type was specified. The legal values are rwOPENLOOP and rwCLOSEDLOOP.


E_RW_INVSTATE

An invalid state was specified. The legal values are rwON and rwOFF.


E_RW_INVSYSTEMINFO

An invalid system parameter was specified. The legal values are rwVERSIONSTRING, rwVERSIONMAJOR, rwVERSIONMINOR, rwVERSIONRELEASE, rwFIXEDPOINTLIB and rwDEBUGGINGLIB.


E_RW_INVTEXTUREDITHERMODE

An invalid texture dithering mode was specified. The legal values are rwAUTODITHER, rwDITHERON and rwDITHEROFF.


E_RW_INVTEXTUREHEIGHT

A texture with an invalid height was specified.


E_RW_INVTEXTUREMODE

An invalid texture mode was specified. The legal values are rwLIT and rwFORESHORTEN.


E_RW_INVTEXTURENAME

An invalid texture name was specified.


E_RW_INVTEXTUREWIDTH

A texture with an invalid width was specified.


E_RW_INVUSERDRAWALIGN

An invalid user-draw alignment type was specified. The legal values are rwALIGNTOP, rwALIGNBOTTOM, rwALIGNLEFT and rwALIGNRIGHT. For convenience rwALIGNTOPLEFT and rwALIGNBOTTOMRIGHT are also defined.


E_RW_INVUSERDRAWTYPE

An invalid user-draw type was specified. The legal values are rwCLUMPALIGN, rwVERTEXALIGN, rwBBOXALIGN and rwVPALIGN.


E_RW_INVVERTEXINDEX

An invalid vertex index was found. A valid index for a vertex is greater than or equal to one and less than or equal to the number of vertices in the clump to which it belongs.


E_RW_NESTEDMODEL

A nested RwModelBegin() was found in an RwModelBegin() … RwModelEnd() block or an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block. Nested modelling contexts are not allowed.


E_RW_NESTEDPROTOTYPE

A nested RwProtoBegin() was found in an RwProtoBegin() … RwProtoEnd() block or an RwClumpBegin() … RwClumpEnd() block. Nested prototype declarations are not allowed.


E_RW_NOCLUMP

No clump is currently under construction. Note that the current clump is an implicit argument of some "Object Builder" functions, e.g., RwSphere().


E_RW_NOCLUMPBUILT

The parsing of a script file resulted in no clump being created, i.e., the top-level ClumpBegin-ClumpEnd was missing from the script.


E_RW_NOERROR

No error has been set. This code indicates that no error has been detected.


E_RW_NOFILE

The specified file does not exist.


E_RW_NOMATCHBEGIN

No matching "Begin" was found for an "End". For example, this error would occur if there was no matching RwTransformBegin() for an RwTransformEnd().


E_RW_NOMATCHEND

No matching "End" was found for a "Begin". For example, this error would occur if there was no matching RwModelEnd() for an RwModelBegin().


E_RW_NOMEM

The library was unable to perform the specified operation due to insufficient memory.


E_RW_NOMODELBEGIN

An attempt was made to declare a prototype outside of an RwModelBegin() … RwModelEnd() block.


E_RW_NOPROTOTYPEFOUND

No prototype with the specified name was found.


E_RW_NOTROOT

An attempt was made to add to a scene or remove from a scene a clump that is not the root of its hierarchy.


E_RW_NULLP

A NULL pointer was used as an argument to a library function where a non-NULL object pointer was expected.


E_RW_RANGE

A numeric range error occurred.


E_RW_RASTERINUSE

An attempt was made to select a raster already owned by a texture into a different texture or to destroy a raster owned by a texture.


E_RW_READ

An error occurred while reading from an input stream.


E_RW_RSINVAXISALIGNMENT

An invalid clump axis alignment type was specified in a script file. The legal values are None, ZOrientX, ZOrientY and XYZ.


E_RW_RSINVDITHERMODE

An invalid texture dithering mode was specified in a script file. The legal values are On, Off and Auto.


E_RW_RSINVGAMMAMODE

An invalid texture gamma correction mode was specified in a script file. The legal values are On and Off.


E_RW_RSINVGEOMETRYSAMPLING

An invalid geometry sampling type was specified in a script file. The legal values are PointCloud, Solid and WireFrame.


E_RW_RSINVHINT

An invalid clump hint was specified in a script file. The legal values are NULL, Container, HS and Editable.


E_RW_RSINVLIGHTSAMPLING

An invalid light sampling type was specified in a script file. The legal values are Facet and Vertex.


E_RW_RSINVTEXTUREMODE

An invalid texture mode was specified in a script file. The legal values are NULL, Lit and Foreshorten.


E_RW_RSINVTRACESTATE

A invalid tracing state was specified in a script file. The legal values are On and Off.


E_RW_RSNOHINTS

No hints were specified as arguments for a scripting command that adds, removes, or sets hints. The legal values are NULL, Container, HS and Editable.


E_RW_RSNOTEXTUREMODES

No texture modes were specified as arguments for a scripting command that adds, removes or sets texture modes. The legal values are Null, Lit and Foreshorten.


E_RW_RSPARSE

An invalid keyword was found in a script file.


E_RW_RSREAD

An I/O error occurred while reading from a script file.


E_RW_SHPPATH

The shape path is too long (greater than 1024 characters).


E_RW_TEXTURENOTFOUND

The specified texture was not found.


E_RW_USER

A call to RwSetUserError() generated this error.


E_RW_WRITE

An error occurred while writing to an output stream.


E_RW_WSWRITE

An error occurred while writing a script to an output stream.


E_RW_ZEROVEC

A zero length vector was specified.


Error Identifiers and Codes

Errors Sorted Alphabetically By Identifier

Errors Sorted Numerically By Code


Errors Sorted Alphabetically By Identifier

Identifier	Numeric Code
E_RW_BADOPEN	14
E_RW_COMPLEXPOLYGON	41
E_RW_DEFSCENE	25
E_RW_DEGEN	7
E_RW_DEGENPOLYGON	40
E_RW_INTERNAL	70
E_RW_INVAXISALIGNMENT	49
E_RW_INVCAMERAPROJECTION	44
E_RW_INVCOP	2
E_RW_INVDEVICE	18
E_RW_INVDEVICEACTION	64
E_RW_INVDEVICEINFO	63
E_RW_INVFRAME	20
E_RW_INVFRAMESTEP	21
E_RW_INVGEOMETRYSAMPLING	26
E_RW_INVHINT	47
E_RW_INVIMAGEFILE	69
E_RW_INVLIGHT	8
E_RW_INVLIGHTSAMPLING	28
E_RW_INVMATERIAL	19
E_RW_INVOPENOPTION	65
E_RW_INVPROTOTYPE	37
E_RW_INVRASTEROPTIONS	60
E_RW_INVRASTERSIZE	62
E_RW_INVSEARCHMODE	46
E_RW_INVSPP	16
E_RW_INVSPT	17
E_RW_INVSTATE	45
E_RW_INVSYSTEMINFO	55
E_RW_INVTEXTUREDITHERMODE	61
E_RW_INVTEXTUREHEIGHT	23
E_RW_INVTEXTUREMODE	56
E_RW_INVTEXTURENAME	43
E_RW_INVTEXTUREWIDTH	22
E_RW_INVUSERDRAWALIGN	51
E_RW_INVUSERDRAWTYPE	50
E_RW_INVVERTEXINDEX	24
E_RW_NESTEDMODEL	32
E_RW_NESTEDPROTOTYPE	35
E_RW_NOCLUMP	38
E_RW_NOCLUMPBUILT	39
E_RW_NOERROR	0
E_RW_NOFILE	13
E_RW_NOMATCHBEGIN	33
E_RW_NOMATCHEND	34
E_RW_NOMEM	3
E_RW_NOMODELBEGIN	36
E_RW_NOPROTOTYPEFOUND	30
E_RW_NOTROOT	15
E_RW_NULLP	1
E_RW_RANGE	11
E_RW_RASTERINUSE	66
E_RW_READ	10
E_RW_RSINVAXISALIGNMENT	54
E_RW_RSINVDITHERMODE	67
E_RW_RSINVGAMMAMODE	68
E_RW_RSINVGEOMETRYSAMPLING	27
E_RW_RSINVHINT	53
E_RW_RSINVLIGHTSAMPLING	29
E_RW_RSINVTEXTUREMODE	57
E_RW_RSINVTRACESTATE	52
E_RW_RSNOHINTS	58
E_RW_RSNOTEXTUREMODES	59
E_RW_RSPARSE	4
E_RW_RSREAD	5
E_RW_SHPPATH	9
E_RW_TEXTURENOTFOUND	42
E_RW_USER	48
E_RW_WRITE	12
E_RW_WSWRITE	6
E_RW_ZEROVEC	31


Errors Sorted Numerically By Code

Numeric Code	Identifier
0	E_RW_NOERROR
1	E_RW_NULLP
2	E_RW_INVCOP
3	E_RW_NOMEM
4	E_RW_RSPARSE
5	E_RW_RSREAD
6	E_RW_WSWRITE
7	E_RW_DEGEN
8	E_RW_INVLIGHT
9	E_RW_SHPPATH
10	E_RW_READ
11	E_RW_RANGE
12	E_RW_WRITE
13	E_RW_NOFILE
14	E_RW_BADOPEN
15	E_RW_NOTROOT
16	E_RW_INVSPP
17	E_RW_INVSPT
18	E_RW_INVDEVICE
19	E_RW_INVMATERIAL
20	E_RW_INVFRAME
21	E_RW_INVFRAMESTEP
22	E_RW_INVTEXTUREWIDTH
23	E_RW_INVTEXTUREHEIGHT
24	E_RW_INVVERTEXINDEX
25	E_RW_DEFSCENE
26	E_RW_INVGEOMETRYSAMPLING
27	E_RW_RSINVEGEOMETRYSAMPLING
28	E_RW_INVLIGHTSAMPLING
29	E_RW_RSINVLIGHTSAMPLING
30	E_RW_NOPROTOTYPEFOUND
31	E_RW_ZEROVEC
32	E_RW_NESTEDMODEL
33	E_RW_NOMATCHBEGIN
34	E_RW_NOMATCHEND
35	E_RW_NESTEDPROTOTYPE
36	E_RW_NOMODELBEGIN
37	E_RW_INVPROTOTYPE
38	E_RW_NOCLUMP
39	E_RW_NOCLUMPBUILT
40	E_RW_DEGENPOLYGON
41	E_RW_COMPLEXPOLYGON
42	E_RW_TEXTURENOTFOUND
43	E_RW_INVTEXTURENAME
44	E_RW_INVCAMERAPROJECTION
45	E_RW_INVSTATE
46	E_RW_INVSEARCHMODE
47	E_RW_INVHINT
48	E_RW_USER
49	E_RW_INVAXISALIGNMENT
50	E_RW_INVUSERDRAWTYPE
51	E_RW_INVUSERDRAWALIGN
52	E_RW_RSINVTRACESTATE
53	E_RW_RSINVHINT
54	E_RW_RSINVAXISALIGNMENT
55	E_RW_INVSYSTEMINFO
56	E_RW_INVTEXTUREMODE
57	E_RW_RSINVTEXTUREMODE
58	E_RW_RSNOHINTS
59	E_RW_RSNOTEXTUREMODES
60	E_RW_INVRASTEROPTIONS
61	E_RW_INVTEXTUREDITHERMODE
62	E_RW_INVRASTERSIZE
63	E_RW_INVDEVICEINFO
64	E_RW_INVDEVICEACTION
65	E_RW_INVOPENOPTION
66	E_RW_RASTERINUSE
67	E_RW_RSINVDITHERMODE
68	E_RW_RSINVGAMMAMODE
69	E_RW_INVIMAGEFILE
70	E_RW_INTERNAL


The Texture File Formats

Textures in RenderWare V1.3 are 128 x 128, 8 or 16 bit deep bitmaps. However, RenderWare can read bitmaps of sizes other than 128 x 128 pixels and depths other than 8 or 16 bits. Such bitmaps are converted automatically to RenderWare's internal raster format. Furthermore, RenderWare can read textures from MS Windows and OS/2 bitmap (.bmp) files in addition to RenderWare's own texture file format (.ras).

In the case of RenderWare's own texture file format (.ras) the following are supported:

•	Bitmaps of any width and height.

•	Bitmaps with depths of 1, 8, 24 or 32 bits.

•	Uncompressed or run length encoded bitmaps.

For MS Windows and OS/2 bitmap (.bmp) files the following are supported:

•	Bitmaps of any width and height.

•	Bitmaps with depths of 1, 4, 8 or 24 bits.

•	Uncompressed or run length encoded bitmaps.

Bitmaps of sizes other than 128 x 128 and depths other than 8 bits will be filtered and quantized to RenderWare's internal texture format. It is important to note the following when using textures of sizes and depths different from the internal format:

•	Files that contain bitmaps which are already in the internal format, i.e., 128 x 128 by 8 bits deep will load more quickly. However, such textures are likely to be less visually pleasing than larger, deeper textures which are filtered and quantized to size.

•	Texture "movies" (multi-frame textures) must be stored as bitmaps which are 128 pixels wide and a whole multiple of 128 pixels high.

RenderWare's own texture file format is based on the format used for Sun Microsystems's rasterfiles. RenderWare will read any legal Sun rasterfile. For a description of Sun's rasterfile format see:

[1] Rasterfile (5) in Sun Microsystems, Sun OS 4.0 Programmer's Manual, 1990

[2] Pat McGee, Format for byte encoded rasterfiles in Sun-Spots Digest, Volume 6, Issue 84.

[3] David. C. Kay and John R. Levine, Graphics File Formats, Windcrest/ McGraw-Hill, 1992.

For a description of MS Windows bitmap (.bmp) file format see:

[4] Bitmap-File Formats, Microsoft Windows 3.1 Programmer's Reference Volume 4: Resources, Microsoft, 1987-1992. Part Number: 30211.

[5] David. C. Kay and John R. Levine, Graphics File Formats, Windcrest/ McGraw-Hill, 1992.

This appendix details the various default values found in the RenderWare library. This includes the default values of global library parameters and the default values of RenderWare objects when first created.


Cameras

Camera Object Defaults

Attribute	Default
Position	[CREAL(0.0), CREAL(0.0), CREAL(0.0)] in world coordinates
Look At	[CREAL(0.0), CREAL(0.0), CREAL(-1.0)]
Look Right	[CREAL(1.0), CREAL(0.0), CREAL(0.0)]
Look Up	[CREAL(0.0), CREAL(1.0), CREAL(0.0)]
Viewport	Position = [0, 0] Size = [0, 0]
Viewwindow	[CREAL(1.0), CREAL(1.0)]
View Offset	[CREAL(0.0), CREAL(0.0)]
Near Clipping	CREAL(0.05)
Projection	rwPERSPECTIVE
Back Color	[CREAL(0.0), CREAL(0.0), CREAL(0.0)] (Black)
Backdrop	NULL
Backdrop Offset	[0, 0]
Backdrop Viewport Rectangle	Position = [0, 0] Size = [0, 0]
Data	NULL
Image	Device dependent


Clumps

Clump Object Defaults

Attribute	Default
Origin	[CREAL(0.0), CREAL(0.0), CREAL(0.0)] in world coordinates
Matrix	Identity
Joint Matrix	Identity
LTM	Identity
Owner	The default scene (as returned by RwDefaultScene())
Parent	NULL
Root	The clump itself
Data	NULL
First Child	NULL
Next Clump	NULL
Number of Vertices	Defined at creation time
Number of Polygons	Defined at creation time
Number of Children	0
Number of UserDraws	0
Tag	0
Hints	rwHS
Axis Alignment	rwNOAXISALIGNMENT
State	rwON
Bounding Box	Computed
Viewport Rectangle	Computed


Library Defaults - Debugging
Debugging

Debugging Defaults

Attribute	Default
Stream	stderr on Unix "\rw.log" on DOS and MS Windows stderr on the Macintosh
Assertion State	rwENABLE
Message State	rwENABLE
Script State	rwDISABLE
Severity	rwINFORM


Device Information

Device Information Defaults

Attribute	Default
rwRENDERDEPTH	8 or 16. Actual value is device specific
rwINDEXEDRENDERING	Non-zero if the current render depth is 8 Zero if the current render depth is 16
rwPALETTEBASED	Non-zero if the output device is palette based Zero if the output device is not palette based
rwINDEXEDCOLORMODEL	rwRAMPBASED for indexed rendering Undefined for direct rendering
rwNUMCOLRAMPS	10 for indexed rendering Undefined for direct rendering
rwCOLRAMPSIZE	Device dependent
rwPALETTE	Device dependent
rwPALETTESIZE	Device dependent
rwFIRSTPALETTEENTRY	Device dependent
rwLASTPALETTEENTRY	Device dependent


Errors

Error Status Defaults

Attribute	Default
Status	E_RW_NOERROR
Internal Error	Undefined


Library Global Defaults

Library Global Defaults

Attribute	Default
Device	Defined at creation time If NULL is passed as the device name to RwOpen() or RwOpenExt() the value of the environment variable "RWDEVICE" on DOS, MS Windows and Unix
Current Camera	NULL
Shape Path	Value of environment variable "RWSHAPEPATH" or "" if the environment variable is not set on DOS, MS Windows and Unix "" on the Macintosh
Scenes	One. The default scene (as returned by RwDefaultScene())
Lights	None
Clumps	None
Cameras	None
Textures	None
Texture Dictionaries	One on the Texture Dictionary stack.
Rasters	None
Splines	None
UserDraws	None
Matrices	One on the Scratch matrix stack, one on the Current Matrix stack and one on the Joint Matrix stack
Materials	One on the Material stack
Texture Dithering	rwAUTODITHER
Texture Gamma Correction	rwON


Lights

Light Object Defaults

Attribute	Default
Type	Defined at creation time
Brightness	Defined at creation time
Position	Defined at creation time for point and conical lights
Vector	Defined at creation time for directional lights. [CREAL(0.0), CREAL(-1.0), CREAL(0.0)] for conical lights
Owner	The default scene (as returned by RwDefaultScene())
Cone Angle	CREAL(30.0) for conical lights CREAL(180.0) for point lights
State	rwON
Data	NULL


Materials

Material Object Defaults

Attribute	Default
Ambient	CREAL(0.0)
Diffuse	CREAL(0.0)
Specular	CREAL(0.0)
Light Sampling	rwFACET
Geometry Sampling	rwSOLID
Color	[CREAL(0.0), CREAL(0.0), CREAL(0.0)] (Black)
Opacity	CREAL(1.0)
Texture	NULL
Texture Modes	rwLIT


Library Defaults - Matrices
Matrices

Matrix Object Defaults

Attribute	Default
Elements	Identity


Polygons

Polygon Object Defaults

Attribute	Default
Material	Defined at creation time by the Current Material (as returned by RwCurrentMaterial())
Vertices	Defined at creation time
Center	Computed
Normal	Computed
Number of Sides	Defined at creation time
Owner	Defined at creation time
UV	[CREAL(0.5), CREAL(0.5)] for all vertices
Tag	0
Data	NULL


Rasters

Raster Object Defaults

Attribute	Default
Width	Defined at creation time (either explicitly or by source image)
Height	Defined at creation time (either explicitly or by source image)
Depth	Equal to the current RenderWare render depth
Stride	Computed from the width
Pixel Pointer	Defined at creation time
Pixel Values	Undefined if created with RwCreateRaster() Derived from the source image if created by RwBitmapRaster(), RwReadRaster() or RwReadMaskRaster()
Data	NULL


Scenes

Scene Object Defaults

Attribute	Default
Number of Clumps	0
Number of Lights	0
Data	NULL


Splines

Spline Object Defaults

Attribute	Default
Type	Defined at creation time
Points	Defined at creation time
Number of Points	Defined at creation time
Data	NULL


System Information

System Information Defaults

Attribute	Default
rwVERSIONSTRING	Library dependent
rwVERSIONMAJOR	Library dependent
rwVERSIONMINOR	Library dependent
rwVERSIONRELEASE	Library dependent
rwFIXEDPOINTLIB	Non-zero for fixed point library Zero for floating point library
rwDEBUGGINGLIB	Non-zero for debugging library Zero for production library


Textures

Texture Object Defaults

Attribute	Default
Name	Computed for named textures NULL for other textures
Frame	0
Frame Step	+1
Number of Frames	Defined at creation time
Raster	Defined at creation time
Mask	Unmasked
Dithering	Defined by the global dithering mode for a texture read by RwReadTexture() or RwReadNamedTexture() Defined by the specified raster options for a texture created from a raster created by RwReadRaster() or RwBitmapRaster().
Gamma Correction	Defined by the global gamma correction mode for a texture read by RwReadTexture() or RwReadNamedTexture() Defined by the specified raster options for a texture created from a raster created by RwReadRaster() or RwBitmapRaster()
Data	NULL


Texture Dictionaries

Texture Dictionary Defaults

Attribute	Default
Textures	None
Search Mode	rwGLOBAL


UserDraw

UserDraw Object Defaults

Attribute	Default
Alignment	Defined at creation time
Call-back	Defined at creation time
Offset	Defined at creation time
Size	Defined at creation time
Type	Defined at creation time
Owner	NULL
Data	NULL
Vertex Index	Undefined
Parent Alignment	Undefined


Vertices

Vertex Defaults

Attribute	Default
Coordinates	Defined at creation time
Texture coordinates	[CREAL(0.5), CREAL(0.5)]
Normal	Computed
Viewport Position	Computed


This code is only valid when using a floating-point RenderWare library. The macro functions necessary for correct fixed-point operation have been omitted for clarity.


RwCreateMatrix() can fail and so its return value should be checked. However, for the sake of clarity this check has been omitted.


The local transformation matrix (LTM) transforms local space into world space. Thus, to find the world space coordinates of a clump's vertex, transform the position of the vertex by the LTM.


RwForAllClumpsInHierarchyInt(), RwForAllClumpsInHierarchyLong(), RwForAllClumpsInHiearchyReal() and RwForAllClumpsInHierarchyPointer().


RwFindClumpInt(), RwFindClumpLong(), RwFindClumpReal(), RwFindClumpPointer().


Certain versions of RenderWare have platform specific include files. These include files are not automatically included by rwlib.h. See MS Windows 3.1 Specific Information for more information.


Although these code fragments are taken from an MS Windows 3.1 application the modifications necessary for other platforms are trivial.


Subsequent errors are most often the direct result of the first error. Such error cascades are not significant. The first error encountered is the source of the problem.


Fixed-point compatibility macros omitted for clarity.


Error checking omitted for clarity.


The number of ramps can be found with RwGetDeviceInfo().


RenderWare achieves greater performance when the depth of the output device is equal to the current render depth. Therefore, RenderWare will use memory device contexts as camera image buffers whenever possible.


The color table of the device independent bitmap returned by RwGetCameraImage() uses palette indices (DIB_PAL_COLORS) if the output device is palette based and RGB colors (DIB_RGB_COLORS) otherwise.


The entries in use by RenderWare can be found by RwGetDeviceInfo() with the information types rwFIRSTPALETTEENTRY and rwLASTPALETTEENTRY.


In Version 1.3 of RenderWare, param is ignored. Thus, it is legal to continue to pass the application's instance handle. However, to ensure compatibility with future versions of RenderWare it is recommended that applications should be modified to pass param as NULL.


In RenderWare V1.3, param is ignored. Thus, it is legal to continue to pass the application's instance handle. However, to ensure compatibility with future versions of RenderWare it is recommended that applications should be modified to pass param as NULL.


Textures are, in fact, based on RenderWare's own bitmap object type, RwRaster. The depth of RwRaster objects is always equal to the current RenderWare rendering depth. Therefore, textures will be either 8 or 16 bits deep, the actual depth being decided at run-time.


Currently RenderWare does not support any 16 bit texture file formats. Therefore, when rendering at 16 bits all texture files undergo color conversion.


Function Reference

Function Index by Category

Function Index Alphabetically


Function Index by Category

Camera Functions

Clump Functions

Debug Functions

Error Functions

Light Functions

Material Functions

Matrix Functions

Object Builder Functions

Point / Vector Functions

Polygon Functions

Raster Functions

Scene Functions

Shape Functions

Spline Functions

Texture Functions

User Draw Functions

Other Functions


Camera Functions

RwBeginCameraUpdate()

RwClearCameraViewport()

RwCreateCamera()

RwDamageCameraViewport()

RwDestroyCamera()

RwDuplicateCamera()

RwEndCameraUpdate()

RwGetCameraBackColor()

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwGetCameraData()

RwGetCameraImage()

RwGetCameraLookAt()

RwGetCameraLookRight()

RwGetCameraLookUp()

RwGetCameraNearClipping()

RwGetCameraPosition()

RwGetCameraProjection()

RwGetCameraViewOffset()

RwGetCameraViewport()

RwGetCameraViewportRaster()

RwGetCameraViewwindow()

RwInvalidateCameraViewport()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraBackColor()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropOffset()

RwSetCameraBackdropViewportRect()

RwSetCameraData()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwSetCameraNearClipping()

RwSetCameraPosition()

RwSetCameraProjection()

RwSetCameraViewOffset()

RwSetCameraViewport()

RwSetCameraViewwindow()

RwShowCameraImage()

RwTiltCamera()

RwTransformCamera()

RwTransformCameraOrientation()

RwUndamageCameraViewport()

RwVCMoveCamera()

RwWCMoveCamera()


Clump Functions

RwAddChildToClump()

RwAddHintToClump()

RwAddPolygonsToClump()

RwAddPolygonToClump()

RwAddVertexToClump

RwCalculateClumpVertexNormal()

RwClumpDistance()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwCubicTexturizeClump()

RwDestroyClump()

RwDuplicateClump()

RwEnvMapClump()

RwFindClump()

RwFindClumpInt()

RwFindClumpLong()

RwFindClumpPointer()

RwFindClumpReal()

RwFindTaggedClump()

RwForAllClumpsInHierarchy()

RwForAllClumpsInHierarchyInt()

RwForAllClumpsInHierarchyLong()

RwForAllClumpsInHierarchyPointer()

RwForAllClumpsInHierarchyReal()

RwForAllPolygonsInClump()

RwForAllPolygonsInClumpInt()

RwForAllPolygonsInClumpLong()

RwForAllPolygonsInClumpPointer()

RwForAllPolygonsInClumpReal()

RwGetClumpAxisAlignment()

RwGetClumpBBox()

RwGetClumpData()

RwGetClumpHints()

RwGetClumpJointMatrix()

RwGetClumpLTM()

RwGetClumpMatrix()

RwGetClumpNumChildren()

RwGetClumpNumPolygons()

RwGetClumpNumVertices()

RwGetClumpOrigin()

RwGetClumpOwner()

RwGetClumpParent()

RwGetClumpRoot()

RwGetClumpState()

RwGetClumpTag()

RwGetClumpVertex()

RwGetClumpVertexNormal()

RwGetClumpVertexUV()

RwGetClumpVertexViewportPosition()

RwGetClumpViewportRect()

RwGetFirstChildClump()

RwGetNextClump()

RwNormalizeClump()

RwPickClump()

RwRemoveChildFromClump()

RwRemoveHintFromClump()

RwRenderClump()

RwSetClumpAxisAlignment()

RwSetClumpData()

RwSetClumpHints()

RwSetClumpState()

RwSetClumpTag()

RwSetClumpVertex()

RwSetClumpVertexNormal()

RwSetClumpVertexUV()

RwSetClumpVertices()

RwSphericalTexturizeClump()

RwTransformClump()

RwTransformClumpJoint()


Error Functions

RwGetError()

RwGetInternalError()

RwSetUserError()


Light Functions

RwCreateLight()

RwDestroyLight()

RwDuplicateLight()

RwGetLightBrightness()

RwGetLightConeAngle()

RwGetLightData()

RwGetLightOwner()

RwGetLightPosition()

RwGetLightState()

RwGetLightType()

RwGetLightVector()

RwSetLightBrightness()

RwSetLightConeAngle()

RwSetLightData()

RwSetLightPosition()

RwSetLightState()

RwSetLightVector()

RwTransformLight()


Debug Functions

RwCloseDebugStream()

RwGetDebugAssertionState()

RwGetDebugMessageState()

RwGetDebugScriptState()

RwGetDebugSeverity()

RwOpenDebugStream()

RwSetDebugAssertionState()

RwSetDebugMessageState()

RwSetDebugOutputState()

RwSetDebugScriptState()

RwSetDebugSeverity()

RwSetDebugStream()


Material Functions

RwAddTextureModeToMaterial()

RwCopyMaterial()

RwCreateMaterial()

RwCurrentMaterial()

RwDestroyMaterial()

RwDuplicateMaterial()

RwGetMaterialAmbient()

RwGetMaterialColor()

RwGetMaterialDiffuse()

RwGetMaterialGeometrySampling()

RwGetMaterialLightSampling()

RwGetMaterialOpacity()

RwGetMaterialSpecular()

RwGetMaterialTexture()

RwGetMaterialTextureModes()

RwPopCurrentMaterial()

RwPushCurrentMaterial()

RwRemoveTextureModeFromMaterial()

RwSetMaterialAmbient()

RwSetMaterialColor()

RwSetMaterialColorStruct()

RwSetMaterialDiffuse()

RwSetMaterialGeometrySampling()

RwSetMaterialLightSampling()

RwSetMaterialOpacity()

RwSetMaterialSpecular()

RwSetMaterialSurface()

RwSetMaterialTexture()

RwSetMaterialTextureModes()


Matrix Functions

RwCopyMatrix()

RwCreateMatrix()

RwDestroyMatrix()

RwDuplicateMatrix()

RwGetMatrixElement()

RwGetMatrixElements()

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwPopScratchMatrix()

RwPushScratchMatrix()

RwQueryRotateMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwScratchMatrix()

RwSetMatrixElement()

RwSetMatrixElements()

RwTransformMatrix()

RwTranslateMatrix()


Object Builder Functions

RwAddHint()

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCone()

RwCylinder()

RwDisc()

RwHemisphere()

RwIdentityCTM()

RwIdentityJointTM()

RwInclude()

RwIncludeGeometry()

RwJointTransformBegin()

RwJointTransformEnd()

RwMaterialBegin()

RwMaterialEnd()

RwModelBegin()

RwModelEnd()

RwPolygon()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwProtoInstance()

RwProtoInstanceGeometry()

RwQuad()

RwQuadExt()

RwRemoveHint()

RwRotateCTM()

RwRotateJointTM()

RwScaleCTM()

RwSetAxisAlignment()

RwSetHints()

RwSetSurface()

RwSetSurfaceAmbient()

RwSetSurfaceColor()

RwSetSurfaceDiffuse()

RwSetSurfaceGeometrySampling()

RwSetSurfaceLightSampling()

RwSetSurfaceOpacity()

RwSetSurfaceSpecular()

RwSetSurfaceTexture()

RwSetSurfaceTextureExt()

RwSetSurfaceTextureModes()

RwSetTag()

RwSphere()

RwTransformBegin()

RwTransformCTM()

RwTransformEnd()

RwTransformJointTM()

RwTranslateCTM()

RwTriangle()

RwTriangleExt()

RwVertex()

RwVertexExt()


Point / Vector Functions

RwAddVector()

RwCrossProduct()

RwDotProduct()

RwNormalize()

RwScaleVector()

RwSubtractVector()

RwTransformPoint()

RwTransformVector()


Polygon Functions

RwAddTextureModeToPolygon

RwDestroyPolygon()

RwFindTaggedPolygon()

RwGetPolygonAmbient()

RwGetPolygonCenter()

RwGetPolygonColor()

RwGetPolygonData()

RwGetPolygonDiffuse()

RwGetPolygonGeometrySampling()

RwGetPolygonLightSampling()

RwGetPolygonMaterial()

RwGetPolygonNormal()

RwGetPolygonNumSides()

RwGetPolygonOpacity()

RwGetPolygonOwner()

RwGetPolygonSpecular()

RwGetPolygonTag()

RwGetPolygonTexture()

RwGetPolygonTextureModes()

RwGetPolygonUV()

RwGetPolygonVertices()

RwRemoveTextureModeFromPolygon()

RwReversePolygonFace()

RwSetPolygonAmbient()

RwSetPolygonColor()

RwSetPolygonColorStruct()

RwSetPolygonData()

RwSetPolygonDiffuse()

RwSetPolygonGeometrySampling()

RwSetPolygonLightSampling()

RwSetPolygonMaterial()

RwSetPolygonOpacity()

RwSetPolygonSpecular()

RwSetPolygonSurface()

RwSetPolygonTag()

RwSetPolygonTexture()

RwSetPolygonTextureModes()

RwSetPolygonUV()


Raster Functions

RwBitmapRaster()

RwCreateRaster()

RwDestroyRaster()

RwDuplicateRaster()

RwGetRasterData()

RwGetRasterDepth()

RwGetRasterHeight()

RwGetRasterPixels()

RwGetRasterStride()

RwGetRasterWidth()

RwReadMaskRaster()

RwReadRaster()

RwSetRasterData()


Scene Functions

RwAddClumpToScene()

RwAddLightToScene()

RwCreateScene()

RwDefaultScene()

RwDestroyScene()

RwForAllClumpsInScene()

RwForAllClumpsInSceneInt()

RwForAllClumpsInSceneLong()

RwForAllClumpsInScenePointer()

RwForAllClumpsInSceneReal()

RwForAllLightsInScene()

RwForAllLightsInSceneInt()

RwForAllLightsInSceneLong()

RwForAllLightsInScenePointer()

RwForAllLightsInSceneReal()

RwGetSceneData()

RwGetSceneNumClumps()

RwGetSceneNumLights()

RwPickScene()

RwRemoveClumpFromScene()

RwRemoveLightFromScene()

RwRenderScene()

RwSetSceneData()


Shape Functions

RwGetShapePath()

RwReadShape()

RwSetShapePath()

RwWriteShape()


Spline Functions

RwCreateSpline()

RwDestroySpline()

RwDuplicateSpline()

RwGetSplineData()

RwGetSplineNumPoints()

RwGetSplinePoint()

RwSetSplineData()

RwSetSplinePoint()

RwSplinePoint()

RwSplineTransform()


Texture Functions

RwAddTextureModeToSurface()

RwCreateTexture()

RwDestroyTexture()

RwFindNamedTexture()

RwForAllNamedTextures()

RwForAllNamedTexturesInt()

RwForAllNamedTexturesLong()

RwForAllNamedTexturesPointer()

RwForAllNamedTexturesReal()

RwGetNamedTexture()

RwGetNumNamedTextures()

RwGetTextureData()

RwGetTextureDictSearchMode()

RwGetTextureDithering()

RwGetTextureFrame()

RwGetTextureFrameStep()

RwGetTextureGammaCorrection()

RwGetTextureName()

RwGetTextureNumFrames()

RwGetTextureRaster()

RwMaskTexture()

RwReadNamedTexture()

RwReadTexture()

RwRemoveTextureModeFromSurface()

RwSetTextureData()

RwSetTextureDictSearchMode()

RwSetTextureDithering()

RwSetTextureFrame()

RwSetTextureFrameStep()

RwSetTextureGammaCorrection()

RwSetTextureRaster()

RwTextureDictBegin()

RwTextureDictEnd()

RwTextureNextFrame()


User Draw Functions

RwAddUserDrawToClump()

RwCreateUserDraw()

RwDestroyUserDraw()

RwDuplicateUserDraw()

RwForAllUserDrawsInClump()

RwForAllUserDrawsInClumpInt()

RwForAllUserDrawsInClumpLong()

RwForAllUserDrawsInClumpPointer()

RwForAllUserDrawsInClumpReal()

RwGetClumpNumUserDraws()

RwGetUserDrawAlignment()

RwGetUserDrawCallback()

RwGetUserDrawData()

RwGetUserDrawOffset()

RwGetUserDrawOwner()

RwGetUserDrawParentAlignment()

RwGetUserDrawSize()

RwGetUserDrawType()

RwGetUserDrawVertexIndex()

RwRemoveUserDrawFromClump()

RwSetUserDrawAlignment()

RwSetUserDrawCallback()

RwSetUserDrawData()

RwSetUserDrawOffset()

RwSetUserDrawParentAlignment()

RwSetUserDrawSize()

RwSetUserDrawType()

RwSetUserDrawVertexIndex()


Other Functions

RwClose()

RwDeviceControl()

RwGetDeviceInfo()

RwGetSystemInfo()

RwOpen()

RwOpenExt()


Function Index Alphabetically

RwAddChildToClump()

RwAddClumpToScene()

RwAddHint()

RwAddHintToClump()

RwAddLightToScene()

RwAddPolygonsToClump()

RwAddPolygonToClump()

RwAddTextureModeToMaterial()

RwAddTextureModeToPolygon()

RwAddTextureModeToSurface()

RwAddUserDrawToClump()

RwAddVector()

RwAddVertexToClump()

RwBeginCameraUpdate()

RwBitmapRaster()

RwBlock()

RwCalculateClumpVertexNormal()

RwClearCameraViewport()

RwClose()

RwCloseDebugStream()

RwClumpBegin()

RwClumpDistance()

RwClumpEnd()

RwCone()

RwCopyMaterial()

RwCopyMatrix()

RwCreateCamera()

RwCreateClump()

RwCreateDecal()

RwCreateLight()

RwCreateMaterial()

RwCreateMatrix()

RwCreateRaster()

RwCreateScene()

RwCreateSpline()

RwCreateSprite()

RwCreateTexture()

RwCreateUserDraw()

RwCrossProduct()

RwCubicTexturizeClump()

RwCurrentMaterial()

RwCylinder()

RwDamageCameraViewport()

RwDefaultScene()

RwDestroyCamera()

RwDestroyClump()

RwDestroyLight()

RwDestroyMaterial()

RwDestroyMatrix()

RwDestroyPolygon()

RwDestroyRaster()

RwDestroyScene()

RwDestroySpline()

RwDestroyTexture()

RwDestroyUserDraw()

RwDeviceControl()

RwDisc()

RwDotProduct()

RwDuplicateCamera()

RwDuplicateClump()

RwDuplicateLight()

RwDuplicateMaterial()

RwDuplicateMatrix()

RwDuplicateRaster()

RwDuplicateSpline()

RwDuplicateUserDraw()

RwEndCameraUpdate()

RwEnvMapClump()

RwFindClump()

RwFindNamedTexture()

RwFindTaggedClump()

RwFindTaggedPolygon()

RwForAllClumpsInHierarchy()

RwForAllClumpsInScene()

RwForAllLightsInScene()

RwForAllNamedTextures()

RwForAllPolygonsInClump()

RwForAllUserDrawsInClump()

RwGetCameraBackColor()

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwGetCameraData()

RwGetCameraImage()

RwGetCameraLookAt()

RwGetCameraLookRight()

RwGetCameraLookUp()

RwGetCameraNearClipping()

RwGetCameraPosition()

RwGetCameraProjection()

RwGetCameraViewOffset()

RwGetCameraViewport()

RwGetCameraViewportRaster()

RwGetCameraViewwindow()

RwGetClumpAxisAlignment()

RwGetClumpBBox()

RwGetClumpData()

RwGetClumpHints()

RwGetClumpJointMatrix()

RwGetClumpLTM()

RwGetClumpMatrix()

RwGetClumpNumChildren()

RwGetClumpNumPolygons()

RwGetClumpNumUserDraws()

RwGetClumpNumVertices()

RwGetClumpOrigin()

RwGetClumpOwner()

RwGetClumpParent()

RwGetClumpRoot()

RwGetClumpState()

RwGetClumpTag()

RwGetClumpVertex()

RwGetClumpVertexNormal()

RwGetClumpVertexUV()

RwGetClumpVertexViewportPosition()

RwGetClumpViewportRect()

RwGetDebugAssertionState()

RwGetDebugMessageState()

RwGetDebugScriptState()

RwGetDebugSeverity()

RwGetDeviceInfo()

RwGetError()

RwGetFirstChildClump()

RwGetInternalError()

RwGetLightBrightness()

RwGetLightConeAngle()

RwGetLightData()

RwGetLightOwner()

RwGetLightPosition()

RwGetLightState()

RwGetLightType()

RwGetLightVector()

RwGetMaterialAmbient()

RwGetMaterialColor()

RwGetMaterialDiffuse()

RwGetMaterialGeometrySampling()

RwGetMaterialLightSampling()

RwGetMaterialOpacity()

RwGetMaterialSpecular()

RwGetMaterialTexture()

RwGetMaterialTextureModes()

RwGetMatrixElement()

RwGetMatrixElements()

RwGetNamedTexture()

RwGetNextClump()

RwGetNumNamedTextures()

RwGetPolygonAmbient()

RwGetPolygonCenter()

RwGetPolygonColor()

RwGetPolygonData()

RwGetPolygonDiffuse()

RwGetPolygonGeometrySampling()

RwGetPolygonLightSampling()

RwGetPolygonMaterial()

RwGetPolygonNormal()

RwGetPolygonNumSides()

RwGetPolygonOpacity()

RwGetPolygonOwner()

RwGetPolygonSpecular()

RwGetPolygonTag()

RwGetPolygonTexture()

RwGetPolygonTextureModes()

RwGetPolygonUV()

RwGetPolygonVertices()

RwGetRasterData()

RwGetRasterDepth()

RwGetRasterHeight()

RwGetRasterPixels()

RwGetRasterStride()

RwGetRasterWidth()

RwGetSceneData()

RwGetSceneNumClumps()

RwGetSceneNumLights()

RwGetShapePath()

RwGetSplineData()

RwGetSplineNumPoints()

RwGetSplinePoint()

RwGetSystemInfo()

RwGetTextureData()

RwGetTextureDictSearchMode()

RwGetTextureDithering()

RwGetTextureFrame()

RwGetTextureFrameStep()

RwGetTextureGammaCorrection()

RwGetTextureName()

RwGetTextureNumFrames()

RwGetTextureRaster()

RwGetUserDrawAlignment()

RwGetUserDrawCallback()

RwGetUserDrawData()

RwGetUserDrawOffset()

RwGetUserDrawOwner()

RwGetUserDrawParentAlignment()

RwGetUserDrawSize()

RwGetUserDrawType()

RwGetUserDrawVertexIndex()

RwHemisphere()

RwIdentityCTM()

RwIdentityJointTM()

RwIdentityMatrix()

RwInclude()

RwIncludeGeometry()

RwInvalidateCameraViewport()

RwInvertMatrix()

RwJointTransformBegin()

RwJointTransformEnd()

RwMaskTexture()

RwMaterialBegin()

RwMaterialEnd()

RwModelBegin()

RwModelEnd()

RwMultiplyMatrix()

RwNormalize()

RwNormalizeClump()

RwOpen()

RwOpenDebugStream()

RwOpenExt()

RwOrthoNormalizeMatrix()

RwPanCamera()

RwPickClump()

RwPickScene()

RwPointCamera()

RwPolygon()

RwPolygonExt()

RwPopCurrentMaterial()

RwPopScratchMatrix()

RwProtoBegin()

RwProtoEnd()

RwProtoInstance()

RwProtoInstanceGeometry()

RwPushCurrentMaterial()

RwPushScratchMatrix()

RwQuad()

RwQuadExt()

RwQueryRotateMatrix()

RwReadMaskRaster()

RwReadNamedTexture()

RwReadRaster()

RwReadShape()

RwReadTexture()

RwRemoveChildFromClump()

RwRemoveClumpFromScene()

RwRemoveHint()

RwRemoveHintFromClump()

RwRemoveLightFromScene()

RwRemoveTextureModeFromMaterial()

RwRemoveTextureModeFromPolygon()

RwRemoveTextureModeFromSurface()

RwRemoveUserDrawFromClump()

RwRenderClump()

RwRenderScene()

RwResetCamera()

RwReversePolygonFace()

RwRevolveCamera()

RwRotateCTM()

RwRotateJointTM()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleCTM()

RwScaleMatrix()

RwScaleVector()

RwScratchMatrix()

RwSetAxisAlignment()

RwSetCameraBackColor()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropOffset()

RwSetCameraBackdropViewportRect()

RwSetCameraData()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwSetCameraNearClipping()

RwSetCameraPosition()

RwSetCameraProjection()

RwSetCameraViewOffset()

RwSetCameraViewport()

RwSetCameraViewwindow()

RwSetClumpAxisAlignment()

RwSetClumpData()

RwSetClumpHints()

RwSetClumpState()

RwSetClumpTag()

RwSetClumpVertex()

RwSetClumpVertexNormal()

RwSetClumpVertexUV()

RwSetClumpVertices()

RwSetDebugAssertionState()

RwSetDebugMessageState()

RwSetDebugOutputState()

RwSetDebugScriptState()

RwSetDebugSeverity()

RwSetDebugStream()

RwSetHints()

RwSetLightBrightness()

RwSetLightConeAngle()

RwSetLightData()

RwSetLightPosition()

RwSetLightState()

RwSetLightVector()

RwSetMaterialAmbient()

RwSetMaterialColor()

RwSetMaterialColorStruct()

RwSetMaterialDiffuse()

RwSetMaterialGeometrySampling()

RwSetMaterialLightSampling()

RwSetMaterialOpacity()

RwSetMaterialSpecular()

RwSetMaterialSurface()

RwSetMaterialTexture()

RwSetMaterialTextureModes()

RwSetMatrixElement()

RwSetMatrixElements()

RwSetPolygonAmbient()

RwSetPolygonColor()

RwSetPolygonColorStruct()

RwSetPolygonData()

RwSetPolygonDiffuse()

RwSetPolygonGeometrySampling()

RwSetPolygonLightSampling()

RwSetPolygonMaterial()

RwSetPolygonOpacity()

RwSetPolygonSpecular()

RwSetPolygonSurface()

RwSetPolygonTag()

RwSetPolygonTexture()

RwSetPolygonTextureModes()

RwSetPolygonUV()

RwSetRasterData()

RwSetSceneData()

RwSetShapePath()

RwSetSplineData()

RwSetSplinePoint()

RwSetSurface()

RwSetSurfaceAmbient()

RwSetSurfaceColor()

RwSetSurfaceDiffuse()

RwSetSurfaceGeometrySampling()

RwSetSurfaceLightSampling()

RwSetSurfaceOpacity()

RwSetSurfaceSpecular()

RwSetSurfaceTexture()

RwSetSurfaceTextureExt()

RwSetSurfaceTextureModes()

RwSetTag()

RwSetTextureData()

RwSetTextureDictSearchMode()

RwSetTextureDithering()

RwSetTextureGammaCorrection()

RwSetTextureFrame()

RwSetTextureFrameStep()

RwSetTextureRaster()

RwSetUserDrawAlignment()

RwSetUserDrawCallback()

RwSetUserDrawData()

RwSetUserDrawOffset()

RwSetUserDrawParentAlignment()

RwSetUserDrawSize()

RwSetUserDrawType()

RwSetUserDrawVertexIndex()

RwSetUserError()

RwShowCameraImage()

RwSphere()

RwSphericalTexturizeClump()

RwSplinePoint()

RwSplineTransform()

RwSubtractVector()

RwTextureDictBegin()

RwTextureDictEnd()

RwTextureNextFrame()

RwTiltCamera()

RwTransformBegin()

RwTransformCamera()

RwTransformCameraOrientation()

RwTransformClump()

RwTransformClumpJoint()

RwTransformCTM()

RwTransformEnd()

RwTransformJointTM()

RwTransformLight()

RwTransformMatrix()

RwTransformPoint()

RwTransformVector()

RwTranslateCTM()

RwTranslateMatrix()

RwTriangle()

RwTriangleExt()

RwUndamageCameraViewport()

RwVCMoveCamera()

RwVertex()

RwVertexExt()

RwWCMoveCamera()

RwWriteShape()


RwAddChildToClump()

RwClump *

RwAddChildToClump(RwClump *parent, RwClump *child);

Description

Makes the second clump a child of the first. If child is already a child of another clump, it will be removed from that clump's list of children before being added to parent.

Arguments

parent	Pointer to the parent clump.

child	Pointer to the child clump.

Return Value

The argument parent if successful, and NULL otherwise.

Comments

After addition, the child's modelling and joint (articulation) transformations will be relative to those of its new parent.

See Also

RwGetClumpNumChildren()

RwGetClumpParent()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()


RwAddClumpToScene()

RwScene *

RwAddClumpToScene(RwScene *scene, RwClump *clump);

Description

Adds the clump (and all its descendants) to the scene.

Arguments

scene	Pointer to the scene.

clump	Pointer to the clump.

Return Value

The argument scene if successful, and NULL otherwise.

Comments

Note that the clump being added must not have a parent (i.e., it must be a root clump).

See Also

RwAddLightToScene()

RwDestroyClump()

RwDestroyScene()

RwForAllClumpsInScene()

RwGetClumpOwner()

RwGetSceneNumClumps()

RwRemoveClumpFromScene()


RwAddHint()

int

RwAddHint(RwClumpHints hints);

Description

Adds a hint (or set of hints) to the current clump under construction. A clump's hints enable RenderWare to render a scene containing that clump more efficiently.

Arguments

hints	A bitfield representing a hint (or bitwise or of hints).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

Currently, the following hints are supported:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent   hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() block.

See Also

RwAddHintToClump()

RwClumpBegin()

RwClumpEnd()

RwRemoveHint()

RwSetHints()


RwAddHintToClump()

RwClump *

RwAddHintToClump(RwClump *clump, RwClumpHints hint);

Description

Adds a hint (or set of hints) to the clump. A clump's hints enable RenderWare to render a scene containing that clump more efficiently.

Arguments

clump	Pointer to the clump.

hint	A bitfield representing a hint (or bitwise or of hints).

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Currently, the following hints are supported:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

See Also

RwAddHint()

RwGetClumpHints()

RwRemoveHintFromClump()

RwSetClumpHints()


RwAddLightToScene()

RwScene *

RwAddLightToScene(RwScene *scene, RwLight *light);

Description

Adds the light to the scene.

Arguments

scene	Pointer to the scene.

light	Pointer to the light.

Return Value

The argument scene if successful, and NULL otherwise.

See Also

RwDestroyLight()

RwDestroyScene()

RwForAllLightsInScene()

RwGetLightOwner()

RwGetSceneNumLights()

RwRemoveLightFromScene()


RwAddPolygonsToClump()

RwClump *

RwAddPolygonsToClump(RwClump *dest, RwClump *source);

Description

Makes copies of all the polygons (and their associated vertices and materials) in the source clump and adds them to the destination clump.

Arguments

dest	Pointer to the destination clump.

source	Pointer to the source clump.

Return Value

The argument dest if successful, and NULL otherwise.

Comments

As this function modifies the geometry of the destination clump, the destination clump is made editable (the rwEDITABLE hint is set).

See Also

RwAddHintToClump()

RwAddPolygonToClump()

RwAddVertexToClump()

RwForAllPolygonsInClump()

RwGetClumpNumPolygons()

RwGetPolygonOwner()


RwAddPolygonToClump()

RwPolygon3d *

RwAddPolygonToClump(RwClump *clump, int sides, int *vlist);

Description

Creates a polygon and adds it to the clump. The current material is applied to the new polygon.

Arguments

clump	Pointer to the clump.

sides	Number of sides of the polygon.

vlist	Pointer to an array of ints containing the vertex indices of the new polygon.

Return Value

A pointer to the new polygon if successful, and NULL otherwise.

Comments

As this function modifies the geometry of the destination clump, the destination clump is made editable (the rwEDITABLE hint is set).

See Also

RwAddHintToClump()

RwAddPolygonsToClump()

RwAddVertexToClump()

RwForAllPolygonsInClump()

RwGetClumpNumPolygons()

RwGetPolygonOwner()


RwAddTextureModeToMaterial()

RwMaterial *

RwAddTextureModeToMaterial(RwMaterial *material, RwTextureModes mode);

Description

Adds the given texture mode (or modes) to the material. Texture modes permit fine grain control over the rendering of textures.

Arguments

material	Pointer to the material.

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument material if successful, and NULL otherwise.

Comments

The following texture modes are supported:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToPolygon()

RwAddTextureModeToSurface()

RwGetMaterialTextureModes()

RwSetMaterialLightSampling()

RwSetMaterialTextureModes()

RwSetMaterialTextureModes()

RwRemoveTextureModeFromSurface()


RwAddTextureModeToPolygon()

RwPolygon3d *

RwAddTextureModeToPolygon(RwPolygon3d *polygon, RwTextureModes mode);

Description

Adds the given texture mode (or modes) to the polygon's material. Texture modes permit fine grain control over the rendering of textures.

Arguments

polygon	Pointer to the polygon.

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

The following texture modes are supported:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToMaterial()

RwAddTextureModeToSurface()

RwGetPolygonTextureModes()

RwSetPolygonLightSampling()

RwSetPolygonTexture()

RwSetPolygonTextureModes()

RwRemoveTextureModeFromSurface()


RwAddTextureModeToSurface()

int

RwAddTextureModeToSurface(RwTextureModes mode);

Description

Adds the given texture mode (or modes) to the current material. Texture modes permit fine grain control over the rendering of textures.

Arguments

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The following texture modes are supported:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwAddTextureModeToMaterial()

RwAddTextureModeToPolygon()

RwModelBegin()

RwModelEnd()

RwSetSurfaceTexture()

RwSetSurfaceTextureModes()

RwRemoveTextureModeFromSurface()


RwAddUserDrawToClump()

RwClump *

RwAddUserDrawToClump(RwClump *clump, RwUserDraw *userdraw);

Description

Adds the user-draw to the clump. If the user-draw is already owned by another clump, it is first removed from that clump.

Arguments

clump	Pointer to the clump.

userdraw	Pointer to the user-draw.

Return Value

The argument clump if successful, and NULL otherwise.

See Also

RwCreateUserDraw()

RwDestroyClump()

RwDestroyUserDraw()

RwDuplicateUserDraw()

RwForAllUserDrawsInClump()

RwGetClumpNumUserDraws()

RwGetUserDrawOwner()

RwRemoveUserDrawFromClump()


RwAddVector()

RwV3d *

RwAddVector(RwV3d *a, RwV3d *b, RwV3d *c);

Description

Adds two vectors.

Arguments

a	Pointer to the first vector.

b	Pointer to the second vector.

c	Pointer to the vector that will receive the result.

Return Value

The argument c if successful, and NULL otherwise.

See Also

RwCrossProduct()

RwDotProduct()

RwNormalize()

RwScaleVector()

RwSubtractVector()

RwTransformVector()


RwAddVertexToClump()

int

RwAddVertexToClump(RwClump *clump, RPARAM x, RPARAM y, RPARAM z);

Description

Adds a vertex to the clump.

Arguments

clump	Pointer to the clump.

x	X coordinate of the vertex (in object space coordinates).

y	Y coordinate of the vertex (in object space coordinates).

z	Z coordinate of the vertex (in object space coordinates).

Return Value

A positive integer representing the index of the vertex within the clump if successful, and 0 otherwise.

Comments

As this function modifies the geometry of the clump, the clump is made editable by this function (the rwEDITABLE hint is set).

The initial texture coordinates of the vertex are [CREAL(0.5), CREAL(0.5)] and the initial unit shading normal is computed by RenderWare.

See Also

RwAddPolygonsToClump()

RwAddPolygonToClump()

RwGetClumpNumVertices()

RwSetClumpVertex()

RwSetClumpVertexUV()

RwSetClumpVertexNormal()

RwSetClumpVertices()


RwBeginCameraUpdate()

RwCamera *

RwBeginCameraUpdate(RwCamera *camera);

Description

Makes camera the current camera (the camera used in subsequent rendering operations).

Arguments

camera	Pointer to the camera.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

RwClearCameraViewport(), RwRenderClump(), and RwRenderScene() should only be called from within an RwBeginCameraUpdate() … RwEndCameraUpdate().

See Also

RwClearCameraViewport()

RwEndCameraUpdate()

RwRenderClump()

RwRenderScene()

RwShowCameraImage()


RwBitmapRaster()

RwRaster *

RwBitmapRaster(void *bitmap, RwRasterOptions options);

Description

Converts a platform specific bitmap to a raster. The bitmap will be processed according to the specified options.

Arguments

bitmap	The source bitmap (device dependent parameter).

options	A bitfield representing a raster processing option (or bitwise or of options).

Return Value

A pointer to the new raster if successful, and NULL otherwise.

Comments

This function is useful for generating texture maps at run-time. An application can convert platform specific, 2D rendering into a raster with RwBitmapRaster(). The resultant raster can then be selected into a texture map with RwSetTextureRaster().

The supported raster options are as follows:

•	rwAUTODITHERRASTER     Dither the raster only if the source bitmap is to be resized (rwFITRASTER has been specified) or if the bitmap is a different depth from the current RenderWare render depth.

•	rwDITHERRASTER    Dither the raster.

•	rwFITRASTER    Resize the raster to texture map dimensions, i.e., 128 x n * 128 (where n is the number of frames in a multi-frame texture).

•	rwGAMMARASTER    Gamma correct the raster.

•	rwINDEXRASTER    Do not convert the raster into RenderWare color space.

See Also

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwReadRaster()

RwReadMaskRaster()

RwSetTextureRaster()


RwBlock()

int

RwBlock(RPARAM width, RPARAM height, RPARAM depth);

Description

Adds a block, centred about the origin, to the current clump under construction. The block is transformed by the CTM, and the current material is applied to its polygons.

Arguments

width	Block width.

height	Block height.

depth	Block depth.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

It is an error if any of the block's dimensions are degenerate, i.e., CREAL(0.0).

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwCone()

RwCylinder()

RwDisc()

RwHemisphere()

RwProtoBegin()

RwProtoEnd()

RwSphere()


RwCalculateClumpVertexNormal()

RwClump *

RwCalculateClumpVertexNormal(RwClump *clump, int index);

Description

Activates automatic calculation of the unit shading normal at the vertex which belongs to clump and has the vertex index index. This ensures that the unit shading normal of the vertex will be recalculated every time the vertex is moved with RwSetClumpVertex() or the set of polygons sharing the vertex is modified.

Arguments

clump	Pointer to the clump.

index 	The vertex index.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Automatic calculation is deactivated after a call to RwSetClumpVertexNormal() or if the vertex is created by calling RwVertexExt() with a non-NULL normal.

Unit shading normals are automatically recalculated by default.

See Also

RwGetClumpVertexNormal()

RwSetClumpVertex()

RwSetClumpVertexNormal()

RwVertexExt()


RwClearCameraViewport()

RwCamera *

RwClearCameraViewport(RwCamera *camera);

Description

Clears the camera's image buffer. If the camera does not have a backdrop raster the viewport will be cleared to the camera's background color. If the camera has a backdrop raster the camera's backdrop viewport rectangle will be filled with the backdrop raster. The remainder of the viewport will be cleared to the camera's background color.

Arguments

camera	Pointer to the camera.

Return Value

The argument camera if successful, and NULL otherwise.

Comment

This function can only be called within the context of an RwBeginCameraUpdate()… RwEndCameraUpdate() block.

See Also

RwBeginCameraUpdate()

RwDamageCameraViewport()

RwEndCameraUpdate()

RwInvalidateCameraViewport()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropViewportRect()

RwUndamageCameraViewport()


RwClose()

void

RwClose(void);

Description

Closes the RenderWare library.

Arguments

None.

Return Value

None.

Comments

This function must be called before the program exits.

RwClose() frees the following resources:

•	the default scene, and any clumps and lights contained in that scene.

•	the scratch matrix stack.

•	the transformation matrix stack.

•	the joint transformation matrix stack.

•	the material stack.

•	all cameras.

•	all named textures (and their rasters) and texture dictionaries.

RwClose() does not free the following resources:

•	scenes other than the default scene.

•	clumps and lights not in the default scene.

•	matrices created with RwCreateMatrix() or RwDuplicateMatrix().

•	materials created with RwCreateMaterial() or RwDuplicateMaterial().

•	unnamed textures.

•	rasters not selected into named textures (this includes camera backdrop rasters which must be destroyed explicitly).

•	splines.

•	user-draws not owned by clumps in the default scene.

See Also

RwCreateMaterial()

RwCreateMatrix()

RwDuplicateMaterial()

RwDuplicateMatrix()

RwOpen()

RwOpenExt()


RwCloseDebugStream()

void

RwCloseDebugStream(void);

Description

Closes the current debug stream.

Arguments

None.

Return Value

None.

Comments

No more debugging messages will be issued until a debugging stream is specified with RwSetDebugStream() or opened using RwOpenDebugStream().

See Also

RwOpenDebugStream()

RwSetDebugStream()


RwClumpBegin()

int

RwClumpBegin(void);

Description

Identifies the beginning of a clump definition. The modelling matrix for the clump is set to the CTM at this time. The joint (articulation) matrix for the clump is set to the current joint transformation matrix.

The current transformation matrix, the current joint transformation matrix, and the current material are pushed onto the main transformation stack, the joint transformation stack, and the material stack respectively.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block. A call to RwClumpBegin() may be nested, to any depth, within an RwProtoBegin() … RwProtoEnd() or RwClumpBegin() … RwClumpEnd() block.

When nested within an RwProtoBegin() … RwProtoEnd() or RwClumpBegin() … RwClumpEnd() block, an RwClumpBegin() … RwClumpEnd() block creates a child clump.

If the nested RwClumpBegin() … RwClumpEnd() block is within an RwProtoBegin() … RwProtoEnd() block, then no clump is actually created, instead a child definition is added to the prototype under construction.

See Also

RwClumpEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()


RwClumpDistance()

RPARAM

RwClumpDistance(RwClump *clump, RwV3d *point);

Description

Calculates the distance from the origin of the clump to the point (in world space units).

Arguments

clump	Pointer to the clump.

point	Pointer to the point.

Return Value

The distance between the origin of the clump and the point in world space units if successful. Errors can be checked for using RwGetError().

See Also

RwGetClumpOrigin()


RwClumpEnd()

RwClump *

RwClumpEnd(RwClump **pointer);

Description

Marks the end of the construction of clump and returns the newly created clump. The main transformation stack, the joint transformation stack and the material stack are restored to their state at the time of the matching RwClumpBegin().

Arguments

pointer	Pointer to the clump pointer that will receive the clump.

Return Value

A pointer to the new clump if successful, and NULL otherwise.

Comments

The function returns a pointer to the newly created clump. If a non-NULL argument is passed then pointer will also be set to point to the new clump.

When there are nested RwClumpEnd() calls, i.e., a hierarchical model is being built, NULL should be used as the argument in all RwClumpEnd() calls except the top-level one. Do not rely on the clump pointers returned by this function when creating child clumps.

See Also

RwClumpBegin()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()


RwCone()

int

RwCone(RPARAM height, RPARAM radius, int nsides);

Description

Adds a cone to the current clump under construction. The cone is transformed by the CTM, and the current material is assigned to its polygons. The base of the cone lies on the X-Z plane, extending up the Y axis. The base is not closed.

Arguments

height	Cone height.

radius	Radius of the cone base.

nsides	Number of sides.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

It is an error if the cone's radius is degenerate, i.e. CREAL(0.0).

If a negative radius is specified, the polygons forming the cone will face inward.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCylinder()

RwDisc()

RwHemisphere()

RwProtoBegin()

RwProtoEnd()

RwSphere()


RwCopyMaterial()

RwMaterial *

RwCopyMaterial(RwMaterial *source, RwMaterial *dest);

Description

Copies material source to material dest.

Arguments

source	Pointer to the source material.

dest	Pointer to the destination material.

Return Value

The argument dest if successful, and NULL otherwise.

See Also

RwCreateMaterial()

RwDestroyMaterial()

RwDuplicateMaterial()

RwPushCurrentMaterial()


RwCopyMatrix()

RwMatrix4d *

RwCopyMatrix(RwMatrix4d *source, RwMatrix4d *dest);

Description

Copies matrix source to matrix dest.

Arguments

source	Pointer to the source matrix.

dest	Pointer to the destination matrix.

Return Value

The argument dest if successful, and NULL otherwise.

See Also

RwCreateMatrix()

RwDestroyMatrix()

RwDuplicateMatrix()

RwPushScratchMatrix()


RwCreateCamera()

RwCamera *

RwCreateCamera(int maxwidth, int maxheight, void *param);

Description

Creates a new camera.

Arguments

maxwidth	Maximum width of the camera viewport (in device space units).

maxheight	Maximum height of the camera viewport (in device space units).

param	Device dependent parameter.

Return Value

A pointer to the new camera if successful, and NULL otherwise.

Comments

For a description of the device dependent parameter, param, see MS Windows 3.1 Specific Information.

By default:

•	The camera is positioned at the origin, looking down the negative Z axis (into the screen).

•	The "Look Up" vector is the positive Y axis of the world space.

•	The projection model is rwPERPSECTIVE.

•	The viewport has a position of (0, 0) and a size of 0 by 0.

•	The view window is centered about the origin of the camera space and has a size of CREAL(1.0) by CREAL(1.0).

•	The view offset is (CREAL(0.0), CREAL(0.0)).

•	The near (front) clipping plane is approximately CREAL(0.05) world space units from the camera.

•	The camera background color is black, i.e., [CREAL(0.0), CREAL(0.0), CREAL(0.0)].

•	The backdrop raster is NULL.

•	The backdrop offset is (0, 0).

•	The backdrop viewport rectangle has a position of (0, 0) and a size of 0 by 0.

See Also

RwDestroyCamera()

RwDuplicateCamera()

RwResetCamera()


RwCreateClump()

RwClump *

RwCreateClump(int vcount, int pcount);

Description

Creates a new, empty clump. The clump is added to the default scene.

Arguments

vcount	Initial number of vertices.

pcount	Initial number of polygons.

Return Value

A pointer to the new clump if successful, and NULL otherwise.

Comments

The arguments vcount and pcount are initial guidelines only, the actual number of polygons and vertices in a clump is not constrained by these initial values.

See Also

RwAddPolygonsToClump()

RwAddPolygonToClump()

RwAddVertexToClump()

RwClumpBegin()

RwClumpEnd()

RwCreateDecal()

RwCreateSprite()

RwDestroyClump()

RwDuplicateClump()

RwReadShape()


RwCreateDecal()

RwClump *

RwCreateDecal(RwTexture *texture);

Description

Synonym for RwCreateSprite(). See the description of RwCreateSprite() for details.

Arguments

texture	Pointer to the texture.

Return Value

A pointer to the newly created decal if successful, and NULL otherwise.

 See Also

RwAddPolygonToClump()

RwAddVertexToClump()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateSprite()

RwDestroyClump()

RwFindNamedTexture()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadShape()

RwReadTexture()

RwSetClumpAxisAlignment()

RwSetPolygonTexture()

RwSetPolygonTextureModes()


RwCreateLight()

RwLight *

RwCreateLight(RwLightType type, RPARAM x, RPARAM y, RPARAM z, RPARAM intensity);

Description

Creates a new light. The light is added to the default scene.

Arguments

type	Type of light.

x	X component of the light's position in world space coordinates (for point and conical lights), or vector (for directional lights).

y	Y component of the light's position in world space coordinates (for point and conical lights), or vector (for directional lights).

z	Z component of the light's position in world space coordinates (for point and conical lights), or vector (for directional lights).

intensity	Intensity of the light in the range CREAL(-1.0) to CREAL(1.0).

Return Value

A pointer to the new light if successful, and NULL otherwise.

Comments

The default light state is rwON.

For conical lights, the default direction vector is down the negative Y axis, and the default cone angle is CREAL(30.0) degrees.

See Also

RwAddLightToScene()

RwDestroyLight()

RwDuplicateLight()


RwCreateMaterial()

RwMaterial *

RwCreateMaterial(void);

Description

Creates a new material with default values for its attributes.

Arguments

None.

Return Value

A pointer to the newly created material if successful, and NULL otherwise.

Comments

By default:

•	The material's coefficients of ambient, diffuse, and specular reflection are CREAL(0.0).

•	The material's color is black, i.e., [CREAL(0.0), CREAL(0.0), CREAL(0.0)].

•	The material's light sampling type is rwFACET.

•	The material's geometry sampling type is rwSOLID.

•	The material has no texture.

•	The material's only texture mode is rwLIT.

•	The material's opacity is CREAL(1.0).

See Also

RwCurrentMaterial()

RwDestroyMaterial()

RwDuplicateMaterial()

RwPushCurrentMaterial()


RwCreateMatrix()

RwMatrix4d *

RwCreateMatrix(void);

Description

Creates a new transformation matrix.

Arguments

None.

Return Value

A pointer to the new matrix if successful, and NULL otherwise.

Comments

The new matrix is initialized to the identity matrix.

See Also

RwScratchMatrix()

RwDestroyMatrix()

RwDuplicateMatrix()

RwPushScratchMatrix()


RwCreateRaster()

RwRaster *

RwCreateRaster(int width, int height);

Description

Creates a new raster.

Arguments

width	Width of the raster (in pixels).

height	Height of the raster (in pixels).

Return Value

A pointer to the new raster if successful, and NULL otherwise.

Comments

The depth of the raster created is the same as the current render depth (the current render depth can be retrieved by RwGetDeviceInfo()).

The raster's pixels are not initialized by RwCreateRaster(). The initial pixel values are undefined.

See Also

RwBitmapRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwGetDeviceInfo()

RwGetTextureRaster()

RwReadRaster()

RwReadMaskRaster()

RwSetCameraBackdrop()

RwSetTextureRaster()


RwCreateScene()

RwScene *

RwCreateScene(void);

Description

Creates a new, empty scene.

Arguments

None.

Return Value

A pointer to the new scene if successful, and NULL otherwise.

See Also

RwAddClumpToScene()

RwAddLightToScene()

RwDefaultScene()

RwDestroyScene()


RwCreateSpline()

RwSpline *

RwCreateSpline(int npoints, RwSplineType type, RwV3d *points);

Description

Creates a new spline.

Arguments

npoints	Number of control points (greater than or equal to 4).

type	Type of the spline.

points	Array of control points.

Return Value

A pointer to the new spline if successful, and NULL otherwise.

Comments

A minimum of 4 control points must be specified.

See Also

RwDestroySpline()

RwDuplicateSpline()


RwCreateSprite()

RwClump *

RwCreateSprite(RwTexture *texture);

Description

Creates a sprite. A sprite is a specialized form of clump which is used to display unlit textures constrained to be co-planer with the viewplane of a camera.

Arguments

texture	Pointer to the texture.

Return Value

A pointer to the newly created sprite if successful, and NULL otherwise.

Comments

This function is a simplification function which creates a clump with a single, rectangular polygon, one unit in width and one unit in height, centered about the origin and lying in the X-Y plane. The given texture is made the current texture of the polygon's material and the material's texture mode is set to 0, i.e., the sprite is unlit and not foreshortened. The clump's axis alignment parameter is set to rwALIGNAXISXYZ.

The resulting clump may be manipulated in exactly the same way and using exactly the same API calls as clumps created by RwReadShape(), RwClumpBegin() … RwClumpEnd(), and RwCreateClump(). In particular, RwDestroyClump() should be used to destroy the clump created by RwCreateSprite() when it is no longer required.

Previous versions of RenderWare referred to sprites as decals. The function RwCreateDecal() remains in the API as a synonym for RwCreateSprite(). However, it is recommended that applications replace calls to RwCreateDecal() with RwCreateSprite(). RwCreateSprite() and RwCreateDecal() are semantically identical.

 See Also

RwAddPolygonToClump()

RwAddVertexToClump()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwDestroyClump()

RwFindNamedTexture()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadShape()

RwReadTexture()

RwSetClumpAxisAlignment()

RwSetPolygonTexture()

RwSetPolygonTextureModes()


RwCreateTexture()

RwTexture *

RwCreateTexture(RwRaster *raster);

Description

Creates a new texture and sets its raster to raster.

Arguments

raster	Pointer to the raster.

Return Value

A pointer to the newly created texture if successful, and NULL otherwise.

Comments

The specified raster must have a width of 128 pixels and a height of 128 pixels (or n * 128 pixels for multi-frame textures where n is the number of frames). The raster will not be resized if it not already of the correct size.

Rasters cannot be shared between textures. It is an error to specify a raster already selected into a texture.

See Also

RwBitmapRaster()

RwCreateRaster()

RwDestroyTexture()

RwFindNamedTexture()

RwGetCameraViewportRaster()

RwGetNamedTexture()

RwMaskTexture()

RwReadMaskRaster()

RwReadNamedTexture()

RwReadRaster()

RwReadTexture()

RwSetTextureRaster()


RwCreateUserDraw()

RwUserDraw *

RwCreateUserDraw(RwUserDrawType type, RwUserDrawAlignmentTypes alignment, int x, int y, int width, int height, void (*callback)(RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data));

Description

Creates a user-draw.

Arguments

type	Type of user-draw to create.

alignment	A bitfield representing an alignment type (or bitwise or of alignment types).

x	X offset of the user-draw from the alignment point (in viewport space units).

y	Y offset of the user-draw from the alignment point (in viewport space units).

width	Width of the user-draw (in viewport space units).

height	Height of the user-draw (in viewport space units).

callback	Pointer to the call-back function that will render the user-draw.

Return Value

A pointer to the new user-draw if successful, and NULL otherwise.

Comments

The type of the user-draw determines whether it is aligned with a clump's origin (rwCLUMPALIGN), with a clump's vertex (rwVERTEXALIGN), with a clump's bounding box in viewport space (rwBBOXALIGN), or a camera's viewport (rwVPALIGN).

The following alignment flags are supported: rwALIGNTOP, rwALIGNBOTTOM, rwALIGNLEFT and rwALIGNRIGHT. For convenience, two common combinations of these flags, rwALIGNTOPLEFT and rwALIGNBOTTOMRIGHT are also defined.

Assuming that the type of the user-draw is rwVERTEXALIGN, then the interpretations of the different valid values for alignment are as follows:

•	0

The center of the user-draw is aligned with the vertex.

•	rwALIGNTOP

The midpoint of the top edge of the user-draw rectangle is aligned with the vertex.

•	rwALIGNBOTTOM

The midpoint of the bottom edge of the user-draw rectangle is aligned with the vertex.

•	rwALIGNLEFT

The midpoint of the left edge of the user-draw rectangle is aligned with the vertex.

•	rwALIGNRIGHT

The midpoint of the right edge of the user-draw rectangle is aligned with the vertex.

•	rwALIGNTOP | rwALIGNLEFT

The top left corner of the user-draw rectangle is aligned with the vertex.

•	rwALIGNTOP | rwALIGNRIGHT

The top right corner of the user-draw rectangle is aligned with the vertex.

•	rwALIGNBOTTOM | rwALIGNLEFT

The bottom left corner of the user-draw rectangle is aligned with the vertex.

•	rwALIGNBOTTOM | rwALIGNRIGHT

The bottom right corner of the user-draw rectangle is aligned with the vertex.

A user-draw is positioned at an offset (x, y) from the point of alignment and its size is specified by width and height.

User-draw call-backs should be declared as follows:

void callback(RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data);

Where the call-back's arguments are as follows:

userdraw	Pointer to the user-draw to be rendered.

camimage	The camera's image buffer as returned by RwGetCameraImage() for the current camera. camimage is device dependent. For more information, see MS Windows 3.1 Specific Information.

rect	Pointer to a rectangle defining the area of the camera's image buffer into which the call-back may render. This rectangle is specified in viewport space coordinates, i.e., (0, 0) is the origin of the viewport.

data	Pointer to the user data of the user-draw being drawn. This value can be obtained by calling RwGetUserDrawData() with userdraw as an argument. data is passed directly to the call-back function for the convenience of the application developer.

Note that the call-back function is always called after all clumps in the scene have been rendered, i.e., when RwEndCameraUpdate() is called. Therefore user-draw rendering always appear in front of clump rendering. In the case of overlapping user-draws, the order of rendering is not defined.

See Also

RwAddUserDrawToClump()

RwDestroyClump()

RwDestroyUserDraw()

RwDuplicateUserDraw()

RwEndCameraUpdate()

RwGetCameraImage()

RwGetUserDrawData()


RwCrossProduct()

RwV3d *

RwCrossProduct(RwV3d *a, RwV3d *b, RwV3d *c);

Description

Calculates the cross product of two vectors.

Arguments

a	Pointer to the left vector.

b	Pointer to the right vector.

c	Pointer to the vector that will receive the result.

Return Value

The argument c if successful, and NULL otherwise.

Comments

c must not point to the same vector as either of the other arguments.

See Also

RwAddVector()

RwDotProduct()

RwNormalize()

RwScaleVector()

RwSubtractVector()

RwTransformVector()


RwCubicTexturizeClump()

RwClump *

RwCubicTexturizeClump(RwClump *clump);

Description

Sets the texture coordinates for every polygon belonging to the clump using the cubic projection method.

A cubic mapping results in the construction of a nominal cube which has the texture applied to each of the cube's six facets. The resulting cube (with a copy of the texture applied to each face) is then mapped to the clump by "shrink wrapping" the clump with the cube.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

This function need only be called once, the first time a clump is texturized, and not each time the clump is rendered.

Note that this function does not set the textures associated with the clump's polygons; this must be accomplished separately. The following code fragment illustrates this procedure:

RwForAllPolygonsInClumpPointer(clump, (RwPolygon3d*(*)())RwSetPolygonTexture, texture);

See Also

RwEnvMapClump()

RwForAllPolygonsInClump()

RwSetClumpVertexUV()

RwSetPolygonTexture()

RwSetPolygonUV()

RwSphericalTexturizeClump()

RwVertexExt()


RwCurrentMaterial()

RwMaterial *

RwCurrentMaterial(void);

Description

Retrieves the current material.

Arguments

None.

Return Value

A pointer to the current material if successful, and NULL otherwise.

Comments

The material returned by RwCurrentMaterial() must not be destroyed with RwDestroyMaterial(). The material stack is destroyed by RenderWare when RwClose() is called.

See Also

RwClose()

RwCreateMaterial()

RwDestroyMaterial()

RwPopCurrentMaterial()

RwPushCurrentMaterial()


RwCylinder()

int

RwCylinder(RPARAM height, RPARAM baserad, RPARAM toprad, int nsides);

Description

Adds a cylinder to the current clump under construction. The cylinder is transformed by the CTM, and the current material is assigned to its polygons. The base of the cylinder lies on the X-Z plane, extending up the Y axis.

Arguments

height	Cylinder height.

baserad	Radius of the cylinder base.

toprad	Radius of the cylinder top.

nsides	Number of sides.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

It is an error if the cylinder's radius is degenerate, i.e., CREAL(0.0).

Note that if both baserad and toprad are negative the polygons forming the cylinder will face inward. It is an error if one of the radii is negative and the other is positive.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCone()

RwDisc()

RwHemisphere()

RwSphere()

RwProtoBegin()

RwProtoEnd()


RwDamageCameraViewport()

RwCamera *

RwDamageCameraViewport(RwCamera *camera, int x, int y, int width, int height);

Description

Damages a rectangular area of the camera's viewport. The rectangle is added to the area to be updated by RwShowCameraImage() and cleared by RwClearCameraViewport().

Arguments

camera	Pointer to the camera.

x	X coordinate of the rectangle's top left corner (in viewport space coordinates).

y	Y coordinate of the rectangle's top left corner (in viewport space coordinates).

width	Width of the rectangle (in viewport space units).

height	Height of the rectangle (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwBeginCameraUpdate()

RwClearCameraViewport()

RwEndCameraUpdate()

RwInvalidateCameraViewport()

RwShowCameraImage()

RwUndamageCameraViewport()


RwDefaultScene()

RwScene *

RwDefaultScene(void);

Description

Retrieves the default scene.

Arguments

None.

Return Value

A pointer to the default scene.

Comments

The scene returned by RwDefaultScene() must not be destroyed with RwDestroyScene(). The default scene is destroyed by RenderWare when RwClose() is called.

See Also

RwClose()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateLight()

RwCreateScene()

RwCreateSprite()

RwDestroyScene()

RwReadShape()

RwRemoveClumpFromScene()

RwRemoveLightFromScene()


RwDestroyCamera()

int

RwDestroyCamera(RwCamera *camera);

Description

Destroys the camera.

Arguments

camera	Pointer to the camera.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

All cameras not explicitly destroyed are automatically destroyed by RwClose().

This function does not destroy the device dependent object specified in the call to RwCreateCamera(). Furthermore, the camera's backdrop raster (if any) is not destroyed.

See Also

RwClose()

RwCreateCamera()

RwDuplicateCamera()

RwSetCameraBackdrop()


RwDestroyClump()

int

RwDestroyClump(RwClump *clump);

Description

Destroys the clump.

Arguments

clump	Pointer to the clump.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

Note that this function is recursive - it destroys the clump and all its descendants (if any). Furthermore, any user-draw objects added to this clump will also be destroyed by RwDestroyClump().

See Also

RwAddUserDrawToClump()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwDestroyScene()

RwDuplicateClump()

RwReadShape()


RwDestroyLight()

int

RwDestroyLight(RwLight *light);

Description

Destroys the light.

Arguments

light	Pointer to the light.

Return Value

TRUE if successful, and FALSE otherwise.

See Also

RwCreateLight()

RwDestroyScene()

RwDuplicateLight()

RwRemoveLightFromScene()


RwDestroyMaterial()

int

RwDestroyMaterial(RwMaterial *material);

Description

Destroys the material.

Arguments

material	Pointer to the material.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function must not be used to destroy a polygon's material (as obtained by a call to RwGetPolygonMaterial()), or a material from the material stack (as obtained by RwCurrentMaterial(), RwPopCurrentMaterial() or RwPushCurrentMaterial()).

See Also

RwCreateMaterial()

RwDuplicateMaterial()

RwGetPolygonMaterial()

RwPopCurrentMaterial()

RwPushCurrentMaterial()


RwDestroyMatrix()

int

RwDestroyMatrix(RwMatrix4d *matrix);

Description

Destroys the matrix.

Arguments

matrix	Pointer to the matrix.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function must not be used to destroy a matrix from the scratch matrix stack (as obtained by RwScratchMatrix(), RwPopScratchMatrix() or RwPushScratchMatrix()).

See Also

RwCreateMatrix()

RwScratchMatrix()

RwDuplicateMatrix()

RwPopScratchMatrix()

RwPushScratchMatrix()


RwDestroyPolygon()

int

RwDestroyPolygon(RwPolygon3d *polygon);

Description

Destroys the polygon.

Arguments

polygon	Pointer to the polygon.

Return Value

TRUE if successful, and FALSE otherwise.

See Also

RwAddPolygonsToClump()

RwAddPolygonToClump()

RwDestroyClump()


RwDestroyRaster()

int

RwDestroyRaster(RwRaster *raster);

Description

Destroys the raster.

Arguments

raster	Pointer to the raster.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

It is an error to attempt to destroy a a texture's raster. RwDestroyTexture() destroys both a texture and its raster. This also applies to rasters selected into texture by RwCreateTexture() or RwSetTextureRaster().

RwDestroyCamera() does not destroy a camera's backdrop raster. The backdrop raster should be destroyed by RwDestroyRaster().

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyCamera()

RwDestroyTexture()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwGetTextureRaster()

RwReadRaster()

RwReadMaskRaster()

RwSetCameraBackdrop()

RwSetTextureRaster()


RwDestroyScene()

int

RwDestroyScene(RwScene *scene);

Description

Destroys the scene and all its clumps and lights.

Arguments

scene	Pointer to the scene.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

To prevent a clump or light from being destroyed, use RwRemoveClumpFromScene() or RwRemoveLightFromScene() before calling RwDestroyScene().

The default scene cannot be destroyed.

See Also

RwCreateScene()

RwDefaultScene()

RwDestroyClump()

RwDestroyLight()

RwRemoveClumpFromScene()

RwRemoveLightFromScene()


RwDestroySpline()

int

RwDestroySpline(RwSpline *spline);

Description

Destroys the spline.

Arguments

spline	Pointer to the spline.

Return Value

TRUE if successful, and FALSE otherwise.

See Also

RwCreateSpline()

RwDuplicateSpline()


RwDestroyTexture()

int

RwDestroyTexture(RwTexture *texture);

Description

Destroys the texture (and its raster).

Arguments

texture	Pointer to the texture.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

Textures which are still referenced by materials must not be destroyed. Remove the references to a texture with RwSetMaterialTexture() or RwSetPolygonTexture() before destroying the texture.

If the texture is defined in a dictionary, this function removes it from that dictionary.

See Also

RwCreateTexture()

RwFindNamedTexture()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadShape()

RwReadTexture()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetTextureRaster()

RwTextureDictEnd()


RwDestroyUserDraw()

int

RwDestroyUserDraw(RwUserDraw *userdraw);

Description

Destroys the user-draw.

Arguments

userdraw	Pointer to the user-draw.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If userdraw is owned by a clump it will be removed from the clump prior to being destroyed.

Note that RwDestroyClump() destroys any user-draw objects that belong to the clump being destroyed.

See Also

RwAddUserDrawToClump()

RwCreateUserDraw()

RwDestroyClump()

RwDuplicateUserDraw()

RwRemoveUserDrawFromClump()


RwDeviceControl()

int

RwDeviceControl(RwDeviceAction action, long param1, void *param2);

Description

Performs low-level, device dependent actions.

Arguments

action	Device dependent action.

param1	First action specific parameter.

param2	Second action specific parameter.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The supported actions and their associated parameter values are device dependent. See MS Windows 3.1 Specific Information for details.


RwDisc()

int

RwDisc(RPARAM height, RPARAM radius, int nsides);

Description

Adds a disc to the current clump under construction. The disc is transformed by the CTM, and the current material is assigned to its polygons. The disc lies on the Y=height plane, centered about the Y axis. This function is primarily used to cap cones and cylinders.

Arguments

height	Disc plane.

radius	Radius of the disc.

nsides	Number of sides.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

It is an error if the disc's radius is degenerate, i.e., CREAL(0.0).

Note that it is possible for the argument radius to have a negative value. In which case, the polygons forming the disc will be reversed.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCone()

RwCylinder()

RwHemisphere()

RwProtoBegin()

RwProtoEnd()

RwSphere()


RwDotProduct()

RPARAM

RwDotProduct(RwV3d *a, RwV3d *b);

Description

Calculates the dot product of two vectors.

Arguments

a	Pointer to the left vector.

b	Pointer to the right vector.

Return Value

The dot product. Errors can be checked for using RwGetError().

Comments

The answer is effectively meaningful only when the vectors are normalized (unit length).

See Also

RwAddVector()

RwCrossProduct()

RwGetError()

RwNormalize()

RwScaleVector()

RwSubVector()

RwTransformVector()


RwDuplicateCamera()

RwCamera *

RwDuplicateCamera(RwCamera *camera, void *param);

Description

Creates a new camera with the same attributes as camera.

Arguments

camera	Pointer to the camera.

param	Device dependent parameter.

Return Value

A pointer to the new camera if successful, and NULL otherwise.

Comments

For a description of the device dependent parameter, param, see MS Windows 3.1 Specific Information.

If camera has a backdrop raster the raster will not be duplicated. The new camera will share the raster with camera.

See Also

RwCreateCamera()

RwDestroyCamera()


RwDuplicateClump()

RwClump *

RwDuplicateClump(RwClump *clump);

Description

Creates a new clump with the same attributes as clump. The new clump is added to the same scene as clump.

Arguments

clump	Pointer to the clump.

Return Value

A pointer to the new clump if successful, and NULL otherwise.

Comments

Note that this function is recursive - it copies the clump and all its descendants (if any).

See Also

RwAddClumpToScene()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwDestroyClump()

RwReadShape()


RwDuplicateLight()

RwLight *

RwDuplicateLight(RwLight *light);

Description

Creates a new light with the same attributes as light. The new light is added to the same scene as light.

Arguments

light	Pointer to the light.

Return Value

A pointer to the new light if successful, and NULL otherwise.

See Also

RwAddLightToScene()

RwCreateLight()

RwDestroyLight()


RwDuplicateMaterial()

RwMaterial *

RwDuplicateMaterial(RwMaterial *material);

Description

Creates a new material with the same attributes as material.

Arguments

material	Pointer to the material.

Return Value

A pointer to the new material if successful, and NULL otherwise.

See Also

RwCreateMaterial()

RwDestroyMaterial()


RwDuplicateMatrix()

RwMatrix4d *

RwDuplicateMatrix(RwMatrix4d *matrix);

Description

Creates a new matrix with the same elements as matrix.

Arguments

matrix	Pointer to the matrix to duplicate.

Return Value

Pointer to the new matrix if successful, and NULL otherwise.

See Also

RwCreateMatrix()

RwDestroyMatrix()


RwDuplicateRaster()

RwRaster *

RwDuplicateRaster(RwRaster *raster);

Description

Creates a new raster with the same attributes as raster. The pixels of raster are copied to the new raster.

Arguments

raster	Pointer to the raster.

Return Value

Pointer to the new raster if successful, and NULL otherwise.

See Also

RwBitmapRaster()

RwCreateRaster()

RwDestroyRaster()

RwGetCameraViewportRaster()

RwReadRaster()

RwReadMaskRaster()


RwDuplicateSpline()

RwSpline *

RwDuplicateSpline(RwSpline *spline);

Description

Creates a new spline with the same attributes as spline.

Arguments

spline	Pointer to the spline.

Return Value

A pointer to the new spline if successful, and NULL otherwise.

See Also

RwCreateSpline()

RwDestroySpline()


RwDuplicateUserDraw()

RwUserDraw *

RwDuplicateUserDraw(RwUserDraw *userdraw);

Description

Creates a new user-draw with the same attributes as userdraw.

Arguments

userdraw	Pointer to the user-draw to be duplicated.

Return Value

A pointer to the new user-draw if successful, and NULL otherwise.

Comments

The new user-draw is owned by the same clump as userdraw, if userdraw has an owning clump, otherwise it will not be owned by a clump and should be added to a clump with RwAddUserDrawToClump().

 See Also

RwAddUserDrawToClump()

RwCreateUserDraw()

RwDestroyUserDraw()


RwEndCameraUpdate()

RwCamera *

RwEndCameraUpdate(RwCamera *camera);

Description

Performs all necessary housekeeping activities after rendering into the camera's image buffer is complete.

Arguments

camera	Pointer to the camera.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

RwClearCameraViewport(), RwRenderClump() and RwRenderScene() should only be called from within an RwBeginCameraUpdate()… RwEndCameraUpdate(). Upon exit from this block, rendering to the specified camera's image buffer is complete. RwShowCameraImage() can then be used to update the host's display.

See Also

RwBeginCameraUpdate()

RwClearCameraViewport()

RwRenderClump()

RwRenderScene()

RwShowCameraImage()


RwEnvMapClump()

RwClump *

RwEnvMapClump(RwClump *clump);

Description

Performs a view dependent projection of an environment map onto a clump.

 Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

To ensure the accuracy of the map, call this function each time the clump is transformed or the viewing camera is moved.

The environment map must have been previously assigned to that clump using;

RwForAllPolygonsInClumpPointer(clump, (RwPolygon3d*(*)())RwSetPolygonTexture, texture);

See Also

RwCubicTexturizeClump()

RwForAllPolygonsInClump()

RwSetClumpVertexUV()

RwSetPolygonTexture()

RwSetPolygonUV()

RwSphericalTexturizeClump()


RwFindClump()

RwClump *

RwFindClump(RwClump *root, int (*func)(RwClump *clump));

RwClump *

RwFindClumpInt(RwClump *root, int (*func)(RwClump *clump, int arg), int arg);

RwClump *

RwFindClumpLong(RwClump *root, int (*func)(RwClump *clump, long arg), long arg);

RwClump *

RwFindClumpReal(RwClump *root, int (*func)(RwClump *clump, RPARAM arg), RPARAM arg);

RwClump *

RwFindClumpPointer(RwClump *root, int (*func)(RwClump *clump, void *arg), void *arg);

Description

Finds a particular clump in a hierarchy by applying a boolean call-back function to each clump in the hierarchy in turn. If any invocation of the call-back function returns TRUE, iteration is terminated and the clump passed as the argument to the call-back function is returned.

The call-back function can either be a RenderWare API function or user-defined. It is important to note that a return value of TRUE indicates success (i.e., the clump being sought was found) and stops iteration, while a return value of FALSE indicates that the search should continue. If the search fails (i.e., no predicate returns TRUE), NULL is returned.

The difference between RwFindClump() and its variations listed above is that for RwFindClump() the call-back function takes only one argument (a clump pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

root	Pointer to the root clump.

func	Pointer to the call-back function.

arg	A user supplied argument to be passed to the call-back function.

Return Value

A pointer to the clump found if the search was successful, and NULL if the search failed or if any errors occurred. Errors can be checked for using RwGetError().

Comments

The traversal of the clump hierarchy is done in a depth-first manner.

See Also

RwAddChildToClump()

RwFindTaggedClump()

RwForAllClumpsInHierarchy()

RwGetError()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()


RwFindNamedTexture()

RwTexture *

RwFindNamedTexture(char *name);

Description

Searches for a texture with the name name. If the current search mode is rwLOCAL, only the current dictionary is searched. If the current search mode is rwGLOBAL, the entire texture dictionary stack is searched. In the latter case, the search starts with the current texture dictionary, i.e., the top element of the stack, and proceeds downwards until a texture with the specified name is found or there are no more dictionaries to be examined.

Arguments

name	The texture name.

Return Value

A pointer to a texture. If there is an error or if no texture with that name is found, NULL is returned. Errors can be checked for using RwGetError().

Comments

This function only searches the current dictionary or dictionary stack. It will not attempt to load a texture from disk.

See Also

RwCreateTexture()

RwDestroyTexture()

RwForAllNamedTextures()

RwGetError()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadTexture()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetTextureDictSearchMode()

RwTextureDictBegin()

RwTextureDictEnd()


RwFindTaggedClump()

RwClump *

RwFindTaggedClump(RwClump *clump, int tag);

Description

Looks for the clump with the specified tag in the hierarchy rooted at clump.

Arguments

clump	Pointer to the clump.

tag	Integer tag to find.

Return Value

A pointer to the clump found if the search was successful, and NULL if the search failed or if any errors occurred. Errors can be checked for using RwGetError().

See Also

RwAddChildToClump()

RwFindClump()

RwFindTaggedPolygon()

RwForAllClumpsInHierarchy()

RwGetClumpTag()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()

RwSetClumpTag()

RwSetTag()


RwFindTaggedPolygon()

RwPolygon3d *

RwFindTaggedPolygon(RwClump *clump, short int tag);

Description

Looks for the polygon with the specified tag in the polygon list of clump.

Arguments

clump	Pointer to the clump.

tag	Integer tag to find.

Return Value

A pointer to the polygon found if the search was successful, and NULL if the search failed or if any errors occurred. Errors can be checked for using RwGetError().

See Also

RwForAllPolygonsInClump()

RwFindTaggedClump()

RwGetError()

RwGetPolygonTag()

RwPolygonExt()

RwQuadExt()

RwSetPolygonTag()

RwTriangleExt()


RwForAllClumpsInHierarchy()

RwClump *

RwForAllClumpsInHierarchy(RwClump *root, RwClump *(*func) (RwClump *clump));

RwClump *

RwForAllClumpsInHierarchyInt(RwClump *root, RwClump *(*func)(RwClump *clump, int arg), int arg);

RwClump *

RwForAllClumpsInHierarchyLong(RwClump *root, RwClump *(*func)(RwClump *clump, long arg), long arg);

RwClump *

RwForAllClumpsInHierarchyReal(RwClump *root, RwClump *(*func)(RwClump *clump, RPARAM arg), RPARAM arg);

RwClump *

RwForAllClumpsInHierarchyPointer(RwClump *root, RwClump *(*func)(RwClump *clump, void *arg), void *arg);

Description

Applies a call-back function to all clumps in the hierarchy whose root is pointed to by root. If any invocation of the call-back function sets RenderWare's error status, iteration is terminated. The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllClumpsInHierarchy() and its variations listed above is that for RwForAllClumpsInHierarchy() the call-back function takes only one argument (a clump pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

root	Pointer to the root clump.

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

If the return type of the call-back function is not RwClump *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwClump *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwClump*(*)())foo

The traversal of the clump hierarchy is done in a depth-first manner.

See Also

RwAddChildToClump()

RwFindClump()

RwFindTaggedClump()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()

RwSetUserError()


RwForAllClumpsInScene()

RwScene *

RwForAllClumpsInScene(RwScene *scene, RwClump *(*func) (RwClump *clump));

RwScene *

RwForAllClumpsInSceneInt(RwScene *scene, RwClump *(*func) (RwClump *clump, int arg), int arg);

RwScene *

RwForAllClumpsInSceneLong(RwScene *scene, RwClump *(*func) (RwClump *clump, long arg), long arg);

RwScene *

RwForAllClumpsInSceneReal(RwScene *scene, RwClump *(*func) (RwClump *clump, RPARAM arg), RPARAM arg);

RwScene *

RwForAllClumpsInScenePointer(RwScene *scene, RwClump *(*func) (RwClump *clump, void *arg), void *arg);

Description

Applies a call-back function to all clumps in the scene. If any invocation of the call-back function sets RenderWare's error status, iteration is terminated. The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllClumpsInScene() and its variations listed above is that for RwForAllClumpsInScene() the call-back function takes only one argument (a clump pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

scene	Pointer to the scene.

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function

Return Value

The argument scene if successful, and NULL otherwise.

Comments

If the return type of the call-back function is not RwClump *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwClump *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwClump*(*)())foo

See Also

RwAddClumpToScene()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwForAllClumpsInHierarchy()

RwForAllLightsInScene()

RwGetSceneNumClumps()

RwReadShape()

RwRemoveClumpFromScene()

RwSetUserError()


RwForAllLightsInScene()

RwScene *

RwForAllLightsInScene(RwScene *scene, RwLight *(*func) (RwLight *light));

RwScene *

RwForAllLightsInSceneInt(RwScene *scene, RwLight *(*func) (RwLight *light, int arg), int arg);

RwScene *

RwForAllLightsInSceneLong(RwScene *scene, RwLight *(*func) (RwLight *light, long arg), long arg);

RwScene *

RwForAllLightsInSceneReal(RwScene *scene, RwLight *(*func) (RwLight *light, RPARAM arg), RPARAM arg);

RwScene *

RwForAllLightsInScenePointer(RwScene *scene, RwLight *(*func)(RwLight *light, void *arg), void *arg);

Description

Applies a call-back function to all lights in the scene. If any invocation of the call-back function sets RenderWare's error status, iteration is terminated. The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllLightsInScene() and its variations listed above is that for RwForAllLightsInScene() the call-back function takes only one argument (a light pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

scene	Pointer to the scene.

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function.

Return Value

The argument scene if successful, and NULL otherwise.

Comments

If the return type of the call-back function is not RwLight *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwLight *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwLight*(*)())foo

See Also

RwAddLightToScene()

RwCreateLight()

RwDestroyLight()

RwForAllClumpsInScene()

RwGetSceneNumLights()

RwRemoveLightFromScene()


RwForAllNamedTextures()

int

RwForAllNamedTextures(RwTexture *(*func)(RwTexture *texture));

int

RwForAllNamedTexturesInt(RwTexture *(*func)(RwTexture *texture, int arg), int arg);

int

RwForAllNamedTexturesLong(RwTexture *(*func)(RwTexture *texture, long arg), long arg);

int

RwForAllNamedTexturesReal(RwTexture *(*func)(RwTexture *texture, RPARAM arg), RPARAM arg);

int

RwForAllNamedTexturesPointer(RwTexture *(*func)(RwTexture *texture, void *arg), void *arg);

Description

Applies a call-back function to all named textures. Depending on the current search mode, the scope is either the current texture dictionary (rwLOCAL) or the entire texture dictionary stack (rwGLOBAL). The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllNamedTextures() and its variations listed above is that for RwForAllNamedTextures() the call-back function takes only one argument (a texture pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If the return type of the call-back function is not RwTexture *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwTexture *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwTexture*(*)())foo

See Also

RwFindNamedTexture()

RwDestroyTexture()

RwGetNamedTexture()

RwReadNamedTexture()

RwSetTextureDictSearchMode()

RwSetUserError()

RwTextureDictBegin()

RwTextureDictEnd()


RwForAllPolygonsInClump()

RwClump *

RwForAllPolygonsInClump(RwClump *clump, RwPolygon3d *(*func)(RwPolygon3d *polygon));

RwClump *

RwForAllPolygonsInClumpInt(RwClump *clump, RwPolygon3d *(*func)(RwPolygon3d *polygon, int arg), int arg);

RwClump *

RwForAllPolygonsInClumpLong(RwClump *clump, RwPolygon3d *(*func)(RwPolygon3d *polygon, long arg), long arg);

RwClump *

RwForAllPolygonsInClumpReal(RwClump *clump, RwPolygon3d *(*func)(RwPolygon3d *polygon, RPARAM arg), RPARAM arg);

RwClump *

RwForAllPolygonsInClumpPointer(RwClump *clump, RwPolygon3d *(*func)(RwPolygon3d *polygon, void *arg), void *arg);

Description

Applies a call-back function to all polygons belonging to a given clump. If any invocation of the call-back function sets RenderWare's error status, iteration is terminated. The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllPolygonsInClump() and its variations listed above is that for RwForAllPolygonsInClump() the call-back function takes only one argument (a polygon pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

clump	Pointer to the clump.

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

If the return type of the call-back function is not RwPolygon3d *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwPolygon3d *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwPolygon3d*(*)()) foo

See Also

RwAddPolygonToClump()

RwAddPolygonsToClump()

RwFindTaggedPolygon()

RwGetClumpNumPolygons()

RwPolygon()

RwPolygonExt()

RwQuad()

RwQuadExt()

RwSetUserError()

RwTriangle()

RwTriangleExt()


RwForAllUserDrawsInClump()

RwClump *

RwForAllUserDrawsInClump(RwClump *clump, RwUserDraw *(*func)(RwUserDraw *userdraw));

RwClump *

RwForAllUserDrawsInClumpInt(RwClump *clump, RwUserDraw *(*func)(RwUserDraw *userdraw, int arg), int arg);

RwClump *

RwForAllUserDrawsInClumpLong(RwClump *clump, RwUserDraw *(*func)(RwUserDraw *userdraw, long arg), long arg);

RwClump *

RwForAllUserDrawsInClumpReal(RwClump *clump, RwUserDraw *(*func)(RwUserDraw *userdraw, RPARAM arg), RPARAM arg);

RwClump *

RwForAllUserDrawsInClumpPointer(RwClump *clump, RwUserDraw *(*func)(RwUserDraw *userdraw, void *arg), void *arg);

Description

Applies a call-back function to all user-draws belonging to a given clump. If any invocation of the call-back function sets RenderWare's error status, iteration is terminated. The call-back function can either be a RenderWare API function or a user-defined function. In the latter case, the call-back function should call RwSetUserError() if it fails for any reason.

The difference between RwForAllUserDrawsInClump() and its variations listed above is that for RwForAllUserDrawsInClump() the call-back function takes only one argument (a user-draw pointer), whereas in the case of its variations, the call-back function takes an additional, user-supplied argument (arg) that can be of type int, long, RPARAM or void* respectively.

Arguments

clump	Pointer to the clump.

func	Pointer to the call-back function.

arg	A user-supplied argument to be passed to the call-back function.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

If the return type of the call-back function is not RwUserDraw *, then the pointer to the call-back function should be cast to the expected type, i.e., a pointer to a function whose return type is RwUserDraw *. For example, in the case of a call-back function named foo whose return type is int, the following C expression should be used:

(RwUserDraw*(*)())foo

See Also

RwAddUserDrawToClump()

RwDuplicateUserDraw()

RwGetClumpNumUserDraws()

RwRemoveUserDrawFromClump()

RwSetUserError()


RwGetCameraBackColor()

RwRGBColor *

RwGetCameraBackColor(RwCamera *camera, RwRGBColor *color);

Description

Retrieves the camera's background fill color.

Arguments

camera	Pointer to the camera.

color	Pointer to the RwRGBColor that will receive the camera's color.

Return Value

The argument color if successful, and NULL otherwise.

See Also

RwClearCameraViewport()

RwGetCameraBackdrop()

RwGetCameraBackdropViewportRect()

RwSetCameraBackColorStruct()

RwSetCameraBackColorStruct()


RwGetCameraBackdrop()

RwRaster *

RwGetCameraBackdrop(RwCamera *camera);

Description

Retrieves the camera's backdrop raster.

Arguments

camera	Pointer to the camera.

Return Value

Pointer to the camera's backdrop raster if one has been set, and NULL if there is an error or if no backdrop raster is associated with the camera. Errors can be checked for using RwGetError().

See Also

RwDestroyRaster()

RwGetCameraBackColor()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwSetCameraBackdrop()


RwGetCameraBackdropOffset()

RwCamera *

RwGetCameraBackdropOffset(RwCamera *camera, int *x, int *y);

Description

Retrieves the offset (from the origin of the camera's backdrop viewport rectangle) of the camera's backdrop.

Arguments

camera 	Pointer to the camera.

<BULL>Pointer to integer to receive the horizontal offset (in viewport space units).

y	Pointer to integer to receive the vertical offset (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The x and y offset (modulo the width and height of the backdrop) specify the pixel in the backdrop which will be mapped to the origin of the backdrop viewport rectangle. Therefore, the effect of increasing the x offset will be to scroll the backdrop to the left and increasing the y offset will scroll the backdrop up.

See Also

RwGetCameraBackdrop()

RwGetCameraBackdropViewportRect()

RwSetCameraBackdrop()

RwSetCameraBackdropOffset()

RwSetCameraBackdropViewportRect()


RwGetCameraBackdropViewportRect()

RwCamera *

RwGetCameraBackdropViewportRect(RwCamera *camera, int *x, int *y, int *width, int *height);

Description

Retrieves the rectangular area of the viewport into which the camera's backdrop raster is rendered.

Arguments

camera	Pointer to the camera.

x	Pointer to integer to receive the x coordinate of rectangle (in viewport space coordinates).

y	Pointer to integer to receive the y coordinate of rectangle (in viewport space coordinates).

width	Pointer to integer to receive the width of the rectangle (in viewport space units).

height	Pointer to integer to receive the height of the rectangle (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

If the backdrop viewport rectangle is larger than the backdrop raster, the raster will be tiled to fill the rectangle. If the backdrop viewport rectangle is smaller than the backdrop raster, the raster will be cropped to the rectangle.

Areas of the viewport not covered by the backdrop will be filled with the camera's background color.

The backdrop viewport rectangle is not automatically changed when the camera' viewport is modified. RwSetCameraBackdropViewportRect() should be used to modify the backdrop viewport rectangle appropriately when the camera's viewport is modified.

See Also

RwGetCameraBackColor()

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropOffset()

RwSetCameraBackdropViewportRect()

RwSetCameraViewport()


RwGetCameraData()

void *

RwGetCameraData(RwCamera *camera);

Description

Retrieves the camera's user data pointer.

Arguments

camera	Pointer to the camera.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetCameraData()


RwGetCameraImage()

void *

RwGetCameraImage(RwCamera *camera);

Description

Retrieves a pointer to the camera's image buffer.

Arguments

camera	Pointer to the camera.

Return Value

A pointer to the image buffer if successful, and NULL otherwise.

Comments

The image buffer format is device dependent. For more information, see MS Windows 3.1 Specific Information.

See Also

RwCreateCamera()

RwCreateUserDraw()

RwDuplicateCamera()

RwDestroyCamera()


RwGetCameraLookAt()

RwV3d *

RwGetCameraLookAt(RwCamera *camera, RwV3d *vector);

Description

Retrieves the camera's "Look At" vector (the direction in which the camera points).

Arguments

camera	Pointer to the camera.

vector	Pointer to the vector that will receive the "Look At" vector.

Return Value

The argument vector if successful, and NULL otherwise.

See Also

RwGetCameraLookRight()

RwGetCameraLookUp()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwSetCameraLookAt()

RwTiltCamera()

RwTransformCameraOrientation()


RwGetCameraLookRight()

RwV3d *

RwGetCameraLookRight(RwCamera *camera, RwV3d *vector);

Description

Retrieves the camera's "Look Right" (or U) vector.

Arguments

camera	Pointer to the camera.

vector	Pointer to the vector that will receive the "Look Right" vector.

Return Value

The argument vector if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookUp()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwTransformCameraOrientation()


RwGetCameraLookUp()

RwV3d *

RwGetCameraLookUp(RwCamera *camera, RwV3d *vector);

Description

Retrieves the camera's "Look Up" (or V) vector.

Arguments

camera	Pointer to the camera.

vector	Pointer to the vector that will receive the "Look Up" vector.

Return Value

The argument vector if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookRight()

RwPointCamera()

RwRevolveCamera()

RwResetCamera()

RwSetCameraLookUp()

RwTiltCamera()

RwTransformCameraOrientation()


RwGetCameraNearClipping()

RPARAM

RwGetCameraNearClipping(RwCamera *camera);

Description

Retrieves the distance from the camera's position to the front clipping plane.

Arguments

camera	Pointer to the camera.

Return Value

The distance from the camera to the front clipping plane if successful, and CREAL(-1.0) otherwise.

See Also

RwCreateCamera()

RwSetCameraNearClipping()


RwGetCameraPosition()

RwV3d *

RwGetCameraPosition(RwCamera *camera, RwV3d *position);

Description

Retrieves the camera's position in world space.

Arguments

camera	Pointer to the camera.

position	Pointer to the point that will receive the camera's position (in world space coordinates).

Return Value

The argument position if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwDuplicateCamera()

RwResetCamera()

RwSetCameraPosition()

RwTransformCamera()

RwVCMoveCamera()

RwWCMoveCamera()


RwGetCameraProjection()

RwCameraProjection

RwGetCameraProjection(RwCamera *camera);

Description

Retrieves the camera's projection type.

Arguments

camera	Pointer to the camera.

Return Value

The camera's projection type if successful, and rwNACAMERAPROJECTION otherwise.

Comments

The projection types are:

•	rwPARALLEL    Parallel projection.

•	rwPERSPECTIVE    Perspective projection.

See Also

RwCreateCamera()

RwSetCameraProjection()


RwGetCameraViewOffset()

RwV3d *

RwGetCameraViewOffset(RwCamera *camera, RwV3d *offset);

Description

Retrieves the view offset of the camera.

Arguments

camera	Pointer to the camera.

offset	Pointer to the vector to receive the view offset.

Return Value

The argument offset if successful, and NULL otherwise.

Comments

The x field of offset will be set to the offset in the direction of the camera's  "Look Right" vector, the y field will be set to the offset in the direction "Look Up" vector, whilst the z field will be set to CREAL(0.0).

See Also

RwResetCamera()

RwSetCameraViewOffset()


RwGetCameraViewport()

RwCamera *

RwGetCameraViewport(RwCamera *camera, int *x, int *y, int *width, int *height);

Description

Retrieves the camera's viewport in device space coordinates.

Arguments

camera	Pointer to the camera.

x	Pointer to the integer that will receive the X coordinate of the top left corner of the viewport (in device space coordinates).

y	Pointer to the integer that will receive the Y coordinate of the top left corner of the viewport (in device space coordinates).

width	Pointer to the integer that will receive the width of the viewport (in device space units).

height	Pointer to the integer that will receive the height of the viewport (in device space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The viewport origin is the top left of the viewport.

See Also

RwGetCameraViewwindow()

RwResetCamera()

RwSetCameraViewport()

RwSetCameraViewwindow()


RwGetCameraViewportRaster()

RwRaster *

RwGetCameraViewportRaster(RwCamera *camera, RwRaster *raster);

Description

Copies the camera's viewport to the specified raster.

Arguments

camera	Pointer to the source camera.

raster	Pointer to the destination raster.

Return Value

The argument raster if successful, and NULL otherwise.

Comments

RwGetCameraViewportRaster() performs a straight copy. No conversion, filtering or color matching is performed. raster must have been previously created by RwCreateRaster() and must be large enough to hold the camera's viewport.

If the raster is to be subsequently used as a texture map the width and height of the camera's viewport must be 128.

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewport()

RwGetTextureRaster()

RwSetCameraViewport()

RwSetTextureRaster()


RwGetCameraViewwindow()

RwCamera *

RwGetCameraViewwindow(RwCamera *camera, RwReal *width, RwReal *height);

Description

Retrieves the width and height of the camera's view window in world space units.

Arguments

camera	Pointer to the camera.

width	Pointer to the RwReal that will receive the width of the view window (in world space units).

height	Pointer to the RwReal that will receive the height of the view window (in world space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwGetCameraViewport()

RwResetCamera()

RwSetCameraViewport()

RwSetCameraViewwindow()


RwGetClumpAxisAlignment()

RwAxisAlignment

RwGetClumpAxisAlignment(RwClump *clump);

Description

Retrieves the axis alignment type of the clump.

Arguments

clump	Pointer to the clump.

Return Value

The axis alignment type of the clump if successful, and rwNAAXISALIGNMENT otherwise.

Comments

The following axis alignment types are supported:

•	rwNOAXISALIGNMENT

The clump is not axis aligned, it is unconstrained.

•	rwALIGNAXISZORIENTX

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local X axis is preserved.

•	rwALIGNAXISZORIENTY

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local Y axis is preserved.

•	rwALIGNAXISXYZ

The local X, Y and Z axes of the clump are aligned with the camera's "Look Right", "Look Up" and "Look At" vectors respectively.

A clump that is axis aligned will be aligned with the view planes of all cameras used to view that clump.

See Also

RwCreateDecal()

RwCreateSprite()

RwSetAxisAlignment()

RwSetClumpAxisAlignment()


RwGetClumpBBox()

RwClump *

RwGetClumpBBox(RwClump *clump, RwV3d *bll, RwV3d *fur);

Description

Retrieves the bounding box of the clump in world space coordinates.

Arguments

clump	Pointer to the clump.

bll	Pointer to the point that will receive the back, lower, left coordinates of the bounding box (in world space coordinates).

fur	Pointer to the point that will receive the front, upper, right coordinates of the bounding box (in world space coordinates).

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Note that this function is not recursive - it returns the bounding box of the specified clump only and not its descendants.

See Also

RwGetClumpViewportRect()


RwGetClumpData()

void *

RwGetClumpData(RwClump *clump);

Description

Retrieves the clump's user data pointer.

Arguments

clump	Pointer to the clump.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer in NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetClumpData()


RwGetClumpHints()

RwClumpHints

RwGetClumpHints(RwClump *clump);

Description

Retrieves the hints associated with the clump.

Arguments

clump	Pointer to the clump.

Return Value

A bitfield representing a hint (or bitwise or of hints) associated with the clump. If there is an error or if no hints have been added to the clump, 0 is returned. Errors can be checked for using RwGetError().

Comments

The clump hints are:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

See Also

RwAddHintToClump()

RwGetError()

RwRemoveHintFromClump()

RwSetClumpHints()


RwGetClumpJointMatrix()

RwMatrix4d *

RwGetClumpJointMatrix(RwClump *clump, RwMatrix4d *matrix);

Description

Retrieves the clump's joint (articulation) matrix.

Arguments

clump	Pointer to the clump.

matrix	Pointer to the matrix that will receive the clump's joint (articulation) matrix.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwGetClumpLTM()

RwGetClumpMatrix()

RwNormalizeClump()

RwTransformClumpJoint()


RwGetClumpLTM()

RwMatrix4d *

RwGetClumpLTM(RwClump *clump, RwMatrix4d *matrix);

Description

Retrieves the clump's Local Transformation Matrix (LTM) which maps object space to world space.

Arguments

clump	Pointer to the clump.

matrix	Pointer to the matrix that will receive the clump's LTM.

Return Value

The argument matrix if successful, and NULL otherwise.

Comments

The clump's LTM is the result of the concatenation of all modelling and joint (articulation) matrices from this clump to the root of the hierarchy.

See Also

RwAddChildToClump()

RwGetClumpJointMatrix()

RwGetClumpMatrix()

RwGetClumpParent()

RwGetClumpRoot()

RwGetFirstChildClump()

RwGetNextClump()

RwNormalizeClump()

RwTransformClump()

RwTransformClumpJoint()


RwGetClumpMatrix()

RwMatrix4d *

RwGetClumpMatrix(RwClump *clump, RwMatrix4d *matrix);

Description

Retrieves the clump's modelling matrix.

Arguments

clump	Pointer to the clump.

matrix	Pointer to the matrix that will receive the clump's modelling matrix.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwGetClumpJointMatrix()

RwGetClumpLTM()

RwNormalizeClump()

RwTransformClump()


RwGetClumpNumChildren()

int

RwGetClumpNumChildren(RwClump *clump);

Description

Retrieves the number of children of the clump.

Arguments

clump	Pointer to the clump.

Return Value

The number of children of the clump if successful, and -1 otherwise.

Comments

This function returns the number of direct children of the clump and not the number of descendants of the clump in the hierarchy.

See Also

RwAddChildToClump()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()


RwGetClumpNumPolygons()

int

RwGetClumpNumPolygons(RwClump *clump);

Description

Retrieves the number of polygons in the clump.

Arguments

clump	Pointer to the clump.

Return Value

The number of polygons in the clump if successful, and -1 otherwise.

See Also

RwAddPolygonToClump()

RwAddPolygonsToClump()

RwDestroyPolygon()

RwForAllPolygonsInClump()

RwGetClumpNumVertices()

RwPolygon()

RwPolygonExt()

RwQuad()

RwQuadExt()

RwTriangle()

RwTriangleExt()


RwGetClumpNumUserDraws()

int

RwGetClumpNumUserDraws(RwClump *clump);

Description

Retrieves the number of user-draws owned by the clump.

Arguments

clump	Pointer to the clump.

Return Value

The number of user-draws owned by clump if successful, and -1 otherwise.

See Also

RwAddUserDrawToClump()

RwDestroyUserDraw()

RwDuplicateUserDraw()

RwForAllUserDrawsInClump()

RwRemoveUserDrawFromClump()


RwGetClumpNumVertices()

int

RwGetClumpNumVertices(RwClump *clump);

Description

Retrieves the number of vertices in the clump.

Arguments

clump	Pointer to the clump.

Return Value

The number of vertices in the clump if successful, and -1 otherwise.

See Also

RwAddVertexToClump()

RwGetClumpNumPolygons()

RwVertex()

RwVertexExt()


RwGetClumpOrigin()

RwV3d *

RwGetClumpOrigin(RwClump *clump, RwV3d *origin);

Description

Retrieves the origin of the clump's local coordinate (object) space in world space coordinates.

Arguments

clump	Pointer to the clump.

origin	Pointer to the point that will receive the clump's origin (in world space coordinates).

Return Value

The argument origin if successful, and NULL otherwise.

See Also

RwClumpDistance()

RwGetClumpLTM()


RwGetClumpOwner()

RwScene *

RwGetClumpOwner(RwClump *clump);

Description

Retrieves the scene that owns the clump.

Arguments

clump	Pointer to the clump.

Return Value

The scene that owns the clump if successful, and NULL otherwise.

See Also

RwAddClumpToScene()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwDuplicateClump()

RwReadShape()

RwRemoveClumpFromScene()


RwGetClumpParent()

RwClump *

RwGetClumpParent(RwClump *clump);

Description

Retrieves the clump's parent.

Arguments

clump	Pointer to the clump.

Return Value

A pointer to the parent clump. NULL is returned if the clump is the root of a hierarchy or if an error occurred. Errors can be checked for using RwGetError().

See Also

RwAddChildToClump()

RwGetClumpRoot()

RwGetError()

RwGetFirstChildClump()

RwRemoveChildFromClump()


RwGetClumpRoot()

RwClump *

RwGetClumpRoot(RwClump *clump);

Description

Retrieves the root of the clump hierarchy containing the clump.

Arguments

clump	Pointer to the clump.

Return Value

The root clump if successful, and NULL otherwise.

See Also

RwAddChildToClump()

RwGetClumpParent()

RwGetFirstChildClump()

RwGetNextClump()

RwRemoveChildFromClump()


RwGetClumpState()

RwState

RwGetClumpState(RwClump *clump);

Description

Retrieves the clump's on/off state.

Arguments

clump	Pointer to the clump.

Return Value

The clump's state if successful, and rwNASTATE otherwise.

Comments

The states are:

•	rwON    The clump is to be a candidate for rendering and picking.

•	rwOFF    The clump is not to be a candidate for rendering and picking.

A state of rwON should be interpreted as making a clump a candidate for rendering and picking. Such a clump will not be rendered if it lies outside the view volume and it will not be picked unless one of its polygons is the foremost under the pick position.

The state affects only the clump to which it is applied and not to that clump's children. Thus, to prevent a single clump in a hierarchy from being rendered it is preferable to modify the clump's state rather than to remove it from a scene with RwRemoveClumpFromScene().

See Also

RwAddClumpToScene()

RwDestroyClump()

RwRemoveClumpFromScene()

RwSetClumpState()


RwGetClumpTag()

int

RwGetClumpTag(RwClump *clump);

Description

Retrieves the integer tag associated with the clump.

Arguments

clump	Pointer to the clump.

Return Value

The clump's tag. Errors can be checked for using RwGetError().

See Also

RwFindTaggedClump()

RwGetError()

RwGetPolygonTag()

RwSetClumpTag()

RwSetTag()


RwGetClumpVertex()

RwV3d *

RwGetClumpVertex(RwClump *clump, int index, RwV3d *coords);

Description

Retrieves the object space coordinates of the vertex which belongs to clump and has the vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

coords	Pointer to the point that will receive the vertex's position (in object space coordinates).

Return Value

The argument coords if successful, and NULL otherwise.

Comments

The vertex index must be an integer greater than 0 and less than or equal to the number of vertices that belong to the clump.

See Also

RwGetClumpVertexNormal()

RwGetClumpVertexUV()

RwSetClumpVertex()

RwSetClumpVertices()


RwGetClumpVertexNormal()

RwV3d *

RwGetClumpVertexNormal(RwClump *clump, int index, RwV3d *normal);

Description

Returns the unit shading normal of the vertex which belongs to clump and has vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

normal	Pointer to the vector that will receive the unit shading normal.

Return Value

The argument normal if successful, and NULL otherwise.

Comments

The vertex index must be an integer greater than 0 and less than or equal to the number of vertices that belong to the clump.

See Also

RwCalculateClumpVertexNormal()

RwGetClumpVertex()

RwGetClumpVertexUV()

RwGetPolygonNormal()

RwSetClumpVertexNormal()

RwVertexExt()


RwGetClumpVertexUV()

RwUV *

RwGetClumpVertexUV(RwClump *clump, int index, RwUV *uv);

Description

Retrieves the texture (U, V) coordinates of the vertex which belongs to clump and has vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

uv	Pointer to the RwUV structure that will receive the texture coordinates of the vertex.

Return Value

The argument uv if successful, and NULL otherwise.

Comments

The vertex index must be an integer greater than 0 and less than or equal to the number of vertices that belong to the clump.

See Also

RwCubicTexturizeClump()

RwEnvMapClump()

RwGetClumpVertex()

RwGetClumpVertexNormal()

RwSetClumpVertexUV()

RwSetPolygonUV()

RwSphericalTexturizeClump()

RwVertexExt()


RwGetClumpVertexViewportPosition()

int

RwGetClumpVertexViewportPosition(RwClump *clump, int index, RwCamera *camera, int *x, int *y, int *visible);

Description

Retrieves the viewport space coordinates of the vertex belonging to clump with the vertex index index in the viewport of camera. visible indicates whether the vertex has been clipped from the view volume.

Arguments

clump	Pointer to the clump.

index	The vertex index.

camera	Pointer to the camera.

x	Pointer to integer to receive the x coordinate of the vertex (in viewport space coordinates).

y	Pointer to integer to receive the y coordinate of the vertex (in viewport space coordinates).

visible	Pointer to integer to receive TRUE if the vertex is visible, and FALSE if it has been clipped from the view volume.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If visible is FALSE the integer values pointed to by x and y are undefined.

See Also

RwGetClumpVertex()

RwGetClumpViewportRect()

RwSetClumpVertex()


RwGetClumpViewportRect()

RwClump *

RwGetClumpViewportRect(RwClump *clump, RwCamera *camera, int *x, int *y, int *width, int *height);

Description

Retrieves the 2D rectangle that encloses the projection of the clump onto the specified camera's viewport.

Arguments

clump	Pointer to the clump.

camera	Pointer to the camera.

x	Pointer to the integer that will receive the X coordinate of the top left corner of the rectangle (in viewport space coordinates).

y	Pointer to the integer that will receive the Ycoordinate of the top left corner of the rectangle (in viewport space coordinates).

width	Pointer to the integer that will receive the width of the rectangle (in viewport space units).

height	Pointer to the integer that will receive the height of the rectangle (in viewport space units).

Return Value

A pointer to the argument clump, and NULL otherwise.

See Also

RwDamageCameraViewport()

RwGetClumpBBox()

RwGetClumpVertexViewportPosition()

RwUndamageCameraViewport()


RwGetDebugAssertionState()

RwDebugState

RwGetDebugAssertionState(void);

Description

Gets the current state of assertion failure messages.

Arguments

None.

Return Value

The current state of assertion failure messages.

Comments

The assertion message states are:

•	rwENABLE    Assertion messages are enabled.

•	rwDISABLE    Assertion messages are disabled.

See Also

RwGetDebugMessageState()

RwGetDebugScriptState()

RwSetDebugAssertionState()

RwSetDebugOutputState()


RwGetDebugMessageState()

RwDebugState

RwGetDebugMessageState(void);

Description

Gets the current state of miscellaneous messages.

Arguments

None.

Return Value

The current state of miscellaneous messages.

Comments

The miscellaneous message states are:

•	rwENABLE     Miscellaneous messages are enabled.

•	rwDISABLE     Miscellaneous messages are disabled.

See Also

RwGetDebugAssertionState()

RwGetDebugScriptState()

RwSetDebugMessageState()

RwSetDebugOutputState()


RwGetDebugScriptState()

RwDebugState

RwGetDebugScriptState(void);

Description

Gets the current state of scripting trace messages.

Arguments

None.

Return Value

The current state of scripting trace messages.

Comments

The script trace message states are:

•	rwENABLE     Script trace messages are enabled.

•	rwDISABLE     Script trace messages are disabled.

See Also

RwGetDebugAssertionState()

RwGetDebugMessageState()

RwSetDebugOutputState()

RwSetDebugScriptState()


RwGetDebugSeverity()

RwDebugSeverity

RwGetDebugSeverity(void);

Description

Gets the current minimum severity level for the reporting of debugging messages.

Arguments

None.

Return Value

The current debug severity level.

Comments

The debug message severity levels are:

•	rwINFORM    Control flow annotations, non-fatal exceptions and fatal exceptions are all enabled.

•	rwWARNING    Non-fatal exceptions and fatal exceptions are enabled.

•	rwERROR    Fatal exceptions are enabled.

See Also

RwSetDebugSeverity()


RwGetDeviceInfo()

int

RwGetDeviceInfo(RwDeviceInfo info, void *value);

Description

Retrieves information about an aspect of the current RenderWare device driver. The specific information to query is given by info.

Arguments

info	Aspect of current device driver to query.

value	Pointer to a buffer to receive the result of the query. The actual data type of value is dependent on the value of info.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The value parameter of each device information type is as follows:

•	rwRENDERDEPTH    A pointer to integer to receive the current depth (in bits) of rendering.

•	rwINDEXEDRENDERING     A pointer to integer (boolean) which will be non-zero if rendering is indexed color based and zero if direct color based.

•	rwPALETTEBASED    A pointer to integer (boolean) which will be non-zero if the output device has a palette that RenderWare will attempt to modify, and zero if the output device uses direct color.

The following options apply if the device is rendering using an indexed color scheme:

•	rwINDEXEDCOLORMODEL     A pointer to integer to receive a number indicating the current indexed color model. The only supported value in this release of RenderWare is rwRAMPBASED which indicates a color model consisting of a series of ramps.

The following options apply to devices rendering using indexed color with a ramp based color model:

•	rwNUMCOLRAMPS    A pointer to integer to receive the number of color ramps in the palette.

•	rwCOLRAMPSIZE    A pointer to integer to receive the number of entries in each color ramp.

The following options apply when the output device is palette based:

•	rwPALETTE    A pointer to a device specific value which will receive a device dependent RenderWare palette object. See MS Windows 3.1 Specific Information for a description of this parameter.

•	rwPALETTESIZE    A pointer to integer to receive the number of entries in the entire palette (this will normally be 256 for 8-bit devices).

•	rwFIRSTPALETTEENTRY     A pointer to integer to receive the palette index of the first palette entry used by RenderWare.

•	rwLASTPALETTEENTRY     A pointer to integer to receive the palette index of the last palette entry used by RenderWare.

Further information types may be supported by specific device drivers. See MS Windows 3.1 Specific Information for more information.

See Also

RwDeviceControl()

RwGetSystemInfo()

RwOpenExt()


RwGetError()

RwErrorCode

RwGetError(void);

Description

Gets the value of RenderWare's global error status (as set by the first function that generated an error since the last call to RwGetError()) and then clears the error status.

Arguments

None.

Return Value

An error code indicating the type of error that has occurred if the error status has been set. If no error has been set then E_RW_NOERROR is returned.

See Also

RwGetInternalError()

RwSetUserError()


RwGetFirstChildClump()

RwClump *

RwGetFirstChildClump(RwClump *clump);

Description

Retrieves the first child of the clump.

Arguments

clump	Pointer to the clump.

Return Value

A pointer to the child clump. NULL is returned if the clump has no children or an error occurred. Errors can be checked for using RwGetError().

Comments

In the absence of any deletions, the first child of a clump is the one that was first added to the clump using RwAddChildToClump().

See Also

RwAddChildToClump()

RwGetClumpNumChildren()

RwGetClumpParent()

RwGetError()

RwGetNextClump()

RwRemoveChildFromClump()


RwGetInternalError()

long

RwGetInternalError(void);

Description

Retrieves a code representing the type of internal error that has occurred.

Arguments

None.

Return Value

The internal error code.

Comments

In the unlikely event that RwGetError() returns E_RW_INTERNAL, this function should be called in order to retrieve the internal error code. The number returned can then be reported to the RenderWare technical support department.

See Also

RwGetError()

RwSetUserError()


RwGetLightBrightness()

RPARAM

RwGetLightBrightness(RwLight *light);

Description

Retrieves the light's brightness.

Arguments

light	Pointer to the light.

Return Value

The brightness of the light if successful. Errors can be checked for using RwGetError().

See Also

RwCreateLight()

RwGetError()

RwSetLightBrightness()


RwGetLightConeAngle()

RPARAM

RwGetLightConeAngle(RwLight *light);

Description

Retrieves the cone angle of a conical or point light.

Arguments

light	Pointer to the light.

Return Value

The cone angle of the light if successful. Errors can be checked for using RwGetError().

Comments

For a point light source, CREAL(180.0) is returned.

See Also

RwCreateLight()

RwGetError()

RwSetLightConeAngle()


RwGetLightData()

void *

RwGetLightData(RwLight *light);

Description

Retrieves the light's user data pointer.

Arguments

light	Pointer to the light.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetLightData()


RwGetLightOwner()

RwScene *

RwGetLightOwner(RwLight *light);

Description

Retrieves the scene that owns the light.

Arguments

light	Pointer to the light.

Return Value

The scene that owns the light if successful, and NULL otherwise.

See Also

RwAddLightToScene()

RwCreateLight()

RwRemoveLightFromScene()


RwGetLightPosition()

RwV3d *

RwGetLightPosition(RwLight *light, RwV3d *position);

Description

Retrieves the position of a point or conical light in world space coordinates.

Arguments

light	Pointer to the light.

position	Pointer to the point that will receive the light's position (in world space coordinates).

Return Value

The argument position if successful, and NULL otherwise.

See Also

RwCreateLight()

RwSetLightPosition()

RwTransformLight()


RwGetLightState()

RwState

RwGetLightState(RwLight *light);

Description

Retrieves the light's on/off state.

Arguments

light	Pointer to the light.

Return Value

The light's state if successful, and rwNASTATE otherwise.

Comments

The states are:

•	rwON    The light is on.

•	rwOFF    The light is off.

See Also

RwCreateLight()

RwGetClumpState()

RwSetLightState()


RwGetLightType()

RwLightType

RwGetLightType(RwLight *light);

Description

Retrieves the type of the light.

Arguments

light	Pointer to the light.

Return Value

The light type if successful, and rwNALIGHTTYPE otherwise.

Comments

The light types are:

•	rwDIRECTIONAL    A directional light source.

•	rwPOINT    A point light source.

•	rwCONICAL    A conical (or spot) light source.

See Also

RwCreateLight()


RwGetLightVector()

RwV3d *

RwGetLightVector(RwLight *light, RwV3d *vector);

Description

Retrieves the illumination vector of a directional or conical light.

Arguments

light	Pointer to the light.

vector	Pointer to a vector that will receive the light's vector.

Return Value

The argument vector if successful, and NULL otherwise.

See Also

RwCreateLight()

RwSetLightVector()

RwTransformLight()


RwGetMaterialAmbient()

RPARAM

RwGetMaterialAmbient(RwMaterial *material);

Description

Retrieves the material's ambient reflection coefficient.

Arguments

material	Pointer to the material.

Return Value

The ambient reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialDiffuse()

RwGetMaterialSpecular()

RwGetPolygonAmbient()

RwSetMaterialAmbient()

RwSetMaterialSurface()


RwGetMaterialColor()

RwRGBColor *

RwGetMaterialColor(RwMaterial *material, RwRGBColor *color);

Description

Retrieves the material's color.

Arguments

material	Pointer to the material.

color	Pointer to the RwRGBColor that will receive the material's color.

Return Value

The argument color if successful, and NULL otherwise.

See Also

RwGetPolygonColor()

RwSetMaterialColor()

RwSetMaterialColorStruct()


RwGetMaterialDiffuse()

RPARAM

RwGetMaterialDiffuse(RwMaterial *material);

Description

Retrieves the material's diffuse reflection coefficient.

Arguments

material	Pointer to the material.

Return Value

The diffuse reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialAmbient()

RwGetMaterialSpecular()

RwGetPolygonDiffuse()

RwSetMaterialDiffuse()

RwSetMaterialSurface()


RwGetMaterialGeometrySampling()

RwGeometrySampling

RwGetMaterialGeometrySampling(RwMaterial *material);

Description

Retrieves the material's geometry sampling type.

Arguments

material	Pointer to the material.

Return Value

The material's geometry sampling type if successful, and rwNAGEOMETRYSAMPLING otherwise.

Comments

The geometry sampling types are:

•	rwPOINTCLOUD    Render geometry as a cloud of points.

•	rwWIREFRAME    Render geometry as a wireframe of polygon edges.

•	rwSOLID    Render geometry as a solid bounded by filled polygons.

See Also

RwGetMaterialLightSampling()

RwGetPolygonGeometrySampling()

RwSetMaterialGeometrySampling()


RwGetMaterialLightSampling()

RwLightSampling

RwGetMaterialLightSampling(RwMaterial *material);

Description

Retrieves the material's light sampling type.

Arguments

material	Pointer to the material.

Return Value

The material's light sampling type if successful, and rwNALIGHTSAMPLING otherwise.

Comments

The light sampling types are:

•	rwFACET    Flat shading.

•	rwVERTEX    Smooth shading.

See Also

RwGetMaterialGeometrySampling()

RwGetPolygonLightSampling()

RwSetMaterialLightSampling()


RwGetMaterialOpacity()

RPARAM

RwGetMaterialOpacity(RwMaterial *material);

Description

Retrieves the material's opacity

Arguments

material	Pointer to the material.

Return Value

The opacity if successful. Errors can be checked for using RwGetError().

Comments

An opacity of CREAL(1.0) yields an entirely opaque material. An opacity of CREAL(0.0) yields an entirely transparent material.

See Also

RwGetError()

RwGetPolygonOpacity()

RwSetMaterialOpacity()


RwGetMaterialSpecular()

RPARAM

RwGetMaterialSpecular(RwMaterial *material);

Description

Retrieves the material's specular reflection coefficient.

Arguments

material	Pointer to the material.

Return Value

The specular reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialAmbient()

RwGetMaterialDiffuse()

RwGetPolygonSpecular()

RwSetMaterialSpecular()

RwSetMaterialSurface()


RwGetMaterialTexture()

RwTexture *

RwGetMaterialTexture(RwMaterial *material);

Description

Retrieves the material's texture.

Arguments

material	Pointer to the material.

Return Value

A pointer to the material's texture if successful, and NULL if there is no texture associated with the material or if there is an error. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialTextureModes()

RwGetPolygonTexture()

RwSetMaterialTextureModes()


RwGetMaterialTextureModes()

RwTextureModes

RwGetMaterialTextureModes(RwMaterial *material);

Description

Retrieves the material's texture mode (or modes).

Arguments

material	Pointer to the material.

Return Value

The material's texture modes if successful. Errors can be checked for using RwGetError().

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToMaterial()

RwGetError()

RwGetMaterialTextureModes()

RwGetPolygonTextureModes()

RwRemoveTextureModeFromSurface()

RwSetMaterialTextureModes()


RwGetMatrixElement()

RPARAM

RwGetMatrixElement(RwMatrix4d *matrix, int row, int column);

Description

Retrieves the value of an individual element of the matrix.

Arguments

matrix	Pointer to the matrix.

row	Row index in the range 0 to 3.

column	Column index in the range 0 to 3.

Return Value

The matrix element if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMatrixElements()

RwSetMatrixElement()

RwSetMatrixElements()


RwGetMatrixElements()

RwReal *

RwGetMatrixElements(RwMatrix4d * matrix, RwReal elements[4][4]);

Description

Retrieves the elements of a matrix into a four by four array of RwReals. The top row of the matrix is copied into the first four array entries.

Arguments

matrix	Pointer to the matrix.

elements	Pointer to a four by four array of RwReals to receive the elements of the matrix.

Return Value

The argument elements if successful, and NULL otherwise.

Comments

By convention a matrix is taken to transform a row vector by post multiplication.

This function supersedes the V1.2 API function RwGetMatrix() which had similar semantics but returned matrix elements in a different order. RwGetMatrix() is no longer a supported RenderWare API call and must be replaced by RwGetMatrixElements().

See Also

RwGetMatrixElement()

RwSetMatrixElement()

RwSetMatrixElements()


RwGetNamedTexture()

RwTexture *

RwGetNamedTexture(char *name);

Description

Searches for the named texture. If the current search mode is rwLOCAL, the function searches only the current dictionary. If the current search mode is rwGLOBAL, the function searches the whole of the texture dictionary stack. If the search fails, an attempt is made to read the named texture from disk. If the named texture is found, it is stored into the current texture dictionary.

Arguments

name	Name of a texture.

Return Value

A pointer to the named texture if successful, and NULL otherwise.

Comments

The string supplied as the texture name should form the leaf part (i.e., without path or extension) of the filename of the texture file. Furthermore, for the sake of portability of texture files across the different platforms supported by RenderWare, it is best to choose texture file names that are a maximum of eight characters long and which are acceptable to MS-DOS as file names.

If the function cannot find the named texture in the texture dictionary stack, it will look for a texture file in the directories whose names appear in the shape path. Furthermore, if the specified name does not have a file extension, then this function will also search for the specified name followed by the extensions ".ras", ".env", ".tex", ".bmp" and ".rle".

An example of a valid texture is "marble", which will match with file names "marble", "marble.tex", "marble.ras", "marble.env", "marble.bmp" and "marble.rle".

See Also

RwCreateTexture()

RwDestroyTexture()

RwFindNamedTexture()

RwForAllNamedTextures()

RwGetShapePath()

RwReadNamedTexture()

RwReadTexture()

RwSetShapePath()

RwSetTextureDictSearchMode()

RwTextureDictBegin()

RwTextureDictEnd()


RwGetNextClump()

RwClump *

RwGetNextClump(RwClump *clump);

Description

Retrieves the next sibling of the clump.

Arguments

clump	Pointer to the clump.

Return Value

A pointer to the sibling clump. NULL is returned if the clump has no next sibling or an error occurred. Errors can be checked for using RwGetError().

See Also

RwAddChildToClump()

RwGetClumpNumChildren()

RwGetClumpParent()

RwGetError()

RwGetFirstChildClump()

RwRemoveChildFromClump()


RwGetNumNamedTextures()

int

RwGetNumNamedTextures(void);

Description

Retrieves the number of named textures in either the current texture dictionary or in all dictionaries in the texture dictionary stack.

Arguments

None.

Return Value

The number of named textures if successful, and -1 otherwise.

Comments

If the texture dictionary search mode is rwLOCAL, the number of textures in the current texture dictionary is returned. If the search mode is rwGLOBAL the number of textures in all dictionaries on the texture dictionary stack is returned.

See Also

RwDestroyTexture()

RwFindNamedTexture()

RwGetNamedTexture()

RwReadNamedTexture()

RwSetTextureDictSearchMode()

RwTextureDictBegin()

RwTextureDictEnd()


RwGetPolygonAmbient()

RPARAM

RwGetPolygonAmbient(RwPolygon3d *polygon);

Description

Retrieves the ambient reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The ambient reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialAmbient()

RwGetPolygonDiffuse()

RwGetPolygonSpecular()

RwSetPolygonAmbient()

RwSetPolygonSurface()


RwGetPolygonCenter()

RwV3d *

RwGetPolygonCenter(RwPolygon3d *polygon, RwV3d *center);

Description

Retrieves the center of the polygon in object space coordinates.

Arguments

polygon	Pointer to the polygon.

center	Pointer to point that will receive the polygon center (in object space coordinates).

Return Value

The argument center if successful, and NULL otherwise.

See Also

RwGetPolygonNormal()


RwGetPolygonColor()

RwRGBColor *

RwGetPolygonColor(RwPolygon3d *polygon, RwRGBColor *color);

Description

Retrieves the color of the polygon's material.

Arguments

polygon	Pointer to the polygon.

color	Pointer to the RwRGBColor that will receive the material's color.

Return Value

The argument color if successful, and NULL otherwise.

See Also

RwGetMaterialColor()

RwSetPolygonColor()

RwSetPolygonColorStruct()


RwGetPolygonData()

void *

RwGetPolygonData(RwPolygon3d *polygon);

Description

Retrieves the polygon's user data pointer.

Arguments

polygon	Pointer to the polygon.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetPolygonData()


RwGetPolygonDiffuse()

RPARAM

RwGetPolygonDiffuse(RwPolygon3d *polygon);

Description

Retrieves the diffuse reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The diffuse reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialDiffuse()

RwGetPolygonAmbient()

RwGetPolygonSpecular()

RwSetPolygonDiffuse()

RwSetPolygonSurface()


RwGetPolygonGeometrySampling()

RwGeometrySampling

RwGetPolygonGeometrySampling(RwPolygon3d *polygon);

Description

Retrieves the geometry sampling type of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The geometry sampling type of the polygon's material if successful, and rwNAGEOMETRYSAMPLING otherwise.

Comments

The geometry sampling types are:

•	rwPOINTCLOUD    Render geometry as a cloud of points.

•	rwWIREFRAME    Render geometry as a wireframe of polygon edges.

•	rwSOLID    Render geometry as a solid bounded by filled polygons.

See Also

RwGetMaterialGeometrySampling()

RwGetPolygonLightSampling()

RwSetPolygonGeometrySampling()


RwGetPolygonLightSampling()

RwLightSampling

RwGetPolygonLightSampling(RwPolygon3d *polygon);

Description

Retrieves the light sampling type of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The light sampling type of the polygon's material if successful, and rwNALIGHTSAMPLING otherwise.

Comments

The light sampling types are:

•	rwFACET    Flat shading.

•	rwVERTEX    Smooth shading.

See Also

RwGetMaterialLightSampling()

RwGetPolygonGeometrySampling()

RwSetPolygonLightSampling()


RwGetPolygonMaterial()

RwMaterial *

RwGetPolygonMaterial(RwPolygon3d *polygon);

Description

Retrieves the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

Pointer to the polygon's material if successful, and NULL otherwise.

Comments

Do not attempt to destroy the material returned by this function.

See Also

RwDestroyMaterial()

RwGetPolygonAmbient()

RwGetPolygonColor()

RwGetPolygonDiffuse()

RwGetPolygonGeometrySampling()

RwGetPolygonLightSampling()

RwGetPolygonOpacity()

RwGetPolygonSpecular()

RwGetPolygonTexture()

RwGetPolygonTextureModes()

RwSetPolygonMaterial()


RwGetPolygonNormal()

RwV3d *

RwGetPolygonNormal(RwPolygon3d *polygon, RwV3d *normal);

Description

Retrieves the polygon's surface normal vector.

Arguments

polygon	Pointer to the polygon.

normal	Pointer to the vector that will receive the polygon normal.

Return Value

The argument normal if successful, and NULL otherwise.

See Also

RwGetClumpVertexNormal()

RwGetPolygonCenter()


RwGetPolygonNumSides()

int

RwGetPolygonNumSides(RwPolygon3d *polygon);

Description

Retrieves the number of sides of the polygon.

Arguments

polygon	Pointer to the polygon.

Return Value

The number of sides of the polygon if successful, and 0 otherwise.

See Also

RwGetPolygonVertices()


RwGetPolygonOpacity()

RPARAM

RwGetPolygonOpacity(RwPolygon3d *polygon);

Description

Retrieves the opacity of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The opacity if successful. Errors can be checked for using RwGetError().

Comments

An opacity of CREAL(1.0) yields an entirely opaque polygon. An opacity of CREAL(0.0) yields an entirely transparent polygon.

See Also

RwGetError()

RwGetMaterialOpacity()

RwSetPolygonOpacity()


RwGetPolygonOwner()

RwClump *

RwGetPolygonOwner(RwPolygon3d *polygon);

Description

Retrieves the clump that owns the polygon.

Arguments

polygon	Pointer to the polygon.

Return Value

A pointer to the clump that owns the polygon if successful, and NULL otherwise.

See Also

RwFindTaggedPolygon()

RwForAllPolygonsInClump()


RwGetPolygonSpecular()

RPARAM

RwGetPolygonSpecular(RwPolygon3d *polygon);

Description

Retrieves the specular reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The specular reflection coefficient if successful. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialSpecular()

RwGetPolygonAmbient()

RwGetPolygonDiffuse()

RwSetPolygonSpecular()


RwGetPolygonTag()

short int

RwGetPolygonTag(RwPolygon3d *polygon);

Description

Retrieves the polygon's tag.

Arguments

polygon	Pointer to the polygon.

Return Value

The polygon's tag if successful. Errors can be checked for using RwGetError().

See Also

RwFindTaggedPolygon()

RwGetError()

RwGetClumpTag()

RwPolygonExt()

RwQuadExt()

RwSetPolygonTag()

RwVertexExt()


RwGetPolygonTexture()

RwTexture *

RwGetPolygonTexture(RwPolygon3d *polygon);

Description

Retrieves the texture of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

A pointer to the texture of the polygon's material. NULL is returned if there is no texture associated with the polygon's material or if there is an error. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetMaterialTextureModes()

RwSetPolygonTexture()


RwGetPolygonTextureModes()

RwTextureModes

RwGetPolygonTextureModes(RwPolygon3d *polygon);

Description

Retrieves the texture mode (or modes) of the polygon's material.

Arguments

polygon	Pointer to the polygon.

Return Value

The polygon's material's texture modes if successful. Errors can be checked for using RwGetError().

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToPolygon()

RwGetError()

RwGetMaterialTextureModes()

RwRemoveTextureModeFromSurface()

RwSetPolygonTexture()

RwSetPolygonTextureModes()


RwGetPolygonUV()

RwUV *

RwGetPolygonUV(RwPolygon3d *polygon, RwUV *uvarray);

Description

Retrieves the texture (U, V) coordinates of the vertices of the polygon.

Arguments

polygon	Pointer to the polygon.

uvarray	An array of RwUV structures that will receive the texture coordinates of the polygon's vertices.

Return Value

The argument uvarray if successful, and NULL otherwise.

Comments

The size of the array uvarray must match the number of the vertices of the polygon.

See Also

RwCubicTexturizeClump()

RwEnvMapClump()

RwGetClumpVertexUV()

RwGetPolygonNumSides()

RwSetClumpVertexUV()

RwSetPolygonUV()

RwSphericalTexturizeClump()

RwVertexExt()


RwGetPolygonVertices()

int

RwGetPolygonVertices(RwPolygon3d *polygon, int *vlist);

Description

Retrieves the polygon's vertex indices.

Arguments

polygon	Pointer to the polygon.

vlist	Pointer to an array of integers that will receive the vertex indices.

Return Value

The number of vertices if successful, and 0 otherwise.

See Also

RwAddPolygonToClump()

RwGetPolygonNumSides()

RwGetPolygonUV()


RwGetRasterData()

void *

RwGetRasterData(RwRaster *raster);

Description

Retrieves the raster's user data pointer.

Arguments

raster	Pointer to the raster.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetRasterData()


RwGetRasterDepth()

int

RwGetRasterDepth(RwRaster *raster);

Description

Retrieves the depth (in bits) of the raster.

Arguments

raster	Pointer to the raster.

Return Value

The depth (in bits) of raster if successful, and -1 otherwise.

Comments

The raster depth is always equal to RenderWare's current render depth.

See Also

RwBitmapRaster()

RwCreateRaster()

RwGetDeviceInfo()

RwGetRasterHeight()

RwGetRasterPixels()

RwGetRasterStride()

RwGetRasterWidth()

RwReadMaskRaster()

RwReadRaster()


RwGetRasterHeight()

int

RwGetRasterHeight(RwRaster *raster);

Description

Retrieves the height (in pixels) of the raster.

Arguments

raster	Pointer to the raster.

Return Value

The height (in pixels) of raster if successful, and -1 otherwise.

See Also

RwBitmapRaster()

RwCreateRaster()

RwGetRasterDepth()

RwGetRasterPixels()

RwGetRasterStride()

RwGetRasterWidth()

RwReadMaskRaster()

RwReadRaster()


RwGetRasterPixels()

unsigned char *

RwGetRasterPixels(RwRaster *raster);

Description

Retrieves a pointer to the pixels of the raster.

Arguments

raster	Pointer to the raster.

Return Value

A pointer to the pixels of raster if successful, and NULL otherwise.

Comments

The pointer returned by this function points to an array of bytes organized into RwGetRasterHeight() scan lines. Each scan line is RwGetRasterStride() bytes in width.

The pixel format is dependent on the raster's depth. For an 8 bit raster each pixel occupies a single byte. This byte is an index into the RenderWare color palette. For a 16 bit raster each pixel occupies two bytes which are interpreted as a short (16 bit) integer. This integer represents a direct, RGB color specification. The least significant five bits (bits 0 - 4) are the blue channel, the next six bits (bits 5 - 10) are the green channel and the most significant five bits (bits 11 - 15) are the red channel.

See Also

RwBitmapRaster()

RwCreateRaster()

RwGetRasterDepth()

RwGetRasterHeight()

RwGetRasterStride()

RwGetRasterWidth()

RwReadMaskRaster()

RwReadRaster()


RwGetRasterStride()

int

RwGetRasterStride(RwRaster *raster);

Description

Retrieves the stride (width in bytes) of the raster.

Arguments

raster	Pointer to the raster.

Return Value

The stride (width in bytes) of raster if successful, and -1 otherwise.

See Also

RwBitmapRaster()

RwCreateRaster()

RwGetRasterDepth()

RwGetRasterHeight()

RwGetRasterPixels()

RwGetRasterWidth()

RwReadMaskRaster()

RwReadRaster()


RwGetRasterWidth()

int

RwGetRasterWidth(RwRaster *raster);

Description

Retrieves the width (in pixels) of the raster.

Arguments

raster	Pointer to the raster.

Return Value

The width (in pixels) of raster if successful, and -1 otherwise.

See Also

RwBitmapRaster()

RwCreateRaster()

RwGetRasterDepth()

RwGetRasterHeight()

()

REF RwGetRasterStride()

RwReadMaskRaster()

RwReadRaster()


RwGetSceneData()

void *

RwGetSceneData(RwScene *scene);

Description

Retrieves the scene's user data pointer.

Arguments

scene	Pointer to the scene.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetSceneData()


RwGetSceneNumClumps()

int

RwGetSceneNumClumps(RwScene *scene);

Description

Retrieves the number of clumps in the scene.

Arguments

scene	Pointer to the scene.

Return Value

The number of clumps in the scene if successful, and -1 otherwise.

See Also

RwAddClumpToScene()

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwForAllClumpsInScene()

RwGetSceneNumLights()

RwReadShape()

RwRemoveClumpFromScene()


RwGetSceneNumLights()

int

RwGetSceneNumLights(RwScene *scene);

Description

Retrieves the number of lights in the scene.

Arguments

scene	Pointer to the scene.

Return Value

The number of lights in the scene if successful, and -1 otherwise.

See Also

RwAddLightToScene()

RwCreateLight()

RwForAllLightsInScene()

RwGetSceneNumClumps()

RwRemoveLightFromScene()


RwGetShapePath()

char *

RwGetShapePath(char *path);

Description

Retrieves the current shape path.

Arguments

path	Pointer to the string that will receive the path. The required size of path is defined by RWMAXPATHLEN.

Return Value

The argument path if successful, and NULL otherwise.

See Also

RwGetNamedTexture()

RwReadNamedTexture()

RwReadShape()

RwReadRaster()

RwReadMaskRaster()

RwReadTexture()

RwSetShapePath()

RwSetSurfaceTexture()

RwSetSurfaceTextureExt()


RwGetSplineData()

void *

RwGetSplineData(RwSpline *spline);

Description

Retrieves the spline's user data pointer.

Arguments

spline	Pointer to the spline.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetSplineData()


RwGetSplineNumPoints()

int

RwGetSplineNumPoints(RwSpline *spline);

Description

Retrieves the number of control points of the spline.

Arguments

spline	Pointer to the spline.

Return Value

Number of control points if successful, and 0 otherwise.

See Also

RwCreateSpline()

RwGetSplinePoint()

RwSetSplinePoint()


RwGetSplinePoint()

RwV3d *

RwGetSplinePoint(RwSpline *spline, int index, RwV3d *point);

Description

Retrieves the specified control point of the spline.

Arguments

spline	Pointer to the spline.

index	Index of the control point to get, in the range 1 £ index £ total number of control points.

point	Pointer to the point that will receive the specified control point.

Return Value

The argument point if successful, and NULL otherwise.

Comments

Note that an index of 1 will retrieve the first control point.

See Also

RwCreateSpline()

RwGetSplineNumPoints()

RwSetSplinePoint()


RwGetSystemInfo()

int

RwGetSystemInfo(RwSystemInfo info, void *value);

Description

Retrieves information about an aspect of the RenderWare system. The particular aspect of system configuration to query is given by info.

Arguments

info	Aspect of RenderWare system configuration to query.

value	Pointer to a buffer to receive the result of the query. The actual data type of value is dependent on the value of info.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The value parameter for each system information type is as follows:

•	rwVERSIONSTRING    A pointer to an array of characters which will receive a version string of the form "NN.nn rel". Where "NN" is the major version number of the RenderWare library being used, "nn" is the minor version number and "rel" is a string identifying the release. For example, "1.3 FCS".

•	rwVERSIONMAJOR    A pointer to an integer which will receive the major version number of the RenderWare library being used.

•	rwVERSIONMINOR    A pointer to an integer which will receive the minor version number of the RenderWare library being used.

•	rwVERSIONRELEASE    A pointer to an array of characters which will receive a string identify the particular release of the RenderWare library being used.

•	rwFIXEDPOINTLIB    A pointer to an integer (boolean) which will be non-zero if the RenderWare library uses fixed point arithmetic, and zero if the library uses floating point arithmetic.

•	rwDEBUGGINGLIB    A pointer to an integer (boolean) which will be non-zero if a debugging RenderWare library is being used, and zero if a production library is being used.

See Also

RwGetDeviceInfo()

RwOpenExt()


RwGetTextureData()

void *

RwGetTextureData(RwTexture *texture);

Description

Retrieves the texture's user data pointer.

Arguments

texture	Pointer to the texture.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetTextureData()


RwGetTextureDictSearchMode()

RwSearchMode

RwGetTextureDictSearchMode(void);

Description

Retrieves the texture dictionary stack's current search mode.

Arguments

None.

Return Value

The current texture dictionary stack search mode.

Comments

The texture dictionary search modes are:

•	rwLOCAL    Search only the top most dictionary in the texture dictionary stack.

•	rwGLOBAL    Search all the dictionaries in the texture dictionary stack.

See Also

RwFindNamedTexture()

RwForAllNamedTextures()

RwGetNamedTexture()

RwSetTextureDictSearchMode()

RwTextureDictBegin()

RwTextureDictEnd()


RwGetTextureDithering()

RwTextureDitherMode

RwGetTextureDithering(void);

Description

Retrieves the current global texture dithering mode applied to subsequently loaded textures.

Arguments

None.

Return Value

The current texture dithering mode.

Comments

The current texture dithering mode is a global parameter which controls whether textures read from disk are dithered to increase perceived color resolution.

The texture dithering modes are:

•	rwDITHERON    Activates dithering.

•	rwDITHEROFF    Deactivates dithering.

•	rwAUTODITHER    Adopts the auto-dithering mode of raster reading to decide whether to dither textures.

The default mode is rwAUTODITHER.

See Also

RwGetTextureGammaCorrection()

RwReadRaster()

RwSetTextureDithering()

RwSetTextureGammaCorrection()


RwGetTextureFrame()

int

RwGetTextureFrame(RwTexture *texture);

Description

Gets the texture's current frame index.

Arguments

texture	Pointer to the texture.

Return Value

The current frame index (an integer greater than or equal to zero) if successful, and -1 otherwise.

See Also

RwGetTextureFrameStep()

RwGetTextureNumFrames()

RwSetTextureFrame()

RwTextureNextFrame()


RwGetTextureFrameStep()

int

RwGetTextureFrameStep(RwTexture *texture);

Description

Retrieves the texture's frame step size.

Arguments

texture	Pointer to the texture.

Return Value

The current step size to be used by RwTextureNextFrame(). Errors can be checked for using RwGetError().

See Also

RwGetError()

RwGetTextureFrame()

RwGetTextureNumFrames()

RwSetTextureFrameStep()

RwTextureNextFrame()


RwGetTextureGammaCorrection()

RwState

RwGetTextureGammaCorrection(void);

Description

Retrieves the current global texture gamma correction mode applied to subsequently loaded textures.

Arguments

None.

Return Value

The current texture gamma correction mode.

Comments

The current texture gamma correction mode is a global parameter which controls whether textures read from disk are gamma corrected or not.

The texture gamma correction modes are:

•	rwON    Gamma correct.

•	rwOFF    Do not gamma correct.

The default mode is rwON.

See Also

RwGetTextureDithering()

RwReadRaster()

RwSetTextureDithering()

RwSetTextureGammaCorrection()


RwGetTextureName()

char *

RwGetTextureName(RwTexture *texture);

Description

Retrieves the texture's name.

Arguments

texture	Pointer to the texture.

Return Value

The texture's name. If there is an error or if the texture is not in a dictionary, NULL is returned. Errors can be checked for using RwGetError().

Comments

Only textures which are defined in dictionaries have names. Textures which are created using RwCreateTexture() or RwReadTexture() (rather RwFindNamedTexture(), RwGetNamedTexture() or RwReadNamedTexture()) are not placed in dictionaries and hence have no name. RwGetNamedTexture() will return NULL for such textures.

The string returned by this function is constant and no attempt should be made to modify it.

See Also

RwCreateTexture()

RwFindNamedTexture()

RwGetError()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadTexture()


RwGetTextureNumFrames()

int

RwGetTextureNumFrames(RwTexture *texture);

Description

Retrieves the number of frames in the texture.

Arguments

texture	Pointer to the texture.

Return Value

Number of frames in the texture if successful, and -1 otherwise.

See Also

RwGetTextureFrame()

RwGetTextureFrameStep()

RwSetTextureFrame()

RwSetTextureFrameStep()

RwTextureNextFrame()


RwGetTextureRaster()

RwRaster *

RwGetTextureRaster(RwTexture *texture);

Description

Retrieves a pointer to the texture's raster.

Arguments

texture	Pointer to the texture.

Return Value

The texture's raster if successful, and NULL otherwise.

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwFindNamedTexture()

RwGetCameraViewportRaster()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadRaster()

RwReadTexture()

RwSetTextureRaster()


RwGetUserDrawAlignment()

RwUserDrawAlignmentTypes

RwGetUserDrawAlignment(RwUserDraw *userdraw);

Description

Retrieves the alignment flag (or flags) of the user-draw. Thee alignment flags determine which part of the user-draw's bounding box is used for alignment.

Arguments

userdraw	Pointer to the user-draw.

Return Value

A bitfield representing the set of alignment flags associated with the user-draw if successful. Errors can be checked for using RwGetError().

Comments

The alignment flags are:

•	0    Center the user-draw.

•	rwALIGNTOP    Align with the top edge of the user-draw.

•	rwALIGNBOTTOM    Align with the bottom edge of the user-draw.

•	rwALIGNLEFT    Align with the left edge of the user-draw.

•	rwALIGNRIGHT    Align with the right edge of the user-draw.

See Also

RwCreateUserDraw()

RwGetError()

RwGetUserDrawParentAlignment()

RwSetUserDrawAlignment()


RwGetUserDrawCallback()

void

(*RwGetUserDrawCallback(RwUserDraw *userdraw)) (RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data);

Description

Retrieves the call-back function used to render the user-draw.

Arguments

userdraw	Pointer to the user-draw.

Return Value

A pointer to the user-draw's call-back function if successful, and NULL otherwise.

Comments

User-draw call-backs should be declared as follows:

void callback(RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data);

Where the call-back's arguments are:

userdraw	Pointer to the user-draw to be rendered.

camimage	The camera's image buffer as returned by RwGetCameraImage() for the current camera. camimage is device dependent. For more information, see MS Windows 3.1 Specific Information.

rect	Pointer to a rectangle defining the area of the camera's image buffer into which the call-back may render. This rectangle is specified in viewport space coordinates, i.e., (0, 0) is the origin of the viewport.

data	Pointer to the user data of the user-draw being drawn. This value can be obtained by calling RwGetUserDrawData() with userdraw as an argument. data is passed directly to the call-back function for the convenience of the application developer.

Note that the call-back function is always called after all clumps in the scene have been rendered, i.e., when RwEndCameraUpdate() is called. Therefore user-draw rendering always appear in front of clump rendering. In the case of overlapping user-draws, the order of rendering is not defined.

See Also

RwCreateUserDraw()

RwEndCameraUpdate()

RwGetCameraImage()

RwGetUserDrawData()

RwSetUserDrawCallback()


RwGetUserDrawData()

void *

RwGetUserDrawData(RwUserDraw *userdraw);

Description

Retrieves the user-draw's user data pointer.

Arguments

userdraw	Pointer to the user-draw.

Return Value

The user data pointer. NULL is returned if there is an error or if the user data pointer is NULL. Errors can be checked for using RwGetError().

See Also

RwGetError()

RwSetUserDrawData()


RwGetUserDrawOffset()

RwUserDraw *

RwGetUserDrawOffset(RwUserDraw *userdraw, int *x, int *y);

Description

Retrieves the user-draw's offset (in viewport space units) from the alignment point of the user-draw.

Arguments

userdraw	Pointer to the user-draw.

x	Pointer to the integer that will receive the horizontal offset from the alignment point of the user-draw (in viewport space units).

y	Pointer to the integer that will receive the vertical offset from the alignment point of the user-draw (in viewport space units).

Return Value

The argument userdraw if successful, and NULL otherwise.

See Also

RwCreateUserDraw()

RwSetUserDrawOffset()


RwGetUserDrawOwner()

RwClump *

RwGetUserDrawOwner(RwUserDraw *userdraw);

Description

Retrieves the clump that owns the user-draw.

Arguments

userdraw	Pointer to the user-draw.

Return Value

The clump that owns the user-draw. NULL is returned if the user-draw is not currently owned by a clump or if an error occurs. Errors can be checked for using RwGetError().

See Also

RwAddUserDrawToClump()

RwCreateUserDraw()

RwDuplicateUserDraw()

RwForAllUserDrawsInClump()

RwGetError()

RwRemoveUserDrawFromClump()


RwGetUserDrawParentAlignment()

RwUserDrawAlignmentTypes

RwGetUserDrawParentAlignment(RwUserDraw *userdraw);

Description

Retrieves the alignment flag (or flags) of the user-draw's parent. A user-draw's parent is either the bounding box of the clump that owns the user-draw or the current camera's viewport.

The alignment flags of the user-draw's parent determine which part of the user-draw's parent rectangle is aligned with the user-draw. The actual point of alignment between a user-draw and its parent is determined by the user-draw's alignment flags and the parent's alignment flags.

Arguments

userdraw	Pointer to the user-draw.

Return Value

A bitfield representing the set of alignment flags associated with the user-draw's parent. Errors can be checked for using RwGetError().

Comments

If the user-draw's type is rwBBOXALIGN then the user-draw's parent is the bounding box of the clump to which the user-draw is attached. If the type is rwVPALIGN, the user-draw's parent is the viewport of the current camera when the user-draw is rendered. If the user-draw's type is rwVERTEXALIGN or rwCLUMPALIGN then the user-draw has no parent and the parent alignment flags are ignored.

The alignment flags are:

•	0    Align with the center of the parent.

•	rwALIGNTOP    Align with the top edge of the parent.

•	rwALIGNBOTTOM    Align with the bottom edge of the parent.

•	rwALIGNLEFT    Align with the left edge of the parent.

•	rwALIGNRIGHT    Align with the right edge of the parent.

See Also

RwCreateUserDraw()

RwGetUserDrawAlignment()

RwSetUserDrawAlignment()

RwSetUserDrawParentAlignment()


RwGetUserDrawSize()

RwUserDraw *

RwGetUserDrawSize(RwUserDraw *userdraw, int *width, int *height);

Description

Retrieves the width and height (in viewport space units) of the user-draw.

Arguments

userdraw	Pointer to the user-draw.

width	Pointer to the integer that will receive the width of the user-draw (in viewport space units).

height	Pointer to the integer that will receive the height of the user-draw (in viewport space units).

Return Value

The argument userdraw if successful, and NULL otherwise.

See Also

RwCreateUserDraw()

RwSetUserDrawSize()


RwGetUserDrawType()

RwUserDrawType

RwGetUserDrawType(RwUserDraw *userdraw);

Description

Retrieves the user-draw's type.

Arguments

userdraw	Pointer to the user-draw.

Return Value

The user-draw's type if successful, and rwNAUSERDRAWTYPE otherwise.

Comments

The user-draw types are:

•	rwCLUMPALIGN    Align with the origin of the owning clump.

•	rwVERTEXALIGN    Align with a vertex of the owning clump.

•	rwBBOXALIGN    Align with the viewport bounding box of the owning clump.

•	rwVPALIGN    Align with the viewing camera's viewport.

See Also

RwCreateUserDraw()

RwGetClumpViewportRect()

RwSetUserDrawType()


RwGetUserDrawVertexIndex()

int

RwGetUserDrawVertexIndex(RwUserDraw *userdraw);

Description

Retrieves the index of the clump vertex with which the user-draw is aligned.

Arguments

userdraw	Pointer to the user-draw.

Return Value

The index of the vertex the user-draw is aligned with if successful, and 0 otherwise.

Comments

The vertex index is only used if the user-draw's type is rwVERTEXALIGN, for all other user-draw types it is ignored.

The vertex index is an index into the vertex list of the owning clump of the user-draw.

See Also

RwCreateUserDraw()

RwSetUserDrawVertexIndex()


RwHemisphere()

int

RwHemisphere(RPARAM radius, int density);

Description

Adds a hemisphere to the current clump. The hemisphere is transformed by the CTM, and the current material is assigned to its polygons. The base of the hemisphere lies on the X-Z plane.

Arguments

radius	Radius of the hemisphere.

density	Density of facets in the hemisphere. The number of facets increases exponentially with density.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCone()

RwCylinder()

RwDisc()

RwProtoBegin()

RwProtoEnd()

RwSphere()


RwIdentityCTM()

int

RwIdentityCTM(void);

Description

Sets the CTM to the identity matrix.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityJointTM()

RwModelBegin()

RwModelEnd()

RwRotateCTM()

RwScaleCTM()

RwTransformCTM()

RwTranslateCTM()


RwIdentityJointTM()

int

RwIdentityJointTM(void);

Description

Sets the current joint transformation matrix to the identity matrix.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityCTM()

RwModelBegin()

RwModelEnd()

RwRotateJointTM()

RwTransformJointTM()


RwIdentityMatrix()

RwMatrix4d *

RwIdentityMatrix(RwMatrix4d *matrix);

Description

Sets the matrix to the identity matrix.

Arguments

matrix	Pointer to the matrix.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwIdentityCTM()

RwIdentityJointTM()

RwInvertMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwInclude()

int

RwInclude(RwClump *clump);

Description

Inserts copies of the polygons and vertices of clump into the current clump under construction. The source polygons and vertices are transformed by the CTM before being added. The materials of the source polygons are copied to the new polygons.

Arguments

clump	Pointer to the clump.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwIncludeGeometry()

RwProtoBegin()

RwProtoEnd()

RwReadShape()


RwIncludeGeometry()

int

RwIncludeGeometry(RwClump *clump);

Description

Inserts copies of the polygons and vertices of the clump into the current clump under construction. The source polygons and vertices are transformed by the CTM before being added to the current clump. The current material is assigned to the new polygons (the materials of the source polygons are ignored).

Arguments

clump	Pointer to the clump.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwInclude()

RwProtoBegin()

RwProtoEnd()

RwReadShape()


RwInvalidateCameraViewport()

RwCamera *

RwInvalidateCameraViewport(RwCamera *camera);

Description

Marks the whole of the camera's viewport as damaged.

Arguments

camera	Pointer to the camera.

Return Value

The argument camera if successful, and NULL otherwise.

Comment

This function will cause the entire viewport to be copied to the display when the next call to RwShowCameraImage() is made. It will also cause the entire viewport to be cleared by the next call to RwClearCameraViewport().

See Also

RwClearCameraViewport()

RwDamageCameraViewport()

RwSetCameraViewport()

RwShowCameraImage()

RwUndamageCameraViewport()


RwInvertMatrix()

RwMatrix4d *

RwInvertMatrix(RwMatrix4d *source, RwMatrix4d *dest);

Description

Inverts matrix source and stores the result in matrix dest.

Arguments

source	Pointer to the matrix to be inverted.

dest	Pointer to the matrix that will receive the result.

Return Value

The argument dest if successful, and NULL otherwise.

Comments

The source and destination arguments must not point to the same matrix.

See Also

RwIdentityMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwJointTransformBegin()

int

RwJointTransformBegin(void);

Description

Pushes a copy of the current joint transformation matrix onto the joint transformation stack.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwIdentityJointTM()

RwJointTransformEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwRotateJointTM()

RwTransformBegin()

RwTransformJointTM()


RwJointTransformEnd()

int

RwJointTransformEnd(void);

Description

Restores the previous value of the joint transformation matrix. Also has the effect of restoring the joint transformation stack to its state at the time of the last RwJointTransformBegin().

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwIdentityJointTM()

RwJointTransformBegin()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwRotateJointTM()

RwTransformJointTM()

RwTransformEnd()


RwMaskTexture()

RwTexture *

RwMaskTexture(RwTexture *texture, RwRaster *mask);

Description

Masks the texture with the mask raster mask.

Arguments

texture	Pointer to the texture.

mask	Pointer to the mask raster.

Return Value

The argument texture if successful, and NULL otherwise.

Comments

The mask raster must of exactly the same width and height as the texture. If the texture is a multi-frame texture, the mask's height must be equal to n * 128, where n is the number of frames in the texture.

The mask raster must have been previously created with RwReadMaskRaster().

Masking a texture is a destructive operation. The masking cannot be undone and applies to all materials referencing the masked texture.

See Also

RwCreateRaster()

RwCreateTexture()

RwReadMaskRaster()

RwSetSurfaceTextureExt()

RwSetTextureRaster()


RwMaterialBegin()

int

RwMaterialBegin(void);

Description

Pushes a copy of the current material onto the material stack.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwMaterialEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwPushCurrentMaterial()


RwMaterialEnd()

int

RwMaterialEnd(void);

Description

Restores the previous state of the current material. The material stack is restored to its state at the time of the last RwMaterialBegin().

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwMaterialBegin()

RwModelBegin()

RwModelEnd()

RwPopCurrentMaterial()

RwProtoBegin()

RwProtoEnd()


RwModelBegin()

int

RwModelBegin(void);

Description

Sets up a modelling context for prototype declaration and clump creation. Prototype clumps declared within an RwModelBegin() …RwModelEnd() block may subsequently be "instanced" when building further prototypes or the desired model.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

An RwModelBegin() … RwModelEnd() block may have any number of prototype clump declarations but must have one, and only one, top-level RwClumpBegin() … RwClumpEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwProtoInstance()

RwProtoInstanceGeometry()


RwModelEnd()

int

RwModelEnd(void);

Description

Marks the end of a model definition.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

An RwModelBegin() … RwModelEnd() block may have any number of prototype clump declarations but must have one, and only one, top-level RwClumpBegin() … RwClumpEnd().

RwModelEnd() will destroy all prototypes defined since the previous RwModelBegin().

See Also

RwClumpBegin()

RwClumpEnd()

RwModelBegin()

RwProtoBegin()

RwProtoEnd()


RwMultiplyMatrix()

RwMatrix4d *

RwMultiplyMatrix(RwMatrix4d *a, RwMatrix4d *b, RwMatrix4d *c);

Description

Multiplies two matrices together.

Arguments

a	Pointer to the left matrix.

b	Pointer to the right matrix.

c	Pointer to the matrix that will receive the result.

Return Value

The argument c if successful, and NULL otherwise.

Comments

Note that the matrix used for the result (c) must be a different matrix from the matrices being multiplied together, (a and b).

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwNormalize()

RwV3d *

RwNormalize(RwV3d *vector);

Description

Normalizes a vector to unit length while retaining the ratio between its X, Y, and Z components.

Arguments

vector	Pointer to the vector.

Return Value

The argument vector if successful, and NULL otherwise.

Comments

Note that it is an error to normalize a vector whose magnitude is zero.

See Also

RwAddVector()

RwCrossProduct()

RwDotProduct()

RwScaleVector()

RwSubtractVector()


RwNormalizeClump()

RwClump *

RwNormalizeClump(RwClump *clump);

Description

Transforms the clump so that all the clump's vertices lie within unit space. The clump's modelling and joint (articulation) matrices are set to the identity.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Note that this function is not recursive. The descendants of the specified clump (if any) are not normalized.

See Also

RwGetClumpBBox()

RwGetClumpJointMatrix()

RwGetClumpLTM()

RwGetClumpMatrix()

RwTransformClump()

RwTransformClumpJoint()


RwOpen()

int

RwOpen(char *device, void *param);

Description

Initializes the RenderWare library. This function (or its variant RwOpenExt()) must be called before any other RenderWare functions.

Arguments

device	A string whose value is either NullDevice or device-dependent.

param	A device dependent parameter.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If device is NULL, the library will examine the environment variable RWDEVICE for the appropriate name.

For a description of the device dependent parameters, device and param, see MS Windows 3.1 Specific Information.

See Also

RwClose()

RwOpenExt()


RwOpenDebugStream()

int

RwOpenDebugStream(char *filename);

Description

Opens the named file as the current debugging stream.

Arguments

filename	Name of a file.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

Note that this function appends information to the specified file or device.

On certain platforms special filenames are recognized which, for example, allow the debugging stream to be redirected to a monochrome, debugging monitor. For more information, see MS Windows 3.1 Specific Information.

See Also

RwCloseDebugStream()

RwSetDebugStream()


RwOpenExt()

int

RwOpenExt(char *device, void *param, int numargs, RwOpenArgument *args);

Description

Initializes the RenderWare library with a number of optional arguments. This function (or its variant RwOpen()) must be called before any other RenderWare functions.

Arguments

device	A string whose value is either NullDevice or device-dependent.

param	A device dependent parameter.

numargs	The number of optional arguments specified.

args	An array of optional open arguments.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If device is NULL, the library will examine the environment variable RWDEVICE for the appropriate name.

For a description of the device dependent parameters, device and param and the optional argument types supported, see MS Windows 3.1 Specific Information.

See Also

RwClose()

RwDeviceControl()

RwOpen()


RwOrthoNormalizeMatrix()

RwMatrix4d *

RwOrthoNormalizeMatrix(RwMatrix4d *source, RwMatrix4d *dest);

Description

Ortho-normalizes the source matrix and places the result in the destination matrix.

Arguments

source	Pointer to the matrix to orthonormalize.

dest	Pointer to the matrix to receive the result.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

Whilst RenderWare supports arbitrary 4 x 4 homogenous matrices, many applications deal only in "rigid body" transformations comprising only rotation and translation without scaling or shearing.

The 4 x 4 homogeneous matrix representing such a transformation has a special form of upper-left 3 x 3 sub-matrix known as an orthonormal matrix. An orthonormal matrix is characterised by its inverse being equal to its transpose.

Mathematically, the upper-left 3 x 3 sub-matrix corresponding to a rigid body transformation remains orthonormal after that transformation is combined with other rigid body transformations.   The upper 3 x 3 sub matrix corresponding to the inverse of a rigid body transformation should also be orthonormal.

Numerically however,   after extended matrix composition, some scale or shear factors may begin to accumulate due to rounding. To prevent the significant build up of such factors, RwOrthoNormalizeMatrix() should be periodically applied to a clump's modelling or joint matrix as appropriate. This will filter out any such accumulated rounding factors from the upper-left 3 x 3 sub-matrix.

The minimal satisfactory frequency of orthonormalization will depend on the nature of the application and whether a fixed- or floating- point version of the RenderWare library is being used. Typically, an orthonormalization frequency of once every 128 frames is adequate.

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwPanCamera()

RwCamera *

RwPanCamera(RwCamera *camera, RPARAM angle);

Description

Rotates the camera about its Y axis.

Arguments

camera	Pointer to the camera.

angle	Angle of rotation (in degrees).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookRight()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwTiltCamera()

RwTransformCameraOrientation()


RwPickClump()

RwPickRecord *

RwPickClump(RwClump *clump, int vpx, int vpy, RwCamera *camera, RwPickRecord *pick);

Description

Finds the frontmost polygon of the clump whose projection on the camera's viewport "contains" the specified point.

Arguments

clump	Pointer to the clump.

vpx	X coordinate (in viewport space coordinates).

vpy	Y coordinate (in viewport space coordinates).

camera	Pointer to the camera.

pick	Pointer to the pick record.

Return Value

A pointer to the argument pick if successful, and NULL otherwise.

Comments

vpx and vpy must be in viewport rather than device space coordinates. To convert from a point in device space coordinates (such as the position of the mouse) to viewport space coordinates simply subtract the X and Y coordinates of the camera's viewport from the X and Y coordinates of the point.

The pick record has a type field that will have either the value rwNAPICKOBJECT or rwPICKCLUMP. The former means that the clump was not picked.

If the pick record's type is rwPICKCLUMP, then assuming that pick is a pick record structure whose address was passed as the last argument of the function, upon return from the function:

pick.object.clump.clump

is a pointer to the clump picked,

pick.object.clump.polygon

is a pointer to the polygon picked,

pick.object.clump.vertex

is an RwPickVertexData structure giving information about the picked vertex, and

pick.object.clump.wcpoint

is the world space coordinates of the actual point picked.

RwPickVertexData is defined as follows:

typedef struct
{
int vindex;
int d2;
} RwPickVertexData;

Fields vindex and d2 specify respectively the index of the vertex picked and the square of its distance (in viewport space units) from the actual pick position.

See Also

RwPickScene()


RwPickScene()

RwPickRecord *

RwPickScene(RwScene *scene, int vpx, int vpy, RwCamera *camera, RwPickRecord *pick);

Description

Finds the frontmost clump of the scene whose projection on the camera's viewport "contains" the specified point.

Arguments

scene	Pointer to the scene.

vpx	X coordinate (in viewport space coordinates).

vpy	Y coordinate (in viewport space coordinates).

camera	Pointer to the camera.

pick	Pointer to the pick record.

Return Value

A pointer to the argument pick if successful, and NULL otherwise.

Comments

vpx and vpy must be in viewport rather than device space coordinates. To convert from a point in device space coordinates (such as the position of the mouse) to viewport space coordinates simply subtract the X and Y coordinates of the camera's viewport from the X and Y coordinates of the point.

The pick record has a type field that will have either the value rwNAPICKOBJECT or rwPICKCLUMP.

If the pick record's type is rwNAPICKOBJECT, then no clumps were picked.

If the pick record's type is rwPICKCLUMP, then assuming that pick is a pick record structure whose address was passed as the last argument of the function, upon return from the function:

pick.object.clump.clump

is a pointer to the clump picked,

pick.object.clump.polygon

is a pointer to the polygon picked,

pick.object.clump.vertex

is an RwPickVertexData structure giving information about the vertex picked, and

pick.object.clump.wcpoint

is the world space coordinates of the actual point picked.

RwPickVertexData is defined as follows:

typedef struct
{
int vindex;
int d2;
} RwPickVertexData;

Fields vindex and d2 specify respectively the index of the vertex picked and the square of its distance (in viewport space units) from the actual pick position.

See Also

RwPickClump()


RwPointCamera()

RwCamera *

RwPointCamera(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Re-orients the camera to point at the given point, while keeping its position constant.

Arguments

camera	Pointer to the camera.

x	X coordinate of the point to look at (in world space coordinates).

y	Y coordinate of the point to look at (in world space coordinates).

z	Z coordinate of the point to look at (in world space coordinates).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookRight()

RwGetCameraLookUp()

RwPanCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwTiltCamera()

RwTransformCameraOrientation()


RwPolygon()

int

RwPolygon(int sides, int *vlist);

Description

Adds a polygon to the current clump under construction. The current material is assigned to the polygon.

Arguments

sides	Number of sides of the polygon.

vlist	Array of vertex indices.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The size of the array vlist must be equal to sides.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwClumpBegin()

RwClumpEnd()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwTriangle()

RwTriangleExt()

RwVertex()

RwVertexExt()


RwPolygonExt()

int

RwPolygonExt(int sides, int *vlist, short int tag);

Description

Adds a polygon with the given integer tag to the current clump under construction. The current material is assigned to the polygon.

Arguments

sides	Number of sides of the polygon.

vlist	Array of vertex indices.

tag	Integer tag to set.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The size of the array vlist must be equal to sides.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwClumpBegin()

RwClumpEnd()

RwFindTaggedPolygon()

RwPolygon()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwSetPolygonTag()

RwSetTag()

RwTriangle()

RwTriangleExt()

RwVertex()

RwVertexExt()


RwPopCurrentMaterial()

RwMaterial *

RwPopCurrentMaterial(void);

Description

Pops the current material from the material stack, restoring the previously pushed material.

Arguments

None.

Return Value

A pointer to the new current material if successful, and NULL otherwise.

See Also

RwCurrentMaterial()

RwMaterialEnd()

RwPushCurrentMaterial()


RwPopScratchMatrix()

RwMatrix4d *

RwPopScratchMatrix(void);

Description

Pops the current scratch matrix from the scratch matrix stack, restoring the previously pushed matrix.

Arguments

None.

Return Value

A pointer to the new scratch matrix if successful, and NULL otherwise.

Comments

The scratch matrix stack is a convenient source of temporary matrices for building transforms.

RwPopScratchMatrix() supersedes the V1.2 API function RwPopCurrentMatrix(). Calls to RwPopCurrentMatrix() must be replaced with RwPopScratchMatrix().

See Also

RwScratchMatrix()

RwPushScratchMatrix()


RwProtoBegin()

int

RwProtoBegin(char *name);

Description

Identifies the beginning of a prototype clump declaration.

Arguments

name	Name of the prototype.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function overrides any existing prototype of the same name.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwModelBegin()

RwModelEnd()

RwProtoEnd()

RwProtoInstance()

RwProtoInstanceGeometry()


RwProtoEnd()

int

RwProtoEnd(void);

Description

Marks the end of a prototype clump declaration.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoInstance()

RwProtoInstanceGeometry()


RwProtoInstance()

int

RwProtoInstance(char *name);

Description

Creates an instance of the named prototype and copies its polygons and vertices to the clump under construction. The source polygons and vertices are transformed by the CTM before being added to the current clump. The materials of the source polygons are copied to the new polygons.

Arguments

name	Name of a prototype.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

A prototype of the given name must have already been defined within the enclosing RwModelBegin() … RwModelEnd() block.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwProtoInstanceGeometry()


RwProtoInstanceGeometry()

int

RwProtoInstanceGeometry(char *name);

Description

Creates an instance of the named prototype and copies its polygons and vertices to the clump under construction. The source polygons and vertices are transformed by the CTM before being added to the current clump. The current material is assigned to the new polygons. The materials of the source polygons are ignored.

Arguments

name	Name of a prototype.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

A prototype of the given name must have already been defined within the enclosing RwModelBegin() … RwModelEnd() block.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwProtoInstance()


RwPushCurrentMaterial()

RwMaterial *

RwPushCurrentMaterial(void);

Description

Pushes a copy of the current material onto the material stack.

Arguments

None.

Return Value

A pointer to the new current material if successful, and NULL otherwise.

See Also

RwCurrentMaterial()

RwMaterialBegin()

RwPopCurrentMaterial()


RwPushScratchMatrix()

RwMatrix4d *

RwPushScratchMatrix(void);

Description

Pushes a copy of the scratch matrix onto the scratch matrix stack.

Arguments

None.

Return Value

A pointer to the new scratch matrix if successful, and NULL otherwise.

Comments

The scratch matrix stack is a convenient source of temporary matrices for building transforms.

RwPushScratchMatrix() supersedes the V1.2 API function RwPushCurrentMatrix(). Calls to RwPushCurrentMatrix() must be replaced with RwPushScratchMatrix().

See Also

RwScratchMatrix()

RwPopScratchMatrix()


RwQuad()

int

RwQuad(int v1, int v2, int v3, int v4);

Description

Adds a quadrilateral to the current clump under construction. The current material is assigned to the polygon.

Arguments

v1	Index of the first vertex of the polygon.

v2	Index of the second vertex of the polygon.

v3	Index of the third vertex of the polygon.

v4	Index of the fourth vertex of the polygon.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function is exactly equivalent to calling RwPolygon() with an array of four vertex indices.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwPolygon()

RwPolygonExt()

RwQuadExt()

RwTriangle()

RwTriangleExt()

RwVertex()

RwVertexExt()


RwQuadExt()

int

RwQuadExt(int v1, int v2, int v3, int v4, short int tag);

Description

Adds a quadrilateral with the given integer tag to the current clump under construction. The current material is assigned to the polygon.

Arguments

v1	Index of the first vertex of the polygon.

v2	Index of the second vertex of the polygon.

v3	Index of the third vertex of the polygon.

v4	Index of the fourth vertex of the polygon.

tag	Integer tag to set.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function is exactly equivalent to calling RwPolygonExt() with an array of four vertex indices.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwFindTaggedPolygon()

RwGetPolygonTag()

RwPolygon()

RwPolygonExt()

RwQuad()

RwSetPolygonTag()

RwSetTag()

RwTriangle()

RwTriangleExt()

RwVertex()

RwVertexExt()


RwQueryRotateMatrix()

RwMatrix4d *

RwQueryRotateMatrix(RwMatrix4d *matrix, RwV3d *axis, RwReal *degrees);

Description

Retrieves the rotation component from a matrix comprising only rotations and translations. The rotation is returned as a unit direction vector along the axis of rotation through the origin and an angle in degrees. This function is the inverse of RwRotateMatrix() with the RwCombineOperation rwREPLACE.

Arguments

matrix	Pointer to the rotation/translation matrix.

axis	Pointer to the vector to receive the unit direction vector along the axis of rotation through the origin.

degrees	Pointer to the RwReal to receive the angle of rotation in degrees.

Return Value

The argument matrix if successful, and NULL otherwise.

Comments

A rotation has two possible descriptions in this axis/angle form, since a rotation about a given axis through the origin by a given angle theta is the same as a rotation about an axis in the reverse direction by the angle 360-theta. The angle returned is always in the range CREAL(0.0) to CREAL(180.0). The direction of the axis of rotation returned is chosen to ensure that the angle lies in this range.

Notice that only matrices known to be composed solely of rotations and translations should be queried with this function. The results of querying other matrices incorporating transforms such as scales are unlikely to be of practical use. RwOrthoNormalizeMatrix() may be applied to extract the rotation/translation component matrix from a more general transformation matrix.

See Also

RwGetMatrixElements()

RwGetMatrixElement()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()


RwReadMaskRaster()

RwRaster *

RwReadMaskRaster(char *filename);

Description

Reads a mask raster from the specified file. The resulting raster can be applied to a texture as a mask.

Arguments

filename	Name of the mask raster file.

Return Value

A pointer to the new mask raster if successful, and NULL otherwise.

Comments

The raster read by RwReadMaskRaster() is used to mask a texture. Those pixels which are "masked out" by the raster are not rendered. Thus, a mask raster is effectively a one bit alpha channel which, when applied to a texture, gives control over the transparency of individual pixels.

The raster read by RwReadMaskRaster() is converted to the texture map dimensions of 128 pixels in width by 128 pixels in height (or n * 128 pixels for a multi-frame texture where n is the number of frames in the texture). Furthermore, the image read will be converted to the current RenderWare render depth.

The file read by this operation should contain a gray scale image of any supported depth. The gray scale value of each pixel is simply thresholded to determine whether it represents an opaque or transparent pixel. Pixels whose value is less than half of the available range of gray values represent transparent pixels. Those whose value is greater than or equal to half the available range of gray values represent opaque pixels.

If filename is not a full path, the library searches for the specified file in all directories on its shape path.

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwGetShapePath()

RwMaskTexture()

RwReadMaskRaster()

RwSetCameraBackdrop()

RwSetShapePath()

RwSetTextureRaster()


RwReadNamedTexture()

RwTexture *

RwReadNamedTexture(char *name);

Description

Reads a texture with the specified name and stores it into the current texture dictionary.

Arguments

name	Name of a texture.

Return Value

A pointer to a newly created texture if successful, and NULL otherwise.

Comments

This function uses the environment variable RWSHAPEPATH as it's search path. The texture read from disk will replace any texture with the specified name that is already in the current texture dictionary.

The string supplied as the texture name must form the leaf part (i.e., without path or extension) of the pathname for the texture file. Furthermore, for the sake of portability of script files across the different platforms supported by RenderWare, it is best to choose texture file names that are a maximum of eight characters long and which are acceptable to MS-DOS as file names.

An example of a valid texture name is "marble", which will match with file names "marble", "marble.tex", "marble.ras", "marble.env", "marble.bmp" and "marble.env".

See Also

RwCreateTexture()

RwDestroyTexture()

RwFindNamedTexture()

RwGetNamedTexture()

RwGetShapePath()

RwReadTexture()

RwSetShapePath()


RwReadRaster()

RwRaster *

RwReadRaster(char *filename, RwRasterOptions options);

Description

Reads a raster from the specified file. The raster will be processed according to the specified options.

Arguments

filename	Name of the raster file.

options	A bitfield representing a raster processing option (or bitwise or of options).

Return Value

A pointer to the new raster if successful, and NULL otherwise.

Comments

If filename is not a full path, the library searches for the specified file in all directories on its shape path.

The supported raster options are as follows:

•	rwAUTODITHERRASTER Dither the raster only if the source bitmap is to be resized (rwFITRASTER has been specified) or if the bitmap is a different depth from the current RenderWare render depth.

•	rwDITHERASTER    Dither the raster.

•	rwFITRASTER    Resize the raster to texture map dimensions, i.e. 128 x n * 128 (where n is the number of frames in a multi-frame texture).

•	rwGAMMARASTER    Gamma correct the raster.

•	rwINDEXRASTER    Do not convert the raster into RenderWare color space.

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwGetDeviceInfo()

RwGetShapePath()

RwReadMaskRaster()

RwSetCameraBackdrop()

RwSetShapePath()

RwSetTextureDithering()

RwSetTextureGammaCorrection()

RwSetTextureRaster()


RwReadShape()

RwClump *

RwReadShape(char *filename);

Description

Loads a clump from a script (.rwx) file. If filename is not an absolute path, the library searches for the specified file in all directories on its shape path.

Arguments

filename	Pointer to the filename string.

Return Value

A pointer to the new clump if successful, and NULL otherwise

Comments

The clump is added to the default scene.

See Also

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwDefaultScene()

RwDestroyClump()

RwGetShapePath()

RwSetShapePath()

RwWriteShape()


RwReadTexture()

RwTexture *

RwReadTexture(char *filename);

Description

Reads a texture from the specified file.

Arguments

filename	Name of the texture file.

Return Value

A pointer to the new texture if successful, and NULL otherwise.

Comments

If filename is not a full path, the library searches for the specified file in all directories on its shape path.

Unlike RwReadNamedTexture(), the texture read from disk will not be placed in the current texture dictionary.

See Also

RwCreateTexture()

RwDestroyTexture()

RwFindNamedTexture()

RwGetNamedTexture()

RwGetShapePath()

RwGetTextureRaster()

RwReadNamedTexture()

RwReadRaster()

RwSetShapePath()

RwSetTextureRaster()


RwRemoveChildFromClump()

RwClump *

RwRemoveChildFromClump(RwClump *clump);

Description

Removes the clump from its parent's list of children.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Once removed, the clump becomes the root of a hierarchy consisting of itself and any descendents.

See Also

RwAddChildToClump()

RwGetClumpNumChildren()

RwGetClumpParent()

RwGetClumpRoot()

RwGetFirstChildClump()

RwGetNextClump()


RwRemoveClumpFromScene()

RwClump *

RwRemoveClumpFromScene(RwClump *clump);

Description

Removes the clump from its scene.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The clump being removed must be the root of its clump hierarchy, i.e., it must not have a parent clump.

The clump is added to the default scene. Clumps cannot be explicitly removed from the default scene.

See Also

RwAddClumpToScene()

RwDefaultScene()

RwDestroyClump()

RwForAllClumpsInScene()

RwGetSceneNumClumps()

RwRemoveLightFromScene()


RwRemoveHint()

int

RwRemoveHint(RwClumpHints hints);

Description

Removes a hint (or set of hints) from the current clump under construction. A clump's hints enable RenderWare to render a scene containing that clump more efficiently.

Arguments

hints	A bitfield representing a hint (or bitwise or of hints).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The clump hints are:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent   hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() block.

See Also

RwAddHint()

RwClumpBegin()

RwClumpEnd()

RwRemoveHintFromClump()

RwSetHints()


RwRemoveHintFromClump()

RwClump *

RwRemoveHintFromClump(RwClump *clump, RwClumpHints hint);

Description

Removes a hint (or set of hints) from the clump.

Arguments

clump	Pointer to the clump.

hint	A bitfield representing a hint (or bitwise or of hints).

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The clump hints are:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

See Also

RwAddHintToClump()

RwGetClumpHints()

RwRemoveHint()

RwSetClumpHints()


RwRemoveLightFromScene()

RwLight *

RwRemoveLightFromScene(RwLight *light);

Description

Removes the light from its scene.

Arguments

light	Pointer to the light.

Return Value

The argument light if successful, and NULL otherwise.

Comments

The light is added to the default scene. Lights cannot be explicitly removed from the default scene.

See Also

RwAddLightToScene()

RwDefaultScene()

RwDestroyLight()

RwForAllLightsInScene()

RwGetSceneNumLights()

RwRemoveClumpFromScene()


RwRemoveTextureModeFromMaterial()

RwMaterial *

RwRemoveTextureModeFromMaterial(RwMaterial *material, RwTextureModes mode);

Description

Removes a texture mode (or modes) from the material. Texture modes permit fine grain control over the rendering of textures.

Arguments

material	Pointer to the material.

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument material if successful, and NULL otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToMaterial()

RwGetMaterialTextureModes()

RwRemoveTextureModeFromSurface()

RwRemoveTextureModeFromSurface()

RwSetMaterialLightSampling()

RwSetMaterialTextureModes()

RwSetMaterialTextureModes()


RwRemoveTextureModeFromPolygon()

RwPolygon3d *

RwRemoveTextureModeFromPolygon(RwPolygon3d *polygon, RwTextureModes mode);

Description

Removes a texture mode (or modes) from the polygon's material. Texture modes permit fine grain control over the rendering of textures.

Arguments

polygon	Pointer to the polygon.

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

See Also

RwAddTextureModeToPolygon()

RwGetPolygonTextureModes()

RwRemoveTextureModeFromSurface()

RwRemoveTextureModeFromSurface()

RwSetPolygonLightSampling()

RwSetPolygonTexture()

RwSetPolygonTextureModes()


RwRemoveTextureModeFromSurface()

int

RwRemoveTextureModeFromSurface(RwTextureModes mode);

Description

Removes a texture mode (or modes) from the current material. Texture modes permit fine grain control over the rendering of textures.

Arguments

mode	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwAddTextureModeToSurface()

RwModelBegin()

RwModelEnd()

RwRemoveTextureModeFromSurface()

RwRemoveTextureModeFromSurface()

RwSetSurfaceTexture()

RwSetSurfaceTextureModes()


RwRemoveUserDrawFromClump()

RwUserDraw *

RwRemoveUserDrawFromClump(RwUserDraw *userdraw);

Description

Removes the user-draw from its clump.

Arguments

userdraw	Pointer to the user-draw.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

After being removed from a clump, the user-draw has no owning clump. To make use of such a user-draw, add it to a clump using RwAddUserDrawToClump().

See Also

RwAddUserDrawToClump()

RwCreateUserDraw()

RwDestroyUserDraw()

RwDuplicateUserDraw()

RwForAllUserDrawsInClump()

RwGetClumpNumUserDraws()


RwRenderClump()

RwClump *

RwRenderClump(RwClump *clump);

Description

Renders the clump into the current camera's image buffer.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise

Comments

It is strongly recommended that RwRenderScene() be used for rendering rather than RwRenderClump(). RwRenderClump() is intended for use in certain unusual circumstances where it is necessary to render a single clump in isolation.

Clumps rendered by RwRenderClump() are illuminated by the lights in the default scene (if any).

Note that this function is not recursive, i.e., it only renders the specified clump and not its descendants.

This function can only be called in the context of an RwBeginCameraUpdate()… RwEndCameraUpdate() block.

See Also

RwBeginCameraUpdate()

RwClearCameraViewport()

RwDefaultScene()

RwEndCameraUpdate()

RwRenderScene()

RwShowCameraImage()


RwRenderScene()

RwScene *

RwRenderScene(RwScene *scene);

Description

Renders the scene into the current camera's image buffer.

Arguments

scene	Pointer to the scene.

Return Value

The argument scene if successful, and NULL otherwise.

Comments

It is strongly recommended that RwRenderScene() be used for rendering rather than RwRenderClump(). RwRenderClump() is intended for use in certain unusual circumstances where it is necessary to render a single clump in isolation.

This function can only be called in the context of an RwBeginCameraUpdate()… RwEndCameraUpdate() block.

See Also

RwBeginCameraUpdate()

RwClearCameraViewport()

RwEndCameraUpdate()

RwRenderClump()

RwShowCameraImage()


RwResetCamera()

RwCamera *

RwResetCamera(RwCamera *camera);

Description

Resets the camera to its initial position and orientation, at the origin, looking down the negative Z axis.

Arguments

camera	Pointer to the camera.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

RwResetCamera() performs the following (and only the following) actions:

•	Moves the camera's position to the origin of world space.

•	Points the camera down the negative Z axis of world space.

•	Points the camera's "Look Up" vector up the positive Y axis of world space.

•	Sets the camera's view window size to CREAL(1.0) by CREAL(1.0).

•	Sets the camera's view offset to (CREAL(0.0), CREAL(0.0)).

•	Damages the camera's entire viewport.

See Also

RwCreateCamera()

InvalidCameraViewport()

RwPointCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwSetCameraViewOffset()

RwSetCameraViewwindow()

RwTransformCamera()

RwTransformCameraOrientation()


RwReversePolygonFace()

RwPolygon3d *

RwReversePolygonFace(RwPolygon3d *polygon);

Description

Reverses the vertex ordering of the polygon.

Arguments

polygon	Pointer to the polygon.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

RwReversePolygonFace() modifies the facedness of a single polygon by reversing the order of the vertices in the polygon's vertex list.

As this function modifies the geometry of the clump which owns the polygon, the clump is made editable (the rwEDITABLE hint is set) by this function.

See Also

None.


RwRevolveCamera()

RwCamera*

RwRevolveCamera(RwCamera *camera, RPARAM angle);

Description

Rotates the camera about its Z axis.

Arguments

camera	Pointer to the camera.

angle	Angle of rotation (in degrees).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraLookRight()

RwGetCameraLookUp()

RwPanCamera()

RwResetCamera()

RwSetCameraLookUp()

RwTiltCamera()

RwTransformCameraOrientation()


RwRotateCTM()

int

RwRotateCTM(RPARAM rx, RPARAM ry, RPARAM rz, RPARAM angle);

Description

Pre-concatenates a rotation matrix onto the CTM.

Arguments

rx	X component of the axis of rotation.

ry	Y component of the axis of rotation.

rz	Z component of the axis of rotation.

angle	Angle of rotation (in degrees).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityCTM()

RwModelBegin()

RwModelEnd()

RwRotateJointTM()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleCTM()

RwTransformCTM()

RwTranslateCTM()


RwRotateJointTM()

int

RwRotateJointTM(RPARAM rx, RPARAM ry, RPARAM rz, RPARAM angle);

Description

Pre-concatenates a rotation matrix onto the current joint transformation matrix.

Arguments

rx	X component of the axis of rotation.

ry	Y component of the axis of rotation.

rz	Z component of the axis of rotation.

angle	Angle of rotation (in degrees).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityJointTM()

RwModelBegin()

RwModelEnd()

RwRotateCTM()

RwRotateMatrix()

RwRotateMatrixCos()

RwTransformJointTM()


RwRotateMatrix()

RwMatrix4d *

RwRotateMatrix(RwMatrix4d *matrix, RPARAM rx, RPARAM ry, RPARAM rz, RPARAM angle, RwCombineOperation op);

Description

Builds a rotation matrix and applies it to matrix. The operation may be a pre-concatenation, post-concatenation, or replacement.

Arguments

matrix	Pointer to the matrix.

rx	X component of the axis of rotation.

ry	Y component of the axis of rotation.

rz	Z component of the axis of rotation.

angle	Angle of rotation (in degrees).

op	Combination operator.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwQueryRotateMatrix()

RwRotateCTM()

RotateJointCTM()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwRotateMatrixCos()

RwMatrix4d *

RwRotateMatrixCos(RwMatrix4d *matrix, RPARAM rx, RPARAM ry, RPARAM rz, RPARAM cosangle, RPARAM rotdir, RwCombineOperation op);

Description

Builds a rotation matrix and applies it to matrix. The angle of rotation is given by the cosine of the angle (cosangle) and a direction of rotation (rotdir). The operation may be a pre-concatenation, post-concatenation, or replacement.

Arguments

matrix	Pointer to the matrix.

rx	X component of the axis of rotation.

ry	Y component of the axis of rotation.

rz	Z component of the axis of rotation.

cosangle	Cosine of the angle of rotation

rotdir	Direction of rotation (a positive value specifies anti-clockwise rotation and a negative value specifies clockwise rotation).

op	Combination operator.

Return Value

The argument matrix if successful, and NULL otherwise.

Comments

This function should be used in preference to RwRotateMatrix() when the cosine of the angle of rotation is known. In such cases RwRotateMatrixCos() is more efficient than RwRotateMatrix().

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwQueryRotateMatrix()

RwRotateCTM()

RwRotateJointCTM()

RwRotateMatrix()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateMatrix()


RwScaleCTM()

int

RwScaleCTM(RPARAM sx, RPARAM sy, RPARAM sz);

Description

Pre-concatenates a scaling matrix onto the CTM.

Arguments

sx	Scale factor in the X axis.

sy	Scale factor in the Y axis.

sz	Scale factor in the Z axis.

Return Value

TRUE if successful, and FALSE otherwise

Comments

Note that if no scaling is to be applied CREAL(1.0) should be specified rather than CREAL(0.0).

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityCTM()

RwIdentityJointTM()

RwModelBegin()

RwModelEnd()

RwRotateCTM()

RwRotateJointTM()

RwScaleMatrix()

RwTransformCTM()

RwTransformJointTM()

RwTranslateCTM()


RwScaleMatrix()

RwMatrix4d *

RwScaleMatrix(RwMatrix4d *matrix, RPARAM sx, RPARAM sy, RPARAM sz, RwCombineOperation op);

Description

Builds a scaling matrix and applies it to matrix. The operation may be a pre-concatenation, post-concatenation, or replacement.

Arguments

matrix	Pointer to the matrix.

sx	Scale factor in the X axis.

sy	Scale factor in the Y axis.

sz	Scale factor in the Z axis.

op	Combination operator.

Return Value

The argument matrix if successful, and NULL otherwise.

Comments

Note that if no scaling is to be applied CREAL(1.0) should be specified rather than CREAL(0.0).

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleCTM()

RwTransformMatrix()

RwTranslateMatrix()


RwScaleVector()

RwV3d *

RwScaleVector(RwV3d *a, RPARAM scale, RwV3d *b);

Description

Scales a vector.

Arguments

a	Pointer to the vector.

scale	Scale factor.

b	Pointer to the vector that will receive the result.

Return Value

The argument b if successful, and NULL otherwise.

See Also

RwAddVector()

RwCrossProduct()

RwDotProduct()

RwNormalize()

RwSubtractVector()

RwTransformVector()


RwScratchMatrix()

RwMatrix4d *

RwScratchMatrix(void);

Description

Retrieves the current scratch matrix (the top matrix of the scratch matrix stack).

Arguments

None.

Return Value

A pointer to the scratch matrix.

Comments

The scratch matrix stack is a convenient source of temporary matrices for building transforms.

The matrix returned by RwScratchMatrix() must not be destroyed with RwDestroyMatrix(). The scratch matrix stack is destroyed by RenderWare when RwClose() is called.

RwScratchMatrix() supersedes the V1.2 API function RwCurrentMatrix(). Calls to RwCurrentMatrix() must be replaced with RwScratchMatrix().

See Also

RwClose()

RwCreateMatrix()

RwDestroyMatrix()

RwPopScratchMatrix()

RwPushScratchMatrix()


RwSetAxisAlignment()

int

RwSetAxisAlignment(RwAxisAlignment alignment);

Description

Sets the axis alignment type of the current clump under construction.

Arguments

alignment	The axis alignment type.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The following axis alignment types are supported:

•	rwNOAXISALIGNMENT

The clump is not axis aligned, it is unconstrained.

•	rwALIGNAXISZORIENTX

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local X axis is preserved.

•	rwALIGNAXISZORIENTY

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local Y axis is preserved.

•	rwALIGNAXISXYZ

The local X, Y and Z axes of the clump are aligned with the camera's "Look Right", "Look Up" and "Look At" vectors respectively.

A clump that is axis aligned will be aligned with the view planes of all camera's used to view that clump.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwCreateDecal()

RwCreateSprite()

RwSetClumpAxisAlignment()


RwSetCameraBackColor()

RwCamera *

RwSetCameraBackColor(RwCamera *camera, RPARAM r, RPARAM g, RPARAM b);

Description

Sets the camera's background fill color.

Arguments

camera	Pointer to the camera.

r	Red component of the color in the range CREAL(0.0) to CREAL(1.0).

g	Green component of the color in the range CREAL(0.0) to CREAL(1.0).

b	Blue component of the color in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

This function is identical to RwSetCameraBackColorStruct() with the exception that it takes individual RPARAMs for the red, green and blue components of the color rather than an RwRGBColor structure as the color specification.

The background of the camera's viewport is cleared when RwClearCameraViewport() is called.

If the camera does not have a backdrop raster then the camera's entire viewport is filled with the background color. It the camera has a backdrop raster then those areas of the viewport outside the backdrop viewport rectangle will be filled with the background color.

See Also

RwClearCameraViewport()

RwGetCameraBackColor()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropViewportRect()


RwSetCameraBackColorStruct()

RwCamera *

RwSetCameraBackColorStruct(RwCamera *camera, RwRGBColor *color);

Description

Sets the camera's background fill color.

Arguments

camera	Pointer to the camera.

color	Pointer to the color.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

This function is identical to RwSetCameraBackColor() with the exception that it takes an RwRGBColor structure as the color specification rather than individual RPARAMs for the red, green and blue components of the color.

The background of the camera's viewport is cleared when RwClearCameraViewport() is called.

If the camera does not have a backdrop raster then the camera's entire viewport is filled with the background color. It the camera has a backdrop raster then those areas of the viewport outside the backdrop viewport rectangle will be filled with the background color.

See Also

RwClearCameraViewport()

RwGetCameraBackColor()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropViewportRect()


RwSetCameraBackdrop()

RwCamera *

RwSetCameraBackdrop(RwCamera *camera, RwRaster *raster);

Description

Sets the camera's backdrop raster.

Arguments

camera	Pointer to the camera.

raster	Pointer to the raster.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

To ensure that a camera has a visible backdrop it is not only necessary to set the camera's backdrop but also to set the rectangle of the viewport which will be filled by the backdrop. As the default backdrop viewport rectangle has a width and height of 0 the backdrop will not be visible unless a non-empty rectangle is specified. This is accomplished by RwSetCameraBackdropViewportRect().

Areas of the viewport outside the backdrop viewport rectangle will be filled with the camera's background color.

The backdrop raster associated with a camera is not destroyed automatically when the camera is destroyed. The backdrop raster (if any) must by explicitly destroyed by RwDestroyRaster().

See Also

RwDestroyRaster()

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwSetCameraBackColorStruct()

RwSetCameraBackColorStruct()

RwSetCameraBackdropOffset()

RwSetCameraBackdropViewportRect()


RwSetCameraBackdropOffset()

RwCamera *

RwSetCameraBackdropOffset(RwCamera *camera, int x, int y);

Description

Sets the offset (from the origin of the camera's backdrop viewport rectangle) of the camera's backdrop raster.

Arguments

camera 	Pointer to the camera.

<BULL>The horizontal offset (in viewport space units).

y	The vertical offset (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The x and y offset (modulo the width and height of the backdrop) specify the pixel in the backdrop which will be mapped to the origin of the backdrop viewport rectangle. Therefore, the effect of increasing the x offset will be to scroll the backdrop to the left and increasing the y offset will scroll the backdrop up.

See Also

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwSetCameraBackdrop()

RwSetCameraBackdropViewportRect()


RwSetCameraBackdropViewportRect()

RwCamera *

RwSetCameraBackdropViewportRect(RwCamera *camera, int x, int y, int width, int height);

Description

Sets the rectangular area of the viewport into which the camera's backdrop raster is rendered.

Arguments

camera	Pointer to the camera.

x	The x coordinate of rectangle (in viewport space coordinates).

y	The y coordinate of rectangle (in viewport space coordinates).

width	The width of the rectangle (in viewport space units).

height	The height of the rectangle (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The default backdrop viewport rectangle has a width and height of 0. In order to ensure that the backdrop raster is visible it is necessary to set a viewport rectangle which has a non-zero width and height.

If the backdrop viewport rectangle is larger than the backdrop raster, the raster will be tiled to fill the rectangle. If the backdrop raster is larger than the viewport rectangle it will be cropped to fit the rectangle.

If the backdrop viewport rectangle does not fill the entire viewport, areas of the viewport outside the backdrop rectangle will be filled with the camera's background color.

The backdrop viewport rectangle is not automatically changed when the camera' viewport is modified. RwSetCameraBackdropViewportRect() should be used to modify the backdrop viewport rectangle appropriately when the camera's viewport is modified.

See Also

RwGetCameraBackColor()

RwGetCameraBackdrop()

RwGetCameraBackdropOffset()

RwGetCameraBackdropViewportRect()

RwSetCameraBackColorStruct()

RwSetCameraBackColorStruct()

RwSetCameraBackdrop()

RwSetCameraBackdropOffset()

RwSetCameraViewport()


RwSetCameraData()

RwCamera *

RwSetCameraData(RwCamera *camera, void *data);

Description

Sets the camera's user data pointer.

Arguments

camera	Pointer to the camera.

data	User data pointer.

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraData()


RwSetCameraLookAt()

RwCamera *

RwSetCameraLookAt(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Sets the camera's "Look At" vector, while maintaining its position.

Arguments

camera	Pointer to the camera.

x	X component of the vector.

y	Y component of the vector.

z	Z component of the vector.

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwGetCameraLookAt()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwSetCameraLookUp()

RwTiltCamera()

RwTransformCameraOrientation()


RwSetCameraLookUp()

RwCamera *

RwSetCameraLookUp(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Sets the camera's "Look Up" (or V) vector, while maintaining its position.

Arguments

camera	Pointer to the camera.

x	X component of the vector.

y	Y component of the vector.

z	Z component of the vector.

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwGetCameraLookUp()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwTiltCamera()

RwTransformCameraOrientation()


RwSetCameraNearClipping()

RwCamera *

RwSetCameraNearClipping(RwCamera *camera, RPARAM near);

Description

Sets the distance from the camera position to the near (front) clipping plane.

Arguments

camera	Pointer to the camera.

near	Distance (in world space units) from the camera to the front clipping plane.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The default near clipping distance is CREAL(0.05). The minimum clipping distance which can be specified is CREAL(0.025).

See Also

RwCreateCamera()

RwGetCameraNearClipping()


RwSetCameraPosition()

RwCamera *

RwSetCameraPosition(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Sets the camera's position in world space coordinates.

Arguments

camera	Pointer to the camera.

x	X coordinate of the new camera position (in world space coordinates).

y	Y coordinate of the new camera position (in world space coordinates).

z	Z coordinate of the new camera position (in world space coordinates).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwGetCameraPosition()

RwResetCamera()

RwTransformCamera()

RwVCMoveCamera()

RwWCMoveCamera()


RwSetCameraProjection()

RwCamera *

RwSetCameraProjection(RwCamera *camera, RwCameraProjection model);

Description

Sets the camera's projection model.

Arguments

camera	Pointer to the camera.

model	Camera projection model.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The projection types are:

•	rwPARALLEL    Parallel projection.

•	rwPERSPECTIVE    Perspective projection.

See Also

RwCreateCamera()

RwGetCameraProjection()


RwSetCameraViewOffset()

RwCamera *

RwSetCameraViewOffset(RwCamera *camera, RPARAM x, RPARAM y);

Description

Sets the camera's view offset, thereby shearing the view volume.

Arguments

camera	Pointer to the camera.

x	View offset displacement in the direction of the camera's "Look Right" vector (in world space units).

y	View offset displacement in the direction of the camera's "Look Up" vector (in world space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The x and y offsets are measured in world space units in a plane passing through the camera position and parallel to the view window, in the directions of the camera's "Look Right" and "Look Up" vectors respectively. For a perspective view, this moves the apex of the view pyramid whilst its edges remain fixed to the corners of the view window. For a parallel view, this shears the view parallelepiped whilst its edges remain fixed to the corners of the view window.

Successive calls to RwSetCameraViewOffset() specify the offset as absolute values from the initial unsheared camera position; successive offsets are not accumulated as relative displacements.

See Also

RwGetCameraViewOffset()

RwResetCamera()


RwSetCameraViewport()

RwCamera *

RwSetCameraViewport(RwCamera *camera, int x, int y, int width, int height);

Description

Defines a rectangular area of the display (screen or window) onto which the camera's view window is mapped.

Arguments

camera	Pointer to the camera.

x	X coordinate of the viewport origin (in device space coordinates).

y	Y coordinate of the viewport origin (in device space coordinates).

width	Width of the viewport (in device space units).

height	Height of the viewport (in device space units).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

The viewport origin is the top left of the viewport.

See Also

RwCreateCamera()

RwGetCameraViewport()

RwSetCameraBackdropViewportRect()

RwSetCameraViewwindow()


RwSetCameraViewwindow()

RwCamera *

RwSetCameraViewwindow(RwCamera *camera, RPARAM width, RPARAM height);

Description

Sets the relative size of the view window in the view plane. Larger values give a wider field of view, smaller values a narrower field of view.

Arguments

camera	Pointer to the camera.

width	Width of the view window (in world space units).

height	Height of the view window (in world space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwCreateCamera()

RwGetCameraViewwindow()

RwResetCamera()

RwSetCameraViewport()


RwSetClumpAxisAlignment()

RwClump *

RwSetClumpAxisAlignment(RwClump *clump, RwAxisAlignment alignment);

Description

Sets the axis alignment type of the clump.

Arguments

clump	Pointer to the clump.

alignment	The axis alignment type.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The axis alignment types are:

•	rwNOAXISALIGNMENT

The clump is not axis aligned, it is unconstrained.

•	rwALIGNAXISZORIENTX

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local X axis is preserved.

•	rwALIGNAXISZORIENTY

The clump's local Z axis is aligned with the "Look At" vector of the camera, but the orientation of the 2D projection of the clump's local Y axis is preserved.

•	rwALIGNAXISXYZ

The local X, Y and Z axes of the clump are aligned with the camera's "Look Right", "Look Up" and "Look At" vectors respectively.

A clump that is axis aligned will be aligned with the view planes of all camera's used to view that clump.

See Also

RwCreateDecal()

RwCreateSprite()

RwGetClumpAxisAlignment()

RwSetAxisAlignment()


RwSetClumpData()

RwClump *

RwSetClumpData(RwClump *clump, void *data);

Description

Sets the clump's user data pointer.

Arguments

clump	Pointer to the clump.

data	User data pointer.

Return Value

The argument clump if successful, and NULL otherwise.

See Also

RwGetClumpData()


RwSetClumpHints()

RwClump *

RwSetClumpHints(RwClump *clump, RwClumpHints hints);

Description

Sets the hints of the clump to those given. A clump's hints enable RenderWare to render a scene containing that clump more efficiently.

Arguments

clump	Pointer to the clump.

hints	A bitfield representing a hint (or bitwise or of hints).

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Unlike RwAddHintToClump(), which simply adds one or more hints to a clump's set of hints, RwSetClumpHints() replaces the entire set of hints of a clump with those specified.

The clump hints are:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

See Also

RwAddHintToClump()

RwGetClumpHints()

RwRemoveHintFromClump()

RwSetHints()


RwSetClumpState()

RwClump *

RwSetClumpState(RwClump *clump, RwState state);

Description

Sets the clump's on/off state.

Arguments

clump	Pointer to the clump.

state	The clump state.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The clump's state determines whether the clump will be considered as a candidate for rendering and picking.

The clump states are:

•	rwON    The clump will be a candidate for rendering and picking.

•	rwOFF    The clump will not be a candidate for rendering and picking.

A state of rwON should be interpreted as making the clump a candidate for rendering and picking. Such a clump will not appear if it lies outside the view volume and it will not be picked unless one of its polygons is the foremost under the pick position.

The state affects only the clump to which it is applied and not to the clump's children. Thus, to prevent a single clump in a hierarchy from being rendered it is preferable to modify the clump's state rather than to remove it from a scene with RwRemoveClumpFromScene().

See Also

RwAddClumpToScene()

RwDestroyClump()

RwGetClumpState()

RwRemoveClumpFromScene()


RwSetClumpTag()

RwClump *

RwSetClumpTag(RwClump *clump, int tag);

Description

Assigns the integer tag to the clump.

Arguments

clump	Pointer to the clump.

tag	Integer tag value to set.

Return Value

The argument clump if successful, NULL otherwise.

See Also

RwGetClumpTag()

RwSetPolygonTag()

RwSetTag()


RwSetClumpVertex()

RwClump *

RwSetClumpVertex(RwClump *clump, int index, RwV3d *coords);

Description

Sets the object space position of the vertex which belongs to clump and has the vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

coords	Pointer to the point that specifies the vertex's position (in object space coordinates).

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The vertex index is an integer greater than 0 and less than or equal to the number of vertices that belong to the clump.

As this function modifies the geometry of the clump, the clump is made editable (the rwEDITABLE hint is set) by this function.

See Also

RwGetClumpVertex()

RwSetClumpVertexNormal()

RwSetClumpVertexUV()

RwSetClumpVertices()


RwSetClumpVertexNormal()

RwClump *

RwSetClumpVertexNormal(RwClump *clump, int index, RwV3d *normal);

Description

Sets the unit shading normal at the vertex which belongs to clump and has the vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

normal	Pointer to the vector that specifies the unit shading normal.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

By default, RenderWare automatically calculates unit shading normals. When a clump is read, created or edited the unit shading normals are recalculated. However, In addition to setting the normal, RwSetClumpVertexNormal() suspends automatic recalculation of the normal at the specified vertex.

To enable automatic recalculation of the normal at a vertex use RwCalculateClumpVertexNormal().

See Also

RwCalculateClumpVertexNormal()

RwGetClumpVertexNormal()

RwSetClumpVertex()

RwSetClumpVertexUV()


RwSetClumpVertexUV()

RwClump *

RwSetClumpVertexUV(RwClump *clump, int index, RPARAM u, RPARAM v);

Description

Sets the texture (U, V) coordinates of the vertex which belongs to clump and has the vertex index index.

Arguments

clump	Pointer to the clump.

index	The vertex index.

u	U coordinate of the vertex's texture coordinates.

v	V coordinate of the vertex's texture coordinates.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

The vertex index is an integer greater than 0 and less than or equal to the number of vertices that belong to the clump.

See Also

RwCubicTexturizeClump()

RwEnvMapClump()

RwGetClumpVertexUV()

RwSetClumpVertex()

RwSetClumpVertexNormal()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetPolygonUV()

RwSphericalTexturizeClump()


RwSetClumpVertices()

RwClump *

RwSetClumpVertices(RwClump *clump, int *indices, RwV3d *coords, int nverts);

Description

Sets the object space coordinates of one or more vertices of the clump.

Arguments

clump	Pointer to the clump.

indices	Pointer to an array of vertex indices.

coords	Pointer to an array of vertex coordinates (in object space coordinates).

nverts	Number of vertices whose coordinates will be modified.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

Each element of the indices array gives the vertex index of a vertex to modify, the corresponding element of the coords array gives the new coordinates of that vertex.

The arrays indices and coords must be of length nverts. There must be at least numverts vertices in the clump.

It is considerably more efficient to use a single call to RwSetClumpVertices() then multiple calls to RwSetClumpVertex() when modifying two or more vertices of a clump.

As this function modifies the geometry of the clump, the clump is made editable (the rwEDITABLE hint is set) by this function.

See Also

RwGetClumpVertex()

RwSetClumpVertex()

RwSetClumpVertexNormal()

RwSetClumpVertexUV()


RwSetDebugAssertionState()

void

RwSetDebugAssertionState(RwDebugState state);

Description

Enables or disables the generation of assertion messages.

Arguments

state	The enable/disable flag.

Return Value

None.

Comments

The assertion message states are:

•	rwENABLE    Assertion messages are enabled.

•	rwDISABLE    Assertion messages are disabled.

See Also

RwGetDebugAssertionState()

RwSetDebugMessageState()

RwSetDebugOutputState()

RwSetDebugScriptState()


RwSetDebugMessageState()

void

RwSetDebugMessageState(RwDebugState state);

Description

Enables or disables the generation of miscellaneous messages.

Arguments

state	The enable/disable flag.

Return Value

None.

Comments

The miscellaneous message states are:

•	rwENABLE     Miscellaneous messages are enabled.

•	rwDISABLE     Miscellaneous messages are disabled.

See Also

RwGetDebugMessageState()

RwSetDebugAssertionState()

RwSetDebugOutputState()

RwSetDebugScriptState()


RwSetDebugOutputState()

void

RwSetDebugOutputState(RwDebugState state);

Description

Enables or disables the generation of all types of debugging messages.

Arguments

state	The debugging state.

Return Value

None.

Comments

This function is equivalent to calling RwSetDebugAssertionState(), RwSetDebugMessageState(), and RwSetDebugTraceState() with the argument state.

The message states are:

•	rwENABLE     Messages are enabled.

•	rwDISABLE     Messages are disabled.

See Also

RwGetDebugAssertionState()

RwGetDebugMessageState()

RwGetDebugScriptState()

RwSetDebugAssertionState()

RwSetDebugMessageState()

RwSetDebugScriptState()


RwSetDebugScriptState()

void

RwSetDebugScriptState(RwDebugState state);

Description

Enables or disables the generation of script trace messages.

Arguments

state	The enable/disable flag.

Return Value

None.

Comments

The script trace message states are:

•	rwENABLE     Script trace messages are enabled.

•	rwDISABLE     Script trace messages are disabled.

See Also

RwGetDebugScriptState()

RwSetDebugAssertionState()

RwSetDebugMessageState()

RwSetDebugOutputState()


RwSetDebugSeverity()

void

RwSetDebugSeverity(RwDebugSeverity severity);

Description

Sets the minimum severity level for the reporting of debugging messages.

Arguments

severity	The minimum severity level.

Return Value

None.

Comments

The debug message severity levels are:

•	rwINFORM    Control flow annotations, non-fatal exceptions and fatal exceptions are all enabled.

•	rwWARNING    Non-fatal exceptions and fatal exceptions are enabled.

•	rwERROR    Fatal exceptions are enabled.

See Also

RwGetDebugSeverity()


RwSetDebugStream()

int

RwSetDebugStream(FILE *stream);

Description

Sets the current debugging stream.

Arguments

stream	File pointer.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function is useful in situations where a file pointer is available but a file name is not, i.e., files that have been opened previously or standard streams such as stderr.

See Also

RwCloseDebugStream()

RwOpenDebugStream()


RwSetHints()

int

RwSetHints(RwClumpHints hints);

Description

Sets the hints of the current clump under construction to those given. A clump's hints enable RenderWare to render a scene containing that clump more efficiently.

Arguments

hints	A bitfield representing a hint (or bitwise or of hints).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The clump hints are:

•	rwCONTAINER    The clump spatially contains other clumps.

•	rwHS     Action should be taken to prevent   hidden surfaces from being visible when the clump is rendered.

•	rwEDITABLE    The clump's geometry is editable (its vertices can be moved and new vertices and polygons added).

Unlike RwAddHint(), which simply adds one or more hints to the current clump's set of hints, RwSetHints() replaces the current clump's entire set of hints with those specified.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() block.

See Also

RwAddHint()

RwClumpBegin()

RwClumpEnd()

RwRemoveHint()

RwSetClumpHints()


RwSetLightBrightness()

RwLight *

RwSetLightBrightness(RwLight *light, RPARAM brightness);

Description

Sets the light's brightness.

Arguments

light	Pointer to the light.

brightness	 Brightness, in the range CREAL(-1.0) to CREAL(1.0).

Return Value

The argument light if successful, and NULL otherwise.

See Also

RwCreateLight()

RwGetLightBrightness()


RwSetLightConeAngle()

RwLight *

RwSetLightConeAngle(RwLight *light, RPARAM angle);

Description

Sets the angle at which a conical light illuminates objects (measured from the direction vector of the light).

Arguments

light	Pointer to the light.

angle	Cone angle (in degrees).

Return Value

The argument light if successful, and NULL otherwise.

Comments

This function is only valid for conical lights (those lights created with the light type rwCONICAL).

See Also

RwCreateLight()

RwGetLightConeAngle()

RwGetLightType()


RwSetLightData()

RwLight *

RwSetLightData(RwLight *light, void *data);

Description

Sets the light's user data pointer.

Arguments

light	Pointer to the light.

data	User data pointer.

Return Value

The argument light if successful, and NULL otherwise.

See Also

RwGetLightData()


RwSetLightPosition()

RwLight *

RwSetLightPosition(RwLight *light, RPARAM x, RPARAM y, RPARAM z);

Description

Sets the position of a point or conical light source in world space coordinates.

Arguments

light	Pointer to the light.

x	X coordinate of the light position (in world space coordinates).

y	Y coordinate of the light position (in world space coordinates).

z	Z coordinate of the light position (in world space coordinates).

Return Value

The argument light if successful, and NULL otherwise.

Comments

This function is only valid for point and conical lights (those lights created with the light types rwPOINT or rwCONICAL).

See Also

RwCreateLight()

RwGetLightPosition()

RwGetLightType()

RwTransformLight()


RwSetLightState()

RwLight *

RwSetLightState(RwLight *light, RwState state);

Description

Turns the light on or off.

Arguments

light	Pointer to the light.

state	The light state.

Return Value

The argument light if successful, and NULL otherwise.

Comments

The light states are:

•	rwON    The light is on.

•	rwOFF    The light is off.

See Also

RwGetLightState()


RwSetLightVector()

RwLight *

RwSetLightVector(RwLight *light, RPARAM x, RPARAM y, RPARAM z);

Description

Sets the illumination vector of a directional or conical light source.

Arguments

light	Pointer to the light.

x	X component of the light vector.

y	Y component of the light vector.

z	Z component of the light vector.

Return Value

The argument light if successful, and NULL otherwise.

Comments

This function is only valid for directional and conical lights (those lights created with the light types rwDIRECTIONAL or rwCONICAL).

See Also

RwCreateLight()

RwGetLightType()

RwGetLightVector()

RwTransformLight()


RwSetMaterialAmbient()

RwMaterial *

RwSetMaterialAmbient(RwMaterial *material, RPARAM ka);

Description

Sets the material's ambient reflection coefficient.

Arguments

material	Pointer to the material.

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

See Also

RwGetMaterialAmbient()

RwSetMaterialDiffuse()

RwSetMaterialSpecular()

RwSetMaterialSurface()

RwSetPolygonAmbient()

RwSetSurfaceAmbient()


RwSetMaterialColor()

RwMaterial *

RwSetMaterialColor(RwMaterial *material, RPARAM r, RPARAM g, RPARAM b);

Description

Sets the material's color.

Arguments

material	Pointer to the material.

r	Red component of the color, in the range CREAL(0.0) to CREAL(1.0).

g	Green component of the color, in the range CREAL(0.0) to CREAL(1.0).

b	Blue component of the color, in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

Comments

This function is identical to RwSetMaterialColorStruct() with the exception that it takes individual RPARAMs for the red, green and blue components of the color rather than an RwRGBColor structure as the color specification.

See Also

RwGetMaterialColor()

RwSetMaterialColorStruct()

RwSetPolygonColor()

RwSetPolygonColorStruct()

RwSetSurfaceColor()


RwSetMaterialColorStruct()

RwMaterial *

RwSetMaterialColorStruct(RwMaterial *material, RwRGBColor *color);

Description

Sets the material's color.

Arguments

material	Pointer to the material.

color	Pointer to the color.

Return Value

The argument material if successful, and NULL otherwise.

Comments

This function is identical to RwSetMaterialColor() with the exception that it takes an RwRGBColor structure as the color specification rather than individual RPARAMs for the red, green and blue components of the color. This can be useful as a call-back in RwForAll...() functions.

See Also

RwGetMaterialColor()

RwSetMaterialColor()

RwSetPolygonColor()

RwSetPolygonColorStruct()

RwSetSurfaceColor()


RwSetMaterialDiffuse()

RwMaterial *

RwSetMaterialDiffuse(RwMaterial *material, RPARAM kd);

Description

Sets the material's diffuse reflection coefficient.

Arguments

material	Pointer to the material.

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

See Also

RwGetMaterialDiffuse()

RwSetMaterialAmbient()

RwSetMaterialSpecular()

RwSetMaterialSurface()

RwSetPolygonDiffuse()

RwSetSurfaceDiffuse()


RwSetMaterialGeometrySampling()

RwMaterial *

RwSetMaterialGeometrySampling(RwMaterial *material, RwGeometrySampling type);

Description

Sets the material's geometry sampling type.

Arguments

material	Pointer to the material.

type	The geometry sampling type.

Return Value

The argument material if successful, and NULL otherwise.

Comments

The geometry sampling types are:

•	rwPOINTCLOUD    Render geometry as a cloud of points.

•	rwWIREFRAME    Render geometry as a wireframe of polygon edges.

•	rwSOLID    Render geometry as a solid bounded by filled polygons.

See Also

RwGetMaterialGeometrySampling()

RwSetMaterialLightSampling()

RwSetPolygonGeometrySampling()

RwSetSurfaceGeometrySampling()


RwSetMaterialLightSampling()

RwMaterial *

RwSetMaterialLightSampling(RwMaterial *material, RwLightSampling type);

Description

Sets the material's light sampling type.

Arguments

material	Pointer to the material.

type	The light sampling type.

Return Value

The argument material if successful, and NULL otherwise.

Comments

The light sampling types are:

•	rwFACET    Flat shading.

•	rwVERTEX    Smooth shading.

See Also

RwGetMaterialLightSampling()

RwSetMaterialGeometrySampling()

RwSetPolygonLightSampling()

RwSetSurfaceLightSampling()


RwSetMaterialOpacity()

RwMaterial *

RwSetMaterialOpacity(RwMaterial *material, RPARAM opacity);

Description

Sets the material's opacity.

Arguments

material	Pointer to the material.

opacity	Opacity in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

Comments

An opacity of CREAL(1.0) yields an entirely opaque material. An opacity of CREAL(0.0) yields an entirely transparent material.

See Also

RwGetMaterialOpacity()

RwSetPolygonOpacity()

RwSetSurfaceOpacity()


RwSetMaterialSpecular()

RwMaterial *

RwSetMaterialSpecular(RwMaterial *material, RPARAM ks);

Description

Sets the material's specular reflection coefficient.

Arguments

material	Pointer to the material.

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

See Also

RwGetMaterialSpecular()

RwSetMaterialAmbient()

RwSetMaterialDiffuse()

RwSetMaterialSurface()

RwSetPolygonSpecular()

RwSetSurfaceSpecular()


RwSetMaterialSurface()

RwMaterial *

RwSetMaterialSurface(RwMaterial *material, RPARAM ka, RPARAM kd, RPARAM ks);

Description

Sets the material's surface attributes (ambient, diffuse, and specular reflection coefficients).

Arguments

material	Pointer to the material.

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument material if successful, and NULL otherwise.

See Also

RwGetMaterialAmbient()

RwGetMaterialDiffuse()

RwGetMaterialSpecular()

RwSetMaterialAmbient()

RwSetMaterialDiffuse()

RwSetMaterialSpecular()

RwSetPolygonSurface()

RwSetSurface()


RwSetMaterialTexture()

RwMaterial *

RwSetMaterialTexture(RwMaterial *material, RwTexture *texture);

Description

Sets the material's texture.

Arguments

material	Pointer to the material.

texture	Pointer to the texture.

Return Value

The argument material if successful, and NULL otherwise.

Comments

NULL may be passed as the second argument to remove the material's texture.

See Also

RwCreateTexture()

RwFindNamedTexture()

RwGetMaterialTextureModes()

RwGetNamedTexture()

RwReadNamedTexture()

RwReadTexture()

RwSetPolygonTexture()

RwSetSurfaceTexture()


RwSetMaterialTextureModes()

RwMaterial *

RwSetMaterialTextureModes(RwMaterial *material, RwTextureModes modes);

Description

Sets the texture modes of the material. Texture modes permit fine grain control over the rendering of textures.

Arguments

material	Pointer to the material.

modes	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument material if successful, and NULL otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

Unlike RwAddTextureModeToMaterial(), which simply adds one or more texture modes to a material's set of modes, RwSetMaterialTextureModes() replaces a material's entire set of modes with those specified.

See Also

RwAddTextureModeToMaterial()

RwGetMaterialTextureModes()

RwRemoveTextureModeFromSurface()

RwSetMaterialLightSampling()

RwSetMaterialTextureModes()

RwSetPolygonTextureModes()

RwSetSurfaceTextureModes()


RwSetMatrixElement()

RwMatrix4d *

RwSetMatrixElement(RwMatrix4d *matrix, int row, int col, RPARAM element);

Description

Sets an individual element of the matrix.

Arguments

matrix	Pointer to the matrix.

row	Row index in the range 0 to 3.

col	Column index in the range 0 to 3.

element	New matrix element.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwGetMatrixElement()

RwSetMatrixElement()

RwSetMatrixElements()


RwSetMatrixElements()

RwMatrix4d *

RwSetMatrixElements(RwMatrix4d *matrix, RwReal elements[4][4]);

Description

Sets the elements of a matrix from a four by four array of RwReals. The first four entries of the array are copied into the top row of the matrix.

Arguments

matrix	Pointer to the matrix.

elements	Pointer to a four by four array of RwReals holding the values to be copied.

Return Value

The argument matrix if successful, and NULL otherwise.

Comments

By convention a matrix is taken to transform a row vector by post multiplication.

The final column of the array will normally be [CREAL(0.0), CREAL(0.0), CREAL(0.0), CREAL(1.0)].

This function supersedes the V1.2 API function RwSetMatrix() which had similar semantics but returned matrix elements in a different order. RwSetMatrix() is no longer a supported RenderWare API call and must be replaced by RwSetMatrixElements().

See Also

RwGetMatrixElement()

RwGetMatrixElements()

RwSetMatrixElement()


RwSetPolygonAmbient()

RwPolygon3d *

RwSetPolygonAmbient(RwPolygon3d *polygon, RPARAM ka);

Description

Sets the ambient reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonAmbient()

RwSetMaterialAmbient()

RwSetPolygonDiffuse()

RwSetPolygonSpecular()

RwSetPolygonSurface()

RwSetSurfaceAmbient()


RwSetPolygonColor()

RwPolygon3d *

RwSetPolygonColor(RwPolygon3d *polygon, RPARAM r, RPARAM g, RPARAM b);

Description

Sets the color of the polygon's material.

Arguments

polygon	Pointer to the polygon.

r	Red component of the color, in the range CREAL(0.0) to CREAL(1.0).

g	Green component of the color, in the range CREAL(0.0) to CREAL(1.0).

b	Blue component of the color, in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

This function is identical to RwSetPolygonColorStruct() with the exception that it takes individual RPARAMs for the red, green and blue components of the color rather than an RwRGBColor structure as the color specification.

See Also

RwSetMaterialColor()

RwSetMaterialColorStruct()

RwSetPolygonColorStruct()

RwSetSurfaceColor()


RwSetPolygonColorStruct()

RwPolygon3d *

RwSetPolygonColorStruct(RwPolygon3d *polygon, RwRGBColor *color);

Description

Sets the color of the polygon's material.

Arguments

polygon	Pointer to the polygon.

color	Pointer to the color.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

This function is identical to RwSetPolygonColor() with the exception that it takes an RwRGBColor structure as the color specification rather than individual RPARAMs for the red, green and blue components of the color. This can be useful as a call-back in RwForAll…() functions.

See Also

RwGetPolygonColor()

RwSetMaterialColor()

RwSetMaterialColorStruct()

RwSetPolygonColor()

RwSetSurfaceColor()


RwSetPolygonData()

RwPolygon3d *

RwSetPolygonData(RwPolygon3d *polygon, void *data);

Description

Sets the polygon's user data pointer.

Arguments

polygon	Pointer to the polygon.

data	User data pointer.

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonData()


RwSetPolygonDiffuse()

RwPolygon3d *

RwSetPolygonDiffuse(RwPolygon3d *polygon, RPARAM kd);

Description

Sets the diffuse reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonDiffuse()

RwSetMaterialDiffuse()

RwSetPolygonAmbient()

RwSetPolygonSpecular()

RwSetPolygonSurface()

RwSetSurfaceDiffuse()


RwSetPolygonGeometrySampling()

RwPolygon3d *

RwSetPolygonGeometrySampling(RwPolygon3d *polygon, RwGeometrySampling type);

Description

Sets the geometry sampling type of the polygon's material.

Arguments

polygon	Pointer to the polygon.

type	The geometry sampling type.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

The geometry sampling types are:

•	rwPOINTCLOUD    Render geometry as a cloud of points.

•	rwWIREFRAME    Render geometry as a wireframe of polygon edges.

•	rwSOLID    Render geometry as a solid bounded by filled polygons.

See Also

RwGetPolygonGeometrySampling()

RwSetMaterialGeometrySampling()

RwSetPolygonLightSampling()

RwSetSurfaceGeometrySampling()


RwSetPolygonLightSampling()

RwPolygon3d *

RwSetPolygonLightSampling(RwPolygon3d *polygon, RwLightSampling type);

Description

Sets the light sampling type of the polygon's material.

Arguments

polygon	Pointer to the polygon.

type	The light sampling type.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

The light sampling types are:

•	rwFACET    Flat shading.

•	rwVERTEX    Smooth shading.

See Also

RwGetPolygonLightSampling()

RwSetMaterialLightSampling()

RwSetPolygonGeometrySampling()

RwSetSurfaceLightSampling()


RwSetPolygonMaterial()

RwPolygon3d *

RwSetPolygonMaterial(RwPolygon3d *polygon, RwMaterial *material);

Description

Sets the polygon's material to a copy of material material.

Arguments

polygon	Pointer to the polygon.

material	Pointer to the material.

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonMaterial()

RwSetPolygonAmbient()

RwSetPolygonColor()

RwSetPolygonColorStruct()

RwSetPolygonDiffuse()

RwSetPolygonGeometrySampling()

RwSetPolygonLightSampling()

RwSetPolygonOpacity()

RwSetPolygonSpecular()

RwSetPolygonSurface()

RwSetPolygonTexture()

RwSetPolygonTextureModes()


RwSetPolygonOpacity()

RwPolygon3d *

RwSetPolygonOpacity(RwPolygon3d *polygon, RPARAM opacity);

Description

Sets the opacity of the polygon's material.

Arguments

polygon	Pointer to the polygon.

opacity	Opacity in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

An opacity of CREAL(1.0) yields an entirely opaque polygon. An opacity of CREAL(0.0) yields an entirely transparent polygon.

See Also

RwGetPolygonOpacity()

RwSetMaterialOpacity()

RwSetSurfaceOpacity()


RwSetPolygonSpecular()

RwPolygon3d *

RwSetPolygonSpecular(RwPolygon3d *polygon, RPARAM ks);

Description

Sets the specular reflection coefficient of the polygon's material.

Arguments

polygon	Pointer to the polygon.

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonSpecular()

RwSetMaterialSpecular()

RwSetPolygonAmbient()

RwSetPolygonDiffuse()

RwSetPolygonMaterial()

RwSetPolygonSurface()

RwSetSurfaceSpecular()


RwSetPolygonSurface()

RwPolygon3d *

RwSetPolygonSurface(RwPolygon3d *polygon, RPARAM ka, RPARAM kd, RPARAM ks);

Description

Sets the surface attributes (ambient, diffuse, and specular reflection coefficients) of the polygon's material.

Arguments

polygon	Pointer to the polygon.

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwGetPolygonAmbient()

RwGetPolygonDiffuse()

RwGetPolygonSpecular()

RwSetMaterialSurface()

RwSetPolygonAmbient()

RwSetPolygonDiffuse()

RwSetPolygonSpecular()

RwSetSurface()


RwSetPolygonTag()

RwPolygon3d *

RwSetPolygonTag(RwPolygon3d *polygon, short int tag);

Description

Sets the polygon's tag.

Arguments

polygon	Pointer to the polygon.

tag	Integer tag value to set.

Return Value

The argument polygon if successful, and NULL otherwise.

See Also

RwFindTaggedPolygon()

RwGetPolygonTag()

RwPolygonExt()

RwQuadExt()

RwSetClumpTag()

RwTriangleExt()


RwSetPolygonTexture()

RwPolygon3d *

RwSetPolygonTexture(RwPolygon3d *polygon, RwTexture *texture);

Description

Sets the texture of the polygon's material.

Arguments

polygon	Pointer to the polygon.

texture	Pointer to the texture.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

NULL may be passed as the second argument to remove the polygon's material's texture.

See Also

RwCreateTexture()

RwFindNamedTexture()

RwGetNamedTexture()

RwGetPolygonTexture()

RwReadNamedTexture()

RwReadTexture()

RwSetMaterialTextureModes()

RwSetSurfaceTexture()


RwSetPolygonTextureModes()

RwPolygon3d *

RwSetPolygonTextureModes(RwPolygon3d *polygon, RwTextureModes modes);

Description

Sets the texture modes of a polygon's material. Texture modes permit fine grain control over the rendering of textures.

Arguments

polygon	Pointer to the polygon.

modes	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

Unlike RwAddTextureModeToPolygon(), which simply adds one or more texture modes to a polygon's material's set of modes, RwSetPolygonTextureModes() replaces a polygon's material's entire set of modes with those specified.

See Also

RwAddTextureModeToPolygon()

RwGetPolygonTextureModes()

RwRemoveTextureModeFromSurface()

RwSetMaterialTextureModes()

RwSetPolygonLightSampling()

RwSetPolygonTexture()

RwSetSurfaceTextureModes()


RwSetPolygonUV()

RwPolygon3d *

RwSetPolygonUV(RwPolygon3d *polygon, RwUV *uvarray);

Description

Sets the texture (U, V) coordinates for the polygon's vertices.

Arguments

polygon	Pointer to the polygon.

uvarray	Array of RwUV structures.

Return Value

The argument polygon if successful, and NULL otherwise.

Comments

Note that the array uvarray must be large enough to accommodate the texture coordinates of all of the polygon's vertices.

See Also

RwCubicTexturizeClump()

RwEnvMapClump()

RwGetClumpVertexUV()

RwGetPolygonNumSides()

RwGetPolygonUV()

RwSetClumpVertexUV()

RwSphericalTexturizeClump()

RwVertexExt()


RwSetRasterData()

RwRaster *

RwSetRasterData(RwRaster *raster, void *data);

Description

Sets the raster's user data pointer.

Arguments

raster	Pointer to the raster.

data	User data pointer.

Return Value

The argument raster if successful, and NULL otherwise.

See Also

RwGetRasterData()


RwSetSceneData()

RwScene *

RwSetSceneData(RwScene *scene, void *data);

Description

Sets the scene's user data pointer.

Arguments

scene	Pointer to the scene.

data	User data pointer.

Return Value

The argument scene if successful, and NULL otherwise.

See Also

RwGetSceneData()


RwSetShapePath()

int

RwSetShapePath(char *path, RwCombineOperation op);

Description

Modifies the shape path. The path may be prepended to (rwPRECONCAT), appended to (rwPOSTCONCAT), or replaced (rwREPLACE).

Arguments

path	Pointer to the new path string.

op	Combination operator.

Return Value

TRUE if successful, and FALSE otherwise.

See Also

RwGetNamedTexture()

RwGetShapePath()

RwReadNamedTexture()

RwReadRaster()

RwReadMaskRaster()

RwReadShape()

RwReadTexture()


RwSetSplineData()

RwSpline *

RwSetSplineData(RwSpline *spline, void *data);

Description

Sets the spline's user data pointer.

Arguments

spline	Pointer to the spline.

data	User data pointer.

Return Value

The argument spline if successful, and NULL otherwise.

See Also

RwGetSplineData()


RwSetSplinePoint()

RwSpline *

RwSetSplinePoint(RwSpline *spline, int index, RwV3d *point);

Description

Sets the specified control point of the spline.

Arguments

spline	Pointer to the spline.

index	Index of the control point to set, in the range 1 £ index £ total number of control points.

point	Pointer to the new control point of the spline.

Return Value

The argument spline if successful, and NULL otherwise.

Comments

Note that passing 1 as the value of argument index will set the first control point.

See Also

RwCreateSpline()

RwGetSplineNumPoints()

RwGetSplinePoint()


RwSetSurface()

int

RwSetSurface(RPARAM ka, RPARAM kd, RPARAM ks);

Description

Sets the surface attributes (ambient, diffuse, and specular reflection coefficients) of the current material.

Arguments

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialSurface()

RwSetPolygonSurface()

RwSetSurfaceAmbient()

RwSetSurfaceDiffuse()

RwSetSurfaceSpecular()


RwSetSurfaceAmbient()

int

RwSetSurfaceAmbient(RPARAM ka);

Description

Sets the ambient reflection coefficient of the current material.

Arguments

ka	Ambient reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialAmbient()

RwSetPolygonAmbient()

RwSetSurface()

RwSetSurfaceDiffuse()

RwSetSurfaceSpecular()


RwSetSurfaceColor()

int

RwSetSurfaceColor(RPARAM r, RPARAM g, RPARAM b);

Description

Sets the current material's color.

Arguments

r	Red component of the color, in the range CREAL(0.0) to CREAL(1.0).

g	Green component of the color, in the range CREAL(0.0) to CREAL(1.0).

b	Blue component of the color, in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialColor()

RwSetMaterialColorStruct()

RwSetPolygonColor()

RwSetPolygonColorStruct()


RwSetSurfaceDiffuse()

int

RwSetSurfaceDiffuse(RPARAM kd);

Description

Sets the current material's diffuse reflection coefficient.

Arguments

kd	Diffuse reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialDiffuse()

RwSetPolygonDiffuse()

RwSetSurface()


RwSetSurfaceGeometrySampling()

int

RwSetSurfaceGeometrySampling(RwGeometrySampling type);

Description

Sets the geometry sampling type of the current material.

Arguments

type	The geometry sampling type.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The geometry sampling types are:

•	rwPOINTCLOUD    Render geometry as a cloud of points.

•	rwWIREFRAME    Render geometry as a wireframe of polygon edges.

•	rwSOLID    Render geometry as a solid bounded by filled polygons.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialGeometrySampling()

RwSetPolygonGeometrySampling()

RwSetSurfaceLightSampling()


RwSetSurfaceLightSampling()

int

RwSetSurfaceLightSampling(RwLightSampling type);

Description

Sets the light sampling type of the current material.

Arguments

type	The light sampling type.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The light sampling types are:

•	rwFACET    Flat shading.

•	rwVERTEX    Smooth shading.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialLightSampling()

RwSetPolygonLightSampling()

RwSetSurfaceGeometrySampling()


RwSetSurfaceOpacity()

int

RwSetSurfaceOpacity(RPARAM opacity);

Description

Sets the opacity of the current material.

Arguments

opacity	Opacity in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

An opacity of CREAL(1.0) yields an entirely opaque polygon. An opacity of CREAL(0.0) yields an entirely transparent polygon.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialOpacity()

RwSetPolygonOpacity()


RwSetSurfaceSpecular()

int

RwSetSurfaceSpecular(RPARAM ks);

Description

Sets the current material's specular reflection coefficient.

Arguments

ks	Specular reflection coefficient in the range CREAL(0.0) to CREAL(1.0).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwModelBegin()

RwModelEnd()

RwSetMaterialSpecular()

RwSetPolygonSpecular()

RwSetSurface()


RwSetSurfaceTexture()

int

RwSetSurfaceTexture(char *name);

Description

Sets the current material's texture to the texture with the given name. RwGetNamedTexture() is used to find the texture. If the named texture is found (either in the dictionary stack or in the file system), the current material's texture is set to the texture found.

Arguments

name	Name of a texture.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

For more information on how the named texture is found, see the description of RwGetNamedTexture().

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwGetNamedTexture()

RwModelBegin()

RwModelEnd()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetSurfaceTextureExt()


RwSetSurfaceTextureExt()

int

RwSetSurfaceTextureExt(char *name, char *maskname);

Description

Sets the current material's texture to the texture with the given name, The mask raster read from the file given by maskname is applied to the texture.

RwGetNamedTexture() is used to find the texture. If the named texture is found (either in the dictionary stack or in the file system), the current material's texture is set to the texture found.

RwReadMaskRaster() is used to read the mask raster and RwMaskRaster() is used to apply the mask raster to the texture.

Arguments

name	Name of a texture.

maskname	Filename of the mask raster.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The masking of a texture is a destructive operation. All existing and future references to the texture will be affected by the masking operation.

For more information on how the named texture is searched for, see the description of RwGetNamedTexture(). For information on how the mask raster is read see RwReadMaskRaster() and for information on how the mask raster is applied see RwMaskTexture().

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwGetNamedTexture()

RwMaskTexture()

RwModelBegin()

RwModelEnd()

RwReadMaskRaster()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetSurfaceTexture()


RwSetSurfaceTextureModes()

int

RwSetSurfaceTextureModes(RwTextureModes modes);

Description

Sets the texture mode (or modes) of the current material. Texture modes permit fine grain control over the rendering of textures.

Arguments

modes	A bitfield representing a texture mode (or bitwise or of modes).

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The texture modes are:

•	rwLIT    The texture will be lit according to the current light sampling type of the material (rwFACET or rwVERTEX).

•	rwFORESHORTEN    The texture will be foreshortened in a perspectively correct manner.

For further information see the Texture Modes section.

Unlike RwAddTextureModeToSurface(), which simply adds one or more texture modes to the current material's set of modes, RwSetSurfaceTextureModes() replaces the current material's entire set of modes with those specified.

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwAddTextureModeToSurface()

RwRemoveTextureModeFromSurface()

RwSetMaterialTextureModes()

RwSetPolygonTextureModes()

RwSetSurfaceLightSampling()

RwSetSurfaceTexture()

RwSetSurfaceTextureExt()


RwSetTag()

int

RwSetTag(int tag);

Description

Assigns an integer tag to the current clump under construction.

Arguments

tag	The integer tag.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwFindTaggedClump()

RwPolygonExt()

RwQuadExt()

RwSetClumpTag()

RwSetPolygonTag()

RwTriangleExt()


RwSetTextureData()

RwTexture *

RwSetTextureData(RwTexture *texture, void *data);

Description

Sets the texture's user data pointer.

Arguments

texture	Pointer to the texture.

data	User data pointer.

Return Value

The argument texture if successful, and NULL otherwise.

See Also

RwGetTextureData()


RwSetTextureDictSearchMode()

int

RwSetTextureDictSearchMode(RwSearchMode mode);

Description

Sets the mode for searching the texture dictionary stack.

Arguments

mode	The texture dictionary stack search mode.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function affects how textures are searched for in the texture dictionary stack. In particular, it affects the behaviour of RwFindNamedTexture(), RwGetNamedTexture(), RwGetNumNamedTextures() and the RwForAllNamedTextures…() functions.

If the texture dictionary search mode is rwLOCAL, then only the current texture dictionary (the top element of the texture dictionary stack) is searched. If the search mode is rwGLOBAL, all dictionaries on the dictionary stack, from the current dictionary down, are searched until the named texture is found or there are no more dictionaries left to search.

The texture dictionary search modes are:

•	rwLOCAL    Search only the top most dictionary in the texture dictionary stack.

•	rwGLOBAL    Search all the dictionaries in the texture dictionary stack.

See Also

RwFindNamedTexture()

RwForAllNamedTextures()

RwGetNamedTexture()

RwGetNumNamedTextures()

RwGetTextureDictSearchMode()

RwTextureDictBegin()

RwTextureDictEnd()


RwSetTextureDithering()

int

RwSetTextureDithering(RwTextureDitherMode mode);

Description

Sets the current global texture dithering mode to be applied to subsequently loaded textures.

Arguments

mode	The texture dithering mode.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The current texture dithering mode is a global parameter which controls whether textures read from disk are dithered to increase perceived color resolution or not.

The following texture dither modes are supported:

•	rwDITHERON    Activates dithering.

•	rwDITHEROFF    Deactivates dithering.

•	rwAUTODITHER    Adopts the auto-dithering mode of raster reading to decide whether to dither textures.

The default mode is rwAUTODITHER.

See Also

RwGetNamedTexture()

RwGetTextureDithering()

RwGetTextureGammaCorrection()

RwReadNamedTexture()

RwReadRaster()

RwReadTexture()

RwSetTextureGammaCorrection()


RwSetTextureGammaCorrection()

int

RwSetTextureGammaCorrection(RwState mode);

Description

Sets the current global texture gamma correction mode applied to subsequently loaded textures.

Arguments

mode	The gamma correction mode.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

The current texture gamma correction mode is a global parameter which controls whether textures read from disk are gamma corrected or not.

The following texture gamma correction modes are supported:

•	rwON    Gamma correct.

•	rwOFF    Do not gamma correct.

The default mode is rwON.

See Also

RwGetNamedTexture()

RwGetTextureDithering()

RwGetTextureGammaCorrection()

RwReadNamedTexture()

RwReadRaster()

RwReadTexture()

RwSetTextureDithering()


RwSetTextureFrame()

RwTexture *

RwSetTextureFrame(RwTexture *texture, int index);

Description

Sets the current frame of the texture.

Arguments

texture	Pointer to the texture.

index	Frame number.

Return Value

The argument texture if successful, and NULL otherwise.

Comments

For those textures which consist of a sequence of frames this function will set the current frame to be the one with the given sequence number. Sequence numbers are in the range 0… n - 1, where n is the number of frames in the texture.

The current frame of a texture is the one used in all rendering of polygons associated with the texture.

See Also

RwGetTextureFrame()

RwGetTextureNumFrames()

RwTextureNextFrame()


RwSetTextureFrameStep()

RwTexture *

RwSetTextureFrameStep(RwTexture *texture, int step);

Description

Sets the texture's current frame step size. This is the number of frames by which the current frame index is incremented or decremented by a call to RwTextureNextFrame().

Arguments

texture	Pointer to the texture.

step	Number of frames to increment or decrement per call to RwTextureNextFrame().

Return Value

The argument texture if successful, and NULL otherwise.

Comments

A value of +1 (the default) will play the texture "movie" forward, one frame at a time. A value of -1 will play the "movie" backwards. Other values will play the "movie" at different speeds.

See Also

RwGetTextureFrame()

RwGetTextureFrameStep()

RwGetTextureNumFrames()

RwSetTextureFrame()

RwTextureNextFrame()


RwSetTextureRaster()

RwTexture *

RwSetTextureRaster(RwTexture *texture, RwRaster *raster);

Description

Sets the raster of the specified texture to raster.

Arguments

texture	Pointer to the texture.

raster	Pointer to the raster.

Return Value

The argument texture if successful, and NULL otherwise.

Comments

The raster selected into a texture provides the actual pixel values of the texture map. RwSetTextureRaster() is used to dynamically generate textures from platform specific bitmaps (via RwBitmapRaster()) or the viewport of a RenderWare camera (via RwGetCameraViewportRaster()).

Rasters cannot be shared between textures. It is an error to specify a raster already selected into a texture.

The texture's existing raster will be destroyed by this function.

raster must be of the correct size - 128 by 128 pixels (or 128 by n*128 pixels for a multi-frame texture). It is an error to call RwSetTextureRaster() with a raster that is not of this size.

See Also

RwBitmapRaster()

RwCreateRaster()

RwCreateTexture()

RwDestroyRaster()

RwDuplicateRaster()

RwGetCameraViewportRaster()

RwReadRaster()

RwSetTextureRaster()


RwSetUserDrawAlignment()

RwUserDraw *

RwSetUserDrawAlignment(RwUserDraw *userdraw, RwUserDrawAlignmentTypes alignment);

Description

Sets the user-draw's alignment flags. The user-draw's alignment flags determine which part of the user-draw's bounding box is used for alignment.

Arguments

userdraw	Pointer to the user-draw.

alignment	A bitfield representing a set of alignment flags.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

The alignment flags are:

•	0    Center the user-draw.

•	rwALIGNTOP    Align with the top edge of the user-draw.

•	rwALIGNBOTTOM    Align with the bottom edge of the user-draw.

•	rwALIGNLEFT    Align with the left edge of the user-draw.

•	rwALIGNRIGHT    Align with the right edge of the user-draw.

See Also

RwCreateUserDraw()

RwGetUserDrawAlignment()

RwSetUserDrawParentAlignment()


RwSetUserDrawCallback()

RwUserDraw *

RwSetUserDrawCallback(RwUserDraw *userdraw, void (*callback)(RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data));

Description

Sets the call-back function that renders the user-draw.

Arguments

userdraw	Pointer to the user-draw.

callback	Pointer to the call-back rendering function.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

User-draw call-backs should be declared as follows:

void callback(RwUserDraw *userdraw, void *camimage, RwRect *rect, void *data);

Where the call-back's arguments are as follows:

userdraw	Pointer to the user-draw to be rendered.

camimage	The camera's image buffer as returned by RwGetCameraImage() for the current camera. camimage is device dependent. For more information, see MS Windows 3.1 Specific Information.

rect	Pointer to a rectangle defining the area of the camera's image buffer into which the call-back may render. This rectangle is specified in viewport space coordinates, i.e., (0, 0) is the origin of the viewport.

data	Pointer to the user data of the user-draw being drawn. This value can be obtained by calling RwGetUserDrawData() with userdraw as an argument. data is passed directly to the call-back function for the convenience of the application developer.

Note that the call-back function is always called after all clumps in the scene have been rendered, i.e., when RwEndCameraUpdate() is called. Therefore user-draw rendering always appear in front of clump rendering. In the case of overlapping user-draws, the order of rendering is not defined.

See Also

RwCreateUserDraw()

RwGetCameraImage()

RwGetUserDrawCallback()

RwGetUserDrawData()


RwSetUserDrawData()

RwUserDraw *

RwSetUserDrawData(RwUserDraw *userdraw, void *data);

Description

Sets the user-draw's user data pointer.

Arguments

userdraw	Pointer to the user-draw.

data	User data pointer.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

Data is passed as the fourth parameter to the user-draw's call-back function when the user-draw is being rendered.

See Also

RwGetUserDrawData()

RwSetUserDrawCallback()


RwSetUserDrawOffset()

RwUserDraw *

RwSetUserDrawOffset(RwUserDraw *userdraw, int x, int y);

Description

Sets the X and Y offset in viewport space units relative to the alignment point of the user-draw.

Arguments

userdraw	Pointer to the user-draw.

x	X offset from the alignment point of the user-draw (in viewport space units).

y	Y offset from the alignment point of the user-draw (in viewport space units).

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

x and y may be negative.

See Also

RwCreateUserDraw()

RwGetUserDrawOffset()


RwSetUserDrawParentAlignment()

RwUserDraw *

RwSetUserDrawParentAlignment(RwUserDraw *userdraw, RwUserDrawAlignmentTypes alignment);

Description

Sets the alignment flags of the user-draw's parent. A user-draw's parent is either the bounding box of the clump that owns the user-draw or the current camera's viewport.

The alignment flags of the user-draw's parent determine which part of the user-draw's parent rectangle is aligned with the user-draw. The actual point of alignment between a user-draw and its parent is determined by the user-draw's alignment flags and the parent's alignment flags.

Arguments

userdraw	Pointer to the user-draw.

alignment	A bitfield representing an alignment flag (or bitwise or of flags).

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

If the user-draw's type is rwBBOXALIGN then the user-draw's parent is the bounding box of the clump to which the user-draw is attached. If the type is rwVPALIGN the user-draw's parent is the viewport of the current camera when the user-draw is rendered. If the user-draw's type is rwVERTEXALIGN or rwCLUMPALIGN then the user-draw has no parent and the parent alignment bitfield is ignored.

The alignment flags are:

•	0    Align with the center of the parent.

•	rwALIGNTOP    Align with the top edge of the parent.

•	rwALIGNBOTTOM    Align with the bottom edge of the parent.

•	rwALIGNLEFT    Align with the left edge of the parent.

•	rwALIGNRIGHT    Align with the right edge of the parent.

See Also

RwGetUserDrawParentAlignment()

RwSetUserDrawAlignment()

RwSetUserDrawType()


RwSetUserDrawSize()

RwUserDraw *

RwSetUserDrawSize(RwUserDraw *userdraw, int width, int height);

Description

Sets the width and height (in viewport space units) of the user-draw.

Arguments

userdraw	Pointer to the user-draw.

width	Width of the user-draw (in viewport space units).

height	Height of the user-draw (in viewport space units).

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

RenderWare does not clip the user-draw's rendering to the specified area. If rendering takes place outside of the designated area garbage may appear on the display.

See Also

RwCreateUserDraw()

RwGetUserDrawSize()


RwSetUserDrawType()

RwUserDraw *

RwSetUserDrawType(RwUserDraw *userdraw, RwUserDrawType type);

Description

Sets the user-draw's type.

Arguments

userdraw	Pointer to the user-draw.

type	Type of the user-draw.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

The user-draw types are:

•	rwCLUMPALIGN    Align with the origin of the owning clump.

•	rwVERTEXALIGN    Align with a vertex of the owning clump.

•	rwBBOXALIGN    Align with the viewport bounding box of the owning clump.

•	rwVPALIGN    Align with the viewing camera's viewport.

See Also

RwCreateUserDraw()

RwGetUserDrawType()


RwSetUserDrawVertexIndex()

RwUserDraw *

RwSetUserDrawVertexIndex(RwUserDraw *userdraw, int index);

Description

Sets the index of the clump vertex with which the user-draw is aligned.

Arguments

userdraw	Pointer to the user-draw.

index	The index of the vertex with which the user-draw is aligned.

Return Value

The argument userdraw if successful, and NULL otherwise.

Comments

The vertex index is only used if the user-draw's type is rwVERTEXALIGN, for all other user-draw types it is ignored.

index is an index into the vertex list of the clump to which the user-draw is attached.

See Also

RwCreateUserDraw()

RwGetUserDrawType()

RwGetUserDrawVertexIndex()


RwSetUserError()

void

RwSetUserError(void);

Description

Sets the error status to E_RW_USER.

Arguments

None.

Return Value

None.

Comments

RwSetUserError() is used when a call-back for RwForAll…() wishes to signal failure and terminate iteration.

See Also

RwForAllClumpsInHierarchy()

RwForAllClumpsInScene()

RwForAllLightsInScene()

RwForAllNamedTextures()

RwForAllPolygonsInClump()

RwForAllUserDrawsInClump()

RwGetError()


RwShowCameraImage()

RwCamera *

RwShowCameraImage(RwCamera *camera, void *param);

Description

Copies the damaged regions of the camera's image buffer to the portion of the display (screen or window) specified by the camera's viewport.

Arguments

camera	Pointer to the camera.

param	Device dependent parameter.

Return Value

The argument camera if successful, and NULL otherwise.

Comments

For a description of the device dependent parameter, param, see MS Windows 3.1 Specific Information.

This function often immediately follows an RwBeginCameraUpdate() … RwEndCameraUpdate() block in order to copy the rendering performed within the RwBeginCameraUpdate() … RwEndCameraUpdate() block to the display.

Note that the camera's image buffer is not automatically cleared after the call to RwShowCameraImage(). To clear the image buffer, call RwClearCameraViewport().

See Also

RwBeginCameraUpdate()

RwDamageCameraViewport()

RwEndCameraUpdate()

RwInvalidateCameraViewport()

RwRenderClump()

RwRenderScene()

RwUndamageCameraViewport()


RwSphere()

int

RwSphere(RPARAM radius, int density);

Description

Adds a sphere to the current clump under construction. The sphere is transformed by the CTM, and the current material is assigned to its polygons. The sphere is centered about the origin.

Arguments

radius	Radius of the sphere.

density	Density of facets in the sphere. A value of 0 results in a cube. Higher values increase the number of facets exponentially.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

If the sphere's radius is negative the polygons forming the sphere will face inward.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwBlock()

RwClumpBegin()

RwClumpEnd()

RwCone()

RwCylinder()

RwDisc()

RwHemisphere()

RwProtoBegin()

RwProtoEnd()


RwSphericalTexturizeClump()

RwClump *

RwSphericalTexturizeClump(RwClump *clump);

Description

Sets the texture coordinates for every polygon belonging to the clump using the spherical projection method.

A spherical mapping results in the construction of a nominal sphere onto which the texture is applied in a way similar to the projection of a two dimensional atlas map onto the surface of a globe. The resulting sphere is then mapped to the clump by "shrink wrapping" the clump with the sphere.

Arguments

clump	Pointer to the clump.

Return Value

The argument clump if successful, and NULL otherwise.

Comments

This function need only be called the first time a clump is texturized and not each time the clump is rendered.

Note that this function does not set the textures associated with the clump's polygons; this must be accomplished separately. The following code fragment illustrates this procedure:

RwForAllPolygonsInClumpPointer(clump,(RwPolygon3d*( *)())RwSetPolygonTexture, texture);

See Also

RwCubicTexturizeClump()

RwForAllPolygonsInClump()

RwGetClumpVertexUV()

RwGetPolygonUV()

RwSetClumpVertexUV()

RwSetPolygonTexture()

RwSetPolygonUV()


RwSplinePoint()

RwV3d *

RwSplinePoint(RwSpline *spline, RwSplinePath path, RPARAM where, RwV3d *point, RwV3d *vector);

Description

Calculates a point and vector for a position on the spline specified by parameter where.

Arguments

spline	Pointer to the spline.

path	Type of curve distribution.

where	Relative distance along the spline in the range CREAL(0.0) to CREAL(1.0).

point	Pointer to the point that will receive the spline location point.

vector	Pointer to the vector that will receive the spline tangent vector.

Return Value

The argument point if successful, and NULL otherwise.

Comments

Note that if a vector is not needed, NULL can be passed as the value of parameter vector.

See Also

RwCreateSpline()

RwSetSplinePoint()


RwSplineTransform()

RPARAM

RwSplineTransform(RwSpline *spline, RwSplinePath path, RPARAM where, RwV3d *up, RwMatrix4d *matrix);

Description

Calculates a Frenet transform matrix at a specified parameter position on a spline and a returns measure of the path's anti-clockwise curvature at this point. This matrix will transform a clump to the specified parameter position on the path with its "Look At" direction pointing tangent to the path, "Look Up" pointing 'up' and  "Look At" pointing toward or away from the centre of curvature.

Arguments

spline	The spline curve.

path	The type of spline path.

where	The parameter position.

up	An "up" vector. If up is NULL, RwSplineTransform() will produce a transform which aligns a clumps "Look Up" y vector with the local y vector of a Frenet frame. If up is non-NULL, RwSplineTransform() will produce a transform which aligns a clumps "Look Up" y vector so as never to roll upside down with respect to this up vector.

matrix	Pointer to the matrix the will receive the Frenet transform matrix.

Return Value

The curvature at the specified point if successful, and NULL otherwise.

Comments

If up is NULL, the returned matrix will always transform a clump's "Look Left" vector to point toward the centre of curvature - as though the clump were being swung on a rod extending this direction from this point. Since the clump's "Look At" vector always transforms to a forward tangent along the spline, when the centre of curvature lies to the right this can result in the clump's "Look Up" vector rolling upside down since handedness is conserved. This behaviour is not always desirable.

Such rolling can be suppressed by specifying an appropriate up vector. RwSplineTransform() will suppress any roll relative to a specified up vector. For example, when modelling the motion of a car over a hilly road circuit, an up vector of [CREAL(0.0), CREAL(1.0), CREAL(0.0)] would give a transform in which the car turns around corners and "tilts" over hills but does not roll - the wheels stay on the ground.

When specifying a non-NULL up vector, some restricted rolling or banking may be reintroduced by pre-concatenating a local z rotation whose angle is driven by the anti-clockwise curvature value returned by RwSplineTransform().

When large and positive, this indicates a sharp anti-clockwise turn in the plane normal to the up vector; when zero this indicates no turn in the plane; when large and negative this indicates a sharp clockwise turn in the plane. An appropriate bank angle may be found with a function such as atan(curvature).

See Also

RwCreateSpline()

RwDestroySpline()

RwDuplicateSpline()

RwSplinePoint()


RwSubtractVector()

RwV3d *

RwSubtractVector(RwV3d *a, RwV3d *b, RwV3d *c);

Description

Subtracts two vectors.

Arguments

a	Pointer to the first vector.

b	Pointer to the second vector.

c	Pointer to the vector that will receive the result.

Return Value

The argument c if successful, and NULL otherwise.

See Also

RwAddVector()

RwCrossProduct()

RwDotProduct()

RwNormalize()

RwScaleVector()

RwTransformVector()


RwTextureDictBegin()

int

RwTextureDictBegin(void);

Description

Creates a new, empty texture dictionary and pushes it on the texture dictionary stack. The newly created dictionary becomes the current texture dictionary.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

See Also

RwFindNamedTexture()

RwForAllNamedTextures()

RwGetNamedTexture()

RwGetTextureDictSearchMode()

RwSetTextureDictSearchMode()

RwReadNamedTexture()

RwTextureDictEnd()


RwTextureDictEnd()

int

RwTextureDictEnd(void);

Description

Destroys the current texture dictionary and all the textures that it contains. The texture dictionary stack is restored to its state at the time of the last RwTextureDictBegin().

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function must not be called if any of the textures in the current dictionary are still in use. Use RwSetMaterialTexture() or RwSetPolygonTexture() with a parameter of NULL to remove all textures in the dictionaries from their materials before calling RwTextureDictEnd().

See Also

RwDestroyTexture()

RwFindNamedTexture()

RwForAllNamedTextures()

RwGetNamedTexture()

RwGetTextureDictSearchMode()

RwReadNamedTexture()

RwSetMaterialTextureModes()

RwSetPolygonTexture()

RwSetTextureDictSearchMode()

RwTextureDictBegin()


RwTextureNextFrame()

RwTexture *

RwTextureNextFrame(RwTexture *texture);

Description

Increments or decrements the current frame index by the current frame step.

Arguments

texture	Pointer to the texture.

Return Value

The argument texture if successful, and NULL otherwise.

Comments

Note that the current frame index will not go outside the range 0 … n-1 (where n is the number of frames in the texture), instead the index will "wrap around" in either direction.

See Also

RwSetTextureFrame()

RwSetTextureFrameStep()

RwTextureNextFrame()


RwTiltCamera()

RwCamera *

RwTiltCamera(RwCamera *camera, RPARAM angle);

Description

Rotates the camera about its X axis.

Arguments

camera	Pointer to the camera.

angle	Angle of rotation (in degrees).

Return Value

The argument camera if successful, and NULL otherwise.

Comments

A positive angle of rotation results in a clockwise rotation about the camera's "Look Right" vector.

See Also

RwGetCameraLookAt()

RwGetCameraLookUp()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwTransformCameraOrientation()


RwTransformBegin()

int

RwTransformBegin(void);

Description

Pushes a copy of the CTM onto the transformation stack.

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwJointTransformBegin()

RwModelBegin()

RwModelEnd()

RwProtoBegin()

RwProtoEnd()

RwTransformEnd()


RwTransformCamera()

RwCamera *

RwTransformCamera(RwCamera *camera, RwMatrix4d *matrix);

Description

Applies a transformation matrix to the camera's current position and orientation.

Arguments

camera	Pointer to the camera.

matrix	Pointer to the transformation matrix.

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookRight()

RwGetCameraLookUp()

RwGetCameraPosition()

RwResetCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwSetCameraPosition()

RwTransformCameraOrientation()


RwTransformCameraOrientation()

RwCamera *

RwTransformCameraOrientation(RwCamera *camera, RwMatrix4d *matrix);

Description

Applies a transformation matrix to the camera's current orientation (which is determined by the "Look At" and "Look Up" vectors). This function does not affect the camera's position.

Arguments

camera	Pointer to the camera.

matrix	Pointer to the transformation matrix.

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraLookAt()

RwGetCameraLookRight()

RwGetCameraLookUp()

RwPanCamera()

RwPointCamera()

RwResetCamera()

RwRevolveCamera()

RwSetCameraLookAt()

RwSetCameraLookUp()

RwTransformCamera()


RwTransformClump()

RwClump *

RwTransformClump(RwClump *clump, RwMatrix4d *matrix, RwCombineOperation op);

Description

Applies a transformation matrix to the clump's modelling matrix.

Arguments

clump	Pointer to the clump.

matrix	Pointer to the transformation matrix.

op	Combination operator.

Return Value

The argument clump if successful, and NULL otherwise.

See Also

RwGetClumpLTM()

RwGetClumpMatrix()

RwTransformClumpJoint()


RwTransformClumpJoint()

RwClump *

RwTransformClumpJoint(RwClump *clump, RwMatrix4d *matrix, RwCombineOperation op);

Description

Applies a transformation matrix to the clump's joint (articulation) matrix.

Arguments

clump	Pointer to the clump.

matrix	Pointer to the transformation matrix.

op	Combination operator.

Return Value

The argument clump if successful, and NULL otherwise.

See Also

RwGetClumpJointMatrix()

RwGetClumpLTM()

RwTransformClump()


RwTransformCTM()

int

RwTransformCTM(RwMatrix4d *matrix);

Description

Replaces the CTM with the specified matrix.

Arguments

matrix	Pointer to a transformation matrix.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityCTM()

RwModelBegin()

RwModelEnd()

RwRotateCTM()

RwScaleCTM()

RwTransformJointTM()

RwTranslateCTM()


RwTransformEnd()

int

RwTransformEnd(void);

Description

Restores the previous value of the CTM. Also has the effect of restoring the transformation stack to its state at the time of the last RwTransformBegin().

Arguments

None.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwClumpBegin()

RwClumpEnd()

RwJointTransformEnd()

RwModelBegin()

RwModelEnd()

RwPopScratchMatrix()

RwProtoBegin()

RwProtoEnd()

RwTransformBegin()


RwTransformJointTM()

int

RwTransformJointTM(RwMatrix4d *matrix);

Description

Replaces the current joint transformation matrix with the specified matrix.

Arguments

matrix	Pointer to a transformation matrix.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityJointTM()

RwModelBegin()

RwModelEnd()

RwRotateJointTM()

RwTransformCTM()


RwTransformLight()

RwLight *

RwTransformLight(RwLight *light, RwMatrix4d *matrix);

Description

Applies a transformation matrix to the light's current position and direction vector (if applicable).

Arguments

light	Pointer to the light.

matrix	Pointer to the transformation matrix.

Return Value

The argument light if successful, and NULL otherwise.

See Also

RwCreateLight()

RwGetLightPosition()

RwGetLightVector()

RwSetLightPosition()

RwSetLightVector()


RwTransformMatrix()

RwMatrix4d *

RwTransformMatrix(RwMatrix4d *dest, RwMatrix4d *source, RwCombineOperation op);

Description

Applies the transformation matrix source to matrix dest.

Arguments

dest	Pointer to the matrix to be transformed.

source	Pointer to the transformation matrix.

op	Combination operator.

Return Value

The argument dest if successful, and NULL otherwise.

Comments

If op is rwREPLACE, RwTransformMatrix() is equivalent to RwCopyMatrix() (although note that the order of the source and destination matrices is reversed). Otherwise, it is equivalent to RwMultiplyMatrix(), but does not require an intermediate matrix to hold the result.

See Also

RwCopyMatrix()

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTranslateMatrix()


RwTransformPoint()

RwV3d *

RwTransformPoint(RwV3d *point, RwMatrix4d *matrix);

Description

Applies a transformation matrix to a point.

Arguments

point	Pointer to the point.

matrix	Pointer to the transformation matrix.

Return Value

The argument point if successful, and NULL otherwise.

See Also

RwTransformVector()


RwTransformVector()

RwV3d *

RwTransformVector(RwV3d *vector, RwMatrix4d *matrix);

Description

Applies a transformation matrix to a vector. However, since a vector does not have a position in space, the translation component of the matrix is ignored.

Arguments

vector	Pointer to the vector.

matrix	Pointer to the transformation matrix.

Return Value

The argument vector if successful, and NULL otherwise.

See Also

RwAddVector()

RwCrossProduct()

RwDotProduct()

RwNormalize()

RwScaleVector()

RwSubtractVector()

RwTransformPoint()


RwTranslateCTM()

int

RwTranslateCTM(RPARAM tx, RPARAM ty, RPARAM tz);

Description

Pre-concatenates a translation matrix onto the CTM.

Arguments

tx	Translation parallel to the X axis.

ty	Translation parallel to the Y axis.

tz	Translation parallel to the Z axis.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function can only be called within the context of an RwModelBegin() … RwModelEnd() block.

See Also

RwIdentityCTM()

RwModelBegin()

RwModelEnd()

RwRotateCTM()

RwScaleCTM()

RwTransformCTM()


RwTranslateMatrix()

RwMatrix4d *

RwTranslateMatrix(RwMatrix4d *matrix, RPARAM tx, RPARAM ty, RPARAM tz, RwCombineOperation op);

Description

Builds a translation matrix and applies it to matrix. The operation may be a pre-concatenation, post-concatenation, or replacement.

Arguments

matrix	Pointer to the matrix.

tx	Translation parallel to the X axis.

ty	Translation parallel to the Y axis.

tz	Translation parallel to the Z axis.

op	Combination operator.

Return Value

The argument matrix if successful, and NULL otherwise.

See Also

RwIdentityMatrix()

RwInvertMatrix()

RwMultiplyMatrix()

RwOrthoNormalizeMatrix()

RwRotateMatrix()

RwRotateMatrixCos()

RwScaleMatrix()

RwTransformMatrix()

RwTranslateCTM()


RwTriangle()

int

RwTriangle(int v1, int v2, int v3);

Description

Adds a triangle to the current clump under construction. The current material is assigned to the triangle.

Arguments

v1	First vertex of the triangle.

v2	Second vertex of the triangle.

v3	Third vertex of the triangle.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function is exactly equivalent to calling RwPolygon() with an array of three vertex indices.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwClumpBegin()

RwClumpEnd()

RwPolygon()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwVertex()

RwVertexExt()


RwTriangleExt()

int

RwTriangleExt(int v1, int v2, int v3, short int tag);

Description

Adds a triangle with the specified integer tag to the clump under construction. The current material is assigned to the triangle.

Arguments

v1	First vertex of the triangle.

v2	Second vertex of the triangle.

v3	Third vertex of the triangle.

tag	Integer tag to set.

Return Value

TRUE if successful, and FALSE otherwise.

Comments

This function is exactly equivalent to calling RwPolygonExt() with an array of three vertex indices.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddPolygonToClump()

RwClumpBegin()

RwClumpEnd()

RwFindTaggedPolygon()

RwGetPolygonTag()

RwPolygon()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwSetPolygonTag()

RwSetTag()

RwTriangle()

RwVertex()

RwVertexExt()


RwUndamageCameraViewport()

RwCamera *

RwUndamageCameraViewport(RwCamera *camera, int x, int y, int width, int height);

Description

Marks a rectangular area of the viewport as "undamaged" (not in need of updating).

Arguments

camera	Pointer to the camera.

x	X coordinate of the rectangle's top left corner (in viewport space coordinates).

y	Ycoordinate of the rectangle's top left corner (in viewport space coordinates).

width	Width of the rectangle (in viewport space units).

height	Height of the rectangle (in viewport space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwClearCameraViewport()

RwDamageCameraViewport()

RwGetClumpViewportRect()

RwInvalidateCameraViewport()

RwShowCameraImage()


RwVCMoveCamera()

RwCamera *

RwVCMoveCamera(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Moves the camera position by the given delta (x,y,z) values (in camera space units) with respect to the camera's orientation. For instance, a positive z value moves the camera forward.

Arguments

camera	Pointer to the camera.

x	Amount to move the camera along its X axis (in camera space units).

y	Amount to move the camera along its Y axis (in camera space units).

z	Amount to move the camera along its Z axis (in camera space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraPosition()

RwResetCamera()

RwSetCameraPosition()

RwTransformCamera()

RwWCMoveCamera()


RwVertex()

int

RwVertex(RPARAM x, RPARAM y, RPARAM z);

Description

Adds a vertex, transformed by the CTM, to the current clump under construction.

Arguments

x	X coordinate of the vertex.

y	Y coordinate of the vertex.

z	Z coordinate of the vertex.

Return Value

The index of the new vertex if successful, and 0 otherwise.

Comments

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddVertexToClump()

RwClumpBegin()

RwClumpEnd()

RwPolygon()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwTriangle()

RwTriangleExt()

RwVertexExt()


RwVertexExt()

int

RwVertexExt(RPARAM x, RPARAM y, RPARAM z, RwUV *uv, RwV3d *normal);

Description

Adds a vertex, transformed by the CTM, to the clump under construction and specifies the vertex's texture coordinates and normal vector.

Arguments

x	X coordinate of the vertex.

y	Y coordinate of the vertex.

z	Z coordinate of the vertex.

uv	Pointer to the RwUV structure holding the vertex's texture coordinates.

normal	Pointer to the RwV3d structure holding the X, Y, and Z components of the normal vector.

Return Value

The index of the new vertex if successful, and 0 otherwise.

Comments

NULL may be passed as the value of uv or normal if the application programmer does not wish to set the value of either or both of these parameters.

This function can only be called within the context of an RwClumpBegin() … RwClumpEnd() or RwProtoBegin() … RwProtoEnd() block.

See Also

RwAddVertexToClump()

RwClumpBegin()

RwClumpEnd()

RwGetClumpVertexUV()

RwGetClumpVertexNormal()

RwPolygon()

RwPolygonExt()

RwProtoBegin()

RwProtoEnd()

RwQuad()

RwQuadExt()

RwSetClumpVertexUV()

RwTriangle()

RwTriangleExt()

RwVertex()


RwWCMoveCamera()

RwCamera *

RwWCMoveCamera(RwCamera *camera, RPARAM x, RPARAM y, RPARAM z);

Description

Moves the camera position by the given delta (x,y,z) values, with respect to the world space coordinate system.

Arguments

camera	Pointer to the camera.

x	Amount to move the camera parallel to the world X axis (in world space units).

y	Amount to move the camera parallel to the world Y axis (in world space units).

z	Amount to move the camera parallel to the world Z axis (in world space units).

Return Value

The argument camera if successful, and NULL otherwise.

See Also

RwGetCameraPosition()

RwResetCamera()

RwSetCameraPosition()

RwTransformCamera()

RwVCMoveCamera()


RwWriteShape()

int

RwWriteShape(char *path, RwClump *clump);

Description

Writes the clump as a script (.rwx) file with the given name.

Arguments

path	Pointer to the filename.

clump	Pointer to the clump.

Return Value

TRUE if successful, and FALSE otherwise.

Comment

When a clump read from a script file is written out, certain aspects of the structure of the original input script file are not preserved. However, this does not affect the appearance or the behaviour of the clump.

It is recommended that the extension.rwx be used for script files. However, this is not enforced by the library.

See Also

RwClumpBegin()

RwClumpEnd()

RwCreateClump()

RwCreateDecal()

RwCreateSprite()

RwReadShape()