UI Overlay
Overlay
Overlay is a singleton class that manages displaying UI frames as image overlays. The image can be displayed over background video playback.
It can be used in any lifecycle state.f
Kind: global class
Emits: event:error
- Overlay
- .addElement(element) ⇒
Promise. - .removeElement(element) ⇒
Promise. - .refresh() ⇒
Promise. - .removeAllElements() ⇒
Promise. - .hideOverlay() ⇒
Promise. - .configure(configuration)
- .getConfiguration() ⇒
Object - .getElements() ⇒
Array. - "error"
- .addElement(element) ⇒
overlay.addElement(element) ⇒ Promise.
Promise.Registers a DOM element as the UI image overlay.
The element's bounding rectangle will be used to determine the frame dimensions.
If a different element is already registered, an error is thrown.
Use configure() to set overlay options before or after registering.
Call refresh() explicitly to render the initial frame after registering the element.
Kind: instance method of Overlay
Returns: Promise. - Resolves to true if successful, rejects with error if failed.
| Param | Type | Description |
|---|---|---|
| element | Element | The DOM element to display as the UI image overlay frame. |
overlay.removeElement(element) ⇒ Promise.
Promise.Unregisters a specific element by reference and deactivates the overlay.
This only removes the registered element. To explicitly hide the overlay frame, use removeAllElements() and hideOverlay().
Kind: instance method of Overlay
Returns: Promise. - Resolves to true if successful, false if not active, rejects with error if element does not match.
| Param | Type | Description |
|---|---|---|
| element | Element | The element to unregister (must match the registered element). |
overlay.refresh() ⇒ Promise.
Promise.Manually refreshes the displayed frame using the current element's dimensions.
This is useful when the element's content or position has changed.
The overlay must have an element registered before calling refresh.
Runs the configured overlay capture plan after each call. The default preset sends
low-quality captures with relative delays, ending with a high-quality capture.
The once preset runs one high-quality conditional step immediately.
All steps in one refresh share the same batchId (from getFCID()). Pending plan
steps are cancelled by a subsequent call to refresh(), hideOverlay(), or removeElement().
Kind: instance method of Overlay
Returns: Promise. - Resolves to true if successful, rejects with error if failed.
overlay.removeAllElements() ⇒ Promise.
Promise.Removes all registered elements and deactivates the overlay.
After calling removeAllElements(), a new element can be registered.
Kind: instance method of Overlay
Returns: Promise. - Resolves to true if successful, rejects with error if failed.
overlay.hideOverlay() ⇒ Promise.
Promise.Hides the current overlay frame.
Kind: instance method of Overlay
Returns: Promise. - Resolves to true if successful, rejects with error if failed.
overlay.configure(configuration)
Updates the configuration of the overlay.
Kind: instance method of Overlay
| Param | Type | Default | Description |
|---|---|---|---|
| configuration | Object | The new configuration to apply. | |
| [configuration.useTransparency] | boolean | true | Controls whether the overlay should be rendered with transparency. When set to true, the overlay is rendered with transparency. |
| [configuration.overlayCapturePreset] | string | ""default"" | Named capture plan preset: default (progressive low→high captures) or once (one immediate high-quality conditional step). |
| [configuration.overlayCapturePlan] | Array.<{quality: ("low"|"mid"|"high"), conditional: boolean, delay: number}> | Explicit capture plan; overrides preset. Steps run on refresh(); each step's delay is ms after the previous step in the batch. Set conditional per step (the SDK does not derive it): when true, capture only if overlay content changed since the last required (non-conditional) capture in this batch; when false, always capture on that step. | |
| [configuration.autoHideDurationSec] | number | 600 | Client auto-hide duration in seconds. Defaults to 600 (10 minutes) until configured. Omit the key to keep the current value. 0 means never auto-hide. Valid range: 0–65535. |
overlay.getConfiguration() ⇒ Object
ObjectGets the current configuration of the overlay.
Kind: instance method of Overlay
Returns: Object - The current configuration.
overlay.getElements() ⇒ Array.
Array.Gets all registered elements.
Kind: instance method of Overlay
Returns: Array. - An array of currently registered elements.
"error"
Fired when an error occurs during displaying the overlay image.
Kind: event emitted by Overlay
Properties
| Name | Type | Description |
|---|---|---|
| error | Error | The error that occurred. |
Updated 14 days ago