Fix GLUT window resizing when CSS scaling (#24699)

When using GLUT and the window is resized with the canvas dependent upon
it due to CSS scaling, the result is a stretched canvas with blocky
pixel scaling. Here's a CSS scaling example:

    <style>
        canvas {
            position: fixed;
            width: 75%;
            height: 75%;
        }
    </style>
    <canvas id="canvas"></canvas>

While position fixed isn't strictly necessary, it more readily shows the
problem as it makes the canvas size directly dependent upon the browser
window. For comparison, SDL behaves properly in this same scenario.

## Fix 

Three issues were found:
1. On window resize, glutReshapeFunc is never called.

2. Even with glutReshapeFunc working, the dimensions passed to it do not
include CSS scaling. Specifically, the canvas width and height are never
updated with the canvas clientWidth and clientHeight, which does include
scaling.

3. On GLUT program startup, glutMainLoop calls glutReshapeWindow, which
is slightly problematic for the case of loading the page while already
in fullscreen. This is a problem because, while an initial resize is
needed on startup, glutReshapeWindow also forces an exit from fullscreen
mode.

Here are the proposed fixes:

1. Register a new resize callback `GLUT.reshapeHandler` using
`window.addEventListener`, replacing `Browser.resizeListeners.push`.
Previous work in this area (see below) utilized `resizeListeners`,
however this fix takes a different route that is self-contained and I
think simpler:
- Using `window.addEventListener` keeps the fix entirely within
`libglut.js`, avoiding any `libbrowser.js` changes as in previous
attempts. As well, `updateResizeListeners` doesn't pass CSS-scaled
canvas dimensions, so changing `updateResizeListeners` implementation
might be necessary and this could impact other non-GLUT clients, going
beyond this GLUT-only fix.
- Since `glutInit` already utilizes `window.addEventListener` for all
other event handling, doing the same for the resize event seems
consistent and simpler, as it avoids mixing event handling methods for
GLUT.

2. Create a new resize callback function, `GLUT.reshapeHandler`, which
does the following:
- Updates `canvas` dimensions (via `Browser.setCanvasSize`) to
`canvas.clientWidth` and `clientHeight`, so that CSS scaling is
accounted for. If no CSS scaling is present, `clientWidth` and
`clientHeight` match `canvas.width` and `height`, so these values are
safe to use in all cases, scaling or not.
- After updating the canvas size, pass `clientWidth` and `clientHeight`
to `glutReshapeFunc`. This is needed so that GLUT reshape callbacks can
properly update their viewport transform by calling `glViewport` with
the actual canvas dimensions.

3. At GLUT startup in `glutMainLoop`, call `GLUT.reshapeHandler` instead
of `glutReshapeWindow`.
- As mentioned above, `glutReshapeWindow` has an unwanted side effect of
always forcing an exit from fullscreen (and this is by design, according
to the [GLUT
API](https://www.opengl.org/resources/libraries/glut/spec3/node23.html)).


## Testing

Manual testing:
1. Window resizing with no CSS, CSS scaling, CSS pixel dimensions, and a
mix of these for canvas width and height.
2. Entering and exiting fullscreen, and loading a page while already in
fullscreen.
3. No DPI testing done (window.devicePixelRatio != 1), as GLUT is not
currently DPI aware and this fix does not address it. I did confirm on
Retina Mac that this fix doesn't make this issue any better or worse.

Automated tests:
1. Added test/browser/test_glut_resize.c, with tests to assert canvas
size matches target size under various scenarios (no CSS, CSS scaling,
CSS pixel dimensions, and a mix of these), as well as canvas size always
matching canvas client size (clientWidth and clientHeight).
2. Since programmatic browser window resizing is not allowed for
security reasons, these tests dispatch a resize event after each CSS
style change as a workaround.
3. Also added tests to assert canvas size consistency after glutMainLoop
and glutReshapeWindow API calls.

## Related work

All the previous work in this area worked toward enabling GLUT resize
callbacks via Emscripten’s built-in event handling (specifically
`Browser.resizeListeners` and `updateResizeListeners`). As mentioned
above, this fix takes a different approach that is entirely
self-contained within `libglut.js`.

This 2013
[commit](6d6490e)
added `GLUT.reshapeFunc` to `Browser.resizeListeners`, presumably to
handle window resizing. However there is no test code with that commit,
and as of current Emscripten, `updateResizeListeners()` is never called
on window resizing with GLUT programs, so this code is currently a
no-op.

[Issue 7133](#7133)
(that I logged in 2018, hi again!) got part of the way on a fix, but
used `glutReshapeWindow` which has the previously mentioned side effect
of exiting fullscreen. This was closed unresolved.

[PR 9835](#9835)
proposed a fix for 7133. Also closed unresolved, this fix involved
modifying `libbrowser.js` in order to get resize callbacks to GLUT via
`resizeListeners`. While this got resize callbacks working, in my
testing it didn’t pass CSS-scaled canvas size in the callback (the
all-important clientWidth and clientHeight).

I also looked at how SDL handles resizing, which uses
`resizeEventListeners`, but decided the more straightforward fix was to
use `addEventListener`. Last, I looked at [GLFW CSS scaling
test](https://github.com/emscripten-core/emscripten/blob/main/test/browser/test_glfw3_css_scaling.c)
which was helpful in writing the automated tests and also to confirm
that no DPI ratio work is addressed by this fix.

Fixes: #7133

---------

Co-authored-by: Sam Clegg <[email protected]>

Author: erik-larsen

src/lib/libglut.js

@@ -298,6 +298,13 @@ var LibraryGLUT = {
         {{{ makeDynCall('vii', 'GLUT.reshapeFunc') }}}(width, height);
       }
       _glutPostRedisplay();
+    },
+
+    // Resize callback stage 1: update canvas by setCanvasSize, which notifies resizeListeners including GLUT.reshapeFunc
+    onResize: () => {
+      // Update canvas size to clientWidth and clientHeight, which include CSS scaling
+      var canvas = Browser.getCanvas();
+      Browser.setCanvasSize(canvas.clientWidth, canvas.clientHeight, /*noUpdates*/false);
     }
   },
 
@@ -336,6 +343,10 @@ var LibraryGLUT = {
     // Firefox
     window.addEventListener('DOMMouseScroll', GLUT.onMouseWheel, true);
 
+    // Resize callback stage 1: update canvas which notifies resizeListeners
+    window.addEventListener('resize', GLUT.onResize, true);
+
+    // Resize callback stage 2: updateResizeListeners notifies reshapeFunc
     Browser.resizeListeners.push((width, height) => {
       if (GLUT.reshapeFunc) {
         {{{ makeDynCall('vii', 'GLUT.reshapeFunc') }}}(width, height);
@@ -359,6 +370,8 @@ var LibraryGLUT = {
       // Firefox
       window.removeEventListener('DOMMouseScroll', GLUT.onMouseWheel, true);
 
+      window.removeEventListener('resize', GLUT.onResize, true);
+
       var canvas = Browser.getCanvas();
       canvas.width = canvas.height = 1;
     });
@@ -633,10 +646,10 @@ var LibraryGLUT = {
   },
 
   glutMainLoop__proxy: 'sync',
-  glutMainLoop__deps: ['$GLUT', 'glutReshapeWindow', 'glutPostRedisplay'],
+  glutMainLoop__deps: ['$GLUT', 'glutPostRedisplay'],
   glutMainLoop: () => {
-    var canvas = Browser.getCanvas();
-    _glutReshapeWindow(canvas.width, canvas.height);
+    // Do an initial resize, since there's no window resize event on startup
+    GLUT.onResize();
     _glutPostRedisplay();
     throw 'unwind';
   },

test/browser/test_glut_resize.c

@@ -0,0 +1,208 @@
+/*
+ * Copyright 2025 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.
+ */
+
+#include <stdio.h>
+#include <assert.h>
+#include <stdint.h>
+#include <emscripten/emscripten.h>
+#include <GL/glut.h>
+
+typedef struct {
+  int32_t width;
+  int32_t height;
+} rect_size_t;
+
+static rect_size_t browser_window_size = { 0, 0 };
+static rect_size_t glut_init_size =      { 0, 0 };
+static rect_size_t glut_reshape_size =   { 0, 0 };
+static rect_size_t target_size =         { 0, 0 };
+
+/*
+ * Set run_async_verification to 0 for sync test cases, and 1 for async tests.
+ *
+ * Callback sequence for test case 1 & 2 (synchronous):
+ * glutMainLoop -> GLUT.onSize -> Browser.setCanvasSize -> updateResizeListeners -> GLUT.reshapeFunc
+ * glutResizeWindow -> Browser.setCanvasSize -> updateResizeListeners -> GLUT.reshapeFunc
+ *
+ * Callback sequence for test cases 3-5 (async):
+ * window resize -> async update -> GLUT.onSize -> Browser.setCanvasSize -> updateResizeListeners -> GLUT.reshapeFunc
+ *
+ * Because window resize does not immediately call GLUT.onSize, we wait to run verification of a test until we get
+ * confirmation in GLUT.reshapeFunc.  And after verification is done, we move on to the next test.
+ *
+ */
+static int run_async_verification = 0;
+
+void print_size_test(int test_num, const char* name, rect_size_t rect_size) {
+  printf("Test %d: %s = %d x %d\n", test_num, name, rect_size.width, rect_size.height);
+}
+
+int equal_size(rect_size_t rect_1, rect_size_t rect_2) {
+  return (rect_1.width == rect_2.width && rect_1.height == rect_2.height);
+}
+
+/**
+ * Obtain various dimensions
+ */
+EM_JS(void, get_browser_window_size, (int32_t* width, int32_t* height), {
+  setValue(Number(width), window.innerWidth, 'i32');
+  setValue(Number(height), window.innerHeight, 'i32');
+});
+
+EM_JS(void, get_canvas_client_size, (int32_t* width, int32_t* height), {
+  const canvas = Module.canvas;
+  setValue(Number(width), canvas.clientWidth, 'i32');
+  setValue(Number(height), canvas.clientHeight, 'i32');
+});
+
+EM_JS(void, get_canvas_size, (int32_t* width, int32_t* height), {
+  const canvas = Module.canvas;
+  setValue(Number(width), canvas.width, 'i32');
+  setValue(Number(height), canvas.height, 'i32');
+});
+
+/**
+ * Update canvas style with given width and height, then invoke window resize event
+ */
+EM_JS(void, test_resize_with_CSS, (const char* position, const char* width, const char* height), {
+  const canvas = Module.canvas;
+  canvas.style.position = UTF8ToString(Number(position));
+  canvas.style.width = UTF8ToString(Number(width));
+  canvas.style.height = UTF8ToString(Number(height));
+
+  window.dispatchEvent(new UIEvent('resize'));
+});
+
+/**
+ * Verify canvas and reshape callback match target size, and also that
+ * canvas width, height matches canvas clientWidth, clientHeight
+ */
+void assert_canvas_and_target_sizes_equal() {
+  /* verify target size match */
+  rect_size_t canvas_size;
+  get_canvas_size(&canvas_size.width, &canvas_size.height);
+  assert(equal_size(canvas_size, target_size));
+  assert(equal_size(glut_reshape_size, target_size));
+
+  /* verify canvas client size match */
+  rect_size_t canvas_client_size;
+  get_canvas_client_size(&canvas_client_size.width, &canvas_client_size.height);
+  assert(equal_size(canvas_size, canvas_client_size));
+}
+
+/**
+ * Verify the result of the previous test and then run the next one
+ */
+void verify_test_and_run_next() {
+  void run_next_test();
+
+  assert_canvas_and_target_sizes_equal();
+  run_next_test();
+}
+
+/**
+ * Resizing tests
+ */
+void run_next_test() {
+  static int test_num = 0;
+  ++test_num;
+
+  switch(test_num) {
+    case 1: {
+      /* startup */
+      target_size = glut_init_size;
+      print_size_test(test_num, "startup, no CSS: canvas == glutReshapeFunc == glutInitWindow size", target_size);
+      verify_test_and_run_next();
+      break;
+    }
+    case 2: {
+      /* glutReshapeWindow */
+      target_size.width = glut_init_size.width + 40;
+      target_size.height = glut_init_size.height + 20;
+      print_size_test(test_num, "glut reshape, no CSS: canvas == glutReshapeFunc == glutReshapeWindow size", target_size);
+      glutReshapeWindow(target_size.width, target_size.height);
+      verify_test_and_run_next();
+      break;
+    }
+    case 3: {
+      /* 100% scale CSS */
+      target_size = browser_window_size;
+      print_size_test(test_num, "100% window scale CSS: canvas == glutReshapeFunc == browser window size", target_size);
+      run_async_verification = 1;
+      test_resize_with_CSS("fixed", "100%", "100%"); /* fixed, so canvas is driven by window size */
+      break;
+    }
+    case 4: {
+      /* specific pixel size CSS */
+      target_size.width = glut_init_size.width - 20;
+      target_size.height = glut_init_size.height + 40;
+      print_size_test(test_num, "specific pixel size CSS: canvas == glutReshapeFunc == CSS specific size", target_size);
+      char css_width[16], css_height[16];
+      snprintf (css_width, 16, "%dpx", target_size.width);
+      snprintf (css_height, 16, "%dpx", target_size.height);
+      run_async_verification = 1;
+      test_resize_with_CSS("static", css_width, css_height); /* static, canvas is driven by CSS size */
+      break;
+    }
+    case 5: {
+      /* mix of CSS scale and pixel size */
+      target_size.width = browser_window_size.width;
+      target_size.height = 100;
+      print_size_test(test_num, "100% width, 100px height CSS: canvas == glutReshapeFunc == CSS mixed size", target_size);
+      run_async_verification = 1;
+      test_resize_with_CSS("fixed", "100%", "100px"); /* fixed, canvas width is driven by window size */
+      break;
+    }
+    default: {
+      /* all tests complete */
+      emscripten_force_exit(0);
+      break;
+    }
+  }
+}
+
+/**
+ * Idle callback - start tests
+ */
+void start_tests() {
+  glutIdleFunc(NULL);
+  run_next_test();
+}
+
+/**
+ * Reshape callback - record latest size, verify and run next test if async
+ */
+void reshape(int w, int h) {
+  glut_reshape_size.width = (int32_t)w;
+  glut_reshape_size.height = (int32_t)h;
+
+  if (run_async_verification) {
+    run_async_verification = 0; /* Only one verification per test */
+    verify_test_and_run_next();
+  }
+}
+
+int main(int argc, char *argv[]) {
+  get_browser_window_size(&browser_window_size.width, &browser_window_size.height);
+
+  /* Make glut initial canvas size be 1/2 of browser window */
+  glut_init_size.width = browser_window_size.width / 2;
+  glut_init_size.height = browser_window_size.height / 2;
+
+  glutInit(&argc, argv);
+  glutInitWindowSize(glut_init_size.width, glut_init_size.height);
+  glutInitDisplayMode(GLUT_RGB);
+  glutCreateWindow("test_glut_resize.c");
+
+  /* Set up glut callback functions */
+  glutIdleFunc(start_tests);
+  glutReshapeFunc(reshape);
+  glutDisplayFunc(NULL);
+
+  glutMainLoop();
+  return 0;
+}

test/code_size/test_codesize_hello_dylink_all.json

@@ -1,7 +1,7 @@
 {
-  "a.out.js": 246735,
+  "a.out.js": 246847,
   "a.out.nodebug.wasm": 597852,
-  "total": 844587,
+  "total": 844699,
   "sent": [
     "IMG_Init",
     "IMG_Load",

test/test_browser.py

@@ -1135,6 +1135,9 @@ def test_glut_glutget(self):
     self.btest_exit('glut_glutget.c', cflags=['-lglut', '-lGL'])
     self.btest_exit('glut_glutget.c', cflags=['-lglut', '-lGL', '-DAA_ACTIVATED', '-DDEPTH_ACTIVATED', '-DSTENCIL_ACTIVATED', '-DALPHA_ACTIVATED'])
 
+  def test_glut_resize(self):
+    self.btest_exit('test_glut_resize.c')
+
   def test_sdl_joystick_1(self):
     # Generates events corresponding to the Working Draft of the HTML5 Gamepad API.
     # http://www.w3.org/TR/2012/WD-gamepad-20120529/#gamepad-interface