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/v27/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))]
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    // These degrade readability significantly.
50    clippy::bool_assert_comparison,
51    clippy::bool_comparison,
52)]
53// NOTE: Keep this in sync with `wgpu-core`.
54#![cfg_attr(not(send_sync), allow(clippy::arc_with_non_send_sync))]
55#![cfg_attr(not(any(wgpu_core, webgpu)), allow(unused))]
56
57extern crate alloc;
58#[cfg(std)]
59extern crate std;
60#[cfg(wgpu_core)]
61pub extern crate wgpu_core as wgc;
62#[cfg(wgpu_core)]
63pub extern crate wgpu_hal as hal;
64pub extern crate wgpu_types as wgt;
65
66//
67//
68// Modules
69//
70//
71
72mod api;
73mod backend;
74mod cmp;
75mod dispatch;
76mod macros;
77pub mod util;
78
79//
80//
81// Public re-exports
82//
83//
84
85#[cfg(custom)]
86pub use backend::custom;
87
88pub use api::*;
89pub use wgt::{
90    AdapterInfo, AddressMode, AllocatorReport, AstcBlock, AstcChannel, Backend, BackendOptions,
91    Backends, BindGroupLayoutEntry, BindingType, BlendComponent, BlendFactor, BlendOperation,
92    BlendState, BufferAddress, BufferBindingType, BufferSize, BufferTextureCopyInfo,
93    BufferTransition, BufferUsages, BufferUses, Color, ColorTargetState, ColorWrites,
94    CommandBufferDescriptor, CompareFunction, CompositeAlphaMode, CopyExternalImageDestInfo,
95    CoreCounters, DepthBiasState, DepthStencilState, DeviceLostReason, DeviceType,
96    DownlevelCapabilities, DownlevelFlags, DownlevelLimits, Dx12BackendOptions, Dx12Compiler,
97    DxcShaderModel, DynamicOffset, ExperimentalFeatures, Extent3d, ExternalTextureFormat,
98    ExternalTextureTransferFunction, Face, Features, FeaturesWGPU, FeaturesWebGPU, FilterMode,
99    FrontFace, GlBackendOptions, GlFenceBehavior, Gles3MinorVersion, HalCounters,
100    ImageSubresourceRange, IndexFormat, InstanceDescriptor, InstanceFlags, InternalCounters,
101    Limits, MemoryBudgetThresholds, MemoryHints, MipmapFilterMode, MultisampleState,
102    NoopBackendOptions, Origin2d, Origin3d, PipelineStatisticsTypes, PollError, PollStatus,
103    PolygonMode, PowerPreference, PredefinedColorSpace, PresentMode, PresentationTimestamp,
104    PrimitiveState, PrimitiveTopology, PushConstantRange, QueryType, RenderBundleDepthStencil,
105    RequestAdapterError, SamplerBindingType, SamplerBorderColor, ShaderLocation, ShaderModel,
106    ShaderRuntimeChecks, ShaderStages, StencilFaceState, StencilOperation, StencilState,
107    StorageTextureAccess, SurfaceCapabilities, SurfaceStatus, TexelCopyBufferLayout, TextureAspect,
108    TextureDimension, TextureFormat, TextureFormatFeatureFlags, TextureFormatFeatures,
109    TextureSampleType, TextureTransition, TextureUsages, TextureUses, TextureViewDimension, Trace,
110    VertexAttribute, VertexFormat, VertexStepMode, WasmNotSend, WasmNotSendSync, WasmNotSync,
111    COPY_BUFFER_ALIGNMENT, COPY_BYTES_PER_ROW_ALIGNMENT, MAP_ALIGNMENT, PUSH_CONSTANT_ALIGNMENT,
112    QUERY_RESOLVE_BUFFER_ALIGNMENT, QUERY_SET_MAX_QUERIES, QUERY_SIZE, VERTEX_ALIGNMENT,
113};
114
115#[expect(deprecated)]
116pub use wgt::VERTEX_STRIDE_ALIGNMENT;
117
118// wasm-only types, we try to keep as many types non-platform
119// specific, but these need to depend on web-sys.
120#[cfg(web)]
121pub use wgt::{CopyExternalImageSourceInfo, ExternalImageSource};
122
123/// Re-export of our `naga` dependency.
124///
125#[cfg(wgpu_core)]
126#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
127// We re-export wgpu-core's re-export of naga, as we may not have direct access to it.
128pub use ::wgc::naga;
129/// Re-export of our `naga` dependency.
130///
131#[cfg(all(not(wgpu_core), naga))]
132#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))]
133// If that's not available, we re-export our own.
134pub use naga;
135
136/// Re-export of our `raw-window-handle` dependency.
137///
138pub use raw_window_handle as rwh;
139
140/// Re-export of our `web-sys` dependency.
141///
142#[cfg(web)]
143pub use web_sys;
144
145#[doc(hidden)]
146pub use macros::helpers as __macro_helpers;
wgpu/lib.rs

wgpu/
lib.rs
