@geastack/native-webgl-angle 0.1.14 → 0.1.15

package/README.md

@@ -121,7 +121,7 @@ to change them. Any present value, including an empty string, enables them.
 
 ### Validation
 
-`npm run test:host-effects` checks 85 direct GL/input declarations and 15 audio
+`npm run test:host-effects` checks 87 direct GL/input declarations and 15 audio
 declarations against the compiler's host-mutation census. Their
 `@gea-host-inert` contracts permit native state changes while excluding script
 reference retention, script object mutation and script callbacks. The native

package/gea-native.json

@@ -1,7 +1,7 @@
 {
   "$comment": "What a GeaStack native target needs in order to build this package into an app. Paths are relative to the package root.",
   "windows": {
-    "sources": ["native/angle_webgl_host.mm", "native/audio_host.mm", "native/win32_webgl_surface.cpp"],
+    "sources": ["native/angle_webgl_host.mm", "native/audio_host.mm", "native/resource_host.mm", "native/win32_webgl_surface.cpp"],
     "includeDirs": ["native"],
     "requires": {
       "gles": {

package/geatsc-plugin-uniforms.mjs

@@ -44,7 +44,9 @@ export const nativeLightUniformClassNames = [
 export const nativeUniformTypedefs = `/**
  * Every value a shader uniform slot can hold, as ONE disjoint union: the math
  * classes three's setters duck-type (\`v.x\`, \`v.r\`, \`v.elements\`), textures,
- * the flat numeric arrays, and the light-uniform arrays \`WebGLLights\` builds.
+ * the flat numeric arrays, the vector and matrix arrays a custom
+ * \`ShaderMaterial\` declares (\`uniform vec4 u[ N ]\`, flattened by
+ * \`copyUniformElement\`), and the light-uniform arrays \`WebGLLights\` builds.
  * A slot is therefore one native tagged union, and every consumer narrows it
  * with \`instanceof\`/\`typeof\`/\`Array.isArray\` instead of reading a box.
  * @typedef {number|boolean|null|undefined
@@ -57,7 +59,9 @@ export const nativeUniformTypedefs = `/**
  *   |import('../../math/Matrix4.js').Matrix4
  *   |import('../../textures/Texture.js').Texture
  *   |number[]|Float32Array|Int32Array|Uint32Array
+ *   |Array<import('../../math/Vector2.js').Vector2>
  *   |Array<import('../../math/Vector3.js').Vector3>
+ *   |Array<import('../../math/Vector4.js').Vector4>
  *   |Array<import('../../math/Matrix4.js').Matrix4>
  *   |Array<import('../../textures/Texture.js').Texture|null>
 ${nativeLightUniformClassNames.map((name) => ` *   |${name}|${name}[]`).join('\n')}
@@ -345,6 +349,13 @@ export function isUniformNumberArray( value ) {
 
 }
 
+/** @param {NativeUniformValue} value @return {value is Vector2[]} */
+function isVector2Array( value ) {
+
+\treturn Array.isArray( value ) && value.length > 0 && value[ 0 ] instanceof Vector2;
+
+}
+
 /** @param {NativeUniformValue} value @return {value is Vector3[]} */
 function isVector3Array( value ) {
 
@@ -352,6 +363,13 @@ function isVector3Array( value ) {
 
 }
 
+/** @param {NativeUniformValue} value @return {value is Vector4[]} */
+function isVector4Array( value ) {
+
+\treturn Array.isArray( value ) && value.length > 0 && value[ 0 ] instanceof Vector4;
+
+}
+
 /** @param {NativeUniformValue} value @return {value is Matrix4[]} */
 function isMatrix4Array( value ) {
 
@@ -405,6 +423,17 @@ export function cloneUniformValue( value ) {
 
 \tif ( isUniformNumberArray( value ) ) return value.slice();
 
+\tif ( isVector2Array( value ) ) {
+
+\t\t/** @type {Vector2[]} */
+\t\tconst cloned = [];
+
+\t\tfor ( let i = 0, l = value.length; i < l; i ++ ) cloned.push( value[ i ].clone() );
+
+\t\treturn cloned;
+
+\t}
+
 \tif ( isVector3Array( value ) ) {
 
 \t\t/** @type {Vector3[]} */
@@ -416,6 +445,17 @@ export function cloneUniformValue( value ) {
 
 \t}
 
+\tif ( isVector4Array( value ) ) {
+
+\t\t/** @type {Vector4[]} */
+\t\tconst cloned = [];
+
+\t\tfor ( let i = 0, l = value.length; i < l; i ++ ) cloned.push( value[ i ].clone() );
+
+\t\treturn cloned;
+
+\t}
+
 \tif ( isMatrix4Array( value ) ) {
 
 \t\t/** @type {Matrix4[]} */

package/geatsc-plugin-uploads.mjs

@@ -1,16 +1,21 @@
+// A texture upload hands GL the view's own bytes, and the GL type names the view
+// (WebGL 2 3.7.6, OES_texture_half_float): UNSIGNED_SHORT, HALF_FLOAT and the
+// packed 16-bit types read a Uint16Array; UNSIGNED_INT and the packed 32-bit
+// types a Uint32Array; BYTE, SHORT and INT their signed views; FLOAT a Float32Array.
+const textureElementKind = '(type == 0x1401 ? 4 : type == 0x1400 ? 5 : type == 0x1402 ? 6 : type == 0x1404 ? 7 : ' +
+  'type == 0x1403 || type == 0x140B || type == 0x8D61 || type == 0x8033 || type == 0x8034 || type == 0x8363 ? 2 : ' +
+  'type == 0x1405 || type == 0x8368 || type == 0x8C3B || type == 0x8C3E || type == 0x84FA ? 3 : 1)'
+
 // The host owns the physical upload format. The compiler only preserves the
 // native carriers at these explicitly registered synchronous boundaries.
-// Element type of the client pixels, by GL type: half floats travel as their
-// 16-bit patterns, never widened to float32.
-const pixelKind = '(type == 0x1403 || type == 0x140B || type == 0x8D61 ? 2 : type == 0x1405 ? 3 : type == 0x1401 ? 4 : type == 0x1400 ? 5 : type == 0x1402 ? 6 : type == 0x1404 ? 7 : 1)';
 export const nativeUploadFunctions = [
   ['threeWebGLBufferData', 'gea_three_webgl_buffer_data_native', ['target', 'usage', 'typeCode'], 'gea_three_webgl_buffer_data_bytes', ['target', 'usage'], 'typeCode'],
   ['threeWebGLBufferSubData', 'gea_three_webgl_buffer_sub_data_native', ['target', 'offset', 'typeCode'], 'gea_three_webgl_buffer_sub_data_bytes', ['target', 'offset'], 'typeCode'],
   ['threeWebGLBufferSubDataRange', 'gea_three_webgl_buffer_sub_data_range_native', ['target', 'offset', 'typeCode'], 'gea_three_webgl_buffer_sub_data_bytes', ['target', 'offset'], 'typeCode', true],
-  ['threeWebGLTexImage2D', 'gea_three_webgl_tex_image_2d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_image_2d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], pixelKind],
-  ['threeWebGLTexImage3D', 'gea_three_webgl_tex_image_3d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_image_3d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], pixelKind],
-  ['threeWebGLTexSubImage3D', 'gea_three_webgl_tex_sub_image_3d_native', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_sub_image_3d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], pixelKind],
-  ['threeWebGLTexSubImage2D', 'gea_three_webgl_tex_sub_image_2d_native', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_sub_image_2d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], pixelKind],
+  ['threeWebGLTexImage2D', 'gea_three_webgl_tex_image_2d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_image_2d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexImage3D', 'gea_three_webgl_tex_image_3d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_image_3d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexSubImage3D', 'gea_three_webgl_tex_sub_image_3d_native', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_sub_image_3d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexSubImage2D', 'gea_three_webgl_tex_sub_image_2d_native', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_sub_image_2d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], textureElementKind],
 ].map(([name, binding, parameters, raw, rawParameters, kind, range]) => {
   const declaration = `extern "C" void ${raw}(${rawParameters.map(p => `double ${p}`).join(', ')}, const void* bytes, double byteLength);
   template <typename Source> inline void ${binding}(${parameters.map(p => `double ${p}`).join(', ')}, const Source& values${range ? ', double sourceOffset, double length' : ''}) {

package/geatsc-plugin.mjs

@@ -97,6 +97,14 @@ const hostFunctions = [
   ],
   ...nativeUploadFunctions,
   ...nativeReadbackFunctions,
+  // Resources files (native/resource_host.mm): read whole, in place, into the caller's Uint8Array.
+  ['threeResourceSize','gea_three_resource_size','double','extern "C" double gea_three_resource_size(std::string name);'],
+  ['threeResourceRead','gea_three_resource_read_native','double',`
+extern "C" double gea_three_resource_read_bytes(std::string name, void* bytes, double byteLength);
+inline double gea_three_resource_read_native(std::string name, const gea::Ref<gea::TypedArray<std::uint8_t>>& destination) {
+  if (!destination) return -1;
+  return gea_three_resource_read_bytes(std::move(name), destination->data(), static_cast<double>(destination->size()));
+}`],
   ['threeWebGLBlitFramebuffer','gea_three_webgl_blit_framebuffer','void','extern "C" void gea_three_webgl_blit_framebuffer(double,double,double,double,double,double,double,double,double,double);'],
   ['threeWebGLReadPixelsPack','gea_three_webgl_read_pixels_pack','void','extern "C" void gea_three_webgl_read_pixels_pack(double,double,double,double,double,double,double);'],
   ['threeWebGLFenceSync','gea_three_webgl_fence_sync','double','extern "C" double gea_three_webgl_fence_sync();'],
@@ -148,6 +156,12 @@ const hostFunctions = [
     "void",
     'extern "C" void gea_three_webgl_swap();',
   ],
+  [
+    "threeWebGLSetVsync",
+    "gea_three_webgl_set_vsync",
+    "void",
+    'extern "C" void gea_three_webgl_set_vsync(double on);',
+  ],
   [
     "threeAngleSmokeLog",
     "gea_three_angle_smoke_log",
@@ -222,6 +236,12 @@ const hostFunctions = [
     "double",
     'extern "C" double gea_three_webgl_get_shader_parameter(double shader, double pname);',
   ],
+  [
+    "threeWebGLGetShaderInfoLog",
+    "gea_three_webgl_get_shader_info_log",
+    "std::string",
+    'extern "C" std::string gea_three_webgl_get_shader_info_log(double shader);',
+  ],
   [
     "threeWebGLDeleteShader",
     "gea_three_webgl_delete_shader",
@@ -253,6 +273,12 @@ const hostFunctions = [
     "double",
     'extern "C" double gea_three_webgl_get_program_parameter(double program, double pname);',
   ],
+  [
+    "threeWebGLGetProgramInfoLog",
+    "gea_three_webgl_get_program_info_log",
+    "std::string",
+    'extern "C" std::string gea_three_webgl_get_program_info_log(double program);',
+  ],
   [
     "threeWebGLDeleteProgram",
     "gea_three_webgl_delete_program",
@@ -1698,6 +1724,12 @@ const nativeDataTextureOverlayUnpackAlignmentSource =
   "\t/** @type {number} */\n\tunpackAlignment;";
 const overlayToJSONParameterSource =
   /(\/\*\*\n\t \* @param )\{[^\n]+\}( \[meta\]\n\t \*\/\n\ttoJSON\( meta \) \{)/g;
+const nativeObject3DJSONType =
+  "{ metadata?: { version: number, type: string, generator: string }, geometries?: Array<Object>, materials?: Array<Object>, textures?: Array<Object>, images?: Array<Object>, shapes?: Array<Object>, skeletons?: Array<Object>, animations?: Array<Object>, nodes?: Array<Object>, object: Object }";
+const nativeBufferGeometryJSONType =
+  "{ metadata: { version: number, type: string, generator: string }, uuid?: string, type?: string, name?: string, userData?: Object, data?: Object, instanceCount?: number, isInstancedBufferGeometry?: boolean, [key: string]: any }";
+const nativeFogJSONType =
+  "{ type: string, name: string, color: number, near?: number, far?: number, density?: number }";
 const rendererReceiverMethods = [
   "setPixelRatio",
   "setSize",
@@ -2032,6 +2064,37 @@ const transformSource = ({ fileName, text }) => {
       object3DRaycastSource,
       nativeObject3DRaycastSource,
     );
+    // `JSON.stringify` on a declared-any value keeps every class's `toJSON`
+    // (three's own `copy()` deep-copies `userData` that way), so these bodies
+    // compile whenever a material or texture is cloned. `@return {Object}`
+    // states nothing, so every `super.toJSON( meta )`, `child.toJSON( meta )`
+    // and `camera.toJSON( false )` result boxed and then had to be read back
+    // as the record the body builds, which no conversion can do. The envelope
+    // is the record the body builds; `object` stays `Object` because each
+    // subclass adds its own fields to it (`data.object.fov = ...`).
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized 3D object.",
+      `\t * @return {${nativeObject3DJSONType}} A JSON object representing the serialized 3D object.`,
+      fileName,
+      "Object3D.toJSON envelope",
+    );
+  }
+  if (
+    normalized.endsWith("/three/src/scenes/Fog.js") ||
+    normalized.endsWith("/three/src/scenes/FogExp2.js")
+  ) {
+    // `Scene.toJSON` calls `toJSON` on `?(Fog|FogExp2)`. Each body's own
+    // literal made the two methods two function types, and the read over the
+    // union had to convert one into the other. One record both literals fit,
+    // spelled once, makes them one type.
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized fog",
+      `\t * @return {${nativeFogJSONType}} A JSON object representing the serialized fog`,
+      fileName,
+      "Fog toJSON shared record",
+    );
   }
   if (normalized.endsWith("/three/src/renderers/WebGLRenderer.js")) {
     transformed =
@@ -2215,6 +2278,15 @@ class WebGLRenderer {
       rendererCompileReturnSource,
       nativeRendererCompileReturnSource,
     );
+    // `if ( targetScene === null ) targetScene = scene;` stores the Object3D
+    // being compiled; every use after it is an Object3D use.
+    transformed = replaceOne(
+      transformed,
+      `@param {?Scene} [targetScene=null] - The target scene.\n\t\t * ${nativeRendererCompileReturnSource}`,
+      `@param {?Object3D} [targetScene=null] - The target scene.\n\t\t * ${nativeRendererCompileReturnSource}`,
+      fileName,
+      "WebGLRenderer compile target root",
+    );
     transformed = transformed.replace(
       rendererCompileAssignmentSource,
       nativeRendererCompileAssignmentSource,
@@ -3718,6 +3790,33 @@ class BufferGeometry extends EventDispatcher {`,
       fileName,
       "BufferGeometry morph-attribute table",
     );
+    // `toJSON` fills each morph entry from `const array = []`, which the
+    // checker types `any[]` (the table's entry type) while the census lays it
+    // out from its pushes, the union of the two attribute `toJSON` records.
+    // Two carriers for one array, and an array cannot be converted in place.
+    // State the element three's attribute `toJSON`s state: `Object`.
+    transformed = replaceOne(
+      transformed,
+      "\t\t\tconst attributeArray = this.morphAttributes[ key ];\n\n\t\t\tconst array = [];",
+      "\t\t\tconst attributeArray = this.morphAttributes[ key ];\n\n\t\t\t/** @type {Array<Object>} */\n\t\t\tconst array = [];",
+      fileName,
+      "BufferGeometry.toJSON morph entry array",
+    );
+    // `JSON.stringify` on a declared-any value keeps every `toJSON` (see
+    // Object3D's envelope), so this envelope is published to dynamic code,
+    // which may write any of its fields. Laid out from the body, its `data`
+    // field is the record `data.data = { attributes: {} }` and the writes
+    // after it build, and a dynamic value has no reader into that record.
+    // State the envelope, with `data` left `Object` as Object3D's `object`
+    // is: the body fills it key by key. The index signature is the
+    // parameters branch, which copies each parameter in by name.
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized geometry.\n\t */\n\ttoJSON() {\n\n\t\tconst data = {",
+      `\t * @return {${nativeBufferGeometryJSONType}} A JSON object representing the serialized geometry.\n\t */\n\ttoJSON() {\n\n\t\t/** @type {${nativeBufferGeometryJSONType}} */\n\t\tconst data = {`,
+      fileName,
+      "BufferGeometry.toJSON envelope",
+    );
     transformed = replaceOne(
       transformed,
       `\tgetAttribute( name ) {
@@ -5455,6 +5554,18 @@ function requireWebGLStateTextureImageSource( value ) {
       fileName,
       "WebGLBindingStates interleaved attribute import",
     );
+    // The binding-state fast paths below test `object instanceof InstancedMesh`; three's own
+    // file reads `object.isInstancedMesh` and imports no InstancedMesh. An app that patches
+    // three on disk may have added the import already.
+    if (!transformed.includes("import { InstancedMesh } from '../../objects/InstancedMesh.js';")) {
+      transformed = replaceOne(
+        transformed,
+        "import { IntType } from '../../constants.js';",
+        "import { IntType } from '../../constants.js';\nimport { InstancedMesh } from '../../objects/InstancedMesh.js';",
+        fileName,
+        "WebGLBindingStates instanced mesh import",
+      );
+    }
     transformed = replaceOne(
       transformed,
       "\t\t\tif ( index !== null ) {\n\n\t\t\t\tgl.bindBuffer( gl.ELEMENT_ARRAY_BUFFER, attributes.get( index ).buffer );",
@@ -5641,7 +5752,7 @@ function requireWebGLStateTextureImageSource( value ) {
     transformed = replaceOne(
       transformed,
       "\tfunction get( scene, renderCallDepth ) {",
-      "\t/** @param {import('../../scenes/Scene.js').Scene} scene @param {number} renderCallDepth */\n\tfunction get( scene, renderCallDepth ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene @param {number} renderCallDepth */\n\tfunction get( scene, renderCallDepth ) {",
       fileName,
       "WebGLRenderLists lookup inputs",
     );
@@ -6373,7 +6484,10 @@ function WebGLShadowMap( renderer, objects, capabilities ) {`,
     transformed = replaceOne(
       transformed,
       "this.render = function ( lights, scene, camera ) {",
-      "this.render = /** @this {WebGLShadowMap} @param {Array<import('../../lights/Light.js').Light>} lights */ function ( lights, scene, camera ) {",
+      // `scene` is the root WebGLRenderer.render was handed, any Object3D;
+      // the body only traverses it. This inline block outranks the
+      // declaration overlay's `@param {Scene} scene` above the assignment.
+      "this.render = /** @this {WebGLShadowMap} @param {Array<import('../../lights/Light.js').Light>} lights @param {import('../../core/Object3D.js').Object3D} scene */ function ( lights, scene, camera ) {",
       fileName,
       "WebGLShadowMap.render receiver",
     );
@@ -6741,21 +6855,21 @@ class WebGLBackgroundPlaneMaterial extends ShaderMaterial {
     transformed = replaceOne(
       transformed,
       "\tfunction getBackground( scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction getBackground( scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction getBackground( scene ) {",
       fileName,
       "WebGLBackground background scene input",
     );
     transformed = replaceOne(
       transformed,
       "\tfunction render( scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction render( scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction render( scene ) {",
       fileName,
       "WebGLBackground scene input",
     );
     transformed = replaceOne(
       transformed,
       "\tfunction addToRenderList( renderList, scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction addToRenderList( renderList, scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction addToRenderList( renderList, scene ) {",
       fileName,
       "WebGLBackground render-list scene input",
     );
@@ -7092,6 +7206,15 @@ class WebGLBackgroundPlaneMaterial extends ShaderMaterial {
       backgroundRotation: "uniformMatrix3",
       uvTransform: "uniformMatrix3",
     });
+    // The renderer renders any Object3D (WebGLRenderer.render states
+    // `@param {Object3D} scene`), so the scene inputs above state Object3D.
+    // Only a Scene has a background: each read sits behind
+    // `scene.isScene === true`, or behind a background only a Scene yields,
+    // and names the Scene it reads.
+    transformed = transformed.replaceAll(
+      "scene.background",
+      "/** @type {Scene} */ ( scene ).background",
+    );
   }
   if (normalized.endsWith("/three/src/renderers/shaders/UniformsLib.js")) {
     transformed = transformUniformsLib(transformed, fileName, replaceOne);
@@ -8511,17 +8634,6 @@ function WebGLProperties() {
 
 \t}
 
-\t/**
-\t * @param {WebGLPropertyOwner} object
-\t * @param {keyof NativeWebGLPropertyBag} key
-\t * @param {NativeWebGLPropertyBag[keyof NativeWebGLPropertyBag]} value
-\t */
-\tfunction update( object, key, value ) {
-
-\t\tget( object )[ key ] = value;
-
-\t}
-
 \tfunction dispose() {
 
 \t\tmaterials.clear();
@@ -8533,7 +8645,12 @@ function WebGLProperties() {
 
 \t}
 
-\treturn { has, get, remove, update, dispose };
+\t// Three's \`update( object, key, value )\` is left out: nothing in three
+\t// calls it, and its \`get( object )[ key ] = value\` stores a union of every
+\t// slot's type into the one slot \`key\` names. TypeScript rejects that store
+\t// (the target is \`never\`), and geatsc certifies no conversion from the
+\t// union into a single slot, so the C++ emitter refused the body.
+\treturn { has, get, remove, dispose };
 
 }
 
@@ -9238,7 +9355,7 @@ function WebGLRenderState( extensions ) {`,
     transformed = replaceOne(
       transformed,
       "\tfunction get( scene, renderCallDepth = 0 ) {",
-      "\t/** @param {import('../../scenes/Scene.js').Scene} scene @param {number} [renderCallDepth=0] */\n\tfunction get( scene, renderCallDepth = 0 ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene @param {number} [renderCallDepth=0] */\n\tfunction get( scene, renderCallDepth = 0 ) {",
       fileName,
       "WebGLRenderStates lookup inputs",
     );

package/native/angle_webgl_host.mm

@@ -328,6 +328,7 @@ static constexpr GLenum GL_UNSIGNED_INT = 0x1405;
 static constexpr GLenum GL_RGBA_VALUE = 0x1908;
 static constexpr GLenum GL_VIEWPORT_VALUE = 0x0BA2;
 static constexpr GLenum GL_FRAMEBUFFER_BINDING_VALUE = 0x8CA6;
+static constexpr GLenum GL_INFO_LOG_LENGTH_VALUE = 0x8B84;
 
 using PFNEGLGETPROCADDRESS = void *(*)(const char *);
 using PFNEGLGETPLATFORMDISPLAYEXTPROC = EGLDisplay (*)(EGLenum, void *, const EGLint *);
@@ -402,6 +403,7 @@ using PFNGLGETINTEGERVPROC = void (*)(GLenum, GLint *);
 using PFNGLGETPROGRAMIVPROC = void (*)(GLuint, GLenum, GLint *);
 using PFNGLGETSHADERIVPROC = void (*)(GLuint, GLenum, GLint *);
 using PFNGLGETSHADERINFOLOGPROC = void (*)(GLuint, GLsizei, GLsizei *, GLchar *);
+using PFNGLGETPROGRAMINFOLOGPROC = void (*)(GLuint, GLsizei, GLsizei *, GLchar *);
 using PFNGLGETSTRINGPROC = const unsigned char *(*)(GLenum);
 using PFNGLGETUNIFORMLOCATIONPROC = GLint (*)(GLuint, const GLchar *);
 using PFNGLLINEWIDTHPROC = void (*)(GLfloat);
@@ -549,6 +551,7 @@ struct AngleWebGLState {
   PFNGLGETPROGRAMIVPROC glGetProgramiv = nullptr;
   PFNGLGETSHADERIVPROC glGetShaderiv = nullptr;
   PFNGLGETSHADERINFOLOGPROC glGetShaderInfoLog = nullptr;
+  PFNGLGETPROGRAMINFOLOGPROC glGetProgramInfoLog = nullptr;
   PFNGLGETSTRINGPROC glGetString = nullptr;
   PFNGLGETUNIFORMLOCATIONPROC glGetUniformLocation = nullptr;
   PFNGLLINEWIDTHPROC glLineWidth = nullptr;
@@ -627,6 +630,10 @@ struct AngleWebGLState {
 };
 
 static AngleWebGLState gWebGL;
+// Vertical sync as the program chose it (nativeWebGLSetVsync): 1 on, 0 off, -1 not chosen
+// (then GEA_ANGLE_SWAP_INTERVAL, else 0; see makeCurrent).
+static int gVsyncChoice = -1;
+extern "C" void gea_three_webgl_set_vsync(double on) { gVsyncChoice = on != 0 ? 1 : 0; }
 static GLenum hostReadbackError = 0;
 static std::chrono::steady_clock::time_point gProfileSizeSync;
 static bool gProfileSizeSyncPending = false;
@@ -942,9 +949,19 @@ static bool makeCurrent(const char *label) {
   // reintroduced because the layer still syncs its own present.
   // `GEA_ANGLE_SWAP_INTERVAL` overrides it (set `1` to restore the old
   // double-paced behaviour) so both arms can be measured from one binary.
+  // A program's choice (nativeWebGLSetVsync) wins: off is interval 0; on is
+  // interval 1 where nothing else paces the frames (a desktop window with no
+  // display link), and the default above on Apple platforms, where the display
+  // link and the layer's own sync already do.
   if (gWebGL.eglSwapInterval) {
     const char *requested = std::getenv("GEA_ANGLE_SWAP_INTERVAL");
-    const EGLint interval = requested ? static_cast<EGLint>(std::atoi(requested)) : 0;
+    const EGLint fallback = requested ? static_cast<EGLint>(std::atoi(requested)) : 0;
+#if defined(__APPLE__)
+    const EGLint paced = fallback;
+#else
+    const EGLint paced = 1;
+#endif
+    const EGLint interval = gVsyncChoice == 0 ? 0 : gVsyncChoice == 1 ? paced : fallback;
     gWebGL.eglSwapInterval(gWebGL.display, interval);
   }
   if (gWebGL.eglMakeCurrent(gWebGL.display, gWebGL.surface, gWebGL.surface, gWebGL.context) == EGL_FALSE_VALUE) {
@@ -1069,6 +1086,7 @@ static bool loadGlSymbols() {
   LOAD_GL(glGetProgramiv, PFNGLGETPROGRAMIVPROC)
   LOAD_GL(glGetShaderiv, PFNGLGETSHADERIVPROC)
   LOAD_GL(glGetShaderInfoLog, PFNGLGETSHADERINFOLOGPROC)
+  LOAD_GL(glGetProgramInfoLog, PFNGLGETPROGRAMINFOLOGPROC)
   LOAD_GL(glGetString, PFNGLGETSTRINGPROC)
   LOAD_GL(glGetUniformLocation, PFNGLGETUNIFORMLOCATIONPROC)
   LOAD_GL(glLineWidth, PFNGLLINEWIDTHPROC)
@@ -2046,6 +2064,28 @@ extern "C" double gea_three_webgl_get_program_parameter(double program, double p
   gWebGL.glGetProgramiv(asGLuint(program), asGLenum(pname), &value);
   return value;
 }
+// The driver's compile or link log, as WebGL's getShaderInfoLog and
+// getProgramInfoLog return it.
+static std::string geaInfoLog(double object, PFNGLGETSHADERIVPROC queryLength, PFNGLGETSHADERINFOLOGPROC readLog) {
+  GLint length = 0;
+  queryLength(asGLuint(object), GL_INFO_LOG_LENGTH_VALUE, &length);
+  if (length <= 0) return std::string();
+  std::string log(static_cast<std::size_t>(length), '\0');
+  GLsizei written = 0;
+  readLog(asGLuint(object), length, &written, log.data());
+  log.resize(static_cast<std::size_t>(std::clamp(written, 0, length)));
+  return log;
+}
+extern "C" std::string gea_three_webgl_get_shader_info_log(double shader) {
+  geaTrapCheck("gea_three_webgl_get_shader_info_log");
+  if (!ensureWebGLCurrent("getShaderInfoLog")) return std::string();
+  return geaInfoLog(shader, gWebGL.glGetShaderiv, gWebGL.glGetShaderInfoLog);
+}
+extern "C" std::string gea_three_webgl_get_program_info_log(double program) {
+  geaTrapCheck("gea_three_webgl_get_program_info_log");
+  if (!ensureWebGLCurrent("getProgramInfoLog")) return std::string();
+  return geaInfoLog(program, gWebGL.glGetProgramiv, gWebGL.glGetProgramInfoLog);
+}
 extern "C" void gea_three_webgl_delete_program(double program) {
   geaTrapCheck("gea_three_webgl_delete_program"); GEA_WEBGL_VOID("deleteProgram"); gWebGL.glDeleteProgram(asGLuint(program)); }
 extern "C" void gea_three_webgl_use_program(double program) {

package/native/resource_host.mm

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// Files an app ships in its Resources folder, read whole into a typed array the
+// program allocated (src/nativeResources.ts). Resources is the app bundle's
+// resource directory on macOS and iOS, and the Resources folder beside the
+// executable elsewhere (where the desktop targets stage an app's
+// nativeResources); GEA_RESOURCE_DIR names another directory.
+//
+// A name is relative to that directory, with '/' between its parts; an
+// absolute name, a backslash or a '..' part is refused, so a name never reaches
+// outside it.
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <string>
+
+#if defined(_WIN32)
+#include <windows.h>
+#elif defined(__APPLE__)
+#import <Foundation/Foundation.h>
+#else
+#include <unistd.h>
+#include <climits>
+#endif
+
+namespace {
+
+bool geaResourceNameValid(const std::string &name) {
+  if (name.empty() || name.front() == '/' || name.find('\\') != std::string::npos || name.find(':') != std::string::npos) return false;
+  size_t start = 0;
+  while (start <= name.size()) {
+    const size_t end = name.find('/', start);
+    const std::string part = name.substr(start, end == std::string::npos ? std::string::npos : end - start);
+    if (part.empty() || part == "." || part == "..") return false;
+    if (end == std::string::npos) break;
+    start = end + 1;
+  }
+  return true;
+}
+
+#if defined(_WIN32)
+const std::wstring &geaResourceDirectory() {
+  static const std::wstring directory = [] {
+    wchar_t value[MAX_PATH] = {};
+    const DWORD n = GetEnvironmentVariableW(L"GEA_RESOURCE_DIR", value, MAX_PATH);
+    if (n > 0 && n < MAX_PATH) return std::wstring(value);
+    wchar_t module[MAX_PATH] = {};
+    const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+    std::wstring path(module, length < MAX_PATH ? length : 0);
+    const size_t slash = path.find_last_of(L"\\/");
+    return slash == std::wstring::npos ? std::wstring() : path.substr(0, slash) + L"\\Resources";
+  }();
+  return directory;
+}
+
+FILE *geaOpenResource(const std::string &name) {
+  if (!geaResourceNameValid(name) || geaResourceDirectory().empty()) return nullptr;
+  const int length = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), nullptr, 0);
+  if (length <= 0) return nullptr;
+  std::wstring relative(static_cast<size_t>(length), L'\0');
+  MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), relative.data(), length);
+  for (wchar_t &c : relative) if (c == L'/') c = L'\\';
+  FILE *file = nullptr;
+  return _wfopen_s(&file, (geaResourceDirectory() + L"\\" + relative).c_str(), L"rb") == 0 ? file : nullptr;
+}
+#else
+const std::string &geaResourceDirectory() {
+  static const std::string directory = [] {
+    if (const char *value = std::getenv("GEA_RESOURCE_DIR")) return std::string(value);
+#if defined(__APPLE__)
+    @autoreleasepool {
+      NSString *resources = [[NSBundle mainBundle] resourcePath];
+      return resources ? std::string(resources.UTF8String) : std::string();
+    }
+#else
+    char path[PATH_MAX] = {};
+    const ssize_t length = readlink("/proc/self/exe", path, sizeof(path) - 1);
+    if (length <= 0) return std::string();
+    const std::string executable(path, static_cast<size_t>(length));
+    const size_t slash = executable.find_last_of('/');
+    return slash == std::string::npos ? std::string() : executable.substr(0, slash) + "/Resources";
+#endif
+  }();
+  return directory;
+}
+
+FILE *geaOpenResource(const std::string &name) {
+  if (!geaResourceNameValid(name) || geaResourceDirectory().empty()) return nullptr;
+  return std::fopen((geaResourceDirectory() + "/" + name).c_str(), "rb");
+}
+#endif
+
+long long geaResourceLength(FILE *file) {
+  if (std::fseek(file, 0, SEEK_END) != 0) return -1;
+#if defined(_WIN32)
+  const long long length = _ftelli64(file);
+#else
+  const long long length = static_cast<long long>(ftello(file));
+#endif
+  if (length < 0 || std::fseek(file, 0, SEEK_SET) != 0) return -1;
+  return length;
+}
+
+}  // namespace
+
+// The file's size in bytes, or -1 when it is missing or the name is refused.
+extern "C" double gea_three_resource_size(std::string name) {
+  FILE *file = geaOpenResource(name);
+  if (!file) return -1;
+  const long long length = geaResourceLength(file);
+  std::fclose(file);
+  return static_cast<double>(length);
+}
+
+// Reads the whole file into `bytes` when it holds exactly `byteLength` bytes.
+// Answers the bytes read, or -1 (missing file, refused name, other size, short read).
+extern "C" double gea_three_resource_read_bytes(std::string name, void *bytes, double byteLength) {
+  if (!bytes && byteLength != 0) return -1;
+  FILE *file = geaOpenResource(name);
+  if (!file) return -1;
+  const long long length = geaResourceLength(file);
+  double result = -1;
+  if (length >= 0 && static_cast<double>(length) == byteLength) {
+    const size_t wanted = static_cast<size_t>(length);
+    if (wanted == 0 || std::fread(bytes, 1, wanted, file) == wanted) result = static_cast<double>(length);
+  }
+  std::fclose(file);
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {
@@ -21,6 +21,7 @@
     "./nativeWebXRManager": "./src/nativeWebXRManager.ts",
     "./troika-three-text": "./src/troika-three-text.ts",
     "./inflate": "./src/inflate.ts",
+    "./nativeResources": "./src/nativeResources.ts",
     "./geatsc-plugin": "./geatsc-plugin.mjs",
     "./native/*": "./native/*",
     "./package.json": "./package.json",
@@ -53,7 +54,7 @@
     "test:host-effects": "node test/native-host-effects-contract.test.mjs",
     "test:allocation-contracts": "node test/render-sort-contract.test.mjs && node test/upload-array-contract.test.mjs && node test/draw-dispatch-contract.test.mjs && node test/native-upload-transport.test.mjs && node test/fixed-uniform-contract.test.mjs && node test/uniform-binding-contract.test.mjs && node test/buffer-streaming-contract.test.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs && node test/gea-native-declaration.test.mjs",
+    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/info-log-contract.test.mjs && node test/resource-host-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs && node test/gea-native-declaration.test.mjs",
     "test:package": "node --experimental-vm-modules test/package.test.mjs"
   },
   "dependencies": {

package/src/nativeResources.ts

@@ -0,0 +1,22 @@
+// Files the app ships in its Resources folder (native/resource_host.mm): the
+// app bundle's resource directory on macOS, the Resources folder beside the
+// executable elsewhere. Names are relative to it, with '/' between parts.
+
+/** @gea-host-inert Reads its argument and the file system only; never calls back into script. */
+declare function threeResourceSize(name: string): number
+/** @gea-host-typed-array-element-writes Stores the file's bytes into the destination typed array's elements only; no other property of any object, no callbacks. */
+declare function threeResourceRead(name: string, destination: Uint8Array): number
+
+/** The size in bytes of a file in Resources, or -1 when there is none. */
+export function nativeResourceSize(name: string): number {
+  return threeResourceSize(name)
+}
+
+/** Reads a whole file from Resources; throws when it is missing or cannot be read. */
+export function nativeReadResource(name: string): Uint8Array {
+  const size = threeResourceSize(name)
+  if (size < 0) throw new Error(`Missing resource: ${name}`)
+  const bytes = new Uint8Array(size)
+  if (threeResourceRead(name, bytes) !== size) throw new Error(`Could not read resource: ${name}`)
+  return bytes
+}

package/src/nativeWebGL.ts

@@ -59,7 +59,9 @@ import {
   nativeWebGLGetError,
   nativeWebGLGetActiveAttribInfo,
   nativeWebGLGetActiveUniformInfo,
+  nativeWebGLGetProgramInfoLog,
   nativeWebGLGetProgramParameter,
+  nativeWebGLGetShaderInfoLog,
   nativeWebGLGetShaderParameter,
   nativeWebGLGetUniformLocation,
   nativeWebGLHeight,
@@ -1036,7 +1038,7 @@ export class NativeWebGL2RenderingContext {
     if (pname === this.DELETE_STATUS) return false
     return nativeWebGLGetShaderParameter(nativeHandle(shader), pname) !== 0
   }
-  getShaderInfoLog(_shader: NativeHandle | null): string { return '' }
+  getShaderInfoLog(shader: NativeShader): string { return nativeWebGLGetShaderInfoLog(nativeHandle(shader)) }
   getShaderSource(shader: NativeShader): string { return shaderSourceFor(shader) }
   deleteShader(shader: NativeShader | null): void { if (shader) { shaderSourceByHandle.delete(nativeHandle(shader)); nativeWebGLDeleteShader(nativeHandle(shader)) } }
 
@@ -1065,7 +1067,7 @@ export class NativeWebGL2RenderingContext {
     if (pname === this.VALIDATE_STATUS) return true
     return nativeWebGLGetProgramParameter(nativeHandle(program), pname) !== 0
   }
-  getProgramInfoLog(_program: NativeProgram | null): string { return '' }
+  getProgramInfoLog(program: NativeProgram): string { return nativeWebGLGetProgramInfoLog(nativeHandle(program)) }
   deleteProgram(program: NativeProgram | null): void { if (program) { nativeWebGLDeleteProgram(nativeHandle(program)) } }
   validateProgram(_program: NativeProgram): void {}
   getAttachedShaders(program: NativeProgram): NativeShader[] { return program.shaders }

package/src/nativeWebGLHost.ts

@@ -35,6 +35,16 @@ export function nativeWebGLSwap(): void {
   threeWebGLSwap()
 }
 
+/**
+ * Vertical sync from the next frame on. Off presents at once, so the frame rate shows what
+ * a frame costs. On paces presents to the display: interval 1 where nothing else paces the
+ * frames (a desktop window with no display link), the host's own pacing on Apple platforms,
+ * where a second waiter would only make frames miss refreshes.
+ */
+export function nativeWebGLSetVsync(on: boolean): void {
+  threeWebGLSetVsync(on ? 1 : 0)
+}
+
 // GPU time-elapsed timers (GL_EXT_disjoint_timer_query): begin returns a timer id (0 when
 // unsupported), end closes the open timer, and result is the elapsed nanoseconds, or -1 while the
 // GPU has not finished it. A timer is released once its result has been read.
@@ -88,12 +98,14 @@ export function nativeWebGLCreateShader(type: number): number { return threeWebG
 export function nativeWebGLShaderSource(shader: number, source: string): void { threeWebGLShaderSource(shader, source) }
 export function nativeWebGLCompileShader(shader: number): void { threeWebGLCompileShader(shader) }
 export function nativeWebGLGetShaderParameter(shader: number, pname: number): number { return threeWebGLGetShaderParameter(shader, pname) }
+export function nativeWebGLGetShaderInfoLog(shader: number): string { return threeWebGLGetShaderInfoLog(shader) }
 export function nativeWebGLDeleteShader(shader: number): void { threeWebGLDeleteShader(shader) }
 
 export function nativeWebGLCreateProgram(): number { return threeWebGLCreateProgram() }
 export function nativeWebGLAttachShader(program: number, shader: number): void { threeWebGLAttachShader(program, shader) }
 export function nativeWebGLLinkProgram(program: number): void { threeWebGLLinkProgram(program) }
 export function nativeWebGLGetProgramParameter(program: number, pname: number): number { return threeWebGLGetProgramParameter(program, pname) }
+export function nativeWebGLGetProgramInfoLog(program: number): string { return threeWebGLGetProgramInfoLog(program) }
 export function nativeWebGLDeleteProgram(program: number): void { threeWebGLDeleteProgram(program) }
 export function nativeWebGLUseProgram(program: number): void { threeWebGLUseProgram(program) }
 export function nativeWebGLGetAttribLocation(program: number, name: string): number { return threeWebGLGetAttribLocation(program, name) }
@@ -187,6 +199,8 @@ declare function threeWebGLDevicePixelRatio(): number
 /** Lifecycle entry: presents the native surface and may run platform hooks; not an inert call. */
 declare function threeWebGLSwap(): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLSetVsync(on: number): void
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeAngleSmokeLog(message: string): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeKeyPressed(code: number): boolean
@@ -207,6 +221,8 @@ declare function threeWebGLCompileShader(shader: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLGetShaderParameter(shader: number, pname: number): number
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLGetShaderInfoLog(shader: number): string
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLDeleteShader(shader: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLCreateProgram(): number
@@ -217,6 +233,8 @@ declare function threeWebGLLinkProgram(program: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLGetProgramParameter(program: number, pname: number): number
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLGetProgramInfoLog(program: number): string
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLDeleteProgram(program: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLUseProgram(program: number): void