Main Page Modules Alphabetical List Data Structures Data Fields

RpPVS
[PVS]


Typedefs
typedef RwBool(*	RpPVSProgressCallBack )(RwInt32 msg, RwReal value)
typedef RpWorldSector (	RpPVSCallBack )(RpWorldSector worldSector, const RwBBox box, void *pData)
Functions
RwBool	RpPVSSetCollisionDetection (RwBool collis)
RwBool	RpPVSSetBackFaceCulling (RwBool bfc)
RpWorldSector *	RpPVSGeneric (RpWorldSector spSect, const RwBBox box, void *data)
RpWorldSector *	RpPVSSetViewPosition (RpWorld wpWorld, RwV3d pos)
RpWorldSector *	RpPVSSetViewSector (RpWorld wpWorld, RpWorldSector spSect)
RwBool	RpPVSWorldSectorVisible (RpWorldSector *spSect)
RpWorldSector *	RpPVSSetWorldSectorVisibility (RpWorldSector *spSect, RwBool visible)
RpWorldSector *	RpPVSSetWorldSectorPairedVisibility (RpWorldSector spSectA, RpWorldSector spSectB, RwBool visible, RwBool mutual)
RpWorld *	RpPVSConstruct (RpWorld wpWorld, RpPVSCallBack callback, void pData)
RpWorld *	RpPVSConstructSector (RpWorld wpWorld, RpWorldSector spSector, RpPVSCallBack callback, void *pData)
RwBool	RpPVSSamplePOV (RwV3d *pos, RwBool colltest)
RpWorld *	RpPVSDestroy (RpWorld *wpWorld)
RpWorld *	RpPVSHook (RpWorld *wpWorld)
RpWorld *	RpPVSUnhook (RpWorld *wpWorld)
RpPVSProgressCallBack	RpPVSGetProgressCallBack (RpWorld *wpWorld)
RpWorld *	RpPVSSetProgressCallBack (RpWorld *wpWorld, RpPVSProgressCallBack callback)
RwBool	RpPVSPluginAttach (void)
RwBool	RpPVSQuery (RpWorld *wpWorld)
RwBool	RpPVSAtomicVisible (RpAtomic *atom)
RpWorld *	RpPVSStatisticsGet (RpWorld wpWorld, RwInt32 ptotal, RwInt32 *paccept)
RxNodeDefinition *	RxNodeDefinitionGetPVSWorldSectorCSL (void)

Detailed Description

Geometric Potentially Visible Set Plugin for RenderWare Graphics.

RpPVS Plugin Overview

Requirements

Headers: rwcore.h, rpworld.h, rpcollis.h, rppvs.h
Libraries: rwcore, rpworld, rtintsec, rpcollis, rppvs
Plugin attachments: RpWorldPluginAttach, RpCollisionPluginAttach RpPVSPluginAttach

The RpPVS plugin extends the RenderWare Graphics API to support optimization of BSP world rendering using a custom Potentially Visible Sets algorithm. Under the right conditions, this algorithm can dramatically reduce the time taken to render a large 3D model, such as a level for a game.

This plugin supports both ends of the PVS process: you can use it to create PVS data as well as to accelerate rendering using the results.

Potentially Visible Sets processing is usually applied to large 3D models, such as one of a large building, where only a small portion is ever expected to be visible at any one time. In use, the application developer tells the plugin to check a number of points within an RpWorld and determine which RpWorldSector objects are visible from each location. When this process is completed, the rendering engine can easily determine which RpWorldSector objects are to be rendered at any location.

The format of PVS data has changed since release 3.10. SDK-tools pvscnvrt can be used to convert from old-style to new-style PVS data. It can also be used to delete, generate and enhance PVS data.

Typedef Documentation

typedef RpWorldSector*(* RpPVSCallBack)(RpWorldSector * worldSector, const RwBBox * box, void *pData)

RpPVSCallBack This typedef sets the callback function for sampling within a world sector.

Parameters:

worldSector	A pointer to the RpWorldSector being sampled.
box	The bounding box of the region being sampled.
pData	A pointer to private data for the sampling function.

typedef RwBool(* RpPVSProgressCallBack)(RwInt32 msg, RwReal value)

RpPVSProgressCallBack This typedef sets the callback function for sampling within a world sector.

Parameters:

value	A value between 0.0 and 100.0 to represent the percentage completion.
msg	The message may take one of the following:

rpPVSPROGRESSSTART The PVS creation process is about to start. The argument value is equal to 0.0.

rpPVSPROGRESSUPDATE The PVS creation process has finished processing a subsection of the world. The argument value is equal to the percentage of the world processed up to this point.

rpPVSPROGRESSEND The PVS creation process has ended. All world sectors have been processed. The argument value is equal to 100.0.

