Lines Matching +full:is +full:- +full:buffer
3 // <LICENSE-APACHE or
4 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT
5 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>,
12 //! A Vulkan buffer is very similar to a buffer that you would use in programming languages in
13 //! general, in the sense that it is a location in memory that contains data. The difference
14 //! between a Vulkan buffer and a regular buffer is that the content of a Vulkan buffer is
17 //! Vulkano does not perform any specific marshalling of buffer data. The representation of the
18 //! buffer in memory is identical between the CPU and GPU. Because the Rust compiler is allowed to
19 //! reorder struct fields at will by default when using `#[repr(Rust)]`, it is advised to mark each
21 //! procedure. Each element is laid out in memory in the order of declaration and aligned to a
26 //! - The low-level implementation of a buffer is [`RawBuffer`], which corresponds directly to a
28 //! - [`Buffer`] is a `RawBuffer` with memory bound to it, and with state tracking.
29 //! - [`Subbuffer`] is what you will use most of the time, as it is what all the APIs expect. It is
30 //! a reference to a portion of a `Buffer`. `Subbuffer` also has a type parameter, which is a
31 //! hint for how the data in the portion of the buffer is going to be interpreted.
37 //! - By using the functions on `Buffer`, which create a new buffer and memory allocation each
38 //! time, and give you a `Subbuffer` that has an entire `Buffer` dedicated to it.
39 //! - By using the [`SubbufferAllocator`], which creates `Subbuffer`s by suballocating existing
40 //! `Buffer`s such that the `Buffer`s can keep being reused.
46 //! once, or you can keep reusing the same buffer (because its size is unchanging) it's best to
47 //! use a dedicated `Buffer` for that.
51 //! When allocating memory for a buffer, you have to specify a *memory usage*. This tells the
54 //! - [`MemoryUsage::DeviceOnly`] will allocate a buffer that's usually located in device-local
56 //! buffer from the device is generally faster compared to accessing a buffer that's located in
57 //! host-visible memory.
58 //! - [`MemoryUsage::Upload`] and [`MemoryUsage::Download`] both allocate from a host-visible
59 //! memory type, which means the buffer can be accessed directly from the host. Buffers allocated
62 //! Take for example a buffer that is under constant access by the device but you need to read its
63 //! content on the host from time to time, it may be a good idea to use a device-local buffer as
64 //! the main buffer and a host-visible buffer for when you need to read it. Then whenever you need
65 //! to read the main buffer, ask the device to copy from the device-local buffer to the
66 //! host-visible buffer, and read the host-visible buffer instead.
68 //! # Buffer usage
70 //! When you create a buffer, you have to specify its *usage*. In other words, you have to
71 //! specify the way it is going to be used. Trying to use a buffer in a way that wasn't specified
76 //! - Can contain arbitrary data that can be transferred from/to other buffers and images.
77 //! - Can be read and modified from a shader.
78 //! - Can be used as a source of vertices and indices.
79 //! - Can be used as a source of list of models for draw indirect commands.
81 //! Accessing a buffer from a shader can be done in the following ways:
83 //! - As a uniform buffer. Uniform buffers are read-only.
84 //! - As a storage buffer. Storage buffers can be read and written.
85 //! - As a uniform texel buffer. Contrary to a uniform buffer, the data is interpreted by the GPU
87 //! - As a storage texel buffer. Additionally, some data formats can be modified with atomic
90 //! Using uniform/storage texel buffers requires creating a *buffer view*. See [the `view` module]
91 //! for how to create a buffer view.
93 //! See also [the `shader` module documentation] for information about how buffer contents need to
149 /// Unlike [`RawBuffer`], a `Buffer` has memory backing it, and can be used normally.
151 /// See [the module-level documentation] for more information about buffers.
155 /// Sometimes, you need a buffer that is rarely accessed by the host. To get the best performance
156 /// in this case, one should use a buffer in device-local memory, that is inaccessible from the
157 /// host. As such, to initialize or otherwise access such a buffer, we need a *staging buffer*.
160 /// device-local buffer.
164 /// buffer::{BufferUsage, Buffer, BufferCreateInfo},
181 /// // Create a host-accessible buffer initialized with the data.
182 /// let temporary_accessible_buffer = Buffer::from_iter(
185 /// // Specify that this buffer will be used as a transfer source.
198 /// // Create a buffer in device-local with enough space for a slice of `10_000` floats.
199 /// let device_local_buffer = Buffer::new_slice::<f32>(
202 /// // Specify use as a storage buffer and transfer destination.
215 /// // Create a one-time command to copy between the buffers.
238 /// [the module-level documentation]: self
240 pub struct Buffer { struct
246 /// The type of backing memory that a buffer can have.
249 /// The buffer is backed by normal memory, bound with [`bind_memory`].
254 /// The buffer is backed by sparse memory, bound with [`bind_sparse`].
260 impl Buffer { implementation
261 /// Creates a new `Buffer` and writes `data` in it. Returns a [`Subbuffer`] spanning the whole
262 /// buffer.
264 /// This only works with memory types that are host-visible. If you want to upload data to a
265 /// buffer allocated in device-local memory, you will need to create a staging buffer and copy
273 /// - Panics if `T` has zero size.
274 /// - Panics if `T` has an alignment greater than `64`.
280 ) -> Result<Subbuffer<T>, BufferError> in from_data()
284 let buffer = Buffer::new_sized(allocator, buffer_info, allocation_info)?; in from_data() localVariable
286 unsafe { ptr::write(&mut *buffer.write()?, data) }; in from_data()
288 Ok(buffer) in from_data()
291 /// Creates a new `Buffer` and writes all elements of `iter` in it. Returns a [`Subbuffer`]
292 /// spanning the whole buffer.
294 /// This only works with memory types that are host-visible. If you want to upload data to a
295 /// buffer allocated in device-local memory, you will need to create a staging buffer and copy
303 /// - Panics if `iter` is empty.
309 ) -> Result<Subbuffer<[T]>, BufferError> in from_iter()
316 let buffer = Buffer::new_slice( in from_iter() localVariable
323 for (o, i) in buffer.write()?.iter_mut().zip(iter) { in from_iter()
327 Ok(buffer) in from_iter()
330 /// Creates a new uninitialized `Buffer` for sized data. Returns a [`Subbuffer`] spanning the
331 /// whole buffer.
339 ) -> Result<Subbuffer<T>, BufferError> in new_sized()
344 let buffer = Subbuffer::new(Buffer::new( in new_sized() localVariable
351 Ok(unsafe { buffer.reinterpret_unchecked() }) in new_sized()
354 /// Creates a new uninitialized `Buffer` for a slice. Returns a [`Subbuffer`] spanning the
355 /// whole buffer.
362 /// - Panics if `len` is zero.
368 ) -> Result<Subbuffer<[T]>, BufferError> in new_slice()
372 Buffer::new_unsized(allocator, buffer_info, allocation_info, len) in new_slice()
375 /// Creates a new uninitialized `Buffer` for unsized data. Returns a [`Subbuffer`] spanning the
376 /// whole buffer.
383 /// - Panics if `len` is zero.
389 ) -> Result<Subbuffer<T>, BufferError> in new_unsized()
393 let len = NonZeroDeviceSize::new(len).expect("empty slices are not valid buffer contents"); in new_unsized()
395 let buffer = Subbuffer::new(Buffer::new( in new_unsized() localVariable
402 Ok(unsafe { buffer.reinterpret_unchecked() }) in new_unsized()
405 /// Creates a new uninitialized `Buffer` with the given `layout`.
412 /// - Panics if `layout.alignment()` is greater than 64.
418 ) -> Result<Arc<Self>, BufferError> { in new()
425 "`Buffer::new*` functions set the `buffer_info.size` field themselves, you should not \ in new()
440 Some(DedicatedAllocation::Buffer(&raw_buffer)), in new()
449 // The implementation might require a larger size than we wanted. With this it is easier to in new()
450 // invalidate and flush the whole buffer. It does not affect the allocation in any way. in new()
458 fn from_raw(inner: RawBuffer, memory: BufferMemory) -> Self { in from_raw()
461 Buffer { in from_raw()
468 /// Returns the type of memory that is backing this buffer.
470 pub fn memory(&self) -> &BufferMemory { in memory()
474 /// Returns the memory requirements for this buffer.
476 pub fn memory_requirements(&self) -> &MemoryRequirements { in memory_requirements()
480 /// Returns the flags the buffer was created with.
482 pub fn flags(&self) -> BufferCreateFlags { in flags()
486 /// Returns the size of the buffer in bytes.
488 pub fn size(&self) -> DeviceSize { in size()
492 /// Returns the usage the buffer was created with.
494 pub fn usage(&self) -> BufferUsage { in usage()
498 /// Returns the sharing the buffer was created with.
500 pub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>> { in sharing()
504 /// Returns the external memory handle types that are supported with this buffer.
506 pub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes { in external_memory_handle_types()
510 /// Returns the device address for this buffer.
512 pub fn device_address(&self) -> Result<NonZeroDeviceSize, BufferError> { in device_address()
515 // VUID-vkGetBufferDeviceAddress-bufferDeviceAddress-03324 in device_address()
518 required_for: "`Buffer::device_address`", in device_address()
526 // VUID-VkBufferDeviceAddressInfo-buffer-02601 in device_address()
532 buffer: self.handle(), in device_address()
548 pub(crate) fn state(&self) -> MutexGuard<'_, BufferState> { in state()
553 unsafe impl VulkanObject for Buffer { implementation
554 type Handle = ash::vk::Buffer;
557 fn handle(&self) -> Self::Handle { in handle()
562 unsafe impl DeviceOwned for Buffer { implementation
564 fn device(&self) -> &Arc<Device> { in device()
569 impl PartialEq for Buffer { implementation
571 fn eq(&self, other: &Self) -> bool { in eq()
576 impl Eq for Buffer {} implementation
578 impl Hash for Buffer { implementation
584 /// The current state of a buffer.
591 fn new(size: DeviceSize) -> Self { in new()
607 pub(crate) fn check_cpu_read(&self, range: Range<DeviceSize>) -> Result<(), ReadLockError> { in check_cpu_read()
628 _ => unreachable!("Buffer is being written by the CPU or GPU"), in cpu_read_lock()
639 CurrentAccess::Shared { cpu_reads, .. } => *cpu_reads -= 1, in cpu_read_unlock()
640 _ => unreachable!("Buffer was not locked for CPU read"), in cpu_read_unlock()
645 pub(crate) fn check_cpu_write(&self, range: Range<DeviceSize>) -> Result<(), WriteLockError> { in check_cpu_write()
685 _ => unreachable!("Buffer was not locked for CPU write"), in cpu_write_unlock()
690 pub(crate) fn check_gpu_read(&self, range: Range<DeviceSize>) -> Result<(), AccessError> { in check_gpu_read()
709 _ => unreachable!("Buffer is being written by the CPU"), in gpu_read_lock()
720 CurrentAccess::GpuExclusive { gpu_reads, .. } => *gpu_reads -= 1, in gpu_read_unlock()
721 CurrentAccess::Shared { gpu_reads, .. } => *gpu_reads -= 1, in gpu_read_unlock()
722 _ => unreachable!("Buffer was not locked for GPU read"), in gpu_read_unlock()
727 pub(crate) fn check_gpu_write(&self, range: Range<DeviceSize>) -> Result<(), AccessError> { in check_gpu_write()
757 _ => unreachable!("Buffer is being accessed by the CPU"), in gpu_write_lock()
777 CurrentAccess::GpuExclusive { gpu_writes, .. } => *gpu_writes -= 1, in gpu_write_unlock()
778 _ => unreachable!("Buffer was not locked for GPU write"), in gpu_write_unlock()
784 /// The current state of a specific range of bytes in a buffer.
790 /// Error that can happen in buffer functions.
803 /// The buffer is missing the `SHADER_DEVICE_ADDRESS` usage.
806 /// The memory was created dedicated to a resource, but not to this buffer.
809 /// A dedicated allocation is required for this buffer, but one was not provided.
812 /// The host is already using this buffer in a way that is incompatible with the
816 /// The device is already using this buffer in a way that is incompatible with the
832 /// The size of the allocation is smaller than what is required.
838 /// The buffer was created with the `SHADER_DEVICE_ADDRESS` usage, but the memory does not
843 /// enabled on the buffer.
850 /// the buffer.
856 /// The memory backing this buffer is not visible to the host.
859 /// The protection of buffer and memory are not equal.
865 /// The provided memory type is not one of the allowed memory types that can be bound to this
866 /// buffer.
881 fn source(&self) -> Option<&(dyn Error + 'static)> { in source()
891 fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> { in fmt()
904 write!(f, "the buffer is missing the `SHADER_DEVICE_ADDRESS` usage") in fmt()
908 "the memory was created dedicated to a resource, but not to this buffer", in fmt()
912 "a dedicated allocation is required for this buffer, but one was not provided" in fmt()
916 "the host is already using this buffer in a way that is incompatible with the \ in fmt()
921 "the device is already using this buffer in a way that is incompatible with the \ in fmt()
941 "the size of the allocation ({}) is smaller than what is required ({})", in fmt()
946 "the buffer was created with the `SHADER_DEVICE_ADDRESS` usage, but the memory \ in fmt()
952 were enabled on the buffer", in fmt()
957 enabled on the buffer", in fmt()
961 "the memory backing this buffer is not visible to the host", in fmt()
968 "the protection of buffer ({}) and memory ({}) are not equal", in fmt()
976 "the provided memory type ({}) is not one of the allowed memory types (", in fmt()
995 .and_then(|_| write!(f, ") that can be bound to this buffer")), in fmt()
1006 fn from(err: VulkanError) -> Self { in from()
1012 fn from(err: AllocationCreationError) -> Self { in from()
1018 fn from(err: RequirementNotMet) -> Self { in from()
1027 fn from(err: ReadLockError) -> Self { in from()
1036 fn from(err: WriteLockError) -> Self { in from()
1047 /// Flags to be set when creating a buffer.
1051 /// The buffer will be backed by sparse memory binding (through queue commands) instead of
1061 /// The buffer can be used without being fully resident in memory at the time of use.
1071 /// The buffer's memory can alias with another buffer or a different part of the same buffer.
1081 /// The buffer is protected, and can only be used in combination with protected memory and other
1090 /// The buffer's device address can be saved and reused on a subsequent run.
1100 /// The buffer configuration to query in
1104 /// The external handle type that will be used with the buffer.
1107 /// The usage that the buffer will have.
1119 pub fn handle_type(handle_type: ExternalMemoryHandleType) -> Self { in handle_type()