Merge branch 'main' into fix/imageworker-initialisation

examples/tests/rtt-nested-clipping.ts

@@ -0,0 +1,76 @@
+import type { ExampleSettings } from '../common/ExampleSettings.js';
+import rocko from '../assets/rocko.png';
+
+export default async function test({ renderer, testRoot }: ExampleSettings) {
+  const node = renderer.createNode({
+    x: 0,
+    y: 0,
+    width: 1920,
+    height: 1080,
+    color: 0x000000ff,
+    parent: testRoot,
+  });
+
+  // RTT Node 1
+  const rttNode = renderer.createNode({
+    x: 100,
+    y: 200,
+    width: 400,
+    height: 400,
+    parent: node,
+    rtt: true,
+    zIndex: 5,
+    colorTop: 0xfff00fff,
+    colorBottom: 0x00ffffff,
+  });
+
+  const rect = renderer.createNode({
+    x: 0,
+    y: 0,
+    width: 300,
+    height: 300,
+    parent: rttNode,
+    clipping: true,
+    color: 0xff0000ff,
+  });
+
+  renderer.createTextNode({
+    x: 0,
+    y: 0,
+    text: 'Render to texture',
+    parent: rttNode,
+    fontSize: 48,
+    color: 0xffffffff,
+    fontFamily: 'Ubuntu',
+  });
+
+  renderer.createNode({
+    x: 50,
+    y: 100,
+    width: 600,
+    height: 600,
+    parent: rttNode,
+    src: rocko,
+  });
+
+  window.addEventListener('keydown', (e) => {
+    if (e.key === 's') {
+      // rect.clipping = !rect.clipping;
+      rect
+        .animate(
+          {
+            x: 100, //going to render out of bounds as well
+          },
+          {
+            duration: 3000,
+            easing: 'ease-out',
+            loop: true,
+            stopMethod: 'reverse',
+          },
+        )
+        .start();
+    }
+  });
+
+  // Define the page function to configure different test scenarios
+}

package.json

@@ -16,7 +16,7 @@
     "start": "cd examples && pnpm start",
     "start:prod": "cd examples && pnpm start:prod",
     "build": "tsc --build",
-    "build:docker": "docker build -t visual-regression .",
+    "build:docker": "cd visual-regression && pnpm build:docker",
     "watch": "tsc --build --watch",
     "test": "vitest",
     "coverage": "vitest run --coverage",

src/core/renderers/webgl/WebGlCoreRenderOp.ts

@@ -23,11 +23,9 @@ import type { WebGlCoreCtxTexture } from './WebGlCoreCtxTexture.js';
 import type { WebGlCoreRendererOptions } from './WebGlCoreRenderer.js';
 import type { BufferCollection } from './internal/BufferCollection.js';
 import type { Dimensions } from '../../../common/CommonTypes.js';
-import type { Rect, RectWithValid } from '../../lib/utils.js';
+import type { RectWithValid } from '../../lib/utils.js';
 import type { WebGlContextWrapper } from '../../lib/WebGlContextWrapper.js';
 
