Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RpWorldSector
[Scene Management]


Data Structures
struct   RpWorldSector

Typedefs
typedef RpWorldSector *(*  RpWorldSectorCallBack )(RpWorldSector *worldSector, void *data)
typedef RpWorldSector *(*  RpWorldSectorCallBackRender )(RpWorldSector *worldSector)

Functions
RwInt32  RpWorldSectorGetNumVertices (const RpWorldSector *sector)
RwInt32  RpWorldSectorGetNumPolygons (const RpWorldSector *sector)
RpWorldSector *  RpWorldSectorRender (RpWorldSector *sector)
const RpWorldSector *  RpWorldSectorForAllMeshes (const RpWorldSector *sector, RpMeshCallBack fpCallBack, void *pData)
const RwBBox *  RpWorldSectorGetBBox (const RpWorldSector *sector)
const RwBBox *  RpWorldSectorGetTightBBox (const RpWorldSector *sector)
RwInt32  RpWorldSectorRegisterPlugin (RwInt32 size, RwUInt32 pluginID, RwPluginObjectConstructor constructCB, RwPluginObjectDestructor destructCB, RwPluginObjectCopy copyCB)
RwInt32  RpWorldSectorRegisterPluginStream (RwUInt32 pluginID, RwPluginDataChunkReadCallBack readCB, RwPluginDataChunkWriteCallBack writeCB, RwPluginDataChunkGetSizeCallBack getSizeCB)
RwInt32  RpWorldSectorSetStreamAlwaysCallBack (RwUInt32 pluginID, RwPluginDataChunkAlwaysCallBack alwaysCB)
RwInt32  RpWorldSectorSetStreamRightsCallBack (RwUInt32 pluginID, RwPluginDataChunkRightsCallBack rightsCB)
RwInt32  RpWorldSectorGetPluginOffset (RwUInt32 pluginID)
RwBool  RpWorldSectorValidatePlugins (const RpWorldSector *sector)
RpWorld *  RpWorldSectorGetWorld (const RpWorldSector *sector)
RpWorldSector *  RpWorldSectorForAllAtomics (RpWorldSector *sector, RpAtomicCallBack callback, void *data)
RpWorldSector *  RpWorldSectorForAllCollisionAtomics (RpWorldSector *sector, RpAtomicCallBack callback, void *data)
RpWorldSector *  RpWorldSectorForAllLights (RpWorldSector *sector, RpLightCallBack callback, void *data)
RpWorldSector *  RpWorldSectorSetPipeline (RpWorldSector *sector, RxPipeline *pipeline)
RpWorldSector *  RpWorldSectorGetPipeline (RpWorldSector *sector, RxPipeline **pipeline)

Detailed Description

Handling atomic sectors

RpWorldSector Overview

Requirements

Overview

World Sectors contain static geometry - if we use a TV studio metaphor, these represent the scenery and sets. These objects are stored using a BSP-tree structure to speed up the rendering process. The World object passes dynamic scene objects, such as Atomics, Cameras and Lights, to World Sectors for storage. For this reason, World Sectors contain iterators which can be used to access such dynamic objects. World Sector geometry data is not expected to change. This opens up more optimization techniques, such as Potentially Visible Sets (available by attaching the RpPVS plugin). The disadvantage is that the geometry data must remain static.

Further information is available in the World & Static Models chapter of the User Guide.

Typedef Documentation

typedef RpWorldSector*(* RpWorldSectorCallBack)(RpWorldSector *worldSector, void *data)
 

RpWorldSectorCallBack represents the function called from RpWorldForAllWorldSectors, RpAtomicForAllWorldSectors and RpLightForAllWorldSectors for all world sectors in a given world or world sectors a given atomic or light lies in. This function should return a pointer to the current world sector to indicate success. The callback may return NULL to terminate further callbacks on the atomic or light.

Parameters:
sector  Pointer to the current world sector
data  Pointer to developer-defined data structure.
Returns:
Pointer to the current world sector.
typedef RpWorldSector*(* RpWorldSectorCallBackRender)(RpWorldSector * worldSector)
 

