@swf2es/context3d 0.0.0-stage → 0.1.1

package/src/webgl/index.ts

@@ -0,0 +1,2 @@
+export { WebGLContext3D } from "./context.js";
+export type { WebGLContext3DLimits } from "./limits.js";

package/src/webgl/limits.ts

@@ -0,0 +1,61 @@
+/** Per-context resource budgets; byte counts cover buffer storage, texture mip
+ * chains and texture-target attachments, not physical driver VRAM. */
+export interface WebGLContext3DLimits {
+  maxBuffers: number;
+  maxVertexBuffers: number;
+  maxIndexBuffers: number;
+  maxPrograms: number;
+  maxTextures: number;
+  max2DTextures: number;
+  maxRectangleTextures: number;
+  maxCubeTextures: number;
+  maxBufferBytes: number;
+  maxVertexBufferBytes: number;
+  maxIndexBufferBytes: number;
+  maxTextureBytes: number;
+  max2DTextureBytes: number;
+  maxRectangleTextureBytes: number;
+  maxCubeTextureBytes: number;
+  maxTargetDepthBytes: number;
+  maxTargetColorBytes: number;
+}
+
+const DEFAULT_LIMITS: WebGLContext3DLimits = {
+  maxBuffers: 8192,
+  maxVertexBuffers: 4096,
+  maxIndexBuffers: 4096,
+  maxPrograms: 4096,
+  maxTextures: 12288,
+  max2DTextures: 4096,
+  maxRectangleTextures: 4096,
+  maxCubeTextures: 4096,
+  maxBufferBytes: 384 * 1024 * 1024,
+  maxVertexBufferBytes: 256 * 1024 * 1024,
+  maxIndexBufferBytes: 128 * 1024 * 1024,
+  maxTextureBytes: 1280 * 1024 * 1024,
+  max2DTextureBytes: 512 * 1024 * 1024,
+  maxRectangleTextureBytes: 512 * 1024 * 1024,
+  maxCubeTextureBytes: 256 * 1024 * 1024,
+  maxTargetDepthBytes: 64 * 1024 * 1024,
+  maxTargetColorBytes: 64 * 1024 * 1024,
+};
+const LIMIT_NAMES = Object.keys(DEFAULT_LIMITS) as (keyof WebGLContext3DLimits)[];
+
+export function resourceLimits(
+  overrides: Partial<WebGLContext3DLimits>,
+): Readonly<WebGLContext3DLimits> {
+  const limits = { ...DEFAULT_LIMITS };
+  for (let i = 0; i < LIMIT_NAMES.length; i++) {
+    const name = LIMIT_NAMES[i];
+    const value = overrides[name];
+    if (value !== undefined) {
+      if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`Context3D resource limit ${name} must be a nonnegative safe integer`);
+      }
+
+      limits[name] = value;
+    }
+  }
+
+  return Object.freeze(limits);
+}

package/src/webgl/programs.ts

