Module assets

Expand description

Renderer assets module.

This module contains:

Definitions and loading logic for all assets used by the renderer, that is Mesh, Texture, Buffer, Shader assets. Each asset type has its own loading logic and GPU preparation steps, defined in their respective submodules.
The bindings submodule, which provides utilities for defining custom render resources and bindings.
A set of default utility meshes, defined in the meshes submodule.

§Asset loading

§Default asset loading

Assets can be loaded with the default options using the AssetServer as usual:

let texture_handle: Handle<Texture> = asset_server.load("res/my_texture.png");

§Load with options

Some assets can be loaded with options, for example a texture can be loaded with specific sampler settings:

let texture_handle: Handle<Texture> = assets_server.load_with_settings("res/my_texture.png",
    |settings: &mut TextureLoaderSettings| {
        settings.label = "my_texture".to_string();
        settings.format = TextureFormat::R8Unorm;
        settings.usages = TextureUsages::TEXTURE_BINDING;
    });

§Custom asset creation

Assets can also be created from raw data, for example a texture can be created from raw pixel data:

let texture_handle: Handle<Texture> = asset_server.add(Texture {
    label: "My Texture".to_string(),
    size: (256, 256),
    format: TextureFormat::Rgba8Unorm,
    usages: TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING,
    data: vec![0u8; 256 * 256 * 4], // RGBA8 texture with all pixels set to transparent black
    ..Default::default()
});

§Render assets and render bindings

Assets defined in this module can be used as GPU resources in render bindings/pipelines by referencing them in the corresponding preparation systems. The main types to be aware of are:

RenderData: declares GPU resources (buffers/textures) and how they are recreated.
RenderBinding: builds a bind group by referencing resources exposed by one or more RenderData instances.

§RenderData

A RenderData is used to allocate reusable GPU resources. It is registered with RenderDataRegisterPlugin, which:

creates and prepares the corresponding GpuRenderData,
optionally recreates it when RenderData::recreate returns Some(true).

Typical example (deferred textures):

#[derive(Asset, Clone, TypePath, Default)]
pub struct DeferredTextures;
impl DeferredTextures {
    pub const ALBEDO_RESOLVED_IDX: u32 = 1;
    pub const DEMO_BUFFER: u32 = 2;
}

impl RenderData for DeferredTextures {
    type Params = (SQuery<&'static Window>, SRes<Messages<SurfaceResized>>);

    fn describe((window, _): &mut SystemParamItem<Self::Params>, builder: &mut RenderDataBuilder) {
        let size = {
            let window = window.single().unwrap();
            (window.resolution.physical_width(), window.resolution.physical_height())
        };
        let usages = TextureUsages::RENDER_ATTACHMENT | TextureUsages::TEXTURE_BINDING;
        builder
            .add_texture(Self::ALBEDO_RESOLVED_IDX,
                Texture {
                    label: "pbr-albedo-resolved".to_string(),
                    size,
                    format: TextureFormat::Rgba8UnormSrgb,
                    usages,
                    ..Default::default()
                },
            )
            .add_buffer(Self::DEMO_BUFFER,
                Buffer {
                    label: "demo-buffer".to_string(),
                    size: 1024,
                    usage: BufferUsage::STORAGE | BufferUsage::COPY_DST,
                    content: None,
                },
            );
    }

    fn recreate((_, surface_resized): &SystemParamItem<Self::Params>) -> Option<bool> {
        Some(surface_resized.get_cursor().read(surface_resized).next().is_some())
    }
}

pub struct DeferredTexturesPlugin;
impl Plugin for DeferredTexturesPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(RenderDataRegisterPlugin::<DeferredTextures>::default());
    }
}

To later update the content of a render data buffer/texture, request ResRenderData in a system and use the corresponding getters to access the GPU resource:

fn update_buffer(mut deferred_textures: ResRenderData<DeferredTextures>, mut buffers: ResMut<GpuBuffers>) {
    let buffer = match buffer.iter().next() {
        Some((_, buffer)) => match buffer.get_buffer(DeferredTextures::DEMO_BUFFER) {
            Some(buffer) => buffer,
            None => return
        },
        _ => return
    };

    // Update the buffer content with new data
    // (...)
}

§RenderBinding

A RenderBinding maps resources from GpuRenderData into a bind group layout + bind group pair (GpuRenderBinding). It is registered with RenderBindingRegisterPlugin.

Example: build a bind group from the resolved deferred textures.


#[derive(TypePath, Default, Clone, Asset)]
struct RenderBindingResolved;
impl RenderBinding for RenderBindingResolved {
    type Params = SRenderData<DeferredTextures>;

    fn describe(
        deferred_textures: &SystemParamItem<Self::Params>,
        builder: &mut RenderBindingBuilder,
    ) {
        builder
            .add_texture_view(deferred_textures, DeferredTextures::ALBEDO_RESOLVED_IDX)
            .add_texture_sampler(deferred_textures, DeferredTextures::ALBEDO_RESOLVED_IDX);
    }

    fn label(&self) -> &'static str { "deferred-textures-resolved-binding" }
}

pub struct DeferredBindingPlugin;
impl Plugin for DeferredBindingPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(RenderBindingRegisterPlugin::<RenderBindingResolved>::default());
    }
}

§Referencing In Pipelines

To use a registered render binding in a pipeline preparation system, request SRenderBinding in the render asset params and use its layout/bind_group.

type Params = (
    SRenderBinding<RenderBindingResolved>
);

// In RenderPipelineDescriptor
bind_group_layouts: vec![
    // (...)
    render_binding.iter().next().map(|(_, d)| d.layout.clone()),
],

