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

wgpu/
lib.rs
