Struct SpriteSheet 

pub struct SpriteSheet { /* private fields */ }

A sprite sheet containing uniformly-sized sprites in a grid layout.

All sprites in a sprite sheet have the same dimensions and are arranged in rows and columns. This makes it efficient for animations where each frame is the same size.

Example

// Create a sprite sheet from a texture
let sprite_sheet = SpriteSheet::new(
    context,
    texture,
    SpriteSheetDescriptor {
        sprite_width: 32,
        sprite_height: 32,
        columns: 8,
        rows: 4,
        ..Default::default()
    },
);

// Get UV coordinates for sprite at index 5
let uv = sprite_sheet.sprite_uv(5);

// Or by row/column
let uv = sprite_sheet.sprite_uv_at(1, 2);

Implementations

impl SpriteSheet

pub fn new( texture: Texture, view: TextureView, texture_width: u32, texture_height: u32, descriptor: SpriteSheetDescriptor, ) -> Self

Create a new sprite sheet from an existing texture.

pub fn from_data( context: &GraphicsContext, data: &[u8], texture_width: u32, texture_height: u32, descriptor: SpriteSheetDescriptor, ) -> Self

Create a sprite sheet from raw pixel data.

Arguments

• context - Graphics context
• data - Raw RGBA pixel data
• texture_width - Width of the texture in pixels
• texture_height - Height of the texture in pixels
• descriptor - Sprite sheet configuration

Examples found in repository

examples/sprite_sheet.rs (lines 178-190)

fn main() {
    logging::init();

    run_app(|ctx| {
        let graphics_ctx = GraphicsContext::new_sync();
        let mut windows = HashMap::new();

        let scale = Window::platform_dpi() as f32;
        let window = ctx
            .create_window(WindowDescriptor {
                title: "Sprite Sheet Animation Example".to_string(),
                size: Some(PhysicalSize::new(400.0 * scale, 400.0 * scale)),
                ..Default::default()
            })
            .expect("Failed to create window");

        let renderable_window = RenderableWindow::new_with_descriptor(
            window,
            graphics_ctx,
            WindowContextDescriptor {
                format: Some(wgpu::TextureFormat::Bgra8UnormSrgb),
                ..Default::default()
            },
        );

        let window_id = renderable_window.id();
        windows.insert(window_id, renderable_window);

        // Generate sprite sheet
        let (sprite_data, tex_width, tex_height) = generate_sprite_sheet_data();
        let sprite_sheet = SpriteSheet::from_data(
            graphics_ctx,
            &sprite_data,
            tex_width,
            tex_height,
            SpriteSheetDescriptor {
                sprite_width: 64,
                sprite_height: 64,
                columns: 4,
                rows: 1,
                ..Default::default()
            },
        );

        // Create animation (4 frames at 8 fps)
        let animation = SpriteAnimation::new(4, 8.0);

        // Create shader module
        let shader = graphics_ctx.device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("Sprite Shader"),
            source: wgpu::ShaderSource::Wgsl(SHADER.into()),
        });

        // Create bind group layout
        let bind_group_layout = graphics_ctx.device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("Sprite Bind Group Layout"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::VERTEX,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ],
        });

        // Create pipeline layout
        let pipeline_layout = graphics_ctx.device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Sprite Pipeline Layout"),
            bind_group_layouts: &[&bind_group_layout],
            push_constant_ranges: &[],
        });

        // Create render pipeline
        let pipeline = graphics_ctx.device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("Sprite Pipeline"),
            layout: Some(&pipeline_layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<Vertex>() as u64,
                    step_mode: wgpu::VertexStepMode::Vertex,
                    attributes: &[
                        wgpu::VertexAttribute {
                            offset: 0,
                            shader_location: 0,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                        wgpu::VertexAttribute {
                            offset: 8,
                            shader_location: 1,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                    ],
                }],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format: wgpu::TextureFormat::Bgra8UnormSrgb,
                    blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview: None,
            cache: None,
        });

        // Create uniform buffer
        let uniforms = Uniforms {
            mvp: [
                [1.0, 0.0, 0.0, 0.0],
                [0.0, 1.0, 0.0, 0.0],
                [0.0, 0.0, 1.0, 0.0],
                [0.0, 0.0, 0.0, 1.0],
            ],
        };
        let uniform_buffer = graphics_ctx.device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("Uniform Buffer"),
            contents: bytemuck::cast_slice(&[uniforms]),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        // Create sampler
        let sampler = graphics_ctx.device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("Sprite Sampler"),
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            ..Default::default()
        });

        // Create bind group
        let bind_group = graphics_ctx.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("Sprite Bind Group"),
            layout: &bind_group_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: uniform_buffer.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::TextureView(sprite_sheet.view()),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: wgpu::BindingResource::Sampler(&sampler),
                },
            ],
        });

        // Initial vertex buffer (will be updated each frame with new UVs)
        let vertices = create_quad_vertices(0.0, 0.0, 1.0, 1.0);
        let vertex_buffer = graphics_ctx.device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("Vertex Buffer"),
            contents: bytemuck::cast_slice(&vertices),
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        });

        Box::new(App {
            _context: graphics_ctx,
            windows,
            pipeline,
            bind_group,
            vertex_buffer,
            uniform_buffer,
            sprite_sheet,
            animation,
            last_update: Instant::now(),
        })
    });
}

pub fn sprite_uv(&self, index: u32) -> SpriteUV

Get UV coordinates for a sprite by linear index.

Sprites are indexed left-to-right, top-to-bottom, starting from 0.

