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}