[−][src]Struct oxydyze::util::renderer::Canvas
Manages and owns a target (Surface
or Window
) 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 every time // 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
.
pub fn from_surface(surface: Surface<'s>) -> Result<Canvas<Surface<'s>>, String>
[src]
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.
pub fn surface(&self) -> &SurfaceRef
[src]
Gets a reference to the associated surface of the Canvas
pub fn surface_mut(&mut self) -> &mut SurfaceRef
[src]
Gets a mutable reference to the associated surface of the Canvas
pub fn into_surface(self) -> Surface<'s>
[src]
Gets the associated surface of the Canvas and destroys the Canvas
pub fn texture_creator(&self) -> TextureCreator<SurfaceContext<'s>>
[src]
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
.
pub fn window(&self) -> &Window
[src]
Gets a reference to the associated window of the Canvas
pub fn window_mut(&mut self) -> &mut Window
[src]
Gets a mutable reference to the associated window of the Canvas
pub fn into_window(self) -> Window
[src]
Gets the associated window of the Canvas and destroys the Canvas
pub fn default_pixel_format(&self) -> PixelFormatEnum
[src]
pub fn texture_creator(&self) -> TextureCreator<WindowContext>
[src]
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> Canvas<T> where
T: RenderTarget,
[src]
T: RenderTarget,
pub fn render_target_supported(&self) -> bool
[src]
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>),
[src]
&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
Texture
s, 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<'a, 's, I, F, U>(
&mut self,
textures: I,
f: F
) -> Result<(), TargetRenderError> where
'a: 's,
F: for<'r> FnMut(&'r mut Canvas<T>, &U),
I: Iterator<Item = &'s (&'a mut Texture, U)>,
U: 's,
[src]
&mut self,
textures: I,
f: F
) -> Result<(), TargetRenderError> where
'a: 's,
F: for<'r> FnMut(&'r mut Canvas<T>, &U),
I: Iterator<Item = &'s (&'a mut Texture, U)>,
U: 's,
impl<T> Canvas<T> where
T: RenderTarget,
[src]
T: RenderTarget,
Drawing methods
pub fn raw(&self) -> *mut SDL_Renderer
[src]
pub fn set_draw_color<C>(&mut self, color: C) where
C: Into<Color>,
[src]
C: Into<Color>,
Sets the color used for drawing operations (Rect, Line and Clear).
pub fn draw_color(&self) -> Color
[src]
Gets the color used for drawing operations (Rect, Line and Clear).
pub fn set_blend_mode(&mut self, blend: BlendMode)
[src]
Sets the blend mode used for drawing operations (Fill and Line).
pub fn blend_mode(&self) -> BlendMode
[src]
Gets the blend mode used for drawing operations.
pub fn clear(&mut self)
[src]
Clears the current rendering target with the drawing color.
pub fn present(&mut self)
[src]
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>
[src]
Gets the output size of a rendering context.
pub fn set_logical_size(
&mut self,
width: u32,
height: u32
) -> Result<(), IntegerOrSdlError>
[src]
&mut self,
width: u32,
height: u32
) -> Result<(), IntegerOrSdlError>
Sets a device independent resolution for rendering.
pub fn logical_size(&self) -> (u32, u32)
[src]
Gets device independent resolution for rendering.
pub fn set_viewport<R>(&mut self, rect: R) where
R: Into<Option<Rect>>,
[src]
R: Into<Option<Rect>>,
Sets the drawing area for rendering on the current target.
pub fn viewport(&self) -> Rect
[src]
Gets the drawing area for the current target.
pub fn set_clip_rect<R>(&mut self, rect: R) where
R: Into<Option<Rect>>,
[src]
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>
[src]
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>
[src]
Sets the drawing scale for rendering on the current target.
pub fn scale(&self) -> (f32, f32)
[src]
Gets the drawing scale for the current target.
pub fn draw_point<P>(&mut self, point: P) -> Result<(), String> where
P: Into<Point>,
[src]
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]>,
[src]
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>,
[src]
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]>,
[src]
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>
[src]
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>
[src]
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>>,
[src]
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)
pub fn fill_rects(&mut self, rects: &[Rect]) -> Result<(), String>
[src]
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>>,
[src]
&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.
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
P: Into<Option<Point>>,
R1: Into<Option<Rect>>,
R2: Into<Option<Rect>>,
[src]
&mut self,
texture: &Texture,
src: R1,
dst: R2,
angle: f64,
center: P,
flip_horizontal: bool,
flip_vertical: bool
) -> Result<(), String> where
P: Into<Option<Point>>,
R1: Into<Option<Rect>>,
R2: Into<Option<Rect>>,
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.
pub fn read_pixels<R>(
&self,
rect: R,
format: PixelFormatEnum
) -> Result<Vec<u8>, String> where
R: Into<Option<Rect>>,
[src]
&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.
pub fn create_texture<F>(
&self,
format: F,
access: TextureAccess,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
[src]
&self,
format: F,
access: TextureAccess,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
Creates a texture for a rendering context.
If format is None
, the format will be the one the parent Window or Surface uses.
If format is Some(pixel_format)
created with the specified format if possible. If the PixelFormat is not supported, this
will return an error.
You should prefer the default format if possible to have performance gains and to avoid
unsupported Pixel Formats that can cause errors. However, be careful with the default
PixelFormat
if you want to create transparent textures.
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature,
because lifetimes otherwise prevent Canvas
from creating and accessing Texture
s at the
same time.
pub fn create_texture_static<F>(
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
[src]
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
Shorthand for create_texture(format, TextureAccess::Static, width, height)
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature.
pub fn create_texture_streaming<F>(
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
[src]
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
Shorthand for create_texture(format, TextureAccess::Streaming, width, height)
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature.
pub fn create_texture_target<F>(
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
[src]
&self,
format: F,
width: u32,
height: u32
) -> Result<Texture, TextureValueError> where
F: Into<Option<PixelFormatEnum>>,
Shorthand for create_texture(format, TextureAccess::Target, width, height)
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature.
pub fn create_texture_from_surface<S>(
&self,
surface: S
) -> Result<Texture, TextureValueError> where
S: AsRef<SurfaceRef>,
[src]
&self,
surface: S
) -> Result<Texture, TextureValueError> where
S: AsRef<SurfaceRef>,
Creates a texture from an existing surface.
Remarks
The access hint for the created texture is TextureAccess::Static
.
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature.
pub unsafe fn raw_create_texture(&self, raw: *mut SDL_Texture) -> Texture
[src]
Create a texture from its raw SDL_Texture
. Should be used with care.
Notes
Note that this method is only accessible in Canvas with the unsafe_textures
feature.
Methods from Deref<Target = RendererContext<<T as RenderTarget>::Context>>
pub fn info(&self) -> RendererInfo
[src]
Gets information about the rendering context.
pub fn raw(&self) -> *mut SDL_Renderer
[src]
Gets the raw pointer to the SDL_Renderer
Trait Implementations
impl<T> Deref for Canvas<T> where
T: RenderTarget,
[src]
T: RenderTarget,
type Target = RendererContext<<T as RenderTarget>::Context>
The resulting type after dereferencing.
fn deref(&self) -> &RendererContext<<T as RenderTarget>::Context>
[src]
Auto Trait Implementations
impl<T> !RefUnwindSafe for Canvas<T>
impl<T> !Send for Canvas<T>
impl<T> !Sync for Canvas<T>
impl<T> Unpin for Canvas<T> where
T: Unpin,
T: Unpin,
impl<T> !UnwindSafe for Canvas<T>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<R> Resource for R where
R: 'static + Any,
[src]
R: 'static + Any,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,