@geastack/native-webgl-angle 0.1.6

package/src/text/native-text-types.ts

@@ -0,0 +1,17 @@
+// Shape of a baked glyph atlas (native-webgl-angle/tools/bake-font-atlas.cpp
+// via gen-troika-atlas.mjs). Glyph rows are [x0, y0, x1, y1, xoff, yoff,
+// xadvance] in atlas pixels at `pixelHeight`; kerning rows are
+// [codepointA, codepointB, advancePx].
+export interface GlyphAtlas {
+  name: string
+  atlasWidth: number
+  atlasHeight: number
+  pixelHeight: number
+  ascent: number
+  descent: number
+  lineGap: number
+  first: number
+  glyphs: number[][]
+  kerning: number[][]
+  alphaBase64: string[]
+}

package/src/text/native-text.ts

@@ -0,0 +1,203 @@
+// Native text rendering for the troika-three-text Text surface: baked alpha glyph
+// atlases (stb_truetype, build-time) drawn as textured quads. This is the
+// "engine stb_truetype -> GL atlas" path — it runs on
+// any three-angle target (macOS/ANGLE, Windows) with zero host dependencies: the
+// atlas rides in the compiled binary and uploads as a DataTexture.
+import { BufferAttribute } from 'three/src/core/BufferAttribute.js'
+import { BufferGeometry } from 'three/src/core/BufferGeometry.js'
+import { DataTexture } from 'three/src/textures/DataTexture.js'
+import {
+  ClampToEdgeWrapping,
+  LinearFilter,
+  NoColorSpace,
+  RGBAFormat,
+  UnsignedByteType,
+  UVMapping,
+} from 'three/src/constants.js'
+import type { GlyphAtlas } from './native-text-types'
+export interface LaidOutText {
+  geometry: BufferGeometry
+  positions: Float32Array
+  width: number
+  ascent: number
+  descent: number
+}
+
+// Caches keyed by the atlas NAME: GlyphAtlas is an interface (by-value
+// struct under geatsc), so identity comparison on module reads never hits —
+// which would re-decode and re-upload the 1MB texture on every sync
+// (measured: 0.2 fps). String keys are stable across copies.
+const textureCacheKeys: string[] = []
+const textureCacheValues: DataTexture[] = []
+
+function base64Value(code: number): number {
+  if (code >= 65 && code <= 90) return code - 65
+  if (code >= 97 && code <= 122) return code - 71
+  if (code >= 48 && code <= 57) return code + 4
+  if (code === 43) return 62
+  if (code === 47) return 63
+  return 0
+}
+
+// Decode the base64 alpha bitmap into an RGBA texture (white RGB, glyph
+// alpha). Built once per atlas and shared by every text instance.
+export function atlasTexture(atlas: GlyphAtlas): DataTexture {
+  for (let i = 0; i < textureCacheKeys.length; i++) {
+    if (textureCacheKeys[i] === atlas.name) return textureCacheValues[i]
+  }
+  const total = atlas.atlasWidth * atlas.atlasHeight
+  const rgba = new Uint8Array(total * 4)
+  let out = 0
+  for (let c = 0; c < atlas.alphaBase64.length; c++) {
+    // Do not route through atob's "binary string". The native runtime stores
+    // strings as UTF-8, so bytes >= 0x80 would be interpreted as Unicode when
+    // charCodeAt reads the result, corrupting the alpha atlas. Decode the ASCII
+    // base64 directly into the typed array instead.
+    const chunk = atlas.alphaBase64[c]
+    for (let i = 0; i < chunk.length; i += 4) {
+      const code2 = chunk.charCodeAt(i + 2)
+      const code3 = chunk.charCodeAt(i + 3)
+      const v0 = base64Value(chunk.charCodeAt(i))
+      const v1 = base64Value(chunk.charCodeAt(i + 1))
+      const v2 = base64Value(code2)
+      const v3 = base64Value(code3)
+      const a0 = (v0 << 2) | (v1 >> 4)
+      rgba[out] = 255
+      rgba[out + 1] = 255
+      rgba[out + 2] = 255
+      rgba[out + 3] = a0
+      out += 4
+      if (code2 !== 61) {
+        const a1 = ((v1 & 15) << 4) | (v2 >> 2)
+        rgba[out] = 255
+        rgba[out + 1] = 255
+        rgba[out + 2] = 255
+        rgba[out + 3] = a1
+        out += 4
+      }
+      if (code3 !== 61) {
+        const a2 = ((v2 & 3) << 6) | v3
+        rgba[out] = 255
+        rgba[out + 1] = 255
+        rgba[out + 2] = 255
+        rgba[out + 3] = a2
+        out += 4
+      }
+    }
+  }
+  const tex = new DataTexture(
+    rgba,
+    atlas.atlasWidth,
+    atlas.atlasHeight,
+    RGBAFormat,
+    UnsignedByteType,
+    UVMapping,
+    ClampToEdgeWrapping,
+    ClampToEdgeWrapping,
+    LinearFilter,
+    LinearFilter,
+    1,
+    NoColorSpace,
+  )
+  tex.needsUpdate = true
+  textureCacheKeys.push(atlas.name)
+  textureCacheValues.push(tex)
+  return tex
+}
+
+const kerningCacheKeys: string[] = []
+const kerningCacheValues: Map<number, number>[] = []
+
+function kerningTable(atlas: GlyphAtlas): Map<number, number> {
+  for (let i = 0; i < kerningCacheKeys.length; i++) {
+    if (kerningCacheKeys[i] === atlas.name) return kerningCacheValues[i]
+  }
+  const table = new Map<number, number>()
+  for (const row of atlas.kerning) {
+    table.set(row[0] * 1024 + row[1], row[2])
+  }
+  kerningCacheKeys.push(atlas.name)
+  kerningCacheValues.push(table)
+  return table
+}
+
+// Build quad geometry for `text` at `fontSize` world units per em.
+// letterSpacing is in em units (troika convention). Multi-line via '\n'.
+// The origin is the LEFT edge of the FIRST baseline; the caller applies
+// anchor offsets from the returned metrics.
+export function layoutText(
+  atlas: GlyphAtlas,
+  text: string,
+  fontSize: number,
+  letterSpacing: number,
+): LaidOutText {
+  const scale = fontSize / atlas.pixelHeight
+  const lineHeight = (atlas.ascent - atlas.descent + atlas.lineGap) * scale
+  const kern = kerningTable(atlas)
+  const positions: number[] = []
+  const uvs: number[] = []
+  const indices: number[] = []
+  let penX = 0
+  let penY = 0
+  let maxX = 0
+  let prev = 0
+  const invW = 1 / atlas.atlasWidth
+  const invH = 1 / atlas.atlasHeight
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    if (code === 10) {
+      if (penX > maxX) maxX = penX
+      penX = 0
+      penY -= lineHeight
+      prev = 0
+      continue
+    }
+    const index = code - atlas.first
+    if (index < 0 || index >= atlas.glyphs.length) continue
+    if (prev !== 0) {
+      const k = kern.get(prev * 1024 + code)
+      if (k !== undefined) penX += k * scale
+    }
+    const g = atlas.glyphs[index]
+    const gx0 = g[0]
+    const gy0 = g[1]
+    const gx1 = g[2]
+    const gy1 = g[3]
+    const xoff = g[4]
+    const yoff = g[5]
+    const xadvance = g[6]
+    if (gx1 > gx0 && gy1 > gy0) {
+      // yoff is the offset of the bitmap TOP from the baseline (negative up
+      // in stb's y-down convention); flip into three's y-up space.
+      const x0 = penX + xoff * scale
+      const y1 = penY - yoff * scale
+      const x1 = x0 + (gx1 - gx0) * scale
+      const y0 = y1 - (gy1 - gy0) * scale
+      const base = positions.length / 3
+      positions.push(x0, y0, 0, x1, y0, 0, x1, y1, 0, x0, y1, 0)
+      // DataTexture rows upload bottom-up (flipY=false): atlas row 0 (top of
+      // the baked image) lands at v=0, so v maps directly from atlas y.
+      const u0 = gx0 * invW
+      const u1 = gx1 * invW
+      const v0 = gy1 * invH
+      const v1 = gy0 * invH
+      uvs.push(u0, v0, u1, v0, u1, v1, u0, v1)
+      indices.push(base, base + 1, base + 2, base, base + 2, base + 3)
+    }
+    penX += xadvance * scale + letterSpacing * fontSize
+    prev = code
+  }
+  if (penX > maxX) maxX = penX
+  const positionArray = new Float32Array(positions)
+  const geometry = new BufferGeometry()
+  geometry.setAttribute('position', new BufferAttribute(positionArray, 3))
+  geometry.setAttribute('uv', new BufferAttribute(new Float32Array(uvs), 2))
+  geometry.setIndex(indices)
+  return {
+    geometry,
+    positions: positionArray,
+    width: maxX,
+    ascent: atlas.ascent * scale,
+    descent: atlas.descent * scale,
+  }
+}

