Struct BrowserSurfaceShared 

pub struct BrowserSurfaceShared { /* private fields */ }

What the thread of the user interface and the thread that renders both know about one canvas.

Not from upstream, where the surface of a view is one object that both threads read by convention. With a render worker the canvas itself exists in the worker only, and its element only in the page; this object is what is left between them (docs/porting/browser-render-worker.md, section 4):

• the id of the render target, written once by the thread that created the canvas;
• the size of the canvas in device pixels and its scaling, written by the thread of the user interface when the element changes, read by the render thread before each frame, which sets the size of the canvas it draws to;
• the kind of the render target, written by the thread that owns the target: the thread of the page for a canvas it kept, the render thread when its worker has created the target of a canvas that was transferred to it;
• whether the view is disposed;
• how many frames were drawn to the canvas, counted by the thread that draws them, and the thread that is told of the first one (on_first_frame).

A canvas is found by the id of its render target (register, find, report_target): a worker reports a target by its id, on a thread that has never seen the surface.

Everything is an atomic, so neither thread ever waits for the other here: the thread of the page may not block, and a lock that the render thread holds for a moment would make it spin. The size and the scaling are read as one value (a frame never sees a new size with an old scaling) through a version counter that is odd while they are being written.

Implementations

impl BrowserSurfaceShared

pub fn new() -> Arc<Self>

Creates the state of a canvas that has no render target, no id and no size yet.

pub fn target_id(&self) -> i32

The id of the render target in the registry of the script side; 0 while the canvas has not been created.

pub fn set_target_id(&self, target_id: i32)

Records the id of the render target. Called by the thread that created the canvas, once it has.

pub fn register(self: &Arc<Self>, target_id: i32)

Records the id of the render target and makes the canvas known under it to every thread (find). Called by the thread that created the canvas, once it has. When a worker has already reported the target of that id, its kind is published here.

The table holds the canvas weakly; a canvas that is registered again under an id takes the place of the one before.

pub fn unregister(&self)

Takes the canvas out of the table of register: a target reported under its id from here on belongs to no canvas. Called when the view is closed. Does nothing for a canvas that is not registered, and leaves alone a canvas that took its id since.

pub fn find(target_id: i32) -> Option<Arc<Self>>

The canvas that is registered under the id of a render target and still alive. Any thread may ask.

pub fn report_target(target_id: i32, kind: i32) -> Option<Arc<Self>>

The render target target_id exists and is of kind (RENDER_TARGET_KIND_WEB_GL or RENDER_TARGET_KIND_SOFTWARE): publishes the kind in the canvas registered under the id and returns the canvas. Called by the thread whose worker created the target.

When no canvas is registered under the id yet, the kind is kept for the one that will be (register) and the answer is None.

Panics

Panics when kind is neither.

pub fn size(&self) -> (PixelSize, f64)

The size of the canvas in device pixels and its scaling, as one value. Never waits: while a write is in progress it reads again.

pub fn set_size(&self, size: PixelSize, scaling: f64)

Records the size of the canvas in device pixels and its scaling. Called by the thread of the user interface.

pub fn on_size_changed(&self, pixel_width: f64, pixel_height: f64, dpr: f64)

Records what the observer of the canvas element reports: pixel_width and pixel_height in device pixels and the device pixel ratio, as on_size_changed receives them.

pub fn set_target_kind(&self, kind: i32)

Records that the render target exists and its kind (RENDER_TARGET_KIND_WEB_GL or RENDER_TARGET_KIND_SOFTWARE). Called by the thread that owns the target: the thread that created the canvas when it kept it, the render thread when its worker reports the target (report_target).

Panics

Panics when kind is neither.

pub fn target_kind(&self) -> i32

The kind of the render target; 0 while there is none.

pub fn has_target(&self) -> bool

Whether the render target exists.

pub fn uses_contexts(&self) -> Option<bool>

Whether the target renders with a graphics context (WebGL); None while there is no target.

pub fn dispose(&self)

Marks the view as disposed: nothing renders to its canvas any more.

pub fn is_disposed(&self) -> bool

Whether the view is disposed.

pub fn is_ready(&self) -> bool

Whether a frame can be rendered: the target exists, the canvas has a size, and the view is not disposed. Either thread may ask.

pub fn frames(&self) -> u64

The frames that were drawn to the canvas so far. Any thread may ask.

pub fn on_first_frame(&self, handler: Box<dyn FnOnce()>)

Runs handler once, on the calling thread, when the first frame has been drawn to the canvas; at once when it already has. Called by the thread that created the canvas, after the canvas has its id (register); a second handler takes the place of one that still waits.

Not from upstream, which has no such notification: its view closes the splash screen of the page at the first animation frame of the top-level, on the thread that also draws. That is before the frame is drawn, and with a render thread the frame is drawn by another thread, which may be seconds away (docs/porting/browser-render-worker.md, “B3 follow-ups”).

When this thread draws the canvas itself the handler runs inside the frame, right after it was drawn: it must not call into the view. When a render thread draws, that thread queues a call for this one ([thread_proxy::run_on_thread]) and the handler runs from the event loop of this thread; nothing is polled and nobody waits. A frame is only drawn while the page is visible and the canvas has a size, so the handler of a view that never draws never runs.

pub fn forget_first_frame(&self)

Drops the handler of on_first_frame when it still waits. Called by the thread that gave it, when the view is closed.