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
| Name | Type | Default | Description |
|---|---|---|---|
debug | Boolean | false | Shows changes to the focus path for debug purposes |
keys | Object | Object | A custom key map |
Stage configuration options
| Name | Type | Default | Description |
|---|---|---|---|
canvas | HTMLCanvasElement | null | Instead of creating a new canvas, reuse this one |
context | Object | null | Use the specified webgl/canvas2d context |
w | Number | 1920 | Stage width in pixels |
h | Number | 1080 | Stage height in pixels |
precision | Float | 1 | Global stage scaling (see below) |
memoryPressure | Number | 24e6 | Max GPU memory usage (in pixels) |
clearColor | Float[] | [0,0,0,0] | Background color. ARGB values (0 to 1) |
defaultFontFace | String | 'sans-serif' | The default font face to be used when rendering text |
fixedDt | Number | 0 (auto) | The fixed timestep per frame (ms) |
useImageWorker | Boolean | true | Attempt to use a web worker that parsers images off-thread (web only) |
autostart | Boolean | true | If set to false, does not bind to requestAnimationFrame automatically |
canvas2d | Boolean | false | If set, render engine uses canvas2d instead of webgl (has some limitations) |
precision
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
precisionoption 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.
memoryPressure
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.
canvas2d
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.