Examples found in repository

examples/sprite_sheet.rs (line 372)

    fn update(&mut self, _ctx: &mut astrelis_winit::app::AppCtx) {
        let now = Instant::now();
        let dt = now.duration_since(self.last_update).as_secs_f32();
        self.last_update = now;

        // Update animation
        if self.animation.update(dt) {
            // Frame changed - update vertex buffer with new UVs
            let frame = self.animation.current_frame();
            let uv = self.sprite_sheet.sprite_uv(frame);
            let vertices = create_quad_vertices(uv.u_min, uv.v_min, uv.u_max, uv.v_max);
            
            // Get context from first window
            if let Some(window) = self.windows.values().next() {
                window.context().graphics_context().queue.write_buffer(
                    &self.vertex_buffer,
                    0,
                    bytemuck::cast_slice(&vertices),
                );
            }
        }
    }

pub fn sprite_uv_at(&self, row: u32, col: u32) -> SpriteUV

Get UV coordinates for a sprite by row and column.

pub fn sprite_count(&self) -> u32

Get the total number of sprites in the sheet.

pub fn sprite_size(&self) -> (u32, u32)

Get the sprite dimensions in pixels.

pub fn grid_size(&self) -> (u32, u32)

Get the grid dimensions (columns, rows).

pub fn view(&self) -> &TextureView

Get the texture view for binding.

Examples found in repository

examples/sprite_sheet.rs (line 320)

fn main() {
    logging::init();

    run_app(|ctx| {
        let graphics_ctx = GraphicsContext::new_sync();
        let mut windows = HashMap::new();

        let scale = Window::platform_dpi() as f32;
        let window = ctx
            .create_window(WindowDescriptor {
                title: "Sprite Sheet Animation Example".to_string(),
                size: Some(PhysicalSize::new(400.0 * scale, 400.0 * scale)),
                ..Default::default()
            })
            .expect("Failed to create window");

        let renderable_window = RenderableWindow::new_with_descriptor(
            window,
            graphics_ctx,
            WindowContextDescriptor {
                format: Some(wgpu::TextureFormat::Bgra8UnormSrgb),
                ..Default::default()
            },
        );

        let window_id = renderable_window.id();
        windows.insert(window_id, renderable_window);

        // Generate sprite sheet
        let (sprite_data, tex_width, tex_height) = generate_sprite_sheet_data();
        let sprite_sheet = SpriteSheet::from_data(
            graphics_ctx,
            &sprite_data,
            tex_width,
            tex_height,
            SpriteSheetDescriptor {
                sprite_width: 64,
                sprite_height: 64,
                columns: 4,
                rows: 1,
                ..Default::default()
            },
        );

        // Create animation (4 frames at 8 fps)
        let animation = SpriteAnimation::new(4, 8.0);

        // Create shader module
        let shader = graphics_ctx.device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("Sprite Shader"),
            source: wgpu::ShaderSource::Wgsl(SHADER.into()),
        });

        // Create bind group layout
        let bind_group_layout = graphics_ctx.device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("Sprite Bind Group Layout"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::VERTEX,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ],
        });

        // Create pipeline layout
        let pipeline_layout = graphics_ctx.device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Sprite Pipeline Layout"),
            bind_group_layouts: &[&bind_group_layout],
            push_constant_ranges: &[],
        });

        // Create render pipeline
        let pipeline = graphics_ctx.device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("Sprite Pipeline"),
            layout: Some(&pipeline_layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<Vertex>() as u64,
                    step_mode: wgpu::VertexStepMode::Vertex,
                    attributes: &[
                        wgpu::VertexAttribute {
                            offset: 0,
                            shader_location: 0,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                        wgpu::VertexAttribute {
                            offset: 8,
                            shader_location: 1,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                    ],
                }],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format: wgpu::TextureFormat::Bgra8UnormSrgb,
                    blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview: None,
            cache: None,
        });

        // Create uniform buffer
        let uniforms = Uniforms {
            mvp: [
                [1.0, 0.0, 0.0, 0.0],
                [0.0, 1.0, 0.0, 0.0],
                [0.0, 0.0, 1.0, 0.0],
                [0.0, 0.0, 0.0, 1.0],
            ],
        };
        let uniform_buffer = graphics_ctx.device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("Uniform Buffer"),
            contents: bytemuck::cast_slice(&[uniforms]),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        // Create sampler
        let sampler = graphics_ctx.device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("Sprite Sampler"),
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            ..Default::default()
        });

        // Create bind group
        let bind_group = graphics_ctx.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("Sprite Bind Group"),
            layout: &bind_group_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: uniform_buffer.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::TextureView(sprite_sheet.view()),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: wgpu::BindingResource::Sampler(&sampler),
                },
            ],
        });

        // Initial vertex buffer (will be updated each frame with new UVs)
        let vertices = create_quad_vertices(0.0, 0.0, 1.0, 1.0);
        let vertex_buffer = graphics_ctx.device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("Vertex Buffer"),
            contents: bytemuck::cast_slice(&vertices),
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        });

        Box::new(App {
            _context: graphics_ctx,
            windows,
            pipeline,
            bind_group,
            vertex_buffer,
            uniform_buffer,
            sprite_sheet,
            animation,
            last_update: Instant::now(),
        })
    });
}

pub fn texture(&self) -> &Texture

Get the underlying texture.

pub fn texture_size(&self) -> (u32, u32)

Get texture dimensions.

Trait Implementations

impl Debug for SpriteSheet

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

Formats the value using the given formatter.