add README

TODO.md

@@ -1,7 +1,7 @@
 
 # @spearwolf/visual-fx-web-components
 
-> _Generated by [scripts/makeTODO.mjs](scripts/makeTODO.mjs) at 2024-03-23T15:11:12.395Z_
+> _Generated by [scripts/makeTODO.mjs](scripts/makeTODO.mjs) at 2024-03-23T15:46:34.496Z_
 
 This file contains an overview of all TODO, FIXME or XXX comments extracted from the source files of the packages.
 
@@ -24,7 +24,6 @@ This file contains an overview of all TODO, FIXME or XXX comments extracted from
 | [packages/vfx/src/elements/VfxCtxElement.js](packages/vfx/src/elements/VfxCtxElement.js#L299) | 299 | what should happen with the events ? |
 | [packages/vfx/src/elements/VfxCtxElement.js](packages/vfx/src/elements/VfxCtxElement.js#L312) | 312 | find a more friendly way to destroy the worker before termination |
 | [packages/vfx/src/shadow-objects/VfxDisplay.js](packages/vfx/src/shadow-objects/VfxDisplay.js#L26) | 26 | use shared vfx.canvas|multiViewRenderer -------- |
-| [packages/vfx/src/shadow-objects/VfxDisplay.js](packages/vfx/src/shadow-objects/VfxDisplay.js#L119) | 119 | maybe we should create a `<shadow-entity traverse-events="onRenderFrame, onIdle">` attribute ? |
 | [packages/vfx/src/worker/MessageRouter.js](packages/vfx/src/worker/MessageRouter.js#L16) | 16 | subscribe to kernel "message" events |
 | [packages/vfx/src/worker/MessageRouter.js](packages/vfx/src/worker/MessageRouter.js#L73) | 73 | remember constructors from define() for later cleanup (src changed, maybe we should support hotswap here?) |
 

packages/vfx/src/shadow-objects/README.md

@@ -0,0 +1,21 @@
+
+### VfxDisplay
+
+the vfx-display represents an offscreen canvas. however, a canvas _context_ is not created.
+
+these contexts are provided:
+
+| context name | type | description |
+|------|------|-------------|
+| `canvas` | [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas) | the offscreen canvas connected to the canvas element in the main document |
+| `canvasSize` | [**width**: _number_, **height**: _number_, **pixelRatio**: _number_] | the size of the canvas element in _device pixels_. i.e. the pixelRatio is already included in the width and height specification. if you want the _css pixels_, divide the width and height by the pxelRatio |
+
+In addition, the `onRenderFrame` event is dispatched to the entity and its children.
+
+The `onRenderFrame` event comes with a data object:
+
+| property | type | description |
+|----------|------|-------------|
+| `canvas` | [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas) | the offscreen canvas object, which is also offered as context |
+| `now` | _number_ | the current time in seconds. see [performance.now](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) |
+| `frameNo` | _number_ | a frame counter. starts at 0.

packages/vfx/src/shadow-objects/VfxDisplay.js

@@ -50,13 +50,6 @@ export class VfxDisplay {
 
         if (isNaN(w) || isNaN(h) || isNaN(pixelRatio)) return;
 
-        // if (canvas.width !== w || canvas.height !== h) {
-        //   canvas.width = w;
-        //   canvas.height = h;
-        // }
-        //
-        // setCanvasSize([w, h, pixelRatio]);
-
         const canvasWidth = Math.round(w * pixelRatio);
         const canvasHeight = Math.round(h * pixelRatio);
 
@@ -116,6 +109,5 @@ export class VfxDisplay {
 
     const data = {canvas: this.canvas, now: this.now, frameNo: this.frameNo};
     this.entity.traverse((entity) => entity.emit('onRenderFrame', data));
-    // TODO maybe we should create a `<shadow-entity traverse-events="onRenderFrame, onIdle">` attribute ?
   }
 }