[−][src]Module luminance::buffer
Static GPU typed arrays.
A GPU buffer is a typed continuous region of data. It has a size and can hold several elements.
Once the buffer is created, you can perform several operations on it:
- Writing to it.
- Reading from it.
- Passing it around as uniforms.
- Etc.
Buffers are created with the Buffer::new
associated function, which is unsafe
. You pass in
the number of elements you want in the buffer along with the GraphicsContext
to create the
buffer in.
let buffer: Buffer<f32> = Buffer::new(&mut ctx, 5);
Another important point is the fact that creating a buffer with Buffer::new
allocates the
array on the GPU but leaves it uninitialized. You will have to fill its memory by hand. Or
you can use the Buffer::from_slice
method, which both allocates and initializes:
let buffer = Buffer::from_slice(&mut ctx, [1, 2, 3]);
If you would like to allocate a buffer and initialize it with the same value everywhere, you
can use Buffer::repeat
.
let buffer = Buffer::repeat(&mut ctx, 3, 0); // same as Buffer::from_slice(&mut ctx, [0, 0, 0])
Writing to a buffer
Buffer
s support several write methods. The simple one is clearing. That is, replacing the
whole content of the buffer with a single value. Use the Buffer::clear
function to do so.
buffer.clear(0.);
If you want to clear the buffer by providing a value for each elements, you want filling
instead. Use the Buffer::fill
function:
buffer.fill([1, 2, 3]);
You want to change a value at a given index? Easy, you can use the Buffer::set
function:
buffer.set(2, 42);
Reading from the buffer
You can either retrieve the whole content of the Buffer
or get a value with an index.
// get the whole content let all_elems = buffer.whole(); assert_eq!(all_elems, vec![1, 2, 42]); // get the element at index 2 assert_eq!(buffer.at(2), Some(42));
Uniform buffer
It’s possible to use buffers as uniform buffers. That is, buffers that will be in bound at rendering time and which content will be available for a shader to read (no write).
In order to use your buffers in a uniform context, the inner type has to implement
UniformBlock
. Keep in mind alignment must be respected and is a bit peculiar. TODO: explain
std140 here.
Structs
Buffer | A |
BufferSlice | A buffer slice mapped into GPU memory. |
BufferSliceMut | A mutable buffer slice mapped into GPU memory. |
RawBuffer | Raw buffer. Any buffer can be converted to that type. However, keep in mind that even though type erasure is safe, creating a buffer from a raw buffer is not. |
Enums
BufferError | Buffer errors. |
Traits
UniformBlock | Typeclass of types that can be used inside a uniform block. You have to be extra careful when using uniform blocks and ensure you respect the OpenGL std140 alignment / size rules. This will be fixed in a future release. |