Struct Canvas

pub struct Canvas<T: RenderTarget, U> { /* private fields */ }

This struct allows you to draw to the screen in various ways. It is a wrapper around:

• An sdl2 Canvas, which allows you to draw points, lines, rectangles, etc, and to “blit” textures and surfaces onto the screen.
• An sdl2 TextureCreator, which is linked to the sdl2 Canvas, for creating textures.
• An [sdl2-unifont SurfaceRenderer][TextRenderer] for rendering text to a surface. This struct implements Deref and DerefMut for the sdl2 Canvas, so you can call any of the normal drawing routines via deref coersion.

Implementations

impl Canvas<Window, WindowContext>

pub fn new(inner: SdlCanvas<Window>) -> Self

Create a new Canvas from the specified sdl2 WindowCanvas that draws to a window on the screen

impl<'a> Canvas<Surface<'a>, SurfaceContext<'a>>

pub fn new(inner: SdlCanvas<Surface<'a>>) -> Self

Create a new Canvas from an sdl2 SurfaceCanvas, that draws internally to an sdl2 Surface.

impl<T: RenderTarget, U> Canvas<T, U>

pub fn texture_creator(&self) -> &TextureCreator<U>

Returns an immutable reference to the TextureCreator associated with this canvas.

pub fn texture_creator_mut(&mut self) -> &mut TextureCreator<U>

Returns a mutable reference to the TextureCreator associated with this canvas.

pub fn draw_circle<P>(&mut self, center: P, radius: i32) -> Result<(), String>

where P: Into<Point>,

Draws a circle outline using Bresenham’s algorithm, with the given center and radius.

pub fn fill_circle<P>(&mut self, center: P, radius: i32) -> Result<(), String>

where P: Into<Point>,

Draws a filled circle using Bresenham’s algorithm, with the given center and radius.

Examples found in repository

examples/moving_circle.rs (line 50)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - CIRCLE_RADIUS) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - CIRCLE_RADIUS) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Draw the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_circle((self.x as i32, self.y as i32), CIRCLE_RADIUS as i32)?;
        Ok(true)
    }

Methods from Deref<Target = SdlCanvas<T>>

pub fn render_target_supported(&self) -> bool

Determine whether a window supports the use of render targets.

pub fn with_texture_canvas<F>( &mut self, texture: &mut Texture<'_>, f: F, ) -> Result<(), TargetRenderError>

where F: for<'r> FnOnce(&'r mut Canvas<T>),

Temporarily sets the target of Canvas to a Texture. This effectively allows rendering to a Texture in any way you want: you can make a Texture a combination of other Textures, be a complex geometry form with the gfx module, … You can draw pixel by pixel in it if you want, so you can do basically anything with that Texture.

If you want to set the content of multiple Texture at once the most efficient way possible, don’t make a loop and call this function every time and use with_multiple_texture_canvas instead. Using with_texture_canvas is actually inefficient because the target is reset to the source (the Window or the Surface) at the end of this function, but using it in a loop would make this reset useless. Plus, the check that render_target is actually supported on that Canvas is also done every time, leading to useless checks.

Notes

Note that the Canvas in the closure is exactly the same as the one you call this function with, meaning that you can call every function of your original Canvas.

That means you can also call with_texture_canvas and with_multiple_texture_canvas from the inside of the closure. Even though this is useless and inefficient, this is totally safe to do and allowed.

Since the render target is now a Texture, some calls of Canvas might return another result than if the target was to be the original source. For instance output_size will return this size of the current Texture in the closure, but the size of the Window or Surface outside of the closure.

You do not need to call present after drawing in the Canvas in the closure, the changes are applied directly to the Texture instead of a hidden buffer.

Errors

• returns TargetRenderError::NotSupported if the renderer does not support the use of render targets
• returns TargetRenderError::SdlError if SDL2 returned with an error code.

The texture must be created with the texture access: sdl2::render::TextureAccess::Target. Using a texture which was not created with the texture access Target is undefined behavior.