@@ -0,0 +1,145 @@
+import { type SamplerSource, translate } from "../agal.js";
+import { linkProgram as link, ShaderError } from "../device/programs.js";
+import { Context3DError } from "../errors.js";
+
+export interface ProgramState {
+  handle: WebGLProgram | null;
+  targetY: WebGLUniformLocation | null;
+  attributes: number[];
+  vertex: (WebGLUniformLocation | null)[];
+  vertexBank: WebGLUniformLocation | null;
+  fragment: (WebGLUniformLocation | null)[];
+  samplers: { source: SamplerSource; location: WebGLUniformLocation | null }[];
+  samplerMask: number;
+}
+
+export interface CopyProgram {
+  handle: WebGLProgram;
+  size: WebGLUniformLocation | null;
+  face: WebGLUniformLocation | null;
+}
+
+export function uploadProgram(
+  gl: WebGL2RenderingContext,
+  state: ProgramState,
+  vertex: Uint8Array,
+  fragment: Uint8Array,
+): void {
+  // Translate both before allocating anything on the GPU.
+  const vs = translate(vertex, "vertex");
+  const fs = translate(fragment, "fragment");
+  for (let i = 0; i < 8; i++) {
+    if (fs.varyings[i] & ~vs.varyings[i]) {
+      throw new Context3DError(
+        "agalVaryingMissing",
+        "Fragment program reads an unwritten varying component",
+      );
+    }
+  }
+  for (let i = 0; i < 8; i++) {
+    if (vs.varyings[i] && vs.varyings[i] !== 15) {
+      throw new Context3DError(
+        "agalVaryingPartial",
+        "Vertex program only partially writes a varying",
+      );
+    }
+  }
+
+  const handle = linkProgram(gl, vs.source, fs.source);
+  if (state.handle && gl.getParameter(gl.CURRENT_PROGRAM) === state.handle) {
+    gl.useProgram(null);
+  }
+
+  gl.deleteProgram(state.handle);
+  state.handle = handle;
+  state.targetY = gl.getUniformLocation(handle, "targetY");
+  state.attributes = vs.attributes;
+  state.vertex = [];
+  state.vertexBank = vs.indirect ? gl.getUniformLocation(handle, "vc[0]") : null;
+  state.fragment = [];
+  state.samplers = [];
+  state.samplerMask = 0;
+  for (let i = 0; i < vs.constants.length; i++) {
+    const index = vs.constants[i];
+    state.vertex[index] = gl.getUniformLocation(handle, `vc${index}`);
+  }
+
+  for (let i = 0; i < fs.constants.length; i++) {
+    const index = fs.constants[i];
+    state.fragment[index] = gl.getUniformLocation(handle, `fc${index}`);
+  }
+
+  for (let i = 0; i < fs.samplers.length; i++) {
+    const source = fs.samplers[i];
+    state.samplerMask |= 1 << source.index;
+    state.samplers.push({
+      source,
+      location: gl.getUniformLocation(handle, `fs${source.index}`),
+    });
+  }
+}
+
+/** A program linked as the device links one, its failures Context3D's errors as before. */
+function linkProgram(gl: WebGL2RenderingContext, vertex: string, fragment: string): WebGLProgram {
+  try {
+    return link(gl, vertex, fragment);
+  } catch (e) {
+    if (!(e instanceof ShaderError)) {
+      throw e;
+    }
+
+    switch (e.stage) {
+      case "allocate":
+        throw new Context3DError("operation", "Context3D experiment: cannot allocate shader");
+      case "compile":
+        throw new Context3DError("nativeShader", `Context3D shader: ${e.log}`);
+      default:
+        throw new Context3DError("nativeShader", `Context3D link: ${e.log}`);
+    }
+  }
+}
+
+export function createCopyProgram(gl: WebGL2RenderingContext, cube: boolean): CopyProgram {
+  const vertex = `#version 300 es
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}`;
+  const fragment = cube
+    ? `#version 300 es
+precision highp float;
+uniform samplerCube uSource;
+uniform vec2 uSize;
+uniform int uFace;
+out vec4 color;
+void main() {
+  vec2 p = gl_FragCoord.xy * 2.0 / uSize - 1.0;
+  vec3 direction;
+  switch (uFace) {
+    case 0: direction = vec3(1.0, -p.y, -p.x); break;
+    case 1: direction = vec3(-1.0, -p.y, p.x); break;
+    case 2: direction = vec3(p.x, 1.0, p.y); break;
+    case 3: direction = vec3(p.x, -1.0, -p.y); break;
+    case 4: direction = vec3(p.x, -p.y, 1.0); break;
+    default: direction = vec3(-p.x, -p.y, -1.0); break;
+  }
+  color = textureLod(uSource, direction, 0.0);
+}`
+    : `#version 300 es
+precision highp float;
+uniform sampler2D uSource;
+out vec4 color;
+void main() {
+  color = texelFetch(uSource, ivec2(gl_FragCoord.xy), 0);
+}`;
+  const handle = linkProgram(gl, vertex, fragment);
+  const program = {
+    handle,
+    size: gl.getUniformLocation(handle, "uSize"),
+    face: gl.getUniformLocation(handle, "uFace"),
+  };
+  gl.useProgram(handle);
+  gl.uniform1i(gl.getUniformLocation(handle, "uSource"), 0);
+
+  return program;
+}

package/src/webgl/state.ts

