Struct sdl2::render::Canvas
[−]
[src]
pub struct Canvas<T: RenderTarget> { /* fields omitted */ }
Manages and owns a target (Surface
, Window
, or Texture
) and allows drawing in it.
If the Window
manipulates the shell of the Window, Canvas<Window>
allows you to
manipulate both the shell and the inside of the window;
you can manipulate pixel by pixel (not recommended), lines, colored rectangles, or paste
Texture
s to this Canvas
.
Drawing to the Canvas
does not take effect immediately, it draws to a buffer until you
call present()
, where all the operations you did until the last present()
are updated to your target
Its context may be shared with the TextureCreator
.
The context will not be dropped until all references of it are out of scope.
Examples
let window = video_subsystem.window("Example", 800, 600).build().unwrap(); // Let's create a Canvas which we will use to draw in our Window let mut canvas : Canvas<Window> = window.into_canvas() .present_vsync() //< this means the screen cannot // render faster than your display rate (usually 60Hz or 144Hz) .build().unwrap(); canvas.set_draw_color(Color::RGB(0, 0, 0)); // fills the canvas with the color we set in `set_draw_color`. canvas.clear(); // change the color of our drawing with a gold-color ... canvas.set_draw_color(Color::RGB(255, 210, 0)); // A draw a rectangle which almost fills our window with it ! canvas.fill_rect(Rect::new(10, 10, 780, 580)); // However the canvas has not been updated to the window yet, // everything has been processed to an internal buffer, // but if we want our buffer to be displayed on the window, // we need to call `present`. We need to call this everytime // we want to render a new frame on the window. canvas.present(); // present does not "clear" the buffer, that means that // you have to clear it yourself before rendering again, // otherwise leftovers of what you've renderer before might // show up on the window ! // // A good rule of thumb is to `clear()`, draw every texture // needed, and then `present()`; repeat this every new frame.
Methods
impl<'s> Canvas<Surface<'s>>
[src]
Methods for the SurfaceCanvas
.
fn from_surface(surface: Surface<'s>) -> Result<Self, String>
Creates a 2D software rendering context for a surface.
This method should only fail if SDL2 is not built with rendering support, or there's an out-of-memory error.
fn surface(&self) -> &SurfaceRef
Gets a reference to the associated surface of the Canvas
fn surface_mut(&mut self) -> &mut SurfaceRef
Gets a mutable reference to the associated surface of the Canvas
fn into_surface(self) -> Surface<'s>
Gets the associated surface of the Canvas and destroys the Canvas
fn with_target<'r, 't, 'a>(
&'r mut self,
texture: &'t mut Texture<'a>
) -> Result<TextureCanvas<'r, 't, SurfaceContext<'s>>, TargetRenderError>
&'r mut self,
texture: &'t mut Texture<'a>
) -> Result<TextureCanvas<'r, 't, SurfaceContext<'s>>, TargetRenderError>
Sets the render target to the provided texture
Returns a handle for rendering methods to the target
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
.
fn texture_creator(&self) -> TextureCreator<SurfaceContext<'s>>
Returns a TextureCreator
that can create Textures to be drawn on this Canvas
This TextureCreator
will share a reference to the renderer and target context.
The target (i.e., Window
) will not be destroyed and the SDL_Renderer will not be
destroyed if the TextureCreator
is still in scope.
impl Canvas<Window>
[src]
Methods for the WindowCanvas
.
fn window(&self) -> &Window
Gets a reference to the associated window of the Canvas
fn window_mut(&mut self) -> &mut Window
Gets a mutable reference to the associated window of the Canvas
fn into_window(self) -> Window
Gets the associated window of the Canvas and destroys the Canvas
fn with_target<'r, 't, 'a>(
&'r mut self,
texture: &'t mut Texture<'a>
) -> Result<TextureCanvas<'r, 't, WindowContext>, TargetRenderError>
&'r mut self,
texture: &'t mut Texture<'a>
) -> Result<TextureCanvas<'r, 't, WindowContext>, TargetRenderError>
Sets the render target to the provided texture
Returns a handle for rendering methods to the target
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
.
fn texture_creator(&self) -> TextureCreator<WindowContext>
Returns a TextureCreator
that can create Textures to be drawn on this Canvas
This TextureCreator
will share a reference to the renderer and target context.
The target (i.e., Window
) will not be destroyed and the SDL_Renderer will not be
destroyed if the TextureCreator
is still in scope.
impl<T: RenderTarget> Canvas<T>
[src]
fn render_target_supported(&self) -> bool
Determine whether a window supports the use of render targets.
impl<T: RenderTarget> Canvas<T>
[src]
Drawing methods
fn raw(&self) -> *mut SDL_Renderer
fn set_draw_color(&mut self, color: Color)
Sets the color used for drawing operations (Rect, Line and Clear).
fn draw_color(&self) -> Color
Gets the color used for drawing operations (Rect, Line and Clear).
fn set_blend_mode(&mut self, blend: BlendMode)
Sets the blend mode used for drawing operations (Fill and Line).
fn blend_mode(&self) -> BlendMode
Gets the blend mode used for drawing operations.
fn clear(&mut self)
Clears the current rendering target with the drawing color.
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.
fn output_size(&self) -> Result<(u32, u32), String>
Gets the output size of a rendering context.
fn set_logical_size(
&mut self,
width: u32,
height: u32
) -> Result<(), IntegerOrSdlError>
&mut self,
width: u32,
height: u32
) -> Result<(), IntegerOrSdlError>
Sets a device independent resolution for rendering.
fn logical_size(&self) -> (u32, u32)
Gets device independent resolution for rendering.
fn set_viewport<R: Into<Option<Rect>>>(&mut self, rect: R)
Sets the drawing area for rendering on the current target.
fn viewport(&self) -> Rect
Gets the drawing area for the current target.
fn set_clip_rect<R: Into<Option<Rect>>>(&mut self, rect: R)
Sets the clip rectangle for rendering on the specified target.
If the rectangle is None
, clipping will be disabled.
fn clip_rect(&self) -> Option<Rect>
Gets the clip rectangle for the current target.
Returns None
if clipping is disabled.
fn set_scale(&mut self, scale_x: f32, scale_y: f32) -> Result<(), String>
Sets the drawing scale for rendering on the current target.
fn scale(&self) -> (f32, f32)
Gets the drawing scale for the current target.
fn draw_point<P: Into<Point>>(&mut self, point: P) -> Result<(), String>
Draws a point on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)
fn draw_points<'a, P: Into<&'a [Point]>>(
&mut self,
points: P
) -> Result<(), String>
&mut self,
points: P
) -> Result<(), String>
Draws multiple points on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)
fn draw_line<P1: Into<Point>, P2: Into<Point>>(
&mut self,
start: P1,
end: P2
) -> Result<(), String>
&mut self,
start: P1,
end: P2
) -> Result<(), String>
Draws a line on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)
fn draw_lines<'a, P: Into<&'a [Point]>>(
&mut self,
points: P
) -> Result<(), String>
&mut self,
points: P
) -> Result<(), String>
Draws a series of connected lines on the current rendering target. Errors if drawing fails for any reason (e.g. driver failure)
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)
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)
fn fill_rect<R: Into<Option<Rect>>>(&mut self, rect: R) -> Result<(), String>
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)
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)
fn copy<R1, R2>(
&mut self,
texture: &Texture,
src: R1,
dst: R2
) -> Result<(), String> where
R1: Into<Option<Rect>>,
R2: Into<Option<Rect>>,
&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
isNone
, the entire texture is copied. - If
dst
isNone
, 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.
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>>,
&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
isNone
, the entire texture is copied. - If
dst
isNone
, the texture will be stretched to fill the given rectangle. - If
center
isNone
, rotation will be done around the center point ofdst
, orsrc
ifdst
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.
fn read_pixels<R: Into<Option<Rect>>>(
&self,
rect: R,
format: PixelFormatEnum
) -> Result<Vec<u8>, String>
&self,
rect: R,
format: PixelFormatEnum
) -> Result<Vec<u8>, String>
Reads pixels from the current rendering target.
Remarks
WARNING: This is a very slow operation, and should not be used frequently.
impl<'r, 't, TC> Canvas<TextureTarget<'r, 't, TC>>
[src]
fn with_target<'nt, 'a>(
self,
texture: &'nt mut Texture<'a>
) -> Result<TextureCanvas<'r, 'nt, TC>, SdlError>
self,
texture: &'nt mut Texture<'a>
) -> Result<TextureCanvas<'r, 'nt, TC>, SdlError>
Replace the target of the TextureCanvas
with a different Texture
Returns the new TextureCanvas
and releases the &mut
borrow on the old Texture
Methods from Deref<Target = RendererContext<T::Context>>
fn info(&self) -> RendererInfo
Gets information about the rendering context.
fn raw(&self) -> *mut SDL_Renderer
Gets the raw pointer to the SDL_Renderer
Trait Implementations
impl<T: RenderTarget> Deref for Canvas<T>
[src]
type Target = RendererContext<T::Context>
The resulting type after dereferencing
fn deref(&self) -> &RendererContext<T::Context>
The method called to dereference a value