The progress callback may return FALSE to indicate that the generation of PVS data should terminate. Otherwise, return TRUE to continue.

The PVS plugin must be attached before using this function.

Function Documentation

RwBool RpPVSAtomicVisible

(

RpAtomic *

atom

)

RpPVSAtomicVisible is used to determine if the atomic is visible from the current visibility map.

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

Parameters:

atom

A pointer to a RpAtomic.

Returns:: TRUE if visible, FALSE otherwise.

See also:: RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorld* RpPVSConstruct	(	RpWorld *	wpWorld,
		RpPVSCallBack	callback,
		void *	pData
	)

RpPVSConstruct is used to create Potential Visibility Set, PVS, for the world. The PVS is created by taking samples within each world sector to build a visibility map. This map indicates which other world sectors are visible from within its boundary.

The RpPVSCallBack callback function is used for sampling within a world sector. This can be RpPVSGeneric or a user own private function for specific samples distribution.

Note:: If this function is called more than once, the world should have collision data. This is for reasons of efficiency.

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

Parameters:

wpWorld	A pointer to a RpWorld with PVS.
callback	A pointer to the RpPVSCallBack function for sampling a world sector.
pData	A pointer to private data for the callback.

Returns:: RpWorld if successful or NULL if there is an error.

See also:: RpPVSSetWorldSectorVisibility , RpPVSGeneric , RpPVSSamplePOV

RpWorld* RpPVSConstructSector	(	RpWorld *	wpWorld,
		RpWorldSector *	spSector,
		RpPVSCallBack	callback,
		void *	pData
	)

RpPVSConstructSector is used to create Potential Visibility Set, PVS, for the given world sector. The PVS is created by taking samples within the world sector to build a visibility map. This map indicates which other world sectors are visible from within its boundary.

Note:: If this function is called more than once, the world should have collision data. This is for reasons of efficiency.

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

Parameters:

wpWorld	A pointer to an RpWorld with PVS.
spSector	A pointer to an RpWorldSector with PVS.
callback	A pointer to the RpPVSCallBack function for sampling a world sector.
pData	A pointer to private data for the callback.

Returns:: RpWorld if successful or NULL if there is an error.

See also:: RpPVSSetWorldSectorVisibility , RpPVSGeneric , RpPVSSamplePOV

RpWorld* RpPVSDestroy

(

RpWorld *

wpWorld

)

RpPVSDestroy is used to destroy the PVS for the given world.

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

Parameters:

wpWorld

A pointer to a RpWorld containing the PVS data.

Returns:: RpWorld if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorldSector* RpPVSGeneric	(	RpWorldSector *	spSect,
		const RwBBox *	box,
		void *	pData
	)

RpPVSGeneric is the RenderWare supplied function for sampling within a world sector. The samples are non-uniformly distributed in a regular grid.

This requires the private data to be a pointer to a RwReal, in the range 0.01 to 1.0, to specify the sampling distance between two points. The number is the fraction of the major axis length of the world's bounding box.

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

Parameters:

spSect	A pointer to the RpWorldSector being sampled.
box	The bounding box of the sector.
pData	A pointer to private data for the sampling function.

Returns:: RpWorldSector if successful or NULL if there is an error.

See also:: RpPVSSetWorldSectorVisibility , RpPVSConstruct , RpPVSSamplePOV

RpPVSProgressCallBack RpPVSGetProgressCallBack

(

RpWorld *

wpWorld

)

RpPVSGetProgressCallBack is used to retrieve PVS creation progress callback function of the specified world. The callback is called from RpPVSGeneric every time it has processed a single world sector, enabling an application to monitor how the generation of PVS data is progressing and, possibly, to provide feedback to the user.

Parameters:

wpWorld

A pointer to a RpWorld.

Returns:: The RpPVSProgressCallBack function if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorld* RpPVSHook

(

RpWorld *

wpWorld

)

RpPVSHook is used to enable rendering of the specified world using the world's PVS data. Typically used prior to a frame render (and followed afterwards by RpPVSUnhook) but may be permanently enabled if PVS rendering is always required. If RpPVSHook is not used all world sectors in the current camera's view frustum are rendered.

Note that this function overrides the world sector render callback which is only returned to its original form when RpPVSUnhook is called.

The PVS plugin must be attached before using this function.

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

Parameters:

wpWorld

A pointer to a RpWorld with PVS data.

Returns:: RpWorld if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RwBool RpPVSPluginAttach

(

void

)

RpPVSPluginAttach is used to attach the PVS plugin to the RenderWare system to enable the building and use of potentially visible sets. The PVS plugin must be attached between initializing the system with RwEngineInit and opening it with RwEngineOpen.

Note:: The PVS plugin requires the world plugin to be attached.

