Struct Image 

pub struct Image {
    pub data: Option<Vec<u8>>,
    pub data_order: TextureDataOrder,
    pub texture_descriptor: TextureDescriptor<Option<&'static str>, &'static [TextureFormat]>,
    pub sampler: ImageSampler,
    pub texture_view_descriptor: Option<TextureViewDescriptor<Option<&'static str>>>,
    pub asset_usage: RenderAssetUsages,
    pub copy_on_resize: bool,
}

An image, optimized for usage in rendering.

Remote Inspection

To transmit an Image between two running Bevy apps, e.g. through BRP, use SerializedImage. This type is only meant for short-term transmission between same versions and should not be stored anywhere.

Fields

data: Option<Vec<u8>>

Raw pixel data. If the image is being used as a storage texture which doesn’t need to be initialized by the CPU, then this should be None. Otherwise, it should always be Some.

data_order: TextureDataOrder

For texture data with layers and mips, this field controls how wgpu interprets the buffer layout.

Use TextureDataOrder::default() for all other cases.

texture_descriptor: TextureDescriptor<Option<&'static str>, &'static [TextureFormat]>

Describes the data layout of the GPU texture.
For example, whether a texture contains 1D/2D/3D data, and what the format of the texture data is.

Field Usage Notes

• TextureDescriptor::label is used for caching purposes when not using Asset<Image>.
  If you use assets, the label is purely a debugging aid.
• TextureDescriptor::view_formats is currently unused by Bevy.

sampler: ImageSampler

The ImageSampler to use during rendering.

texture_view_descriptor: Option<TextureViewDescriptor<Option<&'static str>>>

Describes how the GPU texture should be interpreted.
For example, 2D image data could be read as plain 2D, an array texture of layers of 2D with the same dimensions (and the number of layers in that case), a cube map, an array of cube maps, etc.

Field Usage Notes

• TextureViewDescriptor::label is used for caching purposes when not using Asset<Image>.
  If you use assets, the label is purely a debugging aid.

asset_usage: RenderAssetUsages

Where this image asset will be used. See RenderAssetUsages for more.

copy_on_resize: bool

Whether this image should be copied on the GPU when resized.

Implementations

impl Image

pub fn new( size: Extent3d, dimension: TextureDimension, data: Vec<u8>, format: TextureFormat, asset_usage: RenderAssetUsages, ) -> Image

Creates a new image from raw binary data and the corresponding metadata.

Panics

Panics if the length of the data, volume of the size and the size of the format do not match.

Examples found in repository

examples/testbed/3d.rs (lines 538-548)

    fn create_white_cubemap(size: u32) -> Image {
        // f16 bytes for 1.0 (white): [0, 60] in little-endian
        const WHITE_F16: [u8; 2] = [0, 60];
        const WHITE_PIXEL: [u8; 8] = [
            WHITE_F16[0],
            WHITE_F16[1], // R
            WHITE_F16[0],
            WHITE_F16[1], // G
            WHITE_F16[0],
            WHITE_F16[1], // B
            WHITE_F16[0],
            WHITE_F16[1], // A
        ];

        let pixel_data: Vec<u8> = (0..6 * size * size).flat_map(|_| WHITE_PIXEL).collect();

        Image {
            texture_view_descriptor: Some(TextureViewDescriptor {
                dimension: Some(TextureViewDimension::Cube),
                ..Default::default()
            }),
            ..Image::new(
                Extent3d {
                    width: size,
                    height: size,
                    depth_or_array_layers: 6,
                },
                TextureDimension::D2,
                pixel_data,
                TextureFormat::Rgba16Float,
                RenderAssetUsages::RENDER_WORLD,
            )
        }
    }

    pub fn setup(
        mut commands: Commands,
        mut meshes: ResMut<Assets<Mesh>>,
        mut materials: ResMut<Assets<StandardMaterial>>,
        mut images: ResMut<Assets<Image>>,
    ) {
        let sphere_mesh = meshes.add(Sphere::new(0.45));

        // Light should come from the environment map only
        commands.insert_resource(GlobalAmbientLight::NONE);

        // add entities to the world
        for y in -2..=2 {
            for x in -5..=5 {
                let x01 = (x + 5) as f32 / 10.0;
                let y01 = (y + 2) as f32 / 4.0;
                // sphere
                commands.spawn((
                    Mesh3d(sphere_mesh.clone()),
                    MeshMaterial3d(materials.add(StandardMaterial {
                        base_color: LinearRgba::WHITE.into(),
                        // vary key PBR parameters on a grid of spheres to show the effect
                        metallic: y01,
                        perceptual_roughness: x01,
                        ..default()
                    })),
                    Transform::from_xyz(x as f32, y as f32 + 0.5, 0.0),
                    DespawnOnExit(CURRENT_SCENE),
                ));
            }
        }

        // Create a pure white cubemap
        let white_cubemap = create_white_cubemap(256);
        let white_cubemap_handle = images.add(white_cubemap);

        let mut solid_color_light = EnvironmentMapLight::solid_color(&mut images, Color::WHITE);
        solid_color_light.intensity = 500.0;

        // camera
        commands.spawn((
            Camera3d::default(),
            Hdr,
            Tonemapping::None,
            Transform::from_xyz(0.0, 0.0, 8.0).looking_at(Vec3::default(), Vec3::Y),
            Projection::from(OrthographicProjection {
                scale: 0.01,
                scaling_mode: ScalingMode::WindowSize,
                ..OrthographicProjection::default_3d()
            }),
            Skybox {
                image: Some(white_cubemap_handle),
                // middle gray
                brightness: 500.0,
                ..default()
            },
            solid_color_light,
            DespawnOnExit(CURRENT_SCENE),
        ));
    }
}

mod white_furnace_environment_map_light {
    use bevy::{
        asset::RenderAssetUsages,
        camera::{Hdr, ScalingMode},
        core_pipeline::tonemapping::Tonemapping,
        light::Skybox,
        prelude::*,
        render::render_resource::{
            Extent3d, TextureDimension, TextureFormat, TextureViewDescriptor, TextureViewDimension,
        },
    };

    const CURRENT_SCENE: super::Scene = super::Scene::WhiteFurnaceEnvironmentMapLight;

    /// Creates a pure white cubemap
    fn create_white_cubemap(size: u32) -> Image {
        // f16 bytes for 1.0 (white): [0, 60] in little-endian
        const WHITE_F16: [u8; 2] = [0, 60];
        const WHITE_PIXEL: [u8; 8] = [
            WHITE_F16[0],
            WHITE_F16[1], // R
            WHITE_F16[0],
            WHITE_F16[1], // G
            WHITE_F16[0],
            WHITE_F16[1], // B
            WHITE_F16[0],
            WHITE_F16[1], // A
        ];

        let pixel_data: Vec<u8> = (0..6 * size * size).flat_map(|_| WHITE_PIXEL).collect();

        Image {
            texture_view_descriptor: Some(TextureViewDescriptor {
                dimension: Some(TextureViewDimension::Cube),
                ..Default::default()
            }),
            ..Image::new(
                Extent3d {
                    width: size,
                    height: size,
                    depth_or_array_layers: 6,
                },
                TextureDimension::D2,
                pixel_data,
                TextureFormat::Rgba16Float,
                RenderAssetUsages::RENDER_WORLD,
            )
        }
    }

pub fn new_uninit( size: Extent3d, dimension: TextureDimension, format: TextureFormat, asset_usage: RenderAssetUsages, ) -> Image

Exactly the same as Image::new, but doesn’t initialize the image

Examples found in repository

examples/3d/mirror.rs (lines 430-435)

fn create_mirror_texture_image(images: &mut Assets<Image>, window_size: UVec2) -> Handle<Image> {
    let mirror_image_extent = Extent3d {
        width: window_size.x,
        height: window_size.y,
        depth_or_array_layers: 1,
    };

    let mut image = Image::new_uninit(
        mirror_image_extent,
        TextureDimension::D2,
        TextureFormat::Bgra8UnormSrgb,
        RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD,
    );
    image.texture_descriptor.usage |=
        TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST | TextureUsages::RENDER_ATTACHMENT;

    images.add(image)
}

examples/app/externally_driven_headless_renderer.rs (lines 76-85)

