Struct DataTextureSource 

pub struct DataTextureSource<'a, T: Pod + Send + Sync> { /* private fields */ }

Utility for writing data to a dynamically sized “data textures”.

For WebGL compatibility we sometimes have to use textures instead of buffers. We call these textures “data textures”. This construct allows to write data directly to gpu readable memory which then upon finishing is automatically copied into an appropriately sized texture which receives all data written to DataTextureSource. Each texel in the data texture represents a single element of the type T.

This is implemented by dynamically allocating cpu-write-gpu-read buffers from the central crate::CpuWriteGpuReadBelt and copying all of them to the texture in the end.

Implementations

impl<'a, T: Pod + Send + Sync> DataTextureSource<'a, T>

pub fn new(ctx: &'a RenderContext) -> Self

Creates a new DataTextureSource with the given RenderContext.

This operation itself will not allocate any memory, empty DataTextureSource are not a concern.

pub fn is_empty(&self) -> bool

Whether no elements have been written at all.

pub fn len(&self) -> usize

The number of elements written so far.

pub fn capacity(&self) -> usize

The number of elements that can be written without allocating more memory.

pub fn remaining_capacity(&self) -> usize

The number of elements that can be written without allocating more memory.

pub fn reserve( &mut self, num_elements: usize, ) -> Result<usize, CpuWriteGpuReadError>

Ensures that there’s space internally for at least num_elements more elements.

Returns the number of elements that are currently reserved. This value is smaller than the requested number of elements if the maximum number of elements that can be stored is reached.

Creating new buffers is a relatively expensive operation, so it’s best to reserve gratuitously and often. Ideally, you know exactly how many elements you’re going to write and reserve accordingly at the start.

If there’s no more space, a new buffer is allocated such that:

• have a total capacity for at least as many elements as requested, clamping total size to the maximum.
• be at least double the size of the last buffer
• keep it easy to copy to textures by always being a multiple of the maximum row size we use for data textures
  • this massively simplifies the buffer->texture copy logic!

pub fn extend_from_slice( &mut self, elements: &[T], ) -> Result<(), DataTextureSourceWriteError>

Pushes a slice of elements into the data texture.

pub fn extend_from_slice_clamped( &mut self, slice: &[T], default: T, len: usize, ) -> Result<(), DataTextureSourceWriteError>

Append len elements, using slice as source, clamping to the last value (or default) if slice is too short.

pub fn add_n( &mut self, element: T, num_elements: usize, ) -> Result<(), DataTextureSourceWriteError>

Fills the data texture with n instances of an element.

pub fn push(&mut self, element: T) -> Result<(), DataTextureSourceWriteError>

pub fn finish( self, texture_format: TextureFormat, texture_label: impl Into<Label>, ) -> Result<GpuTexture, CpuWriteGpuReadError>

Schedules copies of all previous writes to this DataTextureSource to a GpuTexture.

The format has to be uncompressed, not a depth/stencil format and have the exact same block size of the size of type T. The resulting GpuTexture is ready to be bound as a data texture in a shader.