Examples

The example below changes a newly created Texture to be a 150-by-150 black texture with a 50-by-50 red square in the middle.

let texture_creator = canvas.texture_creator();
let mut texture = texture_creator
    .create_texture_target(texture_creator.default_pixel_format(), 150, 150)
    .unwrap();
let result = canvas.with_texture_canvas(&mut texture, |texture_canvas| {
    texture_canvas.set_draw_color(Color::RGBA(0, 0, 0, 255));
    texture_canvas.clear();
    texture_canvas.set_draw_color(Color::RGBA(255, 0, 0, 255));
    texture_canvas.fill_rect(Rect::new(50, 50, 50, 50)).unwrap();
});

pub fn with_multiple_texture_canvas<'t, 'a, 's, I, F, U>( &mut self, textures: I, f: F, ) -> Result<(), TargetRenderError>

where 't: 'a, 'a: 's, U: 's, F: for<'r> FnMut(&'r mut Canvas<T>, &U), I: Iterator<Item = &'s (&'a mut Texture<'t>, U)>,

Same as with_texture_canvas, but allows to change multiple Textures at once with the least amount of overhead. It means that between every iteration the Target is not reset to the source, and that the fact that the Canvas supports render target isn’t checked every iteration either; the check is actually only done once, at the beginning, avoiding useless checks.

The closure is run once for every Texture sent as parameter.

The main changes from with_texture_canvas is that is takes an Iterator of (&mut Texture, U), where U is a type defined by the user. The closure takes a &mut Canvas, and &U as arguments instead of a simple &mut Canvas. This user-defined type allows you to keep track of what to do with the Canvas you have received in the closure.

You will usually want to keep track of the number, a property, or anything that will allow you to uniquely track this Texture, but it can also be an empty struct or () as well!

Examples

Let’s create two textures, one which will be yellow, and the other will be white

let texture_creator = canvas.texture_creator();
enum TextureColor {
    Yellow,
    White,
};

let mut square_texture1 : Texture =
    texture_creator.create_texture_target(None, 100, 100).unwrap();
let mut square_texture2 : Texture =
    texture_creator.create_texture_target(None, 100, 100).unwrap();
let textures : Vec<(&mut Texture, TextureColor)> = vec![
    (&mut square_texture1, TextureColor::Yellow),
    (&mut square_texture2, TextureColor::White)
];
let result : Result<(), _> =
    canvas.with_multiple_texture_canvas(textures.iter(), |texture_canvas, user_context| {
    match *user_context {
        TextureColor::White => {
            texture_canvas.set_draw_color(Color::RGB(255, 255, 255));
        },
        TextureColor::Yellow => {
            texture_canvas.set_draw_color(Color::RGB(255, 255, 0));
        }
    };
    texture_canvas.clear();
});
// square_texture1 is now Yellow and square_texture2 is now White!

pub fn raw(&self) -> *mut SDL_Renderer

pub fn set_draw_color<C>(&mut self, color: C)

where C: Into<Color>,

Sets the color used for drawing operations (Rect, Line and Clear).

Examples found in repository

examples/colour_cycle.rs (line 39)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Handle keyboard input
        if input.keyboard.pressed(Scancode::Q) {
            return Ok(false);
        }
        // If we're at the bounds for a colour value, change direction
        if self.col <= 0.0 || self.col >= 255.0 {
            self.flipper = !self.flipper;
        }
        // Fill the screen with the current colour
        canvas.set_draw_color(Color::RGB(self.col as u8, 0, 255 - self.col as u8));
        canvas.clear();
        // Change the colour
        if !self.flipper {
            self.col -= CYCLE_SPEED * elapsed_time as f32;
        } else {
            self.col += CYCLE_SPEED * elapsed_time as f32;
        }
        Ok(true)
    }

examples/moving_circle.rs (line 47)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - CIRCLE_RADIUS) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - CIRCLE_RADIUS) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Draw the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_circle((self.x as i32, self.y as i32), CIRCLE_RADIUS as i32)?;
        Ok(true)
    }