The include file rppvs.h is also required and must be included by an application wishing to use PVS. Note also that when linking the PVS plugin library, rppvs.lib, into an application, make sure the following RenderWare library is made available to the linker: rtray.lib.

Returns:: TRUE if successful or FALSE if there is an error

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible , RpWorldPluginAttach , RwEngineInit , RwEngineOpen , RwEngineStart

RwBool RpPVSQuery

(

RpWorld *

wpWorld

)

RpPVSQuery is used to determine whether the specified world contains PVS data, that is, if it has already been processed using RpPVSConstruct.

The PVS plugin must be attached before using this function.

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

Parameters:

wpWorld

A pointer to a RpWorld to be queried.

Returns:: TRUE if PVS data is present, FALSE otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RwBool RpPVSSamplePOV	(	RwV3d *	pos,
		RwBool	colltest
	)

RpPVSSamplePOV is used to update the current visibility map with a sample using the given position.

It is possible for the PVS to drop sectors incorrectly due to insufficient sampling. RpPVSSamplePOV can be used to repair such errors by adding extra samples at specific positions.

This functions assumes PVS data is already present in a world.

Note:: If this function is called more than once, the world should have collision data. This is for reasons of efficiency.

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

Parameters:

pos	A pointer to a RwV3d which specifies the current viewing position.
colltest	If TRUE, it only uses the viewpoint if it is inside the geometry of the sector. NB: This temporaily overrides the parameters set by RpPVSSetCollisionDetection

Returns:: TRUE if successful or FALSE if the sample point was rejected.

See also:: RpPVSSetWorldSectorVisibility , RpPVSSamplePOV , RpPVSGeneric , RpPVSConstruct

RwBool RpPVSSetBackFaceCulling

(

RwBool

bfc

)

RpPVSSetBackFaceCulling is used to turn back face culling on or off. By default, it is TRUE.

IMPORTANT NOTES:

It is ONLY recommended to set this to FALSE, if your world is constructed from polygons that are visible from both sides - otherwise unexpected results are likely to occur.

This flag must be set BEFORE any calls to an RpPVS function (but after RpPVSPluginAttach), since it affects initialization of the geometry in the world. If an RpPVS function has already been used, RpPVSDestroy must be called before this function call can take effect.

If, in the world, the viewer is allowed to wander 'outside' the geometry, which in a world made with double sided faces may take on a different meaning, then RpPVSSetCollisionDetection must be called with the FALSE parameter - otherwise some legitimate sample points may be tagged as invalid.

Parameters:

bfc

A boolean to specify whether backface culling should be on.

Returns:: The culling flag.

See also:: RpPVSConstruct , RpPVSSamplePOV , RpPVSDestroy , RpPVSPluginAttach

RwBool RpPVSSetCollisionDetection

(

RwBool

collis

)

RpPVSSetCollisionDetection is used to turn collision detection on or off. With collision detection on, only sample points within the geometry of a sector will be chosen.

Parameters:

collis

A boolean to specify whether collision should be on.

Returns:: Result of collision detection, i.e. collis.

See also:: RpPVSConstruct , RpPVSSamplePOV

RpWorld* RpPVSSetProgressCallBack	(	RpWorld *	wpWorld,
		RpPVSProgressCallBack	callback
	)

RpPVSSetProgressCallBack is used to define a PVS creation progress callback function for the specified world. The callback is called from RpPVSGeneric every time it has processed a single world sector, enabling an application to monitor how the generation of PVS data is progressing and, possibly, to provide feedback to the user.

Parameters:

wpWorld	A pointer to a RpWorld.
callback	A pointer to the RpPVSProgressCallBack function.

Returns:: RpWorld if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorldSector* RpPVSSetViewPosition	(	RpWorld *	wpWorld,
		RwV3d *	pos
	)

RpPVSSetViewPosition is used to set the viewing sector for subsequent PVS culling. NB: This is the alternative function to RpPVSSetViewSector, which is overridden by this function call. It selects the appropriate visibility map for PVS culling. This function must be called before any render function otherwise incorrect culling will occur.

RpPVSSetViewSector is typically used immediately prior to a frame render by setting the view position equal to that of the current camera.

The PVS plugin must be attached before using this function.

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

Parameters:

wpWorld	A pointer to the RpWorld containing the PVS data.
pos	A pointer to a RwV3d which specifies the current viewing position.

Returns:: RpWorldSector if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorldSector* RpPVSSetViewSector	(	RpWorld *	wpWorld,
		RpWorldSector *	spSect
	)

RpPVSSetViewSector is used to set the viewing sector for subsequent PVS culling. NB: This is the alternative function to RpPVSSetViewPosition, which is overridden by this function call. It selects the appropriate visibility map for PVS culling. This function must be called before any render function otherwise incorrect culling will occur.

