Struct tetra::graphics::mesh::Mesh

pub struct Mesh { /* private fields */ }

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.

Performance

Creating or cloning a mesh is a very cheap operation, as they are effectively just bundles of resources that live on the GPU (such as buffers and textures). However, creating or modifying those underlying resources may be slow - make sure you read the docs for each type to understand their performance characteristics.

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

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 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 draw_instanced<P>(&self, ctx: &mut Context, instances: usize, params: P) where
    P: Into<DrawParams>, 

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

You will need to use a custom Shader in order to pass unique properties to each instance. Currently, the easiest way of doing this is via uniform arrays - however, there is a hardware-determined limit on how many uniform locations an individual shader can use, so this may not work if you’re rendering a large number of objects.

This should usually only be used for complex meshes - instancing can be inefficient for simple geometry (e.g. quads). That said, as with all things performance-related, benchmark it before coming to any conclusions!

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.

impl Mesh

Shape constructors

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.

Trait Implementations

impl Clone for Mesh

fn clone(&self) -> Mesh

Returns a copy of the value.

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

Converts to this type from the input type.