Struct FrameBuilder

pub struct FrameBuilder { /* private fields */ }

A full frame builder.

Implementations

impl FrameBuilder

pub fn new( render_widgets: Arc<RenderUpdates>, render_update_widgets: Arc<RenderUpdates>, frame_id: FrameId, root_id: WidgetId, root_bounds: &WidgetBoundsInfo, info_tree: &WidgetInfoTree, renderer: Option<ViewRenderer>, scale_factor: Factor, default_font_aa: FontAntiAliasing, ) -> FrameBuilder

New builder.

• render_widgets - External render requests.

• render_update_widgets - External render update requests.

• frame_id - Id of the new frame.

• root_id - Id of the window root widget.

• root_bounds - Root widget bounds info.

• info_tree - Info tree of the last frame.

• renderer - Connection to the renderer that will render the frame, is None in renderless mode.

• scale_factor - Scale factor that will be used to render the frame, usually the scale factor of the screen the window is at.

• default_font_aa - Fallback font anti-aliasing used when the default value is requested. because WebRender does not let us change the initial clear color.

pub fn new_renderless( render_widgets: Arc<RenderUpdates>, render_update_widgets: Arc<RenderUpdates>, frame_id: FrameId, root_id: WidgetId, root_bounds: &WidgetBoundsInfo, info_tree: &WidgetInfoTree, scale_factor: Factor, default_font_aa: FontAntiAliasing, ) -> FrameBuilder

new with only the inputs required for renderless mode.

pub fn scale_factor(&self) -> Factor

Pixel scale factor used by the renderer.

All layout values are scaled by this factor in the renderer.

pub fn is_renderless(&self) -> bool

If is building a frame for a headless and renderless window.

In this mode only the meta and layout information will be used as a frame.

pub fn set_clear_color(&mut self, color: Rgba)

Set the color used to clear the pixel frame before drawing this frame.

Note the default clear color is rgba(0, 0, 0, 0), and it is not retained, a property that sets the clear color must set it every render.

Note that the clear color is always rendered first before all other layers, if more then one layer sets the clear color only the value set on the top-most layer is used.

pub fn renderer(&self) -> Option<&ViewRenderer>

Connection to the renderer that will render this frame.

Returns None when in renderless mode.

pub fn frame_id(&self) -> FrameId

Id of the new frame.

pub fn widget_id(&self) -> WidgetId

Id of the current widget context.

pub fn transform(&self) -> &PxTransform

Current transform.

pub fn is_hit_testable(&self) -> bool

Returns true if hit-testing is enabled in the widget context, if false methods that push a hit-test silently skip.

This can be set to false in a context using with_hit_tests_disabled.

pub fn is_visible(&self) -> bool

Returns true if display items are actually generated, if false only transforms and hit-test are rendered.

pub fn auto_hit_test(&self) -> bool

Returns true if hit-tests are automatically pushed by push_* methods.

Note that hit-tests are only added if is_hit_testable is true.

pub fn with_default_font_aa( &mut self, aa: FontAntiAliasing, render: impl FnOnce(&mut FrameBuilder), )

Runs render with aa used as the default text anti-aliasing mode.

pub fn with_hit_tests_disabled( &mut self, render: impl FnOnce(&mut FrameBuilder), )

Runs render with hit-tests disabled, inside render is_hit_testable is false, after it is the current value.

pub fn with_auto_hit_test( &mut self, auto_hit_test: bool, render: impl FnOnce(&mut FrameBuilder), )

Runs render with auto_hit_test set to a value for the duration of the render call.

If this is used, FrameUpdate::with_auto_hit_test must also be used.

pub fn auto_hide_rect(&self) -> Rect<Px, Px>

Current culling rect, widgets with outer-bounds that don’t intersect this rect are rendered hidden.

pub fn with_auto_hide_rect( &mut self, auto_hide_rect: Rect<Px, Px>, render: impl FnOnce(&mut FrameBuilder), )

Runs render and hide all widgets with outer-bounds that don’t intersect with the auto_hide_rect.

pub fn push_widget(&mut self, render: impl FnOnce(&mut FrameBuilder))

Start a new widget outer context, this sets is_outer to true until an inner call to push_inner, during this period properties can configure the widget stacking context and actual rendering and transforms are discouraged.

If the widget has been rendered before, render was not requested for it and can_reuse allows reuse, the render closure is not called, an only a reference to the widget range in the previous frame is send.

If the widget is collapsed during layout it is not rendered. See WidgetLayout::collapse for more details.

pub fn can_reuse(&self) -> bool

If previously generated display list items are available for reuse.

If false widgets must do a full render using push_widget even if they did not request a render.

pub fn with_no_reuse(&mut self, render: impl FnOnce(&mut FrameBuilder))

Calls render with can_reuse set to false.