package/src/troika-three-text.ts

@@ -0,0 +1,248 @@
+// Native-target implementation of the `troika-three-text` Text surface.
+//
+// troika-three-text renders SDF glyphs via a Web Worker + runtime font parsing,
+// neither of which is available on the native/ANGLE target. Browser builds use
+// the upstream package; native target resolution selects this module, which renders the
+// SAME property surface (text/font/fontSize/color/anchorX/anchorY/letterSpacing/
+// fillOpacity + sync()) from build-time stb_truetype glyph atlases (see
+// native-webgl-angle/tools/bake-font-atlas.cpp) drawn as textured quads.
+//
+// Font selection consults the atlases an app registered with
+// registerFontAtlas(); the Playfair regular/italic and Inter atlases this
+// package bakes are the defaults behind them.
+//
+// Import from the specific `three/src` path (NOT bare `three`): a bare-`three`
+// import resolves to the pre-bundled `three/build/three.module.js`, which emits
+// duplicate cross-module classes (Vector2__m2, "incomplete type") and drags the
+// entire library into the compile graph.
+import { DoubleSide } from 'three/src/constants.js'
+import { Mesh } from 'three/src/objects/Mesh.js'
+import { BufferAttribute } from 'three/src/core/BufferAttribute.js'
+import { BufferGeometry } from 'three/src/core/BufferGeometry.js'
+import { MeshBasicMaterial } from 'three/src/materials/MeshBasicMaterial.js'
+import { Object3D } from 'three/src/core/Object3D.js'
+import type { Texture } from 'three/src/textures/Texture.js'
+import { atlasTexture, layoutText } from './text/native-text'
+import type { GlyphAtlas } from './text/native-text-types'
+import { sansAtlas } from './text/atlas-sans'
+import { serifAtlas } from './text/atlas-serif'
+import { serifItalicAtlas } from './text/atlas-serif-italic'
+
+// The fonts belong to the app, not to this package. Selecting them by the
+// names one app happens to use -- 'playfair', 'italic' -- meant every other app
+// rendered its whole UI in the fallback sans while nothing reported a problem:
+// the reference app's Unbounded display face silently became Inter. An app whose own
+// fonts must render natively bakes them (tools/bake-font-atlas.cpp, then
+// tools/gen-troika-atlas.mjs) and registers them from its native entry, before
+// the first Text is constructed. The three below stay as this package's
+// defaults so an app that registers nothing still draws.
+interface RegisteredAtlas {
+  match: string
+  atlas: GlyphAtlas
+}
+
+const registered: RegisteredAtlas[] = []
+
+/**
+ * Map a substring of the app's `font` value (a bundler asset URL, so matching
+ * the file stem is enough) onto a baked atlas. Later registrations win over the
+ * built-in defaults but not over earlier ones, so registration order is the
+ * app's priority order.
+ */
+export function registerFontAtlas(match: string, atlas: GlyphAtlas): void {
+  registered.push({ match, atlas })
+}
+
+// One authority for "which atlas is this font", because sync() needs the
+// identity for its layout key and the layout itself needs the atlas; resolving
+// them separately is how the two could ever disagree.
+function atlasNameForFont(font: string | null): string {
+  if (font === null) return 'sans'
+  for (let i = 0; i < registered.length; i++) {
+    const entry = registered[i]
+    if (entry !== undefined && font.indexOf(entry.match) >= 0) return entry.match
+  }
+  if (font.indexOf('italic') >= 0) return 'serif-italic'
+  if (font.indexOf('playfair') >= 0) return 'serif'
+  return 'sans'
+}
+
+function atlasForFont(font: string | null): GlyphAtlas {
+  const name = atlasNameForFont(font)
+  for (let i = 0; i < registered.length; i++) {
+    const entry = registered[i]
+    if (entry !== undefined && entry.match === name) return entry.atlas
+  }
+  if (name === 'serif-italic') return serifItalicAtlas
+  if (name === 'serif') return serifAtlas
+  return sansAtlas
+}
+
+function srgbToLinear(value: number): number {
+  return value < 0.04045 ? value * 0.0773993808 : Math.pow(value * 0.9478672986 + 0.0521327014, 2.4)
+}
+
+function setMaterialHex(material: MeshBasicMaterial, value: number): void {
+  material.color.r = srgbToLinear(((value >> 16) & 0xff) / 255)
+  material.color.g = srgbToLinear(((value >> 8) & 0xff) / 255)
+  material.color.b = srgbToLinear((value & 0xff) / 255)
+}
+
+// NOTE: the class must NOT be named `Text` — geatsc's gea host-shim maps any
+// type named `Text` (the DOM global) to `gea::embedded::ui::NodeHandle`, so a
+// class named `Text` would lower to a NodeHandle (no `.sync()`/`.visible`).
+// Name it `TroikaText` and re-export as `Text` so the upstream package's
+// import surface is unchanged while the class keeps its own native struct type.
+export class TroikaText extends Object3D {
+  text = ''
+  font: string | null = null
+  fontSize = 1
+  color: number = 0xffffff
+  anchorX: number | string = 'center'
+  anchorY: number | string = 'middle'
+  letterSpacing = 0
+  fillOpacity = 1
+  depthOffset = 0
+  outlineWidth: number | string = 0
+  outlineColor: number | string = 0x000000
+  material: MeshBasicMaterial
+  private mesh: Mesh
+  // Layout fingerprint of the last geometry build. HUD callers (troika
+  // convention) call sync() every frame while pulsing fillOpacity/color;
+  // rebuilding glyph quads for that is pure waste — only rebuild when an
+  // input that changes GEOMETRY changed.
+  private layoutKey = '\u0000'
+
+  constructor() {
+    super()
+    this.material = new MeshBasicMaterial({
+      transparent: true,
+      depthWrite: false,
+      side: DoubleSide,
+      // Flat glyph quads never need Three's transparent double-sided two-pass
+      // path. Without this, Three flips `side` twice per label per frame,
+      // increments material.version, and rebuilds the program-parameter graph.
+      forceSinglePass: true
+    })
+    this.mesh = new Mesh(new BufferGeometry(), this.material)
+    // This mesh lives in the orthographic HUD pass. Its bounds are rebuilt
+    // whenever glyph geometry changes, and native Three can otherwise retain
+    // the empty constructor geometry's bounds until a later text update. HUD
+    // glyphs are screen-space by definition, so frustum culling is both
+    // unnecessary and capable of hiding labels that never change after mount.
+    this.mesh.frustumCulled = false
+    this.add(this.mesh)
+  }
+
+  // No callback param: troika's real sync(cb?) is async, but this native stub
+  // lays out synchronously, so every caller invokes sync() with no argument.
+  // Declaring an optional callback made the dynamic (duck-typed) call site in
+  // hud.ts lower the absent arg into a non-empty std::function that invokes a
+  // `missing` value ("Value is not callable"); omitting it removes that path.
+  sync(): void {
+    // Compute the cheap font identity first. GlyphAtlas is a large generated
+    // by-value struct under geatsc, so fetching it before the layout-key check
+    // copied the entire atlas even for paint-only syncs.
+    const atlasKey = atlasNameForFont(this.font)
+    const nextLayoutKey =
+      this.text +
+      '\u0001' +
+      String(this.fontSize) +
+      '\u0001' +
+      String(this.letterSpacing) +
+      '\u0001' +
+      atlasKey +
+      '\u0001' +
+      String(this.anchorX) +
+      '\u0001' +
+      String(this.anchorY)
+    if (nextLayoutKey === this.layoutKey) {
+      // Geometry inputs unchanged: only refresh paint state (color/opacity),
+      // matching what per-frame HUD pulses actually vary.
+      setMaterialHex(this.material, this.color)
+      this.material.opacity = this.fillOpacity
+      return
+    }
+    const atlas = atlasForFont(this.font)
+    this.layoutKey = nextLayoutKey
+    const laidOut = layoutText(atlas, this.text, this.fontSize, this.letterSpacing)
+    // Anchor offsets: troika's anchorX left|center|right and anchorY
+    // top|middle|bottom (the subset the app uses). The layout origin is the
+    // left edge of the first baseline.
+    let offsetX = 0
+    if (this.anchorX === 'center') offsetX = -laidOut.width / 2
+    else if (this.anchorX === 'right') offsetX = -laidOut.width
+    let offsetY = 0
+    if (this.anchorY === 'middle') offsetY = -(laidOut.ascent + laidOut.descent) / 2
+    else if (this.anchorY === 'top') offsetY = -laidOut.ascent
+    else if (this.anchorY === 'bottom') offsetY = -laidOut.descent
+    // 'bottom-baseline' needs no offset: the layout origin IS the baseline.
+    const positions = laidOut.positions
+    for (let i = 0; i < positions.length; i += 3) {
+      positions[i] += offsetX
+      positions[i + 1] += offsetY
+    }
+    // Keep the BufferAttribute objects stable when the next layout has the
+    // same storage shape. WebGLAttributes keys its native buffer cache by
+    // attribute identity, so swapping the entire geometry would otherwise
+    // delete and recreate three GL buffers for every same-length score change.
+    // A size or typed-array-kind change still replaces and disposes the old
+    // geometry so WebGLAttributes can allocate correctly-sized storage.
+    const previous: BufferGeometry = this.mesh.geometry
+    const next = laidOut.geometry
+    const previousPosition = previous.getAttribute('position')
+    const nextPosition = next.getAttribute('position')
+    const previousUv = previous.getAttribute('uv')
+    const nextUv = next.getAttribute('uv')
+    const previousIndex = previous.index
+    const nextIndex = next.index
+    const matchingIndexStorage =
+      previousIndex !== null &&
+      nextIndex !== null &&
+      ((previousIndex.array instanceof Uint16Array && nextIndex.array instanceof Uint16Array) ||
+        (previousIndex.array instanceof Uint32Array && nextIndex.array instanceof Uint32Array))
+    if (
+      previousPosition instanceof BufferAttribute &&
+      nextPosition instanceof BufferAttribute &&
+      previousUv instanceof BufferAttribute &&
+      nextUv instanceof BufferAttribute &&
+      previousPosition.array instanceof Float32Array &&
+      nextPosition.array instanceof Float32Array &&
+      previousUv.array instanceof Float32Array &&
+      nextUv.array instanceof Float32Array &&
+      matchingIndexStorage &&
+      previousPosition.array.length === nextPosition.array.length &&
+      previousUv.array.length === nextUv.array.length &&
+      previousIndex.array.length === nextIndex.array.length
+    ) {
+      previousPosition.array = nextPosition.array
+      previousPosition.needsUpdate = true
+      previousUv.array = nextUv.array
+      previousUv.needsUpdate = true
+      previousIndex.array = nextIndex.array
+      previousIndex.needsUpdate = true
+    } else {
+      this.mesh.geometry = next
+      previous.dispose()
+    }
+    // Keep both sides of the identity comparison on the shared Texture
+    // carrier. Otherwise a derived DataTexture local can be incorrectly
+    // treated as disjoint from Material.map during native constant folding.
+    const nextMap: Texture = atlasTexture(atlas)
+    if (this.material.map !== nextMap) {
+      this.material.map = nextMap
+      // needsUpdate recompiles the shader program; only pay that when the
+      // map binding actually changed, not on every per-frame sync().
+      this.material.needsUpdate = true
+    }
+    setMaterialHex(this.material, this.color)
+    this.material.opacity = this.fillOpacity
+  }
+
+  dispose(): void {
+    if (this.mesh.geometry) this.mesh.geometry.dispose()
+    this.material.dispose()
+  }
+}
+
+export { TroikaText as Text }

