[][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.

This example is not tested
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:

This example is not tested
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.

This example is not tested
let buffer = Buffer::repeat(&mut ctx, 3, 0); // same as Buffer::from_slice(&mut ctx, [0, 0, 0])

Writing to a buffer

Buffers 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.

This example is not tested
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:

This example is not tested
buffer.fill([1, 2, 3]);

You want to change a value at a given index? Easy, you can use the Buffer::set function:

This example is not tested
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.

This example is not tested
// 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 Buffer is a GPU region you can picture as an array.

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.