pub struct SurfaceEngine { /* private fields */ }Expand description
Host-independent rendering pipeline for one Whisker surface.
This is the sole mutable owner of the paired Scene and LayoutTree.
Structural operations update both retained trees, while a successful layout
pass projects only changed rectangles into the scene journal. Clones share
unchanged state and copy each subsystem only when it is mutated.
Implementations§
Source§impl SurfaceEngine
impl SurfaceEngine
Sourcepub fn drive_layout<Provider: MeasurementProvider>(
&mut self,
root: NodeId,
viewport: LayoutSize,
environment_epoch: u64,
provider: &mut Provider,
options: LayoutOptions,
) -> Result<LayoutProgress, LayoutError<Provider::Error>>
pub fn drive_layout<Provider: MeasurementProvider>( &mut self, root: NodeId, viewport: LayoutSize, environment_epoch: u64, provider: &mut Provider, options: LayoutOptions, ) -> Result<LayoutProgress, LayoutError<Provider::Error>>
Runs layout and all immediately answerable Host measurement batches.
A synchronous Text provider normally makes this return
LayoutProgress::Complete in one call. If a provider returns
Pending, this returns blocked or provisional progress; a later
Host-to-Rust MeasurementReady
event is applied with SurfaceEngine::apply_measurement_ready before
driving layout again.
Source§impl SurfaceEngine
impl SurfaceEngine
Sourcepub fn with_protocol(surface: SurfaceId, protocol: ProtocolVersion) -> Self
pub fn with_protocol(surface: SurfaceId, protocol: ProtocolVersion) -> Self
Creates an empty pipeline using the protocol selected with its Host.
Sourcepub const fn scene(&self) -> &Scene
pub const fn scene(&self) -> &Scene
Returns the retained scene without allowing structural mutation.
Sourcepub fn layout_tree(&self) -> &LayoutTree
pub fn layout_tree(&self) -> &LayoutTree
Returns the retained layout tree without allowing structural mutation.
Sourcepub fn last_layout(&self) -> Option<&LayoutSnapshot>
pub fn last_layout(&self) -> Option<&LayoutSnapshot>
Returns the most recent successful layout snapshot.
Sourcepub const fn needs_layout(&self) -> bool
pub const fn needs_layout(&self) -> bool
Returns whether retained inputs require another layout pass.
Sourcepub fn has_pending_work(&self) -> bool
pub fn has_pending_work(&self) -> bool
Returns whether the scene has a snapshot, mutation, command, or retry.
Sourcepub fn node(&self, node: NodeId) -> Option<&SceneNode>
pub fn node(&self, node: NodeId) -> Option<&SceneNode>
Returns a retained scene node when it is live.
Sourcepub fn hit_test(
&self,
root: NodeId,
point: InputPoint,
) -> Result<Option<NodeId>, SurfaceError>
pub fn hit_test( &self, root: NodeId, point: InputPoint, ) -> Result<Option<NodeId>, SurfaceError>
Finds the visually topmost retained node at a surface-space point.
Sourcepub fn update_host_scroll_offset(
&mut self,
node: NodeId,
offset: [f32; 2],
) -> Result<(), SurfaceError>
pub fn update_host_scroll_offset( &mut self, node: NodeId, offset: [f32; 2], ) -> Result<(), SurfaceError>
Synchronizes one native scroll container’s transient logical offset.
This state participates only in Rust hit testing. It does not dirty layout or echo a frame operation back to the Host.
Sourcepub fn set_pointer_capture(
&mut self,
node: NodeId,
pointer: PointerId,
) -> Result<(), SurfaceError>
pub fn set_pointer_capture( &mut self, node: NodeId, pointer: PointerId, ) -> Result<(), SurfaceError>
Captures a pointer stream for a node.
Sourcepub fn release_pointer_capture(
&mut self,
node: NodeId,
pointer: PointerId,
) -> Result<(), SurfaceError>
pub fn release_pointer_capture( &mut self, node: NodeId, pointer: PointerId, ) -> Result<(), SurfaceError>
Releases a pointer stream previously captured by a node.
Sourcepub fn release_pointer_captures(&mut self) -> Result<(), SurfaceError>
pub fn release_pointer_captures(&mut self) -> Result<(), SurfaceError>
Releases every captured pointer.
Sourcepub fn pointer_capture_target(&self, pointer: PointerId) -> Option<NodeId>
pub fn pointer_capture_target(&self, pointer: PointerId) -> Option<NodeId>
Returns the node currently retaining one pointer capture.
Sourcepub fn set_event_mask(
&mut self,
node: NodeId,
mask: u64,
) -> Result<(), SurfaceError>
pub fn set_event_mask( &mut self, node: NodeId, mask: u64, ) -> Result<(), SurfaceError>
Replaces one node’s event subscription mask.
Sourcepub fn set_accessibility(
&mut self,
node: NodeId,
accessibility: Accessibility,
) -> Result<(), SurfaceError>
pub fn set_accessibility( &mut self, node: NodeId, accessibility: Accessibility, ) -> Result<(), SurfaceError>
Replaces one node’s common accessibility semantics.
Sourcepub fn set_property(
&mut self,
node: NodeId,
property: PropertyId,
value: WhiskerValue,
) -> Result<(), SurfaceError>
pub fn set_property( &mut self, node: NodeId, property: PropertyId, value: WhiskerValue, ) -> Result<(), SurfaceError>
Sets one typed element property in the retained scene.
Sourcepub fn clear_property(
&mut self,
node: NodeId,
property: PropertyId,
) -> Result<(), SurfaceError>
pub fn clear_property( &mut self, node: NodeId, property: PropertyId, ) -> Result<(), SurfaceError>
Clears one typed element property in the retained scene.
Sourcepub fn invoke_command(
&mut self,
node: NodeId,
command: CommandId,
arguments: WhiskerValue,
) -> Result<(), SurfaceError>
pub fn invoke_command( &mut self, node: NodeId, command: CommandId, arguments: WhiskerValue, ) -> Result<(), SurfaceError>
Queues one typed element command after preceding visual mutations.
Sourcepub fn set_hit_test(
&mut self,
node: NodeId,
behavior: HitTestBehavior,
) -> Result<(), SurfaceError>
pub fn set_hit_test( &mut self, node: NodeId, behavior: HitTestBehavior, ) -> Result<(), SurfaceError>
Replaces one node’s hit-test participation.
Sourcepub fn set_cursor(
&mut self,
node: NodeId,
cursor: Cursor,
) -> Result<(), SurfaceError>
pub fn set_cursor( &mut self, node: NodeId, cursor: Cursor, ) -> Result<(), SurfaceError>
Replaces one node’s resolved pointing-device cursor.
Sourcepub fn set_opacity(
&mut self,
node: NodeId,
opacity: f32,
) -> Result<(), SurfaceError>
pub fn set_opacity( &mut self, node: NodeId, opacity: f32, ) -> Result<(), SurfaceError>
Replaces one node’s already-resolved group opacity.
Sourcepub fn set_box_paint(
&mut self,
node: NodeId,
paint: BoxPaint,
) -> Result<(), SurfaceError>
pub fn set_box_paint( &mut self, node: NodeId, paint: BoxPaint, ) -> Result<(), SurfaceError>
Replaces one node’s resolved background, border, and radius paint.
Sourcepub fn set_text_content(
&mut self,
node: NodeId,
content: TextContent,
) -> Result<(), SurfaceError>
pub fn set_text_content( &mut self, node: NodeId, content: TextContent, ) -> Result<(), SurfaceError>
Replaces one node’s already-lowered text presentation.
Runtime-owned paint animation uses this after intrinsic measurement is complete; callers must preserve the retained payload and prepared content when changing paint-only fields.
Sourcepub fn set_text_style(
&mut self,
node: NodeId,
style: &ComputedStyle,
) -> Result<(), SurfaceError>
pub fn set_text_style( &mut self, node: NodeId, style: &ComputedStyle, ) -> Result<(), SurfaceError>
Delivers resolved inherited text style to a native text-capable element independently from plain-text child content.
Sourcepub fn set_text_style_snapshot(
&mut self,
node: NodeId,
style: TextStyleSnapshot,
) -> Result<(), SurfaceError>
pub fn set_text_style_snapshot( &mut self, node: NodeId, style: TextStyleSnapshot, ) -> Result<(), SurfaceError>
Replaces an already-lowered native text-style snapshot. Runtime-owned paint animation uses this without re-resolving inherited values.
Sourcepub fn set_transform(
&mut self,
node: NodeId,
transform: Transform,
) -> Result<(), SurfaceError>
pub fn set_transform( &mut self, node: NodeId, transform: Transform, ) -> Result<(), SurfaceError>
Replaces one node’s already-resolved transform matrix without changing its computed transform target.
Sourcepub fn create_node(
&mut self,
element_type: ElementTypeId,
style: ComputedLayoutStyle,
) -> Result<NodeId, SurfaceError>
pub fn create_node( &mut self, element_type: ElementTypeId, style: ComputedLayoutStyle, ) -> Result<NodeId, SurfaceError>
Creates one unattached node in both retained trees.
Sourcepub fn delete_node(&mut self, node: NodeId) -> Result<(), SurfaceError>
pub fn delete_node(&mut self, node: NodeId) -> Result<(), SurfaceError>
Deletes a node and its complete subtree from both retained trees.
Sourcepub fn insert_child(
&mut self,
parent: NodeId,
child: NodeId,
index: u32,
) -> Result<(), SurfaceError>
pub fn insert_child( &mut self, parent: NodeId, child: NodeId, index: u32, ) -> Result<(), SurfaceError>
Attaches an unattached child at an index in both retained trees.
Sourcepub fn remove_child(
&mut self,
parent: NodeId,
child: NodeId,
) -> Result<(), SurfaceError>
pub fn remove_child( &mut self, parent: NodeId, child: NodeId, ) -> Result<(), SurfaceError>
Detaches a direct child without deleting it.
Sourcepub fn move_child(
&mut self,
parent: NodeId,
child: NodeId,
index: u32,
) -> Result<(), SurfaceError>
pub fn move_child( &mut self, parent: NodeId, child: NodeId, index: u32, ) -> Result<(), SurfaceError>
Moves a direct child within its current parent.
Sourcepub fn update_layout_style(
&mut self,
node: NodeId,
style: ComputedLayoutStyle,
) -> Result<PropertyImpactSet, SurfaceError>
pub fn update_layout_style( &mut self, node: NodeId, style: ComputedLayoutStyle, ) -> Result<PropertyImpactSet, SurfaceError>
Replaces a node’s computed layout input and reports its impact.
Sourcepub fn update_computed_style(
&mut self,
node: NodeId,
style: &ComputedStyle,
) -> Result<PropertyImpactSet, SurfaceError>
pub fn update_computed_style( &mut self, node: NodeId, style: &ComputedStyle, ) -> Result<PropertyImpactSet, SurfaceError>
Applies every currently supported computed layout and paint value.
Sourcepub fn set_background_layers(
&mut self,
node: NodeId,
layers: Vec<BackgroundLayer>,
) -> Result<(), SurfaceError>
pub fn set_background_layers( &mut self, node: NodeId, layers: Vec<BackgroundLayer>, ) -> Result<(), SurfaceError>
Updates retained background image layers independently from computed box paint. Resource identity is assigned by the runtime boundary, not by the layout/style engine.
Sourcepub fn set_measurable(
&mut self,
node: NodeId,
measurable: bool,
) -> Result<bool, SurfaceError>
pub fn set_measurable( &mut self, node: NodeId, measurable: bool, ) -> Result<bool, SurfaceError>
Marks or unmarks a leaf as requiring intrinsic Host measurement.
Returns whether retained measurement behavior changed.
Sourcepub fn set_measurement(
&mut self,
node: NodeId,
spec: Option<MeasurementSpec>,
) -> Result<bool, SurfaceError>
pub fn set_measurement( &mut self, node: NodeId, spec: Option<MeasurementSpec>, ) -> Result<bool, SurfaceError>
Registers or clears Host-backed intrinsic measurement for one leaf.
Element modules provide a semantic kind, complete content/style hashes, a versioned payload, and an explicit pending policy. Ordinary boxes and explicitly sized media should leave this unset.
Sourcepub fn set_plain_text(
&mut self,
node: NodeId,
input: &PlainTextInput,
style: &ComputedStyle,
) -> Result<bool, SurfaceError>
pub fn set_plain_text( &mut self, node: NodeId, input: &PlainTextInput, style: &ComputedStyle, ) -> Result<bool, SurfaceError>
Lowers and registers one plain UTF-8 Text v1 presentation.
Metric-affecting values come from the already resolved computed text context. The same payload is retained for final frame production and registered with Taffy for Host intrinsic measurement.
Sourcepub fn set_rich_text(
&mut self,
node: NodeId,
input: &PlainTextInput,
style: &ComputedStyle,
runs: &[ResolvedTextRun],
attachments: &[InlineAttachmentInput],
) -> Result<bool, SurfaceError>
pub fn set_rich_text( &mut self, node: NodeId, input: &PlainTextInput, style: &ComputedStyle, runs: &[ResolvedTextRun], attachments: &[InlineAttachmentInput], ) -> Result<bool, SurfaceError>
Replaces a paragraph’s inline content and intrinsic measurement inputs.
Sourcepub fn last_measurement(&self, node: NodeId) -> Option<&MeasurementMetrics>
pub fn last_measurement(&self, node: NodeId) -> Option<&MeasurementMetrics>
Returns the last final Host metrics retained for a node.
Baselines, overflow, and prepared-content handles remain available for later text and paint lowering even though Taffy consumes only the size.
Sourcepub fn invalidate_node(
&mut self,
node: NodeId,
impacts: PropertyImpactSet,
) -> Result<bool, SurfaceError>
pub fn invalidate_node( &mut self, node: NodeId, impacts: PropertyImpactSet, ) -> Result<bool, SurfaceError>
Applies invalidation categories for a changed node property.
Paint-only changes do not schedule Taffy. Intrinsic-measure changes invalidate the layout backend’s cached measurement before scheduling. Returns whether a layout pass is required by the supplied impacts.
Sourcepub fn compute_layout(
&mut self,
root: NodeId,
viewport: LayoutSize,
measurer: &mut dyn IntrinsicMeasurer,
) -> Result<LayoutUpdate, SurfaceError>
pub fn compute_layout( &mut self, root: NodeId, viewport: LayoutSize, measurer: &mut dyn IntrinsicMeasurer, ) -> Result<LayoutUpdate, SurfaceError>
Computes layout when inputs are dirty and journals changed rectangles.
Sourcepub fn compute_layout_with_measurements(
&mut self,
root: NodeId,
viewport: LayoutSize,
environment_epoch: u64,
) -> Result<LayoutProgress, SurfaceError>
pub fn compute_layout_with_measurements( &mut self, root: NodeId, viewport: LayoutSize, environment_epoch: u64, ) -> Result<LayoutProgress, SurfaceError>
Advances layout using retained, batched Host intrinsic measurement.
A blocked result must not be presented. Provisional geometry is emitted only when the element schema or provider supplied an explicit fallback. Reinvoke after applying immediate or deferred responses until complete.
Sourcepub fn apply_measurement_responses(
&mut self,
responses: &[MeasurementResponse],
) -> Result<MeasurementApply, SurfaceError>
pub fn apply_measurement_responses( &mut self, responses: &[MeasurementResponse], ) -> Result<MeasurementApply, SurfaceError>
Applies synchronous results from one Host measurement batch.
Unknown and wrong-epoch responses are counted as stale and ignored. Accepted results invalidate only their current Taffy consumers.
Sourcepub fn apply_measurement_ready(
&mut self,
ready: &MeasurementReady,
) -> Result<DeferredMeasurementApply, SurfaceError>
pub fn apply_measurement_ready( &mut self, ready: &MeasurementReady, ) -> Result<DeferredMeasurementApply, SurfaceError>
Applies a deferred Host-to-Rust measurement completion.
Sourcepub fn prepare_frame(
&mut self,
viewport_epoch: u32,
) -> Result<Option<&FramePacket>, SurfaceError>
pub fn prepare_frame( &mut self, viewport_epoch: u32, ) -> Result<Option<&FramePacket>, SurfaceError>
Prepares the next scene snapshot or delta frame.
Sourcepub fn present<Sink: FrameSink>(
&mut self,
viewport_epoch: u32,
sink: &mut Sink,
) -> Result<Option<ApplyResult>, SurfacePresentError<Sink::Error>>
pub fn present<Sink: FrameSink>( &mut self, viewport_epoch: u32, sink: &mut Sink, ) -> Result<Option<ApplyResult>, SurfacePresentError<Sink::Error>>
Presents the next transaction and applies the Host acknowledgement.
NeedSnapshot, a sink error, or an invalid acknowledgement rotates the
scene epoch and leaves a complete snapshot ready for the next call.
This repairs Hosts that may have applied part of a rejected packet.
Sourcepub fn accept_pending(&mut self, revision: u64) -> Result<(), SurfaceError>
pub fn accept_pending(&mut self, revision: u64) -> Result<(), SurfaceError>
Commits the prepared frame after renderer acceptance.
Sourcepub fn discard_pending(&mut self) -> Result<(), SurfaceError>
pub fn discard_pending(&mut self) -> Result<(), SurfaceError>
Discards the prepared frame while retaining its semantic changes.
Sourcepub fn require_snapshot(&mut self) -> Result<(), SurfaceError>
pub fn require_snapshot(&mut self) -> Result<(), SurfaceError>
Requires the next frame to rebuild the receiver from a full snapshot.