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]. It serves as the core of the
5//! WebGPU integration in Firefox, Servo, and Deno.
6//!
7//! [webgpu]: https://gpuweb.github.io/gpuweb/
8//!
9//! ## Getting Started
10//!
11//! The main entry point to the API is the [`Instance`] type, from which you can create [`Adapter`], [`Device`], and [`Surface`].
12//!
13//! If you are new to `wgpu` and graphics programming, we recommend reading
14//! <https://sotrh.github.io/learn-wgpu/> and <https://webgpufundamentals.org/>. The latter is a WebGPU
15//! tutorial, but the concepts are nearly identical to `wgpu`.
16//!
17//! There are examples for this version [available on GitHub](https://github.com/gfx-rs/wgpu/tree/v26/examples#readme)..
18//!
19//! The API is refcounted, so all handles are cloneable, and if you create a resource which references another,
20//! it will automatically keep dependent resources alive.
21//!
22//! ## Feature flags
23#![doc = document_features::document_features!()]
24//!
25//! ### Feature Aliases
26//!
27//! These features aren't actually features on the crate itself, but a convenient shorthand for
28//! complicated cases.
29//!
30//! - **`wgpu_core`** --- Enabled when there is any non-webgpu backend enabled on the platform.
31//! - **`naga`** --- Enabled when target `glsl` or `spirv`` input is enabled, or when `wgpu_core` is enabled.
32//!
33
34#![no_std]
35#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
36#![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")]
37#![warn(
38    clippy::alloc_instead_of_core,
39    clippy::allow_attributes,
40    clippy::std_instead_of_alloc,
41    clippy::std_instead_of_core,
42    missing_docs,
43    rust_2018_idioms,
44    unsafe_op_in_unsafe_fn
45)]
46#![allow(
47    // We need to investiagate these.
48    clippy::large_enum_variant
49)]
50// NOTE: Keep this in sync with `wgpu-core`.
51#![cfg_attr(not(send_sync), allow(clippy::arc_with_non_send_sync))]
52#![cfg_attr(not(any(wgpu_core, webgpu)), allow(unused))]
53
54extern crate alloc;
55#[cfg(std)]
56extern crate std;
57#[cfg(wgpu_core)]
58pub extern crate wgpu_core as wgc;
59#[cfg(wgpu_core)]
60pub extern crate wgpu_hal as hal;
61pub extern crate wgpu_types as wgt;
62
63//
64//
65// Modules
66//
67//
68
69mod api;
70mod backend;
71mod cmp;
72mod dispatch;
73mod macros;
74pub mod util;
75
76//
77//
78// Public re-exports
79//
80//
81
82#[cfg(custom)]
83pub use backend::custom;
84
85pub use api::*;
86pub use wgt::{
87    AdapterInfo, AddressMode, AllocatorReport, AstcBlock, AstcChannel, Backend, BackendOptions,
88    Backends, BindGroupLayoutEntry, BindingType, BlendComponent, BlendFactor, BlendOperation,
89    BlendState, BufferAddress, BufferBindingType, BufferSize, BufferTextureCopyInfo,
90    BufferTransition, BufferUsages, BufferUses, Color, ColorTargetState, ColorWrites,
91    CommandBufferDescriptor, CompareFunction, CompositeAlphaMode, CopyExternalImageDestInfo,
92    CoreCounters, DepthBiasState, DepthStencilState, DeviceLostReason, DeviceType,
93    DownlevelCapabilities, DownlevelFlags, DownlevelLimits, Dx12BackendOptions, Dx12Compiler,
94    DxcShaderModel, DynamicOffset, ExperimentalFeatures, Extent3d, ExternalTextureFormat,
95    ExternalTextureTransferFunction, Face, Features, FeaturesWGPU, FeaturesWebGPU, FilterMode,
96    FrontFace, GlBackendOptions, GlFenceBehavior, Gles3MinorVersion, HalCounters,
97    ImageSubresourceRange, IndexFormat, InstanceDescriptor, InstanceFlags, InternalCounters,
98    Limits, MemoryBudgetThresholds, MemoryHints, MultisampleState, NoopBackendOptions, Origin2d,
99    Origin3d, PipelineStatisticsTypes, PollError, PollStatus, PolygonMode, PowerPreference,
100    PredefinedColorSpace, PresentMode, PresentationTimestamp, PrimitiveState, PrimitiveTopology,
101    PushConstantRange, QueryType, RenderBundleDepthStencil, RequestAdapterError,
102    SamplerBindingType, SamplerBorderColor, ShaderLocation, ShaderModel, ShaderRuntimeChecks,
103    ShaderStages, StencilFaceState, StencilOperation, StencilState, StorageTextureAccess,
104    SurfaceCapabilities, SurfaceStatus, TexelCopyBufferLayout, TextureAspect, TextureDimension,
105    TextureFormat, TextureFormatFeatureFlags, TextureFormatFeatures, TextureSampleType,
106    TextureTransition, TextureUsages, TextureUses, TextureViewDimension, Trace, VertexAttribute,
107    VertexFormat, VertexStepMode, WasmNotSend, WasmNotSendSync, WasmNotSync, COPY_BUFFER_ALIGNMENT,
108    COPY_BYTES_PER_ROW_ALIGNMENT, MAP_ALIGNMENT, PUSH_CONSTANT_ALIGNMENT,
109    QUERY_RESOLVE_BUFFER_ALIGNMENT, QUERY_SET_MAX_QUERIES, QUERY_SIZE, VERTEX_ALIGNMENT,
110};
111
112#[expect(deprecated)]
113pub use wgt::VERTEX_STRIDE_ALIGNMENT;
114
115// wasm-only types, we try to keep as many types non-platform
116// specific, but these need to depend on web-sys.
117#[cfg(web)]
118pub use wgt::{CopyExternalImageSourceInfo, ExternalImageSource};
119
120/// Re-export of our `naga` dependency.
121///
122#[cfg(wgpu_core)]
123#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
124// We re-export wgpu-core's re-export of naga, as we may not have direct access to it.
125pub use ::wgc::naga;
126/// Re-export of our `naga` dependency.
127///
128#[cfg(all(not(wgpu_core), naga))]
129#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
130// If that's not available, we re-export our own.
131pub use naga;
132
133/// Re-export of our `raw-window-handle` dependency.
134///
135pub use raw_window_handle as rwh;
136
137/// Re-export of our `web-sys` dependency.
138///
139#[cfg(web)]
140pub use web_sys;
141
142#[doc(hidden)]
143pub use macros::helpers as __macro_helpers;
wgpu/lib.rs

wgpu/
lib.rs
