The include file rwlib.h contains the prototypes for all RenderWare API functions. Any application program exploiting RenderWare should include this include file.
There are three other important include files: rwtypes.h, rwmacros.h and rwerrors.h. rwtypes.h contains the declarations of RenderWare’s data types; rwmacros.h contains macro functions for fixed-point arithmetic and rwerrors.h contains the RenderWare error codes. Each of these files is included by rwlib.h, there is no need to explicitly include them.
The first and last RenderWare API functions called by an application program must be RwOpen() (or its variant RwOpenExt()) and RwClose() respectively.
A typical RenderWare application:
Each of these tasks is discussed in more detail below. Code fragments are given to illustrate each operation. These code fragments are sections of a floating-point, RenderWare application targeted at the Microsoft Windows 3.1 operating system.
The code fragments are from a program which displays a clump read from a script file.
For the sake of clarity the following code fragments omit the various macros necessary for compatibility with the fixed-point RenderWare libraries. Furthermore, variable declarations and some error checking have been omitted.
Initializing the Library
RwOpen() initializes the library for a particular output device.
if
(RwOpen("MSWindows", NULL))
{
/*
* Since the return value was non-zero,
* the application can continue...
*/
Creating and Initializing a Camera
A new camera can be created with RwCreateCamera(). This requires the maximum width and height of the camera’s viewport and a device-specific parameter as its arguments:
cam =
RwCreateCamera(320, 200, NULL);
if (cam)
{
/*
* As NULL was not returned the call
* was successful and the application can
* continue...
*/
The above code fragment creates a camera cam with a maximum viewport size of 320 by 200 pixels.
By default, the camera is positioned at the origin of world space, looking down the world space Z axis in the direction of decreasing Z. The camera has a view window of 1.0 unit by 1.0 unit and has a viewport background color of black (0.0, 0.0, 0.0). The default projection model is perspective.
To move the camera back 10.0 units down the Z axis from its initial position:
RwVCMoveCamera(cam,
0.0, 0.0, -10.0);
Important Note:
By default, the camera’s viewport has a width and height of
zero. The application program must explicitly set the viewport of
each new camera to a non-zero width and height. This viewport
should be set with the API function RwSetCameraViewport()
as soon as the desired size is established.
The following code fragment sets the camera’s viewport in response to a WM_SIZE message from MS Windows:
case WM_SIZE:
width = LOWORD(lParam);
height = HIWORD(lParam);
RwSetCameraViewport(cam, 0, 0, width, height);
Creating a Scene
RwOpen() creates a scene (the default scene) which holds all clumps and lights when they are first created. The default scene can be viewed and rendered with a camera in the same way as any other scene. However, it is recommended that an application creates a specific scene for rendering and only uses the default scene to hold currently unused clumps and lights.
if (scene =
RwCreateScene())
{
/*
* Since NULL was not returned,
* the call was successful and the
* application can continue...
*/
Creating a Light Source and adding it to a Scene
A light source is created by calling RwCreateLight().
if (light =
RwCreateLight(rwPOINT,
0.0, 10.0, 0.0, 1.0))
{
/*
* Since NULL was not returned,
* the call was successful and the
* application can continue...
*/
The above code fragment creates a point light source of maximum brightness (1.0) positioned at (0.0, 10.0, 0.0) in world space.
To add the light to the scene:
RwAddLightToScene(scene,
light);
Creating a Clump and adding it to a Scene
A clump is read from a RenderWare script file as follows:
ball =
RwReadShape("ball.rwx");
if (ball)
{
/*
* Since NULL was not returned,
* the call was successful and the
* application can continue...
*/
If the application wishes to replace the surface properties of the clump defined in the script file it can do so via the RenderWare API functions which deal with polygons and materials:
RwForAllPolygonsInClumpInt(ball,
RwSetPolygonGeometrySampling, rwSOLID);
RwForAllPolygonsInClumpInt(ball,
RwSetPolygonLightSampling, rwVERTEX);
RwForAllPolygonsInClumpReal(ball,
RwSetPolygonAmbient, 0.7);
color.r = 1.0;
color.g = 0.0;
color.b = 1.0;
RwForAllPolygonsInClumpPointer(ball,
RwSetPolygonColorStruct, &color);
The above code fragment sets the geometry sampling type, light sampling type, ambient reflection coefficient, and color of all the clump’s polygons.
To add the clump to the scene:
RwAddClumpToScene(scene,
ball);
Rendering a Scene
At some point, the application must render the scene and display the results of that rendering. Under Windows the application may do this in response to a WM_PAINT message:
case
WM_PAINT:
hdc = BeginPaint(window, &ps);
RwBeginCameraUpdate(cam, (void *)window);
RwClearCameraViewport(cam);
RwRenderScene(scene);
RwEndCameraUpdate(cam);
RwShowCameraImage(cam, (void *)hdc);
EndPaint(window, &ps);
Closing the Library
Finally, when all rendering is complete, the RenderWare library is closed:
RwClose();