RpWorldSectorCallBackRender represents the function called from RpWorldSectorRender when the specified world sector lies inside the current camera's view frustum. The default callback initiates execution of the world sector rendering pipeline. This function should return a pointer to the world sector to indicate success

Parameters:
worldSector  Pointer to the world sector to be rendered
Returns:
Pointer to the world sector.

Function Documentation

RpWorldSector* RpWorldSectorForAllAtomics (  RpWorldSector *    sector,
RpAtomicCallBack    callback,
void *    data
) 
 

RpWorldSectorForAllAtomics is used to apply the given callback function to all atomics lying in the specified world sector. The format of the callback function is:

RpAtomic * (*RpAtomicCallBack)(RpAtomic *atomic, void *data);

where data is a user-supplied data pointer to pass to the callback function.

If any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldSectorForAllAtomics will still return successfully.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the sector.
callback  Callback function to be called with each atomic.
data  User data pointer to be passed to the callback.
Returns:
Returns the world sector pointer on success, or NULL on failure.
See also:
RpWorldSectorForAllCollisionAtomics , RpAtomicForAllWorldSectors , RpWorldSectorForAllLights , RpWorldPluginAttach
RpWorldSector* RpWorldSectorForAllCollisionAtomics (  RpWorldSector *    sector,
RpAtomicCallBack    callback,
void *    data
) 
 

RpWorldSectorForAllCollisionAtomics is used to apply the given callback function to all atomics lying in the specified world sector which are marked as collision atomics. This applies to atomics which have their rpATOMICCOLLISIONTEST flag set (see RpAtomicFlag), but note that any change in this flag will not be registered until after the next synchronistion phase during an RwCameraBeginUpdate.

The use of this function is potentially faster than using RpWorldSectorForAllAtomics and testing the collision flag for each atomic.

The format of the callback function is:

RpAtomic * (*RpAtomicCallBack)(RpAtomic *atomic, void *data);

where data is a user-supplied data pointer to pass to the callback function.

If any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldSectorForAllCollisionAtomics will still return successfully.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the sector.
callback  Callback function to be called with each atomic.
data  User data pointer to be passed to the callback.
Returns:
Returns the world sector pointer on success, or NULL on failure.
See also:
RpAtomicSetFlags , RpWorldSectorForAllAtomics , RpAtomicForAllWorldSectors , RpWorldSectorForAllLights , RpWorldPluginAttach
RpWorldSector* RpWorldSectorForAllLights (  RpWorldSector *    sector,
RpLightCallBack    callback,
void *    data
) 
 

RpWorldSectorForAllLights is used to apply the given callback function to all lights lying in the specified world sector. 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.

If any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldSectorForAllLights will still return successfully.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the sector.
callback  Callback function to be called with each light.
data  User data pointer to be passed to the callback.
Returns:
Returns the world sector pointer on success, or NULL on failure.
See also:
RpLightForAllWorldSectors , RpWorldSectorForAllAtomics , RpWorldPluginAttach
const RpWorldSector* RpWorldSectorForAllMeshes (  const RpWorldSector *    sector,
RpMeshCallBack    fpCallBack,
void *    pData
) 
 

RpWorldSectorForAllMeshes is used to apply the given callback function to all meshes in the given world sector. The format of the callback function is:

RpMesh *(*RpMeshCallBack)(RpMesh *mesh, RpMeshHeader *meshHeader, void *data);

where data is a user-supplied data pointer to pass to the callback function.

If any invocation of the callback function returns a failure status the iteration is terminated. However, RpWorldSectorForAllMeshes will still return successfully.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the world sector containing the meshes.
fpCallBack  Pointer to the callback function to apply to each mesh.
pData  Pointer to the user-supplied data to pass to callback function.
Returns:
Returns pointer to the world sector if successful or NULL if there is an error or if the world sector does not have any mesh information.
See also:
RpWorldSectorGetBBox , RpWorldSectorGetNumVertices , RpGeometryForAllMeshes , RpWorldSectorGetNumPolygons , RpWorldSectorGetWorld , RpWorldPluginAttach
const RwBBox* RpWorldSectorGetBBox (  const RpWorldSector *    sector ) 
 

