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 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
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.
Creates a new canvas builder, which can be used to create a canvas with multisampling and/or additional buffers.
👎 Deprecated since 0.6.4: use Canvas::builder instead
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.
Draws the canvas to the screen (or to another canvas, if one is enabled).
Returns the filter mode being used by the canvas.
Sets the filter mode that should be used by the canvas.
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.
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.
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.
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
Auto Trait Implementations
impl !RefUnwindSafe for Canvas
impl !UnwindSafe for Canvas
Blanket Implementations
Mutably borrows from an owned value. Read more