webgltexture-loader-ndarray

WebGLTextureLoader libraries

gre/webgltexture-loader repository hosts webgltexture-loader libraries, utility to load & cache various kind of WebGLTexture with an extensible and loosely coupled system.

The webgltexture-loader library is a core WebGL Texture loader implementation used by frameworks like gl-react.

The gist

You usually need to build a small helper to hook things together (as things are initially uncoupled). That said, the following gist is a proof it's still viable to directly use it.

import { LoaderResolver } from "webgltexture-loader";
import "webgltexture-loader-dom"; // import support for DOM, including video, canvas or simple image url

const canvas = document.createElement("canvas"); document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");

const resolver = new LoaderResolver(gl);

function load (input) { // just an example (create your own load function based on needs)
  const loader = resolver.resolve(input);
  return loader ? loader.load(input) : Promise.reject("no loader supports the input "+input);
}

load("https://i.imgur.com/wxqlQkh.jpg") // just an example, many format supported here
.then(({ texture }) => {
  const program = createDemoProgram(gl);
  const tLocation = gl.getUniformLocation(program, "t");
  gl.activeTexture(gl.TEXTURE0);
  gl.bindTexture(gl.TEXTURE_2D, texture);
  gl.uniform1i(tLocation, 0);
  gl.drawArrays(gl.TRIANGLES, 0, 3);
});

createDemoProgram() source code

WebGLTextureLoader ?

a WebGLTextureLoader<T> is an object created with a WebGLRenderingContext that can load and cache a WebGLTexture for a given input.

type TextureAndSize = {
  texture: WebGLTexture,
  width: number,
  height: number
}

class WebGLTextureLoader<T> {
  constructor(gl: WebGLRenderingContext){}
  canLoad(input: any): boolean
  load(input: T): Promise<TextureAndSize>
  get(input: T): ?TextureAndSize
  update(input: T)
}

If loader.canLoad(input) is true, the loader can be used:

loader.get(input) returns a {texture, width, height} object if the input is loaded. Otherwise it returns null, and you need to call loader.load(input) to load the resource, which return a promise of that same object. Note that you can just stick with the load API.

When the load(input) promise is fulfilled, it is guarantee that loader.get(input) returns a result that is === to the Promise result. It is also guarantee that 2 call to the same loader.load(input) is idempotent and returns the same Promise (by ===).

Why is there both get and load API?

The dual get and load is defined to allow the best of the 2 worlds paradigms: async and sync. Typically, you can call get() in a requestAnimationFrame loop (and call load if it fails so the future frames will eventually have it resolved). But, in a more async paradigm, you can wait the load() Promise.

A second reason is that some Loader are simply sync by nature. For instance, the HTMLCanvasElement or ndarray loaders. (this is transparent when using the API).

Th idea behind get(input) is also to allow functional/"descriptive" way like an object coming from React (e.g. in React, user sent again and again the full state tree and therefore don't keep state, input might just be an new object each time, the library do the reconciliation in some way).

LoaderResolver

A LoaderResolver is a tiny utility that instantiate the loaders and exposes a resolve method that returns the first WebGLTextureLoader that canLoad a given input.

const resolver = new LoaderResolver(gl); // instantiate once
const maybeLoader = resolver.resolve(input); // use many times
// then do your logic...
// ... maybeLoader.get(input);
// ... maybeLoader.load(input);

LoaderResolver also accept a second parameter that is the LoadersRegistry to use, by default it is the "globalRegistry".

Available loaders

Loaders implementation are available via various NPM packages. The idea of each is that they both expose the loader class but they will also automatically add itself in the globalRegistry (as soon as imported in the bundle). So typically you need to import "webgltexture-loader-WHATEVER;" them all and use new LoaderResolver(gl) to use the globalRegistry.

• webgltexture-loader-dom add all DOM only loaders:
  • webgltexture-loader-dom-canvas for a HTMLCanvasElement
  • webgltexture-loader-dom-video for a HTMLVideoElement
  • webgltexture-loader-dom-image-url support for image by giving it's URL (as a string input).
• webgltexture-loader-ndarray add NDArray loader support.
• webgltexture-loader-react-native add all React Native loaders (using react-native-webgl)
  • webgltexture-loader-react-native-config add the generic Config format of react-native-webgl
  • webgltexture-loader-react-native-imagesource add support of ImageSource (same format as in React Native Image source prop).
• webgltexture-loader-expo exposes loaders for Expo (EXGLView). They might soon be replaced by webgltexture-loader-react-native if it gets migrated to react-native-webgl.