RpWorldSectorGetBBox is used to retrieve the specified world sector's bounding box. This corresponds to the maximum extent of the world sector based on the planes of the BSP tree. The function RpWorldSectorGetTightBBox may be used instead to obtain a bounding box that tightly encloses the geometry in the sector.

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.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns pointer to a RwBBox value if successful or NULL if there is an error.
See also:
RpWorldSectorGetTightBBox , RpWorldSectorForAllMeshes , RpWorldSectorGetNumVertices , RpWorldSectorGetNumPolygons , RpWorldSectorGetWorld , RpWorldGetBBox , RpWorldCreate , RpWorldStreamRead , RpWorldPluginAttach
RwInt32 RpWorldSectorGetNumPolygons (  const RpWorldSector *    sector ) 
 

RpWorldSectorGetNumPolygons is used to retrieve the number of triangles that reside within the specified world sector. Only triangles associated with static geometry are counted.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns a RwInt32 value equal to the number of triangles if successful or zero if there is an error or if there are no triangles.
See also:
RpWorldSectorGetBBox , RpWorldSectorForAllMeshes , RpWorldSectorGetNumVertices , RpWorldSectorGetWorld , RpWorldPluginAttach
RwInt32 RpWorldSectorGetNumVertices (  const RpWorldSector *    sector ) 
 

RpWorldSectorGetNumVertices is used to retrieve the number of vertices that reside within the specified atomic sector. Only vertices associated with static geometry are counted.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns a RwInt32 value equal to the number of vertices if successful or zero if there is an error or if there are no vertices.
See also:
RpWorldSectorGetBBox , RpWorldSectorForAllMeshes , RpWorldSectorGetNumPolygons , RpWorldSectorGetWorld , RpWorldPluginAttach
RpWorldSector* RpWorldSectorGetPipeline (  RpWorldSector *    sector,
RxPipeline **    pipeline
) 
 

RpWorldSectorGetPipeline returns the object pipeline for the specified world sector. 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.

The world sector will use this pipeline, unless it is set to NULL, in which case the current world's pipeline will be used. 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.

Parameters:
sector  Pointer to the world sector.
pipeline  Pointer to receive the pipeline.
Returns:
Returns pointer to the world sector if successful or NULL if there is an error.
See also:
RpAtomicGetGenericPipeline , RpAtomicGetDefaultPipeline , RpAtomicGetDefaultPipeline (platform-specific) , RpAtomicGetPipeline , RpAtomicSetDefaultPipeline , RpAtomicSetPipeline , RpMaterialGetGenericPipeline , RpMaterialGetDefaultPipeline , RpMaterialGetDefaultPipeline (platform-specific) , RpMaterialGetPipeline , RpMaterialSetDefaultPipeline , RpMaterialSetPipeline , RpWorldGetGenericSectorPipeline , RpWorldGetDefaultSectorPipeline , RpWorldGetDefaultSectorPipeline (platform-specific) , RpWorldGetSectorPipeline , RpWorldSectorSetPipeline , RpWorldSetDefaultSectorPipeline , RpWorldSetSectorPipeline
RwInt32 RpWorldSectorGetPluginOffset (  RwUInt32    pluginID ) 
 

RpWorldSectorGetPluginOffset is used to get the offset of a previously registered world sector plugin.

The world plugin must be attached before using this function.

Parameters:
pluginID  A RwUInt32 value equal to the plugin ID.
Returns:
Returns the data block offset if successful or -1 if the plugin is not registered.
See also:
RpWorldSectorRegisterPlugin , RpWorldSectorRegisterPluginStream , RpWorldSectorSetStreamAlwaysCallBack , RpWorldSectorValidatePlugins , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldGetPluginOffset , RpWorldValidatePlugins , RpWorldPluginAttach
const RwBBox* RpWorldSectorGetTightBBox (  const RpWorldSector *    sector ) 
 

