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> {
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: BufferUsages,
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<K>(&self, fun: impl FnOnce(&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
47bitflags::bitflags! {
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(transparent)]
60 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
61 #[cfg_attr(feature = "serde", serde(transparent))]
62 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
63 pub struct BufferUsages: u32 {
64 /// Allow a buffer to be mapped for reading using [`Buffer::map_async`] + [`Buffer::get_mapped_range`].
65 /// This does not include creating a buffer with [`BufferDescriptor::mapped_at_creation`] set.
66 ///
67 /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`] isn't enabled, the only other usage a buffer
68 /// may have is COPY_DST.
69 const MAP_READ = 1 << 0;
70 /// Allow a buffer to be mapped for writing using [`Buffer::map_async`] + [`Buffer::get_mapped_range_mut`].
71 /// This does not include creating a buffer with [`BufferDescriptor::mapped_at_creation`] set.
72 ///
73 /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`] feature isn't enabled, the only other usage a buffer
74 /// may have is COPY_SRC.
75 const MAP_WRITE = 1 << 1;
76 /// Allow a buffer to be the source buffer for a [`CommandEncoder::copy_buffer_to_buffer`] or [`CommandEncoder::copy_buffer_to_texture`]
77 /// operation.
78 const COPY_SRC = 1 << 2;
79 /// Allow a buffer to be the destination buffer for a [`CommandEncoder::copy_buffer_to_buffer`], [`CommandEncoder::copy_texture_to_buffer`],
80 /// [`CommandEncoder::clear_buffer`] or [`Queue::write_buffer`] operation.
81 const COPY_DST = 1 << 3;
82 /// Allow a buffer to be the index buffer in a draw operation.
83 const INDEX = 1 << 4;
84 /// Allow a buffer to be the vertex buffer in a draw operation.
85 const VERTEX = 1 << 5;
86 /// Allow a buffer to be a [`BufferBindingType::Uniform`] inside a bind group.
87 const UNIFORM = 1 << 6;
88 /// Allow a buffer to be a [`BufferBindingType::Storage`] inside a bind group.
89 const STORAGE = 1 << 7;
90 /// Allow a buffer to be the indirect buffer in an indirect draw call.
91 const INDIRECT = 1 << 8;
92 /// Allow a buffer to be the destination buffer for a [`CommandEncoder::resolve_query_set`] operation.
93 const QUERY_RESOLVE = 1 << 9;
94 /// Allows a buffer to be used as input for a bottom level acceleration structure build
95 const BLAS_INPUT = 1 << 10;
96 /// Allows a buffer to be used as input for a top level acceleration structure build
97 const TLAS_INPUT = 1 << 11;
98 }
99}
100
101bitflags::bitflags! {
102 /// Similar to `BufferUsages`, but used only for `CommandEncoder::transition_resources`.
103 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
104 #[cfg_attr(feature = "serde", serde(transparent))]
105 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
106 pub struct BufferUses: u16 {
107 /// The argument to a read-only mapping.
108 const MAP_READ = 1 << 0;
109 /// The argument to a write-only mapping.
110 const MAP_WRITE = 1 << 1;
111 /// The source of a hardware copy.
112 /// cbindgen:ignore
113 const COPY_SRC = 1 << 2;
114 /// The destination of a hardware copy.
115 /// cbindgen:ignore
116 const COPY_DST = 1 << 3;
117 /// The index buffer used for drawing.
118 const INDEX = 1 << 4;
119 /// A vertex buffer used for drawing.
120 const VERTEX = 1 << 5;
121 /// A uniform buffer bound in a bind group.
122 const UNIFORM = 1 << 6;
123 /// A read-only storage buffer used in a bind group.
124 /// cbindgen:ignore
125 const STORAGE_READ_ONLY = 1 << 7;
126 /// A read-write buffer used in a bind group.
127 /// cbindgen:ignore
128 const STORAGE_READ_WRITE = 1 << 8;
129 /// The indirect or count buffer in a indirect draw or dispatch.
130 const INDIRECT = 1 << 9;
131 /// A buffer used to store query results.
132 const QUERY_RESOLVE = 1 << 10;
133 /// Buffer used for acceleration structure building.
134 const ACCELERATION_STRUCTURE_SCRATCH = 1 << 11;
135 /// Buffer used for bottom level acceleration structure building.
136 const BOTTOM_LEVEL_ACCELERATION_STRUCTURE_INPUT = 1 << 12;
137 /// Buffer used for top level acceleration structure building.
138 const TOP_LEVEL_ACCELERATION_STRUCTURE_INPUT = 1 << 13;
139 /// A buffer used to store the compacted size of an acceleration structure
140 const ACCELERATION_STRUCTURE_QUERY = 1 << 14;
141 /// The combination of states that a buffer may be in _at the same time_.
142 const INCLUSIVE = Self::MAP_READ.bits() | Self::COPY_SRC.bits() |
143 Self::INDEX.bits() | Self::VERTEX.bits() | Self::UNIFORM.bits() |
144 Self::STORAGE_READ_ONLY.bits() | Self::INDIRECT.bits() | Self::BOTTOM_LEVEL_ACCELERATION_STRUCTURE_INPUT.bits() | Self::TOP_LEVEL_ACCELERATION_STRUCTURE_INPUT.bits();
145 /// The combination of states that a buffer must exclusively be in.
146 const EXCLUSIVE = Self::MAP_WRITE.bits() | Self::COPY_DST.bits() | Self::STORAGE_READ_WRITE.bits() | Self::ACCELERATION_STRUCTURE_SCRATCH.bits();
147 /// The combination of all usages that the are guaranteed to be be ordered by the hardware.
148 /// If a usage is ordered, then if the buffer state doesn't change between draw calls, there
149 /// are no barriers needed for synchronization.
150 const ORDERED = Self::INCLUSIVE.bits() | Self::MAP_WRITE.bits();
151 }
152}
153
154/// A buffer transition for use with `CommandEncoder::transition_resources`.
155#[derive(Clone, Debug)]
156#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
157pub struct BufferTransition<T> {
158 /// The buffer to transition.
159 pub buffer: T,
160 /// The new state to transition to.
161 pub state: BufferUses,
162}