SceneCullingState
Engine/source/scene/culling/sceneCullingState.h
An object that gathers the culling state for a scene.
Visibility and Occlusion
CullOptions { CullEditorOverrides = BIT( 0 ) DontCullRenderDisabled = BIT( 1 ) }
cullObjects(SceneObject ** objects, U32 numObjects, U32 cullOptions)
Cull the given list of objects according to the current culling state.
bool
isCulled(SceneObject * object)
Return true if the given object is culled according to the current culling state.
bool
bool
bool
bool
isOccluded(SceneObject * object)
Return true if the given object is occluded according to the current culling state.
bool
bool
isOccluded(const OrientedBox3F & obb, const U32 * zones, U32 numZones)
Return true if the given OBB is occluded according to the current culling state.
bool
addOccluder(SceneObject * object)
Add the occlusion information contained in the given object.
bool
isOccludedByTerrain(SceneObject * object)
Test whether the given object is occluded by any of the terrains in the scene.
setDisableTerrainOcclusion(bool value)
Set whether isCulled() should do terrain occlusion checks or not.
Occluder Restrictions
Size restrictions on occlusion culling volumes.
Any occlusion volume that does not meet these minimum requirements is not accepted into the rendering state.
Having independent restrictions on both width and height allows filtering out occluders that might have a lot of area but only by covering very thin stretches of the screen.
If more than this number of occlusion volumes are added to a ZoneState, then the occlusions volumes corresponding to the smallest amount of screen real estate get dropped such as to never exceed this total number of occlusion volumes.
Percentage of camera-space frustum near plane height that an occlusion culler must at least fill in order to not be rejected.
Percentage of camera-space frustum near plane width that an occlusion culler must at least fill in order to not be rejected.
Zones
bool
If true, culling will only be performed against the root frustum and not against frustums of individual zones.
disableZoneCulling(bool value)
bool
isWithinVisibleZone(SceneObject * object)
Return true if any of the zones that the object is currently are visible.
Return a bit vector with one bit for each zone in the scene.
getZoneState(U32 zoneId)
Return the culling state for a particular zone.
getZoneState(U32 zoneId)
Returns the culling state for a particular zone.
bool
addCullingVolumeToZone(U32 zoneId, const SceneCullingVolume & volume)
Add a culling volume to the visibility state of the given zone.
bool
addCullingVolumeToZone(U32 zoneId, SceneCullingVolume::Type type, const AnyPolyhedron & polyhedron)
Copy the data from the given polyhedron to the culling state, create a new culling volume it and add it to the current culling state of the given zone.
bool
createCullingVolume(const Point3F * vertices, U32 numVertices, SceneCullingVolume::Type type, SceneCullingVolume & outVolume)
Create a new culling volume by extruding the given polygon away from the viewpoint.
Memory Management
Rather than allocating a lot of individual point and plane data for the culling volumes, it is more efficient to batch allocate chunks of memory and then release all the memory for all culling volumes in one go.
This is facilitated by this interface.
void *
allocateData(U32 size)
Allocate memory from this culling state.
T *
allocateData(U32 num)
Allocate memory for num instances of T from this culling state.
Private Types
CullingTestResult
Public Static Attributes
bool
Used to disable the somewhat expensive terrain occlusion testing done in during scene culling.
bool
Whether to force zone culling to off by default.
Protected Attributes
Vector< SceneObject * >
Occluders that have been added to this render state.
The viewing state that defines how the scene is being viewed.
The root culling frustum, which may be different from the camera frustum.
Allocator for culling data that can be freed in one go when the culling state is freed.
bool
If true, occlusion checks will not be done against the terrains in the scene.
bool
If true, all objects will only be tested against the root frustum.
Extra planes for culling.
The root culling volume corresponding to the culling frustum.
Scene which is being culled.
ZoneState entries for all zones in the scene.
Public Functions
SceneCullingState(SceneManager * sceneManager, const SceneCameraState & cameraState)
_testOccludersOnly(const T & bounds, Iter zoneIter)
Clear planes for extra culling.
Queue debug visualizations of the culling volumes of all currently selected zones (or, if no zone is selected, all volumes in the outdoor zone) to the debug drawer.
Return the root frustum which is used to set up scene visibility.
Return the viewing state that defines how the scene is being viewed.
Return the root frustum which is used to set up scene visibility.
Return the root culling volume that corresponds to the camera frustum.
Return the scene which is being culled in this state.
bool
Check extra planes culling.
setExtraPlanesCull(const PlaneSetF & cull)
Set planes for extra culling.
Private Functions
_testOccludersOnly(const T & bounds, Iter iter)
Detailed Description
An object that gathers the culling state for a scene.
Visibility and Occlusion
CullOptions
Enumerator
- CullEditorOverrides = BIT( 0 )
Cull objects that have their SceneObject::DisableCullingInEditorFlag set.
By default, these objects will not get culled if the editor is active.
- DontCullRenderDisabled = BIT( 1 )
Do not cull objects that are render-disabled.
cullObjects(SceneObject ** objects, U32 numObjects, U32 cullOptions)
Cull the given list of objects according to the current culling state.
Parameters:
| object | Array of objects. This array will be modified in place. |
| numObjects | Number of objects in objects. |
| cullOptions | Combination of CullOptions. |
Number of objects remaining in the list.
isCulled(SceneObject * object)
Return true if the given object is culled according to the current culling state.
isCulled(const Box3F & aabb, const U32 * zones, U32 numZones)
Return true if the given AABB is culled in any of the given zones.
isCulled(const OrientedBox3F & obb, const U32 * zones, U32 numZones)
Return true if the given OBB is culled in any of the given zones.
isCulled(const SphereF & sphere, const U32 * zones, U32 numZones)
Return true if the given sphere is culled in any of the given zones.
isOccluded(SceneObject * object)
Return true if the given object is occluded according to the current culling state.
isOccluded(const Box3F & aabb, const U32 * zones, U32 numZones)
Return true if the given AABB is occluded according to the current culling state.
isOccluded(const OrientedBox3F & obb, const U32 * zones, U32 numZones)
Return true if the given OBB is occluded according to the current culling state.
isOccluded(const SphereF & sphere, const U32 * zones, U32 numZones)
Return true if the given sphere is occluded according to the current culling state.
addOccluder(SceneObject * object)
Add the occlusion information contained in the given object.
note:This should only be called after all positive frustums have been added to the zone state.
isOccludedByTerrain(SceneObject * object)
Test whether the given object is occluded by any of the terrains in the scene.
setDisableTerrainOcclusion(bool value)
Set whether isCulled() should do terrain occlusion checks or not.
Occluder Restrictions
Size restrictions on occlusion culling volumes.
Any occlusion volume that does not meet these minimum requirements is not accepted into the rendering state.
Having independent restrictions on both width and height allows filtering out occluders that might have a lot of area but only by covering very thin stretches of the screen.
U32 smMaxOccludersPerZone
If more than this number of occlusion volumes are added to a ZoneState, then the occlusions volumes corresponding to the smallest amount of screen real estate get dropped such as to never exceed this total number of occlusion volumes.
F32 smOccluderMinHeightPercentage
Percentage of camera-space frustum near plane height that an occlusion culler must at least fill in order to not be rejected.
note:The height computed for occluders is only an estimate.
F32 smOccluderMinWidthPercentage
Percentage of camera-space frustum near plane width that an occlusion culler must at least fill in order to not be rejected.
note:The width computed for occluders is only an estimate.
Zones
disableZoneCulling()
If true, culling will only be performed against the root frustum and not against frustums of individual zones.
note:This also disables occluders as these are added to the zone frustums.
disableZoneCulling(bool value)
isWithinVisibleZone(SceneObject * object)
Return true if any of the zones that the object is currently are visible.
getZoneVisibilityFlags()
Return a bit vector with one bit for each zone in the scene.
If the bit is set, the zone has includer culling volumes attached to it and thus is visible.
getZoneState(U32 zoneId)
Return the culling state for a particular zone.
Parameters:
| zoneId | Numeric ID of zone. |
getZoneState(U32 zoneId)
Returns the culling state for a particular zone.
Parameters:
| zoneId | Numeric ID of zone. |
addCullingVolumeToZone(U32 zoneId, const SceneCullingVolume & volume)
Add a culling volume to the visibility state of the given zone.
Parameters:
| zoneId | ID of zone to which to add the given frustum's visibility information. |
| volume | A culling volume. Note that the data in the volume must have a lifetime at least as long as the culling state. |
True if the visibility state of the zone has changed, i.e. if the volume was either added in whole or merged with an existing set of planes. If the visibility state of the zone has not changed, returns false.
addCullingVolumeToZone(U32 zoneId, SceneCullingVolume::Type type, const AnyPolyhedron & polyhedron)
Copy the data from the given polyhedron to the culling state, create a new culling volume it and add it to the current culling state of the given zone.
Parameters:
| zoneId | ID of zone to which to add the given frustum's visibility information. |
| type | Which type of culling volume to add. |
| polyhedron | Polyhedron describing the space of the culling volume. |
createCullingVolume(const Point3F * vertices, U32 numVertices, SceneCullingVolume::Type type, SceneCullingVolume & outVolume)
Create a new culling volume by extruding the given polygon away from the viewpoint.
Parameters:
| vertices | Array of polygon vertices. |
| numVertices | Number of vertices in vertices. |
| type | Type of culling volume to create. |
| outVolume | (out) Receives the generated volume, if successful. |
True if a volume could be generated from the given polygon or false if not.
Memory Management
Rather than allocating a lot of individual point and plane data for the culling volumes, it is more efficient to batch allocate chunks of memory and then release all the memory for all culling volumes in one go.
This is facilitated by this interface.
allocateData(U32 size)
Allocate memory from this culling state.
The memory is freed when the culling state is destroyed.
allocateData(U32 num)
Allocate memory for num instances of T from this culling state.
Private Types
typedef SceneZoneCullingState::CullingTestResult CullingTestResult
Public Static Attributes
bool smDisableTerrainOcclusion
Used to disable the somewhat expensive terrain occlusion testing done in during scene culling.
bool smDisableZoneCulling
Whether to force zone culling to off by default.
Protected Attributes
Vector< SceneObject * > mAddedOccluderObjects
Occluders that have been added to this render state.
Adding an occluder does not necessarily result in an occluder volume being added. To not repeatedly try to process the same occluder object, all objects that are added are recorded here.
SceneCameraState mCameraState
The viewing state that defines how the scene is being viewed.
Frustum mCullingFrustum
The root culling frustum, which may be different from the camera frustum.
DataChunker mDataChunker
Allocator for culling data that can be freed in one go when the culling state is freed.
bool mDisableTerrainOcclusion
If true, occlusion checks will not be done against the terrains in the scene.
bool mDisableZoneCulling
If true, all objects will only be tested against the root frustum.
PlaneSetF mExtraPlanesCull
Extra planes for culling.
SceneCullingVolume mRootVolume
The root culling volume corresponding to the culling frustum.
SceneManager * mSceneManager
Scene which is being culled.
Vector< SceneZoneCullingState > mZoneStates
ZoneState entries for all zones in the scene.
BitVector mZoneVisibilityFlags
Public Functions
SceneCullingState(SceneManager * sceneManager, const SceneCameraState & cameraState)
_test(const T & bounds, const U32 * zones, U32 numZones)
_test(const T & bounds, Iter zoneIter, const PlaneF & nearPlane, const PlaneF & farPlane)
_testOccludersOnly(const T & bounds, Iter zoneIter)
clearExtraPlanesCull()
Clear planes for extra culling.
debugRenderCullingVolumes()
Queue debug visualizations of the culling volumes of all currently selected zones (or, if no zone is selected, all volumes in the outdoor zone) to the debug drawer.
getCameraFrustum()
Return the root frustum which is used to set up scene visibility.
getCameraState()
Return the viewing state that defines how the scene is being viewed.
getCullingFrustum()
Return the root frustum which is used to set up scene visibility.
getRootVolume()
Return the root culling volume that corresponds to the camera frustum.
note:This volume omits the near and far plane of the frustum's polyhedron as these will be tested separately during culling. Testing them repeatedly just wastes time.
getSceneManager()
Return the scene which is being culled in this state.
isOccludedWithExtraPlanesCull(const Box3F & box)
Check extra planes culling.
setExtraPlanesCull(const PlaneSetF & cull)
Set planes for extra culling.