Skip to main content

LensStudio:LensPreview.LensPreview

Class

Headless preview that renders the project open in Lens Studio without a panel or widgets.

Headless preview that renders the project open in Lens Studio without a panel or widgets. It starts rendering when constructed and can capture screenshots, inspect the runtime scene, record traces, and exchange messages with the Lens; it is released when no longer referenced.

Index

Example

Keep one headless preview for a plugin and reload its Lens after the project changes. refresh() reloads the Lens asynchronously; wait for onLensReset before capturing a frame of the reloaded Lens.

import { LensPreview } from 'LensStudio:LensPreview';
import { Image, StreamType, Input } from 'LensStudio:Preview';

export function createPreview(pluginSystem: Editor.PluginSystem, imageFile: Editor.Path): LensPreview {
const preview = new LensPreview(pluginSystem);
preview.setViewport(new Editor.Size(360, 640));
const input = new Input();
input.type = StreamType.Multimedia;
input.sourcePath = imageFile;
const config = preview.config;
config.input = input;
preview.config = config;
return preview;
}

export async function reloadAndCapture(preview: LensPreview, timeoutMs = 20000): Promise<Image> {
let connection: Editor.ScopedConnection | undefined;
let timer: ReturnType<typeof setTimeout> | undefined;
try {
const reloaded = new Promise<void>((resolve, reject) => {
connection = preview.onLensReset.connect(() => resolve());
timer = setTimeout(() => reject(new Error('The Lens did not reload in time')), timeoutMs);
});
preview.refresh();
await reloaded;
} finally {
connection?.disconnect();
if (timer !== undefined) clearTimeout(timer);
}
return preview.tryScreenshot(timeoutMs);
}

Extends

Constructors

Constructor

new LensPreview(pluginSystem, options?): LensPreview

Constructs a headless preview of the project open in the given plugin system's model, optionally configured with LensPreviewOptions.

Parameters

ParameterType
pluginSystemPluginSystem
options?LensPreviewOptions

Returns

LensPreview

Overrides

ScriptObject.constructor

Properties

config

config: Config

Input configuration of the preview: input source, camera view, simulated device, and input upscale. Reading it returns a copy, so assign the modified Config back to apply it; a Config whose input type is StreamType.None is rejected.


device

device: any

Device descriptor the preview simulates, or null until one is assigned. Assigning a descriptor applies its aspect ratio and camera field of view; null is rejected.


isDisposed

readonly isDisposed: boolean


muted

muted: boolean


onLensReset

readonly onLensReset: signal0<void>

Signal emitted each time the preview creates a new Lens scene, such as after the Lens first loads or after refresh().


onMessage

readonly onMessage: signal1<any, void>

Signal emitted when the Lens running in the preview posts a message. The callback receives an object whose data property holds the message.


pauseReason?

readonly optional pauseReason?: AssetNotReady | InvalidAssetConfiguration | RenderFailed | PausedByUser | Suspended

Reason the preview is not rendering normally: an AssetNotReady, RenderFailed, PausedByUser, or Suspended value, or null while it renders. Use instanceof to tell the reasons apart.


pose

pose: mat4

Transform of the simulated device as a 4x4 matrix. Assigning a matrix applies its rotation and translation as a custom device pose.


profiling

readonly profiling: IPreviewProfiling

Profiling interface for recording performance traces of this preview.

Methods

dispose()

dispose(): void

Returns

void


getTypeName()

static getTypeName(): string

Returns the type name of this class.

Returns

string

Overrides

ScriptObject.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

ScriptObject.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object is of the specified type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

ScriptObject.isOfType


isSame()

isSame(other): boolean

Returns true if this object refers to the same instance as the given object.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

ScriptObject.isSame


pause()

pause(): void

Pauses the preview by setting pauseReason to a Suspended value; pending screenshots and video recordings are cancelled. Has no effect while a non-resumable reason such as AssetNotReady is reported.

Returns

void


postMessage()

postMessage(message): void

Sends a message to the Lens running in the preview. The value is serialized, so pass plain data such as strings, numbers, arrays, or objects.

Parameters

ParameterType
messageany

Returns

void


recordVideo()

recordVideo(durationMs): Promise<Video>

Records an H.264 MP4 video of the preview output lasting durationMs milliseconds and resolves with a Video. Rejects if durationMs is not positive, the preview is paused, or another recording is in progress; changing the input, device, or viewport, or resetting the Lens, cancels the recording.

Parameters

ParameterType
durationMsnumber

Returns

Promise<Video>


refresh()

refresh(): void

Reloads the Lens in the preview from the current project. onLensReset is emitted when the new Lens scene is created.

Returns

void


resume()

resume(): void

Resumes a preview paused with pause() and clears its Suspended pauseReason. Has no effect while a non-resumable reason such as AssetNotReady is reported.

Returns

void


screenshot()

screenshot(): Promise<Image>

Captures the next rendered frame and resolves with an Image. Rejects if no frame is produced, for example while the preview is paused; use tryScreenshot() to limit how long to wait.

Returns

Promise<Image>


sendGesture()

sendGesture(gesture): void

Parameters

ParameterType
gestureGesture

Returns

void


setViewport()

setViewport(size): void

Sets the preferred size, in pixels, of the viewport the preview renders into. Changing it cancels a video recording in progress.

Parameters

ParameterType
sizeSize

Returns

void


startInspection()

startInspection(): Promise<InspectionSession>

Switches the preview to scene inspection and resolves with an InspectionSession for the Lens's runtime scene. Concurrent calls share the current session; the promise rejects if inspection stops before the runtime scene is available.

Returns

Promise<InspectionSession>


tryScreenshot()

tryScreenshot(timeoutMs): Promise<Image>

Captures the next rendered frame like screenshot(), but rejects if no frame arrives within timeoutMs milliseconds.

Parameters

ParameterType
timeoutMsnumber

Returns

Promise<Image>