Struct ggez::graphics::MeshBuilder

pub struct MeshBuilder { /* fields omitted */ }

A builder for creating Meshes.

This allows you to easily make one Mesh containing many different complex pieces of geometry. They don’t have to be connected to each other, and will all be drawn at once.

Note that this doesn’t try very hard to handle degenerate cases. It can easily break if you tell it to do things that result in a circle of radius 0, a line of width 0, an infintessimally skinny triangle, or other mathematically inconvenient things like that.

The following example shows how to build a mesh containing a line and a circle:

let mesh: Mesh = MeshBuilder::new()
    .line(&[glam::vec2(20.0, 20.0), glam::vec2(40.0, 20.0)], 4.0, (255, 0, 0).into())?
    .circle(DrawMode::fill(), glam::vec2(60.0, 38.0), 40.0, 1.0, (0, 255, 0).into())?
    .build(ctx)?;

A more sophisticated example:

use ggez::{Context, GameResult};
use ggez::graphics::{self, DrawMode, MeshBuilder};

fn draw_danger_signs(ctx: &mut Context) -> GameResult {
    // Initialize a builder instance.
    let mesh = MeshBuilder::new()
        // Add vertices for 3 lines (in an approximate equilateral triangle).
        .line(
            &[
                glam::vec2(0.0, 0.0),
                glam::vec2(-30.0, 52.0),
                glam::vec2(30.0, 52.0),
                glam::vec2(0.0, 0.0),
            ],
            1.0,
            graphics::Color::WHITE,
        )?
        // Add vertices for an exclamation mark!
        .ellipse(DrawMode::fill(), glam::vec2(0.0, 25.0), 2.0, 15.0, 2.0, graphics::Color::WHITE,)?
        .circle(DrawMode::fill(), glam::vec2(0.0, 45.0), 2.0, 2.0, graphics::Color::WHITE,)?
        // Finalize then unwrap. Unwrapping via `?` operator either yields the final `Mesh`,
        // or propagates the error (note return type).
        .build(ctx)?;
    // Draw 3 meshes in a line, 1st and 3rd tilted by 1 radian.
    graphics::draw(ctx, &mesh, (glam::vec2(50.0, 50.0), -1.0, graphics::Color::WHITE))?;
    graphics::draw(ctx, &mesh, (glam::vec2(150.0, 50.0), 0.0, graphics::Color::WHITE))?;
    graphics::draw(ctx, &mesh, (glam::vec2(250.0, 50.0), 1.0, graphics::Color::WHITE))?;
    Ok(())
}

Implementations

impl MeshBuilder

pub fn new() -> Self

Create a new MeshBuilder.

pub fn line<P>(
    &mut self,
    points: &[P],
    width: f32,
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>> + Clone, 

Create a new mesh for a line of one or more connected segments.

pub fn circle<P>(
    &mut self,
    mode: DrawMode,
    point: P,
    radius: f32,
    tolerance: f32,
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>>, 

Create a new mesh for a circle.

For the meaning of the tolerance parameter, see here.

pub fn ellipse<P>(
    &mut self,
    mode: DrawMode,
    point: P,
    radius1: f32,
    radius2: f32,
    tolerance: f32,
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>>, 

Create a new mesh for an ellipse.

For the meaning of the tolerance parameter, see here.

pub fn polyline<P>(
    &mut self,
    mode: DrawMode,
    points: &[P],
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>> + Clone, 

Create a new mesh for a series of connected lines.

pub fn polygon<P>(
    &mut self,
    mode: DrawMode,
    points: &[P],
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>> + Clone, 

Create a new mesh for a closed polygon. The points given must be in clockwise order, otherwise at best the polygon will not draw.

pub fn polyline_with_vertex_builder<P, V>(
    &mut self,
    mode: DrawMode,
    points: &[P],
    is_closed: bool,
    vb: V
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>> + Clone,
    V: StrokeVertexConstructor<Vertex> + FillVertexConstructor<Vertex>, 

Create a new mesh for a given polyline using a custom vertex builder. The points given must be in clockwise order.

pub fn rectangle(
    &mut self,
    mode: DrawMode,
    bounds: Rect,
    color: Color
) -> GameResult<&mut Self>

Create a new mesh for a rectangle.

pub fn rounded_rectangle(
    &mut self,
    mode: DrawMode,
    bounds: Rect,
    radius: f32,
    color: Color
) -> GameResult<&mut Self>

Create a new mesh for a rounded rectangle.

pub fn triangles<P>(
    &mut self,
    triangles: &[P],
    color: Color
) -> GameResult<&mut Self> where
    P: Into<Point2<f32>> + Clone, 

Create a new Mesh from a raw list of triangles. The length of the list must be a multiple of 3.

Currently does not support UV’s or indices.

pub fn texture(&mut self, texture: Image) -> GameResult<&mut Self>

Takes an Image to apply to the mesh.

pub fn raw<V>(
    &mut self,
    verts: &[V],
    indices: &[u32],
    texture: Option<Image>
) -> GameResult<&mut Self> where
    V: Into<Vertex> + Clone, 

Creates a Mesh from a raw list of triangles defined from vertices and indices. You may also supply an Image to use as a texture, if you pass None, it will just use a pure white texture.

This is the most primitive mesh-creation method, but allows you full control over the tesselation and texturing. It has the same constraints as Mesh::from_raw().

pub fn build(&self, ctx: &mut Context) -> GameResult<Mesh>

Takes the accumulated geometry and load it into GPU memory, creating a single Mesh.

Note that this returns a GameResult<Mesh>, since the build can fail, for example when trying to build an empty MeshBuilder.

Trait Implementations

impl Clone for MeshBuilder

fn clone(&self) -> MeshBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MeshBuilder

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

Formats the value using the given formatter.

impl Default for MeshBuilder

fn default() -> Self

Returns the “default value” for a type.