pub struct Mesh { /* private fields */ }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
Texturethat individual vertices can sample from. - An
IndexBufferthat 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§
source§impl Mesh
impl Mesh
sourcepub fn new(vertex_buffer: VertexBuffer) -> Mesh
pub fn new(vertex_buffer: VertexBuffer) -> Mesh
Creates a new mesh, using the provided vertex buffer.
sourcepub fn indexed(vertex_buffer: VertexBuffer, index_buffer: IndexBuffer) -> Mesh
pub fn indexed(vertex_buffer: VertexBuffer, index_buffer: IndexBuffer) -> Mesh
Creates a new mesh, using the provided vertex and index buffers.
sourcepub fn draw<P>(&self, ctx: &mut Context, params: P)where
P: Into<DrawParams>,
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).
sourcepub fn draw_instanced<P>(&self, ctx: &mut Context, instances: usize, params: P)where
P: Into<DrawParams>,
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!
sourcepub fn vertex_buffer(&self) -> &VertexBuffer
pub fn vertex_buffer(&self) -> &VertexBuffer
Gets a reference to the vertex buffer contained within this mesh.
sourcepub fn set_vertex_buffer(&mut self, vertex_buffer: VertexBuffer)
pub fn set_vertex_buffer(&mut self, vertex_buffer: VertexBuffer)
Sets the vertex buffer that will be used when drawing the mesh.
sourcepub fn index_buffer(&self) -> Option<&IndexBuffer>
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.
sourcepub fn set_index_buffer(&mut self, index_buffer: IndexBuffer)
pub fn set_index_buffer(&mut self, index_buffer: IndexBuffer)
Sets the index buffer that will be used when drawing the mesh.
sourcepub fn reset_index_buffer(&mut self)
pub fn reset_index_buffer(&mut self)
Resets the mesh to no longer use indexed drawing.
sourcepub fn texture(&self) -> Option<&Texture>
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.
sourcepub fn set_texture(&mut self, texture: Texture)
pub fn set_texture(&mut self, texture: Texture)
Sets the texture that will be used when drawing the mesh.
sourcepub fn reset_texture(&mut self)
pub fn reset_texture(&mut self)
Resets the mesh to be untextured.
sourcepub fn front_face_winding(&self) -> VertexWinding
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.
sourcepub fn set_front_face_winding(&mut self, winding: VertexWinding)
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.
sourcepub fn backface_culling(&self) -> bool
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.
sourcepub fn set_backface_culling(&mut self, enabled: bool)
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.
sourcepub fn set_draw_range(&mut self, start: usize, count: usize)
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.
sourcepub fn reset_draw_range(&mut self)
pub fn reset_draw_range(&mut self)
Sets the mesh to include all of its data when drawing.
source§impl Mesh
impl Mesh
sourcepub fn rectangle(
ctx: &mut Context,
style: ShapeStyle,
rectangle: Rectangle
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn rounded_rectangle(
ctx: &mut Context,
style: ShapeStyle,
rectangle: Rectangle,
radii: BorderRadii
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn circle(
ctx: &mut Context,
style: ShapeStyle,
center: Vec2<f32>,
radius: f32
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn ellipse(
ctx: &mut Context,
style: ShapeStyle,
center: Vec2<f32>,
radii: Vec2<f32>
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn polygon(
ctx: &mut Context,
style: ShapeStyle,
points: &[Vec2<f32>]
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn polyline(
ctx: &mut Context,
stroke_width: f32,
points: &[Vec2<f32>]
) -> Result<Mesh>
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::TessellationErrorwill be returned if the shape could not be turned into vertex data.TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.