@quake2ts/test-utils 0.0.764 → 0.0.766

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quake2ts/test-utils",
-  "version": "0.0.764",
+  "version": "0.0.766",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,6 +20,11 @@
       "types": "./src/setup/webgpu.ts",
       "import": "./src/setup/webgpu.ts",
       "require": "./src/setup/webgpu.ts"
+    },
+    "./src/setup/headless-webgl": {
+      "types": "./src/setup/headless-webgl.ts",
+      "import": "./src/setup/headless-webgl.ts",
+      "require": "./src/setup/headless-webgl.ts"
     }
   },
   "files": [
@@ -39,10 +44,10 @@
     "pngjs": "^7.0.0",
     "vitest": "^1.6.0",
     "webgpu": "^0.3.8",
-    "@quake2ts/engine": "^0.0.764",
-    "@quake2ts/server": "0.0.764",
-    "@quake2ts/game": "0.0.764",
-    "@quake2ts/shared": "0.0.764"
+    "@quake2ts/engine": "^0.0.766",
+    "@quake2ts/game": "0.0.766",
+    "@quake2ts/server": "0.0.766",
+    "@quake2ts/shared": "0.0.766"
   },
   "peerDependenciesMeta": {
     "@quake2ts/engine": {
@@ -93,10 +98,10 @@
     "typescript": "^5.4.5",
     "vitest": "^1.6.0",
     "webgpu": "^0.3.8",
-    "@quake2ts/engine": "^0.0.764",
-    "@quake2ts/game": "0.0.764",
-    "@quake2ts/server": "0.0.764",
-    "@quake2ts/shared": "0.0.764"
+    "@quake2ts/engine": "^0.0.766",
+    "@quake2ts/game": "0.0.766",
+    "@quake2ts/server": "0.0.766",
+    "@quake2ts/shared": "0.0.766"
   },
   "optionalDependencies": {
     "gl": "^8.1.6"

package/src/engine/helpers/webgl-rendering.ts

@@ -0,0 +1,47 @@
+import { createHeadlessWebGL, captureWebGLFramebuffer, HeadlessWebGLContext } from '../../setup/headless-webgl.js';
+// Removed invalid import
+
+export interface WebGLRenderTestSetup {
+  gl: WebGL2RenderingContext;
+  width: number;
+  height: number;
+  cleanup: () => void;
+}
+
+/**
+ * Creates a setup for testing WebGL rendering.
+ * Initializes a headless WebGL context.
+ */
+export async function createWebGLRenderTestSetup(
+  width: number = 256,
+  height: number = 256
+): Promise<WebGLRenderTestSetup> {
+  const context = createHeadlessWebGL({ width, height });
+
+  return {
+    gl: context.gl,
+    width: context.width,
+    height: context.height,
+    cleanup: context.cleanup
+  };
+}
+
+/**
+ * Helper to render and capture the output as pixel data.
+ * Executes the render function, ensures completion, and captures the framebuffer.
+ */
+export async function renderAndCaptureWebGL(
+  setup: WebGLRenderTestSetup,
+  renderFn: (gl: WebGL2RenderingContext) => void
+): Promise<Uint8ClampedArray> {
+  const { gl, width, height } = setup;
+
+  // Execute the user's render function
+  renderFn(gl);
+
+  // Ensure all commands are finished before reading pixels
+  gl.finish();
+
+  // Capture the framebuffer content
+  return captureWebGLFramebuffer(gl, width, height);
+}

package/src/index.ts

@@ -29,7 +29,8 @@ export * from './server/helpers/bandwidth.js';
 export * from './setup/browser.js';
 export * from './setup/canvas.js';
 export * from './setup/webgpu.js';
-export * from './setup/headless-webgl.js'; // Added
+// Safe to export now as gl is lazy loaded
+export * from './setup/headless-webgl.js';
 export * from './engine/mocks/webgpu.js';
 export * from './setup/timing.js';
 export * from './setup/node.js';
@@ -44,6 +45,7 @@ export * from './engine/rendering.js';
 export * from './setup/storage.js';
 export * from './setup/audio.js';
 export * from './engine/helpers/webgpu-rendering.js';
+export * from './engine/helpers/webgl-rendering.js';
 export * from './engine/helpers/pipeline-test-template.js';
 
 // Client Mocks
@@ -72,8 +74,9 @@ export type { StorageScenario } from './setup/storage.js';
 export type { NetworkSimulator, NetworkCondition } from './e2e/network.js';
 export type { VisualScenario, VisualDiff } from './e2e/visual.js';
 export type { HeadlessWebGPUSetup, WebGPUContextState } from './setup/webgpu.js';
-export type { HeadlessWebGLContext, HeadlessWebGLOptions } from './setup/headless-webgl.js'; // Added
+export type { HeadlessWebGLContext, HeadlessWebGLOptions } from './setup/headless-webgl.js';
 export type { RenderTestSetup, ComputeTestSetup } from './engine/helpers/webgpu-rendering.js';
+export type { WebGLRenderTestSetup } from './engine/helpers/webgl-rendering.js';
 export type { GeometryBuffers } from './engine/helpers/pipeline-test-template.js';
 
 // Shared Types

package/src/setup/headless-webgl.ts

@@ -1,3 +1,7 @@
+// Remove top-level import to avoid runtime crash when gl is missing
+// import createGL from 'gl';
+import type { WebGLContextState } from '@quake2ts/engine';
+
 export interface HeadlessWebGLOptions {
   width?: number;
   height?: number;
@@ -14,99 +18,98 @@ export interface HeadlessWebGLContext {
 
 /**
  * Creates a headless WebGL2 context using the 'gl' package.
- * Note: 'gl' is lazy-loaded to avoid issues in environments where it's not supported/needed.
+ * This is used for running WebGL tests in a Node.js environment without a browser.
  */
-export async function createHeadlessWebGL(
+export function createHeadlessWebGL(
   options: HeadlessWebGLOptions = {}
-): Promise<HeadlessWebGLContext> {
+): HeadlessWebGLContext {
   const width = options.width ?? 256;
   const height = options.height ?? 256;
 
-  // Dynamically import gl
-  // @ts-ignore - gl package might not be typed correctly for dynamic import or TS config
-  const { default: gl } = await import('gl');
+  let createGL;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    createGL = require('gl');
+  } catch (e) {
+    throw new Error('gl package not found or failed to load. Install it to run WebGL tests.');
+  }
 
-  // The 'gl' function signature is gl(width, height, options)
-  const context = gl(width, height, {
-    antialias: options.antialias ?? false, // Default to false for determinism
-    preserveDrawingBuffer: options.preserveDrawingBuffer ?? true, // Default to true for readback
+  // Create WebGL context using 'gl' package
+  const glContext = createGL(width, height, {
+    antialias: options.antialias ?? false, // Default to false for deterministic testing
+    preserveDrawingBuffer: options.preserveDrawingBuffer ?? true, // Needed for readback
     stencil: true,
-    alpha: true,
     depth: true,
+    alpha: true
   });
 
-  if (!context) {
+  if (!glContext) {
     throw new Error('Failed to create headless WebGL context');
   }
 
-  // Cast to WebGL2RenderingContext
-  const glContext = context as unknown as WebGL2RenderingContext;
+  // Cast to WebGL2RenderingContext as 'gl' returns a compatible interface
+  // but TypeScript types might not align perfectly without casting
+  const gl = glContext as unknown as WebGL2RenderingContext;
+
+  // Verify context creation
+  const version = gl.getParameter(gl.VERSION);
+  // console.log(`Created headless WebGL context: ${version}`);
+
+  // Create cleanup function
+  const cleanup = () => {
+    const ext = gl.getExtension('STACKGL_destroy_context');
+    if (ext) {
+      ext.destroy();
+    }
+  };
 
   return {
-    gl: glContext,
+    gl,
     width,
     height,
-    cleanup: () => {
-      // gl package extension to destroy context
-      const ext = glContext.getExtension('STACKGL_destroy_context');
-      if (ext) {
-        ext.destroy();
-      }
-    },
+    cleanup
   };
 }
 
 /**
- * Captures the current framebuffer content as a Uint8ClampedArray (RGBA).
- * Flips the pixels vertically to match standard image orientation (top-left origin).
+ * Captures the current framebuffer content as a pixel array.
+ * Performs a vertical flip to match standard image coordinates (top-left origin).
  */
 export function captureWebGLFramebuffer(
-  glContext: WebGL2RenderingContext,
+  gl: WebGL2RenderingContext,
   width: number,
   height: number
 ): Uint8ClampedArray {
   const pixels = new Uint8ClampedArray(width * height * 4);
 
-  // readPixels reads from bottom-left
-  glContext.readPixels(
-    0,
-    0,
-    width,
-    height,
-    glContext.RGBA,
-    glContext.UNSIGNED_BYTE,
-    pixels
-  );
+  // Read pixels from framebuffer (bottom-left origin)
+  gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
 
+  // Flip vertically to match image coordinates (top-left origin)
   return flipPixelsVertically(pixels, width, height);
 }
 
 /**
- * Flips pixel data vertically in-place.
+ * Flips a pixel array vertically in-place or returns a new array.
+ * WebGL reads pixels bottom-up, but images are typically stored top-down.
  */
 export function flipPixelsVertically(
   pixels: Uint8ClampedArray,
   width: number,
   height: number
 ): Uint8ClampedArray {
+  const flipped = new Uint8ClampedArray(pixels.length);
   const rowSize = width * 4;
-  const halfHeight = Math.floor(height / 2);
-  const tempRow = new Uint8Array(rowSize);
-
-  // Swap rows
-  for (let y = 0; y < halfHeight; y++) {
-    const topOffset = y * rowSize;
-    const bottomOffset = (height - 1 - y) * rowSize;
-
-    // Copy top to temp
-    tempRow.set(pixels.subarray(topOffset, topOffset + rowSize));
 
-    // Copy bottom to top
-    pixels.copyWithin(topOffset, bottomOffset, bottomOffset + rowSize);
+  for (let y = 0; y < height; y++) {
+    const srcRowStart = y * rowSize;
+    const destRowStart = (height - 1 - y) * rowSize;
 
-    // Copy temp to bottom
-    pixels.set(tempRow, bottomOffset);
+    // Copy row
+    for (let i = 0; i < rowSize; i++) {
+      flipped[destRowStart + i] = pixels[srcRowStart + i];
+    }
   }
 
-  return pixels;
+  return flipped;
 }