This category consists of:
Numeric Types
RwReal
RenderWare provides both fixed-point and floating-point libraries. A single data type, RwReal 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 - throughout the code.
There are three possible scenarios in which an application program may exploit the RenderWare library.
· The RenderWare arithmetic macros, e.g., RMul and RAdd, must be used instead of C’s corresponding arithmetic operators.
· C’s built-in types - int, long, float and double - should be converted to RenderWare’s RwReal with the conversion macros, e.g., CREAL and INT2REAL. Prototypes for RenderWare API functions use RwReal * rather than float *.
· RwReal is a 32-bit fixed point number, 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.
· RwReal is interpreted by the library as float.
· 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.
To facilitate the use of the RwReal type, several conversion macros are provided:
In addition, there are several arithmetic macros that take RwReal arguments and return an RwReal result:
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.
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
RwReal
sinangle(RwReal 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.
Integer Types
RenderWare supports a number of integer types to aid in portability across platforms. These types are defined as follows:
typedef
short RwInt16; /* 16 bit signed integer */
typedef
unsigned short RwUInt16; /* 16 bit unsigned integer */
typedef long
RwInt32; /* 32 bit signed integer */
typedef
unsigned long RwUInt32; /* 32 bit unsigned integer */
typedef
RwInt32 RwBool; /* Boolean type */
These types should be used throughout a RenderWare application in preference to their underlying native type. This is particularly important when building 16-bit RenderWare applications using either Visual C++ or Borland C++. Certain RenderWare functions, such as RwGetCameraViewport(), require pointers to RwInt32s or pointers to arrays of RwInt32s. It is essential in 16-bit environments that the objects passed to these functions are declared RwInt32 and not int.
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.
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(32.0)
} RwUV;
RwRect
The type RwRect represents a rectangular region. It is defined as follows:
typedef
struct
{
RwInt32 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;
RwPaletteEntry
The type RwPaletteEntry represents a palette entry. It is defined as follows:
typedef
struct
{
unsigned char r, g, b; Intensities in the range 0 - 255
unsigned char flags; Reserved
}
RwPalette
The type RwPalette represents an entire palette. It is defined as follows:
#define
rwPALETTELENGTH 256
typedef
RwPaletteEntry RwPalette[rwPALETTELENGTH];
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
{
RwInt32 vindex; Index of vertex closest to the pick
position
RwInt32 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 viewport 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 the clump picked
RwPolygon3d *polygon; Pointer to the 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 Appendix B.
RwMemory
The type RwMemory defines an area of memory that can be used as the source for an RwStream. It is defined as follows:
typedef
struct
{
char *start; Start of memory block
RwUInt32 length; Size of memory block
} RwMemory;
The field option identifies the open option and value is a device specific parameter associated with that option. The available options are described in Appendix B.
Device Capabilities Structure
The RenderWare API function RwFindDisplayDevice() finds a display device with a required set of capabilities. The capabilities required can be specified via this data structure which is defined as follows:
typedef
struct
{
char device_name[80];
RwUInt32 num_names;
RwUInt32 version_major;
RwUInt32 version_minor;
RwUInt32 version_release;
RwUInt32 display_depth;
RwUInt32 zbuffer_depth;
RwUInt32 default_map_size;
RwUInt32 max_map_tiling;
RwUInt32 small_map_size
RwUInt32 max_small_map_tiling;
RwUInt32 features;
RwUInt32 capabilities[6];
RwUInt32 hardware_capabilities[6];
} RwDeviceCapabilities;
The members of this structure are as follows:
• device_name The device name (usually has one name). If more than one name is specified, they are separated by semicolons.
• num_names The number of names in the device_name string. (Usually 1).
• version_major, version_minor, version_release
The version number of this device. Note that in future versions it may be the case that a later version of the library will not be able to use a previous device driver.
• display_depth The rendering display depth. Currently the display_depths supported are 8 and 16 bit.
• zbuffer_depth The z buffer depth used with this device (if it has a z buffering capability).
• default_map_size The default texture map size. This is the size of texture maps the device can handle, unless it is a device which can handle multiple texture map sizes. In this case it is the texture map size used by default by the device.
• max_map_tiling The number of repetition of a texture that is possible over a single polygon.
• small_map_size The small texture map size. For devices which support 2 texture sizes this field defines the small size.
• max_small_map_tiling The number of repetition of a texture that is possible over a single polygon. This feature is only available on devices that support 2 texture sizes.
• features Bit field made up from the following 'features' or-ed together.
rwFEATUREHWDOUBLEBUFFER The card can hardware double buffer.
rwFEATUREPALETTEBASED The device is a palette based (usually 8 bit)
rwFEATUREHARDWARESUPPORT The device has some hardware support
rwFEATUREVARIABLEMAPSIZE The device supports texture maps of sizes different from the default texture map size.
rwFEATUREMOUSESUPPORT The device contains mouse support capabilities
rwFEATUREZBUFFER The device supports Z buffering
rwFEATURERESOLUTIONSWITCH The device can be resolution set
rwFEATUREDEPTHSWITCH The device can be depth switched
rwFEATUREPASSTHROUGHDEVICE The device uses a secondary frame buffer. Some application programming is required to switch between this device and another application.
rwFEATUREMIPMAPS The device supports the use of mipmaps.
rwFEATURETRUEOPACITY The device has true opacity as opposed to the screen door method used for the standard software renderers. This functionality is available with the MMX optimised renderer set.
rwFEATURECOLORFOG The device supports the use of colored fog.
rwFEATUREGENERICHARDWARE The device is a generic driver that drives multiple hardware devices. The application may wish to select a native driver if one is available in preference to a driver with this feature.
• capabilities The index into the capabilities array is via the following definitions
rwCAPABILITYFLAT
rwCAPABILITYTEXTURED
rwCAPABILITYPCTEXTURED
For finding out the if the capability is present with Z buffering, 'or' in the following define
rwCAPABILITYZBUFFERED
For example finding the if the device was capable of textured Z buffering
capabilities[rwCAPABILITYTEXTURED|
rwCAPABILITYZBUFFERED]
The entry held at this address is a bit field made from the following entries. If the bit is set then the device is capable of this type of rendering.
rwCAPABILITYMODEOPACITY Rendering with opacity
rwCAPABILITYMODEGOURAUD Gouraud shading is possible
rwCAPABILITYMODEFULLGOURAUD Gouraud shading with interpolation over red, green and blue seperately.
rwCAPABILITYMODETRANSPARENT Only applicable with texturing. Indicates that it is possible to use masked rasters. That is pixels within the texture map can be marked as transparent.
rwCAPABILITYMODEFILTERED The device is capable of rendering with filtering.
rwCAPABILITYMODELITTEXTURE The device is capable of flat (facet light sampling) lighting a texture.
rwCAPABILITYMODEGOURAUDTEXTURE
The device is capable of smooth shading over a texture (vertex light sampling). If the rwCAPABILITYMODEFULLGOURAUD flag is set then red, green and blue components will be seperately interpolated over the surface.
• hardware_capabilities
The hardware_capabilities entry is indexed in exactly the same manner as capabilities. Bits are set in this structure if the device is capable of implementing the type of rendering in hardware. Thus every bit set in hardware_capabilities must be set in capabilities, but only a sub set of capabilities will be set in hardware_capabilities.
A bit will only be set in hardware_capabilities if the rendering mode is implemented in hardware and using that hardware is significantly faster than the software implementation.
Raster Information
The type RwRasterInfo represents detailed information about an RwRaster object. It is defined as follows:
typedef
struct
{
RwRasterType type; /* type of RwRaster */
RwInt32 size; /* size in bits of a pixel */
RwInt32 redmask; /* position of red bits */
RwInt32 greenmask; /* position of green bits */
RwInt32 bluemask; /* position of blue bits */
RwInt32 alphamask; /* position of alpha bits */
}
RwRasterInfo;
Standard Library Functions Structure
The type RwStdlib represents the structure that can be passed into RwInitialize() to overload the standard memory allocation functions that are used by RenderWare.
typedef
struct
{
RwStdlibFuncMalloc rwmalloc;
RwStdlibFuncCalloc rwcalloc;
RwStdlibFuncRealloc rwrealloc;
RwStdlibFuncFree rwfree;
}
RwStdlib;
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.
Axis Alignment Type
Clumps may have their axes aligned with the "Look At", "Look Right" and "Look Up" vectors of the camera used to render that clump. This is mainly useful for creating sprites or decals (2D bitmaps aligned with the viewplane of the viewing camera). However, a clump’s axis alignment type may be used to constrain the motion of any clump. The axis alignment type is defined as follows:
RwAxisAlignment
• rwNAAXISALIGNMENT Error code
• rwNOAXISALIGNMENT Do not align the clump with the viewing camera.
• rwALIGNAXISZORIENTX
Preserve the horizontal orientation of the clump when aligning with the viewing camera.
• rwALIGNAXISZORIENTY
Preserve the vertical orientation of the clump when aligning with the viewing camera.
• rwALIGNAXISXYZ Align the X, Y and Z axes of the clump with the "Look Right", "Look Up" and "Look At" vectors of the viewing camera.
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
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
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
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
Specific device drivers may define additional device actions. Appendix B documents any additional (platform specific) actions.
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
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 palette based devices.
• rwPALETTE Fetch the RenderWare palette
• rwPALETTESIZE The number of entries in the entire palette
• rwFIRSTPALETTEENTRY
Index of the first palette entry available for use by an application
• rwLASTPALETTEENTRY Index of the last palette entry available for use by an application
Specific device drivers may define additional information types. Appendix B documents any additional (platform specific) options.
Error Code Type
For a full description of the error code type, RwErrorCode, see Appendix C: Error Codes
Geometry Sampling Type
Geometry may be visualized 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
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 Sampling Type
The lighting of a polygon in a clump can be calculated in either of two ways: a single lighting sample per polygon at the polygon’s center, 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
Open Option Type
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
Specific device drivers may define additional open options. Appendix B documents any additional (platform specific) options.
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 a clump pick data record, and is as follows:
RwPickObject
• rwNAPICKOBJECT No Clump picked
• rwPICKCLUMP Clump picked
Search Mode Type
Several API functions operate on the texture dictionary stack. The behavior 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)
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 is interpolated uniformly across the range, whilst a rwNICEENDS path will have zero differential at its ends. The spline path type is as follows:
RwSplinePath
• rwNASPLINEPATHTYPE Error code
• rwSMOOTH Uniform interpolation across the range.
• rwNICEENDS Zero differential at ends.
State Type
This is a generic state type. It is used whenever an attribute can be switched on or off. The state type is as follows:
RwState
• rwNASTATE Error code
• rwOFF Object is turned off
• rwON Object is turned on
Stream Type
This defines the type of stream to be used. The stream type is as follows:
RwStreamType
• rwSTREAMFILE A stream file is a standard file stream which has been opened by the user.
• rwSTREAMFILENAME Opens a file using the given filename.
• rwSTREAMMEMORY Performs operations to/from a chunk of memory.
Stream Access Type
When opening a stream the type of access is also specified this is defined as follows:
RwStreamAccessType
• rwSTREAMREAD The stream can only be read from.
• rwSTREAMWRITE The stream can only be written to.
• rwSTREAMAPPEND The stream can only be appended to.
System Information Type
The API function RwGetSystemInfo() returns information about the current RenderWare library. Values of the type RwSystemInfo identify the information returned by RwGetSystemInfo().
The system information type is as follows:
RwSystemInfo
• rwNASYSTEMINFO Error code
• rwVERSIONSTRING A string including major and minor version numbers and the release string
• rwVERSIONMAJOR The major version number of the library
• rwVERSIONMINOR The minor version number of the library
• rwVERSIONRELEASE A string identifying a particular release of RenderWare
• rwFIXEDPOINTLIB Does the current library using fixed-point numerics
• rwDEBUGGINGLIB Does the current library use the RenderWare debugging kernel
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.
Current versions of RenderWare provide 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"
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
Raster Type
RenderWare V2.1 supports rasters which can have arbitrary formats. The application can manipulate the pixels of the raster with reference to the RwRasterInfo block. The type of RwRasters that are supported are defined as follows:
RwRasterType
• rwNARASTER Error code
• rwRASTERINDEXED Raster contains indices into a system palette
• rwRASTERRGBA Raster contains RGB and Alpha components. The mask fields in the RwRasterInfo structure indicate the placement of these components in the pixel.
· rwRASTERZLESS Raster contains Z buffer values - nearer Z values are less than further.
· rwRASTERZGREATER Raster contains Z buffer values - nearer Z values are greater than further.
Depth Cue Type
RenderWare allows the application to specify a number of different depth cue types. The implementation of these modes and the availability is a device dependant feature. All depth cueing varies from none at the Depth Cue distance to maximum at the far clipping plane. The rate at which the depth cueing increases between these values is defined by this type as follows.
RwDepthCueType
• rwNADEPTHCUETYPE Error code
• rwLINEAR Depth cueing increases linearly from near to far.
• rwEXPONENTIAL Depth cueing increases exponentially from near to far. Assuming that max fog is represented by F then the depthcued value f=F-F/Fs where s is the normalized distance between the near and far distances.
• rwEXPONENTIALSQUARED Depth cueing increases exponentially from near to far using the distance squared. Assuming that max fog is represented by F then the depthcued value f=F-F/F2s where s is the normalized distance between the near and far distances.
Stereo Mode Type
RenderWare V2.1 has support for a number of different Stereo Modes. The availability of these modes is a device dependant feature. The following modes are available:
RwStereoMode
• rwNASTEREOMODE Error code.
• rwSTEREONONE No Stereo - use mono rendering.
• rwSTEREOINTERLACEDRL Interlaced scanline stereo. The right eye image is rendered on the first scanline of the display.
• rwSTEREOINTERLACEDLR Interlaced scanline stereo. The left eye image is rendered on the first scanline of the display.
• rwSTEREOADJACENTRL The Stereo images are rendered side by side. The image on the left of the display represents the right eye.
• rwSTEREOADJACENTLR The Stereo images are rendered side by side. The image on the left of the display represents the left eye.
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.
Raster Options
The bitfield type RwRasterOptions controls several aspects of raster loading, these options being resizing, 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 bit in version 2.1). If the source of a raster (either a bitmap file or a platform specific bitmap object) is of a different 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.
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
• rwMIPMAPTEXTURE If the Raster is to be used as a texture, it is possible to specify the creation of a set of mipmaps from the initial level 0 texture. Note, support for mipmapped textures is a device specific feature. The standard software renderers do not support mipmaps.
Palette Options
The bitfield type RwPaletteOptions specifies the options that can be performed when setting the palette entries.
The palette options are as follows:
rwGAMMAPALETTE will gamma correct the palette. Do not specify this option if the source of the palette has already been gamma corrected. This option will normally be used when reading the palette from a bitmap which will be loaded via RwReadRaster() with the corresponding rwGAMMARASTER option set.
RwPaletteOptions
• rwGAMMAPALETTE Gamma correct the palette.
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
Material Modes
The bitfield type RwMaterialModes provides fine grain control over the rendering of materials.
• rwDECAL If this mode is specified, any polygons using this material will be rendered on top of any co-planar polygons that do not specify this flag.
• rwDOUBLE If this mode is specified any polygons using this material will be rendered double sided.
Texture Modes
The bitfield type RwTextureModes provides fine grain control over the rendering of textures.
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 color 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.0 - 32.0] and measure how far to the right and below the upper left corner of the image (respectively) to take the texel color. 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.
The rwFILTER texture mode reduces texture aliasing artifacts arising from extreme texellation to make the texture map appear more continuous. By default, when "zooming in" to a textured polygon, the square texel boundaries become clearly visible, emphasizing discrete texel steps in the texture map. The texture map may be made to appear more continuous and hence realistic, since such sharp transitions tend not to occur in real world texture detail, by applying the rwFILTER texture mode. This mode smoothes the transition between adjacent texels to reduce the sharp edges which would otherwise appear.
RwTextureModes
• rwLIT Texture is illuminated by light sources.
• rwFORESHORTEN Texture is foreshortened in a perspectively correct manner.
• rwFILTER A filter will be applied to the texture to reduce the effect of pixelation due to aliasing.
• rwTRILINEAR When used in combination with hardware that support mipmaps, this enables the use of trilinear mipmapping with textures that have this mode set.
• rwSMALLTEXTURE This is a read only mode. This texture mode will be set on materials that are using small textures on devices that offer this functionality.
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