Struct Canvas

pub struct Canvas { /* private fields */ }

Canvases are the main method of drawing meshes and text to images in ggez.

They can draw to any image that is capable of being drawn to (i.e. has been created with Image::new_canvas_image() or ScreenImage), or they can draw directly to the screen.

Canvases are also where you can bind your own custom shaders and samplers to use while drawing. Canvases do not automatically batch draws. To used batched (instanced) drawing, refer to InstanceArray.

Implementations

impl Canvas

pub fn from_image( gfx: &impl Has<GraphicsContext>, image: Image, clear: impl Into<Option<Color>>, ) -> Self

Create a new Canvas from an image. This will allow for drawing to a single color image.

clear will set the image initially to the given color, if a color is provided, or keep it as is, if it’s None.

The image must be created for Canvas usage, i.e. Image::new_canvas_image(), or ScreenImage, and must only have a sample count of 1.

pub fn from_screen_image( gfx: &impl Has<GraphicsContext>, image: &mut ScreenImage, clear: impl Into<Option<Color>>, ) -> Self

Helper for Canvas::from_image for construction of a Canvas from a ScreenImage.

pub fn from_msaa( gfx: &impl Has<GraphicsContext>, msaa_image: Image, resolve: Image, clear: impl Into<Option<Color>>, ) -> Self

Create a new Canvas from an MSAA image and a resolve target. This will allow for drawing with MSAA to a color image, then resolving the samples into a secondary target.

Both images must be created for Canvas usage (see Canvas::from_image). msaa_image must have a sample count > 1 and resolve_image must strictly have a sample count of 1.

pub fn from_screen_msaa( gfx: &impl Has<GraphicsContext>, msaa_image: &mut ScreenImage, resolve: &mut ScreenImage, clear: impl Into<Option<Color>>, ) -> Self

Helper for Canvas::from_msaa for construction of an MSAA Canvas from a ScreenImage.

pub fn from_frame( gfx: &impl Has<GraphicsContext>, clear: impl Into<Option<Color>>, ) -> Self

Create a new Canvas that renders directly to the window surface.

clear will set the image initially to the given color, if a color is provided, or keep it as is, if it’s None.

pub fn set_shader(&mut self, shader: &Shader)

Sets the shader to use when drawing meshes.

pub fn shader(&self) -> Shader

Returns the current shader being used when drawing meshes.

pub fn set_shader_params<Uniforms: AsStd140>( &mut self, params: &ShaderParams<Uniforms>, )

Sets the shader parameters to use when drawing meshes.

Bound to bind group 3.

pub fn set_text_shader(&mut self, shader: Shader)

Sets the shader to use when drawing text.

pub fn text_shader(&self) -> Shader

Returns the current text shader being used when drawing text.

pub fn set_text_shader_params<Uniforms: AsStd140>( &mut self, params: &ShaderParams<Uniforms>, ) -> GameResult

Sets the shader parameters to use when drawing text.

Bound to bind group 3.

pub fn set_default_shader(&mut self)

Resets the active mesh shader to the default.

pub fn set_default_text_shader(&mut self)

Resets the active text shader to the default.

pub fn set_sampler(&mut self, sampler: impl Into<Sampler>)

Sets the active sampler used to sample images.

Use set_sampler(Sampler::nearest_clamp()) for drawing pixel art graphics without blurring them.

pub fn sampler(&self) -> Sampler

Returns the currently active sampler used to sample images.

pub fn set_default_sampler(&mut self)

Resets the active sampler to the default.

This is equivalent to set_sampler(Sampler::linear_clamp()).

pub fn set_blend_mode(&mut self, blend_mode: BlendMode)

Sets the active blend mode used when drawing images.

pub fn blend_mode(&self) -> BlendMode

Returns the currently active blend mode used when drawing images.

pub fn set_premultiplied_text(&mut self, premultiplied_text: bool)

Selects whether text will be drawn with BlendMode::PREMULTIPLIED when the current blend mode is BlendMode::ALPHA. This is true by default.

pub fn set_projection(&mut self, proj: impl Into<ColumnMatrix4<f32>>)

Sets the raw projection matrix to the given homogeneous transformation matrix. For an introduction to graphics matrices, a good source is this: http://ncase.me/matrix/

pub fn projection(&self) -> ColumnMatrix4<f32>

Gets a copy of the canvas’s raw projection matrix.

pub fn mul_projection(&mut self, transform: impl Into<ColumnMatrix4<f32>>)

Premultiplies the given transformation matrix with the current projection matrix.

pub fn set_screen_coordinates(&mut self, rect: Rect)

Sets the bounds of the screen viewport. This is a shortcut for set_projection and thus will override any previous projection matrix set.

The default coordinate system has [0.0, 0.0] at the top-left corner with X increasing to the right and Y increasing down, with the viewport scaled such that one coordinate unit is one pixel on the screen. This function lets you change this coordinate system to be whatever you prefer.

The Rect’s x and y will define the top-left corner of the screen, and that plus its w and h will define the bottom-right corner.

pub fn screen_coordinates(&self) -> Option<Rect>

Returns the boudns of the screen viewport, iff the projection was last set with set_screen_coordinates. If the last projection was set with set_projection or mul_projection, None will be returned.

pub fn set_scissor_rect(&mut self, rect: Rect) -> GameResult

Sets the scissor rectangle used when drawing. Nothing will be drawn to the canvas that falls outside of this region.

Note: The rectangle is in pixel coordinates, and therefore the values will be rounded towards zero.

pub fn scissor_rect(&self) -> Rect

Returns the scissor rectangle as set by Canvas::set_scissor_rect.

pub fn set_default_scissor_rect(&mut self)

Resets the scissorr rectangle back to the original value. This will effectively disable any scissoring.

pub fn draw(&mut self, drawable: &impl Drawable, param: impl Into<DrawParam>)

Draws the given Drawable to the canvas with a given DrawParam.

pub fn draw_textured_mesh( &mut self, mesh: Mesh, image: Image, param: impl Into<DrawParam>, )

Draws a Mesh textured with an Image.

This differs from canvas.draw(mesh, param) as in that case, the mesh is untextured.

pub fn draw_instanced_mesh( &mut self, mesh: Mesh, instances: &InstanceArray, param: impl Into<DrawParam>, )

Draws an InstanceArray textured with a Mesh.

This differs from canvas.draw(instances, param) as in that case, the instances are drawn as quads.

pub fn finish(self, gfx: &mut impl HasMut<GraphicsContext>) -> GameResult

Finish drawing with this canvas and submit all the draw calls.

Trait Implementations

impl Debug for Canvas

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

Formats the value using the given formatter.