Stage Configuration

Created on November 04, 2020, Last modified on May 19, 2022

Supplying the configuration

When initializing your application, you can pass Lightning configuration options like this:

const options = {stage: {w: 1920, h: 1080, clearColor: 0xFF000000}}
const app = new MyApp(options);

Notice the stage sub object, which is used to define configuration options for the render tree.

Application configuration options

debugBooleanfalseShows changes to the focus path for debug purposes
keysObjectObjectA custom key map

Stage configuration options

canvasHTMLCanvasElementnullInstead of creating a new canvas, reuse this one
contextObjectnullUse the specified webgl/canvas2d context
wNumber1920Stage width in pixels
hNumber1080Stage height in pixels
precisionFloat1Global stage scaling (see below)
memoryPressureNumber24e6Max GPU memory usage (in pixels)
clearColorFloat[][0,0,0,0]Background color. ARGB values (0 to 1)
defaultFontFaceString'sans-serif'The default font face to be used when rendering text
fixedDtNumber0 (auto)The fixed timestep per frame (ms)
useImageWorkerBooleantrueAttempt to use a web worker that parsers images off-thread (web only)
autostartBooleantrueIf set to false, does not bind to requestAnimationFrame automatically
canvas2dBooleanfalseIf set, render engine uses canvas2d instead of webgl (has some limitations)


Assume you've created an app for 1080p quality. You've used a 1920x1080 coordinate system to position all your content. Now you've found out that the app needs to be displayed in 1280x720 resolution.

We advice you to always develop your TV app in a 1080p coordinate system, as is the Lightning default.

The precision property exists for this exact use case. It performs a global rescale of the coordinate system. So by specifying precision: 2/3, the 1920 x-position will be mapped to the 1280 output pixel coordinate.

Furthermore, the text renderer engine will render texts at the lower resolution, increasing quality (less pixel interpolation) as well as reducing memory usage. Off-screen render textures will also be rendered at a lower resolution for the same reason.

Downscaling using the precision option works pretty good, but you might still run into annoying issues. WebGL rasterizes as pixel boundaries, so when using a line with width 2 in 1080p, it may render at either 2px or 3px in 720p (depending on the pixel offset it's rendered at). If you run into this issue, make sure you're sizing at multiples of 3.


This defines the total number of pixels that may be allocated in GPU memory. This allows you to tweak the amount of GPU memory that your Lightning app can use. Lightning only performs an unused texture cleanup when this amount is reached. Ideally, it's not reached often.

Notice that a single pixel will take up to 4 to 6 bytes in GPU memory.


By default, Lightning uses WebGL for rendering. If that's not available, or when canvas2d is set to false, Lightning will try to use canvas2d as the render engine renderer output. Please keep in mind that some functionality, such as WebGL-only shaders, naturally won't work (the default shader will be used).

Another limitation is in colorizing textures. You can safely colorize rectangle textures and even provide (only linear) gradients, but other textures, such as text and images, require the engine to create an offscreen colorized texture (gradients are not supported). This is expensive in terms of cpu and memory, but when used sparingly to color text or tint images one time, it works fine in practice.

Give feedback

Rating - 4.2 / 5. . Reviews - 5

No votes so far! Be the first to rate this post.

Go To Top