Updated readme and documentation

Author: ypujante

CMakeLists.txt

@@ -1,8 +1,8 @@
 cmake_minimum_required(VERSION 3.10)
 
 set(emscripten-glfw_RELEASE_YEAR  "2025")
-set(emscripten-glfw_RELEASE_MONTH "06"  )
-set(emscripten-glfw_RELEASE_DAY   "07"  )
+set(emscripten-glfw_RELEASE_MONTH "08"  )
+set(emscripten-glfw_RELEASE_DAY   "24"  )
 
 set(emscripten-glfw_GLFW_VERSION "3.4.0")
 
@@ -57,7 +57,7 @@ if(NOT EMSCRIPTEN_GLFW3_DISABLE_JOYSTICK)
 endif()
 
 # Update the version appropriately
-configure_file("${CMAKE_CURRENT_LIST_DIR}/version.h.in" "${CMAKE_CURRENT_BINARY_DIR}/emscripten_glfw3_version.h" @ONLY)
+configure_file("${CMAKE_CURRENT_LIST_DIR}/version.h.in" "${CMAKE_CURRENT_LIST_DIR}/include/GLFW/emscripten_glfw3_version.h" @ONLY)
 
 macro(add_glfw_lib LIBRARY_NAME)
   add_library(${LIBRARY_NAME} ${glfw3_sources})

README.md

@@ -4,12 +4,16 @@ Introduction
 This project is an Emscripten port of GLFW written in C++ for the web/wasm platform. The currently supported
 GLFW API is 3.4.
 