RpWorldSectorGetTightBBox is used to retrieve the tight bounding box of the specified world sector. This tightly encloses the geometry of the sector. Use RpWorldSectorGetBBox to retrieve the outer bounding box that extends to the BSP planes. For space filling (empty) sectors, both functions return the full extent.

Atomics and other objects in the world sector may or may not lie within the tight bounding box.

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.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns pointer to a RwBBox value if successful or NULL if there is an error.
See also:
RpWorldSectorGetBBox , RpWorldGetBBox , RpWorldCreate , RpWorldStreamRead , RpWorldPluginAttach
RpWorld* RpWorldSectorGetWorld (  const RpWorldSector *    sector ) 
 

RpWorldSectorGetWorld is used to retrieve the specified world sector's parent world. Use this function to determine the world that contains the world sector.

The world plugin must be attached before using this function.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns pointer to the world if successful or NULL if there is an error.
See also:
RpWorldSectorGetBBox , RpWorldSectorForAllMeshes , RpWorldSectorGetNumVertices , RpWorldSectorGetNumPolygons , RpWorldPluginAttach
RwInt32 RpWorldSectorRegisterPlugin (  RwInt32    size,
RwUInt32    pluginID,
RwPluginObjectConstructor    constructCB,
RwPluginObjectDestructor    destructCB,
RwPluginObjectCopy    copyCB
) 
 

RpWorldSectorRegisterPlugin is used to register a plugin and reserve some space within a world sector. 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.

Parameters:
size  A RwInt32 value equal to the size of the memory block to reserve.
pluginID  A RwInt32 value equal to the plugin ID (must be unique; used to identify binary chunks).
constructCB  Constructor for the plugin data block.
destructCB  Destructor for the plugin data block.
copyCB  Copy constructor for the plugin data block.
Returns:
Returns RwInt32 value equal to the byte offset within the world sector of memory reserved for this plugin if successful or -1 if there is an error.
See also:
RpWorldSectorValidatePlugins , RpWorldSectorRegisterPluginStream , RpWorldSectorSetStreamAlwaysCallBack , RpWorldSectorGetPluginOffset , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldValidatePlugins , RpWorldGetPluginOffset , RpWorldPluginAttach
RwInt32 RpWorldSectorRegisterPluginStream (  RwUInt32    pluginID,
RwPluginDataChunkReadCallBack    readCB,
RwPluginDataChunkWriteCallBack    writeCB,
RwPluginDataChunkGetSizeCallBack    getSizeCB
) 
 

RpWorldSectorRegisterPluginStream is used to associate a set of binary stream functionality with a previously registered world sector plugin.

The world plugin must be attached before using this function.

Parameters:
pluginID  A RwInt32 value equal to the plugin ID (must be unique; used to identify binary chunks).
readCB  Callback used when a chunk is read that is identified as being for this plugin.
writeCB  Callback used when a chunk should be written out for this plugin.
getSizeCB  Callback used to determine the binary stream size required for this plugin (return negative to suppress chunk writing).
Returns:
Returns a RwInt32 value equal to the byte offset within the world sector of memory reserved for this plugin if successful or -1 if there is an error.
See also:
RpWorldSectorSetStreamAlwaysCallBack , RpWorldSectorValidatePlugins , RpWorldSectorRegisterPlugin , RpWorldSectorGetPluginOffset , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldGetPluginOffset , RpWorldValidatePlugins , RpWorldPluginAttach
RpWorldSector* RpWorldSectorRender (  RpWorldSector *    sector ) 
 

RpWorldSectorRender is used to render all static objects in the specified world sector to the current camera's image raster.

Note 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.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns pointer to the world sector if successful or NULL if there is an error.
See also:
RwCameraBeginUpdate , RwCameraEndUpdate , RpWorldSetSectorRenderCallBack , RpWorldGetSectorRenderCallBack , RpWorldRender , RpClumpRender , RpAtomicRender , RpWorldPluginAttach
RpWorldSector* RpWorldSectorSetPipeline (  RpWorldSector *    sector,
RxPipeline *    pipeline
) 
 

