Skip to main content

wgame_gfx/
lib.rs

1//! GPU rendering with ordered scenes, reusable renderers, and window/offscreen targets.
2//!
3//! Collect changing objects in a [`Scene`], then draw through [`Target::render_iter`].
4//! For unchanged content, [`Scene::bake`] produces a [`BakedScene`] that reuses its
5//! instance buffers across frames and cameras. See those types for painter order,
6//! resource lifetimes, and rebaking rules.
7//!
8//! [`Target::camera`] supplies aspect-correct coordinates; [`Target::physical_camera`]
9//! uses physical pixels. [`AutoScene`] provides automatic rendering on normal drop.
10//! [`Target::viewport`] borrows a clipped rectangle with its own camera coordinates
11//! for previews, split-screen views, and nested drawing areas.
12//!
13//! # Custom and headless rendering
14//!
15//! Use [`Graphics::device`] and [`Graphics::queue`] for direct wgpu access. Implement
16//! [`Renderer<C>`] to encode drawing in a supplied render pass and [`Context`] for
17//! shared bindings. [`Target`] abstracts window frames and [`Offscreen`] textures.
18//! [`Graphics::new`] wraps a supplied adapter/device/queue for headless applications.
19//! The facade's `raw_wgpu` example demonstrates a custom pipeline.
20
21#![forbid(unsafe_code)]
22
23mod auto;
24mod camera;
25mod clear;
26mod depth;
27mod frame;
28mod instance;
29pub mod modifiers;
30mod object;
31mod offscreen;
32mod order;
33mod renderer;
34mod resource;
35mod scene;
36mod state;
37mod surface;
38mod target;
39pub mod types;
40pub mod utils;
41mod viewport;
42
43pub use self::{
44    auto::AutoScene,
45    camera::Camera,
46    depth::{DEPTH_FORMAT, DepthBuffer, DepthMode},
47    frame::Frame,
48    instance::{AnyStorage, Instance, Storage},
49    object::{InstanceVisitor, Object},
50    offscreen::Offscreen,
51    order::Ordered,
52    renderer::{Context, Renderer},
53    resource::{AnyResource, Resource},
54    scene::{BakedScene, Scene},
55    state::Graphics,
56    surface::Surface,
57    target::Target,
58    viewport::{Viewport, ViewportError},
59};
60pub use anyhow::Error;
61pub use wgpu::PresentMode;
62
63/// Commonly used types and traits.
64pub mod prelude {
65    #[doc(no_inline)]
66    pub use crate::{Object, Renderer, Target, modifiers::*};
67}
68
69/// Surface presentation and GPU device requirements.
70///
71/// Defaults support WebGL2 graphics without compute or storage bindings. Request
72/// compute-capable limits explicitly on a backend that supports them:
73///
74/// ```
75/// let config = wgame_gfx::Config {
76///     required_limits: wgpu::Limits::default(),
77///     ..Default::default()
78/// };
79/// ```
80///
81/// Surface creation fails if the selected adapter cannot satisfy the requested
82/// features and non-texture limits.
83#[derive(Clone, Debug)]
84pub struct Config {
85    pub present_mode: wgpu::PresentMode,
86    /// Optional GPU features to enable. Defaults to none.
87    pub required_features: wgpu::Features,
88    /// Required device limits. Defaults to WebGL2-compatible limits.
89    ///
90    /// The three texture-dimension limits use the adapter's supported maxima so
91    /// render targets can match the window resolution. Other limits are
92    /// requested as supplied, except buffer limits when
93    /// [`Self::use_adapter_buffer_limits`] is enabled.
94    pub required_limits: wgpu::Limits,
95    /// Request the adapter's maximum storage-binding and buffer-allocation sizes.
96    ///
97    /// Defaults to false. When enabled, replaces `max_storage_buffer_binding_size`
98    /// and `max_buffer_size` in [`Self::required_limits`] with the adapter's
99    /// supported values. This permits larger buffers without allocating memory;
100    /// individual allocations still depend on available resources.
101    pub use_adapter_buffer_limits: bool,
102}
103
104impl Default for Config {
105    fn default() -> Self {
106        Self {
107            present_mode: wgpu::PresentMode::AutoVsync,
108            required_features: wgpu::Features::empty(),
109            required_limits: wgpu::Limits::downlevel_webgl2_defaults(),
110            use_adapter_buffer_limits: false,
111        }
112    }
113}