Main Page Modules Alphabetical List Data Structures Data Fields

RtTileRender
[Cameras]


Functions
RwCamera *	RtTileRender (RwCamera camera, RwInt32 imageWidth, RwInt32 imageHeight, RwInt32 tileWidth, RwInt32 tileHeight, RtTileRenderCallBack renderCallBack, RtTileArchiveCallBack archiveCallBack, void pData)
RwImage *	RtTileDefaultArchive (RwImage image, RwInt32 x, RwInt32 y, void pData)

Detailed Description

Tile renderer - e.g. grabbing screen shots - Toolkit for RenderWare.

RtTile Toolkit Overview

Requirements

Headers: rwcore.h, rpworld.h, rttilerd.h
Libraries: rwcore, rpworld, rttilerd
Plugin attachments: RpWorldPluginAttach

Overview

This Toolkit provides a facility for rendering large, high-resolution scenes on systems without the available video and system memory required to handle such resolutions.

By allowing a scene to be split into sections -- or tiles -- and rendered one row of tiles at a time, the memory overheads can be dramatically reduced when rendering for high-resolution targets such as printed media. (Eg: creating screenshots for magazines.)

The developer can specify the number of tiles to split the rendered scene into, as well as supply replacement callback functions for both rendering and serialization.

Function Documentation

RwImage* RtTileDefaultArchive	(	RwImage *	image,
		RwInt32	x,
		RwInt32	y,
		void *	pData
	)

RtTileDefaultArchive is the default archiving function when used in conjunction with RtTileRender.

The default archiver accumulates the renderings for a complete line of tiles (spanning the output image width) before writing the results to the output file. This enables an application to produce very high resolution images without requiring very high amounts of memory.

The include file rttilerd.h and the library file rttilerd.lib are required to use this function. The library file rpworld.lib is also required.

Parameters:

image	Pointer to the image.
x	A RwInt32 value equal to the horizontal index of the tile (left-most tiles have index zero).
y	A RwInt32 value equal to the vertical index of the tile (top-most tiles have index zero).
pData	User-data pointer to pass to archive callback.

Returns:: a pointer to the tile's image if successful or NULL if there is an error.

See also:: RtTileRender

RwCamera* RtTileRender	(	RwCamera *	camera,
		RwInt32	iWidth,
		RwInt32	iHeight,
		RwInt32	tWidth,
		RwInt32	tHeight,
		RtTileRenderCallBack	renderCallBack,
		RtTileArchiveCallBack	archiveCallBack,
		void *	pData
	)

RtTileRender is used to perform tile rendering using the specified camera. The resulting image's dimensions are arbitrary but must be an exact muliple of the tile's size. Furthermore, the tile's size must not exceed the camera raster's dimensions.

This function requires the specification of two callback functions: the render callback specifies the function that will do the rendering for each tile; the archive callback specifies the function that will save the results of each rendered tile. Both callbacks must be set. There is a default archive callback provided, RtTileDefaultArchive, for saving images. A default render callback is not provided because it is too application specific.

The render callback should return a pointer to the camera to indicate success; return NULL to indicate an error has occurred - this will cause the tile rendering to be aborted. Similarly, the archive callback should return a pointer to the tile image if successful or NULL if there is an error which, again, will cause the tile rendering to be prematurely terminated.

An example of render callback would be

    RwCamera *
    RtTileDefaultRender(RwCamera * camera,
                        RwInt32 x,
                        RwInt32  y,
                        void * pData)
    {
        RwRGBA bkcol;

        bkcol.red = 0;
        bkcol.green = 128;
        bkcol.blue = 255;
        bkcol.alpha = 255;

        RwCameraClear(camera, &bkcol,
                    (rwCAMERACLEARIMAGE | rwCAMERACLEARZ));

        if (RwCameraBeginUpdate(camera))
        {
            RpWorldRender(RwCameraGetWorld(camera));

            RwCameraEndUpdate(camera);
        }

        return camera;
    }

The user-data pointer can be used to pass data to the callbacks. If the default archive callback is used, a pointer to a string containing the name of the output image filename (with .ras extension) should be specified.