examples/moving_rect.rs (line 47)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - RECT_SIZE) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - RECT_SIZE) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Fill the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_rect(Rect::new(
            self.x as i32,
            self.y as i32,
            RECT_SIZE,
            RECT_SIZE,
        ))?;
        Ok(true)
    }

pub fn draw_color(&self) -> Color

Gets the color used for drawing operations (Rect, Line and Clear).

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

Sets the blend mode used for drawing operations (Fill and Line).

pub fn blend_mode(&self) -> BlendMode

Gets the blend mode used for drawing operations.

pub fn clear(&mut self)

Clears the current rendering target with the drawing color.

Examples found in repository

examples/colour_cycle.rs (line 40)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Handle keyboard input
        if input.keyboard.pressed(Scancode::Q) {
            return Ok(false);
        }
        // If we're at the bounds for a colour value, change direction
        if self.col <= 0.0 || self.col >= 255.0 {
            self.flipper = !self.flipper;
        }
        // Fill the screen with the current colour
        canvas.set_draw_color(Color::RGB(self.col as u8, 0, 255 - self.col as u8));
        canvas.clear();
        // Change the colour
        if !self.flipper {
            self.col -= CYCLE_SPEED * elapsed_time as f32;
        } else {
            self.col += CYCLE_SPEED * elapsed_time as f32;
        }
        Ok(true)
    }

examples/moving_circle.rs (line 48)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - CIRCLE_RADIUS) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - CIRCLE_RADIUS) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Draw the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_circle((self.x as i32, self.y as i32), CIRCLE_RADIUS as i32)?;
        Ok(true)
    }

examples/moving_rect.rs (line 48)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - RECT_SIZE) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - RECT_SIZE) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Fill the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_rect(Rect::new(
            self.x as i32,
            self.y as i32,
            RECT_SIZE,
            RECT_SIZE,
        ))?;
        Ok(true)
    }

pub fn present(&mut self)

Updates the screen with any rendering performed since the previous call.

SDL’s rendering functions operate on a backbuffer; that is, calling a rendering function such as draw_line() does not directly put a line on the screen, but rather updates the backbuffer. As such, you compose your entire scene and present the composed backbuffer to the screen as a complete picture.

pub fn output_size(&self) -> Result<(u32, u32), String>

Gets the output size of a rendering context.

pub fn set_logical_size( &mut self, width: u32, height: u32, ) -> Result<(), IntegerOrSdlError>

Sets a device independent resolution for rendering.

pub fn logical_size(&self) -> (u32, u32)

Gets device independent resolution for rendering.

pub fn set_viewport<R>(&mut self, rect: R)

where R: Into<Option<Rect>>,

Sets the drawing area for rendering on the current target.

pub fn viewport(&self) -> Rect

Gets the drawing area for the current target.

pub fn set_clip_rect<R>(&mut self, rect: R)

where R: Into<Option<Rect>>,

Sets the clip rectangle for rendering on the specified target.

If the rectangle is None, clipping will be disabled.

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

Gets the clip rectangle for the current target.

Returns None if clipping is disabled.

pub fn set_scale(&mut self, scale_x: f32, scale_y: f32) -> Result<(), String>

Sets the drawing scale for rendering on the current target.

pub fn scale(&self) -> (f32, f32)

Gets the drawing scale for the current target.

pub fn draw_point<P>(&mut self, point: P) -> Result<(), String>

where P: Into<Point>,

Draws a point on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn draw_points<'a, P>(&mut self, points: P) -> Result<(), String>

where P: Into<&'a [Point]>,

Draws multiple points on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn draw_line<P1, P2>(&mut self, start: P1, end: P2) -> Result<(), String>

where P1: Into<Point>, P2: Into<Point>,

Draws a line on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn draw_lines<'a, P>(&mut self, points: P) -> Result<(), String>

where P: Into<&'a [Point]>,

