wgpu_types/
buffer.rs

1#[cfg(any(feature = "serde", test))]
2use serde::{Deserialize, Serialize};
3
4#[cfg(doc)]
5use crate::{DownlevelFlags, COPY_BUFFER_ALIGNMENT};
6
7/// Describes a [`Buffer`](../wgpu/struct.Buffer.html).
8///
9/// Corresponds to [WebGPU `GPUBufferDescriptor`](
10/// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferdescriptor).
11#[repr(C)]
12#[derive(Clone, Debug, PartialEq, Eq, Hash)]
13#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
14pub struct BufferDescriptor<L, BU = BufferUsages> {
15    /// Debug label of a buffer. This will show up in graphics debuggers for easy identification.
16    pub label: L,
17    /// Size of a buffer, in bytes.
18    pub size: crate::BufferAddress,
19    /// Usages of a buffer. If the buffer is used in any way that isn't specified here, the operation
20    /// will panic.
21    ///
22    /// Specifying only usages the application will actually perform may increase performance.
23    /// Additionally, on the WebGL backend, there are restrictions on [`BufferUsages::INDEX`];
24    /// see [`DownlevelFlags::UNRESTRICTED_INDEX_BUFFER`] for more information.
25    pub usage: BU,
26    /// Allows a buffer to be mapped immediately after they are made. It does not have to be [`BufferUsages::MAP_READ`] or
27    /// [`BufferUsages::MAP_WRITE`], all buffers are allowed to be mapped at creation.
28    ///
29    /// If this is `true`, [`size`](#structfield.size) must be a multiple of
30    /// [`COPY_BUFFER_ALIGNMENT`].
31    pub mapped_at_creation: bool,
32}
33
34impl<L> BufferDescriptor<L> {
35    /// Takes a closure and maps the label of the buffer descriptor into another.
36    #[must_use]
37    pub fn map_label<'a, K>(&'a self, fun: impl FnOnce(&'a L) -> K) -> BufferDescriptor<K> {
38        BufferDescriptor {
39            label: fun(&self.label),
40            size: self.size,
41            usage: self.usage,
42            mapped_at_creation: self.mapped_at_creation,
43        }
44    }
45}
46
47crate::bitflags_array! {
48    /// Different ways that you can use a buffer.
49    ///
50    /// The usages determine what kind of memory the buffer is allocated from and what
51    /// actions the buffer can partake in.
52    ///
53    /// Specifying only usages the application will actually perform may increase performance.
54    /// Additionally, on the WebGL backend, there are restrictions on [`BufferUsages::INDEX`];
55    /// see [`DownlevelFlags::UNRESTRICTED_INDEX_BUFFER`] for more information.
56    ///
57    /// Corresponds to [WebGPU `GPUBufferUsageFlags`](
58    /// https://gpuweb.github.io/gpuweb/#typedefdef-gpubufferusageflags).
59    #[repr(C)]
60    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
61    pub struct (BufferUsages, BufferUsagesBits): [u32; 2];
62
63    /// Buffer usages that are defined in the WebGPU specification.
64    /// For all usages, see [`BufferUsages`].
65    ///
66    /// Corresponds to [WebGPU `GPUBufferUsage`](
67    /// https://gpuweb.github.io/gpuweb/#enumdef-gpubufferusage).
68    #[repr(transparent)]
69    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
70    #[cfg_attr(feature = "serde", serde(transparent))]
71    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
72    pub struct BufferUsagesWebGPU buffer_usages_webgpu {
73        /// Allow a buffer to be mapped for reading using `Buffer::map_async` + `Buffer::get_mapped_range`.
74        /// This does not include creating a buffer with [`BufferDescriptor::mapped_at_creation`] set.
75        ///
76        /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`](crate::Features::MAPPABLE_PRIMARY_BUFFERS) isn't enabled, the only other usage a buffer
77        /// may have is COPY_DST.
78        const MAP_READ = 1 << 0;
79        /// Allow a buffer to be mapped for writing using `Buffer::map_async` + `Buffer::get_mapped_range_mut`.
80        /// This does not include creating a buffer with [`BufferDescriptor::mapped_at_creation`] set.
81        ///
82        /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`](crate::Features::MAPPABLE_PRIMARY_BUFFERS) feature isn't enabled, the only other usage a buffer
83        /// may have is COPY_SRC.
84        const MAP_WRITE = 1 << 1;
85        /// Allow a buffer to be the source buffer for a `CommandEncoder::copy_buffer_to_buffer` or `CommandEncoder::copy_buffer_to_texture`
86        /// operation.
87        const COPY_SRC = 1 << 2;
88        /// Allow a buffer to be the destination buffer for a `CommandEncoder::copy_buffer_to_buffer`, `CommandEncoder::copy_texture_to_buffer`,
89        /// `CommandEncoder::clear_buffer` or `Queue::write_buffer` operation.
90        const COPY_DST = 1 << 3;
91        /// Allow a buffer to be the index buffer in a draw operation.
92        const INDEX = 1 << 4;
93        /// Allow a buffer to be the vertex buffer in a draw operation.
94        const VERTEX = 1 << 5;
95        /// Allow a buffer to be a [`BufferBindingType::Uniform`](crate::BufferBindingType::Uniform) inside a bind group.
96        const UNIFORM = 1 << 6;
97        /// Allow a buffer to be a [`BufferBindingType::Storage`](crate::BufferBindingType::Storage) inside a bind group.
98        const STORAGE = 1 << 7;
99        /// Allow a buffer to be the indirect buffer in an indirect draw call.
100        const INDIRECT = 1 << 8;
101        /// Allow a buffer to be the destination buffer for a `CommandEncoder::resolve_query_set` operation.
102        const QUERY_RESOLVE = 1 << 9;
103    }
104
105    /// Buffer usages that are available in WGPU only when targeting native.
106    /// For all usages, see [`BufferUsages`].
107    #[repr(transparent)]
108    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
109    #[cfg_attr(feature = "serde", serde(transparent))]
110    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
111    pub struct BufferUsagesWGPU buffer_usages_wgpu {
112        /// Allows a buffer to be used as input for a bottom level acceleration structure build
113        const BLAS_INPUT = 1 << 0;
114        /// Allows a buffer to be used as input for a top level acceleration structure build
115        const TLAS_INPUT = 1 << 1;
116    }
117}
118
119bitflags::bitflags! {
120    /// Similar to `BufferUsages`, but used only for `CommandEncoder::transition_resources`.
121    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
122    #[cfg_attr(feature = "serde", serde(transparent))]
123    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
124    pub struct BufferUses: u16 {
125        /// The argument to a read-only mapping.
126        const MAP_READ = 1 << 0;
127        /// The argument to a write-only mapping.
128        const MAP_WRITE = 1 << 1;
129        /// The source of a hardware copy.
130        /// cbindgen:ignore
131        const COPY_SRC = 1 << 2;
132        /// The destination of a hardware copy.
133        /// cbindgen:ignore
134        const COPY_DST = 1 << 3;
135        /// The index buffer used for drawing.
136        const INDEX = 1 << 4;
137        /// A vertex buffer used for drawing.
138        const VERTEX = 1 << 5;
139        /// A uniform buffer bound in a bind group.
140        const UNIFORM = 1 << 6;
141        /// A read-only storage buffer used in a bind group.
142        /// cbindgen:ignore
143        const STORAGE_READ_ONLY = 1 << 7;
144        /// A read-write buffer used in a bind group.
145        /// cbindgen:ignore
146        const STORAGE_READ_WRITE = 1 << 8;
147        /// The indirect or count buffer in a indirect draw or dispatch.
148        const INDIRECT = 1 << 9;
149        /// A buffer used to store query results.
150        const QUERY_RESOLVE = 1 << 10;
151        /// Buffer used for acceleration structure building.
152        const ACCELERATION_STRUCTURE_SCRATCH = 1 << 11;
153        /// Buffer used for bottom level acceleration structure building.
154        const BOTTOM_LEVEL_ACCELERATION_STRUCTURE_INPUT = 1 << 12;
155        /// Buffer used for top level acceleration structure building.
156        const TOP_LEVEL_ACCELERATION_STRUCTURE_INPUT = 1 << 13;
157        /// A buffer used to store the compacted size of an acceleration structure
158        const ACCELERATION_STRUCTURE_QUERY = 1 << 14;
159        /// Buffer used for storing opaque shader data
160        const RAY_TRACING_PIPELINE_SHADER_DATA = 1 << 15;
161        /// The combination of states that a buffer may be in _at the same time_.
162        const INCLUSIVE = Self::MAP_READ.bits() | Self::COPY_SRC.bits() |
163            Self::INDEX.bits() | Self::VERTEX.bits() | Self::UNIFORM.bits() |
164            Self::STORAGE_READ_ONLY.bits() | Self::INDIRECT.bits() | Self::BOTTOM_LEVEL_ACCELERATION_STRUCTURE_INPUT.bits() | Self::TOP_LEVEL_ACCELERATION_STRUCTURE_INPUT.bits() | Self::RAY_TRACING_PIPELINE_SHADER_DATA.bits();
165        /// The combination of states that a buffer must exclusively be in.
166        const EXCLUSIVE = Self::MAP_WRITE.bits() | Self::COPY_DST.bits() | Self::STORAGE_READ_WRITE.bits() | Self::ACCELERATION_STRUCTURE_SCRATCH.bits();
167    }
168}
169
170/// A buffer transition for use with `CommandEncoder::transition_resources`.
171#[derive(Clone, Debug)]
172#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
173pub struct BufferTransition<T> {
174    /// The buffer to transition.
175    pub buffer: T,
176    /// The new state to transition to.
177    pub state: BufferUses,
178}
179
180/// Type of buffer mapping.
181#[repr(C)]
182#[derive(Debug, Clone, Copy, Eq, PartialEq)]
183#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
184pub enum MapMode {
185    /// Map only for reading
186    Read,
187    /// Map only for writing
188    Write,
189}
190static_assertions::assert_impl_all!(MapMode: Send, Sync);
wgpu_types/buffer.rs

wgpu_types/
buffer.rs
