Struct DrawBuilder 

pub struct DrawBuilder<V, U> {
    pub scissor: Option<Bounds2<i32>>,
    pub blend_mode: BlendMode,
    pub depth_test: Option<Compare>,
    pub cull_mode: Option<CullMode>,
    pub shader: ShaderProgram,
    pub uniform: U,
    /* private fields */
}

Draw builder.

A DrawBuilder collects geometry (vertices and indices) generated on the CPU, and prepares it for rendering. It is the primary structure for immediate-mode drawing.

See also: DrawPool allows mixing multiple DrawBuilder types with different vertex or uniform formats in a single pass.

Filling the buffer

Use one of the high-level tools to populate the buffer with geometry:

• d2::Paint – fill shapes with color via fill_* methods.
• d2::Pen – draw outlines and polylines via draw_* methods.
• d2::Sprite – draw textured quads and images via sprite_* methods.
• d2::Scribe – draw text via text_* methods.

These tools append to the buffer incrementally and can be freely mixed.

Configuring rendering

Rendering behavior is controlled via the public fields on this type:

• blend_mode, depth_test, scissor, cull_mode, and shader can be customized.
• The uniform field contains shader-specific uniform data.

Draw calls are automatically batched when these settings remain unchanged. For best performance, group similar drawing operations together using the same tool and properties.

Advanced usage

Reusing the buffer

A DrawBuilder can be reused across frames to avoid repeated allocations. Simply call clear() to remove previously submitted geometry and start fresh.

Drawing multiple times

Once populated, a DrawBuilder can be drawn multiple times using draw(). This is useful when the same content needs to be rendered to different surfaces or at different points in the frame. The buffer remains valid until cleared or modified.

Cross-thread generation

Geometry can be generated in a background thread by filling a DrawBuilder, then sending it to the main thread for rendering. This allows expensive CPU-side work (e.g., shape tessellation, layout) to be decoupled from real-time rendering.

Custom draw tools

For low-level or specialized use cases, custom draw tools can be implemented using the begin() method. This provides access to a PrimBuilder, allowing direct construction of geometry and command batching.

Example

use shade::{cvmath, d2, im};

fn draw(g: &mut shade::Graphics, viewport: cvmath::Bounds2i, shader: shade::ShaderProgram) {
	// Construct a new DrawBuilder instance
	let mut cv = im::DrawBuilder::<d2::ColorVertex, d2::ColorUniform>::new();

	// Adjust the shared properties
	cv.blend_mode = shade::BlendMode::Alpha;
	cv.shader = shader;

	// Setup shader uniforms
	cv.uniform.transform = cvmath::Transform2::ortho(viewport.cast());

	// Create a paint bucket with the vertex template
	let paint = d2::Paint {
		template: d2::ColorTemplate {
			color1: cvmath::Vec4(255, 128, 128, 190),
			color2: cvmath::Vec4::dup(255),
		},
	};

	// Using the paint bucket, fill some shapes
	cv.fill_edge_rect(&paint, &cvmath::Bounds2::c(50.0, 50.0, 100.0, 100.0), 0.2);
	cv.fill_ring(&paint, &cvmath::Bounds2::c(50.0, 50.0, 150.0, 150.0), 5.0, 19);

	// Draw to the back buffer
	cv.draw(g);
}

Fields

scissor: Option<Bounds2<i32>>

blend_mode: BlendMode

depth_test: Option<Compare>

cull_mode: Option<CullMode>

shader: ShaderProgram

uniform: U

Implementations

impl<V: TVertex, U: TUniform> DrawBuilder<V, U>

pub fn fill_rect<T: ToVertex<V>>(&mut self, paint: &Paint<T>, rc: &Bounds2f)

Fills a rectangle.

pub fn fill_edge_rect<T: ToVertex<V>>( &mut self, paint: &Paint<T>, rc: &Bounds2f, thickness: f32, )

Fills a rectangle with an outline.

pub fn fill_round_rect<T: ToVertex<V>>( &mut self, paint: &Paint<T>, rc: &Bounds2f, sx: f32, sy: f32, _segments: i32, )

Fills a rounded rectangle.

pub fn fill_convex<T: ToVertex<V>>(&mut self, paint: &Paint<T>, pts: &[Point2f])

Fills a convex shape.

pub fn fill_polygon<T: ToVertex<V>>( &mut self, paint: &Paint<T>, pts: &[Point2f], triangles: &[Index3], )

Fills a polygon shape.

pub fn fill_polygon2(&mut self, vertices: &[V], triangles: &[Index3])

Fills a polygon shape with pre-made vertices.

pub fn fill_quad<T: ToVertex<V>>( &mut self, paint: &Paint<T>, bottom_left: &Point2f, top_left: &Point2f, top_right: &Point2f, bottom_right: &Point2f, )

Fills an arbitrary quad.

pub fn fill_ellipse<T: ToVertex<V>>( &mut self, paint: &Paint<T>, rc: &Bounds2f, segments: i32, )

Fills an ellipse.

pub fn fill_pie<T: ToVertex<V>>( &mut self, paint: &Paint<T>, rc: &Bounds2f, start: Angle<f32>, sweep: Angle<f32>, segments: i32, )

Fills a pie slice.

pub fn fill_ring<T: ToVertex<V>>( &mut self, paint: &Paint<T>, rc: &Bounds2f, thickness: f32, segments: i32, )

Fills a ring.

pub fn fill_bezier2<T: ToVertex<V>>( &mut self, paint: &Paint<T>, pivot: &Point2f, pts: &[Point2f; 3], segments: i32, )

impl<V: TVertex, U: TUniform> DrawBuilder<V, U>

