RwRenderState
[Render States]

Modules

Enumerations

Functions

RwBlendFunction represents the options available when changing the RwRenderState setting for rwRENDERSTATESRCBLEND and rwRENDERSTATEDESTBLEND. The values are factors used to modulate either the source or destination pixel color when blending to the frame buffer. Note the some combinations are not allowed on certain platforms (see platform specific restrictions).

In the following list, the factors applied to each color component are listed explicitly. A subscript s refers to a source value while a subscript d refers to a destination value. Note that blending in the alpha channel is only applicable when the frame buffer actually contains alpha, and that the precise operation is platform specific. For instance, the source alpha value might simply be written to the alpha channel with no blending.

Enumeration values:

rwBLENDZERO	(0, 0, 0, 0 )
rwBLENDONE	(1, 1, 1, 1 )
rwBLENDSRCCOLOR	(Rs, Gs, Bs, As )
rwBLENDINVSRCCOLOR	(1-Rs, 1-Gs, 1-Bs, 1-As)
rwBLENDSRCALPHA	(As, As, As, As )
rwBLENDINVSRCALPHA	(1-As, 1-As, 1-As, 1-As)
rwBLENDDESTALPHA	(Ad, Ad, Ad, Ad )
rwBLENDINVDESTALPHA	(1-Ad, 1-Ad, 1-Ad, 1-Ad)
rwBLENDDESTCOLOR	(Rd, Gd, Bd, Ad )
rwBLENDINVDESTCOLOR	(1-Rd, 1-Gd, 1-Bd, 1-Ad)
rwBLENDSRCALPHASAT	(f, f, f, 1 ) f = min (As, 1-Ad)

RwCullMode represents the options available for culling polygons during rendering. The cull mode may be set via the RwRenderState setting rwRENDERSTATECULLMODE.

Enumeration values:

rwCULLMODECULLNONE	Both front and back-facing triangles are drawn.
rwCULLMODECULLBACK	Only front-facing triangles are drawn
rwCULLMODECULLFRONT	Only back-facing triangles are drawn

RwFogType represents the fog modes available when setting the RwRenderState rwRENDERSTATEFOGTYPE. Note that a particular platform may not support all of these modes (see platform specific restrictions).

Enumeration values:

rwFOGTYPELINEAR	Linear fog
rwFOGTYPEEXPONENTIAL	Exponential fog
rwFOGTYPEEXPONENTIAL2	Exponential^2 fog

RwRenderState represents the global state variables that control rendering. These may be set and queried using the RwRenderStateSet and RwRenderStateGet functions respectively.

Refer to the RwRenderState Overview for an overview of this system.

Note:

The texture render states (raster, address & filter modes) would normally just be used when rendering in immediate mode and should be specificied completely every time a texture is used. Retained mode pipelines will frequently set theses states internally, usually based on RwTexture objects.

Enumeration values:

rwRENDERSTATETEXTURERASTER	Raster used for texturing (normally used in immediate mode). The value is a pointer to an RwRaster.
rwRENDERSTATETEXTUREADDRESS	RwTextureAddressMode: wrap, clamp, mirror or border.
rwRENDERSTATETEXTUREADDRESSU	RwTextureAddressMode in u only.
rwRENDERSTATETEXTUREADDRESSV	RwTextureAddressMode in v only.
rwRENDERSTATETEXTUREPERSPECTIVE	Perspective correction on/off (always enabled on many platforms).
rwRENDERSTATEZTESTENABLE	Z-buffer test on/off.
rwRENDERSTATESHADEMODE	RwShadeMode: flat or gouraud shading.
rwRENDERSTATEZWRITEENABLE	Z-buffer write on/off.
rwRENDERSTATETEXTUREFILTER	RwTextureFilterMode: point sample, bilinear, trilinear, etc.
rwRENDERSTATESRCBLEND	RwBlendFunction used to modulate the source pixel color when blending to the frame buffer.
rwRENDERSTATEDESTBLEND	RwBlendFunction used to modulate the destination pixel color in the frame buffer when blending. The resulting pixel color is given by the formula (SRCBLEND * srcColor + DESTBLEND * destColor) for each RGB component. For a particular platform, not all combinations of blend function are allowed (see platform specific restrictions).
rwRENDERSTATEVERTEXALPHAENABLE	Alpha blending on/off (always enabled on some platforms). This is normally used in immediate mode to enable alpha blending when vertex colors or texture rasters have transparency. Retained mode pipelines will usually set this state based on material colors and textures.
rwRENDERSTATEBORDERCOLOR	Border color for RwTextureAddressMode rwTEXTUREADDRESSBORDER. The value should be a packed RwUInt32 in a platform specific format. The macro RWRGBALONG(r, g, b, a) may be used to construct this using 8-bit color components.
rwRENDERSTATEFOGENABLE	Fogging on/off (all polygons will be fogged).
rwRENDERSTATEFOGCOLOR	Color used for fogging. The value should be a packed RwUInt32 in a platform specific format. The macro RWRGBALONG(r, g, b, a) may be used to construct this using 8-bit color components.
rwRENDERSTATEFOGTYPE	RwFogType, the type of fogging to use.
rwRENDERSTATEFOGDENSITY	Fog density for RwFogType of rwFOGTYPEEXPONENTIAL or rwFOGTYPEEXPONENTIAL2. The value should be a pointer to an RwReal in the range 0 to 1.
rwRENDERSTATECULLMODE	RwCullMode, for selecting front/back face culling, or no culling.
rwRENDERSTATESTENCILENABLE	Stenciling on/off. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILFAIL	RwStencilOperation used when the stencil test passes. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILZFAIL	RwStencilOperation used when the stencil test passes and the depth test (z-test) fails. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILPASS	Stencil operation used when both the stencil and the depth (z) tests pass. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILFUNCTION	RwStencilFunction for the stencil test. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILFUNCTIONREF	Integer reference value for the stencil test. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILFUNCTIONMASK	Mask applied to the reference value and each stencil buffer entry to determine the significant bits for the stencil test. Supported on Xbox, D3D8, and OpenGL only.
rwRENDERSTATESTENCILFUNCTIONWRITEMASK	Write mask applied to values written into the stencil buffer. Supported on Xbox, D3D8, and OpenGL only.