pub fn push_reuse( &mut self, group: &mut Option<ReuseRange>, generate: impl FnOnce(&mut FrameBuilder), )

If group has a range and can_reuse a reference to the items is added, otherwise generate is called and any display items generated by it are tracked in group.

Note that hit-test items are not part of group, only display items are reused here, hit-test items for a widget are only reused if the entire widget is reused in push_widget. This method is recommended for widgets that render a large volume of display data that is likely to be reused even when the widget itself is not reused, an example is a widget that renders text and a background, the entire widget is invalidated when the background changes, but the text is the same, so placing the text in a reuse group avoids having to upload all glyphs again.

pub fn hide(&mut self, render: impl FnOnce(&mut FrameBuilder))

Calls render with is_visible set to false.

Nodes that set the visibility to Hidden must render using this method and update using the FrameUpdate::hidden method.

Note that for Collapsed the widget is automatically not rendered if WidgetLayout::collapse or other related collapse method was already called for it.

pub fn with_backface_visibility( &mut self, visible: bool, render: impl FnOnce(&mut FrameBuilder), )

Calls render with back face visibility set to visible.

All visual display items pushed inside render will have the visible flag.

pub fn is_outer(&self) -> bool

Returns true if the widget stacking context is still being build.

This is true when inside an push_widget call but false when inside an push_inner call.

pub fn push_inner_filter( &mut self, filter: Vec<FilterOp>, render: impl FnOnce(&mut FrameBuilder), )

Includes a widget filter and continues the render build.

This is valid only when is_outer.

When push_inner is called a stacking context is created for the widget that includes the filter.

pub fn push_inner_opacity( &mut self, bind: FrameValue<f32>, render: impl FnOnce(&mut FrameBuilder), )

Includes a widget opacity filter and continues the render build.

This is valid only when is_outer.

When push_inner is called a stacking context is created for the widget that includes the opacity filter.

pub fn push_inner_backdrop_filter( &mut self, filter: Vec<FilterOp>, render: impl FnOnce(&mut FrameBuilder), )

Include a widget backdrop filter and continue the render build.

This is valid only when is_outer.

When push_inner is called the widget are is first filled with the backdrop filters.

pub fn push_inner_blend( &mut self, mode: MixBlendMode, render: impl FnOnce(&mut FrameBuilder), )

Sets the widget blend mode and continue the render build.

This is valid only when is_outer.

When push_inner is called the mode is used to blend with the parent content.

pub fn push_child( &mut self, offset: Vector2D<Px, Px>, render: impl FnOnce(&mut FrameBuilder), )

Pre-starts the scope of a widget with offset set for the inner reference frame. The render closure must call push_widget before attempting to render.

Nodes that use WidgetLayout::with_child to optimize reference frames must use this method when a reference frame was not created during render.

Nodes that use this must also use FrameUpdate::with_child.

pub fn push_inner_transform( &mut self, transform: &PxTransform, render: impl FnOnce(&mut FrameBuilder), )

Include the transform on the widget inner reference frame.

This is valid only when is_outer.

When push_inner is called a reference frame is created for the widget that applies the layout transform then the transform.

pub fn push_inner( &mut self, layout_translation_key: FrameValueKey<PxTransform>, layout_translation_animating: bool, render: impl FnOnce(&mut FrameBuilder), )

Push the widget reference frame and stacking context then call render inside of it.

If layout_translation_animating is false the view-process can still be updated using FrameUpdate::update_inner, but a full webrender frame will be generated for each update, if is true webrender frame updates are used, but webrender skips some optimizations, such as auto-merging transforms. When in doubt setting this to true is better than false as a webrender frame update is faster than a full frame, and the transform related optimizations don’t gain much.

pub fn is_inner(&self) -> bool

Returns true if the widget reference frame and stacking context is pushed and now is time for rendering the widget.

This is true when inside a push_inner call but false when inside a push_widget call.

pub fn hit_test(&mut self) -> HitTestBuilder<'_>

Gets the inner-bounds hit-test shape builder.

Note that all hit-test is clipped by the inner-bounds, the shapes pushed with this builder only refine the widget inner-bounds, shapes out-of-bounds are clipped.

pub fn push_clip_rect( &mut self, clip_rect: Rect<Px, Px>, clip_out: bool, hit_test: bool, render: impl FnOnce(&mut FrameBuilder), )

Calls render with a new clip context that adds the clip_rect.

If clip_out is true only pixels outside the rect are visible. If hit_test is true the hit-test shapes rendered inside render are also clipped.

Note that hit-test will be generated if hit_test or auto_hit_test is true.

pub fn push_clip_rounded_rect( &mut self, clip_rect: Rect<Px, Px>, corners: CornerRadius2D<Px, Px>, clip_out: bool, hit_test: bool, render: impl FnOnce(&mut FrameBuilder), )