pub fn draw_line<T: ToVertex<V>>( &mut self, pen: &Pen<T>, a: Point2f, b: Point2f, )

Draws a line from a to b.

pub fn draw_lines<T: ToVertex<V>>( &mut self, pen: &Pen<T>, pts: &[Point2f], lines: &[(u32, u32)], )

Draws lines.

pub fn draw_line_rect<T: ToVertex<V>>(&mut self, pen: &Pen<T>, rc: &Bounds2f)

Draws a rectangle with lines.

pub fn draw_round_rect<T: ToVertex<V>>( &mut self, pen: &Pen<T>, rc: &Bounds2f, sx: f32, sy: f32, _segments: i32, )

Draws a rounded rectangle with lines.

pub fn draw_arrow<T: ToVertex<V>>( &mut self, pen: &Pen<T>, start: Point2f, end: Point2f, head: f32, )

Draws an arrow.

pub fn draw_poly_line<T: ToVertex<V>>( &mut self, pen: &Pen<T>, pts: &[Point2f], close: bool, )

Draws connected lines.

pub fn draw_ellipse<T: ToVertex<V>>( &mut self, pen: &Pen<T>, rc: &Bounds2f, segments: i32, )

Draws an ellipse.

pub fn draw_arc<T: ToVertex<V>>( &mut self, pen: &Pen<T>, rc: &Bounds2f, start: Angle<f32>, sweep: Angle<f32>, segments: i32, )

Draws an arc.

pub fn draw_bezier2<T: ToVertex<V>>( &mut self, pen: &Pen<T>, pts: &[Point2f; 3], segments: i32, )

pub fn draw_bezier3<T: ToVertex<V>>( &mut self, pen: &Pen<T>, pts: &[Point2f; 4], segments: i32, )

pub fn draw_cspline<T: ToVertex<V>>( &mut self, pen: &Pen<T>, pts: &[Point2f], tension: f32, segments: i32, )

impl DrawBuilder<TextVertex, TextUniform>

pub fn text_write<T: Display>( &mut self, font: &FontResource<impl IFont>, scribe: &mut Scribe, cursor: &mut Vec2f, text: T, )

Writes a text string.

Escape sequences can modify the scribe properties in the middle of the text string, strip user controlled text of ascii escape characters to avoid this.

pub fn text_lines( &mut self, font: &FontResource<impl IFont>, scribe: &Scribe, rect: &Bounds2f, align: TextAlign, lines: &[&dyn Display], )

Writes individual lines of text strings using the box model.

The text will be aligned within the rect according to the alignment.

Escape sequences can modify the scribe properties in the middle of the text string, strip user controlled text of ascii escape characters to avoid this.

pub fn text_box( &mut self, font: &FontResource<impl IFont>, scribe: &Scribe, rect: &Bounds2f, align: TextAlign, text: &str, )

Writes a text string using the box model.

The text will be aligned within the rect according to the alignment.

Escape sequences can modify the scribe properties in the middle of the text string, strip user controlled text of ascii escape characters to avoid this.

impl<V: TVertex, U: TUniform> DrawBuilder<V, U>

pub fn sprite_rect<T: ToVertex<V>>(&mut self, sprite: &Sprite<T>, rc: &Bounds2f)

Draws a sprite inside the given rectangle.

pub fn sprite_quad<T: ToVertex<V>>( &mut self, sprite: &Sprite<T>, pos: &Transform2f, )

Draws a sprite with custom position, rotation, scale, or skew.

Unlike sprite_rect, this method lets you place the sprite at any orientation or shape by providing a 2D transform. Conceptually, the sprite is a unit square from 0, 0 to 1, 1, and each of its corners is transformed using the provided pos. The transform’s translation sets the position of the bottom-left corner (at 0, 0), while its X and Y axes define the direction and extent of the sprite’s sides.

Example

To position a sprite using three points:

use shade::d2;
use shade::cvmath::{Vec2f, Vec4, Transform2f};

fn draw(buf: &mut d2::TexturedBuffer) {
	// Create a sprite with texture coordinates and no color modulation.
	let color = Vec4(255, 255, 255, 255);
	let sprite = d2::Sprite {
		bottom_left: d2::TexturedTemplate { uv: Vec2f(0.0, 0.0), color },
		top_left: d2::TexturedTemplate { uv: Vec2f(0.0, 1.0), color },
		top_right: d2::TexturedTemplate { uv: Vec2f(1.0, 1.0), color },
		bottom_right: d2::TexturedTemplate { uv: Vec2f(1.0, 0.0), color },
	};

	let origin = Vec2f(100.0, 50.0);       // bottom-left corner
	let top_left = Vec2f(100.0, 100.0);    // defines Y axis
	let bottom_right = Vec2f(150.0, 50.0); // defines X axis

	let x_axis = bottom_right - origin;
	let y_axis = top_left - origin;

	let transform = Transform2f::compose(x_axis, y_axis, origin);
	buf.sprite_quad(&sprite, &transform);
}

impl<V: TVertex, U: TUniform> DrawBuilder<V, U>

pub fn new() -> Self

Creates a new DrawBuilder.

pub fn clear(&mut self)

Clears the DrawBuilder for reuse.

pub fn commit(self, g: &mut Graphics, usage: BufferUsage) -> DrawBuffer<U>

Commit the DrawBuilder to a DrawBuffer.

pub fn draw(&self, g: &mut Graphics)

Draws the buffer.

pub fn begin<'a>( &'a mut self, prim_type: PrimType, nverts: usize, nprims: usize, ) -> PrimBuilder<'a, V>

Begins adding a new geometry to the DrawBuilder.