mirror of
https://github.com/storytold/wgpu.git
synced 2026-11-22 07:21:04 +01:00
Duplicate BufferSlice methods onto Buffer and vice versa. (#7123)
This allows users to skip creation of `BufferSlice` if they have no use for it, and brings `wgpu` closer to the WebGPU API without removing any Rust convenience. New functions: * `BufferSlice::slice()` * `Buffer::map_async()` * `Buffer::get_mapped_range()` * `Buffer::get_mapped_range_mut()` * `Buffer::get_mapped_range()`
This commit is contained in:
1 parent
f0bf789f58
commit
c4b25b8794
6 files changed
+170
-29
No files matched your search
@@ -50,6 +50,8 @@ Bottom level categories:
|
||||
|
||||
By @kpreid in [#7063](https://github.com/gfx-rs/wgpu/pull/7063).
|
||||
|
||||
- Added `Buffer` methods corresponding to `BufferSlice` methods, so you can skip creating a `BufferSlice` when it offers no benefit, and `BufferSlice::slice()` for sub-slicing a slice. By @kpreid in [#7123](https://github.com/gfx-rs/wgpu/pull/7123).
|
||||
|
||||
#### Naga
|
||||
|
||||
- Support @must_use attribute on function declarations. By @turbocrime in [#6801](https://github.com/gfx-rs/wgpu/pull/6801).
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
//! Tests of [`wgpu::Buffer`] and related.
|
||||
|
||||
mod buffer_slice {
|
||||
#[test]
|
||||
fn reslice_success() {
|
||||
let (device, _queue) = crate::request_noop_device();
|
||||
|
||||
let buffer = device.create_buffer(&wgpu::BufferDescriptor {
|
||||
label: None,
|
||||
size: 100,
|
||||
usage: wgpu::BufferUsages::VERTEX,
|
||||
mapped_at_creation: false,
|
||||
});
|
||||
|
||||
assert_eq!(buffer.slice(10..90).slice(10..70), buffer.slice(20..80));
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic = "slice offset 10 size 80 is out of range for buffer of size 80"]
|
||||
fn reslice_out_of_bounds() {
|
||||
let (device, _queue) = crate::request_noop_device();
|
||||
|
||||
let buffer = device.create_buffer(&wgpu::BufferDescriptor {
|
||||
label: None,
|
||||
size: 100,
|
||||
usage: wgpu::BufferUsages::VERTEX,
|
||||
mapped_at_creation: false,
|
||||
});
|
||||
|
||||
buffer.slice(10..90).slice(10..90);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
mod buffer;
|
||||
@@ -19,22 +19,7 @@ fn device_is_not_available_by_default() {
|
||||
|
||||
#[test]
|
||||
fn device_and_buffers() {
|
||||
let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
|
||||
backends: wgpu::Backends::NOOP,
|
||||
backend_options: wgpu::BackendOptions {
|
||||
noop: wgpu::NoopBackendOptions { enable: true },
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
});
|
||||
let adapter =
|
||||
pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
|
||||
.expect("adapter");
|
||||
let (device, queue) =
|
||||
pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor::default(), None))
|
||||
.expect("device");
|
||||
|
||||
assert_eq!(adapter.get_info().backend, wgpu::Backend::Noop);
|
||||
let (device, queue) = crate::request_noop_device();
|
||||
|
||||
// Demonstrate that creating and *writing* to a buffer succeeds.
|
||||
// This also involves creation of a staging buffer.
|
||||
|
||||
@@ -1,3 +1,25 @@
|
||||
//! Tests of the [`wgpu`] library API that are not run against a particular GPU.
|
||||
|
||||
mod api;
|
||||
mod noop;
|
||||
|
||||
/// Obtain a device using [`wgpu::Backend::Noop`].
|
||||
/// This should never fail.
|
||||
fn request_noop_device() -> (wgpu::Device, wgpu::Queue) {
|
||||
let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
|
||||
backends: wgpu::Backends::NOOP,
|
||||
backend_options: wgpu::BackendOptions {
|
||||
noop: wgpu::NoopBackendOptions { enable: true },
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
});
|
||||
|
||||
let adapter =
|
||||
pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
|
||||
.expect("adapter");
|
||||
assert_eq!(adapter.get_info().backend, wgpu::Backend::Noop);
|
||||
|
||||
pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor::default(), None))
|
||||
.expect("device")
|
||||
}
|
||||
+112
-13
@@ -218,8 +218,6 @@ impl Buffer {
|
||||
}
|
||||
}
|
||||
|
||||
/// Return a slice of a [`Buffer`]'s bytes.
|
||||
///
|
||||
/// Return a [`BufferSlice`] referring to the portion of `self`'s contents
|
||||
/// indicated by `bounds`. Regardless of what sort of data `self` stores,
|
||||
/// `bounds` start and end are given in bytes.
|
||||
@@ -266,6 +264,81 @@ impl Buffer {
|
||||
pub fn usage(&self) -> BufferUsages {
|
||||
self.usage
|
||||
}
|
||||
|
||||
/// Map the buffer. Buffer is ready to map once the callback is called.
|
||||
///
|
||||
/// For the callback to complete, either `queue.submit(..)`, `instance.poll_all(..)`, or `device.poll(..)`
|
||||
/// must be called elsewhere in the runtime, possibly integrated into an event loop or run on a separate thread.
|
||||
///
|
||||
/// The callback will be called on the thread that first calls the above functions after the gpu work
|
||||
/// has completed. There are no restrictions on the code you can run in the callback, however on native the
|
||||
/// call to the function will not complete until the callback returns, so prefer keeping callbacks short
|
||||
/// and used to set flags, send messages, etc.
|
||||
///
|
||||
/// This can also be performed using [`BufferSlice::map_async()`].
|
||||
pub fn map_async<S: RangeBounds<BufferAddress>>(
|
||||
&self,
|
||||
mode: MapMode,
|
||||
bounds: S,
|
||||
callback: impl FnOnce(Result<(), BufferAsyncError>) + WasmNotSend + 'static,
|
||||
) {
|
||||
self.slice(bounds).map_async(mode, callback)
|
||||
}
|
||||
|
||||
/// Gain read-only access to the bytes of a [mapped] [`Buffer`].
|
||||
///
|
||||
/// Return a [`BufferView`] referring to the buffer range represented by
|
||||
/// `self`. See the documentation for [`BufferView`] for details.
|
||||
///
|
||||
/// This can also be performed using [`BufferSlice::get_mapped_range()`].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - If the buffer to which `self` refers is not currently [mapped].
|
||||
/// - If you try to create overlapping views of a buffer, mutable or otherwise.
|
||||
///
|
||||
/// [mapped]: Buffer#mapping-buffers
|
||||
pub fn get_mapped_range<S: RangeBounds<BufferAddress>>(&self, bounds: S) -> BufferView<'_> {
|
||||
self.slice(bounds).get_mapped_range()
|
||||
}
|
||||
|
||||
/// Synchronously and immediately map a buffer for reading. If the buffer is not immediately mappable
|
||||
/// through [`BufferDescriptor::mapped_at_creation`] or [`BufferSlice::map_async`], will fail.
|
||||
///
|
||||
/// This is useful when targeting WebGPU and you want to pass mapped data directly to js.
|
||||
/// Unlike `get_mapped_range` which unconditionally copies mapped data into the wasm heap,
|
||||
/// this function directly hands you the ArrayBuffer that we mapped the data into in js.
|
||||
///
|
||||
/// This is only available on WebGPU, on any other backends this will return `None`.
|
||||
///
|
||||
/// This can also be performed using [`BufferSlice::get_mapped_range_as_array_buffer()`].
|
||||
#[cfg(webgpu)]
|
||||
pub fn get_mapped_range_as_array_buffer<S: RangeBounds<BufferAddress>>(
|
||||
&self,
|
||||
bounds: S,
|
||||
) -> Option<js_sys::ArrayBuffer> {
|
||||
self.slice(bounds).get_mapped_range_as_array_buffer()
|
||||
}
|
||||
|
||||
/// Gain write access to the bytes of a [mapped] [`Buffer`].
|
||||
///
|
||||
/// Return a [`BufferViewMut`] referring to the buffer range represented by
|
||||
/// `self`. See the documentation for [`BufferViewMut`] for more details.
|
||||
///
|
||||
/// This can also be performed using [`BufferSlice::get_mapped_range_mut()`].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - If the buffer to which `self` refers is not currently [mapped].
|
||||
/// - If you try to create overlapping views of a buffer, mutable or otherwise.
|
||||
///
|
||||
/// [mapped]: Buffer#mapping-buffers
|
||||
pub fn get_mapped_range_mut<S: RangeBounds<BufferAddress>>(
|
||||
&self,
|
||||
bounds: S,
|
||||
) -> BufferViewMut<'_> {
|
||||
self.slice(bounds).get_mapped_range_mut()
|
||||
}
|
||||
}
|
||||
|
||||
/// A slice of a [`Buffer`], to be mapped, used for vertex or index data, or the like.
|
||||
@@ -307,7 +380,7 @@ impl Buffer {
|
||||
/// working with the [`Buffer`], instead.
|
||||
///
|
||||
/// [map]: Buffer#mapping-buffers
|
||||
#[derive(Copy, Clone, Debug)]
|
||||
#[derive(Copy, Clone, Debug, PartialEq)]
|
||||
pub struct BufferSlice<'a> {
|
||||
pub(crate) buffer: &'a Buffer,
|
||||
pub(crate) offset: BufferAddress,
|
||||
@@ -317,6 +390,30 @@ pub struct BufferSlice<'a> {
|
||||
static_assertions::assert_impl_all!(BufferSlice<'_>: Send, Sync);
|
||||
|
||||
impl<'a> BufferSlice<'a> {
|
||||
/// Return another [`BufferSlice`] referring to the portion of `self`'s contents
|
||||
/// indicated by `bounds`.
|
||||
///
|
||||
/// The `range` argument can be half or fully unbounded: for example,
|
||||
/// `buffer.slice(..)` refers to the entire buffer, and `buffer.slice(n..)`
|
||||
/// refers to the portion starting at the `n`th byte and extending to the
|
||||
/// end of the buffer.
|
||||
pub fn slice<S: RangeBounds<BufferAddress>>(&self, bounds: S) -> BufferSlice<'a> {
|
||||
let (offset, size) = range_to_offset_size(bounds);
|
||||
check_buffer_bounds(
|
||||
match self.size {
|
||||
Some(size) => size.get(),
|
||||
None => self.buffer.size(),
|
||||
},
|
||||
offset,
|
||||
size,
|
||||
);
|
||||
BufferSlice {
|
||||
buffer: self.buffer,
|
||||
offset: self.offset + offset, // check_buffer_bounds ensures this does not overflow
|
||||
size: size.or(self.size), // check_buffer_bounds ensures this is essentially min()
|
||||
}
|
||||
}
|
||||
|
||||
/// Map the buffer. Buffer is ready to map once the callback is called.
|
||||
///
|
||||
/// For the callback to complete, either `queue.submit(..)`, `instance.poll_all(..)`, or `device.poll(..)`
|
||||
@@ -326,6 +423,8 @@ impl<'a> BufferSlice<'a> {
|
||||
/// has completed. There are no restrictions on the code you can run in the callback, however on native the
|
||||
/// call to the function will not complete until the callback returns, so prefer keeping callbacks short
|
||||
/// and used to set flags, send messages, etc.
|
||||
///
|
||||
/// This can also be performed using [`Buffer::map_async()`].
|
||||
pub fn map_async(
|
||||
&self,
|
||||
mode: MapMode,
|
||||
@@ -349,13 +448,12 @@ impl<'a> BufferSlice<'a> {
|
||||
/// Return a [`BufferView`] referring to the buffer range represented by
|
||||
/// `self`. See the documentation for [`BufferView`] for details.
|
||||
///
|
||||
/// This can also be performed using [`Buffer::get_mapped_range()`].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - This panics if the buffer to which `self` refers is not currently
|
||||
/// [mapped].
|
||||
///
|
||||
/// - If you try to create overlapping views of a buffer, mutable or
|
||||
/// otherwise, `get_mapped_range` will panic.
|
||||
/// - If the buffer to which `self` refers is not currently [mapped].
|
||||
/// - If you try to create overlapping views of a buffer, mutable or otherwise.
|
||||
///
|
||||
/// [mapped]: Buffer#mapping-buffers
|
||||
pub fn get_mapped_range(&self) -> BufferView<'a> {
|
||||
@@ -375,6 +473,8 @@ impl<'a> BufferSlice<'a> {
|
||||
/// this function directly hands you the ArrayBuffer that we mapped the data into in js.
|
||||
///
|
||||
/// This is only available on WebGPU, on any other backends this will return `None`.
|
||||
///
|
||||
/// This can also be performed using [`Buffer::get_mapped_range_as_array_buffer()`].
|
||||
#[cfg(webgpu)]
|
||||
pub fn get_mapped_range_as_array_buffer(&self) -> Option<js_sys::ArrayBuffer> {
|
||||
let end = self.buffer.map_context.lock().add(self.offset, self.size);
|
||||
@@ -389,13 +489,12 @@ impl<'a> BufferSlice<'a> {
|
||||
/// Return a [`BufferViewMut`] referring to the buffer range represented by
|
||||
/// `self`. See the documentation for [`BufferViewMut`] for more details.
|
||||
///
|
||||
/// This can also be performed using [`Buffer::get_mapped_range_mut()`].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - This panics if the buffer to which `self` refers is not currently
|
||||
/// [mapped].
|
||||
///
|
||||
/// - If you try to create overlapping views of a buffer, mutable or
|
||||
/// otherwise, `get_mapped_range_mut` will panic.
|
||||
/// - If the buffer to which `self` refers is not currently [mapped].
|
||||
/// - If you try to create overlapping views of a buffer, mutable or otherwise.
|
||||
///
|
||||
/// [mapped]: Buffer#mapping-buffers
|
||||
pub fn get_mapped_range_mut(&self) -> BufferViewMut<'a> {
|
||||
|
||||
Reference in new issue
Block a user