pub struct Canvas { /* private fields */ }
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 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
sourceimpl Canvas
impl Canvas
sourcepub fn new(ctx: &mut Context, width: i32, height: i32) -> Result<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
TextureFormat::Rgba8
is used for the underlying texture
Errors
TetraError::PlatformError
will be returned if the underlying graphics API encounters an error.
sourcepub fn builder(width: i32, height: i32) -> CanvasBuilder
pub fn builder(width: i32, height: i32) -> CanvasBuilder
Creates a new canvas builder, which can be used to create a canvas with more advanced configurations, such as multisampling or stencil buffers.
sourcepub fn draw<P>(&self, ctx: &mut Context, params: P) where
P: Into<DrawParams>,
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).
sourcepub fn filter_mode(&self) -> FilterMode
pub fn filter_mode(&self) -> FilterMode
Returns the filter mode being used by the canvas.
sourcepub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
Sets the filter mode that should be used by the canvas.
sourcepub fn get_data(&self, ctx: &mut Context) -> ImageData
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.
sourcepub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
pub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
Writes pixel data to a specified region of the canvas.
The data will be interpreted based on the TextureFormat
of the canvas’
underlying texture.
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.
sourcepub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result
pub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result
Overwrites the entire canvas with new pixel data.
The data will be interpreted based on the TextureFormat
of the canvas’
underlying texture.
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.
sourcepub fn texture(&self) -> &Texture
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 StructuralPartialEq for Canvas
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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more