-[![emscripten - 4.0.11](https://img.shields.io/badge/emscripten-4.0.11-blue)](https://emscripten.org)
-[![contrib.glfw3 - 3.4.0.20250607](https://img.shields.io/badge/contrib.glfw3-3.4.0.20250607-blue)](https://github.com/pongasoft/emscripten-glfw/releases/latest)
+[![emscripten - TBD](https://img.shields.io/badge/emscripten-TBD-blue)](https://emscripten.org)
+[![contrib.glfw3 - 3.4.0.20250824](https://img.shields.io/badge/contrib.glfw3-3.4.0.20250824-blue)](https://github.com/pongasoft/emscripten-glfw/releases/latest)
 [![GLFW - 3.4.0](https://img.shields.io/badge/GLFW-3.4.0-blue)](https://www.glfw.org/)
 [![License](https://img.shields.io/badge/License-Apache%20License%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 ![Compiles](https://github.com/pongasoft/emscripten-glfw/actions/workflows/main.yml/badge.svg)
 
+[![emscripten - 4.0.11](https://img.shields.io/badge/emscripten-4.0.11-blue)](https://emscripten.org)
+[![contrib.glfw3 - 3.4.0.20250607](https://img.shields.io/badge/contrib.glfw3-3.4.0.20250607-blue)](https://github.com/pongasoft/emscripten-glfw/releases/latest)
+[![GLFW - 3.4.0](https://img.shields.io/badge/GLFW-3.4.0-blue)](https://www.glfw.org/)
+
 Goal
 ----
 
@@ -209,6 +213,7 @@ emcc --use-port=contrib.glfw3:disableWarning=true:disableMultiWindow=true main.c
 > #### Note about availability in Emscripten
 > | Emscripten | this port      |
 > |------------|----------------|
+> | TBD        | 3.4.0.20250824 |
 > | 4.0.11     | 3.4.0.20250607 |
 > | 4.0.5      | 3.4.0.20250305 |
 > | 4.0.4      | 3.4.0.20250209 |
@@ -243,6 +248,14 @@ Check the [Building](docs/Building.md) page for details on how to build this pro
 
 Release Notes
 -------------
+#### 3.4.0.20250824 - 2025-08-24 | Emscripten TBD
+
+- The code has been optimized for size
+- Fixed [#21](https://github.com/pongasoft/emscripten-glfw/issues/21): Flicker when resizing
+  - to fix this issue, resizing (when the handle is moved or the window resized) is now delayed until `glfwPollEvents()`
+    is called. Make sure to call `glfwPollEvents()` at the beginning of the loop to ensure a flicker-free experience.
+    See [Events & Main loop](docs/Usage.md#events--main-loop) for more details.
+
 #### 3.4.0.20250607 - 2025-06-07 | Emscripten 4.0.11
 
 - The main port file has been simplified and is now using the new (as of 4.0.10) "external port file" Emscripten feature

archive.txt

@@ -12,6 +12,7 @@ src/cpp/emscripten/glfw3/Cursor.h
 src/cpp/emscripten/glfw3/ErrorHandler.cpp
 src/cpp/emscripten/glfw3/ErrorHandler.h
 src/cpp/emscripten/glfw3/Events.h
+src/cpp/emscripten/glfw3/Events.cpp
 src/cpp/emscripten/glfw3/Joystick.cpp
 src/cpp/emscripten/glfw3/Joystick.h
 src/cpp/emscripten/glfw3/Keyboard.cpp

docs/Usage.md

@@ -165,6 +165,55 @@ emscripten::glfw3::MakeCanvasResizable(window, "#canvas1-container", "canvas1-ha
 > If you do not want the canvas to be resizable by the user, you can simply set its size during window creation
 > (`glfwCreateWindow`) or with `glfwSetWindowSize` and don't do anything else.
 
+## Events & Main loop
+
+It is strongly recommended to use the `emscripten_set_main_loop` (or `emscripten_set_main_loop_arg`) API 
+provided by Emscripten to run the main loop.
+
+Here is an example:
+
+```cpp
+//! The main loop (called by emscripten for each frame)
+void main_loop(void *user_data)
+{
+  auto window = reinterpret_cast<GLFWwindow *>(user_data);
+  if(!glfwWindowShouldClose(window))
+  {
+    glfwPollEvents();
+    
+    // render frame
+    // ...
+  }
+  else
+  {
+    // done => terminating
+    glfwTerminate();
+    emscripten_cancel_main_loop();
+  }
+}
+
+//! main
+int main()
+{
+  // create the window...
+  // auto window = glfwCreateWindow(...);
+  
+  // tell emscripten to use "main_loop" as the main loop (window is user data)
+  emscripten_set_main_loop_arg(main_loop, window, 0, GLFW_FALSE);
+}
+```
+
+This ensures that the `requestAnimationFrame` mechanism of the browser is used
+(see [documentation](https://emscripten.org/docs/api_reference/emscripten.h.html#c.emscripten_set_main_loop)).
+
+> [!Note]
+> `glfwPollEvents()` is called at the beginning of the loop because it processes the events that are necessary
+> for rendering the frame. In particular, it applies any window resize request, which triggers the canvas to be 
+> resized. When the canvas gets resized, the browser paints it black, which is why the "render frame" section
+> needs to re-render the content (using the new size).
+
+
+
 ## Fullscreen support
 
 GLFW has a concept of a fullscreen window.

include/GLFW/emscripten_glfw3_version.h

@@ -24,8 +24,8 @@
 // #if EMSCRIPTEN_GLFW_VERSION >= 3'4'0'20240801
 // .... code that can be used past a certain release
 // #endif
-#define EMSCRIPTEN_GLFW_VERSION 3'4'0'20250607
+#define EMSCRIPTEN_GLFW_VERSION 3'4'0'20250824
 
-#define EMSCRIPTEN_GLFW_FULL_VERSION_STR "3.4.0.20250607"
+#define EMSCRIPTEN_GLFW_FULL_VERSION_STR "3.4.0.20250824"
 
 #endif

port/emscripten-glfw3.py

@@ -14,10 +14,10 @@
 #
 # @author Yan Pujante
 
-TAG = '3.4.0.20250607'
+TAG = '3.4.0.20250824'
 
 EXTERNAL_PORT = f'https://github.com/pongasoft/emscripten-glfw/releases/download/v{TAG}/emscripten-glfw3-{TAG}.zip'
-SHA512 = '1b264ac8891ffff51b899ca5853d4f945294dde9a9191eb5df9dd4cb26a4b27c5e7dac99cad42466833e9aae76d450de8a4b84381a63214321dc0427fd054f1b'
+SHA512 = 'b5b3670b80c87571ea56a54e701874d6b2323f74e359782a15c9ae0a931341fb05e4c778945950f8846aef66c7cc48556d30c8cc5939c87e3091c8be63856a1a'
 PORT_FILE = 'port/glfw3.py'
 
 # contrib port information (required)