-const MAX_TEXTURES = 8; // TODO: get from gl
-
 /**
  * Can render multiple quads with multiple textures (up to vertex shader texture limit)
  *
@@ -95,13 +93,22 @@ export class WebGlCoreRenderOp extends CoreRenderOp {
     // Clipping
     if (this.clippingRect.valid) {
       const { x, y, width, height } = this.clippingRect;
-      const pixelRatio = options.pixelRatio;
+      const pixelRatio = this.parentHasRenderTexture ? 1 : options.pixelRatio;
       const canvasHeight = options.canvas.height;
 
       const clipX = Math.round(x * pixelRatio);
       const clipWidth = Math.round(width * pixelRatio);
       const clipHeight = Math.round(height * pixelRatio);
-      const clipY = Math.round(canvasHeight - clipHeight - y * pixelRatio);
+      let clipY = Math.round(canvasHeight - clipHeight - y * pixelRatio);
+
+      // if parent has render texture, we need to adjust the scissor rect
+      // to be relative to the parent's framebuffer
+      if (this.parentHasRenderTexture) {
+        clipY = this.framebufferDimensions
+          ? this.framebufferDimensions.height - this.dimensions.height
+          : 0;
+      }
+
       glw.setScissorTest(true);
       glw.scissor(clipX, clipY, clipWidth, clipHeight);
     } else {

visual-regression/DOCKER.md

@@ -1,75 +1,149 @@
 # Visual Regression Test Docker Instructions
 
-The Visual Regression Tests utilize headless browsers provided by the
-[Playwright](https://playwright.dev/) project. Browsers tend to be very platform
-specific in terms of exactly how pixels end up being rendered out. The
-differences should be small, but they tend to be big enough such that a simple
-image comparison algorithm cannot reliably tell what is a real regression and
-what is just a platform difference.
+The Visual Regression Tests utilize headless browsers provided by the [Playwright](https://playwright.dev/) project. Browsers are highly platform-specific, and even small pixel differences can cause significant issues for image comparison algorithms. These differences can prevent reliable detection of regressions.
 
-In order to prevent this issue, the Visual Regression Tests are built to run
-inside a Docker container which guarantees a consistent platform environment
-for the given headless browser to run in.
+To avoid these issues, Visual Regression Tests run inside a containerized environment. This guarantees a consistent platform for headless browsers, ensuring reproducible results.
 
-Whenever new commits to a PR are pushed, a GitHub Action runs the Visual
-Regression Tests in a Linux-based Docker container to determine if the PR should
-be allowed to merge or not.
+For PRs, a GitHub Action runs these tests in a Linux-based container. Locally, you must use `--ci` mode, which launches tests in a container to produce snapshots identical to the GitHub Action environment.
 
-When you need to capture new snapshots or update existing ones, you must run the
-Visual Regression Test Runner locally in `--ci` mode. This launches the tests in
-a Docker container giving you exactly the same snapshot results as the tests
-that run in the cloud on GitHub Actions.
+This guide covers installing the required tools (`docker`, `colima`, or `podman`) and building the Visual Regression Test image.
 
-Below are the instructions for both installing Docker and building the Visual
-Regression Test Image that is used when you run the tests in `--ci`.
+---
 
-## Installing Docker
+## Installing a Container Runtime
 
 ### Mac
 
-If you have a license for [Docker Desktop](https://www.docker.com/products/docker-desktop/)
-you can install that and all should be well. However, if you don't follow the
-alternative steps below:
+You can use Docker Desktop if you have a license. If you don’t, use Colima or Podman as alternatives.
+
+#### Option 1: Docker Desktop (Requires License)
+
+1. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop).
+2. After installation, test Docker:
+   ```bash
+   docker ps
+   ```
+
+#### Option 2: Colima (Open Source Docker Alternative)
+
+1. Install the Docker CLI using [Homebrew](https://brew.sh/):
+   ```bash
+   brew install docker
+   ```
+2. Install [Colima](https://colima.dev/):
+   ```bash
+   brew install colima
+   ```
+3. Start Colima:
+   ```bash
+   colima start
+   ```
+4. Test Docker with Colima:
+   ```bash
+   docker ps
+   ```
+   It should run without errors.
+
+#### Option 3: Podman (Docker Alternative)
+
+1. Install [Podman](https://podman.io/):
+   ```bash
+   brew install podman
+   ```
+2. Start Podman:
+   ```bash
+   podman machine init
+   podman machine start
+   ```
+3. Test Podman:
+   ```bash
+   podman ps
+   ```
+
+### Linux
+
+Docker is natively supported on Linux, but you can also use Podman for a rootless container environment.
+
+#### Option 1: Docker
+
+1. Follow the instructions for your Linux distribution to install Docker:
+   - [Ubuntu/Debian](https://docs.docker.com/engine/install/debian/)
+   - [Fedora/CentOS](https://docs.docker.com/engine/install/centos/)
+2. After installation, test Docker:
+   ```bash
+   docker ps
+   ```
+
+#### Option 2: Podman
+
+1. Install [Podman](https://podman.io/) for your Linux distribution:
+   - [Podman Installation Guide](https://podman.io/getting-started/installation)
+2. Test Podman:
+   ```bash
+   podman ps
+   ```
+
+### Windows
+
+Windows users can use Docker Desktop if they have a license or install Podman as an alternative.
+
+#### Option 1: Docker Desktop (Requires License)
+
+1. Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop).
+2. After installation, test Docker:
+   ```powershell
+   docker ps
+   ```
+
+#### Option 2: Podman (Open Source Alternative)
+
+1. Install [Podman](https://podman.io/) via the Windows installer:
+   - [Podman for Windows](https://podman.io/getting-started/installation)
+2. Start the Podman machine:
+   ```powershell
+   podman machine init
+   podman machine start
+   ```
+3. Test Podman:
+   ```powershell
+   podman ps
+   ```
+
+---
 
-1. Using [Homebrew](https://brew.sh/) install the Docker Client:
-
-```
-brew install docker
-```
+## Building the Test Image
 
-2. Install [Colima](https://github.com/abiosoft/colima)
+After installing a container runtime, you must build the Visual Regression Test image.
 
-```
-brew install colima
-```
+1. Run the build script:
 
-3. Start Colima
+   ```bash
+   pnpm build:docker
+   ```
 
-```
-colima start
-```
+2. The script automatically detects your runtime (`docker` or `podman`) and builds the image. After a successful build, you should see the image:
 
-4. Test Docker
+   ```bash
+   docker images
+   ```
 
-```
-docker ps
-```
+   Or, if using Podman:
 
-It should run without errors.
+   ```bash
+   podman images
+   ```
 
-## Building the Test Image
+   Example output:
 
-After installing Docker, you must build the Visual Regression Test Image before
-running the test runner in `--ci` mode.
+   ```
+   REPOSITORY                     TAG             IMAGE ID       CREATED         SIZE
+   visual-regression              latest          40476ed4acae   3 minutes ago   2.09GB
+   ```
 
-```
-pnpm build:docker
-```
+---
 
-If all goes well it should create an image called **visual-regression** locally.
+## References
 
-```
-❯ docker images
-REPOSITORY                     TAG             IMAGE ID       CREATED         SIZE
-visual-regression              latest          40476ed4acae   3 minutes ago   2.09GB
-```
+- **Docker Desktop**: [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
+- **Colima**: [colima.dev](https://colima.dev/)
+- **Podman**: [podman.io](https://podman.io/)

visual-regression/package.json

@@ -11,7 +11,7 @@
     "build": "tsc",
     "build:renderer": "cd .. && pnpm build",
     "build:examples": "cd ../examples && pnpm build",
-    "build:docker": "cd .. && pnpm build:docker",
+    "build:docker": "tsc && node dist/src/build-docker.js",
     "serve-examples": "cd ../examples && pnpm preview:automation",
     "node-version": "node --version"
   },

visual-regression/src/build-docker.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env ts-node
+
+import { $ } from 'execa';
+import { argv } from 'process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { detectContainerRuntime } from './detectDockerRuntime.js';
+
+/**
+ * Builds a container image using the detected container runtime.
+ * Changes the working directory to one level higher than the script's location.
+ * @param runtime - The container runtime (`podman` or `docker`).
+ * @param imageName - The name of the container image to build.
+ */
+async function buildContainer(
+  runtime: string,
+  imageName: string,
+): Promise<void> {
+  // Change working directory to one level higher than the script's location
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const scriptDir = path.resolve(__dirname, '../../../');
+  process.chdir(scriptDir);
+
+  console.log(`Working directory changed to: ${scriptDir}`);
+  console.log(`Using ${runtime} to build the container image: ${imageName}`);
+  try {
+    await $({ stdio: 'inherit' })`${runtime} build -t ${imageName} .`;
+  } catch (error) {
+    console.error(`Failed to build the image with ${runtime}.`, error);
+    process.exit(1);
+  }
+}
+
+(async () => {
+  const imageName = argv[2] || 'visual-regression'; // Default image name
+  try {
+    const runtime = await detectContainerRuntime();
+    await buildContainer(runtime, imageName);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    } else {
+      console.error(error);
+    }
+    process.exit(1);
+  }
+})();