Draws a series of connected lines on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn draw_rect(&mut self, rect: Rect) -> Result<(), String>

Draws a rectangle on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn draw_rects(&mut self, rects: &[Rect]) -> Result<(), String>

Draws some number of rectangles on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)

pub fn fill_rect<R>(&mut self, rect: R) -> Result<(), String>

where R: Into<Option<Rect>>,

Fills a rectangle on the current rendering target with the drawing color. Passing None will fill the entire rendering target. Errors if drawing fails for any reason (e.g. driver failure)

Examples found in repository

examples/moving_rect.rs (lines 50-55)

    fn on_update(
        &mut self,
        canvas: &mut WindowCanvas,
        input: &InputState,
        elapsed_time: f64,
    ) -> sge::ApplicationResult {
        // Move the rectangle with the keyboard
        if input.keyboard.held(Scancode::Up) {
            self.y = (self.y - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Down) {
            self.y =
                (self.y + MOVEMENT_SPEED * elapsed_time).min((SCREEN_HEIGHT - RECT_SIZE) as f64);
        }
        if input.keyboard.held(Scancode::Left) {
            self.x = (self.x - MOVEMENT_SPEED * elapsed_time).max(0.0);
        } else if input.keyboard.held(Scancode::Right) {
            self.x =
                (self.x + MOVEMENT_SPEED * elapsed_time).min((SCREEN_WIDTH - RECT_SIZE) as f64);
        }
        // Move the rectangle with the mouse
        if input.mouse.buttons.held(MouseButton::Left) {
            self.x = input.mouse.x as f64;
            self.y = input.mouse.y as f64;
        }
        // Fill the screen
        canvas.set_draw_color(Color::BLACK);
        canvas.clear();
        canvas.set_draw_color(Color::GRAY);
        canvas.fill_rect(Rect::new(
            self.x as i32,
            self.y as i32,
            RECT_SIZE,
            RECT_SIZE,
        ))?;
        Ok(true)
    }

pub fn fill_rects(&mut self, rects: &[Rect]) -> Result<(), String>

Fills some number of rectangles on the current rendering target with the drawing color. Errors if drawing fails for any reason (e.g. driver failure)

pub fn copy<R1, R2>( &mut self, texture: &Texture<'_>, src: R1, dst: R2, ) -> Result<(), String>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Copies a portion of the texture to the current rendering target.

• If src is None, the entire texture is copied.
• If dst is None, the texture will be stretched to fill the given rectangle.

Errors if drawing fails for any reason (e.g. driver failure), or if the provided texture does not belong to the renderer.

pub fn copy_ex<R1, R2, P>( &mut self, texture: &Texture<'_>, src: R1, dst: R2, angle: f64, center: P, flip_horizontal: bool, flip_vertical: bool, ) -> Result<(), String>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>, P: Into<Option<Point>>,

Copies a portion of the texture to the current rendering target, optionally rotating it by angle around the given center and also flipping it top-bottom and/or left-right.

• If src is None, the entire texture is copied.
• If dst is None, the texture will be stretched to fill the given rectangle.
• If center is None, rotation will be done around the center point of dst, or src if dst is None.

Errors if drawing fails for any reason (e.g. driver failure), if the provided texture does not belong to the renderer, or if the driver does not support RenderCopyEx.

pub fn read_pixels<R>( &self, rect: R, format: PixelFormatEnum, ) -> Result<Vec<u8>, String>

where R: Into<Option<Rect>>,

Reads pixels from the current rendering target.

Remarks

WARNING: This is a very slow operation, and should not be used frequently.

Methods from Deref<Target = RendererContext<<T as RenderTarget>::Context>>

pub fn info(&self) -> RendererInfo

Gets information about the rendering context.

pub fn raw(&self) -> *mut SDL_Renderer

Gets the raw pointer to the SDL_Renderer

Trait Implementations

impl<T: RenderTarget, U> Deref for Canvas<T, U>

type Target = Canvas<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: RenderTarget, U> DerefMut for Canvas<T, U>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.