Struct tetra::graphics::Canvas [−][src]
pub struct Canvas { /* fields omitted */ }
Expand description
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 a relatively expensive operation. If you can, store them in your
State
struct rather than recreating them each frame.
Cloning a Canvas
is a very cheap operation, as the underlying data is shared between the
original instance and the clone via reference-counting.
This does mean, however, that updating a Canvas
(for example, changing its filter mode) will also
update any other clones of that Canvas
.
Examples
The canvas
example demonstrates how to draw to a canvas, and then draw that canvas to
the screen.
Implementations
impl Canvas
[src]
impl Canvas
[src]pub fn new(ctx: &mut Context, width: i32, height: i32) -> Result<Canvas>
[src]
pub fn new(ctx: &mut Context, width: i32, height: i32) -> Result<Canvas>
[src]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
[src]
pub fn builder(width: i32, height: i32) -> CanvasBuilder
[src]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>
[src]
👎 Deprecated since 0.6.4: use Canvas::builder instead
pub fn multisampled(
ctx: &mut Context,
width: i32,
height: i32,
samples: u8
) -> Result<Canvas>
[src]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>,
[src]
pub fn draw<P>(&self, ctx: &mut Context, params: P) where
P: Into<DrawParams>,
[src]Draws the canvas to the screen (or to another canvas, if one is enabled).
pub fn filter_mode(&self) -> FilterMode
[src]
pub fn filter_mode(&self) -> FilterMode
[src]Returns the filter mode being used by the canvas.
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
[src]
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
[src]Sets the filter mode that should be used by the canvas.
pub fn get_data(&self, ctx: &mut Context) -> ImageData
[src]
pub fn get_data(&self, ctx: &mut Context) -> ImageData
[src]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
[src]
pub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
[src]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
[src]
pub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result
[src]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
[src]
pub fn texture(&self) -> &Texture
[src]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 StructuralPartialEq for Canvas
[src]
Auto Trait Implementations
impl !RefUnwindSafe for Canvas
impl !Send for Canvas
impl !Sync for Canvas
impl Unpin for Canvas
impl !UnwindSafe for Canvas
Blanket Implementations
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]pub fn borrow_mut(&mut self) -> &mut T
[src]
pub fn borrow_mut(&mut self) -> &mut T
[src]Mutably borrows from an owned value. Read more
impl<T> ToOwned for T where
T: Clone,
[src]
impl<T> ToOwned for T where
T: Clone,
[src]type Owned = T
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn to_owned(&self) -> T
[src]Creates owned data from borrowed data, usually by cloning. Read more
pub fn clone_into(&self, target: &mut T)
[src]
pub fn clone_into(&self, target: &mut T)
[src]🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more