Enum Readback

pub enum Readback {
    Texture(Handle<Image>),
    Buffer(Handle<ShaderStorageBuffer>),
}

A component that registers the wrapped handle for gpu readback, either a texture or a buffer.

Data is read asynchronously and will be triggered on the entity via the ReadbackComplete event when complete. If this component is not removed, the readback will be attempted every frame

Variants

Texture(Handle<Image>)

Buffer(Handle<ShaderStorageBuffer>)

Implementations

impl Readback

pub fn texture(image: Handle<Image>) -> Readback

Create a readback component for a texture using the given handle.

Examples found in repository

examples/shader/gpu_readback.rs (line 117)

fn setup(
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
    mut buffers: ResMut<Assets<ShaderStorageBuffer>>,
) {
    // Create a storage buffer with some data
    let buffer = vec![0u32; BUFFER_LEN];
    let mut buffer = ShaderStorageBuffer::from(buffer);
    // We need to enable the COPY_SRC usage so we can copy the buffer to the cpu
    buffer.buffer_description.usage |= BufferUsages::COPY_SRC;
    let buffer = buffers.add(buffer);

    // Create a storage texture with some data
    let size = Extent3d {
        width: BUFFER_LEN as u32,
        height: 1,
        ..default()
    };
    let mut image = Image::new_fill(
        size,
        TextureDimension::D2,
        &[0, 0, 0, 0],
        TextureFormat::R32Uint,
        RenderAssetUsages::RENDER_WORLD,
    );
    // We also need to enable the COPY_SRC, as well as STORAGE_BINDING so we can use it in the
    // compute shader
    image.texture_descriptor.usage |= TextureUsages::COPY_SRC | TextureUsages::STORAGE_BINDING;
    let image = images.add(image);

    // Spawn the readback components. For each frame, the data will be read back from the GPU
    // asynchronously and trigger the `ReadbackComplete` event on this entity. Despawn the entity
    // to stop reading back the data.
    commands.spawn(Readback::buffer(buffer.clone())).observe(
        |trigger: Trigger<ReadbackComplete>| {
            // This matches the type which was used to create the `ShaderStorageBuffer` above,
            // and is a convenient way to interpret the data.
            let data: Vec<u32> = trigger.event().to_shader_type();
            info!("Buffer {:?}", data);
        },
    );
    // This is just a simple way to pass the buffer handle to the render app for our compute node
    commands.insert_resource(ReadbackBuffer(buffer));

    // Textures can also be read back from the GPU. Pay careful attention to the format of the
    // texture, as it will affect how the data is interpreted.
    commands.spawn(Readback::texture(image.clone())).observe(
        |trigger: Trigger<ReadbackComplete>| {
            // You probably want to interpret the data as a color rather than a `ShaderType`,
            // but in this case we know the data is a single channel storage texture, so we can
            // interpret it as a `Vec<u32>`
            let data: Vec<u32> = trigger.event().to_shader_type();
            info!("Image {:?}", data);
        },
    );
    commands.insert_resource(ReadbackImage(image));
}

pub fn buffer(buffer: Handle<ShaderStorageBuffer>) -> Readback

Create a readback component for a buffer using the given handle.

Examples found in repository

examples/shader/gpu_readback.rs (line 104)

fn setup(
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
    mut buffers: ResMut<Assets<ShaderStorageBuffer>>,
) {
    // Create a storage buffer with some data
    let buffer = vec![0u32; BUFFER_LEN];
    let mut buffer = ShaderStorageBuffer::from(buffer);
    // We need to enable the COPY_SRC usage so we can copy the buffer to the cpu
    buffer.buffer_description.usage |= BufferUsages::COPY_SRC;
    let buffer = buffers.add(buffer);

    // Create a storage texture with some data
    let size = Extent3d {
        width: BUFFER_LEN as u32,
        height: 1,
        ..default()
    };
    let mut image = Image::new_fill(
        size,
        TextureDimension::D2,
        &[0, 0, 0, 0],
        TextureFormat::R32Uint,
        RenderAssetUsages::RENDER_WORLD,
    );
    // We also need to enable the COPY_SRC, as well as STORAGE_BINDING so we can use it in the
    // compute shader
    image.texture_descriptor.usage |= TextureUsages::COPY_SRC | TextureUsages::STORAGE_BINDING;
    let image = images.add(image);

    // Spawn the readback components. For each frame, the data will be read back from the GPU
    // asynchronously and trigger the `ReadbackComplete` event on this entity. Despawn the entity
    // to stop reading back the data.
    commands.spawn(Readback::buffer(buffer.clone())).observe(
        |trigger: Trigger<ReadbackComplete>| {
            // This matches the type which was used to create the `ShaderStorageBuffer` above,
            // and is a convenient way to interpret the data.
            let data: Vec<u32> = trigger.event().to_shader_type();
            info!("Buffer {:?}", data);
        },
    );
    // This is just a simple way to pass the buffer handle to the render app for our compute node
    commands.insert_resource(ReadbackBuffer(buffer));

    // Textures can also be read back from the GPU. Pay careful attention to the format of the
    // texture, as it will affect how the data is interpreted.
    commands.spawn(Readback::texture(image.clone())).observe(
        |trigger: Trigger<ReadbackComplete>| {
            // You probably want to interpret the data as a color rather than a `ShaderType`,
            // but in this case we know the data is a single channel storage texture, so we can
            // interpret it as a `Vec<u32>`
            let data: Vec<u32> = trigger.event().to_shader_type();
            info!("Image {:?}", data);
        },
    );
    commands.insert_resource(ReadbackImage(image));
}

Trait Implementations

impl Clone for Readback

fn clone(&self) -> Readback

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Component for Readback

where Readback: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_required_components( requiree: ComponentId, components: &mut Components, storages: &mut Storages, required_components: &mut RequiredComponents, inheritance_depth: u16, )

Registers required components.

fn register_component_hooks(hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl Debug for Readback

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl ExtractComponent for Readback

where Readback: Clone,

type QueryData = &'static Readback

ECS ReadOnlyQueryData to fetch the components to extract.

type QueryFilter = ()

Filters the entities with additional constraints.

type Out = Readback

The output from extraction.

fn extract_component( item: <<Readback as ExtractComponent>::QueryData as WorldQuery>::Item<'_>, ) -> Option<<Readback as ExtractComponent>::Out>

Defines how the component is transferred into the “render world”.