Struct tetra::graphics::mesh::Mesh[−][src]

pub struct Mesh { /* fields omitted */ }

Expand description

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`[src]

`pub fn new(vertex_buffer: VertexBuffer) -> Mesh`[src]

Creates a new mesh, using the provided vertex buffer.

`pub fn indexed(vertex_buffer: VertexBuffer, index_buffer: IndexBuffer) -> Mesh`[src]

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

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

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

`pub fn draw_instanced(&self, ctx: &mut Context, instances: usize, params: P) where P: Into<DrawParams>,` [src]

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`[src]

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

`pub fn set_vertex_buffer(&mut self, vertex_buffer: VertexBuffer)`[src]

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

`pub fn index_buffer(&self) -> Option<&IndexBuffer>`[src]

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)`[src]

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

`pub fn reset_index_buffer(&mut self)`[src]

Resets the mesh to no longer use indexed drawing.

`pub fn texture(&self) -> Option<&Texture>`[src]

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)`[src]

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

`pub fn reset_texture(&mut self)`[src]

Resets the mesh to be untextured.

`pub fn front_face_winding(&self) -> VertexWinding`[src]

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)`[src]

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`[src]

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)`[src]

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)`[src]

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)`[src]

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