package/test/auto-instanced-render-scene.ts

@@ -0,0 +1,66 @@
+// Generic render-list instancing fixture. Reference meshes deliberately have
+// observable callback overrides, so the renderer must retain ordinary draws.
+import { PerspectiveCamera } from 'three/src/cameras/PerspectiveCamera.js'
+import { BoxGeometry } from 'three/src/geometries/BoxGeometry.js'
+import { Color } from 'three/src/math/Color.js'
+import { MeshPhongMaterial } from 'three/src/materials/MeshPhongMaterial.js'
+import { Mesh } from 'three/src/objects/Mesh.js'
+import { Scene } from 'three/src/scenes/Scene.js'
+import { AmbientLight } from 'three/src/lights/AmbientLight.js'
+import { DirectionalLight } from 'three/src/lights/DirectionalLight.js'
+import { WebGLRenderer } from 'three/src/renderers/WebGLRenderer.js'
+import { createNativeWebGLCanvas } from '../src/nativeWebGL'
+import { nativeWebGLSwap, syncNativeWebGLSize } from '../src/nativeWebGLHost'
+
+export function startRealThreeFrameLoop(width: number, height: number, aspect: number): void {
+  const canvas = createNativeWebGLCanvas(width, height)
+  const context = canvas.getContext('webgl2')
+  if (!context) throw new Error('Native instancing validation requires a WebGL2 context')
+  const renderer = new WebGLRenderer({canvas, context, antialias:false, alpha:false, depth:true, stencil:true})
+  renderer.setPixelRatio(1)
+  renderer.setSize(width,height,false)
+  renderer.setClearColor(new Color(0x102030),1)
+  const camera = new PerspectiveCamera(55,aspect,.1,100)
+  camera.position.z = 7
+  const reference = new Scene()
+  const candidate = new Scene()
+  const geometry = new BoxGeometry(1.25,1.25,1.25)
+  const material = new MeshPhongMaterial({color:0xff6010,flatShading:false})
+  const instances: Mesh[] = []
+  let callbacks = 0
+  for (let i=0;i<2;i++) {
+    const original = new Mesh(geometry,material)
+    original.position.set(i===0?-1.25:1.25,0,0)
+    original.scale.set(1,i===0?.75:1.25,.5)
+    original.rotation.x = Math.PI / 2
+    original.onBeforeRender = () => { callbacks++ }
+    reference.add(original)
+    const mesh = new Mesh(geometry,material)
+    mesh.position.copy(original.position)
+    mesh.scale.copy(original.scale)
+    mesh.rotation.copy(original.rotation)
+    candidate.add(mesh)
+    instances.push(mesh)
+  }
+  reference.add(new AmbientLight(0xffffff, .5))
+  candidate.add(new AmbientLight(0xffffff, .5))
+  const light = new DirectionalLight(0xffffff,2)
+  light.position.set(3,5,7)
+  reference.add(light)
+  const light2 = new DirectionalLight(0xffffff,2)
+  light2.position.copy(light.position)
+  candidate.add(light2)
+  let frame=0
+  function renderFrame(): void {
+    frame++
+    camera.aspect=syncNativeWebGLSize(aspect)
+    camera.updateProjectionMatrix()
+    if(frame===241) instances[0].visible=false
+    renderer.render(frame<121?reference:candidate,camera)
+    if(frame===90||frame===180||frame===300) console.error('[auto.instance]',frame,renderer.info.render.calls,renderer.info.render.triangles,callbacks)
+    nativeWebGLSwap()
+    if(frame<301) requestAnimationFrame(renderFrame)
+    else console.error('[batch.render] complete')
+  }
+  requestAnimationFrame(renderFrame)
+}

