Struct fyrox::scene::mesh::buffer::VertexBuffer

pub struct VertexBuffer { /* private fields */ }

Vertex buffer with dynamic layout. It is used to store multiple vertices of a single type, that implements VertexTrait. Different vertex types used to for efficient memory usage. For example, you could have a simple vertex with only position expressed as Vector3 and it will be enough for simple cases, when only position is required. However, if you want to draw a mesh with skeletal animation, that also supports texturing, lighting, you need to provide a lot more data (bone indices, bone weights, normals, tangents, texture coordinates).

Examples

#[derive(Copy, Clone)]
#[repr(C)]
struct MyVertex {
    position: Vector3<f32>,
}

impl VertexTrait for MyVertex {
    fn layout() -> &'static [VertexAttributeDescriptor] {
        &[VertexAttributeDescriptor {
            usage: VertexAttributeUsage::Position,
            data_type: VertexAttributeDataType::F32,
            size: 3,
            divisor: 0,
            shader_location: 0,
        }]
    }
}

fn create_triangle_vertex_buffer() -> VertexBuffer {
    VertexBuffer::new(
        3,
        vec![
            MyVertex {
                position: Vector3::new(0.0, 0.0, 0.0),
            },
            MyVertex {
                position: Vector3::new(0.0, 1.0, 0.0),
            },
            MyVertex {
                position: Vector3::new(1.0, 1.0, 0.0),
            },
        ],
    )
    .unwrap()
}  

This example creates a simple vertex buffer that contains a single triangle with custom vertex format. The most important part here is VertexTrait::layout implementation - it describes each “attribute” of your vertex, if your layout does not match the actual content of the vertex (in terms of size in bytes), then vertex buffer cannot be created and VertexBuffer::new will return None.

The second, but not least important is #[repr(C)] attribute - it is mandatory for every vertex type, it forbids fields reordering of you vertex structure and guarantees that they will have the same layout in memory as their declaration order.

Limitations

Vertex size cannot be more than 256 bytes, this limitation shouldn’t be a problem because almost every GPU supports up to 16 vertex attributes with 16 bytes of size each, which gives exactly 256 bytes.

Implementations

impl VertexBuffer

pub fn new<T>( vertex_count: usize, data: Vec<T> ) -> Result<Self, ValidationError>where T: VertexTrait,

Creates new vertex buffer from provided data and with the given layout of the vertex type T.

pub fn raw_data(&self) -> &[u8]

Returns a reference to underlying data buffer slice.

pub fn is_empty(&self) -> bool

Returns true if buffer does not contain any vertex, false - otherwise.

pub fn data_hash(&self) -> u64

Returns cached data hash. Cached value is guaranteed to be in actual state.

pub fn layout_hash(&self) -> u64

Returns hash of vertex buffer layout. Cached value is guaranteed to be in actual state. The hash could be used to check if the layout has changed.

pub fn modify(&mut self) -> VertexBufferRefMut<'_>

Provides mutable access to content of the buffer.

Performance

This method returns special structure which has custom destructor that calculates hash of the data once modification is over. You must hold this structure as long as possible while modifying contents of the buffer. Do not even try to do this:

use fyrox::{
    scene::mesh::buffer::{VertexBuffer, VertexWriteTrait, VertexAttributeUsage},
    core::algebra::Vector3
};
fn do_something(buffer: &mut VertexBuffer) {
    for i in 0..buffer.vertex_count() {
        buffer
            .modify() // Doing this in a loop will cause HUGE performance issues!
            .get_mut(i as usize)
            .unwrap()
            .write_3_f32(VertexAttributeUsage::Position, Vector3::<f32>::default())
            .unwrap();
    }
}

Instead do this:

use fyrox::{
    scene::mesh::buffer::{VertexBuffer, VertexWriteTrait, VertexAttributeUsage},
    core::algebra::Vector3
};
fn do_something(buffer: &mut VertexBuffer) {
    let mut buffer_modifier = buffer.modify();
    for mut vertex in buffer_modifier.iter_mut() {
        vertex
            .write_3_f32(VertexAttributeUsage::Position, Vector3::<f32>::default())
            .unwrap();
    }
}

Why do we even need such complications? It is used for lazy hash calculation which is used for automatic upload of contents to GPU in case if content has changed.

pub fn has_attribute(&self, usage: VertexAttributeUsage) -> bool

Checks if an attribute of usage exists.

pub fn layout(&self) -> &[VertexAttribute]

Returns vertex buffer layout.

pub fn cast_data_ref<T>(&self) -> Result<&[T], ValidationError>where T: VertexTrait,

Tries to cast internal data buffer to a slice of given type. It may fail if size of type is not equal with claimed size (which is set by the layout).

pub fn iter(&self) -> impl Iterator<Item = VertexViewRef<'_>> + '_

Creates iterator that emits read accessors for vertices.

pub fn get(&self, n: usize) -> Option<VertexViewRef<'_>>

Returns a read accessor of n-th vertex.

pub fn vertex_count(&self) -> u32

Returns exact amount of vertices in the buffer.

pub fn vertex_size(&self) -> u8

Return vertex size of the buffer.

pub fn find_free_shader_location(&self) -> u8

Finds free location for an attribute in the layout.

Trait Implementations

impl Clone for VertexBuffer

fn clone(&self) -> VertexBuffer

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VertexBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for VertexBuffer

fn default() -> VertexBuffer

Returns the “default value” for a type.

impl Visit for VertexBufferwhere Vec<VertexAttribute>: Visit, [Option<VertexAttribute>; 13]: Visit, u8: Visit, u32: Visit, BytesStorage: Visit, u64: Visit,

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult