Struct RenderContext 

pub struct RenderContext {
    pub(crate) width: u16,
    pub(crate) height: u16,
    pub(crate) state: RenderState,
    root_transforms: RootTransforms,
    pub(crate) mask: Option<Mask>,
    pub(crate) temp_path: BezPath,
    pub(crate) aliasing_threshold: Option<u8>,
    pub(crate) encoded_paints: Vec<EncodedPaint>,
    pub(crate) filter: Option<Filter>,
    pub(crate) render_settings: RenderSettings,
    dispatcher: Box<dyn Dispatcher>,
}

A render context for CPU-based 2D graphics rendering.

This is the main entry point for drawing operations. It maintains the current rendering state (transforms, paint, stroke, etc.) and dispatches drawing commands to the underlying rasterization engine.

Fields

width: u16

Width of the render target in pixels.

height: u16

Height of the render target in pixels.

state: RenderState

The current rendering state.

root_transforms: RootTransforms

mask: Option<Mask>

The current mask in place.

temp_path: BezPath

Temporary path buffer to avoid repeated allocations.

aliasing_threshold: Option<u8>

Optional threshold for aliasing.

encoded_paints: Vec<EncodedPaint>

filter: Option<Filter>

render_settings: RenderSettings

dispatcher: Box<dyn Dispatcher>

Implementations

impl RenderContext

pub fn new(width: u16, height: u16) -> Self

Create a new render context with the given width and height in pixels.

pub fn new_with(width: u16, height: u16, settings: RenderSettings) -> Self

Create a new render context with specific settings.

fn transforms(&self) -> &Transforms

fn transforms_mut(&mut self) -> &mut Transforms

fn encode_current_paint(&mut self) -> Paint

pub fn fill_path(&mut self, path: &BezPath)

Fill a path.

pub fn stroke_path(&mut self, path: &BezPath)

Stroke a path.

pub fn fill_rect(&mut self, rect: &Rect)

Fill a rectangle.

pub fn stroke_rect(&mut self, rect: &Rect)

Stroke a rectangle.

fn rect_to_temp_path(&mut self, rect: &Rect)

pub fn fill_blurred_rounded_rect( &mut self, rect: &Rect, radius: f32, std_dev: f32, invert: bool, )

Fill a blurred rectangle with the given corner radius and standard deviation.

When invert is true, the inverse (1 - alpha) of the blur coverage is painted: the paint is fully opaque outside the blurred rectangle and fades to transparent inside it. This can be used to implement inset box shadows.

Note that this only works properly if the current paint is set to a solid color. If not, it will fall back to using black as the fill color.

pub fn glyph_run<'a>( &'a mut self, resources: &'a mut Resources, font: &FontData, ) -> GlyphRunBuilder<'a>

Creates a builder for drawing a run of glyphs that have the same attributes.

pub fn push_layer( &mut self, clip_path: Option<&BezPath>, blend_mode: Option<BlendMode>, opacity: Option<f32>, mask: Option<Mask>, filter: Option<Filter>, )

Push a new layer with the given properties.

Note that the mask, if provided, needs to have the same size as the render context. Otherwise, it will be ignored. In addition to that, the mask will not be affected by the current transformation matrix in place.

Panics

Panics if filter is provided when this context uses multi-threaded rendering.

pub fn push_clip_layer(&mut self, path: &BezPath)

Push a new clip layer.

See the explanation in the clipping example for how this method differs from push_clip_path.

pub fn push_blend_layer(&mut self, blend_mode: BlendMode)

Push a new blend layer.

pub fn push_opacity_layer(&mut self, opacity: f32)

Push a new opacity layer.

pub fn push_mask_layer(&mut self, mask: Mask)

Push a new mask layer. The mask needs to have the same dimensions as the render context. The mask will not be affected by the current transform in place.

See the explanation in the masking example for how this method differs from set_mask.

pub fn push_filter_layer(&mut self, filter: Filter)

Push a filter layer that affects all subsequent drawing operations.

WARNING: Note that filters are currently incomplete and experimental. In particular, they will lead to a panic when used in combination with multi-threaded rendering.

Panics

Panics when this context uses multi-threaded rendering.

pub fn set_aliasing_threshold(&mut self, aliasing_threshold: Option<u8>)

Set the aliasing threshold.

If set to None (which is the recommended option in nearly all cases), anti-aliasing will be applied.

If instead set to some value, then a pixel will be fully painted if the coverage is bigger than the threshold (between 0 and 255), otherwise it will not be painted at all.

Note that there is no performance benefit to disabling anti-aliasing and this functionality is simply provided for compatibility.

pub fn pop_layer(&mut self)

Pop the last-pushed layer.

pub fn set_stroke(&mut self, stroke: Stroke)

Set the current stroke.

pub fn stroke(&self) -> &Stroke

Get the current stroke.

pub(crate) fn stroke_mut(&mut self) -> &mut Stroke

Get a mutable reference to the current stroke.

pub fn set_paint(&mut self, paint: impl Into<PaintType>)

Set the current paint.

If the paint is an image with ImageSource::OpaqueId, it will be resolved to the corresponding pixmap at rasterization time. Make sure to register images with Resources::register_image first.

pub fn paint(&self) -> &PaintType

Get the current paint.

pub fn set_tint(&mut self, tint: Option<Tint>)

Set the tint for subsequent image paint operations.

pub fn reset_tint(&mut self)

Clear the tint, so subsequent image paints are drawn without tinting.

pub fn set_blend_mode(&mut self, blend_mode: BlendMode)

Set the blend mode that should be used when drawing objects.

pub fn blend_mode(&self) -> BlendMode

Get the currently active blend mode.

pub fn set_paint_transform(&mut self, paint_transform: Affine)

Set the current paint transform.

The paint transform is applied to the paint after the transform of the geometry the paint is drawn in, i.e., the paint transform is applied after the global transform. This allows transforming the paint independently from the drawn geometry.

pub fn paint_transform(&self) -> &Affine

Get the current paint transform.

pub fn reset_paint_transform(&mut self)

Reset the current paint transform.

pub fn set_fill_rule(&mut self, fill_rule: Fill)

Set the current fill rule.

pub fn set_mask(&mut self, mask: Mask)

Set the mask to use for path-painting operations. The mask needs to have the same dimensions as the render context. The mask will not be affected by the current transform in place.

See the explanation in the masking example for how this method differs from push_mask_layer.

pub fn reset_mask(&mut self)

Reset the mask that is used for path-painting operations.

pub fn fill_rule(&self) -> &Fill

Get the current fill rule.

pub fn set_transform(&mut self, transform: Affine)

Set the current transform.

pub fn transform(&self) -> &Affine

Get the current transform.

pub fn reset_transform(&mut self)

Reset the current transform.

pub fn set_filter_effect(&mut self, filter: Filter)

Apply filter to the current paint (affects next drawn elements).

This sets a filter that will be applied to the next drawn element. To apply a filter to multiple elements, use push_filter_layer instead.

Panics

When this context uses multi-threaded rendering.

pub fn reset_filter_effect(&mut self)

Reset the current filter effect.

pub fn reset_and_resize(&mut self, width: u16, height: u16)

Reset the render context and update the scene size.

pub fn reset(&mut self)

Reset the render context.

pub fn push_clip_path(&mut self, path: &BezPath)

Push a new clip path to the clip stack.

See the explanation in the clipping example for how this method differs from push_clip_layer.

pub fn pop_clip_path(&mut self)

Pop a clip path from the clip stack.

Note that unlike push_clip_layer, it is permissible to have pending pushed clip paths before finishing the rendering operation.

pub fn flush(&mut self)

Flush any pending operations.

This is a no-op when using the single-threaded render mode, and can be ignored. For multi-threaded rendering, you have to call this before rasterizing, otherwise the program will panic.

pub fn render<'a>( &self, target: impl Into<PixmapMut<'a>>, resources: &mut Resources, )

Render the current context into a target using default rasterizer settings.

See the documentation of RenderContext::render_with for more information.

pub fn render_with<'a>( &self, target: impl Into<PixmapMut<'a>>, resources: &mut Resources, settings: RasterizerSettings, )

Render the current context into a target using custom rasterizer settings.

See the documentation of RasterizerSettings to understand the tunable parameters for rasterization.

