Visibility
Show and hide entities with Visibility, how frustum culling works, render layers for per-camera objects, visibility ranges for level of detail, and occlusion culling.
Every frame the renderer works out which entities each camera can see, and draws only those. You control that with three tools: Visibility to hide things, render layers to show things to some cameras only, and visibility ranges to swap detail with distance. The engine adds frustum culling on top.
Show and hide#
Visibility is a component on everything that can be drawn (meshes, sprites, lights, UI nodes). It has three values:
| Value | Effect |
|---|---|
Visibility::Inherited | The default. Visible if the parent is, or if it has no parent. |
Visibility::Hidden | Hidden, and so are children set to Inherited. |
Visibility::Visible | Visible even if the parent is hidden. |
#[derive(Component)]
struct Door;
fn toggle_door(keys: Res<ButtonInput<KeyCode>>, mut doors: Query<&mut Visibility, With<Door>>) {
if keys.just_pressed(KeyCode::KeyH) {
for mut visibility in &mut doors {
visibility.toggle_inherited_hidden();
}
}
}Hiding an entity keeps it in the world: its components stay and its systems still run. Despawn it to remove it.
Two more components are computed for you; read them, don't set them:
| Component | Means |
|---|---|
InheritedVisibility | Visible after applying the hierarchy. |
ViewVisibility | Visible to at least one camera this frame, after culling. Use it to skip work on things nobody sees. |
Frustum culling#
The engine computes an axis-aligned bounding box (Aabb) for every mesh and skips meshes whose box is outside a camera's view. You don't need to do anything, but two cases need help:
| Component | Use it when |
|---|---|
NoFrustumCulling | A mesh's vertices move outside its box (a shader that displaces vertices), so it vanishes at the screen edge. The mesh is then always drawn. |
NoAutoAabb | You set a correct Aabb yourself and don't want it recomputed. |
DynamicSkinnedMeshBounds | A skinned mesh's bounds should follow its animated pose. |
These are in neo::camera::visibility (and Aabb in neo::camera::primitives).
Render layers#
RenderLayers (in neo::camera::visibility) decides which cameras see which entities. An entity is drawn by a camera when they share at least one layer. Entities and cameras without the component are on layer 0.
use neo::camera::visibility::RenderLayers;
// the player's arms: only the view-model camera sees them
commands.spawn((Mesh3d(arms), MeshMaterial3d(material), RenderLayers::layer(1)));
// the view-model camera draws layer 1 on top of the world camera
commands.spawn((
Camera3d::default(),
Camera { order: 1, ..default() },
RenderLayers::layer(1),
));RenderLayers::layer(0).with(1) puts something on several layers, without removes one and RenderLayers::none() hides it from every camera. Lights use layers too: a light only lights entities on its layers. Uses: first-person arms, a minimap camera, a render-to-texture camera that sees a separate set of objects. Examples: first_person_view_model, render_to_texture.
Visibility ranges#
VisibilityRange (in neo::camera::visibility) shows an entity only within a band of distances from the camera, crossfading at the edges. Give each level of detail of a model its own range to swap between them:
use neo::camera::visibility::VisibilityRange;
// the detailed model, up close
commands.spawn((
Mesh3d(high_poly),
MeshMaterial3d(material.clone()),
VisibilityRange { start_margin: 0.0..0.0, end_margin: 3.0..4.0, use_aabb: false },
));
// the simple model, further away
commands.spawn((
Mesh3d(low_poly),
MeshMaterial3d(material),
VisibilityRange { start_margin: 3.0..4.0, end_margin: 8.0..9.0, use_aabb: false },
));Each margin is the distance range over which the model fades in or out. Make one level's end_margin equal the next level's start_margin for a smooth swap. Web builds support up to 64 visibility ranges per view. Example: cargo run --example visibility_range.
Occlusion culling#
Occlusion culling skips meshes hidden behind other meshes, which helps in dense scenes such as cities and interiors. It runs on the GPU, needs a depth prepass, and is off by default:
use neo::core_pipeline::prepass::DepthPrepass;
use neo::render::occlusion_culling::OcclusionCulling;
commands.spawn((Camera3d::default(), DepthPrepass, OcclusionCulling));Turn it on only if you measure a speed-up for your scene. It doesn't work with deferred rendering, and it needs GPU culling, which web builds don't have. Example: occlusion_culling (needs neo_feathers).