webgl: populate uniformLocsById on first glUniform (#26846)

PR created with AI assistance.

`$webglGetUniformLocation` reads `program.uniformLocsById` to resolve a
uniform location integer to a `WebGLUniformLocation`. `uniformLocsById`
is reset to `0` by `glLinkProgram` and lazily allocated by
`$webglPrepareUniformLocationsBeforeFirstUse`, but that prepare call
only ran on the `glGetUniformLocation()` path. As a result, calling
`glUniform*()` on a freshly linked program before any
`glGetUniformLocation()` — which is the intended usage with
`-sGL_EXPLICIT_UNIFORM_LOCATION` and `explicit layout(location=N)` —
silently no-opped: `$webglGetUniformLocation` read
`uniformLocsById[location]` off the integer `0`, returned `undefined`,
and `GLctx.uniform*()` dropped the call with no error.

Fix: call `$webglPrepareUniformLocationsBeforeFirstUse(p)` at the top of
`$webglGetUniformLocation`, inside the `GL_TRACK_ERRORS` guard. The
prepare call is idempotent (guards on `!uniformLocsById`), so the
steady-state overhead is a single property read.

Adds `browser.test_webgl_uniform_before_get_location` with two
parameterizations (default and `-sGL_ASSERTIONS`).

Fixes: #26672

Author: vittorioromeo

src/lib/libwebgl.js

@@ -603,7 +603,9 @@ for (/**@suppress{duplicate}*/var i = 0; i <= {{{ GL_POOL_TEMP_BUFFERS_SIZE }}};
 
 #if GL_ASSERTIONS
     validateGLObjectID: (objectHandleArray, objectID, callerFunctionName, objectReadableType) => {
-      if (objectID != 0) {
+      // `objectHandleArray` may be uninitialized when GL uniforms are lazily initialized, and `glUniform*` is called
+      // for the first time before uniforms have been populated. So ignore this validation if the handle array is not present.
+      if (objectID != 0 && objectHandleArray) {
         if (objectHandleArray[objectID] === null) {
           err(`${callerFunctionName} called with an already deleted ${objectReadableType} ID ${objectID}!`);
         } else if (!(objectID in objectHandleArray)) {
@@ -2171,6 +2173,7 @@ for (/**@suppress{duplicate}*/var i = 0; i <= {{{ GL_POOL_TEMP_BUFFERS_SIZE }}};
 
   // Returns the WebGLUniformLocation object corresponding to the location index
   // integer on the currently active shader in this GL context.
+  $webglGetUniformLocation__deps: ['$webglPrepareUniformLocationsBeforeFirstUse'],
   $webglGetUniformLocation: (location) => {
     var p = GLctx.currentProgram;
 
@@ -2182,6 +2185,14 @@ for (/**@suppress{duplicate}*/var i = 0; i <= {{{ GL_POOL_TEMP_BUFFERS_SIZE }}};
 
 #if GL_TRACK_ERRORS
     if (p) {
+#endif
+#if GL_EXPLICIT_UNIFORM_LOCATION
+      // Ensure `uniformLocsById`/`uniformArrayNamesById` are populated. Without
+      // this, calling `glUniform*()` on a freshly linked program before any
+      // `glGetUniformLocation()` silently no-ops: `glLinkProgram` resets
+      // `uniformLocsById` to 0 and only `$webglPrepareUniformLocationsBeforeFirstUse`
+      // refills it. The call below is idempotent (guards on `!uniformLocsById`).
+      webglPrepareUniformLocationsBeforeFirstUse(p);
 #endif
       var webglLoc = p.uniformLocsById[location];
       // p.uniformLocsById[location] stores either an integer, or a
@@ -3865,7 +3876,7 @@ for (/**@suppress{duplicate}*/var i = 0; i <= {{{ GL_POOL_TEMP_BUFFERS_SIZE }}};
       GLctx.bufferSubData(0x8893 /*GL_ELEMENT_ARRAY_BUFFER*/,
                           0,
                           HEAPU8.subarray(indices, indices + size));
-      
+
       // Calculating vertex count if shader's attribute data is on client side
       if (count > 0) {
         for (var i = 0; i < GL.currentContext.maxVertexAttribs; ++i) {

test/browser/webgl_uniform_before_get_location.c

@@ -0,0 +1,85 @@
+// Copyright 2026 The Emscripten Authors.  All rights reserved.
+// Emscripten is available under two separate licenses, the MIT license and the
+// University of Illinois/NCSA Open Source License.  Both these licenses can be
+// found in the LICENSE file.
+
+// Regression test for $webglGetUniformLocation silently returning undefined
+// when called from a glUniform*() setter on a freshly linked program before
+// any glGetUniformLocation() has run.
+//
+// glLinkProgram resets program.uniformLocsById to 0; only
+// $webglPrepareUniformLocationsBeforeFirstUse populates it. That prepare call
+// used to live only on the glGetUniformLocation() path, so a program author
+// using -sGL_EXPLICIT_UNIFORM_LOCATION and addressing uniforms by their
+// layout(location=N) value (i.e. without ever calling glGetUniformLocation)
+// would see glUniform*() silently no-op: GLctx.uniform*(undefined, ...) is
+// dropped by WebGL with no error.
+
+#include <assert.h>
+#include <stdio.h>
+#include <GLES3/gl3.h>
+#include <emscripten/html5.h>
+
+int main() {
+  EmscriptenWebGLContextAttributes attr;
+  emscripten_webgl_init_context_attributes(&attr);
+  attr.majorVersion = 2;
+  EMSCRIPTEN_WEBGL_CONTEXT_HANDLE ctx = emscripten_webgl_create_context("#canvas", &attr);
+  assert(ctx);
+  emscripten_webgl_make_context_current(ctx);
+
+  const char* vs = "#version 300 es\n"
+                   "layout(location = 6) uniform vec3 u_val;\n"
+                   "void main() { gl_Position = vec4(u_val, 1.0); }\n";
+
+  const char* fs = "#version 300 es\n"
+                   "precision mediump float;\n"
+                   "out vec4 o;\n"
+                   "void main() { o = vec4(1.0); }\n";
+
+  GLuint v = glCreateShader(GL_VERTEX_SHADER);
+  glShaderSource(v, 1, &vs, NULL);
+  glCompileShader(v);
+
+  GLuint f = glCreateShader(GL_FRAGMENT_SHADER);
+  glShaderSource(f, 1, &fs, NULL);
+  glCompileShader(f);
+
+  GLuint p = glCreateProgram();
+  glAttachShader(p, v);
+  glAttachShader(p, f);
+  glLinkProgram(p);
+
+  GLint linked = 0;
+  glGetProgramiv(p, GL_LINK_STATUS, &linked);
+  assert(linked && "Program link failed");
+
+  glUseProgram(p);
+
+  // Set a uniform using its explicit layout(location=6) WITHOUT first calling
+  // glGetUniformLocation. Before the fix, this silently no-ops because
+  // $webglGetUniformLocation reads from program.uniformLocsById which is still
+  // 0 from glLinkProgram, returns undefined, and GLctx.uniform3fv ignores it.
+  const float val[] = {1.0f, 2.0f, 3.0f};
+  glUniform3fv(/* location */ 6, 1, val);
+  assert(glGetError() == GL_NO_ERROR);
+
+  float rb[3] = {-1.f, -1.f, -1.f};
+  glGetUniformfv(p, /* location */ 6, rb);
+  assert(glGetError() == GL_NO_ERROR);
+  assert(rb[0] == 1.0f && rb[1] == 2.0f && rb[2] == 3.0f);
+
+  // Subsequent set should also work (was already working before the fix,
+  // because the readback's prepare populated uniformLocsById as a side effect).
+  const float val2[] = {4.0f, 5.0f, 6.0f};
+  glUniform3fv(/* location */ 6, 1, val2);
+  assert(glGetError() == GL_NO_ERROR);
+
+  float rb2[3] = {-1.f, -1.f, -1.f};
+  glGetUniformfv(p, /* location */ 6, rb2);
+  assert(glGetError() == GL_NO_ERROR);
+  assert(rb2[0] == 4.0f && rb2[1] == 5.0f && rb2[2] == 6.0f);
+
+  printf("Test passed!\n");
+  return 0;
+}

test/test_browser.py

@@ -1235,6 +1235,14 @@ def test_webgl_parallel_shader_compile(self):
   def test_webgl_explicit_uniform_location(self):
     self.btest_exit('webgl_explicit_uniform_location.c', cflags=['-sGL_EXPLICIT_UNIFORM_LOCATION', '-sMIN_WEBGL_VERSION=2'])
 
+  @parameterized({
+    '': ([],),
+    'assertions': (['-sGL_ASSERTIONS'],),
+  })
+  @requires_webgl2
+  def test_webgl_uniform_before_get_location(self, args):
+    self.btest_exit('webgl_uniform_before_get_location.c', cflags=args + ['-sGL_EXPLICIT_UNIFORM_LOCATION', '-sMIN_WEBGL_VERSION=2'])
+
   @requires_graphics_hardware
   def test_webgl_sampler_layout_binding(self):
     self.btest_exit('webgl_sampler_layout_binding.c', cflags=['-sGL_EXPLICIT_UNIFORM_BINDING'])