    fn new_render_target(&mut self, width: u32, height: u32) -> RenderTarget {
        let mut target = Image::new_uninit(
            Extent3d {
                width,
                height,
                depth_or_array_layers: 1,
            },
            TextureDimension::D2,
            TextureFormat::Rgba8UnormSrgb,
            RenderAssetUsages::RENDER_WORLD,
        );
        // We're going to render to this image, mark it as such
        target.texture_descriptor.usage |= TextureUsages::RENDER_ATTACHMENT;
        self.0
            .main
            .world_mut()
            .resource_mut::<Assets<Image>>()
            .add(target)
            .into()
    }

examples/2d/dynamic_mip_generation.rs (lines 773-782)

    fn regenerate_mipmap_source_image(
        &mut self,
        commands: &mut Commands,
        images: &mut Assets<Image>,
    ) -> Handle<Image> {
        let image_data = self.generate_image_data();

        let mut image = Image::new_uninit(
            Extent3d {
                width: self.image_width as u32,
                height: self.image_height as u32,
                depth_or_array_layers: 1,
            },
            TextureDimension::D2,
            TextureFormat::Rgba8Unorm,
            RenderAssetUsages::all(),
        );
        image.texture_descriptor.mip_level_count = self.image_mip_level_count();
        image.texture_descriptor.usage |= TextureUsages::STORAGE_BINDING;
        image.data = Some(image_data);

        let image_handle = images.add(image);
        commands.insert_resource(MipmapSourceImage(image_handle.clone()));

        image_handle
    }

examples/shader_advanced/render_depth_to_texture.rs (lines 311-320)

    fn from_world(world: &mut World) -> Self {
        let mut images = world.resource_mut::<Assets<Image>>();

        // Create a new 32-bit floating point depth texture.
        let mut depth_image = Image::new_uninit(
            Extent3d {
                width: DEPTH_TEXTURE_SIZE,
                height: DEPTH_TEXTURE_SIZE,
                depth_or_array_layers: 1,
            },
            TextureDimension::D2,
            TextureFormat::Depth32Float,
            RenderAssetUsages::default(),
        );

        // Create a sampler. Note that this needs to specify a `compare`
        // function in order to be compatible with depth textures.
        depth_image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
            label: Some("custom depth image sampler".to_owned()),
            compare: Some(ImageCompareFunction::Always),
            ..ImageSamplerDescriptor::default()
        });

        let depth_image_handle = images.add(depth_image);
        DemoDepthTexture(depth_image_handle)
    }

examples/ui/widgets/viewport_node.rs (lines 36-41)

fn test(
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Spawn a UI camera
    commands.spawn(Camera3d::default());

    // Set up an texture for the 3D camera to render to.
    // The size of the texture will be based on the viewport's ui size.
    let mut image = Image::new_uninit(
        default(),
        TextureDimension::D2,
        TextureFormat::Bgra8UnormSrgb,
        RenderAssetUsages::all(),
    );
    image.texture_descriptor.usage =
        TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST | TextureUsages::RENDER_ATTACHMENT;
    let image_handle = images.add(image);

    // Spawn the 3D camera
    let camera = commands
        .spawn((
            Camera3d::default(),
            Camera {
                // Render this camera before our UI camera
                order: -1,
                ..default()
            },
            RenderTarget::Image(image_handle.clone().into()),
        ))
        .id();

    // Spawn something for the 3D camera to look at
    commands
        .spawn((
            Mesh3d(meshes.add(Cuboid::new(5.0, 5.0, 5.0))),
            MeshMaterial3d(materials.add(Color::WHITE)),
            Transform::from_xyz(0.0, 0.0, -10.0),
            Shape,
        ))
        // We can observe pointer events on our objects as normal, the
        // `bevy::ui::widget::viewport_picking` system will take care of ensuring our viewport
        // clicks pass through
        .observe(on_drag_cuboid);

    // Spawn our viewport widget
    commands
        .spawn((
            Node {
                position_type: PositionType::Absolute,
                top: px(50),
                left: px(50),
                width: px(200),
                height: px(200),
                border: UiRect::all(px(5)),
                ..default()
            },
            BorderColor::all(Color::WHITE),
            ViewportNode::new(camera),
        ))
        .observe(on_drag_viewport);
}

examples/shader/gpu_readback.rs (lines 87-92)