RpPVSSetViewSector is typically used immediately prior to a frame render by setting the view position equal to that of the current camera.

The PVS plugin must be attached before using this function.

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

Parameters:

wpWorld	A pointer to the RpWorld containing the PVS data.
spSect	A pointer to the sector which specifies the current viewing position.

Returns:: RpWorldSector if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSStatisticsGet , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorldSector* RpPVSSetWorldSectorPairedVisibility	(	RpWorldSector *	spSectA,
		RpWorldSector *	spSectB,
		RwBool	visible,
		RwBool	mutual
	)

RpPVSSetWorldSectorPairedVisibility is to mark the first given world sector with the required visibility from the second given world sector, and vice versa if the mutal flag is set to TRUE.

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

Parameters:

spSectA	A pointer to a RpWorldSector.
spSectB	A pointer to a RpWorldSector.
visible	Flag to set the visibility.
mutual	Flag to say if visibility is to be mutual.

Returns:: RpWorldSector if sucessful, NULL otherwise.

See also:: RpPVSGeneric , RpPVSConstruct , RpPVSSamplePOV , RpPVSSetWorldSectorVisibility

RpWorldSector* RpPVSSetWorldSectorVisibility	(	RpWorldSector *	spSect,
		RwBool	visible
	)

RpPVSSetWorldSectorVisibility is to mark the given world sector as visible (or not) from the current sector (set by calling RpPVSSetViewPosition).

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

Parameters:

spSect	A pointer to a RpWorldSector.
visible	Flag to set the visibility.

Returns:: RpWorldSector if sucessful, NULL otherwise.

See also:: RpPVSGeneric , RpPVSConstruct , RpPVSSamplePOV , RpPVSSetWorldSectorPairedVisibility

RpWorld* RpPVSStatisticsGet	(	RpWorld *	wpWorld,
		RwInt32 *	ptotal,
		RwInt32 *	paccept
	)

RpPVSStatisticsGet is used to retrieve statistics relating to the rendering perfomance of the PVS data in the specified world. The figures obtained from this function are: (a) the total number of triangles that would have been rendered if PVS data was not used, and (b) the total number of triangles that have been rendered using the PVS data. Typically used immediately after a frame render.

The PVS plugin must be attached before using this function.

Parameters:

wpWorld	A pointer to a RpWorld with PVS data.
ptotal	A pointer to a RwInt32 to return number of polygons before PVS culling.
paccept	A pointer to a RwInt32 to return number of polygons after PVS culling.

Returns:: RpWorld if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSUnhook , RpPVSWorldSectorVisible

RpWorld* RpPVSUnhook

(

RpWorld *

wpWorld

)

RpPVSUnhook is used to disable rendering of the specified world using the world's PVS data. Typically used just after to a frame render (which followed a call to RpPVSHook) but may be permanently disabled if PVS rendering is not required.

Note that the function RpPVSHook overrides the world sector render callback which is only returned to its original form when RpPVSUnhook is called. The PVS plugin must be attached before using this function.

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

Parameters:

wpWorld

A pointer to a RpWorld containing PVS data.

Returns:: RpWorld if sucessful, NULL otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSWorldSectorVisible

RwBool RpPVSWorldSectorVisible

(

RpWorldSector *

spSect

)

RpPVSWorldSectorVisible is used to determine if the sector is visible using the current visibility map.

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

Parameters:

spSect

A pointer to a RpWorldSector to be determined.

Returns:: TRUE if visible, FALSE otherwise.

See also:: RpPVSAtomicVisible , RpPVSDestroy , RpPVSGetProgressCallBack , RpPVSHook , RpPVSPluginAttach , RpPVSQuery , RpPVSSetProgressCallBack , RpPVSSetViewPosition , RpPVSStatisticsGet , RpPVSUnhook

RxNodeDefinition* RxNodeDefinitionGetPVSWorldSectorCSL

(

void

)

RxNodeDefinitionGetPVSWorldSectorCSL returns a pointer to a node implementing PVS culling in custom world sector object pipelines.

This nodes prevents world sectors from being rendered if they are culled by the PVS visilibility map.

This node should be inserted at the beginning of a world sector object pipeline. It must come before any nodes which create or expect packets (e.g an instancing node), as it does not itself create or use them. If a world sector is visible, execution continues to the next node in the pipeline, otherwise the pipeline is terminated.

The node has one output and no clusters of interest.

Returns:: pointer to a node for PVS culling in custom world sector pipelines on success, NULL otherwise

Converted from CHM to HTML with chm2web Pro 2.85 (unicode)

RpPVS [PVS]

Typedefs

Functions

Detailed Description

RpPVS Plugin Overview

Overview

Typedef Documentation

Function Documentation

RpPVS
[PVS]