Interface RendererMainSettings

Configuration settings for RendererMain

interface RendererMainSettings {
    appHeight?: number;
    appWidth?: number;
    boundsMargin?: number | [number, number, number, number];
    clearColor?: number;
    deviceLogicalPixelRatio?: number;
    devicePhysicalPixelRatio?: number;
    enableContextSpy?: boolean;
    fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[];
    forceWebGL2?: boolean;
    fpsUpdateInterval?: number;
    inspector?: false | typeof Inspector;
    numImageWorkers?: number;
    quadBufferSize?: number;
    renderEngine: typeof WebGlCoreRenderer | typeof CanvasCoreRenderer;
    strictBounds?: boolean;
    textureMemory?: Partial<TextureMemoryManagerSettings>;
}

Properties

appHeight? appWidth? boundsMargin? clearColor? deviceLogicalPixelRatio? devicePhysicalPixelRatio? enableContextSpy? fontEngines forceWebGL2? fpsUpdateInterval? inspector? numImageWorkers? quadBufferSize? renderEngine strictBounds? textureMemory?

Properties

OptionalappHeight

appHeight?: number

Authored logical pixel height of the application

Default Value

1080

OptionalappWidth

appWidth?: number

Authored logical pixel width of the application

Default Value

1920

OptionalboundsMargin

boundsMargin?: number | [number, number, number, number]

Bounds margin to extend the boundary in which a Node is added as Quad.

OptionalclearColor

clearColor?: number

RGBA encoded number of the background to use

Default Value

0x00000000

OptionaldeviceLogicalPixelRatio

deviceLogicalPixelRatio?: number

Factor to convert app-authored logical coorindates to device logical coordinates

Remarks

This value allows auto-scaling to support larger/small resolutions than the app was authored for.

If the app was authored for 1920x1080 and this value is 2, the app's canvas will be rendered at 3840x2160 logical pixels.

Likewise, if the app was authored for 1920x1080 and this value is 0.66667, the app's canvas will be rendered at 1280x720 logical pixels.

Default Value

1

OptionaldevicePhysicalPixelRatio

devicePhysicalPixelRatio?: number

Factor to convert device logical coordinates to device physical coordinates

Remarks

This value allows auto-scaling to support devices with different pixel densities.

This controls the number of physical pixels that are used to render each logical pixel. For example, if the device has a pixel density of 2, each logical pixel will be rendered using 2x2 physical pixels.

By default, it will be set to window.devicePixelRatio which is the pixel density of the device the app is running on reported by the browser.

Default Value

window.devicePixelRatio

OptionalenableContextSpy

enableContextSpy?: boolean

Include context call (i.e. WebGL) information in FPS updates

Remarks

When enabled the number of calls to each context method over the fpsUpdateInterval will be included in the FPS update payload's contextSpyData property.

Enabling the context spy has a serious impact on performance so only use it when you need to extract context call information.

Default Value

false (disabled)

fontEngines

fontEngines: (typeof CanvasTextRenderer | typeof SdfTextRenderer)[]

Font Engines

Remarks

The font engines to use for text rendering. CanvasTextRenderer is supported on all platforms. SdfTextRenderer is a more performant renderer. When using renderEngine=CanvasCoreRenderer you can only use CanvasTextRenderer. The renderEngine=WebGLCoreRenderer supports both CanvasTextRenderer and SdfTextRenderer.

This setting is used to enable tree shaking of unused font engines. Please import your font engine(s) as follows:

import { CanvasTextRenderer } from '@lightning/renderer/canvas';
import { SdfTextRenderer } from '@lightning/renderer/webgl';

If both CanvasTextRenderer and SdfTextRenderer are provided, the first renderer provided will be asked first if it can render the font. If it cannot render the font, the next renderer will be asked. If no renderer can render the font, the text will not be rendered.

Note that if you have fonts available in both engines the second font engine will not be used. This is because the first font engine will always be asked first.

Default Value

'[]'

OptionalforceWebGL2

forceWebGL2?: boolean

Force WebGL2

Remarks

Force the renderer to use WebGL2. This can be used to force the renderer to use WebGL2 even if the browser supports WebGL1.

Default Value

false

OptionalfpsUpdateInterval

fpsUpdateInterval?: number

Interval in milliseconds to receive FPS updates

Remarks

If set to 0, FPS updates will be disabled.

Default Value

0 (disabled)

Optionalinspector

inspector?: false | typeof Inspector

DOM Inspector

Remarks

The inspector will replicate the state of the Nodes created in the renderer and allow inspection of the state of the nodes.

OptionalnumImageWorkers

numImageWorkers?: number

Number or Image Workers to use

Remarks

On devices with multiple cores, this can be used to improve image loading as well as reduce the impact of image loading on the main thread. Set to 0 to disable image workers.

Default Value

2

OptionalquadBufferSize

quadBufferSize?: number

Quad buffer size in bytes

Default Value

4 * 1024 * 1024

renderEngine

renderEngine: typeof WebGlCoreRenderer | typeof CanvasCoreRenderer

Renderer Engine

Remarks

The renderer engine to use. Spawns a WebGL or Canvas renderer. WebGL is more performant and supports more features. Canvas is supported on most platforms.

Note: When using CanvasCoreRenderer you can only use CanvasTextRenderer. The WebGLCoreRenderer supports both CanvasTextRenderer and SdfTextRenderer for Text Rendering.

OptionalstrictBounds

strictBounds?: boolean

Enable strictBounds

Remarks

Enable strict bounds for the renderer. This will ensure that the renderer will not render outside the bounds of the canvas.

Default Value

true

OptionaltextureMemory

textureMemory?: Partial<TextureMemoryManagerSettings>

Texture Memory Manager Settings

Settings

Member Visibility

On This Page

Properties