settings.json DOC | webGL support

MattiaPontonioKineton commented 4 years ago

Hello,

is possible to have documentation about the settings.json? There was an option in the old version for setting on and of the webGL feature. Is this option still available? Actually I'm getting 2 errors: This browser does not support webGL. Can't use image worker because browser does not have createImageBitmap and Web Worker support and I'm trying to understand if I can solve these issues with some configuration setting.

Best regards

g-zachar commented 4 years ago

Hi @MattiaPontonioKineton ,

Documentation was removed by accident, we will get it back on page promptly.

Here's a copy of what refers to appSettings in settings.json file:

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 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.

`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.

g-zachar commented 4 years ago

Also, please look into https://github.com/WebPlatformForEmbedded/Lightning/issues/16 about createImageBitmap. What browser are you running Lightning on?

Best regards

MattiaPontonioKineton commented 4 years ago

@g-zachar thanks for the references. With this settings.json, the app works:

{
  "appSettings": {
    "stage": {
      "clearColor": "0x00000000",
      "useImageWorker": true,
      "canvas2d": true
    },
    "debug": true
  },
  "platformSettings": {
    "inspector": true,
    "path": "./static",
    "log": true,
    "showVersion": true,
    "textureMode": true,
    "esEnv": "es5"
  }
}

The user agent is:

userAgent: Mozilla/5.0 (X11; Linux armv7l) AppleWebKit/537.36 (KHTML, like Gecko) QtWebEngine/5.6.0 Chrome/45.0.2454.101 Safari/537.36, Sky_STB_ST419_2018/1.0.0 (Sky, ES240IT, )

rdkcentral / Lightning