From 106b7cf0b95c07e15d6b0f8c65b35429f053d6b1 Mon Sep 17 00:00:00 2001
From: Gregg Tavares <github@greggman.com>
Date: Sat, 7 Sep 2024 19:11:07 -0700
Subject: [PATCH] Add createTextureAsync and createTexturesAsync

I'm not really sure I should add these. I think I thought
about it before.

The issue is, createTexture and createTextures both return
usable textures immediately. No waiting. If the data for the
texture needs to be loaded asynchronously, they'll return a 1x1
pixel texture. createTextureAsync and createTexturesAsync on the
other hand, only return the texture after their async sources
have loaded.

These are more here for completeness as sometimes you actually
do want to wait until the texture's data is loaded and it's now
common to use promises for this purpose.
---
 src/textures.js | 61 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/src/textures.js b/src/textures.js
index 6e6b19df..a8f2210e 100644
--- a/src/textures.js
+++ b/src/textures.js
@@ -1700,6 +1700,30 @@ function createTexture(gl, options, callback) {
   return tex;
 }
 
+/**
+ * Value returned by createTextureAsync
+ *
+ * @typedef {Object} CreateTextureInfo
+ * @param {WebGLTexture} texture the texture.
+ * @param {module:twgl.TextureSrc} source image(s) used to as the src for the texture
+ * @memberOf module:twgl
+ */
+
+/**
+ * Creates a texture based on the options passed in.
+ *
+ * see {@link module:twgl/textures.createTexture}.
+ * The only difference is this function returns a promise
+ * where as the other returns a texture and takes a callback.
+ *
+ * Note: this is here for completeness. It is probably better to use
+ * the non-async version as it returns a usable texture immediately
+ * where as this one you have to wait for it to load.
+ *
+ * @param {WebGLRenderingContext} gl the WebGLRenderingContext
+ * @param {module:twgl.TextureOptions} [options] A TextureOptions object with whatever parameters you want set.
+ * @return {Promise<CreateTextureInfo>} The created texture and source.
+ */
 function createTextureAsync(gl, options) {
   return new Promise((resolve, reject) => {
     createTexture(gl, options, (err, texture, source) => {
@@ -1888,6 +1912,42 @@ function createTextures(gl, textureOptions, callback) {
   return textures;
 }
 
+/**
+ * Value returned by createTextureAsync
+ *
+ * @typedef {Object} CreateTexturesInfo
+ * @param {Object.<string, WebGLTexture>} textures the created textures by name. Same as returned by {@link module:twgl.createTextures}.
+ * @param {Object.<string, module:twgl.TextureSrc>} sources the image(s) used for the texture by name.
+ * @memberOf module:twgl
+ */
+
+/**
+ * Creates textures based on the options passed in.
+ *
+ * see {@link module:twgl/textures.createTextures}.
+ * The only difference is this function returns a promise
+ * where as the other returns a texture and takes a callback.
+ *
+ * Note: this is here for completeness. It is probably better to use
+ * the non-async version as it returns usable textures immediately
+ * where as this one you have to wait for them to load.
+ *
+ * @param {WebGLRenderingContext} gl the WebGLRenderingContext
+ * @param {Object.<string,module:twgl.TextureOptions>} options A object of TextureOptions one per texture.
+ * @return {Promise<CreateTexturesInfo>} The created textures and sources.
+ */
+function createTexturesAsync(gl, options) {
+  return new Promise((resolve, reject) => {
+    createTexture(gl, options, (err, textures, sources) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve({ textures, sources });
+      }
+    });
+  });
+}
+
 export {
   setDefaults as setTextureDefaults_,
 
@@ -1905,6 +1965,7 @@ export {
   setTextureParameters,
   setDefaultTextureColor,
   createTextures,
+  createTexturesAsync,
   resizeTexture,
 
   canGenerateMipmap,