@luma.gl/webgl 9.1.0-alpha.16 → 9.1.0-alpha.17

package/src/adapter/resources/webgl-texture.ts

@@ -17,10 +17,8 @@ import type {
   Sampler,
   SamplerProps,
   SamplerParameters,
-  // TextureFormat,
   TextureCubeFace,
   ExternalImage,
-  TextureLevelData,
   Texture1DData,
   Texture2DData,
   Texture3DData,
@@ -58,42 +56,11 @@ import {
   getWebGLTextureTarget
 } from '../helpers/webgl-texture-utils';
 
-// PORTABLE HELPERS (Move to methods on Texture?)
-
-/**
- * Normalize TextureData to an array of TextureLevelData / ExternalImages
- * @param data
- * @param options
- * @returns array of TextureLevelData / ExternalImages
- */
-function normalizeTextureData(
-  data: Texture2DData,
-  options: {width: number; height: number; depth: number}
-): (TextureLevelData | ExternalImage)[] {
-  let lodArray: (TextureLevelData | ExternalImage)[];
-  if (ArrayBuffer.isView(data)) {
-    lodArray = [
-      {
-        // ts-expect-error does data really need to be Uint8ClampedArray?
-        data,
-        width: options.width,
-        height: options.height
-        // depth: options.depth
-      }
-    ];
-  } else if (!Array.isArray(data)) {
-    lodArray = [data];
-  } else {
-    lodArray = data;
-  }
-  return lodArray;
-}
-
 /**
  * WebGL... the texture API from hell... hopefully made simpler
  */
 export class WEBGLTexture extends Texture {
-  readonly MAX_ATTRIBUTES: number;
+  // readonly MAX_ATTRIBUTES: number;
   readonly device: WebGLDevice;
   readonly gl: WebGL2RenderingContext;
   handle: WebGLTexture;
@@ -101,9 +68,14 @@ export class WEBGLTexture extends Texture {
   sampler: WEBGLSampler = undefined; // TODO - currently unused in WebGL. Create dummy sampler?
   view: WEBGLTextureView = undefined; // TODO - currently unused in WebGL. Create dummy view?
 
-  mipmaps: boolean = false;
+  mipmaps: boolean;
+
+  // Texture type
+  /** Whether the internal format is compressed */
+  compressed: boolean;
 
   /**
+   * The WebGL target corresponding to the texture type
    * @note `target` cannot be modified by bind:
    * textures are special because when you first bind them to a target,
    * When you first bind a texture as a GL_TEXTURE_2D, you are saying that this texture is a 2D texture.
@@ -112,41 +84,23 @@ export class WEBGLTexture extends Texture {
    * attempting to bind it as GL_TEXTURE_3D will give rise to a run-time error
    */
   glTarget: GLTextureTarget;
-
-  // Texture type
-
   /** The WebGL format - essentially channel structure */
   glFormat: GLTexelDataFormat;
   /** The WebGL data format - the type of each channel */
   glType: GLPixelType;
   /** The WebGL constant corresponding to the WebGPU style constant in format */
   glInternalFormat: GL;
-  /** Whether the internal format is compressed */
-  compressed: boolean;
-
-  // data;
-  // inherited props
-  // dimension: ...
-  // format: GLTextureTarget;
-  // width: number = undefined;
-  // height: number = undefined;
-  // depth: number = undefined;
 
   // state
-  /** Texture binding slot */
+  /** Texture binding slot - TODO - move to texture view? */
   textureUnit: number = 0;
-  /** For automatically updating video */
-  _video: {
-    video: HTMLVideoElement;
-    parameters: any;
-    lastTime: number;
-  } | null = null;
 
   constructor(device: Device, props: TextureProps) {
-    props = Texture._fixProps(props);
+    super(device, props);
 
-    // Note: Clear out `props.data` so that we don't hold a reference to any big memory chunks
-    super(device, {...Texture.defaultProps, ...props, data: undefined!});
+    // Texture base class strips out the data prop, so we need to add it back in
+    const propsWithData = {...this.props};
+    propsWithData.data = props.data;
 
     this.device = device as WebGLDevice;
     this.gl = this.device.gl;
@@ -155,26 +109,14 @@ export class WEBGLTexture extends Texture {
     this.glTarget = getWebGLTextureTarget(this.props.dimension);
 
     // The target format of this texture
-    const format = getTextureFormatWebGL(this.props.format);
-    this.glInternalFormat = format.internalFormat;
-    this.glFormat = format.format;
-    this.glType = format.type;
-    this.compressed = format.compressed;
+    const formatInfo = getTextureFormatWebGL(this.props.format);
+    this.glInternalFormat = formatInfo.internalFormat;
+    this.glFormat = formatInfo.format;
+    this.glType = formatInfo.type;
+    this.compressed = formatInfo.compressed;
+    this.mipmaps = Boolean(this.props.mipmaps);
 
-    if (
-      typeof HTMLVideoElement !== 'undefined' &&
-      props.data instanceof HTMLVideoElement &&
-      // @ts-expect-error
-      props.data.readyState < HTMLVideoElement.HAVE_METADATA
-    ) {
-      const video = props.data;
-      this._video = null; // Declare member before the object is sealed
-      video.addEventListener('loadeddata', () => this.initialize(props));
-    }
-
-    // We removed data, we need to add it again.
-    // @ts-expect-error
-    this.initialize({...this.props, data: props.data});
+    this._initialize(propsWithData);
 
     Object.seal(this);
   }
@@ -183,18 +125,14 @@ export class WEBGLTexture extends Texture {
    * Initialize texture with supplied props
    */
   // eslint-disable-next-line max-statements
-  initialize(props: TextureProps = {}): void {
+  _initialize(propsWithData: TextureProps): void {
     this.handle = this.props.handle || this.gl.createTexture();
-    this.device.setSpectorMetadata(this.handle, {...this.props, data: typeof this.props.data});
-
-    const data = props.data;
+    this.device.setSpectorMetadata(this.handle, {...this.props, data: propsWithData.data});
 
-    // const {parameters = {}  as Record<GL, any>} = props;
-
-    let {width, height} = props;
+    let {width, height} = propsWithData;
 
     if (!width || !height) {
-      const textureSize = Texture.getTextureDataSize(data);
+      const textureSize = Texture.getTextureDataSize(propsWithData.data);
       width = textureSize?.width || 1;
       height = textureSize?.height || 1;
     }
@@ -202,73 +140,35 @@ export class WEBGLTexture extends Texture {
     // Store opts for accessors
     this.width = width;
     this.height = height;
-    this.depth = props.depth;
+    this.depth = propsWithData.depth;
 
     // Set texture sampler parameters
-    this.setSampler(props.sampler);
-    // @ts-ignore
+    this.setSampler(propsWithData.sampler);
+    // @ts-ignore TODO - fix types
     this.view = new WEBGLTextureView(this.device, {...this.props, texture: this});
 
     this.bind();
-    if (!this.props.data) {
-      initializeTextureStorage(this.gl, this.mipLevels, this);
-    }
+    initializeTextureStorage(this.gl, this.mipLevels, this);
 
-    if (props.data) {
+    if (propsWithData.data) {
       // prettier-ignore
-      switch (props.dimension) {
-        case '1d': this.setTexture1DData(props.data); break;
-        case '2d': this.setTexture2DData(props.data); break;
-        case '3d': this.setTexture3DData(props.data); break;
-        case 'cube': this.setTextureCubeData(props.data); break;
-        case '2d-array': this.setTextureArrayData(props.data); break;
-        case 'cube-array': this.setTextureCubeArrayData(props.data); break;
+      switch (propsWithData.dimension) {
+        case '1d': this.setTexture1DData(propsWithData.data); break;
+        case '2d': this.setTexture2DData(propsWithData.data); break;
+        case '3d': this.setTexture3DData(propsWithData.data); break;
+        case 'cube': this.setTextureCubeData(propsWithData.data); break;
+        case '2d-array': this.setTextureArrayData(propsWithData.data); break;
+        case 'cube-array': this.setTextureCubeArrayData(propsWithData.data); break;
         // @ts-expect-error
-        default: throw new Error(props.dimension);
+        default: throw new Error(propsWithData.dimension);
       }
     }
 
-    this.mipmaps = Boolean(props.mipmaps);
-
     if (this.mipmaps) {
       this.generateMipmap();
     }
-
-    // if (isVideo) {
-    //   this._video = {
-    //     video: data,
-    //     // TODO  - should we be using the sampler parameters here?
-    //     parameters: {},
-    //     // @ts-expect-error HTMLVideoElement.HAVE_CURRENT_DATA is not declared
-    //     lastTime: data.readyState >= HTMLVideoElement.HAVE_CURRENT_DATA ? data.currentTime : -1
-    //   };
-    // }
   }
 
-  /*
-  initializeCube(props?: TextureProps): void {
-    const {mipmaps = true} = props; // , parameters = {} as Record<GL, any>} = props;
-
-    // Store props for accessors
-    // this.props = props;
-
-    // @ts-expect-error
-    this.setCubeMapData(props).then(() => {
-      // TODO - should genMipmap() be called on the cubemap or on the faces?
-      // TODO - without generateMipmap() cube textures do not work at all!!! Why?
-      if (mipmaps) {
-        this.generateMipmap(props);
-      }
-
-      this.setSampler(props.sampler);
-
-      // v8 compatibility?
-      // const {parameters = {} as Record<GL, any>} = props;
-      // this._setSamplerParameters(parameters);
-    });
-  }
-  */
-
   override destroy(): void {
     if (this.handle) {
       this.gl.deleteTexture(this.handle);
@@ -279,10 +179,6 @@ export class WEBGLTexture extends Texture {
     }
   }
 
-  override toString(): string {
-    return `Texture(${this.id},${this.width}x${this.height})`;
-  }
-
   createView(props: TextureViewProps): WEBGLTextureView {
     return new WEBGLTextureView(this.device, {...props, texture: this});
   }
@@ -301,37 +197,25 @@ export class WEBGLTexture extends Texture {
     this._setSamplerParameters(parameters);
   }
 
-  /** Update external texture (video frame or canvas) */
-  update(): void {
-    log.warn('Texture.update() not implemented');
-    // if (this._video) {
-    //   const {video, parameters, lastTime} = this._video;
-    //   // @ts-expect-error
-    //   if (lastTime === video.currentTime || video.readyState < HTMLVideoElement.HAVE_CURRENT_DATA) {
-    //     return;
-    //   }
-    //   this.setSubImageData({
-    //     data: video,
-    //     parameters
-    //   });
-    //   if (this.mipmaps) {
-    //     this.generateMipmap();
-    //   }
-    //   this._video.lastTime = video.currentTime;
-    // }
-  }
-
   // Call to regenerate mipmaps after modifying texture(s)
   generateMipmap(params = {}): void {
-    if (!this.props.data) {
-      return;
+    if (
+      !this.device.isTextureFormatRenderable(this.props.format) ||
+      !this.device.isTextureFormatFilterable(this.props.format)
+    ) {
+      log.warn(`${this} is not renderable or filterable, may not be able to generate mipmaps`)();
+    }
+
+    try {
+      this.gl.bindTexture(this.glTarget, this.handle);
+      withGLParameters(this.gl, params, () => {
+        this.gl.generateMipmap(this.glTarget);
+      });
+    } catch (error) {
+      log.warn(`Error generating mipmap for ${this}: ${(error as Error).message}`)();
+    } finally {
+      this.gl.bindTexture(this.glTarget, null);
     }
-    this.mipmaps = true;
-    this.gl.bindTexture(this.glTarget, this.handle);
-    withGLParameters(this.gl, params, () => {
-      this.gl.generateMipmap(this.glTarget);
-    });
-    this.gl.bindTexture(this.glTarget, null);
   }
 
   // Image Data Setters
@@ -349,11 +233,12 @@ export class WEBGLTexture extends Texture {
     aspect?: 'all' | 'stencil-only' | 'depth-only';
     colorSpace?: 'srgb';
     premultipliedAlpha?: boolean;
+    flipY?: boolean;
   }): {width: number; height: number} {
     const size = Texture.getExternalImageSize(options.image);
     const opts = {...Texture.defaultCopyExternalImageOptions, ...size, ...options};
 
-    const {image, depth, mipLevel, x, y, z} = opts;
+    const {image, depth, mipLevel, x, y, z, flipY} = opts;
     let {width, height} = opts;
     const {dimension, glTarget, glFormat, glInternalFormat, glType} = this;
 
@@ -361,12 +246,9 @@ export class WEBGLTexture extends Texture {
     width = Math.min(width, size.width - x);
     height = Math.min(height, size.height - y);
 
-    // WebGL does not yet support sourceX/sourceY in copyExternalImage; requires copyTexSubImage2D from a framebuffer'
-
     if (options.sourceX || options.sourceY) {
-      throw new Error(
-        'WebGL does not yet support sourceX/sourceY in copyExternalImage; requires copyTexSubImage2D from a framebuffer'
-      );
+      // requires copyTexSubImage2D from a framebuffer'
+      throw new Error('WebGL does not support sourceX/sourceY)');
     }
 
     copyExternalImageToMipLevel(this.device.gl, this.handle, image, {
@@ -381,7 +263,8 @@ export class WEBGLTexture extends Texture {
       glFormat,
       glInternalFormat,
       glType,
-      glTarget
+      glTarget,
+      flipY
     });
 
     return {width: opts.width, height: opts.height};
@@ -395,7 +278,7 @@ export class WEBGLTexture extends Texture {
   setTexture2DData(lodData: Texture2DData, depth = 0): void {
     this.bind();
 
-    const lodArray = normalizeTextureData(lodData, this);
+    const lodArray = Texture.normalizeTextureData(lodData, this);
 
     // If the user provides multiple LODs, then automatic mipmap
     // generation generateMipmap() should be disabled to avoid overwriting them.
@@ -474,6 +357,13 @@ export class WEBGLTexture extends Texture {
     this.setTexture2DData(lodData, faceDepth);
   }
 
+  // DEPRECATED METHODS
+
+  /** Update external texture (video frame or canvas) @deprecated Use ExternalTexture */
+  update(): void {
+    throw new Error('Texture.update() not implemented. Use ExternalTexture');
+  }
+
   // INTERNAL METHODS
 
   /** @todo update this method to accept LODs */
@@ -528,7 +418,7 @@ export class WEBGLTexture extends Texture {
    * Sets sampler parameters on texture
    */
   _setSamplerParameters(parameters: GLSamplerParameters): void {
-    log.log(1, 'texture sampler parameters', parameters)();
+    log.log(1, `${this.id} sampler parameters`, this.device.getGLKeys(parameters))();
 
     this.gl.bindTexture(this.glTarget, this.handle);
     for (const [pname, pvalue] of Object.entries(parameters)) {
@@ -566,63 +456,6 @@ export class WEBGLTexture extends Texture {
     this.gl.bindTexture(this.glTarget, null);
   }
 
-  // CLASSIC
-
-  /*
-  setCubeMapData(options: {
-    width: number;
-    height: number;
-    data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
-    format?: any;
-    type?: any;
-    /** @deprecated Use .data *
-    pixels: any;
-  }): void {
-    const {gl} = this;
-
-    const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
-
-    // pixel data (imageDataMap) is an Object from Face to Image or Promise.
-    // For example:
-    // {
-    // GL.TEXTURE_CUBE_MAP_POSITIVE_X : Image-or-Promise,
-    // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : Image-or-Promise,
-    // ... }
-    // To provide multiple level-of-details (LODs) this can be Face to Array
-    // of Image or Promise, like this
-    // {
-    // GL.TEXTURE_CUBE_MAP_POSITIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
-    // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
-    // ... }
-
-    const imageDataMap = this._getImageDataMap(pixels || data);
-
-    const resolvedFaces = WEBGLTexture.FACES.map(face => {
-      const facePixels = imageDataMap[face];
-      return Array.isArray(facePixels) ? facePixels : [facePixels];
-    });
-    this.bind();
-
-    WEBGLTexture.FACES.forEach((face, index) => {
-      if (resolvedFaces[index].length > 1 && this.props.mipmaps !== false) {
-        // If the user provides multiple LODs, then automatic mipmap
-        // generation generateMipmap() should be disabled to avoid overwritting them.
-        log.warn(`${this.id} has mipmap and multiple LODs.`)();
-      }
-      resolvedFaces[index].forEach((image, lodLevel) => {
-        // TODO: adjust width & height for LOD!
-        if (width && height) {
-          gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
-        } else {
-          gl.texImage2D(face, lodLevel, format, format, type, image);
-        }
-      });
-    });
-
-    this.unbind();
-  }
-  */
-
   // INTERNAL SETTERS
 
   /**
@@ -645,7 +478,8 @@ export class WEBGLTexture extends Texture {
         ...this,
         depth,
         mipLevel,
-        glTarget
+        glTarget,
+        flipY: this.props.flipY
       });
       return;
     }
@@ -693,3 +527,60 @@ export class WEBGLTexture extends Texture {
     return textureUnit;
   }
 }
+
+// TODO - Remove when texture refactor is complete
+
+/*
+setCubeMapData(options: {
+  width: number;
+  height: number;
+  data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
+  format?: any;
+  type?: any;
+  /** @deprecated Use .data *
+  pixels: any;
+}): void {
+  const {gl} = this;
+
+  const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
+
+  // pixel data (imageDataMap) is an Object from Face to Image or Promise.
+  // For example:
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : Image-or-Promise,
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : Image-or-Promise,
+  // ... }
+  // To provide multiple level-of-details (LODs) this can be Face to Array
+  // of Image or Promise, like this
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // ... }
+
+  const imageDataMap = this._getImageDataMap(pixels || data);
+
+  const resolvedFaces = WEBGLTexture.FACES.map(face => {
+    const facePixels = imageDataMap[face];
+    return Array.isArray(facePixels) ? facePixels : [facePixels];
+  });
+  this.bind();
+
+  WEBGLTexture.FACES.forEach((face, index) => {
+    if (resolvedFaces[index].length > 1 && this.props.mipmaps !== false) {
+      // If the user provides multiple LODs, then automatic mipmap
+      // generation generateMipmap() should be disabled to avoid overwritting them.
+      log.warn(`${this.id} has mipmap and multiple LODs.`)();
+    }
+    resolvedFaces[index].forEach((image, lodLevel) => {
+      // TODO: adjust width & height for LOD!
+      if (width && height) {
+        gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
+      } else {
+        gl.texImage2D(face, lodLevel, format, format, type, image);
+      }
+    });
+  });
+
+  this.unbind();
+}
+*/

package/src/adapter/webgl-adapter.ts

@@ -61,7 +61,7 @@ export class WebGLAdapter extends Adapter {
     const promises: Promise<unknown>[] = [];
 
     // Load webgl and spector debug scripts from CDN if requested
-    if (props.debugWebGL) {
+    if (props.debugWebGL || props.debug) {
       promises.push(loadWebGLDeveloperTools());
     }
 

package/src/adapter/webgl-device.ts

@@ -202,11 +202,14 @@ export class WebGLDevice extends Device {
     glState.trackState(this.gl, {copyState: false});
 
     // DEBUG contexts: Add luma debug instrumentation to the context, force log level to at least 1
-    if (props.debugWebGL) {
-      this.gl = makeDebugContext(this.gl, {...props});
-      this.debug = true;
-      log.level = Math.max(log.level, 1);
+    const debugWebGL = props.debugWebGL || props.debug;
+    const traceWebGL = props.debugWebGL;
+    if (debugWebGL) {
+      this.gl = makeDebugContext(this.gl, {debugWebGL, traceWebGL});
       log.warn('WebGL debug mode activated. Performance reduced.')();
+      if (props.debugWebGL) {
+        log.level = Math.max(log.level, 1);
+      }
     }
   }
 
@@ -425,18 +428,28 @@ export class WebGLDevice extends Device {
    * Be aware that there are some duplicates especially for constants that are 0,
    * so this isn't guaranteed to return the right key in all cases.
    */
-  getGLKey(value: unknown, gl?: WebGL2RenderingContext): string {
-    // @ts-ignore expect-error depends on settings
-    gl = gl || this.gl2 || this.gl;
+  getGLKey(value: unknown, options?: {emptyIfUnknown?: boolean}): string {
     const number = Number(value);
-    for (const key in gl) {
+    for (const key in this.gl) {
       // @ts-ignore expect-error depends on settings
-      if (gl[key] === number) {
+      if (this.gl[key] === number) {
         return `GL.${key}`;
       }
     }
     // No constant found. Stringify the value and return it.
-    return String(value);
+    return options?.emptyIfUnknown ? '' : String(value);
+  }
+
+  /**
+   * Returns a map with any GL.<KEY> constants mapped to strings, both for keys and values
+   */
+  getGLKeys(glParameters: Record<number, unknown>): Record<string, string> {
+    const opts = {emptyIfUnknown: true};
+    return Object.entries(glParameters).reduce<Record<string, string>>((keys, [key, value]) => {
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      keys[`${key}:${this.getGLKey(key, opts)}`] = `${value}:${this.getGLKey(value, opts)}`;
+      return keys;
+    }, {});
   }
 
   /** Store constants */

package/src/context/debug/webgl-developer-tools.ts

@@ -12,6 +12,7 @@ const WEBGL_DEBUG_CDN_URL = 'https://unpkg.com/webgl-debug@2.0.1/index.js';
 
 type DebugContextProps = {
   debugWebGL?: boolean;
+  traceWebGL?: boolean;
 };
 
 type ContextData = {
@@ -51,7 +52,7 @@ export function makeDebugContext(
   gl: WebGL2RenderingContext,
   props: DebugContextProps = {}
 ): WebGL2RenderingContext {
-  return props.debugWebGL ? getDebugContext(gl, props) : getRealContext(gl);
+  return props.debugWebGL || props.traceWebGL ? getDebugContext(gl, props) : getRealContext(gl);
 }
 
 // Returns the real context from either of the real/debug contexts
@@ -139,7 +140,9 @@ function onValidateGLFunc(
   let functionString: string = '';
   if (log.level >= 1) {
     functionString = getFunctionString(functionName, functionArgs);
-    log.log(1, functionString)();
+    if (props.traceWebGL) {
+      log.log(1, functionString)();
+    }
   }
 
   for (const arg of functionArgs) {

package/src/context/helpers/create-browser-context.ts

@@ -25,7 +25,7 @@ export function createBrowserContext(
   webglContextAttributes: WebGLContextAttributes
 ): WebGL2RenderingContext {
   // Try to extract any extra information about why context creation failed
-  const errorMessage = null;
+  let errorMessage = '';
   // const onCreateError = error => (errorMessage = error.statusMessage || errorMessage);
 
   // Avoid multiple listeners?
@@ -43,11 +43,15 @@ export function createBrowserContext(
 
   // Create a webgl2 context
   gl ||= canvas.getContext('webgl2', webglProps);
+  if (webglProps.failIfMajorPerformanceCaveat) {
+    errorMessage ||=
+      'Only software GPU is available. Set `failIfMajorPerformanceCaveat: false` to allow.';
+  }
 
   // Creation failed with failIfMajorPerformanceCaveat - Try a Software GPU
   if (!gl && !webglContextAttributes.failIfMajorPerformanceCaveat) {
     webglProps.failIfMajorPerformanceCaveat = false;
-    gl = canvas.getContext('webgl', webglProps) as WebGL2RenderingContext;
+    gl = canvas.getContext('webgl2', webglProps);
     // @ts-expect-error
     gl.luma ||= {};
     // @ts-expect-error
@@ -55,7 +59,16 @@ export function createBrowserContext(
   }
 
   if (!gl) {
-    throw new Error(`Failed to create WebGL context: ${errorMessage || 'Unknown error'}`);
+    gl = canvas.getContext('webgl', {}) as WebGL2RenderingContext;
+    if (gl) {
+      gl = null;
+      errorMessage ||= 'Your browser only supports WebGL1';
+    }
+  }
+
+  if (!gl) {
+    errorMessage ||= 'Your browser does not support WebGL';
+    throw new Error(`Failed to create WebGL context: ${errorMessage}`);
   }
 
   // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
@@ -67,6 +80,8 @@ export function createBrowserContext(
     false
   );
 
+  // @ts-expect-error
+  gl.luma ||= {};
   return gl;
 }