[contrib.glfw3] new project version 3.4.0.20240731 (#22303)

This contains 2 new versions with the following release notes for the
underlying project:

#### 3.4.0.20240731 - 2024-07-31

- Added `emscripten_glfw_get_clipboard_string` the C version of
`emscripten::glfw3::GetClipboardString` to
  retrieve the clipboard asynchronously
- Added a helper class `emscripten::glfw3::FutureClipboardString` to
greatly simplify the more frequent use-cases
- `GetClipboardString::value()` now returns the internal clipboard in
case of error, instead of throwing exception
- Added `optimizationLevel` option to the emscripten port

#### 3.4.0.20240727 - 2024-07-27

- Introduced C++ API (namespace `emscripten::glfw3`) included with
`GLFW3/emscripten_glfw3.h`:
- provides a more correct API with sensible defaults (ex:
`std::string_view` / `std::optional<std::string_view>`
    vs `char const *` which may or may not be `nullptr`)
  - allow for C++ only API (ex: `std::future`)
  - the C API is still available if you would rather stick to it
- Implemented `emscripten::glfw3::GetClipboardString` which provides a
way of fetching the global
clipboard in a browser environment (`glfwGetClipboardString` is not the
right API due to the asynchronous nature
  of the underlying platform API).
- The cursor position is no longer clamped to the window size, and as a
result, can have negative values or values
  greater than the window size.
Note that GLFW implements a similar behavior on the macOS desktop
platform.
- Implemented `glfwSetWindowPosCallback`
- Added support for GLFW Window Attribute `GLFW_HOVERED`
- Fixed [#6](pongasoft/emscripten-glfw#6):
_`emscripten_glfw_make_canvas_resizable` does not clean up properly_.
- Fixed an issue with opacity: when using opacity, the handle is not
working unless its z-index is higher than the
  canvas z-index

tools/ports/contrib/glfw3.py

@@ -4,32 +4,43 @@
 # found in the LICENSE file.
 
 import os
-from typing import Dict
+from typing import Union, Dict
 
-TAG = '3.4.0.20240627'
-HASH = '6598834deece7087fd5dda14ec6d410ae651c39b9955eb050dd736a7d3eb650075fc69cf70340f4f0514bef63723a5bbcc315397ec44ba7cab46e59fa137e27f'
+TAG = '3.4.0.20240731'
+HASH = '1d348f2a6423def537bc11ba5a67347d23696f623e0155e315711d0e23e9b4e6f623019c24c699b6dd5b727322f7093af804d58fc48488f37888ba17300c3aa8'
 
 # contrib port information (required)
 URL = 'https://github.com/pongasoft/emscripten-glfw'
-DESCRIPTION = 'This project is an emscripten port of GLFW written in C++ for the web/webassembly platform'
+DESCRIPTION = 'This project is an emscripten port of GLFW 3.4 written in C++ for the web/webassembly platform'
 LICENSE = 'Apache 2.0 license'
 
+VALID_OPTION_VALUES = {
+  'disableWarning': ['true', 'false'],
+  'disableJoystick': ['true', 'false'],
+  'disableMultiWindow': ['true', 'false'],
+  'optimizationLevel': ['0', '1', '2', '3', 'g', 's', 'z']  # all -OX possibilities
+}
+
 OPTIONS = {
   'disableWarning': 'Boolean to disable warnings emitted by the library',
   'disableJoystick': 'Boolean to disable support for joystick entirely',
-  'disableMultiWindow': 'Boolean to disable multi window support which makes the code smaller and faster'
+  'disableMultiWindow': 'Boolean to disable multi window support which makes the code smaller and faster',
+  'optimizationLevel': f'Optimization level: {VALID_OPTION_VALUES["optimizationLevel"]} (default to 2)',
 }
 
 # user options (from --use-port)
-opts: Dict[str, bool] = {
+opts: Dict[str, Union[str, bool]] = {
   'disableWarning': False,
   'disableJoystick': False,
-  'disableMultiWindow': False
+  'disableMultiWindow': False,
+  'optimizationLevel': '2'
 }
 
+port_name = 'contrib.glfw3'
+
 
 def get_lib_name(settings):
-  return ('lib_contrib.glfw3' +
+  return (f'lib_{port_name}-O{opts["optimizationLevel"]}' +
           ('-nw' if opts['disableWarning'] else '') +
           ('-nj' if opts['disableJoystick'] else '') +
           ('-sw' if opts['disableMultiWindow'] else '') +
@@ -38,18 +49,18 @@ def get_lib_name(settings):
 
 def get(ports, settings, shared):
   # get the port
-  ports.fetch_project('contrib.glfw3',
+  ports.fetch_project(port_name,
                       f'https://github.com/pongasoft/emscripten-glfw/releases/download/v{TAG}/emscripten-glfw3-{TAG}.zip',
                       sha512hash=HASH)
 
   def create(final):
-    root_path = os.path.join(ports.get_dir(), 'contrib.glfw3')
+    root_path = os.path.join(ports.get_dir(), port_name)
     source_path = os.path.join(root_path, 'src', 'cpp')
     source_include_paths = [os.path.join(root_path, 'external'), os.path.join(root_path, 'include')]
     for source_include_path in source_include_paths:
-      ports.install_headers(os.path.join(source_include_path, 'GLFW'), target=os.path.join('contrib.glfw3', 'GLFW'))
+      ports.install_headers(os.path.join(source_include_path, 'GLFW'), target=os.path.join(port_name, 'GLFW'))
 
-    flags = []
+    flags = [f'-O{opts["optimizationLevel"]}']
 
     if opts['disableWarning']:
       flags += ['-DEMSCRIPTEN_GLFW3_DISABLE_WARNING']
@@ -60,7 +71,7 @@ def create(final):
     if opts['disableMultiWindow']:
       flags += ['-DEMSCRIPTEN_GLFW3_DISABLE_MULTI_WINDOW_SUPPORT']
 
-    ports.build_port(source_path, final, 'contrib.glfw3', includes=source_include_paths, flags=flags)
+    ports.build_port(source_path, final, port_name, includes=source_include_paths, flags=flags)
 
   return [shared.cache.get_lib(get_lib_name(settings), create, what='port')]
 
@@ -70,7 +81,7 @@ def clear(ports, settings, shared):
 
 
 def linker_setup(ports, settings):
-  root_path = os.path.join(ports.get_dir(), 'contrib.glfw3')
+  root_path = os.path.join(ports.get_dir(), port_name)
   source_js_path = os.path.join(root_path, 'src', 'js', 'lib_emscripten_glfw3.js')
   settings.JS_LIBRARIES += [source_js_path]
 
@@ -79,12 +90,17 @@ def linker_setup(ports, settings):
 # so that we don't conflict with the builtin GLFW headers that emscripten
 # includes
 def process_args(ports):
-  return ['-isystem', ports.get_include_dir('contrib.glfw3'), '-DEMSCRIPTEN_USE_PORT_CONTRIB_GLFW3']
+  return ['-isystem', ports.get_include_dir(port_name), '-DEMSCRIPTEN_USE_PORT_CONTRIB_GLFW3']
+
+
+def check_option(option, value, error_handler):
+  if value not in VALID_OPTION_VALUES[option]:
+    error_handler(f'[{option}] can be {list(VALID_OPTION_VALUES[option])}, got [{value}]')
+  if isinstance(opts[option], bool):
+    value = value == 'true'
+  return value
 
 
 def handle_options(options, error_handler):
   for option, value in options.items():
-    if value.lower() in {'true', 'false'}:
-      opts[option] = value.lower() == 'true'
-    else:
-      error_handler(f'{option} is expecting a boolean, got {value}')
+    opts[option] = check_option(option, value.lower(), error_handler)