fn setup(
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
    mut buffers: ResMut<Assets<ShaderBuffer>>,
) {
    // Create a storage buffer with some data
    let buffer: Vec<u32> = (0..BUFFER_LEN as u32).collect();
    let mut buffer = ShaderBuffer::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()
    };
    // We create an uninitialized image since this texture will only be used for getting data out
    // of the compute shader, not getting data in, so there's no reason for it to exist on the CPU
    let mut image = Image::new_uninit(
        size,
        TextureDimension::D2,
        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(|event: On<ReadbackComplete>| {
            // This matches the type which was used to create the `ShaderBuffer` above,
            // and is a convenient way to interpret the data.
            let data: Vec<u32> = event.to_shader_type();
            info!("Buffer {:?}", data);
        });

    // It is also possible to read only a range of the buffer.
    commands
        .spawn(Readback::buffer_range(
            buffer.clone(),
            4 * u32::SHADER_SIZE.get(), // skip the first four elements
            8 * u32::SHADER_SIZE.get(), // read eight elements
        ))
        .observe(|event: On<ReadbackComplete>| {
            let data: Vec<u32> = event.to_shader_type();
            info!("Buffer range {:?}", 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(|event: On<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> = event.to_shader_type();
            info!("Image {:?}", data);
        });
    commands.insert_resource(ReadbackImage(image));
}

pub fn transparent() -> Image

A transparent white 1x1x1 image.

Contrast to Image::default, which is opaque.

pub fn default_uninit() -> Image

Creates a new uninitialized 1x1x1 image

pub fn new_fill( size: Extent3d, dimension: TextureDimension, pixel: &[u8], format: TextureFormat, asset_usage: RenderAssetUsages, ) -> Image

Creates a new image from raw binary data and the corresponding metadata, by filling the image data with the pixel data repeated multiple times.

Panics

Panics if the size of the format is not a multiple of the length of the pixel data.

Examples found in repository

examples/stress_tests/bevymark_3d.rs (lines 490-500)

fn init_textures(textures: &mut Vec<Handle<Image>>, args: &Args, images: &mut Assets<Image>) {
    let mut color_rng = ChaCha8Rng::seed_from_u64(42);
    while textures.len() < args.material_texture_count {
        let pixel = [
            color_rng.random(),
            color_rng.random(),
            color_rng.random(),
            255,
        ];
        textures.push(images.add(Image::new_fill(
            Extent3d {
                width: CUBE_TEXTURE_SIZE as u32,
                height: CUBE_TEXTURE_SIZE as u32,
                depth_or_array_layers: 1,
            },
            TextureDimension::D2,
            &pixel,
            TextureFormat::Rgba8UnormSrgb,
            RenderAssetUsages::RENDER_WORLD,
        )));
    }
}

examples/3d/3d_shapes.rs (lines 247-257)

fn uv_debug_texture() -> Image {
    const TEXTURE_SIZE: usize = 8;

    let mut palette: [u8; 32] = [
        255, 102, 159, 255, 255, 159, 102, 255, 236, 255, 102, 255, 121, 255, 102, 255, 102, 255,
        198, 255, 102, 198, 255, 255, 121, 102, 255, 255, 236, 102, 255, 255,
    ];

    let mut texture_data = [0; TEXTURE_SIZE * TEXTURE_SIZE * 4];
    for y in 0..TEXTURE_SIZE {
        let offset = TEXTURE_SIZE * y * 4;
        texture_data[offset..(offset + TEXTURE_SIZE * 4)].copy_from_slice(&palette);
        palette.rotate_right(4);
    }

    Image::new_fill(
        Extent3d {
            width: TEXTURE_SIZE as u32,
            height: TEXTURE_SIZE as u32,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        &texture_data,
        TextureFormat::Rgba8UnormSrgb,
        RenderAssetUsages::RENDER_WORLD,
    )
}

examples/stress_tests/many_cubes.rs (lines 375-381)

fn init_textures(args: &Args, images: &mut Assets<Image>) -> Vec<Handle<Image>> {
    // We're seeding the PRNG here to make this example deterministic for testing purposes.
    // This isn't strictly required in practical use unless you need your app to be deterministic.
    let mut color_rng = ChaCha8Rng::seed_from_u64(42);
    let color_bytes: Vec<u8> = (0..(args.material_texture_count * 4))
        .map(|i| {
            if (i % 4) == 3 {
                255
            } else {
                color_rng.random()
            }
        })
        .collect();
    color_bytes
        .chunks(4)
        .map(|pixel| {
            images.add(Image::new_fill(
                Extent3d::default(),
                TextureDimension::D2,
                pixel,
                TextureFormat::Rgba8UnormSrgb,
                RenderAssetUsages::RENDER_WORLD,
            ))
        })
        .collect()
}

examples/stress_tests/bevymark.rs (lines 632-642)

fn init_textures(textures: &mut Vec<Handle<Image>>, args: &Args, images: &mut Assets<Image>) {
    // We're seeding the PRNG here to make this example deterministic for testing purposes.
    // This isn't strictly required in practical use unless you need your app to be deterministic.
    let mut color_rng = ChaCha8Rng::seed_from_u64(42);
    while textures.len() < args.material_texture_count {
        let pixel = [
            color_rng.random(),
            color_rng.random(),
            color_rng.random(),
            255,
        ];
        textures.push(images.add(Image::new_fill(
            Extent3d {
                width: BIRD_TEXTURE_SIZE as u32,
                height: BIRD_TEXTURE_SIZE as u32,
                depth_or_array_layers: 1,
            },
            TextureDimension::D2,
            &pixel,
            TextureFormat::Rgba8UnormSrgb,
            RenderAssetUsages::RENDER_WORLD,
        )));
    }
}

examples/3d/anti_aliasing.rs (lines 519-529)

fn uv_debug_texture() -> Image {
    const TEXTURE_SIZE: usize = 8;

    let mut palette: [u8; 32] = [
        255, 102, 159, 255, 255, 159, 102, 255, 236, 255, 102, 255, 121, 255, 102, 255, 102, 255,
        198, 255, 102, 198, 255, 255, 121, 102, 255, 255, 236, 102, 255, 255,
    ];

    let mut texture_data = [0; TEXTURE_SIZE * TEXTURE_SIZE * 4];
    for y in 0..TEXTURE_SIZE {
        let offset = TEXTURE_SIZE * y * 4;
        texture_data[offset..(offset + TEXTURE_SIZE * 4)].copy_from_slice(&palette);
        palette.rotate_right(4);
    }

    let mut img = Image::new_fill(
        Extent3d {
            width: TEXTURE_SIZE as u32,
            height: TEXTURE_SIZE as u32,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        &texture_data,
        TextureFormat::Rgba8UnormSrgb,
        RenderAssetUsages::RENDER_WORLD,
    );
    img.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor::default());
    img
}

examples/3d/motion_blur.rs (lines 371-381)

fn uv_debug_texture() -> Image {
    use bevy::{asset::RenderAssetUsages, render::render_resource::*};
    const TEXTURE_SIZE: usize = 7;

    let mut palette = [
        164, 164, 164, 255, 168, 168, 168, 255, 153, 153, 153, 255, 139, 139, 139, 255, 153, 153,
        153, 255, 177, 177, 177, 255, 159, 159, 159, 255,
    ];

    let mut texture_data = [0; TEXTURE_SIZE * TEXTURE_SIZE * 4];
    for y in 0..TEXTURE_SIZE {
        let offset = TEXTURE_SIZE * y * 4;
        texture_data[offset..(offset + TEXTURE_SIZE * 4)].copy_from_slice(&palette);
        palette.rotate_right(12);
    }

    let mut img = Image::new_fill(
        Extent3d {
            width: TEXTURE_SIZE as u32,
            height: TEXTURE_SIZE as u32,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        &texture_data,
        TextureFormat::Rgba8UnormSrgb,
        RenderAssetUsages::RENDER_WORLD,
    );
    img.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
        address_mode_u: ImageAddressMode::Repeat,
        address_mode_v: ImageAddressMode::MirrorRepeat,
        mag_filter: ImageFilterMode::Nearest,
        ..ImageSamplerDescriptor::linear()
    });
    img
}

Additional examples can be found in:

• examples/2d/cpu_draw.rs
• examples/asset/asset_saving.rs
• examples/testbed/2d.rs
• examples/ui/render_ui_to_texture.rs

pub fn new_target_texture( width: u32, height: u32, format: TextureFormat, view_format: Option<TextureFormat>, ) -> Image

Create a new zero-filled image with a given size, which can be rendered to. Useful for mirrors, UI, or exporting images for example. This is primarily for use as a render target for a Camera. See RenderTarget::Image.

For Standard Dynamic Range (SDR) images you can use TextureFormat::Rgba8UnormSrgb. For High Dynamic Range (HDR) images you can use TextureFormat::Rgba16Float.

The default TextureUsages are TEXTURE_BINDING, COPY_DST, RENDER_ATTACHMENT.

The default RenderAssetUsages is MAIN_WORLD | RENDER_WORLD so that it is accessible from the CPU and GPU. You can customize this by changing the asset_usage field.

Examples found in repository

examples/shader/compute_shader_game_of_life.rs (line 55)

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    let mut image = Image::new_target_texture(SIZE.x, SIZE.y, TextureFormat::Rgba32Float, None);
    image.asset_usage = RenderAssetUsages::RENDER_WORLD;
    image.texture_descriptor.usage =
        TextureUsages::COPY_DST | TextureUsages::STORAGE_BINDING | TextureUsages::TEXTURE_BINDING;
    let image0 = images.add(image.clone());
    let image1 = images.add(image);

    commands.spawn((
        Sprite {
            image: image0.clone(),
            custom_size: Some(SIZE.as_vec2()),
            ..default()
        },
        Transform::from_scale(Vec3::splat(DISPLAY_FACTOR as f32)),
    ));
    commands.spawn(Camera2d);

    commands.insert_resource(GameOfLifeImages {
        texture_a: image0,
        texture_b: image1,
    });

    commands.insert_resource(GameOfLifeUniforms {
        alive_color: LinearRgba::RED,
    });
}

examples/app/headless_renderer.rs (line 243)

fn setup_render_target(
    commands: &mut Commands,
    images: &mut ResMut<Assets<Image>>,
    render_device: &Res<RenderDevice>,
    scene_controller: &mut ResMut<SceneController>,
    pre_roll_frames: u32,
    scene_name: String,
) -> RenderTarget {
    let size = Extent3d {
        width: scene_controller.width,
        height: scene_controller.height,
        ..Default::default()
    };

    // This is the texture that will be rendered to.
    let mut render_target_image =
        Image::new_target_texture(size.width, size.height, TextureFormat::Rgba8UnormSrgb, None);
    render_target_image.texture_descriptor.usage |= TextureUsages::COPY_SRC;
    let render_target_image_handle = images.add(render_target_image);

    // This is the texture that will be copied to.
    let cpu_image =
        Image::new_target_texture(size.width, size.height, TextureFormat::Rgba8UnormSrgb, None);
    let cpu_image_handle = images.add(cpu_image);

    commands.spawn(ImageCopier::new(
        render_target_image_handle.clone(),
        size,
        render_device,
    ));

    commands.spawn(ImageToSave(cpu_image_handle));

    scene_controller.state = SceneState::Render(pre_roll_frames);
    scene_controller.name = scene_name;
    RenderTarget::Image(render_target_image_handle.into())
}

examples/3d/render_to_texture.rs (lines 31-36)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
    mut images: ResMut<Assets<Image>>,
) {
    // This is the texture that will be rendered to.
    let image = Image::new_target_texture(
        512,
        512,
        TextureFormat::Rgba8Unorm,
        Some(TextureFormat::Rgba8UnormSrgb),
    );

    let image_handle = images.add(image);

    let cube_handle = meshes.add(Cuboid::new(4.0, 4.0, 4.0));
    let cube_material_handle = materials.add(StandardMaterial {
        base_color: Color::srgb(0.8, 0.7, 0.6),
        reflectance: 0.02,
        unlit: false,
        ..default()
    });

    // This specifies the layer used for the first pass, which will be attached to the first pass camera and cube.
    let first_pass_layer = RenderLayers::layer(1);

    // The cube that will be rendered to the texture.
    commands.spawn((
        Mesh3d(cube_handle),
        MeshMaterial3d(cube_material_handle),
        Transform::from_translation(Vec3::new(0.0, 0.0, 1.0)),
        FirstPassCube,
        first_pass_layer.clone(),
    ));

    // Light
    // NOTE: we add the light to both layers so it affects both the rendered-to-texture cube, and the cube on which we display the texture
    // Setting the layer to RenderLayers::layer(0) would cause the main view to be lit, but the rendered-to-texture cube to be unlit.
    // Setting the layer to RenderLayers::layer(1) would cause the rendered-to-texture cube to be lit, but the main view to be unlit.
    commands.spawn((
        PointLight::default(),
        Transform::from_translation(Vec3::new(0.0, 0.0, 10.0)),
        RenderLayers::layer(0).with(1),
    ));

    commands.spawn((
        Camera3d::default(),
        Camera {
            // render before the "main pass" camera
            order: -1,
            clear_color: Color::WHITE.into(),
            ..default()
        },
        RenderTarget::Image(image_handle.clone().into()),
        Transform::from_translation(Vec3::new(0.0, 0.0, 15.0)).looking_at(Vec3::ZERO, Vec3::Y),
        first_pass_layer,
    ));

    let cube_size = 4.0;
    let cube_handle = meshes.add(Cuboid::new(cube_size, cube_size, cube_size));

    // This material has the texture that has been rendered.
    let material_handle = materials.add(StandardMaterial {
        base_color_texture: Some(image_handle),
        reflectance: 0.02,
        unlit: false,
        ..default()
    });

    // Main pass cube, with material containing the rendered first pass texture.
    commands.spawn((
        Mesh3d(cube_handle),
        MeshMaterial3d(material_handle),
        Transform::from_xyz(0.0, 0.0, 1.5).with_rotation(Quat::from_rotation_x(-PI / 5.0)),
        MainPassCube,
    ));

    // The main pass camera.
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 0.0, 15.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

pub fn width(&self) -> u32

Returns the width of a 2D image.

Examples found in repository

examples/ui/text/font_atlas_debug.rs (line 58)

fn atlas_render_system(
    mut commands: Commands,
    mut state: ResMut<State>,
    font_atlas_set: Res<FontAtlasSet>,
    images: Res<Assets<Image>>,
) {
    if let Some(font_atlases) = font_atlas_set.values().next() {
        let x_offset = state.atlas_count as f32;
        if state.atlas_count == font_atlases.len() as u32 {
            return;
        }
        let font_atlas = &font_atlases[state.atlas_count as usize];
        let image = images.get(&font_atlas.texture).unwrap();
        state.atlas_count += 1;
        commands.spawn((
            ImageNode::new(font_atlas.texture.clone()),
            Node {
                position_type: PositionType::Absolute,
                top: Val::ZERO,
                left: px(image.width() as f32 * x_offset),
                ..default()
            },
        ));
    }
}

examples/3d/skybox.rs (line 160)

fn asset_loaded(
    asset_server: Res<AssetServer>,
    mut images: ResMut<Assets<Image>>,
    mut cubemap: ResMut<Cubemap>,
    mut skyboxes: Query<&mut Skybox>,
) {
    if !cubemap.is_loaded && asset_server.load_state(&cubemap.image_handle).is_loaded() {
        info!("Swapping to {}...", CUBEMAPS[cubemap.index].0);
        let mut image = images.get_mut(&cubemap.image_handle).unwrap();
        // NOTE: PNGs do not have any metadata that could indicate they contain a cubemap texture,
        // so they appear as one texture. The following code reconfigures the texture as necessary.
        if image.texture_descriptor.array_layer_count() == 1 {
            let layers = image.height() / image.width();
            image
                .reinterpret_stacked_2d_as_array(layers)
                .expect("asset should be 2d texture and height will always be evenly divisible with the given layers");
            image.texture_view_descriptor = Some(TextureViewDescriptor {
                dimension: Some(TextureViewDimension::Cube),
                ..default()
            });
        }

        for mut skybox in &mut skyboxes {
            skybox.image = Some(cubemap.image_handle.clone());
        }

        cubemap.is_loaded = true;
    }
}

examples/app/headless_renderer.rs (line 476)

fn update(
    images_to_save: Query<&ImageToSave>,
    receiver: Res<MainWorldReceiver>,
    mut images: ResMut<Assets<Image>>,
    mut scene_controller: ResMut<SceneController>,
    mut app_exit_writer: MessageWriter<AppExit>,
    mut file_number: Local<u32>,
) {
    if let SceneState::Render(n) = scene_controller.state {
        if n < 1 {
            // We don't want to block the main world on this,
            // so we use try_recv which attempts to receive without blocking
            let mut image_data = Vec::new();
            while let Ok(data) = receiver.try_recv() {
                // image generation could be faster than saving to fs,
                // that's why use only last of them
                image_data = data;
            }
            if !image_data.is_empty() {
                for image in images_to_save.iter() {
                    // Fill correct data from channel to image
                    let mut img_bytes = images.get_mut(image.id()).unwrap();

                    // We need to ensure that this works regardless of the image dimensions
                    // If the image became wider when copying from the texture to the buffer,
                    // then the data is reduced to its original size when copying from the buffer to the image.
                    let row_bytes = img_bytes.width() as usize
                        * img_bytes.texture_descriptor.format.pixel_size().unwrap();
                    let aligned_row_bytes = RenderDevice::align_copy_bytes_per_row(row_bytes);
                    if row_bytes == aligned_row_bytes {
                        img_bytes.data.as_mut().unwrap().clone_from(&image_data);
                    } else {
                        // shrink data to original image size
                        img_bytes.data = Some(
                            image_data
                                .chunks(aligned_row_bytes)
                                .take(img_bytes.height() as usize)
                                .flat_map(|row| &row[..row_bytes.min(row.len())])
                                .cloned()
                                .collect(),
                        );
                    }

                    // Create RGBA Image Buffer
                    let img = match img_bytes.clone().try_into_dynamic() {
                        Ok(img) => img.to_rgba8(),
                        Err(e) => panic!("Failed to create image buffer {e:?}"),
                    };

                    // Prepare directory for images, test_images in bevy folder is used here for example
                    // You should choose the path depending on your needs
                    let images_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test_images");
                    info!("Saving image to: {images_dir:?}");
                    std::fs::create_dir_all(&images_dir).unwrap();

                    // Choose filename starting from 000.png
                    let image_path = images_dir.join(format!("{:03}.png", file_number.deref()));
                    *file_number.deref_mut() += 1;

                    // Finally saving image to file, this heavy blocking operation is kept here
                    // for example simplicity, but in real app you should move it to a separate task
                    if let Err(e) = img.save(image_path) {
                        panic!("Failed to save image: {e}");
                    };
                }
                if scene_controller.single_image {
                    app_exit_writer.write(AppExit::Success);
                }
            }
        } else {
            // clears channel for skipped frames
            while receiver.try_recv().is_ok() {}
            scene_controller.state = SceneState::Render(n - 1);
        }
    }
}

pub fn height(&self) -> u32

Returns the height of a 2D image.

Examples found in repository

examples/3d/skybox.rs (line 160)

fn asset_loaded(
    asset_server: Res<AssetServer>,
    mut images: ResMut<Assets<Image>>,
    mut cubemap: ResMut<Cubemap>,
    mut skyboxes: Query<&mut Skybox>,
) {
    if !cubemap.is_loaded && asset_server.load_state(&cubemap.image_handle).is_loaded() {
        info!("Swapping to {}...", CUBEMAPS[cubemap.index].0);
        let mut image = images.get_mut(&cubemap.image_handle).unwrap();
        // NOTE: PNGs do not have any metadata that could indicate they contain a cubemap texture,
        // so they appear as one texture. The following code reconfigures the texture as necessary.
        if image.texture_descriptor.array_layer_count() == 1 {
            let layers = image.height() / image.width();
            image
                .reinterpret_stacked_2d_as_array(layers)
                .expect("asset should be 2d texture and height will always be evenly divisible with the given layers");
            image.texture_view_descriptor = Some(TextureViewDescriptor {
                dimension: Some(TextureViewDimension::Cube),
                ..default()
            });
        }

        for mut skybox in &mut skyboxes {
            skybox.image = Some(cubemap.image_handle.clone());
        }

        cubemap.is_loaded = true;
    }
}

examples/app/headless_renderer.rs (line 486)

fn update(
    images_to_save: Query<&ImageToSave>,
    receiver: Res<MainWorldReceiver>,
    mut images: ResMut<Assets<Image>>,
    mut scene_controller: ResMut<SceneController>,
    mut app_exit_writer: MessageWriter<AppExit>,
    mut file_number: Local<u32>,
) {
    if let SceneState::Render(n) = scene_controller.state {
        if n < 1 {
            // We don't want to block the main world on this,
            // so we use try_recv which attempts to receive without blocking
            let mut image_data = Vec::new();
            while let Ok(data) = receiver.try_recv() {
                // image generation could be faster than saving to fs,
                // that's why use only last of them
                image_data = data;
            }
            if !image_data.is_empty() {
                for image in images_to_save.iter() {
                    // Fill correct data from channel to image
                    let mut img_bytes = images.get_mut(image.id()).unwrap();

                    // We need to ensure that this works regardless of the image dimensions
                    // If the image became wider when copying from the texture to the buffer,
                    // then the data is reduced to its original size when copying from the buffer to the image.
                    let row_bytes = img_bytes.width() as usize
                        * img_bytes.texture_descriptor.format.pixel_size().unwrap();
                    let aligned_row_bytes = RenderDevice::align_copy_bytes_per_row(row_bytes);
                    if row_bytes == aligned_row_bytes {
                        img_bytes.data.as_mut().unwrap().clone_from(&image_data);
                    } else {
                        // shrink data to original image size
                        img_bytes.data = Some(
                            image_data
                                .chunks(aligned_row_bytes)
                                .take(img_bytes.height() as usize)
                                .flat_map(|row| &row[..row_bytes.min(row.len())])
                                .cloned()
                                .collect(),
                        );
                    }

                    // Create RGBA Image Buffer
                    let img = match img_bytes.clone().try_into_dynamic() {
                        Ok(img) => img.to_rgba8(),
                        Err(e) => panic!("Failed to create image buffer {e:?}"),
                    };

                    // Prepare directory for images, test_images in bevy folder is used here for example
                    // You should choose the path depending on your needs
                    let images_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test_images");
                    info!("Saving image to: {images_dir:?}");
                    std::fs::create_dir_all(&images_dir).unwrap();

                    // Choose filename starting from 000.png
                    let image_path = images_dir.join(format!("{:03}.png", file_number.deref()));
                    *file_number.deref_mut() += 1;

                    // Finally saving image to file, this heavy blocking operation is kept here
                    // for example simplicity, but in real app you should move it to a separate task
                    if let Err(e) = img.save(image_path) {
                        panic!("Failed to save image: {e}");
                    };
                }
                if scene_controller.single_image {
                    app_exit_writer.write(AppExit::Success);
                }
            }
        } else {
            // clears channel for skipped frames
            while receiver.try_recv().is_ok() {}
            scene_controller.state = SceneState::Render(n - 1);
        }
    }
}

pub fn aspect_ratio(&self) -> AspectRatio

Returns the aspect ratio (width / height) of a 2D image.

pub fn size_f32(&self) -> Vec2

Returns the size of a 2D image as f32.

Examples found in repository

examples/3d/tonemapping.rs (line 256)

fn resize_image(
    image_mesh: Query<(&MeshMaterial3d<StandardMaterial>, &Mesh3d), With<HDRViewer>>,
    materials: Res<Assets<StandardMaterial>>,
    mut meshes: ResMut<Assets<Mesh>>,
    images: Res<Assets<Image>>,
    mut image_event_reader: MessageReader<AssetEvent<Image>>,
) {
    for event in image_event_reader.read() {
        let (AssetEvent::Added { id } | AssetEvent::Modified { id }) = event else {
            continue;
        };

        for (mat_h, mesh_h) in &image_mesh {
            let Some(mat) = materials.get(mat_h) else {
                continue;
            };

            let Some(ref base_color_texture) = mat.base_color_texture else {
                continue;
            };

            if *id != base_color_texture.id() {
                continue;
            };

            let Some(image_changed) = images.get(*id) else {
                continue;
            };

            let size = image_changed.size_f32().normalize_or_zero() * 1.4;
            // Resize Mesh
            let quad = Mesh::from(Rectangle::from_size(size));
            meshes.insert(mesh_h, quad).unwrap();
        }
    }
}

pub fn size(&self) -> UVec2

Returns the size of a 2D image.

pub fn resize(&mut self, size: Extent3d)

Resizes the image to the new size, by removing information or appending 0 to the data. Does not properly scale the contents of the image.

If you need to keep pixel data intact, use Image::resize_in_place.

Examples found in repository

examples/2d/pixel_grid_snap.rs (line 109)

fn setup_camera(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    let canvas_size = Extent3d {
        width: RES_WIDTH,
        height: RES_HEIGHT,
        ..default()
    };

    // This Image serves as a canvas representing the low-resolution game screen
    let mut canvas = Image {
        texture_descriptor: TextureDescriptor {
            label: None,
            size: canvas_size,
            dimension: TextureDimension::D2,
            format: TextureFormat::Bgra8UnormSrgb,
            mip_level_count: 1,
            sample_count: 1,
            usage: TextureUsages::TEXTURE_BINDING
                | TextureUsages::COPY_DST
                | TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        },
        ..default()
    };

    // Fill image.data with zeroes
    canvas.resize(canvas_size);

    let image_handle = images.add(canvas);

    // This camera renders whatever is on `PIXEL_PERFECT_LAYERS` to the canvas
    commands.spawn((
        Camera2d,
        Camera {
            // Render before the "main pass" camera
            order: -1,
            clear_color: ClearColorConfig::Custom(GRAY.into()),
            ..default()
        },
        RenderTarget::Image(image_handle.clone().into()),
        Msaa::Off,
        InGameCamera,
        PIXEL_PERFECT_LAYERS,
    ));

    // Spawn the canvas
    commands.spawn((Sprite::from_image(image_handle), Canvas, HIGH_RES_LAYERS));

    // The "outer" camera renders whatever is on `HIGH_RES_LAYERS` to the screen.
    // here, the canvas and one of the sample sprites will be rendered by this camera
    commands.spawn((Camera2d, Msaa::Off, OuterCamera, HIGH_RES_LAYERS));
}

pub fn reinterpret_size( &mut self, new_size: Extent3d, ) -> Result<(), TextureReinterpretationError>

Changes the size if the total number of data elements (pixels) remains the same. If not, returns TextureReinterpretationError::IncompatibleSizes.

pub fn resize_in_place(&mut self, new_size: Extent3d)

Resizes the image to the new size, keeping the pixel data intact, anchored at the top-left. When growing, the new space is filled with 0. When shrinking, the image is clipped.

For faster resizing when keeping pixel data intact is not important, use Image::resize.

pub fn reinterpret_stacked_2d_as_array( &mut self, layers: u32, ) -> Result<(), TextureReinterpretationError>

Takes a 2D image containing vertically stacked images of the same size, and reinterprets it as a 2D array texture, where each of the stacked images becomes one layer of the array. This is primarily for use with the texture2DArray shader uniform type.

Errors

Returns TextureReinterpretationError if the texture is not 2D, has more than one layers or is not evenly dividable into the layers.

Examples found in repository

examples/3d/skybox.rs (line 162)

fn asset_loaded(
    asset_server: Res<AssetServer>,
    mut images: ResMut<Assets<Image>>,
    mut cubemap: ResMut<Cubemap>,
    mut skyboxes: Query<&mut Skybox>,
) {
    if !cubemap.is_loaded && asset_server.load_state(&cubemap.image_handle).is_loaded() {
        info!("Swapping to {}...", CUBEMAPS[cubemap.index].0);
        let mut image = images.get_mut(&cubemap.image_handle).unwrap();
        // NOTE: PNGs do not have any metadata that could indicate they contain a cubemap texture,
        // so they appear as one texture. The following code reconfigures the texture as necessary.
        if image.texture_descriptor.array_layer_count() == 1 {
            let layers = image.height() / image.width();
            image
                .reinterpret_stacked_2d_as_array(layers)
                .expect("asset should be 2d texture and height will always be evenly divisible with the given layers");
            image.texture_view_descriptor = Some(TextureViewDescriptor {
                dimension: Some(TextureViewDimension::Cube),
                ..default()
            });
        }

        for mut skybox in &mut skyboxes {
            skybox.image = Some(cubemap.image_handle.clone());
        }

        cubemap.is_loaded = true;
    }
}

pub fn create_stacked_array_from_2d_grid( &self, rows: u32, columns: u32, ) -> Result<Image, TextureReinterpretationError>

Returns a newly constructed 2D image using the same properties as &self from a grid of tiles of the specified size, The new image is constructed in a vertical stack of tiles to be used as a 2D array texture.

This is primarily for preparing grid based tilesets.

Errors

Returns TextureReinterpretationError if the texture is not 2D, has more than one layers or is not evenly dividable by size_in_tiles.

pub fn convert(&self, new_format: TextureFormat) -> Option<Image>

Convert a texture from a format to another. Only a few formats are supported as input and output:

• TextureFormat::R8Unorm
• TextureFormat::Rg8Unorm
• TextureFormat::Rgba8UnormSrgb

To get Image as a image::DynamicImage see: Image::try_into_dynamic.

pub fn from_buffer( buffer: &[u8], image_type: ImageType<'_>, supported_compressed_formats: CompressedImageFormats, is_srgb: bool, image_sampler: ImageSampler, asset_usage: RenderAssetUsages, ) -> Result<Image, TextureError>

Load a bytes buffer in a Image, according to type image_type, using the image crate

pub fn is_compressed(&self) -> bool

Whether the texture format is compressed or uncompressed

pub fn pixel_data_offset( &self, coords: UVec3, ) -> Result<usize, TextureAccessError>

Compute the byte offset where the data of a specific pixel is stored

Returns an error if the provided coordinates are out of bounds.

For 2D textures, Z is the layer number. For 1D textures, Y and Z are ignored.

pub fn pixel_bytes(&self, coords: UVec3) -> Result<&[u8], TextureAccessError>

Get a reference to the data bytes where a specific pixel’s value is stored.

pub fn pixel_bytes_mut( &mut self, coords: UVec3, ) -> Result<&mut [u8], TextureAccessError>

Get a mutable reference to the data bytes where a specific pixel’s value is stored.

Examples found in repository

examples/2d/cpu_draw.rs (line 70)

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    commands.spawn(Camera2d);

    // Create an image that we are going to draw into
    let mut image = Image::new_fill(
        // 2D image of size 256x256
        Extent3d {
            width: IMAGE_WIDTH,
            height: IMAGE_HEIGHT,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        // Initialize it with a beige color
        &(css::BEIGE.to_u8_array()),
        // Use the same encoding as the color we set
        TextureFormat::Rgba8UnormSrgb,
        RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD,
    );

    // To make it extra fancy, we can set the Alpha of each pixel,
    // so that it fades out in a circular fashion.
    for y in 0..IMAGE_HEIGHT {
        for x in 0..IMAGE_WIDTH {
            let center = Vec2::new(IMAGE_WIDTH as f32 / 2.0, IMAGE_HEIGHT as f32 / 2.0);
            let max_radius = IMAGE_HEIGHT.min(IMAGE_WIDTH) as f32 / 2.0;
            let r = Vec2::new(x as f32, y as f32).distance(center);
            let a = 1.0 - (r / max_radius).clamp(0.0, 1.0);

            // Here we will set the A value by accessing the raw data bytes.
            // (it is the 4th byte of each pixel, as per our `TextureFormat`)

            // Find our pixel by its coordinates
            let pixel_bytes = image.pixel_bytes_mut(UVec3::new(x, y, 0)).unwrap();
            // Convert our f32 to u8
            pixel_bytes[3] = (a * u8::MAX as f32) as u8;
        }
    }

    // Add it to Bevy's assets, so it can be used for rendering
    // this will give us a handle we can use
    // (to display it in a sprite, or as part of UI, etc.)
    let handle = images.add(image);

    // Create a sprite entity using our image
    commands.spawn(Sprite::from_image(handle.clone()));
    commands.insert_resource(MyProcGenImage(handle));

    // We're seeding the PRNG here to make this example deterministic for testing purposes.
    // This isn't strictly required in practical use unless you need your app to be deterministic.
    let seeded_rng = ChaCha8Rng::seed_from_u64(19878367467712);
    commands.insert_resource(SeededRng(seeded_rng));
}

pub fn clear(&mut self, pixel: &[u8])

Clears the content of the image with the given pixel. The image needs to be initialized on the cpu otherwise this is a noop.

This does nothing if the image data is not already initialized

pub fn get_color_at_1d(&self, x: u32) -> Result<Color, TextureAccessError>

Read the color of a specific pixel (1D texture).

See get_color_at for more details.

pub fn get_color_at(&self, x: u32, y: u32) -> Result<Color, TextureAccessError>

Read the color of a specific pixel (2D texture).

This function will find the raw byte data of a specific pixel and decode it into a user-friendly Color struct for you.

Supports many of the common TextureFormats:

• RGBA/BGRA 8-bit unsigned integer, both sRGB and Linear
• 16-bit and 32-bit unsigned integer
• 16-bit and 32-bit float

Be careful: as the data is converted to Color (which uses f32 internally), there may be issues with precision when using non-f32 TextureFormats. If you read a value you previously wrote using set_color_at, it will not match. If you are working with a 32-bit integer TextureFormat, the value will be inaccurate (as f32 does not have enough bits to represent it exactly).

Single channel (R) formats are assumed to represent grayscale, so the value will be copied to all three RGB channels in the resulting Color.

Other TextureFormats are unsupported, such as:

• block-compressed formats
• non-byte-aligned formats like 10-bit
• signed integer formats

Examples found in repository

examples/2d/cpu_draw.rs (line 124)

fn draw(
    my_handle: Res<MyProcGenImage>,
    mut images: ResMut<Assets<Image>>,
    // Used to keep track of where we are
    mut i: Local<u32>,
    mut draw_color: Local<Color>,
    mut seeded_rng: ResMut<SeededRng>,
) {
    if *i == 0 {
        // Generate a random color on first run.
        *draw_color = Color::linear_rgb(
            seeded_rng.0.random(),
            seeded_rng.0.random(),
            seeded_rng.0.random(),
        );
    }

    // Get the image from Bevy's asset storage.
    let mut image = images.get_mut(&my_handle.0).expect("Image not found");

    // Compute the position of the pixel to draw.

    let center = Vec2::new(IMAGE_WIDTH as f32 / 2.0, IMAGE_HEIGHT as f32 / 2.0);
    let max_radius = IMAGE_HEIGHT.min(IMAGE_WIDTH) as f32 / 2.0;
    let rot_speed = 0.0123;
    let period = 0.12345;

    let r = ops::sin(*i as f32 * period) * max_radius;
    let xy = Vec2::from_angle(*i as f32 * rot_speed) * r + center;
    let (x, y) = (xy.x as u32, xy.y as u32);

    // Get the old color of that pixel.
    let old_color = image.get_color_at(x, y).unwrap();

    // If the old color is our current color, change our drawing color.
    let tolerance = 1.0 / 255.0;
    if old_color.distance(&draw_color) <= tolerance {
        *draw_color = Color::linear_rgb(
            seeded_rng.0.random(),
            seeded_rng.0.random(),
            seeded_rng.0.random(),
        );
    }

    // Set the new color, but keep old alpha value from image.
    image
        .set_color_at(x, y, draw_color.with_alpha(old_color.alpha()))
        .unwrap();

    *i += 1;
}

pub fn get_color_at_3d( &self, x: u32, y: u32, z: u32, ) -> Result<Color, TextureAccessError>

Read the color of a specific pixel (2D texture with layers or 3D texture).

See get_color_at for more details.

pub fn set_color_at_1d( &mut self, x: u32, color: Color, ) -> Result<(), TextureAccessError>

Change the color of a specific pixel (1D texture).

See set_color_at for more details.

pub fn set_color_at( &mut self, x: u32, y: u32, color: Color, ) -> Result<(), TextureAccessError>

Change the color of a specific pixel (2D texture).

This function will find the raw byte data of a specific pixel and change it according to a Color you provide. The Color struct will be encoded into the Image’s TextureFormat.

Supports many of the common TextureFormats:

• RGBA/BGRA 8-bit unsigned integer, both sRGB and Linear
• 16-bit and 32-bit unsigned integer (with possibly-limited precision, as Color uses f32)
• 16-bit and 32-bit float

Be careful: writing to non-f32 TextureFormats is lossy! The data has to be converted, so if you read it back using get_color_at, the Color you get will not equal the value you used when writing it using this function.

For RG formats, only the respective values from the linear RGB Color will be used.

For R formats the linear RGB Color will be converted to grayscale and the R channel will be the luminance.

Other TextureFormats are unsupported, such as:

• block-compressed formats
• non-byte-aligned formats like 10-bit
• signed integer formats

Examples found in repository

examples/asset/asset_saving.rs (line 241)

fn try_plot(
    event: On<TryPlot>,
    sprite: Query<(&Sprite, &Anchor, &GlobalTransform), With<SpriteToSave>>,
    camera: Single<(&Camera, &GlobalTransform)>,
    texture_atlases: Res<Assets<TextureAtlasLayout>>,
    draw_color: Res<DrawColor>,
    mut images: ResMut<Assets<Image>>,
) {
    let Ok((sprite, anchor, sprite_transform)) = sprite.get(event.entity) else {
        return;
    };
    let (camera, camera_transform) = camera.into_inner();
    let Ok(world_position) = camera.viewport_to_world_2d(camera_transform, event.location.position)
    else {
        return;
    };
    let relative_to_sprite = sprite_transform
        .affine()
        .inverse()
        .transform_point3(world_position.extend(0.0));
    let Ok(pixel_space) = sprite.compute_pixel_space_point(
        relative_to_sprite.xy(),
        *anchor,
        &images,
        &texture_atlases,
    ) else {
        return;
    };
    let pixel_coordinates = pixel_space.floor().as_uvec2();
    let mut image = images.get_mut(&sprite.image).unwrap();
    // For an actual drawing app, you'd at least draw a line from the last point, but this is
    // simpler.
    image
        .set_color_at(pixel_coordinates.x, pixel_coordinates.y, draw_color.0)
        .unwrap();
}

examples/2d/cpu_draw.rs (line 138)

fn draw(
    my_handle: Res<MyProcGenImage>,
    mut images: ResMut<Assets<Image>>,
    // Used to keep track of where we are
    mut i: Local<u32>,
    mut draw_color: Local<Color>,
    mut seeded_rng: ResMut<SeededRng>,
) {
    if *i == 0 {
        // Generate a random color on first run.
        *draw_color = Color::linear_rgb(
            seeded_rng.0.random(),
            seeded_rng.0.random(),
            seeded_rng.0.random(),
        );
    }

    // Get the image from Bevy's asset storage.
    let mut image = images.get_mut(&my_handle.0).expect("Image not found");

    // Compute the position of the pixel to draw.

    let center = Vec2::new(IMAGE_WIDTH as f32 / 2.0, IMAGE_HEIGHT as f32 / 2.0);
    let max_radius = IMAGE_HEIGHT.min(IMAGE_WIDTH) as f32 / 2.0;
    let rot_speed = 0.0123;
    let period = 0.12345;

    let r = ops::sin(*i as f32 * period) * max_radius;
    let xy = Vec2::from_angle(*i as f32 * rot_speed) * r + center;
    let (x, y) = (xy.x as u32, xy.y as u32);

    // Get the old color of that pixel.
    let old_color = image.get_color_at(x, y).unwrap();

    // If the old color is our current color, change our drawing color.
    let tolerance = 1.0 / 255.0;
    if old_color.distance(&draw_color) <= tolerance {
        *draw_color = Color::linear_rgb(
            seeded_rng.0.random(),
            seeded_rng.0.random(),
            seeded_rng.0.random(),
        );
    }

    // Set the new color, but keep old alpha value from image.
    image
        .set_color_at(x, y, draw_color.with_alpha(old_color.alpha()))
        .unwrap();

    *i += 1;
}

pub fn set_color_at_3d( &mut self, x: u32, y: u32, z: u32, color: Color, ) -> Result<(), TextureAccessError>

Change the color of a specific pixel (2D texture with layers or 3D texture).

See set_color_at for more details.

impl Image

pub fn from_dynamic( dyn_img: DynamicImage, is_srgb: bool, asset_usage: RenderAssetUsages, ) -> Image

Converts a DynamicImage to an Image.

pub fn try_into_dynamic(self) -> Result<DynamicImage, IntoDynamicImageError>

Convert a Image to a DynamicImage. Useful for editing image data. Not all TextureFormat are covered, therefore it will return an error if the format is unsupported. Supported formats are:

• TextureFormat::R8Unorm
• TextureFormat::Rg8Unorm
• TextureFormat::Rgba8UnormSrgb
• TextureFormat::Bgra8UnormSrgb

To convert Image to a different format see: Image::convert.

Examples found in repository

examples/app/headless_renderer.rs (line 494)

fn update(
    images_to_save: Query<&ImageToSave>,
    receiver: Res<MainWorldReceiver>,
    mut images: ResMut<Assets<Image>>,
    mut scene_controller: ResMut<SceneController>,
    mut app_exit_writer: MessageWriter<AppExit>,
    mut file_number: Local<u32>,
) {
    if let SceneState::Render(n) = scene_controller.state {
        if n < 1 {
            // We don't want to block the main world on this,
            // so we use try_recv which attempts to receive without blocking
            let mut image_data = Vec::new();
            while let Ok(data) = receiver.try_recv() {
                // image generation could be faster than saving to fs,
                // that's why use only last of them
                image_data = data;
            }
            if !image_data.is_empty() {
                for image in images_to_save.iter() {
                    // Fill correct data from channel to image
                    let mut img_bytes = images.get_mut(image.id()).unwrap();

                    // We need to ensure that this works regardless of the image dimensions
                    // If the image became wider when copying from the texture to the buffer,
                    // then the data is reduced to its original size when copying from the buffer to the image.
                    let row_bytes = img_bytes.width() as usize
                        * img_bytes.texture_descriptor.format.pixel_size().unwrap();
                    let aligned_row_bytes = RenderDevice::align_copy_bytes_per_row(row_bytes);
                    if row_bytes == aligned_row_bytes {
                        img_bytes.data.as_mut().unwrap().clone_from(&image_data);
                    } else {
                        // shrink data to original image size
                        img_bytes.data = Some(
                            image_data
                                .chunks(aligned_row_bytes)
                                .take(img_bytes.height() as usize)
                                .flat_map(|row| &row[..row_bytes.min(row.len())])
                                .cloned()
                                .collect(),
                        );
                    }

                    // Create RGBA Image Buffer
                    let img = match img_bytes.clone().try_into_dynamic() {
                        Ok(img) => img.to_rgba8(),
                        Err(e) => panic!("Failed to create image buffer {e:?}"),
                    };

                    // Prepare directory for images, test_images in bevy folder is used here for example
                    // You should choose the path depending on your needs
                    let images_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test_images");
                    info!("Saving image to: {images_dir:?}");
                    std::fs::create_dir_all(&images_dir).unwrap();

                    // Choose filename starting from 000.png
                    let image_path = images_dir.join(format!("{:03}.png", file_number.deref()));
                    *file_number.deref_mut() += 1;

                    // Finally saving image to file, this heavy blocking operation is kept here
                    // for example simplicity, but in real app you should move it to a separate task
                    if let Err(e) = img.save(image_path) {
                        panic!("Failed to save image: {e}");
                    };
                }
                if scene_controller.single_image {
                    app_exit_writer.write(AppExit::Success);
                }
            }
        } else {
            // clears channel for skipped frames
            while receiver.try_recv().is_ok() {}
            scene_controller.state = SceneState::Render(n - 1);
        }
    }
}

examples/remote/integration_test.rs (line 83)

fn main() -> AnyhowResult<()> {
    let url = format!("http://{DEFAULT_ADDR}:{DEFAULT_PORT}/");

    // Step 1: Take a screenshot via BRP
    // The window must be visible (not fully occluded) for the GPU to render content
    // If the window is hidden, the screenshot will be black
    println!("Spawning Screenshot entity...");
    let spawn_response = brp_request(
        &url,
        BRP_SPAWN_ENTITY_METHOD,
        1,
        &BrpSpawnEntityParams {
            components: HashMap::from([(
                type_name::<Screenshot>().to_string(),
                serde_json::json!({"Window": "Primary"}),
            )]),
        },
    )?;
    let screenshot_entity = &spawn_response["result"]["entity"];

    println!("Observing ScreenshotCaptured on entity {screenshot_entity}...");
    let observe_response = ureq::post(&url).send_json(BrpRequest {
        method: BRP_OBSERVE_METHOD.to_string(),
        id: Some(serde_json::to_value(2)?),
        params: Some(serde_json::to_value(BrpObserveParams {
            event: type_name::<ScreenshotCaptured>().to_string(),
            entity: Some(serde_json::from_value(screenshot_entity.clone())?),
        })?),
    })?;

    println!("Waiting for screenshot capture...");
    let reader = std::io::BufReader::new(observe_response.into_body().into_reader());
    for line in reader.lines() {
        let line = line?;
        if let Some(json_str) = line.strip_prefix("data: ") {
            let response: serde_json::Value = serde_json::from_str(json_str)?;
            if let Some(error) = response.get("error") {
                anyhow::bail!("Observe error: {error}");
            }
            if let Some(result) = response.get("result") {
                let events = result.as_array().expect("Expected events array");
                let event = &events[0];

                let image_data = &event["image"];
                let width = image_data["texture_descriptor"]["size"]["width"]
                    .as_u64()
                    .unwrap();
                let height = image_data["texture_descriptor"]["size"]["height"]
                    .as_u64()
                    .unwrap();
                println!("Screenshot captured! Image size: {width}x{height}");

                let image: bevy::image::Image = serde_json::from_value(image_data.clone())?;
                let dyn_img = image
                    .try_into_dynamic()
                    .expect("Failed to convert screenshot to dynamic image");
                let path = "screenshot.png";
                dyn_img.to_rgb8().save(path)?;
                println!("Screenshot saved to {path}");
                break;
            }
        }
    }

    // Step 2: Find the button entity, and its global transform
    println!("Querying for button entity...");
    let button_query = brp_request(
        &url,
        BRP_QUERY_METHOD,
        3,
        &BrpQueryParams {
            data: BrpQuery {
                components: vec![type_name::<UiGlobalTransform>().to_string()],
                option: ComponentSelector::default(),
                has: Vec::default(),
            },
            strict: false,
            filter: BrpQueryFilter {
                with: vec![type_name::<Button>().to_string()],
                without: Vec::default(),
            },
        },
    )?;

    let button_result = button_query["result"]
        .as_array()
        .expect("Expected result array");
    let button = &button_result[0];

    // UiGlobalTransform wraps an Affine2, serialized as a flat array:
    // [_, _, _, _, translation_x, translation_y]
    // The translation gives the node's center in physical pixels.
    let transform = &button["components"][type_name::<UiGlobalTransform>()];
    let transform_arr = transform.as_array().expect("Expected transform array");
    let phys_x = transform_arr[4].as_f64().unwrap();
    let phys_y = transform_arr[5].as_f64().unwrap();
    println!("Found button at physical ({phys_x}, {phys_y})");

    // Step 3: Find the window entity and scale factor
    println!("Querying for window entity...");
    let window_query = brp_request(
        &url,
        BRP_QUERY_METHOD,
        4,
        &BrpQueryParams {
            data: BrpQuery {
                components: vec![type_name::<Window>().to_string()],
                option: ComponentSelector::default(),
                has: Vec::default(),
            },
            strict: false,
            filter: BrpQueryFilter::default(),
        },
    )?;

    let window_result = window_query["result"]
        .as_array()
        .expect("Expected result array");
    let window = &window_result[0];
    let window_entity = &window["entity"];
    let window_data = &window["components"][type_name::<Window>()];
    let scale_factor = window_data["resolution"]["scale_factor"].as_f64().unwrap();
    println!("Found window entity: {window_entity}, scale_factor: {scale_factor}");

    // Step 4: Convert button center from physical to logical pixels
    let logical_x = phys_x / scale_factor;
    let logical_y = phys_y / scale_factor;
    println!("Clicking at logical position: ({logical_x}, {logical_y})");

    // Step 5: Send CursorMoved via WindowEvent message
    // This lets the picking system know where the pointer is.
    println!("Sending CursorMoved message...");
    brp_request(
        &url,
        BRP_WRITE_MESSAGE_METHOD,
        5,
        &BrpWriteMessageParams {
            message: type_name::<WindowEvent>().to_string(),
            value: Some(serde_json::json!({
                "CursorMoved": {
                    "window": window_entity,
                    "position": [logical_x, logical_y],
                    "delta": null
                }
            })),
        },
    )?;

    // Step 6: Send MouseButtonInput Pressed + Released via WindowEvent messages.
    // The picking system needs both press and release to generate a Pointer<Click>.
    println!("Sending mouse press...");
    brp_request(
        &url,
        BRP_WRITE_MESSAGE_METHOD,
        6,
        &BrpWriteMessageParams {
            message: type_name::<WindowEvent>().to_string(),
            value: Some(serde_json::json!({
                "MouseButtonInput": {
                    "button": "Left",
                    "state": "Pressed",
                    "window": window_entity,
                }
            })),
        },
    )?;

    println!("Sending mouse release...");
    brp_request(
        &url,
        BRP_WRITE_MESSAGE_METHOD,
        7,
        &BrpWriteMessageParams {
            message: type_name::<WindowEvent>().to_string(),
            value: Some(serde_json::json!({
                "MouseButtonInput": {
                    "button": "Left",
                    "state": "Released",
                    "window": window_entity,
                }
            })),
        },
    )?;

    Ok(())
}

Trait Implementations

impl Asset for Image

impl Clone for Image

fn clone(&self) -> Image

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Image

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

Formats the value using the given formatter.

impl Default for Image

fn default() -> Image

default is a 1x1x1 all ‘1.0’ texture

impl<'de> Deserialize<'de> for Image

fn deserialize<D>( deserializer: D, ) -> Result<Image, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromArg for Image

type This<'from_arg> = Image

The type to convert into.

fn from_arg(arg: Arg<'_>) -> Result<<Image as FromArg>::This<'_>, ArgError>

Creates an item from an argument.

impl FromReflect for Image

fn from_reflect(reflect: &(dyn PartialReflect + 'static)) -> Option<Image>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetOwnership for Image

fn ownership() -> Ownership

Returns the ownership of Self.

impl GetTypeRegistration for Image

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(_registry: &mut TypeRegistry)

Registers other types needed by this type.

impl IntoReturn for Image

fn into_return<'into_return>(self) -> Return<'into_return>

where Image: 'into_return,

Converts Self into a Return value.

impl PartialEq for Image

fn eq(&self, other: &Image) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialReflect for Image

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Image>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Image>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Image>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

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

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_partial_cmp( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for Image

fn into_any(self: Box<Image>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Image>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl Serialize for Image

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Image

impl TypePath for Image

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for Image

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl VisitAssetDependencies for Image

fn visit_dependencies(&self, visit: &mut impl FnMut(UntypedAssetId))