1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
// Copyright (c) 2016 The vulkano developers
// Licensed under the Apache License, Version 2.0
// <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT
// license <LICENSE-MIT or https://opensource.org/licenses/MIT>,
// at your option. All files in the project carrying such
// notice may not be copied, modified, or distributed except
// according to those terms.
//! Location in memory that contains data.
//!
//! A Vulkan buffer is very similar to a buffer that you would use in programming languages in
//! general, in the sense that it is a location in memory that contains data. The difference
//! between a Vulkan buffer and a regular buffer is that the content of a Vulkan buffer is
//! accessible from the GPU.
//!
//! Vulkano does not perform any specific marshalling of buffer data. The representation of the buffer in
//! memory is identical between the CPU and GPU. Because the Rust compiler is allowed to reorder struct
//! fields at will by default when using `#[repr(Rust)]`, it is advised to mark each struct requiring
//! imput assembly as `#[repr(C)]`. This forces Rust to follow the standard C procedure. Each element is
//! laid out in memory in the order of declaration and aligned to a multiple of their alignment.
//!
//! # Various kinds of buffers
//!
//! The low level implementation of a buffer is [`RawBuffer`](crate::buffer::sys::RawBuffer).
//! This type makes it possible to use all the features that Vulkan is capable of.
//!
//! Instead you are encouraged to use one of the high-level wrappers that vulkano provides. Which
//! wrapper to use depends on the way you are going to use the buffer:
//!
//! - A [`DeviceLocalBuffer`](crate::buffer::device_local::DeviceLocalBuffer) designates a buffer
//! usually located in video memory and whose content can't be directly accessed by your
//! application. Accessing this buffer from the GPU is generally faster compared to accessing a
//! CPU-accessible buffer.
//! - A [`CpuBufferPool`](crate::buffer::cpu_pool::CpuBufferPool) is a ring buffer that can be used to
//! transfer data between the CPU and the GPU at a high rate.
//! - A [`CpuAccessibleBuffer`](crate::buffer::cpu_access::CpuAccessibleBuffer) is a simple buffer that
//! can be used to prototype.
//!
//! Here is a quick way to choose which buffer to use. Do you often need to read or write
//! the content of the buffer? If so, use a `CpuBufferPool`. Otherwise, do you need to have access
//! to the buffer on the CPU? Then use `CpuAccessibleBuffer`. Otherwise, use a `DeviceLocalBuffer`.
//!
//! Another example: if a buffer is under constant access by the GPU but you need to
//! read its content on the CPU from time to time, it may be a good idea to use a
//! `DeviceLocalBuffer` as the main buffer and a `CpuBufferPool` for when you need to read it.
//! Then whenever you need to read the main buffer, ask the GPU to copy from the device-local
//! buffer to the CPU buffer pool, and read the CPU buffer pool instead.
//!
//! # Buffers usage
//!
//! When you create a buffer object, you have to specify its *usage*. In other words, you have to
//! specify the way it is going to be used. Trying to use a buffer in a way that wasn't specified
//! when you created it will result in a runtime error.
//!
//! You can use buffers for the following purposes:
//!
//! - Can contain arbitrary data that can be transferred from/to other buffers and images.
//! - Can be read and modified from a shader.
//! - Can be used as a source of vertices and indices.
//! - Can be used as a source of list of models for draw indirect commands.
//!
//! Accessing a buffer from a shader can be done in the following ways:
//!
//! - As a uniform buffer. Uniform buffers are read-only.
//! - As a storage buffer. Storage buffers can be read and written.
//! - As a uniform texel buffer. Contrary to a uniform buffer, the data is interpreted by the
//! GPU and can be for example normalized.
//! - As a storage texel buffer. Additionally, some data formats can be modified with atomic
//! operations.
//!
//! Using uniform/storage texel buffers requires creating a *buffer view*. See the `view` module
//! for how to create a buffer view.
//!
pub use self::{
cpu_access::CpuAccessibleBuffer,
cpu_pool::CpuBufferPool,
device_local::DeviceLocalBuffer,
slice::BufferSlice,
sys::BufferError,
traits::{
BufferAccess, BufferAccessObject, BufferDeviceAddressError, BufferInner, TypedBufferAccess,
},
usage::BufferUsage,
};
use crate::{
macros::vulkan_bitflags,
memory::{ExternalMemoryHandleType, ExternalMemoryProperties},
DeviceSize,
};
use bytemuck::{
bytes_of, bytes_of_mut, cast_slice, cast_slice_mut, try_cast_slice, try_cast_slice_mut,
try_from_bytes, try_from_bytes_mut, Pod, PodCastError,
};
use std::mem::size_of;
pub mod cpu_access;
pub mod cpu_pool;
pub mod device_local;
pub mod sys;
pub mod view;
mod slice;
mod traits;
mod usage;
vulkan_bitflags! {
/// Flags to be set when creating a buffer.
#[non_exhaustive]
BufferCreateFlags = BufferCreateFlags(u32);
/*
/// The buffer will be backed by sparse memory binding (through queue commands) instead of
/// regular binding (through [`bind_memory`]).
///
/// The [`sparse_binding`] feature must be enabled on the device.
///
/// [`bind_memory`]: sys::RawBuffer::bind_memory
/// [`sparse_binding`]: crate::device::Features::sparse_binding
sparse_binding = SPARSE_BINDING,
/// The buffer can be used without being fully resident in memory at the time of use.
///
/// This requires the `sparse_binding` flag as well.
///
/// The [`sparse_residency_buffer`] feature must be enabled on the device.
///
/// [`sparse_residency_buffer`]: crate::device::Features::sparse_residency_buffer
sparse_residency = SPARSE_RESIDENCY,
/// The buffer's memory can alias with another buffer or a different part of the same buffer.
///
/// This requires the `sparse_binding` flag as well.
///
/// The [`sparse_residency_aliased`] feature must be enabled on the device.
///
/// [`sparse_residency_aliased`]: crate::device::Features::sparse_residency_aliased
sparse_aliased = SPARSE_ALIASED,
/// The buffer is protected, and can only be used in combination with protected memory and other
/// protected objects.
///
/// The device API version must be at least 1.1.
protected = PROTECTED {
api_version: V1_1,
},
/// The buffer's device address can be saved and reused on a subsequent run.
///
/// The device API version must be at least 1.2, or either the [`khr_buffer_device_address`] or
/// [`ext_buffer_device_address`] extension must be enabled on the device.
device_address_capture_replay = DEVICE_ADDRESS_CAPTURE_REPLAY {
api_version: V1_2,
device_extensions: [khr_buffer_device_address, ext_buffer_device_address],
},
*/
}
/// Trait for types of data that can be put in a buffer. These can be safely transmuted to and from
/// a slice of bytes.
pub unsafe trait BufferContents: Send + Sync + 'static {
/// Converts an immutable reference to `Self` to an immutable byte slice.
fn as_bytes(&self) -> &[u8];
/// Converts a mutable reference to `Self` to an mutable byte slice.
fn as_bytes_mut(&mut self) -> &mut [u8];
/// Converts an immutable byte slice into an immutable reference to `Self`.
fn from_bytes(bytes: &[u8]) -> Result<&Self, PodCastError>;
/// Converts a mutable byte slice into a mutable reference to `Self`.
fn from_bytes_mut(bytes: &mut [u8]) -> Result<&mut Self, PodCastError>;
/// Returns the size of an element of the type.
fn size_of_element() -> DeviceSize;
}
unsafe impl<T> BufferContents for T
where
T: Pod + Send + Sync,
{
fn as_bytes(&self) -> &[u8] {
bytes_of(self)
}
fn as_bytes_mut(&mut self) -> &mut [u8] {
bytes_of_mut(self)
}
fn from_bytes(bytes: &[u8]) -> Result<&T, PodCastError> {
try_from_bytes(bytes)
}
fn from_bytes_mut(bytes: &mut [u8]) -> Result<&mut T, PodCastError> {
try_from_bytes_mut(bytes)
}
fn size_of_element() -> DeviceSize {
1
}
}
unsafe impl<T> BufferContents for [T]
where
T: Pod + Send + Sync,
{
fn as_bytes(&self) -> &[u8] {
cast_slice(self)
}
fn as_bytes_mut(&mut self) -> &mut [u8] {
cast_slice_mut(self)
}
fn from_bytes(bytes: &[u8]) -> Result<&[T], PodCastError> {
try_cast_slice(bytes)
}
fn from_bytes_mut(bytes: &mut [u8]) -> Result<&mut [T], PodCastError> {
try_cast_slice_mut(bytes)
}
fn size_of_element() -> DeviceSize {
size_of::<T>() as DeviceSize
}
}
/// The buffer configuration to query in
/// [`PhysicalDevice::external_buffer_properties`](crate::device::physical::PhysicalDevice::external_buffer_properties).
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ExternalBufferInfo {
/// The external handle type that will be used with the buffer.
pub handle_type: ExternalMemoryHandleType,
/// The usage that the buffer will have.
pub usage: BufferUsage,
/// The sparse binding parameters that will be used.
pub sparse: Option<BufferCreateFlags>,
pub _ne: crate::NonExhaustive,
}
impl ExternalBufferInfo {
/// Returns an `ExternalBufferInfo` with the specified `handle_type`.
#[inline]
pub fn handle_type(handle_type: ExternalMemoryHandleType) -> Self {
Self {
handle_type,
usage: BufferUsage::empty(),
sparse: None,
_ne: crate::NonExhaustive(()),
}
}
}
/// The external memory properties supported for buffers with a given configuration.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct ExternalBufferProperties {
/// The properties for external memory.
pub external_memory_properties: ExternalMemoryProperties,
}