Merge pull request #474 from rdkcentral/release/2.10.0

Release - v2.10.0

.gitignore

@@ -47,3 +47,6 @@ dist
 
 # Type Docs
 /typedocs
+
+# ES5 version of the Lightning Inspector
+/devtools/lightning-inspect.es5.js

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v2.10.0
+*24 apr 2023*
+
+- Integrated `Vite` to replace `rollup` bundler and integrated `Vitest` for unit testing
+- Implemented word wrapping support on zero-width breaking spaces (#450) (docs: [Word Wrap in Non-Latin Based Languages](https://lightningjs.io/docs/#/lightning-core-reference/RenderEngine/Textures/Text?id=word-wrap-in-non-latin-based-languages) ) 
+- Added support for device pixel ratio with an option `devicePixelRatio` (docs: [Global Stage Scaling](https://lightningjs.io/docs/#/lightning-core-reference/RuntimeConfig/index?id=#global-stage-scaling), [Handling high pixel density](https://lightningjs.io/docs/#/lightning-core-reference/RuntimeConfig/index?id=#handling-high-pixel-density-high-dpi) ) 
+- Fixed issue with text rendering at high precision levels causing incorrect word wrapping (#470)
+- Fixed issue with inability to override the id accessor of a Component with string accessor (#456)
+- Added first/last getters to TypeScript definitions for ObjectList
+- Fixed documentation and TypeScript definitions for TextTexture `fontFace`
+- Fixed TypeScript error with getByRef() when using generic type param as Ref value (#444)
+- Implemented default loose type configs for TypeScript.
+
 ## v2.9.1
 
 *21 apr 2023*

banner.vite-plugin.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from 'vite';
+
+/**
+ * Simple vite plugin to add a copyright banner to the beginning of each chunk.
+ *
+ * @param bannerText The banner text to add to each chunk.
+ */
+export function banner(bannerText: string): Plugin {
+  return {
+    name: 'banner',
+    enforce: 'post',
+    generateBundle(options, bundle) {
+      // Add banner to the beginning of each chunk
+      Object.keys(bundle).forEach((key) => {
+        const file = bundle[key];
+        if (file.type === 'chunk') {
+          file.code = bannerText + '\n' + file.code;
+        }
+      });
+    }
+  };
+}

devtools/lightning-inspect.js

@@ -194,12 +194,13 @@ window.attachInspector = function({Application, Element, ElementCore, Stage, Com
             document.body.appendChild(root);
             var self = this;
             let updateRootStyleFromCanvas = function (bcr) {
+                const p = self.stage.getRenderPrecision() / self.stage.getOption('devicePixelRatio');
                 root.style.left = bcr.left + 'px';
                 root.style.top = bcr.top + 'px';
-                root.style.width = Math.ceil(bcr.width / self.stage.getRenderPrecision()) + 'px';
-                root.style.height = Math.ceil(bcr.height / self.stage.getRenderPrecision()) + 'px';
+                root.style.width = Math.ceil(bcr.width / p) + 'px';
+                root.style.height = Math.ceil(bcr.height / p) + 'px';
                 root.style.transformOrigin = '0 0 0';
-                root.style.transform = 'scale(' + self.stage.getRenderPrecision() + ',' + self.stage.getRenderPrecision() + ')';
+                root.style.transform = 'scale(' + p + ',' + p + ')';
             }
 
             if (window.ResizeObserver != null) {

docs/RenderEngine/Textures/Text.md

@@ -11,7 +11,7 @@ You can use various properties to control the way in which you want to render te
 | Name | Type | Default | Description |
 |---|---|---|---|
 | `text` | String | '' | Text to display |
-| `fontFace` | Integer | null | Font family used for current text |
+| `fontFace` | String or String[] | `null` | Font family used for current text. If an array is provided, font families that appear later in the array are used as fallbacks. If the (default) `null` value is specified, the font family value specified in the `defaultFontFace` [Stage Option](../../RuntimeConfig/index.md#stage-configuration-options) is used. If the resolved font family (or families) is unavailable to the browser, a fallback is chosen by the browser. The special [CSS defined font family values](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#values) of "serif" and "sans-serif" may be used as well. |
 | `fontSize` | Integer | 40 | Font size |
 | `fontStyle` | String | 'normal' | Font style |
 | `lineHeight` | Integer | null | Line height |
@@ -45,9 +45,51 @@ You can use various properties to control the way in which you want to render te
 | `letterSpacing` | Integer | 0 | Letter spacing of characters |
 
 
+## Word Wrap in Non-Latin Based Languages
 
+Enabling the `wordWrap` option causes lines of text that are too long for the
+specified `wordWrapWidth` to be broken into multiple lines. Lines are broken
+only at word boundaries. In most latin script based languages (i.e. English,
+Dutch, French, etc) the space " " character is the primary separator of word
+boundaries.
 
+Many non-latin based languages (i.e. Chinese, Japanese, Thai and more) do not use spaces
+to separate words. Instead there is an assortment of rules that determine where
+word boundaries, for the purpose of line breaking, are allowed. Lightning
+currently does not implement these rules as there are many languages and writing
+systems to consider when implementing them. However, we do offer a work around
+that can be employed in your application as needed.
 
+### Zero-Width Spaces
+
+Lightning supports line breaking at [Zero-Width Space](https://en.wikipedia.org/wiki/Zero-width_space)
+(Unicode: `\u200B`) word boundaries. These characters are like normal spaces but
+take up no actual space between visible characers. You can use them in
+your text strings and Lightning will line break on them when it needs to.
+
+You may want to write a function that you funnel all of your application's
+text strings into:
+
+```js
+function addZeroWidthSpaces(text) {
+    // Code that inserts Zero-Width Spaces into text and returns the new text
+}
+
+class ZeroWidthSpaceTextDemo extends lng.Application {
+    static _template() {
+        return {
+            Text: {
+                text: {
+                    text: addZeroWidthSpaces('こんにちは。初めまして!')
+                }
+            }
+        }
+    }
+}
+```
+
+See [this GitHub issue](https://github.com/rdkcentral/Lightning/issues/450) for
+more information.
 
 ## Live Demo
 

docs/RuntimeConfig/index.md

@@ -35,9 +35,10 @@ const App = new MyApp(options);
 | `w` | Number | 1920 | Stage width in pixels |
 | `h` | Number | 1080 | Stage height in pixels |
 | `precision` | Float | 1 | Global stage scaling (see details below) |
+| `devicePixelRatio` | Float | 1 | Handling high DPI (see details below) |
 | `memoryPressure` | Number | 24e6 | Maximum GPU memory usage in pixels (see details below) |
 | `clearColor` | Float[] | [0,0,0,0] | Background color in ARGB values (0 to 1) |
-| `defaultFontFace` | String | sans-serif | Font face for text rendering |
+| `defaultFontFace` | String | "sans-serif" | Default font family to use for text. See the [fontFace Text property](../RenderEngine/Textures/Text.md#properties) for how this value ends up being used. The special [CSS defined font family values](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#values) of "serif" and "sans-serif" may be used as well. |
 | `fontSharp` | Object, Boolean | { precision:0.6666666667, fontSize: 39 } | Determine when to apply gl.NEAREST to TEXTURE_MAG_FILTER |
 | `fixedDt` | Number | 0 (auto) | Fixed time step per frame (in ms) |
 | `useImageWorker` | Boolean | true | By default, use a Web Worker that parses images off-thread (web only) |
@@ -49,25 +50,42 @@ const App = new MyApp(options);
 | `debugFrame` | Boolean | false | If set to *true*, logs debug information about each frame including how many render-to-texture elements were re-rendered. This may impact performance and should not be turned on in production. |
 | `forceTxCanvasSource` | Boolean | false | If set to *true*, forces the Render Engine to use the canvasSource over getImageData for text (this helps with text generation on certain devices). |
 | `pauseRafLoopOnIdle` | Boolean | false | If set to *true* will stop the Render Engine from calling `RequestAnimationFrame` when there are no stage updates. |
+| `devicePixelRatio` | Number | 1 | The DPR is the logical to physical pixel density for a touch enabled device and affects how we calculate collisions |
 
 
+## Global stage scaling
 
+> We advise you to always develop your TV App in a **1080p** coordinate system (the Lightning default).
 
-## Downscaling
 
-> We advise you to always develop your TV App in a **1080p** coordinate system (the Lightning default).
+Assume that you have created an App for 1080p quality, where you've used a 1920x1080 coordinate system to position all of the content. However, you've found out that the App needs to be displayed in a 1280x720 resolution.
+
+
+To make this adjustment, you can use the `precision` property to perform a *global rescale* of the coordinate system. For example, if you specify `precision: 2/3`, the 1920 x-position will be mapped to the 1280-output pixel coordinate. This downscaling generally works well and can improve quality (less pixel interpolation) while reducing memory usage.
 
+By setting  `precision: 2`, the 1920 x-position will be mapped to a 3840-output pixel coordinate, effectively upscaling the content for 4K resolution. Please note that upscaling may result in reduced performance due to the higher GPU memory usage.
 
-Assume that you have created an App for 1080p quality, so you have used a 1920x1080 coordinate system to position all of the content. However, you have found out that the App needs to be displayed in a 1280x720 resolution.
+Keep in mind that WebGL rasterizes at pixel boundaries. This means that when it uses a line width of 2 in 1080p quality, it may render at either 2px or 3px in 720p (depending on the rendered pixel offset). If you encounter such problems, you'll need to set the sizing at a multiple of 3 to ensure proper rendering.
 
+# Handling high pixel density (high DPI)
 
-You can use the `precision` property to perform a  *global rescale* of the coordinate system. For example, if you specify `precision: 2/3`, the 1920 x-position will be mapped to the 1280-output pixel coordinate.
+With the increasing number of devices in the market having high pixel densities (DPI), it's important to handle high DPI properly in your Lightning app. Fortunately, you can take advantage of the higher resolution by setting the devicePixelRatio property, which is a minor and generally non-disruptive change.
+It's worth noting that canvas elements, like most graphics elements, have two sizes
 
+- The size they are displayed in the page
+- The size of their content
+
+For a canvas element, the size of the content or drawingBuffer is determined by the width and height attributes of the canvas, while the display size is determined by the CSS attributes applied to the canvas. Setting `devicePixelRatio: 2` will result in the following:
+
+```html
+<canvas width="3840" height="2060" style="width: 1920px; height: 1080px;"></canvas>
+```
 
-As a result, the text and off-screen textures are rendered at a *lower resolution* by the [Render Engine](../RenderEngine/index.md), which increases quality (less pixel interpolation) and reduces memory usage.
+a canvas that has a drawingBuffer of size 3840x2060 pixels but is displayed at a 1920x1080 viewport.
 
+When viewed on High DPI displays, the browser will automatically upscale the canvas content to ensure that it appears at the correct size on the screen. However, if the devicePixelRatio (DPR) is not set properly, a Lightning application may appear to render at a lower-than-native resolution, which can introduce aliasing.
 
-Downscaling with the `precision` option generally works well. But keep in mind that WebGL rasterizes as *pixel boundaries*, so when it uses a line width of 2 in 1080p quality, it may render at either 2px or 3px in 720p (depending on the rendered pixel offset). If you encounter such problems, you have to set the sizing at a multiple of 3.
+It's essential to handle high DPI properly to ensure that your Lightning app looks crisp and clear on high DPI displays
 
 
 ## FontSharp

docs/TypeScript/Components/TypeConfigs.md

@@ -129,4 +129,17 @@ class MyParentComponent extends Lightning.Component {
   }
   // ...
 }
-```
+```
+
+## Loose Type Configs
+
+If a Type Config is not explicitly provided, a **Loose Type Config** will be used by default. This is similar to the [**Loose Template Spec**](TemplateSpecs.md). Events and Signals will be handled in a much more looser fashion, allowing you to hook up any Events/Signals regardless of if any are explicitly specified.
+
+You can also explicitly extend the base `LooseTypeConfig` interface if you want the best of both worlds. Explicitly specified Events and Signals will be type checked. But any other Event or Signal will be allowed and be able to emit/receive `any` set of parameters.
+
+```ts
+export interface TypeConfigLoose extends Lightning.Component.TypeConfigLoose {
+  SignalMapType: MyComponentSignalMap,
+  EventMapType: MyComponentEventMap
+}
+```

examples/mouse-pointer/basic-usage.html

@@ -74,8 +74,7 @@
 
             }
 
-            const options = {stage: {w: 900, h: 900, clearColor: 0xFF000000, canvas2d: false, useImageWorker: false}, debug: true, enablePointer: ENABLE_POINTER}
-
+            const options = {stage: {w: 1080, h: 720, clearColor: 0xFF000000, canvas2d: false, useImageWorker: false, devicePixelRatio: 2}, debug: true, enablePointer: ENABLE_POINTER}
             const app = new BasicUsageExample(options);
 
             document.body.appendChild(app.stage.getCanvas());