RwDeviceControl(RwDeviceAction action,
RwInt32 param1,
void *param2, RwInt32 size);
Description
Performs low-level, device dependent actions.
Arguments
action Device dependent action.
param1 First action specific parameter.
param2 Second action specific parameter.
size Size in bytes of the buffer (if any) pointed to by param2.
Return Value
The return value is dependent on the device dependent action being performed.
Comments
size gives the size in bytes of the buffer pointed to by the second action specific parameter, param2. For example, to control the stretching of rendering under Microsoft Windows the following device control would be used:
RwWinOutputSize winOutputSize;
winOutputSize.width = 640;
winOutputSize.height = 480;
winOutputSize.camera = Camera;
RwDeviceControl(rwWINSETOUTPUTSIZE, 0L,
&winOutputSize, sizeof(winOutputSize));
If param2 is NULL size is ignored.
The following device controls are generic and are supported for all devices, the value in brackets after each control type indicates whether the control can be used before or after the device is initialized.
· rwSETPALETTEMATCHSTATE (AFTER)
param1 should be set to the palette entry to have its state set. param2 should point to an RwBool. If the match state of a palette entry is TRUE then the palette entry will be used in the matching process. The internal palette colour will be the colour associated with an entry. Setting a palettes matching state to FALSE will stop it taking part in the matching process. This will allow palette entries to be used for other purposes (for example colour cycling). Note the palette must be resolved for the match state to have any effect. Also note that textures loaded with previous palettes previously will potentially reference the wrong colours.
· rwGETPALETTEMATCHSTATE (AFTER)
param1 should be the palette entry of interest, param2 should point to an RwBool. Gets an internal palette entries matching state. If the state for a palette entry is true then it will be used by RenderWare in the palette matching process. If it is set to false the palette entry will never be used in the palette matching process.
· rwSETINTERNALPALETTEENTRY (AFTER)
param1 should be the palette entry number to be set, param2 should point to an RwPaletteEntry. RenderWare has an internal palette which is used when palette matching needs to be performed. This internal palette may be completely different to the actually defined physical palette. It is the responsibility of the programmer to set the physical palette entry once the internal palette entry has been set. (Note the setting and palette matching automatically take place when using RwSetPaletteEntries).
· rwGETINTERNALPALETTEENTRY (AFTER)
param1 should be the palette entry of interest, whilst param2 should point to a RwPaletteEntry. Gets a palette entry from RenderWares internal palette matching palette. This palette may be entirely different from the physical palette. It is the responsibility of the programmer to keep the two in line.
· rwRESOLVEINTERNALPALETTE (AFTER)
param1 should be set to 0, param2 should be set to NULL. Setting internal palette entries and palette matching states have no effect until the palette is resolved. When this (potentially slow) process is initiated the internal palette will be matched against the palette entries who have a matching state of TRUE.
· rwGETPALETTEENTRYNO (AFTER)
This device control should only be used on palette based devices. It's purpose is to allow access to the 'meta palette' which is a table providing a mapping between the RGB color space (in terms of color ramps) and the palette. The RGB color space is divided up into a set of ramps which contain a single color hue. The ramps increase in intensity (value) from the first entry up to 75% up the ramp, then the color is saturated towards white.
param2 should be the color with the hue of the ramp required.
param1 is the ramp entry of interest. This should be a number between 0 and the value returned from RwGetDeviceInfo() with parameter rwGETPALETTERAMPLENGTH.
The ramp entry is the return value from RwDeviceControl(). The example below sets the middle ramp entry in the ramp with hue defined by color to the palette entry 20.
{
RwRGBColor color;
RwInt32 ramplength;
RwInt32 rampentry;
RwUInt32 palettevalue;
color.r = CREAL(0.4); /* Selects hue of ramp */
color.g = CREAL(1.0);
color.b = CREAL(0.5);
/* Get the size of the ramps */
RwGetDeviceInfo(rwGETPALETTERAMPLENGTH,
&ramplength, sizeof(ramplength));
/* Get the entry */
rampentry = RwDeviceControl(rwGETPALETTEENTRYNO,
ramplength/2,
&color, sizeof(color));
/* Set the entry to a palette entry */
palettevalue = 20; /* 21st physical palette entry */
RwDeviceControl(rwSETPALETTEENTRY, ramp,
&palettevalue,
sizeof(palettevalue));
}
· rwSETPALETTEENTRY (AFTER)
Sets a palette entry in the meta palette. param1 should be the value returned from the RwDeviceControl with parameter rwGETPALETTEENTRYNO. param2 should be the physical palette entry the ramp entry should be set to. See rwGETPALETTEENTRYNO for an example.
· rwUSEVIDEOMODE (BOTH)
Switches RenderWare into a resolution. If this is performed before a device is started then the resolution switch will only occur after the device has started.
The example code below looks for a video mode with 8 bit depth and 640 by 400 pixels. The function returns TRUE if it successfully flips into the video mode otherwise it returns FALSE.
NOTE: If this performed before the device is started, then the video mode will not become apparent until the device is started.
RwBool
Find640x400x8VideoMode(void)
{
RwInt32 nummodes, i;
RwVideoMode modeinfo;
/* Find the
number of video modes */
if
(RwGetDeviceInfo(rwGETNUMVIDEOMODES, &nummodes,
sizeof(nummodes)))
{
/* This device can change video modes */
/* Go through all video modes finding accessible ones */
for (i = 0;
i < nummodes; i++)
{
if (RwDeviceControl(rwGETVIDEOMODEINFORMATION, i,
&modeinfo, sizeof(modeinfo)) )
{
/* This mode is accessible from RenderWare */
if (
(modeinfo.width == 640) &&
(modeinfo.height == 400) &&
(modeinfo.depth == 8))
{
/* Found a suitable video mode - Use it */
if
(RwDeviceControl(rwUSEVIDEOMODE,
i, NULL, 0))
{
/* Flipped into the video mode
successfully */
return TRUE;
}
else
{
/* Found the mode but couldn't
flip into it */
return FALSE;
}
}
}
}
}
else
{
/* This device is unable to change video modes */
return FALSE;
}
return FALSE;
}
· rwGETVIDEOMODEINFORMATION (BOTH)
RenderWare video mode numbers are numbered from zero up to the value returned from rwGETNUMVIDEOMODES. param1 holds the video mode number of interest ( between 0 and the value returned form rwGETNUMVIDEOMODES ). param2 should point to a RwVideoMode structure as follows:
typedef
struct _rwvideomode
{
RwUInt32 width; /* Video mode pixel width */
RwUInt32 height; /* Video mode pixel height */
RwUInt32 depth; /* Video mode bits per pixel */
RwBool accessible; /* TRUE if the mode is
accessible */
RwUInt32 flags; /* Video mode flags currently
only
supports rwHWDOUBLEBUFFER */
}
RwVideoMode;
The rwHWDOUBLEBUFFER flag indicates if it is possible for this device to hardware double buffer. The example code below checks if a video mode can hardware double buffer
RwBool
VideoModeDoubleBuffer(RwInt32 mode)
{
RwInt32 nummodes;
RwVideoMode modeinfo;
/* Check if mode switching is possible */
if
(RwGetDeviceInfo(rwGETNUMVIDEOMODES,
&nummodes, sizeof(nummodes)))
{
if ((mode >= nummodes)||(mode < 0))
{
/* Video mode is out of range */
return FALSE;
}
RwDeviceControl(rwGETVIDEOMODEINFORMATION,
mode, &modeinfo, sizeof(modeinfo));
if
((modeinfo.accessible) &&
(modeinfo.flags & rwHWDOUBLEBUFFER))
{
return TRUE;
}
}
return FALSE;
}
See rwUSEVIDEOMODE for more example code.
· rwSETGAMMACORRECT (BEFORE)
Sets the status of gamma correction. If param1 is set to TRUE gamma correction will be performed. If param1 is set to FALSE then no gamma correction will be performed. The example below sets gamma correction on.
RwDeviceControl(rwSETGAMMACORRECT, TRUE, NULL, 0);
· rwSETDOUBLEBUFFER (BEFORE)
Sets double buffering status. Setting param1 to TRUE will cause hardware double buffering to be used. Setting param1 to FALSE will stop hardware double buffering.
The example below sets hardware double buffering on.
RwDeviceControl(rwSETDOUBLEBUFFER, TRUE, NULL, 0);
· rwSETZBUFFERSTATE (BOTH)
Sets the status of the Z buffer. If param1 is TRUE and the device is capable of Z buffering then subsequent renderings will allow the use of the Z buffer. If param1 is FALSE then RenderWare will not perform any Z buffering.
The example below turns off Z buffering.
RwDeviceControl(rwSETZBUFFERSTATE,FALSE,NULL,0);
· rwSETPSEUDOPHONG (AFTER)
Sets the gouraud shaders so that they perform 'pseudo phong' shading. param1 should be set to TRUE if phong shading is required. If param1 is set to FALSE gouraud shading will be performed by default. This operation will only function on an 8 bit renderer.
· rwSETSATURATION (AFTER)
Sets the point when saturation of a color is performed relative to lighting values. Lighting values are from 0 to 1.0 in RenderWare, and usually between 0 and 0.75 a colors luminance is increased to its maximum, and from 0.75 to 1.0 a color is saturated to white. This device control allows you to set the position where saturation starts. This control will only function on 8 bit renderers.
· rwRESTOREHARWARERASTERS
If the application loses the focus then other applications may overwrite the video memory. This device control is used to force the driver to reload any rasters or other information cached in video memory.
· rwSETPASSTHROUGHSTATE
If the hardware supports vide passthrough then this device control allows the application to select which video surface is displayed. If param1 is TRUE then VGA passthrough is enabled.
The additional supported actions and their associated parameter values are device dependent. See Appendix B for details.