RpWorldSectorSetPipeline defines the object pipeline for the specified world sector. 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.

The world sector will use this pipeline, unless it is set to NULL, in which case the current world's pipeline will be used. 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.

Parameters:
sector  Pointer to the world sector.
pipeline  Pointer to the pipeline.
Returns:
Returns pointer to the world sector if successful or NULL if there is an error.
See also:
RpAtomicGetGenericPipeline , RpAtomicGetDefaultPipeline , RpAtomicGetDefaultPipeline (platform-specific) , RpAtomicGetPipeline , RpAtomicSetDefaultPipeline , RpAtomicSetPipeline , RpMaterialGetGenericPipeline , RpMaterialGetDefaultPipeline , RpMaterialGetDefaultPipeline (platform-specific) , RpMaterialSetDefaultPipeline , RpMaterialSetPipeline , RpWorldGetGenericSectorPipeline , RpWorldGetDefaultSectorPipeline , RpWorldGetDefaultSectorPipeline (platform-specific) , RpWorldGetSectorPipeline , RpWorldSectorGetPipeline , RpWorldSetDefaultSectorPipeline , RpWorldSetSectorPipeline
RwInt32 RpWorldSectorSetStreamAlwaysCallBack (  RwUInt32    pluginID,
RwPluginDataChunkAlwaysCallBack    alwaysCB
) 
 

RpWorldSectorSetStreamAlwaysCallBack is used to associate a binary stream callback with a previously registered world sector plugin. This callback is called for all plugins after stream data reading has completed.

The world plugin must be attached before using this function.

Parameters:
pluginID  A RwInt32 value equal to the plugin ID (must be unique; used to identify binary chunks).
alwaysCB  Callback used when object base and plugin data reading is complete.
Returns:
Returns a RwInt32 value equal to the byte offset within the world sector of memory reserved for this plugin if successful or -1 if there is an error.
See also:
RpWorldSectorRegisterPluginStream , RpWorldSectorValidatePlugins , RpWorldSectorRegisterPlugin , RpWorldSectorGetPluginOffset , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldGetPluginOffset , RpWorldValidatePlugins , RpWorldPluginAttach
RwInt32 RpWorldSectorSetStreamRightsCallBack (  RwUInt32    pluginID,
RwPluginDataChunkRightsCallBack    rightsCB
) 
 

RpWorldSectorSetStreamRightsCallBack is used to associate a binary stream callback with a previously registered world sector 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.

Parameters:
pluginID  A RwInt32 value equal to the plugin ID (must be unique; used to identify binary chunks).
rightsCB  Callback used when object base and plugin data reading is complete.
Returns:
Returns a RwInt32 value equal to the byte offset within the world sector of memory reserved for this plugin if successful or -1 if there is an error.
See also:
RpWorldSectorRegisterPluginStream , RpWorldSectorValidatePlugins , RpWorldSectorRegisterPlugin , RpWorldSectorGetPluginOffset , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldGetPluginOffset , RpWorldValidatePlugins , RpWorldPluginAttach
RwBool RpWorldSectorValidatePlugins (  const RpWorldSector *    sector ) 
 

RpWorldSectorValidatePlugins is used to validate the plugin memory allocated within the specified world sector. 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.

Parameters:
sector  Pointer to the world sector.
Returns:
Returns TRUE if the world sector data is valid or FALSE if there is an error or if the world sector data has become corrupt.
See also:
RpWorldSectorRegisterPlugin , RpWorldSectorRegisterPluginStream , RpWorldSectorSetStreamAlwaysCallBack , RpWorldSectorGetPluginOffset , RpWorldRegisterPlugin , RpWorldRegisterPluginStream , RpWorldSetStreamAlwaysCallBack , RpWorldValidatePlugins , RpWorldGetPluginOffset , RpWorldPluginAttach
Criterion Software © 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)