Requirements
The floating-point RenderWare library requires an IBM PC compatible with an Intel Pentium or 80486 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 P90 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.
RenderWare also requires one of the following versions of the Windows operating system.
· Windows 95
· Windows NT Version 3.5 or 4.0.
In order to build programs with RenderWare you will need a 32 bit compiler that can link to an import library generated from a standard WIN32 DLL.
Environment Variables
The RenderWare library makes use of several environment variables, RWSHAPEPATH, RWDEBUGSTREAM 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 Windows. Setting the environment variable from a DOS window running under Windows will not work. It is strongly recommended that the necessary environment variables be set in the host machine’s AUTOEXEC.BAT.
RenderWare Dynamic Link Libraries (DLLs)
RenderWare for Windows is only available in dynamic link library (DLL) form.
There is one core RenderWare DLL, This is
In addition to this DLL, RenderWare provides a number of driver DLL’s. These have all been given the prefix RWDL for RenderWare floating point Driver) to facilitate fast querying and loading of the available drivers. For the software drivers, the following naming convention is used. Hardware driver manufacturers are free to select their own names :
RWDL [6|8|M] [A|B|C|D]21.DLL
M MMX 16 bit
6 16 bit
8 8 bit
A 32 bit Z buffer, 256*256 textures
B 16 bit Z buffer, 256*256 textures
C 32 bit Z buffer, 128*128 textures
D 16 bit Z buffer, 128*128 textures
The recommended location for installing the DLLs is in the Windows System directory. The RenderWare setup program will install the DLLs required to run the RenderWare demonstration programs in the System directory at installation time.
For all of these DLL’s there are 4 variants which may be installed. These select debugging/production and static/dynamic loading of run time libraries. All of these variants are direct drop in replacements for the standard version.
These four variants are installed by default into the \rwwin\lib directory as follows:
Note: For programs which are to run on WIN32s, the static variants of the drivers should be used. If the Dynamic variants are used then the Microsoft Visual C 4.x run time DLLs should also be installed.
The Debugging DLLs
When using the DLL, no relinking is necessary in order to use the debugging version of RenderWare. The static import libraries provided by RenderWare are suitable for either retail or debugging versions of RenderWare.
The static import libraries always attempt to load the same DLL. Therefore, to switch from using the retail DLL to the debugging DLL simply overwrite the existing retail DLLs in c:\windows\system with the debugging DLLs. For example, switching from retail to debugging RenderWare kernels is achieved as follows;
copy
c:\rwwin\lib\static\debug\*.dll c:\windows\system
(assuming RenderWare for windows was installed in c:\rwwin and the Window System directory is c:\windows\system).
Switching back to retail libraries simply involves overwriting the debugging DLLs with the retail ones;
copy
c:\rwwin\lib\static\nondebug\*.dll c:\windows\system
Libraries and Include Files
For the purposes of describing how to build programs, the following assumptions are made:
· the RenderWare include files are installed in \rwwin\include.
· the RenderWare library files are installed in \rwwin\lib.
Source files must include the RenderWare include file:
#include
<rwlib.h>
If your application use the platform specific RwOpenExt() options or RwGetDeviceInfo() information types then the application will also need to include the Windows specific header file rwwin.h. However, it is recommended that, to ensure future compatibility, all source files which use RenderWare API functions include rwwin.h after including the standard RenderWare include file:
#include
<rwlib.h>
#include <rwwin.h>
RenderWare and Windows Bitmap Types
With RenderWare V2.1, the bitmap selection mechanism has been simplified. The following bitmap types are supported on WIN32
· Direct Draw Surface
· DibSection
· DIB
RenderWare V2.1 will select the fastest bitmap type available for a given setup.
For the majority of applications the selection of bitmap type will be entirely transparent to the application developer. However, for those developers who need to interact with RenderWare at a low-level to achieve special effects this section discusses the algorithm used to select the bitmap type. The means by which a developer can fine tune this process and enquire about the chosen bitmap type are also discussed. Initially a short description of each bitmap type will be given.
DIBs are available on all operating system platforms. They are, however, by far the slowest bitmap type and are to be avoided. They are provided only as "last resort" fallback when other bitmap types are not available.
DIB Sections are an enhanced form of DIBs provided by Microsoft’s Windows 95 and Windows NT 4.0 operating systems. They provide a fast portable bitmap format.
RenderWare V2.1 has support for a native Direct Draw surface. These may be available under Windows 95 and NT 4.0
How the Bitmap Type is Chosen
The choice of bitmap handling mechanism is based on two factors:
The following table summarizes the choice of bitmap type for each combination of the above factors. In all case if Direct Draw is not available, DIBSections will be used.
Windowed Mode |
Full Screen |
|
8 or
16-bit output |
4, 15 or
24-bit output |
8 or 16-bit only |
| Direct Draw | DibSection | Direct Draw |
Overriding the Choice of Bitmap Type
In certain circumstances it may be desirable to override RenderWare’s default choice of bitmap type. For example, if you wish to print or save the results of RenderWare’s rendering it may be more convenient to use DIBs than the other bitmap types.
RenderWare allows the application developer to specify that they wish to favor either DibSections or DIBs over RenderWare’s default choice of bitmap type. This is done by supplying additional arguments (rwWINUSEDIBSECTION or rwWINUSEDIB) when opening the library with the API call RwOpenExt().
To specify DIBs, rwWINUSEDIBS should be given as one of the additional arguments to RwOpenExt(). For example;
RwOpenArgument
arg;
arg.option = rwWINUSEDIBS;
arg.value = 0L; /* This value is ignored for rwWINUSEDIBS
*/
if (!RwOpenExt("MSWindows", NULL, 1, &arg))
{
...
To specify DibSections, rwWINUSEDIBSECTION should be given as one of the additional arguments to RwOpenExt(). For example;
RwOpenArgument
arg;
arg.option = rwWINUSEDIBSECTION;
arg.value = 0L; /* This value if ignored for
rwWINUSEDIBSECTION */
if (!RwOpenExt("MSWindows", NULL, 1, &arg))
{
...
Mode enumeration using Direct Draw driver
When using the Direct Draw driver, there will usually be a number of modes available. These can be enumerated and selected with the device info controls and device controls described below:
There is an additional field (rwHWWINDOWED) to the flags field of the RwVideoMode structure, which specifies whether a mode is windowed or not.
There are circumstances under which there will not be a windowed mode available under the RenderWare Direct Draw driver. Under these circumstances, the driver will not use Direct Draw unless you specify the rwAPPCANUSEFULLSCREEN open option, meaning that the application can cope with a full screen mode.
The default mode in which the Direct Draw driver opens is mode 0 (which is usually the windowed mode). This may be changed either before or after the device is started.
RwInt32
nummodes;
RwGetDeviceInfo(rwGETNUMVIDEOMODES,
&nummodes, sizeof(nummodes));
Will get the number of video modes available using the current driver.
RwVideoMode
modeinfo;
RwDeviceControl(rwGETVIDEOMODEINFORMATION,
n, &modeinfo, sizeof(modeinfo));
Will get information on video mode <n>.
RwDeviceControl(rwUSEVIDEOMODE,
<n>, NULL, 0);
Will select mode <n> to be use for displaying future renderings.
Determining the Choice of Bitmap Type
It is sometimes important to determine which bitmap type RenderWare has chosen. This can be done using the API function RwGetDeviceInfo() and the device information types rwWINUSINGDIBS and rwWINUSINGDIBSECTIONS.
To determine whether RenderWare is using DIBs the following code fragment would be used;
RwBool
usingDIBs;
RwGetDeviceInfo(rwWINUSINGDIBS, &usingDIBs,
sizeof(usingDIBs));
if (usingDIBs)
{
/* RenderWare is using DIBs... */
To determine whether RenderWare is using DibSections the following code fragment would be used;
RwBool
usingDibsections;
RwGetDeviceInfo(rwWINUSINGDIBSECTIONS,
&usingDibSections, sizeof(usingDibSections));
if (usingDibsections)
{
/* RenderWare is using DibSections... */
If neither rwWINUSINGDIBS or rwWINUSINGDIBSECTIONS yields a non-zero result then the default bitmap type is being used. For a Win32 executable the default type is Direct Draw.
When performing software only rendering, the size of viewport to which RenderWare renders can have a significant impact on performance, particularly if a high per-pixel cost rendering mode is employed (such as lit, smooth shaded, foreshortened texture mapping). One approach to improving performance is bitmap stretching where RenderWare renders to a small viewport and the rendering is then stretched up to fill a significantly larger rectangle on the output device.
In RenderWare control over bitmap stretching is provided by the rwWINSETOUTPUTSIZE device control. This device control specifies the width and height of the rectangle on the output device that the viewport will be stretched to fill (control over rendering resolution is still achieved through the function call RwSetCameraViewport()).
When specifying stretching, the arguments to RwDeviceControl() are as follows:
action rwWINSETOUTPUTSIZE
param1 Not used (pass 0)
param2 A pointer to an RwWinOutputSize structure as described below;
typedef
struct
{
RwInt32 width; /* Width of the output */
RwInt32 height; /* Height of the output */
RwCamera *camera; /* Camera whose output is
to be stretched */
} RwWinOutputSize;
size The size of RwWinOutputSize (i.e., sizeof(RwWinOutputSize)).
This control specifies the actual output width and height desired for the given camera. For example, the following sets the output size of the camera Camera to 640 by 480 pixels;
RwWinOutputSize
winOutputSize;
winOutputSize.width = (RwInt32)640;
winOutputSize.height = (RwInt32)480;
winOutputSize.camera = Camera;
RwDeviceControl(rwWINSETOUTPUTSIZE, 0,
&winOutputSize,
sizeof(winOutputSize));
RenderWare's rendering resolution is set by the viewport width and height specified by a call to RwSetCameraViewport(). For example, the following code fragment sets the rendering resolution to 320 by 240 pixels:
RwSetCameraViewport(Camera,
0, 0, 320, 240);
The above code fragments will result in RenderWare rendering at a resolution of 320 by 240 and stretching the result to a rectangle of size 640 by 480 (offset at (0, 0) from the output device’s origin).
The stretching is actually perfomed when RwShowCameraImage() is called to perform software double buffering. The offset from the origin of the device context passed to RwShowCameraImage() of the output is given by the viewport offset specified in the call to RwSetCameraViewport().
There are several important points to consider when bitmap stretching:
case WM_SIZE:
RwSetCameraViewport(Camera, 0, 0,
LOWORD(lParam) / 2,
HIWORD(lParam) / 2);
winOutputSize.width
= LOWORD(lParam);
winOutputSize.height = HIWORD(lParam);
winOutputSize.camera = Camera;
RwDeviceControl(rwWINSETOUTPUTSIZE,
0,
&winOutputSize, sizeof(winOutputSize));
winOutputSize.width
= RwInt32(-1);
winOutputSize.height = RwInt32(-1);
winOutputSize.camera = Camera;
RwDeviceControl(rwWINSETOUTPUTSIZE,
0,
&winOutputSize, sizeof(winOutputSize));
case
WM_LBUTTONDOWN:
{
#if defined(WIN32)
POINTS pos;
pos = MAKEPOINTS(lParam);
#else
POINT pos;
pos = MAKEPOINT(lParam);
#endif
RwPickScene(Scene, pos.x / 2, pos.y / 2,
Camera, &pick);
RenderWare and Windows Palettes
RenderWare maintains its own Windows palette object (HPALETTE). Each time RwShowCameraImage() is called this palette is selected into the specified device context and realized. By default, RenderWare realizes its palette as a foreground palette, i.e., FALSE is passed as the third parameter of SelectPalette(). With RenderWare V2.1 it is possible to change this default and have RenderWare realize its palette as a background palette. This is useful when building applications where RenderWare has to co-exist with other windows which also have their own palettes (particularly MDI applications). In such situations it is not acceptable for the RenderWare window to realize its palette as a foreground palette on each call to RwShowCameraImage(). Instead, RenderWare should realize its palette as a background palette and the application must take responsibility for realizing the RenderWare palette as a foreground palette at the appropriate time, i.e., in response to a WM_QUERYNEWPALETTE message.
To following code instructs RenderWare to realize its palette as a background palette;
RwDeviceControl(rwWINBACKGROUNDPALETTE,
TRUE, NULL, 0L);
If an application uses the above control it is essential that it take responsibility for realizing the RenderWare palette as a foreground palette when the RenderWare window receives the WM_QUERYNEWPALETTE message.
The following code fragment demonstrates this process;
case
WM_QUERYNEWPALETTE:
{
HPALETTE rwPalette;
HPALETTE oldPalette;
HDC dc;
int numChanges;
RwGetDeviceInfo(rwPALETTE, &rwPalette,
sizeof(rwPalette));
dc = GetDC(window);
oldPalette = SelectPalette(dc, rwPalette, TRUE);
numChanges = RealizePalette(dc);
SelectPalette(dc, oldPalette, FALSE);
ReleaseDC(window, dc);
if (numChanges > 0)
InvalidateRect(window, NULL, FALSE);
}
break;
The following code fragment switches RenderWare back to realizing its palette as a foreground palette;
RwDeviceControl(rwWINBACKGROUNDPALETTE,
FALSE, NULL, 0L);
It is possible to determine whether RenderWare is realizing its palette in the foreground and background using the rwWINISBACKGROUNDPALETTE device information type. For example;
RwBool
isBackPal;
RwGetDeviceInfo(rwWINISBACKGROUNDPALETTE, &isBackPal,
sizeof(isBackPal));
if (isBackPal)
{
/* Background palette realization... */
}
else
{
/* Foreground palette realization... */
}
Windows Specific API Function Parameters
A small number of RenderWare API functions have device dependent parameters or return values. The following pages describe these device dependent parameters and return values under Windows.