Struct Stage

pub struct Stage { /* private fields */ }

Entrypoint for staging data on the GPU and interacting with lighting.

Design

The Stage struct serves as the central hub for managing and staging data on the GPU. It provides a consistent API for creating resources, applying effects, and customizing parameters.

The Stage uses a combination of new_*, with_*, set_*, and getter functions to facilitate resource management and customization.

Resources are managed internally, requiring no additional lifecycle work from the user. This design simplifies the process of resource management, allowing developers to focus on creating and rendering their scenes without worrying about the underlying GPU resource management.

Resources

The Stage is responsible for creating various resources and staging them on the GPU. It handles the setup and management of the following resources:

• Camera: Manages the view and projection matrices for rendering scenes.
  • Stage::new_camera creates a new Camera.
  • Stage::use_camera tells the Stage to use a camera.
• Transform: Represents the position, rotation, and scale of objects.
  • Stage::new_transform creates a new Transform.
• NestedTransform: Allows for hierarchical transformations, useful for complex object hierarchies.
  • Stage::new_nested_transform creates a new NestedTransform
• Vertices: Manages vertex data for rendering meshes.
  • Stage::new_vertices
• Indices: Manages index data for rendering meshes with indexed drawing.
  • Stage::new_indices
• Primitive: Represents a drawable object in the scene.
  • Stage::new_primitive
• GltfDocument: Handles loading and managing GLTF assets.
  • Stage::load_gltf_document_from_path loads a new GLTF document from the local filesystem.
  • Stage::load_gltf_document_from_bytes parses a new GLTF document from pre-loaded bytes.
• Skin: Animation and rigging information.
  • Stage::new_skin

Lighting effects

The Stage also manages various lighting effects, which enhance the visual quality of the scene:

• AnalyticalLight: Simulates a single light source, with three flavors:
  • DirectionalLight: Represents sunlight or other distant light sources.
  • PointLight: Represents a light source that emits light in all directions from a single point.
  • SpotLight: Represents a light source that emits light in a cone shape.
• Skybox: Provides image-based lighting (IBL) for realistic environmental reflections and ambient lighting.
• Bloom: Adds a glow effect to bright areas of the scene, enhancing visual appeal.
• ShadowMap: Manages shadow mapping for realistic shadow rendering.
• LightTiling: Optimizes lighting calculations by dividing the scene into tiles for efficient processing.

Note

Clones of Stage all point to the same underlying data.

Implementations

impl Stage

GLTF functions

pub fn load_gltf_document_from_path( &self, path: impl AsRef<Path>, ) -> Result<GltfDocument, StageError>

pub fn load_gltf_document_from_bytes( &self, bytes: impl AsRef<[u8]>, ) -> Result<GltfDocument, StageError>

impl Stage

Geometry functions

pub fn default_vertices(&self) -> &Vertices

Returns the vertices of a white unit cube.

This is the mesh of every Primitive that has not had its vertices set.

pub fn new_camera(&self) -> Camera

Stage a new Camera on the GPU.

If no camera is currently in use on the Stage through Stage::use_camera, this new camera will be used automatically.

pub fn use_camera(&self, camera: impl AsRef<Camera>)

Use the given camera when rendering.

pub fn used_camera_id(&self) -> Id<CameraDescriptor>

Return the Id of the camera currently in use.

pub fn use_camera_id(&self, camera_id: Id<CameraDescriptor>)

Set the default camera Id.

pub fn new_transform(&self) -> Transform

Stage a Transform on the GPU.

pub fn new_vertices(&self, data: impl IntoIterator<Item = Vertex>) -> Vertices

Stage some vertex geometry data.

pub fn new_indices(&self, data: impl IntoIterator<Item = u32>) -> Indices

Stage some vertex index data.

pub fn new_morph_targets( &self, data: impl IntoIterator<Item = Vec<MorphTarget>>, ) -> MorphTargets

Stage new morph targets.

pub fn new_morph_target_weights( &self, data: impl IntoIterator<Item = f32>, ) -> MorphTargetWeights

Stage new morph target weights.

pub fn new_skin( &self, joints: impl IntoIterator<Item = impl Into<SkinJoint>>, inverse_bind_matrices: impl IntoIterator<Item = impl Into<Mat4>>, ) -> Skin

Stage a new skin.

pub fn new_primitive(&self) -> Primitive

Stage a new Primitive on the GPU.

The returned Primitive will automatically be added to this Stage.

The returned Primitive will have the stage’s default Vertices, which is an all-white unit cube.

The returned Primitive uses the stage’s default Material, which is white and does not participate in lighting. To change this, first create a Material with Stage::new_material and then call Primitive::set_material with the new material.

pub fn geometry_descriptor(&self) -> &Hybrid<GeometryDescriptor>

Returns a reference to the descriptor stored at the root of the geometry slab.

impl Stage

Materials methods.

pub fn default_material(&self) -> &Material

Returns the default Material.

The default is an all-white matte material.

pub fn new_material(&self) -> Material

Stage a new Material on the GPU.

The returned Material can be customized using the builder pattern.