@@ -0,0 +1,65 @@
+import type { CompareMode, StencilAction } from "../backend.js";
+import { Context3DError } from "../errors.js";
+
+export const DEPTH_FUNCTIONS = {
+  always: "ALWAYS",
+  never: "NEVER",
+  less: "LESS",
+  lessEqual: "LEQUAL",
+  equal: "EQUAL",
+  notEqual: "NOTEQUAL",
+  greaterEqual: "GEQUAL",
+  greater: "GREATER",
+} as const;
+
+export const BLEND_FUNCTIONS = {
+  zero: "ZERO",
+  one: "ONE",
+  sourceColor: "SRC_COLOR",
+  oneMinusSourceColor: "ONE_MINUS_SRC_COLOR",
+  sourceAlpha: "SRC_ALPHA",
+  oneMinusSourceAlpha: "ONE_MINUS_SRC_ALPHA",
+  destinationColor: "DST_COLOR",
+  oneMinusDestinationColor: "ONE_MINUS_DST_COLOR",
+  destinationAlpha: "DST_ALPHA",
+  oneMinusDestinationAlpha: "ONE_MINUS_DST_ALPHA",
+} as const;
+
+export const STENCIL_FUNCTIONS = {
+  keep: "KEEP",
+  zero: "ZERO",
+  set: "REPLACE",
+  incrementSaturate: "INCR",
+  decrementSaturate: "DECR",
+  invert: "INVERT",
+  incrementWrap: "INCR_WRAP",
+  decrementWrap: "DECR_WRAP",
+} as const;
+
+export class StencilState {
+  compare: CompareMode = "always";
+  pass: StencilAction = "keep";
+  depthFail: StencilAction = "keep";
+  stencilFail: StencilAction = "keep";
+
+  get active(): boolean {
+    return (
+      this.compare !== "always" ||
+      this.pass !== "keep" ||
+      this.depthFail !== "keep" ||
+      this.stencilFail !== "keep"
+    );
+  }
+}
+
+export function range(start: number, count: number, length: number): void {
+  if (
+    !Number.isInteger(start) ||
+    !Number.isInteger(count) ||
+    start < 0 ||
+    count < 0 ||
+    start > length - count
+  ) {
+    throw new Context3DError("range", "Context3D experiment: range outside resource");
+  }
+}

package/src/webgl/targets.ts

