Skip to content

Commit

Permalink
Add createTextureAsync and createTexturesAsync
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
greggman committed Sep 8, 2024
1 parent 364ddd6 commit 106b7cf
Showing 1 changed file with 61 additions and 0 deletions.
61 changes: 61 additions & 0 deletions src/textures.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down Expand Up @@ -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_,

Expand All @@ -1905,6 +1965,7 @@ export {
setTextureParameters,
setDefaultTextureColor,
createTextures,
createTexturesAsync,
resizeTexture,

canGenerateMipmap,
Expand Down

0 comments on commit 106b7cf

Please sign in to comment.