pub fn set_atlas_size(&self, size: Extent3d) -> Result<(), StageError>

Set the size of the atlas.

This will cause a repacking.

pub fn add_images( &self, images: impl IntoIterator<Item = impl Into<AtlasImage>>, ) -> Result<Vec<AtlasTexture>, StageError>

Add images to the set of atlas images.

This returns a vector of Hybrid<AtlasTexture>, which is a descriptor of each image on the GPU. Dropping these entries will invalidate those images and cause the atlas to be repacked, and any raw GPU references to the underlying AtlasTexture will also be invalidated.

Adding an image can be quite expensive, as it requires creating a new texture array for the atlas and repacking all previous images. For that reason it is good to batch images to reduce the number of calls.

pub fn clear_images(&self) -> Result<(), StageError>

Clear all images from the atlas.

WARNING

This invalidates any previously staged AtlasTextures.

pub fn set_images( &self, images: impl IntoIterator<Item = impl Into<AtlasImage>>, ) -> Result<Vec<AtlasTexture>, StageError>

Set the images to use for the atlas.

Resets the atlas, packing it with the given images and returning a vector of the frames already staged.

WARNING

This invalidates any previously staged AtlasTextures.

impl Stage

Lighting methods.

pub fn new_directional_light(&self) -> AnalyticalLight<DirectionalLight>

Stage a new directional light.

pub fn new_point_light(&self) -> AnalyticalLight<PointLight>

Stage a new point light.

pub fn new_spot_light(&self) -> AnalyticalLight<SpotLight>

Stage a new spot light.

pub fn add_light<T>(&self, bundle: &AnalyticalLight<T>)

where T: IsLight, Light: From<T>,

Add an AnalyticalLight to the internal list of lights.

This is called implicitly by Stage::new_*_light.

This can be used to add the light back to the scene after using Stage::remove_light.

pub fn remove_light<T: IsLight>(&self, bundle: &AnalyticalLight<T>)

Remove an AnalyticalLight from the internal list of lights.

Use this to exclude a light from rendering, without dropping the light.

After calling this function you can include the light again using Stage::add_light.

pub fn new_shadow_map<T>( &self, analytical_light: &AnalyticalLight<T>, size: UVec2, z_near: f32, z_far: f32, ) -> Result<ShadowMap, StageError>

where T: IsLight, Light: From<T>,

Enable shadow mapping for the given AnalyticalLight, creating a new ShadowMap.

Tips for making a good shadow map

1. Make sure the map is big enough. Using a big map can fix some peter panning issues, even before playing with bias in the returned ShadowMap. The bigger the map, the cleaner the shadows will be. This can also solve PCF problems.
2. Don’t set PCF samples too high in the returned ShadowMap, as this can cause peter panning.
3. Ensure the znear and zfar parameters make sense, as the shadow map uses these to determine how much of the scene to cover. If you find that shadows are cut off in a straight line, it’s likely znear or zfar needs adjustment.

pub fn new_light_tiling(&self, config: LightTilingConfig) -> LightTiling

Enable light tiling, creating a new LightTiling.

impl Stage

Skybox methods

pub fn use_skybox(&self, skybox: &Skybox) -> &Self

Used the given Skybox.

To remove the currently used Skybox, call [Skybox::remove_skybox].

pub fn remove_skybox(&self) -> Option<Skybox>

Removes the currently used Skybox.

Returns the currently used Skybox, if any.

After calling this the Stage will not render with any Skybox, until [Skybox::use_skybox] is called with another Skybox.

pub fn new_skybox_from_path( &self, path: impl AsRef<Path>, ) -> Result<Skybox, AtlasImageError>

Returns a new Skybox using the HDR image at the given path, if possible.

The returned Skybox must be used with Stage::use_skybox.

pub fn new_skybox_from_bytes( &self, bytes: &[u8], ) -> Result<Skybox, AtlasImageError>

Returns a new Skybox using the bytes of an HDR image, if possible.

The returned Skybox must be used with Stage::use_skybox.

impl Stage

Image based lighting methods

pub fn new_ibl(&self, skybox: &Skybox) -> Ibl

Crate a new Ibl from the given Skybox.

pub fn use_ibl(&self, ibl: &Ibl) -> &Self

Use the given image based lighting.

Use Stage::new_ibl to create a new Ibl.

pub fn remove_ibl(&self) -> Option<Ibl>

Remove the current image based lighting from the stage and return it, if any.

impl Stage

pub fn runtime(&self) -> &WgpuRuntime

Returns the runtime.

pub fn device(&self) -> &Device

pub fn queue(&self) -> &Queue

pub fn brdf_lut(&self) -> &BrdfLut

Returns a reference to the BrdfLut.

This is used for creating skyboxes used in image based lighting.

pub fn used_gpu_buffer_byte_size(&self) -> usize

Sum the byte size of all used GPU memory.

Adds together the byte size of all underlying slab buffers.

Note

This does not take into consideration staged data that has not yet been committed with either Stage::commit or Stage::render.

pub fn hdr_texture(&self) -> impl Deref<Target = Texture> + '_

