Type Definition ggez::graphics::Canvas

pub type Canvas = CanvasGeneric<GlBackendSpec>;

A canvas that can be rendered to instead of the screen (sometimes referred to as “render target” or “render to texture”). Set the canvas with the graphics::set_canvas() function, and then anything you draw will be drawn to the canvas instead of the screen.

Resume drawing to the screen by calling graphics::set_canvas(None).

A Canvas allows graphics to be rendered to images off-screen in order to do things like saving to an image file or creating cool effects by using shaders that render to an image. If you just want to draw multiple things efficiently, look at SpriteBatch.

Note that if the canvas is not of the same size as the screen, and you want to render using coordinates relative to the canvas’ coordinate system, you need to call graphics::set_screen_coordinates and pass in a rectangle with position (0, 0) and a size equal to that of the canvas.

If you draw onto a canvas using BlendMode::Alpha you need to set its blend mode to BlendMode::Premultiplied before drawing it to a new surface. This is a side effect of the premultiplication of RGBA values when the canvas was rendered to. This requirement holds for both drawing the Canvas directly or converting it to an Image first.

let mut canvas = Canvas::new(width, height, conf::NumSamples::One, get_window_color_format(ctx));
graphics::set_canvas(ctx, Some(&canvas));

// Draw to canvas here...

graphics::present(ctx);
graphics::set_canvas(ctx, None);
canvas.set_blend_mode(Some(BlendMode::Premultiplied));

Implementations

impl Canvas

pub fn new(
    ctx: &mut Context,
    width: u16,
    height: u16,
    samples: NumSamples,
    color_format: Format
) -> GameResult<Canvas>

Create a new Canvas with the given size and number of samples.

pub fn with_window_size(ctx: &mut Context) -> GameResult<Canvas>

Create a new Canvas with the current window dimensions.

pub fn to_image(&self, ctx: &mut Context) -> GameResult<Image>

Creates an Image with the content of its raw counterpart but transformed to behave like a normal Image.

pub fn to_rgba8(&self, ctx: &mut Context) -> GameResult<Vec<u8>>

Dumps the flipped Canvas’s data to a Vec of u8 RBGA8 values.

pub fn encode<P: AsRef<Path>>(
    &self,
    ctx: &mut Context,
    format: ImageFormat,
    path: P
) -> GameResult

Encode the Canvas’s content to the given file format and write it out to the given path.

See the filesystem module docs for where exactly the file will end up.

pub fn resolve(&self, ctx: &mut Context) -> GameResult

If the canvas is multi-sampled this function resolves the internal multi-sampled texture into a non-multi-sampled texture that can actually be drawn.

ggez calls this automatically when you try to draw the canvas onto another target, or when you copy the underlying image using to_image(), to_rgba8() or encode().

You shouldn’t need to call this manually, unless you want to access the raw image after something has been drawn on the canvas, but before the canvas has been drawn onto another target itself.

Trait Implementations

impl Drawable for Canvas

fn draw(&self, ctx: &mut Context, param: DrawParam) -> GameResult

Draws the drawable onto the rendering target.

fn dimensions(&self, _: &mut Context) -> Option<Rect>

Returns a bounding box in the form of a Rect.

fn set_blend_mode(&mut self, mode: Option<BlendMode>)

Sets the blend mode to be used when drawing this drawable. This overrides the general graphics::set_blend_mode(). If None is set, defers to the blend mode set by graphics::set_blend_mode().

fn blend_mode(&self) -> Option<BlendMode>

Gets the blend mode to be used when drawing this drawable.