Struct 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,
            normalized: false
        }]
    }
}

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 const DENSE_LAYOUT: &'static str = "dense_layout"

pub const SPARSE_LAYOUT: &'static str = "sparse_layout"

pub const VERTEX_SIZE: &'static str = "vertex_size"

pub const VERTEX_COUNT: &'static str = "vertex_count"

pub const DATA: &'static str = "data"

pub const LAYOUT_HASH: &'static str = "layout_hash"

pub const MODIFICATIONS_COUNTER: &'static str = "modifications_counter"

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 new_with_layout( layout: &[VertexAttributeDescriptor], vertex_count: usize, bytes: BytesStorage, ) -> Result<Self, ValidationError>

Creates new vertex buffer from the given layout, vertex count and bytes storage.

pub fn clone_empty(&self, capacity: usize) -> Self

Creates a new empty vertex buffer with the same layout and vertex size, but with an empty inner buffer of the specified capacity.

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 modifications_count(&self) -> u64

Returns the total amount of times the buffer was modified.

pub fn content_hash(&self) -> u64

Calculates inner data hash.

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_impl::{
    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_impl::{
    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 layout_descriptor( &self, ) -> impl Iterator<Item = VertexAttributeDescriptor> + '_

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.

pub fn attribute_view<T>( &self, usage: VertexAttributeUsage, ) -> Option<AttributeViewRef<'_, T>>

where T: Copy,

Tries to find an attribute with the given usage and if it exists, returns its “view”, that allows you to fetch data like in ordinary array.

pub fn attribute_view_mut<T: Copy>( &mut self, usage: VertexAttributeUsage, ) -> Option<AttributeViewRefMut<'_, T>>

Tries to find an attribute with the given usage and if it exists, returns its “view”, that allows you to fetch data like in ordinary array.

Trait Implementations

impl Clone for VertexBuffer

fn clone(&self) -> VertexBuffer

Returns a duplicate 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 Reflect for VertexBuffer

where Self: 'static, Vec<VertexAttribute>: Reflect, [Option<VertexAttribute>; 22]: Reflect, u8: Reflect, u32: Reflect, BytesStorage: Reflect, u64: Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<Self>) -> Box<dyn Any>

fn set( &mut self, value: Box<dyn Reflect>, ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn as_any(&self, func: &mut dyn FnMut(&dyn Any))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut dyn Any))

fn as_reflect(&self, func: &mut dyn FnMut(&dyn Reflect))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut dyn Reflect))

fn fields(&self, func: &mut dyn FnMut(&[&dyn Reflect]))

fn fields_mut(&mut self, func: &mut dyn FnMut(&mut [&mut dyn Reflect]))

fn field(&self, name: &str, func: &mut dyn FnMut(Option<&dyn Reflect>))

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut dyn Reflect>), )

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>), )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>), )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>), )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>), )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>), )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>), )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>), )

impl Visit for VertexBuffer

where Vec<VertexAttribute>: Visit, [Option<VertexAttribute>; 22]: Visit, u8: Visit, u32: Visit, BytesStorage: Visit, u64: Visit,

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

Read or write this value, depending on whether Visitor::is_reading() is true or false.