dear_imgui_wgpu/
lib.rs

1//! WGPU backend for Dear ImGui
2//!
3//! This crate provides a WGPU-based renderer for Dear ImGui, allowing you to
4//! render Dear ImGui interfaces using the WGPU graphics API.
5//!
6//! # Features
7//!
8//! - **WGPU version selection**: choose exactly one of:
9//!   - `wgpu-28` (default)
10//!   - `wgpu-27` (for ecosystems pinned to wgpu 27.x, e.g. some Bevy version trains)
11//! - **Modern texture management**: Full integration with Dear ImGui's ImTextureData system
12//! - **External textures**: Register existing `wgpu::Texture` resources for UI display,
13//!   with optional per-texture custom samplers.
14//! - **Gamma correction**: Automatic sRGB format detection and gamma correction
15//! - **Multi-frame buffering**: Support for multiple frames in flight
16//! - **Device object management**: Helpers to recreate device objects (pipelines/buffers/textures) after loss
17//! - **Multi-viewport support**: Support for multiple windows (feature-gated via `multi-viewport-winit` for winit or `multi-viewport-sdl3` for SDL3 on native targets)
18//!
19//! # Example
20//!
21//! ```rust,no_run
22//! use dear_imgui_rs::Context;
23//! use dear_imgui_wgpu::{WgpuRenderer, WgpuInitInfo};
24//! use wgpu::*;
25//!
26//! // Initialize WGPU device and queue
27//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
28//! let instance = Instance::new(&InstanceDescriptor::default());
29//! let adapter = instance.request_adapter(&RequestAdapterOptions::default()).await.unwrap();
30//! let (device, queue) = adapter.request_device(&DeviceDescriptor::default()).await?;
31//!
32//! // Create Dear ImGui context
33//! let mut imgui = Context::create();
34//!
35//! // Create renderer (recommended path)
36//! let init_info = WgpuInitInfo::new(device, queue, TextureFormat::Bgra8UnormSrgb);
37//! let mut renderer = WgpuRenderer::new(init_info, &mut imgui)?;
38//!
39//! // In your render loop:
40//! // imgui.new_frame();
41//! // ... build your UI ...
42//! // let draw_data = imgui.render();
43//! // renderer.render_draw_data(&draw_data, &mut render_pass)?;
44//! # Ok(())
45//! # }
46//! ```
47
48// Select a single wgpu version via features (default: wgpu-28).
49//
50// We keep the public API surface using `wgpu::*` types, but allow downstream crates to opt into a
51// specific major version to better match their ecosystem (e.g. Bevy).
52#[cfg(all(feature = "wgpu-27", feature = "wgpu-28"))]
53compile_error!("Features `wgpu-27` and `wgpu-28` are mutually exclusive; enable only one.");
54#[cfg(not(any(feature = "wgpu-27", feature = "wgpu-28")))]
55compile_error!("Either feature `wgpu-27` or `wgpu-28` must be enabled for dear-imgui-wgpu.");
56
57#[cfg(all(feature = "wgpu-27", feature = "webgl"))]
58compile_error!(
59    "Feature `webgl` selects the wgpu-28 WebGL route; use `webgl-wgpu27` with `wgpu-27`."
60);
61#[cfg(all(feature = "wgpu-27", feature = "webgpu"))]
62compile_error!(
63    "Feature `webgpu` selects the wgpu-28 WebGPU route; use `webgpu-wgpu27` with `wgpu-27`."
64);
65#[cfg(all(feature = "wgpu-28", feature = "webgl-wgpu27"))]
66compile_error!(
67    "Feature `webgl-wgpu27` is incompatible with `wgpu-28` (would pull multiple wgpu majors)."
68);
69#[cfg(all(feature = "wgpu-28", feature = "webgpu-wgpu27"))]
70compile_error!(
71    "Feature `webgpu-wgpu27` is incompatible with `wgpu-28` (would pull multiple wgpu majors)."
72);
73#[cfg(all(feature = "wgpu-27", feature = "webgl-wgpu28"))]
74compile_error!(
75    "Feature `webgl-wgpu28` is incompatible with `wgpu-27` (would pull multiple wgpu majors)."
76);
77#[cfg(all(feature = "wgpu-27", feature = "webgpu-wgpu28"))]
78compile_error!(
79    "Feature `webgpu-wgpu28` is incompatible with `wgpu-27` (would pull multiple wgpu majors)."
80);
81
82#[cfg(feature = "wgpu-27")]
83extern crate wgpu27 as wgpu;
84#[cfg(feature = "wgpu-28")]
85extern crate wgpu28 as wgpu;
86
87// Module declarations
88mod data;
89mod error;
90mod frame_resources;
91mod render_resources;
92mod renderer;
93mod shaders;
94mod texture;
95mod uniforms;
96
97// Re-exports
98pub use data::*;
99pub use error::*;
100pub use frame_resources::*;
101pub use render_resources::*;
102pub use renderer::*;
103pub use shaders::*;
104pub use texture::*;
105pub use uniforms::*;
106
107// Re-export multi-viewport helpers when enabled
108#[cfg(feature = "multi-viewport-winit")]
109pub use renderer::multi_viewport;
110#[cfg(feature = "multi-viewport-sdl3")]
111pub use renderer::multi_viewport_sdl3;
112
113/// Gamma correction mode for the WGPU renderer
114#[derive(Debug, Clone, Copy, PartialEq, Eq)]
115pub enum GammaMode {
116    /// Automatically pick gamma based on render target format (default)
117    Auto,
118    /// Force linear output (gamma = 1.0)
119    Linear,
120    /// Force gamma 2.2 curve (gamma = 2.2)
121    Gamma22,
122}
dear_imgui_wgpu/lib.rs

dear_imgui_wgpu/
lib.rs
