Documentation
¶
Overview ¶
Occlusion culling can improve rendering performance in closed/semi-open areas by hiding geometry that is occluded by other objects.
The occlusion culling system is mostly static. OccluderInstance3Ds can be moved or hidden at run-time, but doing so will trigger a background recomputation that can take several frames. It is recommended to only move OccluderInstance3Ds sporadically (e.g. for procedural generation purposes), rather than doing so every frame.
The occlusion culling system works by rendering the occluders on the CPU in parallel using Embree, drawing the result to a low-resolution buffer then using this to cull 3D nodes individually. In the 3D editor, you can preview the occlusion culling buffer by choosing Perspective > Display Advanced... > Occlusion Culling Buffer in the top-left corner of the 3D viewport. The occlusion culling buffer quality can be adjusted in the Project Settings.
Baking: Select an OccluderInstance3D node, then use the Bake Occluders button at the top of the 3D editor. Only opaque materials will be taken into account; transparent materials (alpha-blended or alpha-tested) will be ignored by the occluder generation.
Note: Occlusion culling is only effective if ProjectSettings "rendering/occlusion_culling/use_occlusion_culling" is true. Enabling occlusion culling has a cost on the CPU. Only enable occlusion culling if you actually plan to use it. Large open scenes with few or no objects blocking the view will generally not benefit much from occlusion culling. Large open scenes generally benefit more from mesh LOD and visibility ranges (GeometryInstance3D.VisibilityRangeBegin and GeometryInstance3D.VisibilityRangeEnd) compared to occlusion culling.
Note: Due to memory constraints, occlusion culling is not supported by default in Web export templates. It can be enabled by compiling custom Web export templates with module_raycast_enabled=yes.
Index ¶
- type Advanced
- type Any
- type Extension
- type ID
- type Instance
- func (self Instance) AsNode() Node.Instance
- func (self Instance) AsNode3D() Node3D.Instance
- func (self Instance) AsObject() [1]gd.Object
- func (self Instance) AsOccluderInstance3D() Instance
- func (self Instance) AsVisualInstance3D() VisualInstance3D.Instance
- func (self Instance) BakeMask() int
- func (self Instance) BakeSimplificationDistance() Float.X
- func (self Instance) GetBakeMaskValue(layer_number int) bool
- func (self Instance) ID() ID
- func (self Instance) Occluder() Occluder3D.Instance
- func (self Instance) SetBakeMask(value int)
- func (self Instance) SetBakeMaskValue(layer_number int, value bool)
- func (self Instance) SetBakeSimplificationDistance(value Float.X)
- func (self *Instance) SetObject(obj [1]gd.Object) bool
- func (self Instance) SetOccluder(value Occluder3D.Instance)
- func (self Instance) Virtual(name string) reflect.Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Advanced ¶
type Advanced = class
Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.
type Extension ¶
Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension
func (*Extension[T]) AsOccluderInstance3D ¶
func (*Extension[T]) AsVisualInstance3D ¶
func (self *Extension[T]) AsVisualInstance3D() VisualInstance3D.Instance
type ID ¶
ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.
type Instance ¶
type Instance [1]gdclass.OccluderInstance3D
Instance of the class with convieniently typed arguments and results.
var Nil Instance
Nil is a nil/null instance of the class. Equivalent to the zero value.
func (Instance) AsOccluderInstance3D ¶
func (Instance) AsVisualInstance3D ¶
func (self Instance) AsVisualInstance3D() VisualInstance3D.Instance
func (Instance) BakeMask ¶
The visual layers to account for when baking for occluders. Only MeshInstance3Ds whose VisualInstance3D.Layers match with this BakeMask will be included in the generated occluder mesh. By default, all objects with opaque materials are taken into account for the occluder baking.
To improve performance and avoid artifacts, it is recommended to exclude dynamic objects, small objects and fixtures from the baking process by moving them to a separate visual layer and excluding this layer in BakeMask.
func (Instance) BakeSimplificationDistance ¶
The simplification distance to use for simplifying the generated occluder polygon (in 3D units). Higher values result in a less detailed occluder mesh, which improves performance but reduces culling accuracy.
The occluder geometry is rendered on the CPU, so it is important to keep its geometry as simple as possible. Since the buffer is rendered at a low resolution, less detailed occluder meshes generally still work well. The default value is fairly aggressive, so you may have to decrease it if you run into false negatives (objects being occluded even though they are visible by the camera). A value of 0.01 will act conservatively, and will keep geometry perceptually unaffected in the occlusion culling buffer. Depending on the scene, a value of 0.01 may still simplify the mesh noticeably compared to disabling simplification entirely.
Setting this to 0.0 disables simplification entirely, but vertices in the exact same position will still be merged. The mesh will also be re-indexed to reduce both the number of vertices and indices.
Note: This uses the meshoptimizer library under the hood, similar to LOD generation.
func (Instance) GetBakeMaskValue ¶
Returns whether or not the specified layer of the BakeMask is enabled, given a 'layer_number' between 1 and 32.
func (Instance) Occluder ¶
func (self Instance) Occluder() Occluder3D.Instance
The occluder resource for this OccluderInstance3D. You can generate an occluder resource by selecting an OccluderInstance3D node then using the Bake Occluders button at the top of the editor.
You can also draw your own 2D occluder polygon by adding a new PolygonOccluder3D resource to the Occluder property in the Inspector.
Alternatively, you can select a primitive occluder to use: QuadOccluder3D, BoxOccluder3D or SphereOccluder3D.
func (Instance) SetBakeMask ¶
SetBakeMask sets the property returned by [GetBakeMask].
func (Instance) SetBakeMaskValue ¶
Based on 'value', enables or disables the specified layer in the BakeMask, given a 'layer_number' between 1 and 32.
func (Instance) SetBakeSimplificationDistance ¶
SetBakeSimplificationDistance sets the property returned by [GetBakeSimplificationDistance].
func (Instance) SetOccluder ¶
func (self Instance) SetOccluder(value Occluder3D.Instance)
SetOccluder sets the property returned by [GetOccluder].
Source Files