Calls render with a new clip context that adds the clip_rect with rounded corners.

If clip_out is true only pixels outside the rounded rect are visible. If hit_test is true the hit-test shapes rendered inside render are also clipped.

Note that hit-test will be generated if hit_test or auto_hit_test is true.

pub fn push_clips( &mut self, clips: impl FnOnce(&mut ClipBuilder<'_>), render: impl FnOnce(&mut FrameBuilder), )

Calls clips to push multiple clips that define a new clip context, then calls render in the clip context.

pub fn push_mask( &mut self, image: &impl Img, rect: Rect<Px, Px>, render: impl FnOnce(&mut FrameBuilder), )

Push an image mask that affects all visual rendered by render.

pub fn push_reference_frame( &mut self, key: ReferenceFrameId, transform: FrameValue<PxTransform>, is_2d_scale_translation: bool, hit_test: bool, render: impl FnOnce(&mut FrameBuilder), )

Calls render inside a new reference frame transformed by transform.

The is_2d_scale_translation flag optionally marks the transform as only ever having a simple 2D scale or translation, allowing for webrender optimizations.

If hit_test is true the hit-test shapes rendered inside render for the same widget are also transformed.

Note that auto_hit_test overwrites hit_test if it is true.

pub fn push_filter( &mut self, blend: MixBlendMode, filter: &Vec<FilterOp>, render: impl FnOnce(&mut FrameBuilder), )

Calls render with added blend and filter stacking context.

Note that this introduces a new stacking context, you can use the push_inner_blend and push_inner_filter methods to add to the widget stacking context.

pub fn push_opacity( &mut self, bind: FrameValue<f32>, render: impl FnOnce(&mut FrameBuilder), )

Calls render with added opacity stacking context.

Note that this introduces a new stacking context, you can use the push_inner_opacity method to add to the widget stacking context.

pub fn push_backdrop_filter( &mut self, clip_rect: Rect<Px, Px>, filter: &Vec<FilterOp>, )

Push a standalone backdrop filter.

The filter will apply to all pixels already rendered in clip_rect.

Note that you can add backdrop filters to the widget using the push_inner_backdrop_filter method.

pub fn push_border( &mut self, bounds: Rect<Px, Px>, widths: SideOffsets2D<Px, Px>, sides: BorderSides, radius: CornerRadius2D<Px, Px>, )

Push a border.

pub fn push_border_image( &mut self, bounds: Rect<Px, Px>, widths: SideOffsets2D<Px, Px>, slice: SideOffsets2D<Px, Px>, fill: bool, repeat_horizontal: RepeatMode, repeat_vertical: RepeatMode, image: &impl Img, rendering: ImageRendering, )

Push a nine-patch border with image source.

pub fn push_border_linear_gradient( &mut self, bounds: Rect<Px, Px>, widths: SideOffsets2D<Px, Px>, slice: SideOffsets2D<Px, Px>, fill: bool, repeat_horizontal: RepeatMode, repeat_vertical: RepeatMode, line: PxLine, stops: &[GradientStop], extend_mode: ExtendMode, )

Push a nine-patch border with linear gradient source.

pub fn push_border_radial_gradient( &mut self, bounds: Rect<Px, Px>, widths: SideOffsets2D<Px, Px>, slice: SideOffsets2D<Px, Px>, fill: bool, repeat_horizontal: RepeatMode, repeat_vertical: RepeatMode, center: Point2D<Px, Px>, radius: Size2D<Px, Px>, stops: &[GradientStop], extend_mode: ExtendMode, )

Push a nine-patch border with radial gradient source.

pub fn push_border_conic_gradient( &mut self, bounds: Rect<Px, Px>, widths: SideOffsets2D<Px, Px>, slice: SideOffsets2D<Px, Px>, fill: bool, repeat_horizontal: RepeatMode, repeat_vertical: RepeatMode, center: Point2D<Px, Px>, angle: AngleRadian, stops: &[GradientStop], extend_mode: ExtendMode, )

Push a nine-patch border with conic gradient source.

pub fn push_text( &mut self, clip_rect: Rect<Px, Px>, glyphs: &[GlyphInstance], font: &impl Font, color: FrameValue<Rgba>, synthesis: FontSynthesis, aa: FontAntiAliasing, )

Push a text run.

pub fn push_image( &mut self, clip_rect: Rect<Px, Px>, img_size: Size2D<Px, Px>, tile_size: Size2D<Px, Px>, tile_spacing: Size2D<Px, Px>, image: &impl Img, rendering: ImageRendering, )

Push an image.

pub fn push_color(&mut self, clip_rect: Rect<Px, Px>, color: FrameValue<Rgba>)

Push a color rectangle.

The color can be bound and updated using FrameUpdate::update_color, note that if the color binding or update is flagged as animating webrender frame updates are used when color updates are send, but webrender disables some caching for the entire clip_rect region, this can have a big performance impact in RenderMode::Software if a large part of the screen is affected, as the entire region is redraw every full frame even if the color did not actually change.

pub fn push_linear_gradient( &mut self, clip_rect: Rect<Px, Px>, line: PxLine, stops: &[GradientStop], extend_mode: ExtendMode, tile_origin: Point2D<Px, Px>, tile_size: Size2D<Px, Px>, tile_spacing: Size2D<Px, Px>, )

Push a repeating linear gradient rectangle.

The gradient fills the tile_size, the tile is repeated to fill the rect. The extend_mode controls how the gradient fills the tile after the last color stop is reached.

The gradient stops must be normalized, first stop at 0.0 and last stop at 1.0, this is asserted in debug builds.

pub fn push_radial_gradient( &mut self, clip_rect: Rect<Px, Px>, center: Point2D<Px, Px>, radius: Size2D<Px, Px>, stops: &[GradientStop], extend_mode: ExtendMode, tile_origin: Point2D<Px, Px>, tile_size: Size2D<Px, Px>, tile_spacing: Size2D<Px, Px>, )

Push a repeating radial gradient rectangle.

The gradient fills the tile_size, the tile is repeated to fill the rect. The extend_mode controls how the gradient fills the tile after the last color stop is reached.

The center point is relative to the top-left of the tile, the radius is the distance between the first and last color stop in both directions and must be a non-zero positive value.

The gradient stops must be normalized, first stop at 0.0 and last stop at 1.0, this is asserted in debug builds.

pub fn push_conic_gradient( &mut self, clip_rect: Rect<Px, Px>, center: Point2D<Px, Px>, angle: AngleRadian, stops: &[GradientStop], extend_mode: ExtendMode, tile_origin: Point2D<Px, Px>, tile_size: Size2D<Px, Px>, tile_spacing: Size2D<Px, Px>, )

Push a repeating conic gradient rectangle.

The gradient fills the tile_size, the tile is repeated to fill the rect. The extend_mode controls how the gradient fills the tile after the last color stop is reached.

The gradient stops must be normalized, first stop at 0.0 and last stop at 1.0, this is asserted in debug builds.

pub fn push_line( &mut self, clip_rect: Rect<Px, Px>, orientation: LineOrientation, color: Rgba, style: LineStyle, )

Push a styled vertical or horizontal line.

pub fn push_debug_dot_overlay( &mut self, offset: Point2D<Px, Px>, color: impl Into<Rgba>, )

Record the offset in the current context and push_debug_dot after render.

pub fn push_debug_dot( &mut self, offset: Point2D<Px, Px>, color: impl Into<Rgba>, )

Push a color dot to mark the offset.

The dot is a circle of the color highlighted by an white outline and shadow.

pub fn push_extension_context_raw( &mut self, extension_id: ApiExtensionId, payload: ApiExtensionPayload, render: impl FnOnce(&mut FrameBuilder), )

Push a custom display extension context with custom encoding.

pub fn push_extension_context<T>( &mut self, extension_id: ApiExtensionId, payload: &T, render: impl FnOnce(&mut FrameBuilder), )

where T: Serialize,

Push a custom display extension context that wraps render.

pub fn push_extension_item_raw( &mut self, extension_id: ApiExtensionId, payload: ApiExtensionPayload, )

Push a custom display extension item with custom encoding.

pub fn push_extension_item<T>( &mut self, extension_id: ApiExtensionId, payload: &T, )

where T: Serialize,

Push a custom display extension item.

pub fn parallel_split(&self) -> ParallelBuilder<FrameBuilder>

Create a new display list builder that can be built in parallel and merged back onto this one using parallel_fold.

Note that split list must be folded before any current open reference frames, stacking contexts or clips are closed in this list.

pub fn parallel_fold(&mut self, split: ParallelBuilder<FrameBuilder>)

Collect display list from split into self.

pub fn with_nested_window( &mut self, render_widgets: Arc<RenderUpdates>, render_update_widgets: Arc<RenderUpdates>, root_id: WidgetId, root_bounds: &WidgetBoundsInfo, info_tree: &WidgetInfoTree, default_font_aa: FontAntiAliasing, render: impl FnOnce(&mut FrameBuilder), )

Calls render to render a separate nested window on this frame.

pub fn render_widgets(&self) -> &Arc<RenderUpdates>

External render requests for this frame.

pub fn render_update_widgets(&self) -> &Arc<RenderUpdates>

External render update requests for this frame.

pub fn finalize(self, info_tree: &WidgetInfoTree) -> BuiltFrame

Finalizes the build.