@@ -0,0 +1,229 @@
+import type { Texture3D } from "../backend.js";
+import { Context3DError } from "../errors.js";
+import type { TextureState } from "./textures.js";
+
+export interface MultisampleTarget {
+  framebuffer: WebGLFramebuffer;
+  color: WebGLRenderbuffer;
+  depth: WebGLRenderbuffer | null;
+  samples: number;
+  resolve: WebGLFramebuffer | null;
+  texture: WebGLTexture | null;
+  valid: boolean;
+  dirty: boolean;
+  face: number;
+  depthAttached: boolean;
+}
+
+export function selectSamples(gl: WebGL2RenderingContext, quality: number, depth: boolean): number {
+  if (!Number.isInteger(quality)) {
+    throw new Context3DError("operation", "Context3D experiment: invalid antialiasing quality");
+  }
+  if (quality < 2) {
+    return 0;
+  }
+
+  const color: Int32Array = gl.getInternalformatParameter(gl.RENDERBUFFER, gl.RGBA8, gl.SAMPLES);
+  const stencil: Int32Array | null = depth
+    ? gl.getInternalformatParameter(gl.RENDERBUFFER, gl.DEPTH24_STENCIL8, gl.SAMPLES)
+    : null;
+  let samples = 0;
+  // Quality is a hardware-dependent request; bound this experiment to 4x.
+  for (let i = 0; i < color.length; i++) {
+    const count = color[i];
+    if (count > samples && count <= Math.min(quality, 4) && (!stencil || stencil.includes(count))) {
+      samples = count;
+    }
+  }
+
+  return samples;
+}
+
+export function targetFramebuffer(state: TextureState): WebGLFramebuffer | null {
+  return state.samples ? (state.multisample?.framebuffer ?? null) : state.framebuffer;
+}
+
+export function resolveTarget(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  state: TextureState,
+  face: number,
+  scissor: boolean,
+): void {
+  const target = state.multisample;
+  if (!state.samples || !target?.dirty) {
+    return;
+  }
+
+  gl.bindFramebuffer(gl.READ_FRAMEBUFFER, target.framebuffer);
+  gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, target.resolve ?? state.framebuffer);
+  if (scissor) {
+    gl.disable(gl.SCISSOR_TEST);
+  }
+  gl.blitFramebuffer(
+    0,
+    0,
+    texture.width,
+    texture.height,
+    0,
+    0,
+    texture.width,
+    texture.height,
+    gl.COLOR_BUFFER_BIT,
+    gl.NEAREST,
+  );
+  if (target.resolve) {
+    // SwiftShader corrupts direct multisample blits into cube faces.
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, target.resolve);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_CUBE_MAP, state.handle);
+    gl.copyTexSubImage2D(
+      gl.TEXTURE_CUBE_MAP_POSITIVE_X + face,
+      0,
+      0,
+      0,
+      0,
+      0,
+      texture.width,
+      texture.height,
+    );
+  }
+  target.dirty = false;
+}
+
+export function deleteMultisample(gl: WebGL2RenderingContext, target: MultisampleTarget): void {
+  gl.deleteFramebuffer(target.framebuffer);
+  gl.deleteRenderbuffer(target.color);
+  gl.deleteRenderbuffer(target.depth);
+  gl.deleteFramebuffer(target.resolve);
+  gl.deleteTexture(target.texture);
+}
+
+export function allocateMultisample(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  old: MultisampleTarget | null,
+  samples: number,
+  depth: boolean,
+  depthWrite: boolean,
+  stencilWrite: number,
+): MultisampleTarget {
+  const same = old?.samples === samples;
+  const newDepth = depth && (!same || !old.depth);
+  const framebuffer = same ? old.framebuffer : gl.createFramebuffer();
+  const color = same ? old.color : gl.createRenderbuffer();
+  const depthBuffer = newDepth ? gl.createRenderbuffer() : same ? old.depth : null;
+  const resolve = same ? old.resolve : texture.cube ? gl.createFramebuffer() : null;
+  const resolved = same ? old.texture : texture.cube ? gl.createTexture() : null;
+  try {
+    if (texture.cube && (!resolve || !resolved)) {
+      throw new Context3DError(
+        "operation",
+        "Context3D experiment: cannot allocate cube resolve target",
+      );
+    }
+    if (texture.cube && !same) {
+      gl.activeTexture(gl.TEXTURE0);
+      gl.bindTexture(gl.TEXTURE_2D, resolved);
+      gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA8, texture.width, texture.height);
+      gl.bindFramebuffer(gl.FRAMEBUFFER, resolve);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, resolved, 0);
+      if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+        throw new Context3DError(
+          "operation",
+          "Context3D experiment: incomplete cube resolve target",
+        );
+      }
+    }
+    if (!framebuffer || !color || (newDepth && !depthBuffer)) {
+      throw new Context3DError(
+        "operation",
+        "Context3D experiment: cannot allocate multisample target",
+      );
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    if (!same) {
+      gl.bindRenderbuffer(gl.RENDERBUFFER, color);
+      gl.renderbufferStorageMultisample(
+        gl.RENDERBUFFER,
+        samples,
+        gl.RGBA8,
+        texture.width,
+        texture.height,
+      );
+      gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.RENDERBUFFER, color);
+    }
+    if (newDepth) {
+      gl.bindRenderbuffer(gl.RENDERBUFFER, depthBuffer);
+      gl.renderbufferStorageMultisample(
+        gl.RENDERBUFFER,
+        samples,
+        gl.DEPTH24_STENCIL8,
+        texture.width,
+        texture.height,
+      );
+    }
+    gl.framebufferRenderbuffer(
+      gl.FRAMEBUFFER,
+      gl.DEPTH_STENCIL_ATTACHMENT,
+      gl.RENDERBUFFER,
+      depth ? depthBuffer : null,
+    );
+    if (
+      (!same || newDepth) &&
+      gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE
+    ) {
+      throw new Context3DError("operation", "Context3D experiment: incomplete multisample target");
+    }
+  } catch (error) {
+    if (!same) {
+      gl.deleteFramebuffer(framebuffer);
+      gl.deleteRenderbuffer(color);
+      gl.deleteFramebuffer(resolve);
+      gl.deleteTexture(resolved);
+    } else {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, old.framebuffer);
+      gl.framebufferRenderbuffer(
+        gl.FRAMEBUFFER,
+        gl.DEPTH_STENCIL_ATTACHMENT,
+        gl.RENDERBUFFER,
+        old.depthAttached ? old.depth : null,
+      );
+    }
+    if (newDepth) {
+      gl.deleteRenderbuffer(depthBuffer);
+    }
+    throw error;
+  }
+
+  if (newDepth) {
+    gl.disable(gl.SCISSOR_TEST);
+    gl.depthMask(true);
+    gl.stencilMask(255);
+    gl.clearDepth(1);
+    gl.clearStencil(0);
+    gl.clear(gl.DEPTH_BUFFER_BIT | gl.STENCIL_BUFFER_BIT);
+    gl.depthMask(depthWrite);
+    gl.stencilMask(stencilWrite);
+  }
+
+  if (same) {
+    old.depth = depthBuffer;
+    old.depthAttached = depth;
+    return old;
+  }
+
+  return {
+    framebuffer,
+    color,
+    depth: depthBuffer,
+    samples,
+    resolve,
+    texture: resolved,
+    valid: false,
+    dirty: false,
+    face: 0,
+    depthAttached: depth,
+  };
+}