pub fn commit(&self) -> StageCommitResult

Run all upkeep and commit all staged changes to the GPU.

This is done implicitly in Stage::render.

This can be used after dropping resources to reclaim those resources on the GPU.

pub fn create_primitive_pipeline( device: &Device, fragment_color_format: TextureFormat, multisample_count: u32, ) -> RenderPipeline

pub fn new(ctx: &Context) -> Self

Create a new stage.

pub fn set_background_color(&self, color: impl Into<Vec4>)

pub fn with_background_color(self, color: impl Into<Vec4>) -> Self

pub fn get_msaa_sample_count(&self) -> u32

Return the multisample count.

pub fn set_msaa_sample_count(&self, multisample_count: u32)

Set the MSAA multisample count.

Set to 1 to disable MSAA. Setting to 0 will be treated the same as setting to 1.

pub fn with_msaa_sample_count(self, multisample_count: u32) -> Self

Set the MSAA multisample count.

Set to 1 to disable MSAA. Setting to 0 will be treated the same as setting to 1.

pub fn set_clear_color_attachments(&self, should_clear: bool)

Set whether color attachments are cleared before rendering.

pub fn with_clear_color_attachments(self, should_clear: bool) -> Self

Set whether color attachments are cleared before rendering.

pub fn set_clear_depth_attachments(&self, should_clear: bool)

Set whether color attachments are cleared before rendering.

pub fn with_clear_depth_attachments(self, should_clear: bool) -> Self

Set whether color attachments are cleared before rendering.

pub fn set_debug_mode(&self, debug_mode: DebugChannel)

Set the debug mode.

pub fn with_debug_mode(self, debug_mode: DebugChannel) -> Self

Set the debug mode.

pub fn set_use_debug_overlay(&self, use_debug_overlay: bool)

Set whether to render the debug overlay.

pub fn with_debug_overlay(self, use_debug_overlay: bool) -> Self

Set whether to render the debug overlay.

pub fn set_use_frustum_culling(&self, use_frustum_culling: bool)

Set whether to use frustum culling on GPU before drawing.

This defaults to true.

pub fn with_frustum_culling(self, use_frustum_culling: bool) -> Self

Set whether to render the debug overlay.

pub fn set_use_occlusion_culling(&self, use_occlusion_culling: bool)

Set whether to use occlusion culling on GPU before drawing.

This defaults to false.

Warning

Occlusion culling is a feature in development. YMMV.

pub fn with_occlusion_culling(self, use_occlusion_culling: bool) -> Self

Set whether to render the debug overlay.

pub fn set_has_lighting(&self, use_lighting: bool)

Set whether the stage uses lighting.

pub fn with_lighting(self, use_lighting: bool) -> Self

Set whether the stage uses lighting.

pub fn set_has_vertex_skinning(&self, use_skinning: bool)

Set whether to use vertex skinning.

pub fn with_vertex_skinning(self, use_skinning: bool) -> Self

Set whether to use vertex skinning.

pub fn get_size(&self) -> UVec2

pub fn set_size(&self, size: UVec2)

pub fn with_size(self, size: UVec2) -> Self

pub fn set_has_bloom(&self, has_bloom: bool)

Turn the bloom effect on or off.

pub fn with_bloom(self, has_bloom: bool) -> Self

Turn the bloom effect on or off.

pub fn set_bloom_mix_strength(&self, strength: f32)

Set the amount of bloom that is mixed in with the input image.

Defaults to 0.04.

pub fn with_bloom_mix_strength(self, strength: f32) -> Self

pub fn set_bloom_filter_radius(&self, filter_radius: f32)

Sets the bloom filter radius, in pixels.

Default is 1.0.

pub fn with_bloom_filter_radius(self, filter_radius: f32) -> Self

Sets the bloom filter radius, in pixels.

Default is 1.0.

pub fn add_primitive(&self, primitive: &Primitive) -> usize

Adds a primitive to the internal list of primitives to be drawn each frame.

Returns the number of primitives added.

If you drop the primitive and no other references are kept, it will be removed automatically from the internal list and will cease to be drawn each frame.

pub fn remove_primitive(&self, primitive: &Primitive) -> usize

Erase the given primitive from the internal list of primitives to be drawn each frame.

Returns the number of primitives added.

pub fn sort_primitive(&self, f: impl Fn(&Primitive, &Primitive) -> Ordering)

Sort the drawing order of primitives.

This determines the order in which Primitives are drawn each frame.

pub fn get_depth_texture(&self) -> DepthTexture

Returns a clone of the current depth texture.

pub fn new_nested_transform(&self) -> NestedTransform

Create a new NestedTransform.

pub fn render(&self, view: &TextureView)

Render the staged scene into the given view.

Trait Implementations

impl AsRef<Geometry> for Stage

fn as_ref(&self) -> &Geometry

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Lighting> for Stage

fn as_ref(&self) -> &Lighting

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Materials> for Stage

fn as_ref(&self) -> &Materials

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<WgpuRuntime> for Stage

fn as_ref(&self) -> &WgpuRuntime

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Stage

fn clone(&self) -> Stage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.