In the sub-pass, bind groups must match that same ordering:

// (...)
SubPassCommand::BindGroup(1, rbinding.iter().next().map(|(_, d)| d.bind_group.clone())),

§Plugin Order

Register the underlying RenderData plugin before the RenderBinding plugin that depends on it. This allows the binding preparation to retry until all dependent GPU resources are ready, and to react correctly when data are recreated.

Re-exports§

pub use meshes::*;

Modules§

meshes: This module contains built-in meshes that can be used for rendering. These include simple geometric shapes such as planes, cubes, and capsules. Each mesh is defined with its own vertex and index data, and can be easily instantiated and rendered in the scene.

Structs§

Buffer: Stores a CPU buffer with raw byte data and metadata for GPU allocation. This buffer will be uploaded to the GPU, represented by a GpuBuffer asset.
GpuBuffer: Represents a GPU buffer resource allocated from a CPU Buffer asset.
GpuMesh: Represents a GPU mesh resource allocated from a CPU Mesh asset. If the mesh was prepared with use_ssbo = true, the vertex and index data will be in the SSBO mesh buffer SsboMesh and the vertex_buffer and index_buffer fields will be None. Otherwhise, they will contain GPU buffers with the vertex and index data respectively.
GpuRenderBinding: The gpu asset that is created from the render binding holder. This is the asset that is actually used in the render pass. It contains the bind group and bind group layout that are created according to the description in the RenderBinding implementation, and can be retrieved using the binding index specified in the description.
GpuRenderData: The gpu asset that is created from the render data holder. This is the asset that is actually used in the render pass. It contains the gpu buffers and textures that are created according to the description in the RenderData implementation, and can be retrieved using the binding index specified in the description.
GpuTexture: Represents a GPU texture resource allocated from a CPU Texture asset.
Mesh: Stores a CPU mesh with vertex and index data, along with metadata for GPU allocation. If loaded from a file, the mesh should have a .obj or .fbx extension. The vertices, indices, and bbox fields are expected to be populated by the asset loader; if not loaded from a file, they will default to empty and a degenerate bounding box respectively. This mesh will be uploaded to the GPU, represented by a GpuMesh asset.
Mesh3d: Utils component that stores a Mesh asset handle for 3D rendering.
MeshBbox
MeshLoaderSettings: Settings for loading a mesh asset while creating a Mesh.
PlaceholderTexture: Placeholder texture used while real texture handles finish loading.
RenderAssets: Stores all assets of a given GPU RenderAsset type, indexed by the ID of their source CPU asset.
RenderAssetsPlugin: Plugin that adds the systems and resources to extract, prepare and store a given type of GPU RenderAsset from their source CPU [bevy::prelude::Asset]. To use, simply add RenderAssetsPlugin::<YourGpuAssetType>::default() to your app, and make sure to implement the RenderAsset trait for your GPU asset type.
RenderBindingBuilder: A builder for the render binding. This is used in the description of the render binding to specify the buffers and textures that should be created on the gpu, and to build the bind group layout and bind group entries.
RenderBindingHolder
RenderBindingRegisterPlugin: A plugin to register a render binding.
RenderDataBuilder: A builder for render data. This is used to describe the buffers and textures that should be created on the gpu for a render data. After each data have been described, buffers and textures will be created on the gpu according to the description, and can be retrieved on the GPU side (see GpuRenderData).
RenderDataRegisterPlugin: A plugin to register a render data type.
Shader: Stores a shader source as UTF-8 text. File should have a .wgsl extension. Most of the time, the user does not need to load shaders directly, as they can be embedded in materials and pipelines. Note: the shader will only be compiled on the GPU when used in a pipeline, so this is just a container for the source code.
Texture: Stores a CPU texture with raw pixel data and metadata for GPU allocation. If loaded from a file, the texture should have a .png or .jpg extension. This texture will be uploaded to the GPU, represented by a GpuTexture asset.
TextureLoaderSettings: Settings for loading a texture asset while creating a Texture.

Enums§

PrepareAssetError

Constants§

DEPTH_FORMAT: The depth texture format.
SWAPCHAIN_FORMAT: The swapchain texture format.

Traits§

RenderAsset: Trait that describes a GPU asset extracted from a CPU asset that implements the [bevy::prelude::Asset] trait. The GPU asset is prepared from the CPU asset using the render-world system params, and can fail with a retry or fatal error.
RenderBinding: A trait for describing a render binding.
RenderData: A trait for describing render data.

Type Aliases§

Binding: The gpu asset that is created from the render binding holder. This is the asset that is actually used in the render pass.
BindingMut: The gpu asset that is created from the render binding holder. This is the asset that is actually used in the render pass.
BufferBindingType: Buffer binding types.
BufferUsage: Buffer usages.
FilterMode: Texture filter mode.
ResMutRenderData: Alias for a ResMut<RenderAssets<GpuRenderData<M>>>.
ResRenderData: Alias for a Res<RenderAssets<GpuRenderData<M>>>.
SBinding: The gpu asset that is created from the render binding holder. This is the asset that is actually used in the render pass.
SBindingMut: The gpu asset that is created from the render binding holder. This is the asset that is actually used in the render pass.
SRenderData: The gpu asset that is created from the render data holder. This is the asset that is actually used in the render pass.
SRenderDataMut: The gpu asset that is created from the render data holder. This is the asset that is actually used in the render pass.
TextureFormat: Texture format.
TextureUsages: Texture usages.

Module assets

Module assets Copy item path

§Asset loading

§Default asset loading

§Load with options

§Custom asset creation

§Render assets and render bindings

§RenderData

§RenderBinding

§Referencing In Pipelines

§Plugin Order

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Module assets