Skip to main content

SurfaceEngine

Struct SurfaceEngine 

Source
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

Source

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

Source

pub fn new(surface: SurfaceId) -> Self

Creates an empty surface pipeline.

Source

pub fn with_protocol(surface: SurfaceId, protocol: ProtocolVersion) -> Self

Creates an empty pipeline using the protocol selected with its Host.

Source

pub const fn surface(&self) -> SurfaceId

Returns this pipeline’s surface identifier.

Source

pub const fn scene(&self) -> &Scene

Returns the retained scene without allowing structural mutation.

Source

pub fn layout_tree(&self) -> &LayoutTree

Returns the retained layout tree without allowing structural mutation.

Source

pub fn last_layout(&self) -> Option<&LayoutSnapshot>

Returns the most recent successful layout snapshot.

Source

pub const fn needs_layout(&self) -> bool

Returns whether retained inputs require another layout pass.

Source

pub fn has_pending_work(&self) -> bool

Returns whether the scene has a snapshot, mutation, command, or retry.

Source

pub fn node(&self, node: NodeId) -> Option<&SceneNode>

Returns a retained scene node when it is live.

Source

pub fn hit_test( &self, root: NodeId, point: InputPoint, ) -> Result<Option<NodeId>, SurfaceError>

Finds the visually topmost retained node at a surface-space point.

Source

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.

Source

pub fn set_pointer_capture( &mut self, node: NodeId, pointer: PointerId, ) -> Result<(), SurfaceError>

Captures a pointer stream for a node.

Source

pub fn release_pointer_capture( &mut self, node: NodeId, pointer: PointerId, ) -> Result<(), SurfaceError>

Releases a pointer stream previously captured by a node.

Source

pub fn release_pointer_captures(&mut self) -> Result<(), SurfaceError>

Releases every captured pointer.

Source

pub fn pointer_capture_target(&self, pointer: PointerId) -> Option<NodeId>

Returns the node currently retaining one pointer capture.

Source

pub fn set_event_mask( &mut self, node: NodeId, mask: u64, ) -> Result<(), SurfaceError>

Replaces one node’s event subscription mask.

Source

pub fn set_accessibility( &mut self, node: NodeId, accessibility: Accessibility, ) -> Result<(), SurfaceError>

Replaces one node’s common accessibility semantics.

Source

pub fn set_property( &mut self, node: NodeId, property: PropertyId, value: WhiskerValue, ) -> Result<(), SurfaceError>

Sets one typed element property in the retained scene.

Source

pub fn clear_property( &mut self, node: NodeId, property: PropertyId, ) -> Result<(), SurfaceError>

Clears one typed element property in the retained scene.

Source

pub fn invoke_command( &mut self, node: NodeId, command: CommandId, arguments: WhiskerValue, ) -> Result<(), SurfaceError>

Queues one typed element command after preceding visual mutations.

Source

pub fn set_hit_test( &mut self, node: NodeId, behavior: HitTestBehavior, ) -> Result<(), SurfaceError>

Replaces one node’s hit-test participation.

Source

pub fn set_cursor( &mut self, node: NodeId, cursor: Cursor, ) -> Result<(), SurfaceError>

Replaces one node’s resolved pointing-device cursor.

Source

pub fn set_opacity( &mut self, node: NodeId, opacity: f32, ) -> Result<(), SurfaceError>

Replaces one node’s already-resolved group opacity.

Source

pub fn set_box_paint( &mut self, node: NodeId, paint: BoxPaint, ) -> Result<(), SurfaceError>

Replaces one node’s resolved background, border, and radius paint.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn create_node( &mut self, element_type: ElementTypeId, style: ComputedLayoutStyle, ) -> Result<NodeId, SurfaceError>

Creates one unattached node in both retained trees.

Source

pub fn delete_node(&mut self, node: NodeId) -> Result<(), SurfaceError>

Deletes a node and its complete subtree from both retained trees.

Source

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.

Source

pub fn remove_child( &mut self, parent: NodeId, child: NodeId, ) -> Result<(), SurfaceError>

Detaches a direct child without deleting it.

Source

pub fn move_child( &mut self, parent: NodeId, child: NodeId, index: u32, ) -> Result<(), SurfaceError>

Moves a direct child within its current parent.

Source

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.

Source

pub fn update_computed_style( &mut self, node: NodeId, style: &ComputedStyle, ) -> Result<PropertyImpactSet, SurfaceError>

Applies every currently supported computed layout and paint value.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn apply_measurement_ready( &mut self, ready: &MeasurementReady, ) -> Result<DeferredMeasurementApply, SurfaceError>

Applies a deferred Host-to-Rust measurement completion.

Source

pub fn prepare_frame( &mut self, viewport_epoch: u32, ) -> Result<Option<&FramePacket>, SurfaceError>

Prepares the next scene snapshot or delta frame.

Source

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.

Source

pub fn accept_pending(&mut self, revision: u64) -> Result<(), SurfaceError>

Commits the prepared frame after renderer acceptance.

Source

pub fn discard_pending(&mut self) -> Result<(), SurfaceError>

Discards the prepared frame while retaining its semantic changes.

Source

pub fn require_snapshot(&mut self) -> Result<(), SurfaceError>

Requires the next frame to rebuild the receiver from a full snapshot.

Trait Implementations§

Source§

impl Clone for SurfaceEngine

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for SurfaceEngine

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.