Update EMSCRIPTEN_WEBGL_CONTEXT_HANDLE to handle full pointer range

In particular this changes the return type of
`emscripten_webgl_create_context` such that negative values can no
longer be returned.

This allows pointers (specifically 32-bit pointers over 2gb) to be
returned which is needed for pthread builds.

The only valid failure return code for `emscripten_webgl_create_context`
is now 0/NULL.  As it happens this function never fails with anything
except 0 so this should not be an impactful change.

Split out from #21268

Fixes: #21278

.circleci/config.yml

@@ -819,6 +819,7 @@ jobs:
             browser_2gb.test_emscripten_animate_canvas_element_size_manual_css
             browser_2gb.test_fulles2_sdlproc
             browser_2gb.test_cubegeom*
+            browser_2gb.test_html5_webgl_create_context*
             "
   test-browser-chrome-wasm64-4gb:
     executor: bionic
@@ -834,6 +835,7 @@ jobs:
             browser64_4gb.test_fetch*
             browser64_4gb.test_emscripten_animate_canvas_element_size_manual_css
             browser64_4gb.test_fulles2_sdlproc
+            browser64_4gb.test_html5_webgl_create_context*
             "
   test-browser-firefox:
     executor: bionic

ChangeLog.md

@@ -20,6 +20,12 @@ See docs/process.md for more on how version tagging works.
 
 3.1.54 (in development)
 -----------------------
+- The type of `EMSCRIPTEN_WEBGL_CONTEXT_HANDLE` was changed to unsigned and
+  the only valid error returned from `emscripten_webgl_create_context` is
+  now zero.  This allows `EMSCRIPTEN_WEBGL_CONTEXT_HANDLE` to hold a pointer
+  to memory even in 2GB+ mode.  Since `emscripten_webgl_create_context` never
+  returns anything except zero for its errors today this change should not
+  require any action. (#21268)
 - Added `--use-port` option to `emcc`.  This option allows ports to be enabled
   by name and is designed to replace all existing `-sUSE_XXX` settings for
   ports. You can use `--show-ports` to get the list of available ports that

site/source/docs/api_reference/html5.h.rst

@@ -2086,7 +2086,7 @@ Functions
   :type target: const char*
   :param attributes: The attributes of the requested context version.
   :type attributes: const EmscriptenWebGLContextAttributes*
-  :returns: On success, a strictly positive value that represents a handle to the created context. On failure, a negative number that can be cast to an |EMSCRIPTEN_RESULT| field to get the reason why the context creation failed.
+  :returns: On success, a non-zero value that represents a handle to the created context. On failure, 0.
   :rtype: |EMSCRIPTEN_WEBGL_CONTEXT_HANDLE|
 
 

system/include/emscripten/html5_webgl.h

@@ -14,7 +14,7 @@
 extern "C" {
 #endif
 
-typedef intptr_t EMSCRIPTEN_WEBGL_CONTEXT_HANDLE;
+typedef uintptr_t EMSCRIPTEN_WEBGL_CONTEXT_HANDLE;
 
 typedef int EMSCRIPTEN_WEBGL_CONTEXT_PROXY_MODE;
 #define EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW 0