wgpu/
lib.rs

1//! `wgpu` is a cross-platform, safe, pure-Rust graphics API. It runs natively on
2//! Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.
3//!
4//! The API is based on the [WebGPU standard][webgpu], but is a fully native Rust library
5//! and includes many extensions specific to the native backends. It serves as the core of
6//! the WebGPU integration in Firefox, Servo, and Deno.
7//!
8//! [webgpu]: https://gpuweb.github.io/gpuweb/
9//!
10//! ## Getting Started
11//!
12//! The main entry point to the API is the [`Instance`] type, from which you can create [`Adapter`], [`Device`], and [`Surface`].
13//!
14//! If you are new to `wgpu` and graphics programming, we recommend starting with [Learn Wgpu].
15//! <!-- Note, "Learn Wgpu" is using the capitalization style in their header, NOT our styling -->
16//!
17//! Additionally, [WebGPU Fundamentals] is a tutorial for WebGPU which is very similar to our API, minus differences between Rust and Javascript.
18//!
19//! Most types and functions are documented, but for more general guides and explanations, see the [documentation modules][documentation].
20//!
21//! - [Shader `debugPrintf`](documentation::extensions::debug_printf).
22//!
23//! There are examples for this version [available on GitHub](https://github.com/gfx-rs/wgpu/tree/v30/examples#readme).
24//!
25//! The API is refcounted, so all handles are cloneable, and if you create a resource which references another,
26//! it will automatically keep dependent resources alive.
27//!
28//! `wgpu` uses the coordinate systems of D3D and Metal. Depth ranges from [0, 1].
29//!
30//! | Render | Texture |
31//! | --- | --- |
32//! | ![Render coordinates][render_coordinates.webp] | ![Texture coordinates][texture_coordinates.webp] |
33//!
34//! `wgpu`'s MSRV is **1.87**.
35//!
36//! [Learn Wgpu]: https://sotrh.github.io/learn-wgpu/
37//! [WebGPU Fundamentals]: https://webgpufundamentals.org/
38//!
39#![doc = crate::macros::doc_image!("render_coordinates.webp")]
40#![doc = crate::macros::doc_image!("texture_coordinates.webp")]
41#![no_std]
42#![cfg_attr(docsrs, feature(doc_cfg))]
43#![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")]
44#![warn(
45    clippy::alloc_instead_of_core,
46    clippy::allow_attributes,
47    clippy::std_instead_of_alloc,
48    clippy::std_instead_of_core,
49    missing_docs,
50    rust_2018_idioms,
51    unsafe_op_in_unsafe_fn
52)]
53#![allow(
54    // We need to investiagate these.
55    clippy::large_enum_variant,
56    // These degrade readability significantly.
57    clippy::bool_assert_comparison,
58    clippy::bool_comparison,
59)]
60// NOTE: Keep this in sync with `wgpu-core`.
61#![cfg_attr(not(send_sync), allow(clippy::arc_with_non_send_sync))]
62#![cfg_attr(not(any(wgpu_core, webgpu)), allow(unused))]
63
64extern crate alloc;
65#[cfg(any(std, test))]
66extern crate std;
67#[cfg(wgpu_core)]
68pub extern crate wgpu_core as wgc;
69#[cfg(wgpu_core)]
70pub extern crate wgpu_hal as hal;
71pub extern crate wgpu_types as wgt;
72
73//
74//
75// Modules
76//
77//
78
79mod api;
80mod backend;
81mod cmp;
82mod dispatch;
83pub mod documentation;
84mod macros;
85pub mod util;
86
87//
88//
89// Public re-exports
90//
91//
92
93#[cfg(custom)]
94pub use backend::custom;
95
96pub use api::*;
97pub use wgt::{
98    AdapterInfo, AddressMode, AllocatorReport, AstcBlock, AstcChannel, Backend, BackendOptions,
99    Backends, BindGroupLayoutEntry, BindingType, BlendComponent, BlendFactor, BlendOperation,
100    BlendState, BufferAddress, BufferBindingType, BufferSize, BufferTextureCopyInfo,
101    BufferTransition, BufferUsages, BufferUses, Color, ColorTargetState, ColorWrites,
102    CommandBufferDescriptor, CompareFunction, ComponentSwizzle, CompositeAlphaMode,
103    CooperativeMatrixProperties, CooperativeScalarType, CopyExternalImageDestInfo, CoreCounters,
104    DepthBiasState, DepthStencilState, DeviceLostReason, DeviceType, DisplayChromaticity,
105    DisplayCoarseRange, DisplayGamut, DisplayHdrInfo, DisplayHeadroom, DisplayLuminance,
106    DownlevelCapabilities, DownlevelFlags, DownlevelLimits, Dx12BackendOptions, Dx12Compiler,
107    Dx12SwapchainKind, Dx12UseFrameLatencyWaitableObject, DxcShaderModel, DynamicOffset,
108    ExperimentalFeatures, Extent3d, ExternalTextureFormat, ExternalTextureTransferFunction, Face,
109    Features, FeaturesWGPU, FeaturesWebGPU, FilterMode, ForceShaderModelToken, FrontFace,
110    GlBackendOptions, GlDebugFns, GlFenceBehavior, Gles3MinorVersion, HalCounters,
111    ImageSubresourceRange, IndexFormat, InstanceDescriptor, InstanceFlags, InternalCounters,
112    Limits, LoadOpDontCare, MapMode, MemoryBudgetThresholds, MemoryHints, MipmapFilterMode,
113    MultisampleState, NoopBackendOptions, Origin2d, Origin3d, PassthroughShaderEntryPoint,
114    PipelineStatisticsTypes, PollError, PollStatus, PolygonMode, PowerPreference,
115    PredefinedColorSpace, PresentMode, PresentationTimestamp, PrimitiveState, PrimitiveTopology,
116    QueryType, RenderBundleDepthStencil, RequestAdapterError, SamplerBindingType,
117    SamplerBorderColor, ShaderLocation, ShaderModel, ShaderRuntimeChecks, ShaderStages,
118    StencilFaceState, StencilOperation, StencilState, StorageTextureAccess, SurfaceCapabilities,
119    SurfaceColorSpace, SurfaceColorSpaces, SurfaceFormatCapabilities, SurfaceStatus,
120    TexelCopyBufferLayout, TextureAspect, TextureChannel, TextureComponentSwizzle,
121    TextureDimension, TextureFormat, TextureFormatFeatureFlags, TextureFormatFeatures,
122    TextureSampleType, TextureTransition, TextureUsages, TextureUses, TextureViewDimension, Trace,
123    VertexAttribute, VertexFormat, VertexStepMode, WasmNotSend, WasmNotSendSync, WasmNotSync,
124    WriteOnly, WriteOnlyIter, COPY_BUFFER_ALIGNMENT, COPY_BYTES_PER_ROW_ALIGNMENT,
125    IMMEDIATE_DATA_ALIGNMENT, MAP_ALIGNMENT, MAXIMUM_SUBGROUP_MAX_SIZE, MINIMUM_SUBGROUP_MIN_SIZE,
126    QUERY_RESOLVE_BUFFER_ALIGNMENT, QUERY_SET_MAX_QUERIES, QUERY_SIZE, VERTEX_ALIGNMENT,
127};
128
129#[expect(deprecated)]
130pub use wgt::VERTEX_STRIDE_ALIGNMENT;
131
132// wasm-only types, we try to keep as many types non-platform
133// specific, but these need to depend on web-sys.
134#[cfg(web)]
135pub use wgt::{CopyExternalImageSourceInfo, ExternalImageSource};
136
137/// Re-export of our `naga` dependency.
138///
139#[cfg(wgpu_core)]
140#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
141// We re-export wgpu-core's re-export of naga, as we may not have direct access to it.
142pub use ::wgc::naga;
143/// Re-export of our `naga` dependency.
144///
145#[cfg(all(not(wgpu_core), naga))]
146#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
147// If that's not available, we re-export our own.
148pub use naga;
149
150/// Re-export of our `raw-window-handle` dependency.
151///
152pub use raw_window_handle as rwh;
153
154/// Re-export of our `web-sys` dependency.
155///
156#[cfg(web)]
157pub use web_sys;
158
159/// Vendored WebGPU JS-handle types used by the WebGPU backend.
160///
161/// They are exposed publicly so that interop crates can read the JS handle
162/// behind a [`Texture`] / [`Buffer`] / etc. (via [`Texture::as_webgpu`] and
163/// siblings), and pass a foreign handle in (via
164/// [`Device::create_texture_from_webgpu_handle`]).
165///
166/// A `web_sys::GpuTexture` from a consumer's own `web-sys` dependency wraps
167/// the same JS object as a `wgpu::webgpu::GpuTexture`; convert between them
168/// with [`wasm_bindgen::JsCast::unchecked_into`].
169#[cfg(webgpu)]
170pub mod webgpu {
171    pub use crate::backend::webgpu::webgpu_sys::{
172        GpuBuffer, GpuDevice, GpuExternalTexture, GpuQueue, GpuTexture, GpuTextureView,
173    };
174    pub use crate::backend::webgpu::{DropCallback, ExternalTextureSource};
175}
176
177#[doc(hidden)]
178pub use macros::helpers as __macro_helpers;
wgpu/lib.rs

wgpu/
lib.rs