package/src/webgl/textures.ts

@@ -0,0 +1,200 @@
+import type { Texture3D } from "../backend.js";
+import { blockBytes, type DxtEncoder, decodeDxt, encodeDxt } from "../dxt.js";
+import { Context3DError } from "../errors.js";
+import { range } from "./state.js";
+import type { MultisampleTarget } from "./targets.js";
+
+export interface TextureState {
+  handle: WebGLTexture;
+  /** The internal format its storage has: RGBA8, or S3TC's for a compressed texture. */
+  storage: number;
+  /** RGBA staging for a level, made at the first upload that needs it: base-sized. */
+  bytes: Uint8Array;
+  uploaded: Uint16Array;
+  framebuffer: WebGLFramebuffer | null;
+  depthBuffer: WebGLRenderbuffer | null;
+  dirty: boolean;
+  face: number;
+  mipFramebuffer: WebGLFramebuffer | null;
+  depthAttached: boolean;
+  multisample: MultisampleTarget | null;
+  samples: number;
+  antiAlias: number;
+}
+
+/** The staging array, made base-sized at its first use: a texture given only blocks on S3TC has none. */
+function staging(texture: Texture3D, state: TextureState): Uint8Array {
+  if (state.bytes.length === 0) {
+    state.bytes = new Uint8Array(texture.width * texture.height * 4);
+  }
+
+  return state.bytes;
+}
+
+/** The staged level uploaded: as it is, or a compressed texture's encoded to its blocks, as AIR compresses pixels. */
+function uploadLevel(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  state: TextureState,
+  level: number,
+  face: number,
+  w: number,
+  h: number,
+  encoder: DxtEncoder | null,
+): void {
+  if (texture.format !== "bgra") {
+    const rgba = state.bytes.subarray(0, w * h * 4);
+    const dxt5 = texture.format === "compressedAlpha";
+    const blocks = encoder?.(rgba, dxt5, w, h) ?? encodeDxt(rgba, dxt5, w, h);
+    uploadCompressedLevel(gl, texture, state, blocks, level, face);
+    return;
+  }
+
+  const cube = texture.cube;
+  const target = cube ? gl.TEXTURE_CUBE_MAP : gl.TEXTURE_2D;
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(target, state.handle);
+  gl.texSubImage2D(
+    cube ? gl.TEXTURE_CUBE_MAP_POSITIVE_X + face : target,
+    level,
+    0,
+    0,
+    w,
+    h,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    state.bytes,
+  );
+  state.uploaded[face] |= 1 << level;
+}
+
+export function uploadTexture(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  state: TextureState,
+  pixels: Uint32Array,
+  level: number,
+  face: number,
+  sourceWidth?: number,
+  sourceHeight?: number,
+  encoder: DxtEncoder | null = null,
+): void {
+  const { width, height, levels, cube } = texture;
+  const faces = cube ? 6 : 1;
+  range(level, 1, levels);
+  range(face, 1, faces);
+  const w = Math.max(1, width >> level);
+  const h = Math.max(1, height >> level);
+  const sw = sourceWidth ?? w;
+  const sh = sourceHeight ?? h;
+  if (
+    !Number.isSafeInteger(sw) ||
+    sw <= 0 ||
+    !Number.isSafeInteger(sh) ||
+    sh <= 0 ||
+    pixels.length !== sw * sh
+  ) {
+    throw new Context3DError("textureUpload", "Context3D experiment: texture upload size mismatch");
+  }
+
+  // Made once the call is known good: a refused one allocates nothing.
+  staging(texture, state);
+
+  if (sw === w && sh === h) {
+    for (let i = 0; i < pixels.length; i++) {
+      const pixel = pixels[i];
+      const at = i * 4;
+      state.bytes[at] = pixel >>> 16;
+      state.bytes[at + 1] = pixel >>> 8;
+      state.bytes[at + 2] = pixel;
+      state.bytes[at + 3] = pixel >>> 24;
+    }
+  } else {
+    // AIR clips at the top-left and clears uncovered pixels, without scaling.
+    if (sw < w || sh < h) {
+      state.bytes.fill(0, 0, w * h * 4);
+    }
+    const columns = Math.min(w, sw);
+    const rows = Math.min(h, sh);
+    for (let y = 0; y < rows; y++) {
+      for (let x = 0; x < columns; x++) {
+        const pixel = pixels[y * sw + x];
+        const at = (y * w + x) * 4;
+        state.bytes[at] = pixel >>> 16;
+        state.bytes[at + 1] = pixel >>> 8;
+        state.bytes[at + 2] = pixel;
+        state.bytes[at + 3] = pixel >>> 24;
+      }
+    }
+  }
+
+  uploadLevel(gl, texture, state, level, face, w, h, encoder);
+}
+
+export function uploadTextureBytes(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  state: TextureState,
+  data: Uint8Array,
+  offset: number,
+  level: number,
+  face: number,
+  encoder: DxtEncoder | null = null,
+): void {
+  const { width, height, levels, cube } = texture;
+  const faces = cube ? 6 : 1;
+  range(level, 1, levels);
+  range(face, 1, faces);
+  const w = Math.max(1, width >> level);
+  const h = Math.max(1, height >> level);
+  const length = w * h * 4;
+  range(offset, length, data.length);
+  staging(texture, state);
+
+  for (let i = 0; i < length; i += 4) {
+    state.bytes[i] = data[offset + i + 2];
+    state.bytes[i + 1] = data[offset + i + 1];
+    state.bytes[i + 2] = data[offset + i];
+    state.bytes[i + 3] = data[offset + i + 3];
+  }
+
+  uploadLevel(gl, texture, state, level, face, w, h, encoder);
+}
+
+/**
+ * A compressed texture's level from S3TC blocks: as they are where its
+ * storage is S3TC's, or decoded to RGBA where the context takes no S3TC.
+ */
+export function uploadCompressedLevel(
+  gl: WebGL2RenderingContext,
+  texture: Texture3D,
+  state: TextureState,
+  blocks: Uint8Array,
+  level: number,
+  face: number,
+): void {
+  const { width, height, levels, cube } = texture;
+  range(level, 1, levels);
+  range(face, 1, cube ? 6 : 1);
+  const w = Math.max(1, width >> level);
+  const h = Math.max(1, height >> level);
+  const dxt5 = texture.format === "compressedAlpha";
+  if (blocks.length !== blockBytes(w, h, dxt5)) {
+    throw new Context3DError(
+      "textureUpload",
+      "Context3D experiment: compressed level size mismatch",
+    );
+  }
+
+  const target = cube ? gl.TEXTURE_CUBE_MAP_POSITIVE_X + face : gl.TEXTURE_2D;
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(cube ? gl.TEXTURE_CUBE_MAP : gl.TEXTURE_2D, state.handle);
+  if (state.storage === gl.RGBA8) {
+    decodeDxt(blocks, dxt5, w, h, staging(texture, state));
+    gl.texSubImage2D(target, level, 0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, state.bytes);
+  } else {
+    gl.compressedTexSubImage2D(target, level, 0, 0, w, h, state.storage, blocks);
+  }
+
+  state.uploaded[face] |= 1 << level;
+}