This is the 'master' object for RenderWare Graphics' Retained Mode API. It has a number of purposes:
When rendering a World, using RpWorldRender, the World plugin traverses the BSP tree, rendering visible World Sectors as it does so. As each World Sector is rendered, the plugin also renders any dynamic scene objects that have been added to it too, resulting in the rendering of a complete scene.
Further information is available in the World & Static Models chapter of the User Guide.
|
|
The bit-field type RpWorldFlag specifies the options available for creating the static geometry component of a world (see API function RpWorldSetFlags):
|
|
|
RpWorldRenderOrder represents the options available for the rendering order of world sectors in the camera's view frustum (see API function RpWorldSetRenderOrder). |
|
||||||||||||
|
RpTieSetFreeListCreateParams allows the developer to specify how many RpTie s to preallocate space for. Call before RwEngineInit.
|
|
||||||||||||
|
RpWorldAddAtomic is used to add the specified atomic to the given world. Atomics must be added to a world if they are to be rendered using RpWorldRender or be illuminated by point, spot or soft spot lights. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldAddCamera is used to add the specified camera to the given world. Cameras must be added to a world before they can be used to render objects. This function is a world plugin extension and the world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldAddClump is used to add the specified clump to the given world. Clumps must be added to a world if they are to be rendered using RpWorldRender or be illuminated by point, spot or soft spot lights. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldAddLight is used to add the specified light to the given world. Lights must be added to a world if they are to illuminate objects. Otherwise, they will not contribute to any rendering that takes place. The world plugin must be attached before using this function.
|
|
|
RpWorldCreate is used to create a new world which has the specified bounding box. The newly created world contains no objects (static or otherwise) and one world sector covering the whole of the bounding box. The world plugin must be attached before using this function.
|
|
|
RpWorldDestroy is used to destroy the specified world. Only those parts of the world contained in static objects are destroyed. Other objects such as clumps, cameras and lights are not destroyed and it is recommended that they are removed from the world before calling this function. If necessary, non-static objects can then be destroyed using the appropriate functions. The world plugin must be attached before using this function.
|
|
||||||||||||||||
|
RpWorldForAllClumps is used to apply the given callback function to all clumps in the specified world. The format of the callback function is: RpClump * (*RpClumpCallBack)(RpClump *clump, void *data) where data is a user-supplied data pointer to pass to the callback function. Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldForAllClumps will still return successfully. The world plugin must be attached before using this function.
|
|
||||||||||||||||
|
RpWorldForAllLights is used to apply the given callback function to all lights in the specified world. The format of the callback function is: RpLight * (*RpLightCallBack)(RpLight *light, void *data) where data is a user-supplied data pointer to pass to the callback function. Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldForAllLights will still return successfully. The world plugin must be attached before using this function.
|
|
||||||||||||||||
|
RpWorldForAllMaterials is used to apply the given callback function to all materials used by static objects in the specified world. The format of the callback function is: RpMaterial * (*RpMaterialCallBack)(RpMaterial *material, void *data) where data is a user-supplied data pointer to pass to the callback function. Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldForAllMaterials will still return successfully. The world plugin must be attached before using this function.
|
|
||||||||||||||||
|
RpWorldForAllWorldSectors is used to apply the given callback function to all world sectors in the specified world. The format of the callback function is: RpWorldSector * (*RpWorldSectorCallBack)(RpWorldSector *worldSector, void *data); where data is a user-supplied data pointer to pass to the callback function. Note that if any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldForAllWorldSectors will still return successfully. The world plugin must be attached before using this function.
|
|
|
RpWorldGetBBox is used to retrieve the specified world's bounding box. Use this function to determine the actual bounding box of the world which will differ from that specified at creation time. For efficiency reasons the bounding box is translated such that all coordinates within it are positive. The world's offset, describing the extent of the translation, can be used to bring objects defined relative to the original bounding box into the bounding box actually used. Note the world offset is fixed at the time the world is created and describes the translation required to move the world's bounding box back to its original position. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetDefaultSectorPipeline retrieves the global default world sector object pipeline. The pipeline is executed from the default sector render callback, and indirectly from RpWorldSectorRender and RpWorldRender) when a world sector enters the current camera's view frustum. World sectors will use their specified pipeline, unless it is set to NULL, in which case they will use their world's specified pipeline. If the world's pipeline is set to NULL then the global default world sector pipeline will be used. The generic form of the default world-sector object pipeline is detailed in RpWorldGetGenericSectorPipeline and platform-specific versions in RpWorldGetDefaultSectorPipeline (platform-specific) Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetFlags is used to retrieve the property flags from the specified world. The flags only pertain to the static component of the world's geometry. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldGetMaterial is used to retrieve the material with the given index from the specified world's material list. The material list only includes materials used by static surfaces in the world. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetNumClumps is used to retrieve the number of clumps in the specified world. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetNumMaterials is used to retrieve the number of different materials in use by all static surfaces in the specified world. Materials which are not referenced by static surfaces are not counted. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetPluginOffset is used to get the offset of a previously registered world plugin. The world plugin must be attached before using this function.
|
|
|
RpWorldGetRenderOrder is used to retrieve the order in which world sectors in the specified world are rendered with respect to the camera's frustum, which can be either front to back or back to front. Back to front produces the correct results with respect to alpha blending at low memory cost but can lead to higher frame-buffer bandwidth requirements. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldGetSectorPipeline returns the default world sector object pipeline for the specified world. The pipeline is executed from the default render callback and indirectly from RpWorldSectorRender and RpWorldRender) when a world sector enters the current camera's view frustum. World sectors in the current world will use this pipeline by default, unless they have their own pipeline specified. If the world's pipeline is NULL, this signifies that the global default world sector pipeline will be used. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
|
RpWorldGetSectorRenderCallBack is used to retrieve the world sector render callback function of the specified world. The render callback is the function that is executed from RpWorldSectorRender (and indirectly from RpWorldRender) when a world sector lies inside the current camera's view frustum, giving the application the opportunity to alter the way in which static objects in the world sector are rendered. The format of the callback function is: RpWorldSector * (*RpWorldSectorCallBackRender)(RpWorldSector *sect) The world plugin must be attached before using this function.
|
|
|
RpWorldInstance is used to instance a world outside of the resource arena. This means that the world will never be instanced again. Once this function has been called two representations of the world will exist, one platform independent (PI) and one platform specific (PS). If the world is serialized, using RpWorldStreamWrite after RpWorldInstance has been called, only the PS representation will be saved. When the world is reloaded, using RpWorldStreamRead, only the PS representation will exist. This data can only be loaded and used on the platform it was created on. All PI geometry data will be lost so certain things will no longer work. For example, collision detection will not work as this relies on a PI data. A second low resolution collision world can be used to solve this problem. The number of vertices in a world sector RpWorldSectorGetNumVertices and the number of polygons RpWorldSectorGetNumPolygons are preserved. Meshes RpMesh are also preserved but the indices themselves are not present. The correct rendering pipelines must be attached to the world sector and materials before this function is called as those rendering pipelines may introduce PS data that is required to give the desired rendering effect. Pre-instancing should not be attempted when PVS is enabled. PVS should be disabled as world sectors are not pre-instanced, if culled by PVS. This function must be called between RwCameraBeginUpdate and RwCameraEndUpdate as this function has to execute the rendering pipelines to guarantee that all the needed data is generated. In essence this function behaves exactly like RpWorldRender, the only difference being that the instance data does not get created in the resource arena but is allocated from the heap and is therefore persistent. All world sectors will be processed and instanced even if they are not inside the camera frustum. For example:
RpWorldAddCamera(World, Camera);
if (RwCameraBeginUpdate(Camera))
{
RpWorldInstance(World);
RwCameraEndUpdate(Camera);
}
RpWorldRemoveCamera(World, Camera);
The world plugin must be attached before using this function.
|
|
|
RpWorldLock is used to lock the specified world so an application can access it's internal data structures. After the data has been modified the world should be unlocked so that the meshes can be rebuilt. When the world is locked the present meshes are destroyed. The world plugin must be attached before using this function.
|
|
|
RpWorldPluginAttach is used to attach the world plugin to the RenderWare system to enable scene management. The world plugin must be attached between initialising the system with RwEngineInit and opening it with RwEngineOpen. Use this function if the application wishes to use the following system functionality: worlds and world sectors, clumps, atomics, geometry, lights, materials. The include file rpworld.h is also required and must be included by an application wishing to use scene management
|
|
||||||||||||||||||||||||
|
RpWorldRegisterPlugin is used to register a plugin and reserve some space within a world. This must happen after the engine has been initialized but before the engine is opened. The world plugin must be attached before using this function.
|
|
||||||||||||||||||||
|
RpWorldRegisterPluginStream is used to associate a set of binary stream functionality with a previously registered world plugin. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldRemoveAtomic is used to remove the specified atomic from the given world. Unlike RpAtomicDestroy this function preserves the atomic's definition, hence the atomic can be reused without creating it again. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldRemoveCamera is used to remove the specified camera from the given world. Unlike RwCameraDestroy this function preserves the camera's definition, hence the camera can be reused without creating it again. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldRemoveClump is used to remove the specified clump from the given world. Unlike RpClumpDestroy this function preserves the clump's definition, hence the clump can be reused without creating it again. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldRemoveLight is used to remove the specified light from the given world. Unlike RpLightDestroy this function preserves the light's definition, hence the light can be reused without creating it again. The world plugin must be attached before using this function.
|
|
|
RpWorldRender is used to render all objects (static or otherwise) in the specified world to the current camera's image raster. Only objects that have been added to the world will be rendered. RpWorldRender is used to render both world sectors and atomics, but only those that fall inside the current camera's view frustum will be rendered. This function should only be called between RwCameraBeginUpdate and RwCameraEndUpdate to ensure that any rendering that takes place is directed towards an image raster connected to a camera. The world plugin must be attached before using this function.
|
|
|
RpWorldSetDefaultSectorPipeline defines the global default world sector object pipeline. The pipeline is executed from the default render callback, unless overridden by a non-NULL world sector's pipeline or world's pipeline, and indirectly from RpWorldSectorRender and RpWorldRender) when a world sector enters the current camera's view frustum, giving the application the opportunity to alter the way in which static objects in the world sector are rendered. If the parameter is NULL then the default world sector object pipeline will be reinstated (this is platform-specific). World sectors will use their specified pipeline, unless it is set to NULL, in which case they will use their world's specified pipeline.. If the world's pipeline is set to NULL then the global default world sector pipeline will be used. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetFlags is used to define the property flags for the specified world. The flags only pertain to the static component of the world's geometry. Note that this function replaces existing flags with the new ones, hence any previously set flags are lost. Therefore, if any of the old flags are still required they must be set again with this function. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetRenderOrder is used to set the order in which world sectors in the specified world are rendered with respect to the camera's frustum, which can be either front to back or back to front. On rendering a world sector, the contained atomics will not be sorted for rendering. If atomics contains transparencies, it is best to render them separately.. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetSectorPipeline defines the default world sector object pipeline for the specified world. The pipeline is executed from the default render callback and indirectly from RpWorldSectorRender and RpWorldRender) when a world sector enters the current camera's view frustum, giving the application the opportunity to alter the way in which static objects in the world sector are rendered. World sectors in the current world will use this pipeline by default, unless they have their own pipeline specified. If the world's pipeline is set to NULL then the global default world sector pipeline will be used. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetSectorRenderCallBack is used to define the world sector render callback function for the specified world. The callback function is executed from RpWorldSectorRender (and indirectly from RpWorldRender) when a world sector lies inside the current camera's view frustum, giving the application the opportunity to alter the way in which static objects in the world sector are rendered. The default callback function will invoke the world rendering pipeline. The default function can be reinstated by specifying NULL in the callback function parameter. The format of the callback function is: RpWorldSector * (*RpWorldSectorCallBackRender)(RpWorldSector *sect) The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetStreamAlwaysCallBack is used to associate a binary stream callback with a previously registered world plugin. This callback is called for all plugins after stream data reading has completed. The world plugin must be attached before using this function.
|
|
||||||||||||
|
RpWorldSetStreamRightsCallBack is used to associate a binary stream callback with a previously registered world plugin. This callback is called for the plugin with rights after stream data reading has completed. The world plugin must be attached before using this function.
|
|
|
RpWorldStreamGetSize is used to determine the size in bytes of the binary representation of the given world. Only static objects in the world are included. This is used in the binary chunk header to indicate the size of the chunk. The size does not include the size of the chunk header. The world plugin must be attached before using this function.
|
|
|
RpWorldStreamRead is used to read a world from the specified binary stream. Note that prior to this function call a binary world chunk must be found in the stream using the RwStreamFindChunk API function. Note also that the world created by this function only contains static objects. The world plugin must be attached before using this function. The sequence to locate and read a world from a binary stream is as follows: RwStream *stream; RpWorld *newWorld; stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx"); if( stream ) { if( RwStreamFindChunk(stream, rwID_WORLD, NULL, NULL) ) { newWorld = RpWorldStreamRead(stream); } RwStreamClose(stream, NULL); }
|
|
||||||||||||
|
RpWorldStreamWrite is used to write the specified world to the given binary stream. Only those parts of the world contained in static objects are written to the stream. Note that the stream must be opened prior to this function call. The world plugin must be attached before using this function. For example:
RwStream *streamOut;
RpWorld *worldOut;
// Write object
streamOut = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMWRITE, "world.rws");
RpWorldStreamWrite(worldOut, streamOut);
RwStreamClose(streamOut, NULL);
|
|
|
RpWorldUnlock is used to unlock the specified world. This function releases the world's data structures after modification so that the world's meshes can be rebuilt. The world plugin must be attached before using this function.
|
|
|
RpWorldValidatePlugins is used to validate the plugin memory allocated within the specified world. This function is useful for determining where memory trampling may be occuring within an application. This function only returns a meaningful response under a debug library. The world plugin must be attached before using this function.
|
© 1993-2003 Criterion Software Limited. All
rights reserved. Built Tue Apr 22 12:46:19 2003. Send Feedback
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |