Crate astrelis_render 

Astrelis Render - Modular rendering framework for Astrelis

This crate provides:

• Graphics context management
• Window rendering contexts
• Frame and render pass management
• Compute pass management
• Framebuffer abstraction for offscreen rendering
• Render target abstraction (Surface/Framebuffer)
• Blend mode presets for common scenarios
• GPU feature detection and management
• Indirect draw buffer support for GPU-driven rendering
• Texture blitting for fullscreen quad rendering
• Sprite sheet support for animations
• Low-level extensible Renderer for WGPU resource management
• Building blocks for higher-level renderers (TextRenderer, SceneRenderer, etc.)

Error Handling

This crate uses consistent error handling patterns:

Result Types

• Creation methods return Result<T, GraphicsError> for GPU initialization
  • Example: GraphicsContext::new_owned_sync() returns Result<Arc<Self>, GraphicsError>
• Fallible operations return Result<T, E> with specific error types
  • Example: Readback::read() returns Result<Vec<u8>, ReadbackError>
• Use .expect() for examples/tests where error handling isn’t critical
  • Example: let ctx = GraphicsContext::new_owned_sync().expect("GPU required")

Option Types

• Optional resources return Option<&T> for possibly-missing values
  • Example: WindowManager::get_window(id) returns Option<&RenderWindow>
• Hit testing returns Option<T> for no-hit scenarios
  • Example: hit_test(point) returns Option<WidgetId>

Panicking vs Fallible

• Avoid panic-suffixed methods - Use .expect() at call sites instead
  • ❌ Bad: resource_or_panic() method
  • ✅ Good: resource().expect("Resource required") at call site
• Provide both variants for common operations
  • resource() - Panics if unavailable (use when required)
  • try_resource() - Returns Option (use when optional)

Re-exports

pub use capability::GpuRequirements;

pub use capability::RenderCapability;

pub use transform::DataRangeParams;

pub use transform::DataTransform;

pub use wgpu;

Modules

batched

Batched deferred indirect renderer.

capability

Render capability system for declaring GPU feature/limit requirements.

gpu_profiling

GPU profiling via wgpu-profiler with puffin visualization.

transform

Shared data-to-screen coordinate transformation for instanced renderers.

Macros

gpu_profile_scope

Execute a block of code within a GPU profiling scope on a Frame.

Structs

AtlasEntry

An entry in the texture atlas.

AtlasKey

Unique key for an atlas entry.

AtlasRect

Rectangle for atlas packing (not coordinate-space aware).

AtomicFrameStats

Thread-safe atomic frame statistics.

BlitOptions

Options for configuring the blit renderer.

BlitRenderer

Camera

A camera with view and projection matrices.

CameraUniform

Camera uniform buffer data for shaders.

Color

An RGBA color with f32 components in the 0.0..=1.0 range.

ComputePass

A compute pass wrapper that automatically returns the command buffer to the frame.

ComputePassBuilder

Builder for creating compute passes.

ComputePipelineBuilder

Builder for creating a compute pipeline with common defaults.

DepthTexture

A depth texture with Arc-wrapped view for cheap, lifetime-free sharing.

DispatchIndirect

Indirect dispatch command.

DrawIndexedIndirect

Indirect draw command for indexed geometry.

DrawIndirect

Indirect draw command for non-indexed geometry.

ExecutionPlan

Execution plan for the render graph.

Frame

Context for a single frame of rendering.

FrameStats

Per-frame rendering statistics.

Framebuffer

An offscreen render target with optional depth and MSAA attachments.

FramebufferBuilder

Builder for creating framebuffers with optional attachments.

GpuFeatures

GPU features that can be requested or required.

GpuProfiler

GpuReadback

GPU readback handle for async data retrieval.

GpuTexture

A GPU texture with cached view and metadata.

GraphicsContext

A globally shared graphics context.

GraphicsContextDescriptor

Descriptor for configuring graphics context creation.

IndirectBuffer

A type-safe GPU buffer for indirect draw commands.

LineRenderer

Fast batched line renderer using GPU instancing.

LineSegment

A line segment for batch rendering.

Material

A material manages shader parameters, textures, and pipeline state.

MaterialBuilder

Builder for creating materials with a fluent API.

MaterialTexture

Texture binding information for a material.

Mesh

A mesh containing vertex and optional index data.

MeshBuilder

Builder for creating meshes.

PassId

Pass identifier in the render graph.

PipelineState

Pipeline state configuration for a material.

Point

A point for batch rendering.

PointRenderer

Fast batched point renderer using GPU instancing.

ProfileRegion

A handle to a profiling region.

Quad

A quad (axis-aligned rectangle) for batch rendering.

QuadRenderer

Fast batched quad renderer using GPU instancing.

QueryResultBuffer

Buffer for storing and reading query results.

QuerySet

A wrapper around wgpu::QuerySet with metadata.

RenderContext

Render context passed to pass execution functions.

RenderGraph

Render graph managing passes and resources.

RenderGraphPass

A render pass in the graph.

RenderPass

A render pass that owns its encoder.

RenderPassBuilder

Builder for creating render passes with fluent API.

RenderPipelineBuilder

Builder for creating a render pipeline with sensible defaults.

RenderWindow

A renderable window that combines a winit Window with a WindowContext.

RenderWindowBuilder

Builder for configuring a RenderWindow.

Renderer

Low-level extensible renderer that simplifies WGPU resource management.

ResourceId

Resource identifier in the render graph.

ResourceInfo

Resource information in the render graph.

RingBuffer

A ring buffer for streaming per-frame data.

RingBufferAllocation

A region allocated from a ring buffer.

SamplerCache

A thread-safe cache of GPU samplers.

SamplerKey

A hashable key for sampler descriptors.

SpriteAnimation

Animation state for cycling through sprite sheet frames.

SpriteSheet

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

SpriteSheetDescriptor

Descriptor for creating a sprite sheet.

SpriteUV

UV coordinates for a sprite (normalized 0-1 range).

StagingBuffer

A staging buffer for CPU-to-GPU transfers.

StagingBufferPool

A pool of staging buffers for reuse.

StorageTexture

A texture for compute shader read/write access.

Surface

The acquired surface texture and its view for the current frame.

TextureAtlas

Texture atlas with dynamic rectangle packing.

TextureUploader

Helper to upload texture data from CPU to GPU.

TypedBuffer

A GPU buffer with type-safe element tracking.

Viewport

Viewport definition for rendering.

WindowContext

Manages a wgpu Surface and its configuration for a single window.

WindowContextDescriptor

Descriptor for configuring a window’s rendering context.

WindowManager

Manages multiple renderable windows with automatic event handling.

Enums

BlendMode

Predefined blend modes for common use cases.

ClearOp

Clear operation for a render pass.

ColorOp

Color operation for render pass.

ColorTarget

Target for color attachment in render passes.

DepthClearOp

Depth clear operation for a render pass.

DepthConfig

Configuration for how to handle depth in a render pass.

DepthOp

Depth operation for render pass.

FeatureSupportResult

Result of checking feature support.

GraphicsError

Errors that can occur during graphics context creation.

ImageSampling

Sampling mode for image textures.

MaterialParameter

A material parameter value that can be bound to a shader.

ProjectionMode

Projection mode for a camera.

QueryType

Types of GPU queries.

ReadbackError

GPU readback error.

RenderGraphError

Render graph error.

RenderTarget

A render target that can be either a window surface or an offscreen framebuffer.

ResourceType

Resource type in the render graph.

StorageTextureAccess

Access mode for storage textures in compute shaders.

VertexFormat

Vertex format specification.

Constants

DEFAULT_DEPTH_FORMAT

Default depth format used for depth textures.

DEPTH_FORMAT

Depth format used by framebuffers.

Traits

AsWgpu

Access the underlying wgpu type (immutable).

AsWgpuMut

Access the underlying wgpu type (mutable).

IndirectCommand

Marker trait for indirect draw command types.

IntoWgpu

Consume and return the underlying wgpu type.

ReadbackExt

Extension trait for convenient screenshot capture.

RenderPassIndirectExt

Extension trait for render passes to use indirect buffers.

RenderPassMultiDrawIndirectExt

Extension trait for multi-draw indirect operations.

Type Aliases

UniformBuffer

A uniform buffer for shader uniforms.