RwShadeMode represents the available shading modes that may be set using the RwRenderState rwRENDERSTATESHADEMODE.

Enumeration values:

rwSHADEMODEFLAT	Flat shading
rwSHADEMODEGOURAUD	Gouraud shading

RwStencilFunction represents the comparison functions available for a stencil test. The function may be selected via the RwRenderState setting rwRENDERSTATESTENCILFUNCTION.

Enumeration values:

rwSTENCILFUNCTIONNEVER	Always fail the test
rwSTENCILFUNCTIONLESS	Accept the new pixel if its value is less than the value of the current pixel
rwSTENCILFUNCTIONEQUAL	Accept the new pixel if its value equals the value of the current pixel
rwSTENCILFUNCTIONLESSEQUAL	Accept the new pixel if its value is less than or equal to the value of the current pixel
rwSTENCILFUNCTIONGREATER	Accept the new pixel if its value is greater than the value of the current pixel
rwSTENCILFUNCTIONNOTEQUAL	Accept the new pixel if its value does not equal the value of the current pixel
rwSTENCILFUNCTIONGREATEREQUAL	Accept the new pixel if its value is greater than or equal to the value of the current pixel
rwSTENCILFUNCTIONALWAYS	Always pass the test

RwStencilOperation represents the stencil operations that may be performed depending on the results of stencil/z-buffer tests. The operation may be set for the various tests via the RwRenderState settings rwRENDERSTATESTENCILFAIL, rwRENDERSTATESTENCILZFAIL and rwRENDERSTATESTENCILPASS.

Enumeration values:

rwSTENCILOPERATIONKEEP	Do not update the entry in the stencil buffer
rwSTENCILOPERATIONZERO	Set the stencil-buffer entry to 0
rwSTENCILOPERATIONREPLACE	Replace the stencil-buffer entry with reference value
rwSTENCILOPERATIONINCRSAT	Increment the stencil-buffer entry, clamping to the maximum value
rwSTENCILOPERATIONDECRSAT	Decrement the stencil-buffer entry, clamping to zero
rwSTENCILOPERATIONINVERT	Invert the bits in the stencil-buffer entry
rwSTENCILOPERATIONINCR	Increment the stencil-buffer entry, wrapping to zero if the new value exceeds the maximum value
rwSTENCILOPERATIONDECR	Decrement the stencil-buffer entry, wrapping to the maximum value if the new value is less than zero

RwTextureAddressMode represents the addressing modes available when mapping textures to polygons using UV texture coordinates. This may be set in immediate mode via the RwRenderState rwRENDERSTATETEXTUREADDRESS, or via RwTextureSetAddressing for an RwTexture object.

Enumeration values:

rwTEXTUREADDRESSWRAP	UV wraps (tiles)
rwTEXTUREADDRESSMIRROR	Alternate UV is flipped
rwTEXTUREADDRESSCLAMP	UV is clamped to 0-1
rwTEXTUREADDRESSBORDER	Border color takes effect outside of 0-1

RwTextureFilterMode represents the texture filtering modes that may be set using the RwRenderState rwRENDERSTATETEXTUREFILTER in immediate mode, or RwTextureSetFilterMode in retained mode.

Enumeration values:

rwFILTERNEAREST	Point sampled
rwFILTERLINEAR	Bilinear
rwFILTERMIPNEAREST	Point sampled per pixel mip map
rwFILTERMIPLINEAR	Bilinear per pixel mipmap
rwFILTERLINEARMIPNEAREST	MipMap interp point sampled
rwFILTERLINEARMIPLINEAR	Trilinear

RwRenderStateGet queries the value of a renderstate element.

Parameters:

state	The RwRenderState element to be queried.
value	A pointer to memory to receive the value of the renderstate element.

Returns:

Returns TRUE if successful or FALSE if there is an error

      RwShadeMode  shadeMode;
      RwBool       zTest;

      RwRenderStateGet(rwRENDERSTATESHADEMODE, (void *)&shadeMode);
      RwRenderStateGet(rwRENDERSTATEZTESTENABLE, (void *)&zTest);

See also:

RwRenderState Overview , RwRenderStateSet , RwIm3DGetRenderPipeline

RwRenderStateSet is used to set the value of a particular renderstate element.

Attention:

This should only be used between calls to RwCameraBeginUpdate and RwCameraEndUpdate.

Parameters:

state	The RwRenderState to set.
value	The value of the renderstate, cast to type (void *).

Returns:

Returns TRUE if successful or FALSE if there is an error or the renderstate is not supported.

      RwRenderStateSet(rwRENDERSTATESHADEMODE, (void *)rwSHADEMODEGOURAUD);
      RwRenderStateSet(rwRENDERSTATEZTESTENABLE, (void *)TRUE);
      RwRenderStateSet(rwRENDERSTATETEXTURERASTER, (void *)raster);

Many of the renderstates may not be supported on certain platforms and this function will return FALSE in such cases. It is recommended that during development you check the return value to check for unsupported states or values. Refer to the platform specific documentation for more details of unsupported states, and also for any details of any platform specific renderstate functions.

See also:

RwRenderState Overview , RwRenderStateGet , RwIm3DGetRenderPipeline