Struct tetra::graphics::mesh::Mesh

pub struct Mesh { /* fields omitted */ }

A 2D mesh that can be drawn to the screen.

A Mesh is a wrapper for a VertexBuffer, which allows it to be drawn in combination with several optional modifiers:

• A Texture that individual vertices can sample from.
• An IndexBuffer that can be used to modify the order/subset of vertices that are drawn.
• A winding order, which determines which side of the geometry is front-facing.
• A backface culling flag, which determines whether back-facing geometry should be drawn.
• A draw range, which can be used to draw subsections of the mesh.

Without a texture set, the mesh will be drawn in white - the color attribute on the vertex data or DrawParams can be used to change this.

Note that, unlike quad rendering via Texture, mesh rendering is not batched by default - each time you draw the mesh will result in a seperate draw call.

Performance

Creating or cloning a Mesh is a very cheap operation, as meshes are effectively just collections of resources that live on the GPU. The only expensive part is the creation of the buffers/textures, which can be done ahead of time.

Note that cloned meshes do not share data, so updating one instance of a mesh will not affect other instances.

Examples

The mesh example demonstrates how to build and draw a simple mesh.

The shapes example demonstrates how to draw primitive shapes, both through the simplified API on Mesh, and the more powerful GeometryBuilder API.

Implementations

impl Mesh

pub fn new(vertex_buffer: VertexBuffer) -> Mesh

Creates a new mesh, using the provided vertex buffer.

pub fn indexed(vertex_buffer: VertexBuffer, index_buffer: IndexBuffer) -> Mesh

Creates a new mesh, using the provided vertex and index buffers.

pub fn rectangle(
    ctx: &mut Context,
    style: ShapeStyle,
    rectangle: Rectangle
) -> Result<Mesh>

Creates a new rectangle mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn rounded_rectangle(
    ctx: &mut Context,
    style: ShapeStyle,
    rectangle: Rectangle,
    radii: BorderRadii
) -> Result<Mesh>

Creates a new rounded rectangle mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn circle(
    ctx: &mut Context,
    style: ShapeStyle,
    center: Vec2<f32>,
    radius: f32
) -> Result<Mesh>

Creates a new circle mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn ellipse(
    ctx: &mut Context,
    style: ShapeStyle,
    center: Vec2<f32>,
    radii: Vec2<f32>
) -> Result<Mesh>

Creates a new ellipse mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn polygon(
    ctx: &mut Context,
    style: ShapeStyle,
    points: &[Vec2<f32>]
) -> Result<Mesh>

Creates a new polygon mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn polyline(
    ctx: &mut Context,
    stroke_width: f32,
    points: &[Vec2<f32>]
) -> Result<Mesh>

Creates a new polyline mesh.

If you need to draw multiple shapes, consider using GeometryBuilder to generate a combined mesh instead.

Errors

• TetraError::TessellationError will be returned if the shape could not be turned into vertex data.
• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn draw<P>(&self, ctx: &mut Context, params: P) where
    P: Into<DrawParams>, 

Draws the mesh to the screen (or to a canvas, if one is enabled).

pub fn vertex_buffer(&self) -> &VertexBuffer

Gets a reference to the vertex buffer contained within this mesh.

pub fn set_vertex_buffer(&mut self, vertex_buffer: VertexBuffer)

Sets the vertex buffer that will be used when drawing the mesh.

pub fn index_buffer(&self) -> Option<&IndexBuffer>

Gets a reference to the index buffer contained within this mesh.

Returns None if this mesh does not currently have an index buffer attatched.

pub fn set_index_buffer(&mut self, index_buffer: IndexBuffer)

Sets the index buffer that will be used when drawing the mesh.

pub fn reset_index_buffer(&mut self)

Resets the mesh to no longer use indexed drawing.

pub fn texture(&self) -> Option<&Texture>

Gets a reference to the texture contained within this mesh.

Returns None if this mesh does not currently have an texture attatched.

pub fn set_texture(&mut self, texture: Texture)

Sets the texture that will be used when drawing the mesh.

pub fn reset_texture(&mut self)

Resets the mesh to be untextured.

pub fn front_face_winding(&self) -> VertexWinding

Returns which winding order represents front-facing geometry in this mesh.

Back-facing geometry will be culled (not rendered) by default, but this can be changed via set_backface_culling.

The default winding order is counter-clockwise.

pub fn set_front_face_winding(&mut self, winding: VertexWinding)

Sets which winding order represents front-facing geometry in this mesh.

Back-facing geometry will be culled (not rendered) by default, but this can be changed via set_backface_culling.

The default winding order is counter-clockwise.

pub fn backface_culling(&self) -> bool

Returns whether or not this mesh will cull (not render) back-facing geometry.

By default, backface culling is enabled, counter-clockwise vertices are considered front-facing, and clockwise vertices are considered back-facing. This can be modified via set_backface_culling and set_front_face_winding.

pub fn set_backface_culling(&mut self, enabled: bool)

Sets whether or not this mesh will cull (not render) back-facing geometry.

By default, backface culling is enabled, counter-clockwise vertices are considered front-facing, and clockwise vertices are considered back-facing. This can be modified via this function and set_front_face_winding.

pub fn set_draw_range(&mut self, start: usize, count: usize)

Sets the range of vertices (or indices, if the mesh is indexed) that should be included when drawing this mesh.

This can be useful if you have a large mesh but you only want to want to draw a subsection of it, or if you want to draw a mesh in multiple stages.

pub fn reset_draw_range(&mut self)

Sets the mesh to include all of its data when drawing.

Trait Implementations

impl Clone for Mesh

fn clone(&self) -> Mesh

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Mesh

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

Formats the value using the given formatter.

impl From<VertexBuffer> for Mesh

fn from(buffer: VertexBuffer) -> Self

Performs the conversion.