RwDeviceControl(RwDeviceAction action, RwInt32 param1,
void *param2, RwInt32 size);
Arguments
action Under MS DOS, RenderWare provides the following device control actions.
· rwSCRGETCOLOR
This device control is used for resolution independent selection of colors from the colors available. On being given a color specified as an array of three numbers denoting the red green and blue components of the color, this control returns the device dependent color value, which when copied directly to the screen will display the correct color. param1 is ignored (pass 0L). param2 should be a pointer of three RwReals specifying the color. A red component value of CREAL(1.0) means the maximum amount of red. A red component of CREAL(0.0) means no red. size should be the size of the data pointed to by param2 (i.e., sizeof(RwReal) * 3).
For example, the following;
RwReal
red[]={CREAL(1.0), CREAL(0.0), CREAL(0.0)};
RwInt32 colorred;
colorred = RwDeviceControl(rwSCRGETCOLOR, 0L,
red, sizeof(RwReal) * 3);
sets colorred to be the device dependent color value for red whatever resolution the video adapter is in.
· rwPOINTERREMOVE
This device control removes the mouse pointer from the display. param1 and param2 and size are all ignored (pass 0L, NULL and 0L respectively).
For example;
RwDeviceControl(rwPOINTERREMOVE, 0L, NULL, 0L);
will remove the mouse pointer from the display.
This control returns TRUE if successful and FALSE otherwise.
· rwPOINTERDISPLAY
This device control displays the mouse pointer. param1 is ignored (pass as 0L), param2 should point to an RwMousePointer structure (as described below) and size should be the size of an RwMousePointer structure (i.e., sizeof(RwMousePointer)).
typedef
struct
{
RwInt32 x;
RwInt32 y;
RwInt32 buttons;
} RwMousePointer;
This will display the mouse pointer at the current mouse position (removing the mouse pointer at its previous position if necessary). The structure is filled with the position and the current button status of the mouse. For the mouse button, bit 1 will be set if the left button is pressed and bit 3 will be set if the right button is pressed (for three button mice, bit 5 will be set if the middle button is pressed). The x and y co-ordinates are the screen coordinates of the hotspot of the mouse pointer.
For example:
RwMousePointer mouse;
RwDeviceControl(rwPOINTERDISPLAY, 0L, &mouse, sizeof(mouse));
Will display the mouse at its current coordinates and fill the mouse structure with the current mouse status.
This control returns TRUE if successful and FALSE otherwise.
· rwMOUSESETREGION
This device control sets the rectangle in which the mouse can be used. It also has the ability to control the mouse movement speed. Initially when the library is opened the mouse is allowed to move over the entire screen area. This device control can restrict this area. param1 is ignored (pass 0L), for normal mouse movement. Setting param1 to a positive value will mean that for a pixel movement the mouse requires 2^param1 mouse events (or mickeys), i.e., if param1 is set to 3 then 8 mickeys are required for each pixel movement. If param1 is set to a negative number then the speed of the pointer is accelerated by 2^-param1, i.e., if param1 is set to -4 for each mickey the mouse pointer will move 16 pixels. param2 should point to an RwRect structure and size should be the size of an RwRect structure (i.e., sizeof(RwRect)). This defines the area the hot spot of the mouse can traverse.
For example;
RwRect
area;
area.x = 20;
area.y = 50;
area.w = 100;
area.h = 10;
RwDeviceControl(rwMOUSESETREGION, -1L, &area,
sizeof(area));
only allows the mouse pointer hotspot to occupy the region 20 to 120 for the x coordinate and 50 to 60 in the y co-ordinate. The mouse will now move 2 pixels for every mickey (mouse event).
This control returns TRUE if successful and FALSE otherwise.
· rwPOINTERSETCLIPREGION
This device control sets he clipping region for the mouse sprite image. param1 is ignored (pass 0L). param2 should point to an RwRect structure and size should be the size of an RwRect structure (i.e., sizeof(RwRect)). This defines the area the mouse sprite image should be clipped to.
For example;
RwRect
clip;
clip.x = 40;
clip.y = 80;
clip.w = 40;
clip.h = 90;
RwDeviceControl(rwPOINTERSETCLIPREGION, 0L,
&clip, sizeof(clip));
sets the clipping region to be between 40 and 80 for the x co-ordinate and 80 and 170 in the y co-ordinate.
This control returns TRUE if successful and FALSE otherwise.
· rwPOINTERDISPLAYAT
This action displays the pointer image at a specified position on the screen. param1 is ignored, param2 should be a pointer to an RwMousePointer structure and size should be the size of an RwMousePointer structure.
The x field of the RwMousePointer structure is the screen X coordinate that the pointer image is to be placed at. The y field is the screen Y coordinate that the pointer image is to be placed at.
If the image is currently displayed at another position on the display it is removed before the image is displayed at the new position. The pointer clipping rectangle applies to the newly displayed image. The mouse bounding region will not have any affect on the positioning. The mouse pointer will remain at the new position until,
1) rwPOINTERDISPLAY is used - then the pointer image will move to the current mouse position.
2) rwPOINTERDISPLAYAT is used - the pointer image at the previous position is removed and the pointer image is displayed at the new position.
3) rwPOINTERREMOVE is used - the pointer is removed from the display.
This control returns TRUE if successful and FALSE otherwise.
· rwSCRSETCOLOR
Sets a palette entry such that on the next palette change the color will be installed. param1 should be set to the number of the palette entry to be set. param2 should point to an RwPaletteEntry and hold the new color values.
The following example sets palette entry 5 to green.
{
RwPaletteEntry entry;
entry.r = 0;
entry.g = 0xff;
entry.b = 0;
RwDeviceControl(rwSCRSETCOLOR, 5,
&entry, sizeof(entry));
}
· rwSETPHYSICALPALETTEENTRY
Sets a physical palette entry without in anyway affecting RenderWare. The rwSCRSETCOLOR device control is similar except that it registers the palette entry internally with RenderWare which can cause it to be used in subsequent palette matching.
The following example sets the background color (0) to red.
{
RwPaletteEntry entry;
entry.r = 255;
entry.g = 0;
entry.b = 0;
RwDeviceControl(rwSETPHYSICALPALETTEENTRY, 0,
&entry,
sizeof(entry));
}
· rwSETCHARSET
This device control allows for the setting of an arbitrary character set for printing. param1 is ignored (passed as 0L), param2 should point to a RwCharset structure.
typedef
struct RwCharsetTag
{
RwInt32 first;
RwInt32 last;
unsigned char *bitmap;
RwInt32 width;
RwInt32 height;
} RwCharset;
first is the first character in the ASCII character set which is in the bitmap (this is often space).
last is the last character in the ASCII character set which is in the bitmap.
bitmap is in the form of a bit set for each pixel. Each bitmap raster line is always made up of an integer amount of bytes. This means that if an image is 15 pixels wide and one pixel high the bitmap will take 2 whole bytes.
width is the characters width.
height is the characters height.
Note that the characters should appear in the pixmap in 'ASCII order' from the 'first' character through to the last character.
Trying to print a character less than the first or greater than the last will cause the first character in the set to be drawn.
The following example creates a character set with A as a triangle and B as a square (sizes of 4 by 4 pixels):
/*
Note that the bitmap has to have a global scope.
I.e. a
locally declared bitmap will only be useable
within the
function. */
static
unsigned char bitmap[] = {0x80,0xc0,0xe0,0xf0,
0xf0,0xf0,0xf0,0xf0};
{
RwCharset charset;
charset.first = 'A';
charset.last = 'B';
charset.bitmap = bitmap;
charset.width =4;
charset.height = 4;
RwDeviceControl(rwSETCHARSET, 0,
&charset, sizeof(charset));
}
· rwPRINTCHAR
This device control provides a simple way of displaying a character in any resolution. param1 is ignored (passed as 0L) and param2 should point to a structure RwPrintChar (as described below). Size should be the size of an RwPrintChar i.e. sizeof(RwPrintChar).
typedef
struct RwPrintCharTag
{
RwInt32 x;
RwInt32 y;
char c;
char mode;
char __pad[2];
RwRaster *raster;
RwInt32 foreground;
RwInt32 background;
} RwPrintChar;
x is the x coordinate in pixels (0 is the left of the screen).
y is the y coordinate of the character in pixels (0 is the top of the screen.)
c is the character to be displayed.
mode is the type of character display which is to be used. There are two options which can be set 'rwTRANSPARENT' and 'rwRASTER'. rwTRANSPARENT will cause the character to be printed without writing 'background' pixels. rwRASTER will cause the character to be printed into the raster pointer to by raster.
raster is only required with the rwRASTER mode option and is the raster to be printed to.
foreground is the device dependent color the character will be displayed in. In an 8 bit mode it is an index into the palette. In a 16 bit mode, the color is encoded into the low 16 bits of color. The simplest way of finding a color via red, green, blue values is via the rwSCRGETCOLOR device control.
The following example displays a character 'Z' on the screen at position 20,40 with red foreground and green background:
{
RwPrintChar print;
RwReal red[] = {CREAL(1),CREAL(0),CREAL(0)};
RwReal green[] = {CREAL(0),CREAL(1),CREAL(1)};
print.x = 20;
print.y = 40;
print.mode = 0; /* Non transparent to the screen
*/
print.foreground = RwDeviceControl(rwSCRGETCOLOR,
0L,
red, sizeof(red));
print.background = RwDeviceControl(rwSCRGETCOLOR,
0L,
green, sizeof(green));
print.c = 'Z';
RwDeviceControl(rwPRINTCHAR, 0L,
&print, sizeof(print));
}
The following example displays a character 'Y' onto the raster 'raster' at 10,10 in blue with transparency.
{
RwPrintChar print;
RwReal blue[] = {CREAL(0),CREAL(0),CREAL(1)};
print.x = 10;
print.y = 10;
print.mode = rwRASTER|rwTRANSPARENT;
print.foreground = RwDeviceControl(rwSCRGETCOLOR,
0L,
blue, sizeof(blue));
print.c = 'Y';
print.raster = raster;
RwDeviceControl(rwPRINTCHAR, 0L,
&print, sizeof(print));
}
· rwMOUSEGETPOSITION
This action returns the current absolute position of the mouse along with the mouse button status. param1 is ignored, param2 should be a pointer to an RwMousePointer structure and size should be set to the size of an RwMousePointer structure. This structure will be filled in with the current absolute position of the mouse as well as the current mouse button status. This will have no effect on any currently displayed pointer image.
Note that the x and y values returned will be bounded by the settings passed to rwMOUSESETREGION.
TRUE is returned if successful, FALSE otherwise.
The following example gets the current mouse absolute position
{
RwMousePointer position;
RwDeviceControl(rwMOUSEGETPOSITION, 0,
&position, sizeof(position));
}
· rwMOUSEGETRELATIVE
This action returns the current relative position of the mouse along with the mouse button status. param1 is ignored, param2 should be a pointer to an RwMousePointer structure and size should be the size of an RwMousePointer structure.
The structure is filled with the number of 'mickeys' that have occurred between the previous call to this function (or the start of the application) and the current call. The x field in the structure holds the number of mickeys moved, since the last call, in the X direction. The y field holds the number of mickeys moved, since the last call, in the Y direction. The button entry will hold the current mouse button status.
A 'mickey' is the highest resolution value of change given by the mouse. It is a relative value - positive values mean right or down, negative values mean left or up. The larger the mickey value the greater the distance the mouse has moved.
Note: The mickey values can used to produce the 'absolute' position of the mouse if, after the first call, the corresponding relative mickey values are added to a running total of mickeys in the X and Y directions. The running totals are then the 'absolute' position of the mouse.
This control returns TRUE if successful and FALSE otherwise.
The following example finds the number of mickeys moved since the previous call.
{
RwMousePointer relative;
RwDeviceControl(rwMOUSEGETRELATIVE, 0,
&relative, sizeof(relative));
}
· rwEXPANDBITMAP
This function expands up a bitmap into a RwRaster of the required depth. The size of the raster indicates the size of the bitmap. param1 is ignored (set to 0L). param2 should point to an RwBitmapExpand structure, size should be set to the size of a RwBitmapExpand structure.
typedef
struct RwBitmapExpandTag
{
unsigned char *bitmap;
RwInt32 foreground;
RwInt32 background;
RwRaster *raster;
} RwBitmapExpand;
bitmap points to the bitmap to be expanded. Note each horizontal line in the bitmap always fills a whole number of bytes. So for example a 15 by 8 bitmap would have 2 bytes per horizontal line and thus would take up 16 bytes.
The following example expands a bitmap of the character '!' into a raster:
{
RwRaster *raster;
unsigned char bitmap[] =
{0x18, 0x18, 0x18, 0x18, 0x18, 0x00, 0x18, 0x00};
RwBitmapExpand expand;
RwReal red[] = {CREAL(1),CREAL(0),CREAL(0)};
RwReal green[] = {CREAL(0),CREAL(1),CREAL(0)};
/*
Note the size of the bitmap is determined by
the size of the raster */
raster = RwCreateRaster(8,8);
/* Set up the expand structure */
expand.raster = raster;
expand.foreground =
RwDeviceControl(rwSCRGETCOLOR, 0L,
red, sizeof(red));
expand.background =
RwDeviceControl(rwSCRGETCOLOR, 0L,
green, sizeof(green));
expand.bitmap = bitmap;
/* Expand the bitmap */
RwDeviceControl(rwEXPANDBITMAP, 0,
&expand, sizeof(expand));
}
· rwMOUSESETREGION
This device control sets the rectangle in which the mouse can be used. Initially when a device is started the mouse is allowed to move over the entire screen area. param1 is ignored (pass 0L). param2 should point to an RwRect structure and size should be set to the size of an RwRect structure (i.e. sizeof(RwRect)). This defines the area the hot spot of the mouse can traverse.
The following example restricts mouse movement to a 100 by 50 rectangle whose top left corner is at 20,10.
{
RwRect area;
area.x = 20;
area.y = 10;
area.w = 100;
area.h = 50;
RwDeviceControl(rwMOUSESETREGION, 0,
&area, sizeof(area));
}
· rwMOUSESETPOSITION
This action sets the internal mouse absolute position (as read by rwMOUSEGETPOSITION or rwPOINTERDISPLAY). param1 is ignored, param2 should be a pointer to an RwMousePointer structure and size should be the size of an RwMousePointer structure.
The x field of the RwMousePointer structure is the screen X coordinate that the mouse is to be placed at. The y field is the screen Y coordinate that the mouse is to be placed at.
The mouse bounding region is not taken into account when the position is set. Note that this control will not redisplay the pointer at the new position. The pointer will be displayed at its new position on the next rwDISPLAYPOINTER call.
This control returns TRUE if successful and FALSE otherwise.
· rwMOUSESETSPEED
This action can be used to alter how many 'mickeys' (mouse events) equate to a mouse position change. Setting param1 to a positive value will mean that for a pixel movement the mouse requires 2^param1 mouse events (or mickeys). I.e. if param1 is set to 3 then 8 mickeys are required for each movement. If param1 is set to a negative value then the speed of the pointer is accelerated by 2^-param1. I.e. if param1 is set to -4 then for each mouse event the mouse coordinate will move by 16. Setting param1 to zero will mean mickey events will map exactly onto mouse movements.
param2 is ignored and should be set to NULL along with size which should be set to 0.
The example below sets the mouse speed so that it moves half of its usual speed.
RwDeviceControl(rwMOUSESETSPEED,1,NULL,0);
· rwSETMOUSESTATE
This action allows for the control of the installing or deinstalling of the mouse. param1 should be set to TRUE if the mouse is to be installed and FALSE if it isn't to be installed. param2 is ignored and should be set to NULL along with size which should be set to zero. If this action is performed before the device is opened then starting of the mouse will only be attempted when the device is started (and could therefore cause the starting of the device to fail.) If this action is performed when the device is started, the mouse characteristics will be set to their default values. If the mouse is successfully installed TRUE will be returned otherwise FALSE will be returned.
The following example installs the mouse driver.
RwDeviceControl(rwSETMOUSESTATE,TRUE,NULL,0);
· rwPOINTERSETIMAGE
This action allows for the setting of an arbitrary raster as an image for the mouse pointer. Note that the RwRaster passed can be destroyed as the DOS device driver will create a copy of the image itself. param1 is ignored and should be set to 0. param2 should be a pointer to the pointer to the raster (NOT the raster pointer). size should be the size of a RwRaster pointer.
Zero values in the raster indicate transparency. Note that the type of the bits will change depending on the depth of rendering being used. When in an eight bit mode bytes map to pixels, whilst in 16 bit modes shorts map to pixels.
The following example reads a raster and sets it to the mouse image
{
RwRaster *raster;
raster = RwReadRaster("hue.ras",0L);
RwDeviceControl(rwPOINTERSETIMAGE, 0,
&raster, sizeof(raster));
}
· rwPOINTERDEFAULT
This action sets the mouse pointer image back the default image. param1 should be set to the foreground color required, param2 should be set to the background color required. size should be set to zero. Note it is necessary to remove the mouse pointer if no ghosting of the previous mouse image is desired.
The following example sets the default mouse pointer to a cyan foreground and blue background.
{
RwReal cyan[] = {CREAL(0),CREAL(1),CREAL(1)};
RwReal blue[] = {CREAL(0),CREAL(0),CREAL(1)};
/*
Its necessary to remove the pointer if you want
no cursor'ghosting' */
RwDeviceControl(rwPOINTERREMOVE, 0, NULL, 0);
RwDeviceControl(rwPOINTERDEFAULT,
RwDeviceControl(rwSCRGETCOLOR, 0L,
cyan, sizeof(cyan)),
(void *)RwDeviceControl(rwSCRGETCOLOR, 0L,
blue, sizeof(cyan)),
0);
}
· rwVESAGETVESAMODENUMBER
Finds the VESA mode number for the equivalent 'RenderWare mode'. Note that 'true' VESA modes (i.e. ones which are accessed via the VESA BIOS) always have numbers greater than 0xff. These modes are the only modes which allow capabilities such as hardware double buffering and 8 bit DACs.
param1 should be set to the 'RenderWare mode' of interest. param2 should point to a RwInt32 which will receive the mode number.
The example below finds the VESA modes for all RenderWare modes
{
RwInt32 i;
RwInt32 nummodes;
RwGetDeviceInfo(rwGETNUMVIDEOMODES,
&nummodes,
sizeof(nummodes));
for
(i=0; i < nummodes; i++)
{
RwInt32 vesamode;
RwDeviceControl(rwVESAGETVESAMODENUMBER, i,
&vesamode, sizeof(vesamode));
printf("RenderWare Mode : %d VESA mode : %d
\n",
i, vesamode);
}
}
· rwVESASETDACSIZE
Sets the current DAC (digital to analogue converter) size in bits. The VGA standard requires 6 bit DACs providing 64 shades of gray. Newer cards have full 8 bit DACs which provide 256 shades of gray and therefore subtler color. It is only possible to access the 8 bit DACs if a suitable VESA BIOS is installed and you are using a VESA video mode. The only currently supported values are 8 and 6.
Note that RenderWare defaults to trying to use 6 bit DACs as some cards VESA BIOS’s erroneously report having 8 bit DACs and then are unable to switch to the correct mode.
param1 should hold the DAC size required. param2 and size are unused and should be set to NULL and 0 respectively. If the DAC size cannot be set FALSE will be returned. The following example attempts to set an 8 bit DAC
RwDeviceControl(rwVESASETDACSIZE,8,NULL,0);