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

wgpu/
lib.rs
