Struct tetra::graphics::Canvas

pub struct Canvas { /* fields omitted */ }

A texture that can be used for off-screen rendering.

This is sometimes referred to as a ‘render texture’ or ‘render target’ in other frameworks.

Canvases can be useful if you want to do some rendering upfront and then cache the result (e.g. a static background), or if you want to apply transformations/shaders to multiple things simultaneously.

Performance

Creating a canvas is quite an expensive operation. Try to reuse them, rather than recreating them every frame.

Switching which canvas you are rendering to can be also be slow, as it requires flushing any pending draw calls to the GPU. It’s usually a good idea to do your rendering to a canvas all in one go, if you can.

You can clone a canvas cheaply, as it is a reference-counted handle to a GPU resource. However, this does mean that modifying a canvas (e.g. drawing to it) will also affect any clones that exist of it.

Examples

The canvas example demonstrates how to draw to a canvas, and then draw that canvas to the screen.

Implementations

impl Canvas

pub fn new(ctx: &mut Context, width: i32, height: i32) -> Result<Canvas>

Creates a new canvas, with the default settings (no multisampling, no additional buffers).

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn builder(width: i32, height: i32) -> CanvasBuilder

Creates a new canvas builder, which can be used to create a canvas with multisampling and/or additional buffers.

pub fn multisampled(
    ctx: &mut Context,
    width: i32,
    height: i32,
    samples: u8
) -> Result<Canvas>

👎 Deprecated since 0.6.4:

use Canvas::builder instead

Creates a new canvas, with the specified level of multisample anti-aliasing.

The number of samples that can be used varies between graphics cards - 2, 4 and 8 are reasonably well supported. When set to 0 (the default), no multisampling will be used.

Resolving

In order to actually display a multisampled canvas, it first has to be downsampled (or ‘resolved’). This is done automatically once you switch to a different canvas/the backbuffer. Until this step takes place, your rendering will not be reflected in the canvas’ underlying texture (and by extension, in the output of draw and get_data).

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.

pub fn draw<P>(&self, ctx: &mut Context, params: P) where
    P: Into<DrawParams>, 

Draws the canvas to the screen (or to another canvas, if one is enabled).

pub fn width(&self) -> i32

Returns the width of the canvas.

pub fn height(&self) -> i32

Returns the height of the canvas.

pub fn size(&self) -> (i32, i32)

Returns the size of the canvas.

pub fn filter_mode(&self) -> FilterMode

Returns the filter mode being used by the canvas.

pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)

Sets the filter mode that should be used by the canvas.

pub fn get_data(&self, ctx: &mut Context) -> ImageData

Gets the canvas’ data from the GPU.

This can be useful if you need to do some image processing on the CPU, or if you want to output the image data somewhere. This is a fairly slow operation, so avoid doing it too often!

If this is the currently active canvas, you should unbind it or call graphics::flush before calling this method, to ensure all pending draw calls are reflected in the output. Similarly, if the canvas is multisampled, it must be resolved before changes will be reflected in this method’s output.

pub fn set_data(
    &self,
    ctx: &mut Context,
    x: i32,
    y: i32,
    width: i32,
    height: i32,
    data: &[u8]
) -> Result

Writes RGBA pixel data to a specified region of the canvas.

This method requires you to provide enough data to fill the target rectangle. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you want to overwrite the entire canvas, the replace_data method offers a more concise way of doing this.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the target rectangle. This is to prevent the graphics API from trying to read uninitialized memory.

Panics

Panics if any part of the target rectangle is outside the bounds of the canvas.

pub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result

Overwrites the entire canvas with new RGBA pixel data.

This method requires you to provide enough data to fill the canvas. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you only want to write to a subsection of the canvas, use the set_data method instead.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the target rectangle. This is to prevent the graphics API from trying to read uninitialized memory.

pub fn texture(&self) -> &Texture

Returns a reference to the canvas’ underlying texture.

If this is the currently active canvas, you may want to unbind it or call graphics::flush before trying to access the underlying texture data, to ensure all pending draw calls are completed. Similarly, if the canvas is multisampled, it must be resolved before changes will be reflected in the texture.

Trait Implementations

impl Clone for Canvas

fn clone(&self) -> Canvas

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Canvas

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

Formats the value using the given formatter.

impl PartialEq<Canvas> for Canvas

fn eq(&self, other: &Canvas) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Canvas) -> bool

This method tests for !=.

impl StructuralPartialEq for Canvas