There is an important note to make about render sizes. RenderContext can be configured with a specific width/height, but so can Pixmap. In the vast majority of cases, you will simply want to configure them both to have the same size. However, it is very much possible for them to have different sizes, which can be useful in certain situations. In principle, the size that you specify when creating a RenderContext defines the bound of the scene itself. Any content that is to the top/left of (0, 0) and to the right/bottom of (width/height) will be removed. However, the offset in RasterizerSettings as well as the width/height of the PixmapMut define at which location the scene will be rasterized into, and allows for further clipping certain parts of the scene away. The semantics are defined as follows:

1. RasterizerSettings::offset defines the where the top-left corner will be positioned on the pixmap, assuming a y-down coordinate system. In most cases (0, 0) will be the appropriate choice, but other values are certainly sensible. For example, if you want to implement a custom glyph-atlas, you can construct the scene assuming (0, 0) as the origin and then position the glyphs at rasterization time using this feature.

2. In case the pixmap width/height is larger than the offset plus the width/height of the RenderContext, any remaining rows/columns are simply treated as padding (however, when using CompositeMode::Replace, then the whole destination pixmap will be cleared, not just the area covered by the scene). One potential reason for doing this is that certain platforms, for example macOS, require a specific byte stride for buffers. For example, let’s say that a byte stride of 128 is imposed by the platform, but the actual size of the scene you are drawing is only 20x20. In this case, you can create a pixmap of size 32x20, and the last 12 columns are essentially treated as padding.

3. In case the width/height of the pixmap is smaller than the offset + width/height of the scene, then anything that exceeds the pixmap boundaries is simply cut off. This can be useful if for some reason you only want to rasterize a small cut-out of the original scene.

pub fn width(&self) -> u16

Return the width of the scene.

pub fn height(&self) -> u16

Return the height of the scene.

pub fn render_settings(&self) -> &RenderSettings

Return the render settings used by the RenderContext.

fn with_optional_filter<F>(&mut self, f: F)

where F: FnMut(&mut Self),

Execute a drawing operation, optionally wrapping it in a filter layer.

pub fn take_current_state(&mut self) -> RenderState

Take current rendering state and reset the existing state to its default.

pub fn save_current_state(&mut self) -> RenderState

Save a copy of the current rendering state.

pub fn restore_state(&mut self, state: RenderState)

Restore rendering state.

pub fn is_multi_threaded(&self) -> bool

Whether rendering is currently configured to run in multi-threaded mode.

Trait Implementations

impl Debug for RenderContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DrawSink for RenderContext

fn set_transform(&mut self, t: Affine)

Set the current transform.

fn set_paint(&mut self, paint: AtlasPaint)

Set the current paint.

fn set_paint_transform(&mut self, t: Affine)

Set the paint transform.

fn fill_path(&mut self, path: &BezPath)

Fill a path with the current paint and transform.

fn fill_rect(&mut self, rect: &Rect)

Fill a rectangle with the current paint and transform.

fn push_clip_layer(&mut self, clip: &BezPath)

Push a clip layer defined by a path.

fn push_clip_path(&mut self, clip: &BezPath)

Push a clip path.

fn push_blend_layer(&mut self, blend_mode: BlendMode)

Push a blend/compositing layer.

fn pop_layer(&mut self)

Pop the most recent clip or blend layer.

fn pop_clip_path(&mut self)

Pop the most recent clip path.

fn width(&self) -> u16

Width of the surface.

fn height(&self) -> u16

Height of the surface.

impl GlyphRenderer for RenderContext

type SavedState = RenderState

The type of state used by the renderer.

fn save_state(&mut self) -> Self::SavedState

Save the current state.

fn restore_state(&mut self, state: Self::SavedState)

Restore the current state.

fn stroke_path(&mut self, path: &BezPath)

Stroke a path with the current paint and stroke settings.

fn set_paint_image(&mut self, image: Image)

Set the current paint to an image.

fn set_tint(&mut self, tint: Option<Tint>)

Set the tint for subsequent image draws.

fn get_context_color(&self) -> AlphaColor<Srgb>

Get the context color from the renderer’s current paint, used for resolving the context-dependent colors of COLR glyphs.

fn current_paint(&self) -> &PaintType

Get the currently active paint.

fn atlas_image_source(&self, atlas_slot: &AtlasSlot) -> ImageSource

Construct the ImageSource for sampling a cached glyph from the atlas.

fn atlas_paint_transform(&self, atlas_slot: &AtlasSlot) -> Affine

Compute the paint transform for sampling a cached glyph from the atlas.