From 957f00c4134a72869a61cc6a14d8eb637e2be65a Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Thu, 28 Apr 2016 11:28:25 +0200 Subject: [PATCH] Better documentation for unsafe buffers --- vulkano/src/buffer/sys.rs | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/vulkano/src/buffer/sys.rs b/vulkano/src/buffer/sys.rs index a9beba94..39a55723 100644 --- a/vulkano/src/buffer/sys.rs +++ b/vulkano/src/buffer/sys.rs @@ -7,6 +7,23 @@ // notice may not be copied, modified, or distributed except // according to those terms. +//! Low level implementation of buffers. +//! +//! Wraps directly around Vulkan buffers, with the exceptions of a few safety checks. +//! +//! The `UnsafeBuffer` type is the lowest-level buffer object provided by this library. It is used +//! internally by the higher-level buffer types. You are strongly encouraged to have excellent +//! knowledge of the Vulkan specs if you want to use an `UnsafeBuffer`. +//! +//! Here is what you must take care of when you use an `UnsafeBuffer`: +//! +//! - Synchronization, ie. avoid reading and writing simultaneously to the same buffer. +//! - Memory aliasing considerations. If you use the same memory to back multiple resources, you +//! must ensure that they are not used together and must enable some additional flags. +//! - Binding memory correctly and only once. If you use sparse binding, respect the rules of +//! sparse binding. +//! - Type safety. + use std::error; use std::fmt; use std::mem; @@ -27,14 +44,6 @@ use VulkanPointers; use vk; /// Data storage in a GPU-accessible location. -/// -/// # Safety -/// -/// - Doesn't handle synchronization. -/// - Doesn't handle memory aliasing problems. -/// - Doesn't check that memory was correctly bound and only once. -/// - Doesn't enforce type safety. -/// #[derive(Debug)] pub struct UnsafeBuffer { buffer: vk::Buffer,