package/test/batched-render-scene.ts

@@ -0,0 +1,58 @@
+// Rendered by the existing Three ANGLE Metal app shell through the test-only
+// wrapper plugin. The two scenes must produce identical framebuffer pixels.
+import { PerspectiveCamera } from 'three/src/cameras/PerspectiveCamera.js'
+import { BoxGeometry } from 'three/src/geometries/BoxGeometry.js'
+import { Color } from 'three/src/math/Color.js'
+import { Matrix4 } from 'three/src/math/Matrix4.js'
+import { MeshBasicMaterial } from 'three/src/materials/MeshBasicMaterial.js'
+import { Mesh } from 'three/src/objects/Mesh.js'
+import { BatchedMesh } from 'three/src/objects/BatchedMesh.js'
+import { Scene } from 'three/src/scenes/Scene.js'
+import { WebGLRenderer } from 'three/src/renderers/WebGLRenderer.js'
+import { createNativeWebGLCanvas } from '../src/nativeWebGL'
+import { nativeWebGLSwap, syncNativeWebGLSize } from '../src/nativeWebGLHost'
+
+export function startRealThreeFrameLoop(width: number, height: number, aspect: number): void {
+  const canvas = createNativeWebGLCanvas(width, height)
+  const context = canvas.getContext('webgl2')
+  if (!context) throw new Error('Native batching validation requires a WebGL2 context')
+  const renderer = new WebGLRenderer({ canvas, context, antialias: false, alpha: false, depth: true, stencil: true })
+  renderer.setPixelRatio(1)
+  renderer.setSize(width, height, false)
+  renderer.setClearColor(new Color(0x102030), 1)
+  const camera = new PerspectiveCamera(55, aspect, 0.1, 100)
+  camera.position.z = 7
+  const reference = new Scene()
+  const candidate = new Scene()
+  const geometry = new BoxGeometry(1.25, 1.25, 1.25)
+  const colors = [new Color(0xff4010), new Color(0x20c0ff)]
+  const batch = new BatchedMesh(4, 128, 256, new MeshBasicMaterial({ color: 0xffffff }))
+  const geometryId = batch.addGeometry(geometry)
+  for (let i = 0; i < 2; i++) {
+    const matrix = new Matrix4().makeTranslation(i === 0 ? -1 : 1, 0, 0)
+    const mesh = new Mesh(geometry, new MeshBasicMaterial({ color: colors[i] }))
+    mesh.applyMatrix4(matrix)
+    reference.add(mesh)
+    const instance = batch.addInstance(geometryId)
+    batch.setMatrixAt(instance, matrix)
+    batch.setColorAt(instance, colors[i])
+  }
+  candidate.add(batch)
+  let frame = 0
+  function renderFrame(): void {
+    frame++
+    camera.aspect = syncNativeWebGLSize(aspect)
+    camera.updateProjectionMatrix()
+    // The existing native host dumps frames 90, 180 and 300. The last frame
+    // verifies that hiding one instance removes its draw without stale pixels.
+    if (frame === 241) batch.setVisibleAt(0, false)
+    renderer.render(frame < 121 ? reference : candidate, camera)
+    if (frame === 90 || frame === 180 || frame === 300) {
+      console.error('[batch.render]', frame, renderer.info.render.calls, renderer.info.render.triangles, batch._multiDrawCount)
+    }
+    nativeWebGLSwap()
+    if (frame < 301) requestAnimationFrame(renderFrame)
+    else console.error('[batch.render] complete')
+  }
+  requestAnimationFrame(renderFrame)
+}