@bloopjs/toodle 0.0.100

package/src/textures/types.ts

@@ -0,0 +1,182 @@
+// types.ts should exclusively contain typescript types and no runtime js code.
+// that way it is safe to import/export for consumers
+// without accidentally including browser code via tree-shaking.
+
+import type { Size, Vec2 } from "../coreTypes/mod";
+
+export type AtlasCoords = TextureRegion & {
+  atlasIndex: number;
+};
+
+/**
+ * A TextureRegion is a region of the texture atlas in normalized texels.
+ *
+ * It is a combination of a UvRegion and a cropOffset.
+ */
+export type TextureRegion = UvRegion & {
+  /** the offset from the top left of the texture in texels to begin drawing */
+  cropOffset: Vec2;
+  /** the original size of the texture in texels */
+  originalSize: Size;
+};
+
+/**
+ * A UvRegion is a region of the texture atlas in normalized texels.
+ */
+export type UvRegion = {
+  /**
+   * The offset of the UVs in normalized atlas texels. Relative to the un-cropped texture.
+   *
+   * @example
+   *
+   * { x: 10 / 4096, y: 10 / 4096 }
+   */
+  uvOffset: Vec2;
+  /**
+   * The scale of the UVs in normalized texels. Derived from the width and height of the un-cropped texture.
+   *
+   * @example
+   *
+   * { width: 1 / 4096, height: 1 / 4096 }
+   */
+  uvScale: Size;
+  /**
+   * The scale of the UVs in normalized texels. Derived from the width and height of the cropped texture.
+   *
+   * @example
+   *
+   * { width: 1 / 4096, height: 1 / 4096 }
+   */
+  uvScaleCropped?: Size;
+};
+
+/**
+ * A CpuTextureAtlas is a texture atlas that has been loaded into memory.
+ *
+ * It contains the texture and a map of texture ids to TextureRegions.
+ */
+export type CpuTextureAtlas = {
+  texture: ImageBitmap;
+  rg8Bytes?: Uint8Array<ArrayBuffer>;
+  textureRegions: Map<string, TextureRegion>;
+  width: number;
+  height: number;
+};
+
+/**
+ * A TextureWithMetadata is a texture that has been loaded into the gpu.
+ *
+ * It contains the gpu texture data and a cropOffset and originalSize for use with cropped textures.
+ */
+export type TextureWithMetadata = {
+  texture: GPUTexture;
+  /** crop offset from center in texel units */
+  cropOffset: Vec2;
+  /** original size in texel units before cropping */
+  originalSize: Size;
+};
+
+/** A definition for a pre-baked texture atlas */
+export type AtlasDef =
+  | {
+      /** The url of the atlas png file, if empty the png is assumed to be next to the json file */
+      png?: URL;
+      /** The url of the atlas json file, if empty the json is assumed to be next to the png file */
+      json: URL;
+    }
+  | {
+      /** The url of the atlas png file, if empty the png is assumed to be next to the json file */
+      png: URL;
+      /** The url of the atlas json file, if empty the json is assumed to be next to the png file */
+      json?: URL;
+    };
+
+/** Bundle options for registering multiple individual textures */
+export type TextureBundleOpts = {
+  /**
+   * A record of texture ids and URLs.
+   * ids must be unique within a bundle
+   *
+   */
+  textures: Record<string, URL>;
+
+  /**
+   * Whether the image should be cropped down to the minimal bounding box for non-transparent pixels.
+   *
+   * See [Transparent Pixel Cropping](https://toodle.gg/f849595b3ed13fc956fc1459a5cb5f0228f9d259/examples/transparent-cropping.html) for more information.
+   */
+  cropTransparentPixels?: boolean;
+  /**
+   * Whether the bundle should be loaded automatically on registration
+   */
+  autoLoad?: boolean;
+};
+
+/** Bundle options for registering pre-generated texture atlases */
+export type AtlasBundleOpts = {
+  /**
+   * atlas definitions as pregenerated by a texture packer like https://github.com/pixijs/assetpack
+   *
+   * @example
+   *
+   * [
+   *   {
+   *     json: new URL('https://example.com/atlas.json'),
+   *   },
+   *   {
+   *     png: new URL('https://example.com/atlas.png'),
+   *   },
+   *   {
+   *     json: new URL('https://example.com/metadata/atlas.json'),
+   *     png: new URL('https://example.com/images/atlas.png'),
+   *   },
+   * ]
+   */
+  atlases: AtlasDef[];
+
+  /**
+   * Whether the bundle should be loaded automatically on registration
+   */
+  autoLoad?: boolean;
+
+  /**
+   * If true, png urls will be ignored and the texture path will be inferred to be next to the json file
+   * with a .rg8.gz extension.
+   */
+  rg8?: boolean;
+};
+
+/**
+ * A texel region defines a subregion of an individual texture in texel units.
+ *
+ * (0,0) is the top left corner of the original texture.
+ * (width, height) is the bottom right corner of the original texture.
+ *
+ * @example
+ * This is useful for something like spritesheet animations,
+ * for eg a 3-frame pose of a 32x32 character sprite might be 96x32 texels, and the animation could
+ * be done by alternating between:
+ *
+ * { x: 0, y: 0, width: 32, height: 32 }
+ * { x: 32, y: 0, width: 32, height: 32 }
+ * { x: 64, y: 0, width: 32, height: 32 }
+ *
+ */
+export type TexelRegion = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+/** A region specification from a pixi.js spritesheet or atlas paced with assetPack */
+export type PixiRegion = {
+  /** the position and size of the cropped region in the atlas, measured in texels*/
+  frame: { x: number; y: number; w: number; h: number };
+  rotated: boolean;
+  trimmed: boolean;
+  /** the original size of the texture in texels */
+  sourceSize: { w: number; h: number };
+  /** the position and size of the cropped region of the texture prior to packing in the atlas, measured in texels */
+  spriteSourceSize: { x: number; y: number; w: number; h: number };
+};

package/src/textures/util.ts

@@ -0,0 +1,352 @@
+import { unzipSync } from "fflate";
+import type {
+  CpuTextureAtlas,
+  TextureRegion,
+  TextureWithMetadata,
+} from "./types";
+
+export async function getBitmapFromUrl(url: URL): Promise<ImageBitmap> {
+  try {
+    const response = await fetch(url);
+    const blob = await response.blob();
+    return await createImageBitmap(blob);
+  } catch (e) {
+    console.error(`Failed to load texture from ${url.href}`, e);
+    throw e;
+  }
+}
+
+/**
+ * Converts an image Blob to ImageData.
+ *
+ * @param blob - The Blob containing the image.
+ * @returns A Promise resolving to the image as ImageData.
+ */
+async function blobToImageData(blob: Blob) {
+  const imageBitmap: ImageBitmap = await createImageBitmap(blob);
+
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d");
+
+  if (!ctx) {
+    throw new Error("Failed to get 2D context from canvas");
+  }
+
+  canvas.width = imageBitmap.width;
+  canvas.height = imageBitmap.height;
+
+  ctx.drawImage(imageBitmap, 0, 0);
+
+  const imageData: ImageData = ctx.getImageData(
+    0,
+    0,
+    canvas.width,
+    canvas.height,
+  );
+
+  imageBitmap.close();
+
+  return imageData;
+}
+
+/**
+ * Creates a checkerboard pattern ImageData in black and purple.
+ *
+ * @param width - Width of the image.
+ * @param height - Height of the image.
+ * @param tileSize - Size of each checker tile (default is 8).
+ * @returns The generated ImageData object.
+ */
+function createCheckerboardImageData(
+  width: number,
+  height: number,
+  tileSize = 8,
+): ImageData {
+  const data = new Uint8ClampedArray(width * height * 4);
+
+  const purple = [128, 0, 128, 255]; // #800080
+  const black = [0, 0, 0, 255]; // #000000
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const usePurple =
+        (Math.floor(x / tileSize) + Math.floor(y / tileSize)) % 2 === 0;
+      const color = usePurple ? purple : black;
+      const idx = (y * width + x) * 4;
+
+      data.set(color, idx);
+    }
+  }
+
+  return new ImageData(data, width, height);
+}
+
+export async function loadZip(
+  zipUrl: URL,
+): Promise<{ path: string; bitmap: ImageBitmap }[]> {
+  console.time("fetch zip");
+  const zip = await fetch(zipUrl);
+  const zipBlob = await zip.blob();
+  const zipUint8Array = await zipBlob.arrayBuffer();
+  console.timeEnd("fetch zip");
+
+  console.time("unzip");
+  const files = unzipSync(new Uint8Array(zipUint8Array));
+  console.timeEnd("unzip");
+
+  console.time("create bitmaps");
+  const validFiles = Object.entries(files).filter(
+    ([path]) => !path.match("__MACOS") && path.endsWith(".png"),
+  );
+
+  return await Promise.all(
+    validFiles.map(async ([path, file]) => {
+      const bitmap = await createImageBitmap(new Blob([file]));
+      return { path, bitmap };
+    }),
+  );
+}
+
+export async function packBitmapsToAtlas(
+  images: Map<string, TextureWithMetadata>,
+  textureSize: number,
+  device: GPUDevice,
+): Promise<CpuTextureAtlas[]> {
+  const cpuTextureAtlases: CpuTextureAtlas[] = [];
+  const packed: PackedTexture[] = [];
+  const spaces: Rectangle[] = [
+    { x: 0, y: 0, width: textureSize, height: textureSize },
+  ];
+
+  let atlasRegionMap = new Map<string, TextureRegion>();
+
+  for (const [id, { texture, cropOffset: offset, originalSize }] of images) {
+    // Find best fitting space using guillotine method
+    let bestSpace = -1;
+    let bestScore = Number.POSITIVE_INFINITY;
+
+    for (let i = 0; i < spaces.length; i++) {
+      const space = spaces[i];
+      if (texture.width <= space.width && texture.height <= space.height) {
+        // Score based on how well it fits (smaller score is better)
+        const score = Math.abs(
+          space.width * space.height - texture.width * texture.height,
+        );
+        if (score < bestScore) {
+          bestScore = score;
+          bestSpace = i;
+        }
+      }
+    }
+
+    if (bestSpace === -1) {
+      const tex = await createTextureAtlasTexture(device, packed, textureSize);
+      cpuTextureAtlases.push({
+        texture: tex,
+        textureRegions: atlasRegionMap,
+        width: tex.width,
+        height: tex.height,
+      });
+
+      atlasRegionMap = new Map<string, TextureRegion>();
+      packed.length = 0;
+
+      spaces.length = 0;
+      spaces.push({
+        x: 0,
+        y: 0,
+        width: textureSize,
+        height: textureSize,
+      });
+      bestSpace = 0;
+    }
+
+    const space = spaces[bestSpace];
+
+    // Pack the image
+    packed.push(<PackedTexture>{
+      texture: await textureToBitmap(
+        device,
+        texture,
+        texture.width,
+        texture.height,
+      ),
+      x: space.x,
+      y: space.y,
+      width: texture.width,
+      height: texture.height,
+    });
+
+    texture.destroy();
+
+    // Split remaining space into two new spaces
+    spaces.splice(bestSpace, 1);
+
+    if (space.width - texture.width > 0) {
+      spaces.push({
+        x: space.x + texture.width,
+        y: space.y,
+        width: space.width - texture.width,
+        height: texture.height,
+      });
+    }
+
+    if (space.height - texture.height > 0) {
+      spaces.push({
+        x: space.x,
+        y: space.y + texture.height,
+        width: space.width,
+        height: space.height - texture.height,
+      });
+    }
+
+    // Create atlas coords
+    atlasRegionMap.set(id, {
+      uvOffset: {
+        x: space.x / textureSize,
+        y: space.y / textureSize,
+      },
+      uvScale: {
+        width: originalSize.width / textureSize,
+        height: originalSize.height / textureSize,
+      },
+      uvScaleCropped: {
+        width: texture.width / textureSize,
+        height: texture.height / textureSize,
+      },
+      cropOffset: offset,
+      originalSize,
+    });
+  }
+  const tex = await createTextureAtlasTexture(device, packed, textureSize);
+
+  cpuTextureAtlases.push({
+    texture: tex,
+    textureRegions: atlasRegionMap,
+    width: tex.width,
+    height: tex.height,
+  });
+
+  return cpuTextureAtlases;
+}
+
+async function createTextureAtlasTexture(
+  device: GPUDevice,
+  packed: PackedTexture[],
+  atlasSize: number,
+) {
+  const encoder: GPUCommandEncoder = device.createCommandEncoder();
+  const atlasTexture: GPUTexture = device.createTexture({
+    label: "Texture Atlas Texture Holder",
+    size: [atlasSize, atlasSize, 1],
+    format: "rgba8unorm",
+    usage:
+      GPUTextureUsage.TEXTURE_BINDING |
+      GPUTextureUsage.COPY_DST |
+      GPUTextureUsage.COPY_SRC |
+      GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+
+  for (const texture of packed) {
+    device.queue.copyExternalImageToTexture(
+      {
+        source: texture.texture,
+      },
+      {
+        texture: atlasTexture,
+        origin: [texture.x, texture.y, 0],
+      },
+      [texture.width, texture.height, 1],
+    );
+  }
+  device.queue.submit([encoder.finish()]);
+  const atlasBitmap: ImageBitmap = await textureToBitmap(
+    device,
+    atlasTexture,
+    atlasTexture.width,
+    atlasTexture.height,
+  );
+  atlasTexture.destroy();
+  return atlasBitmap;
+}
+
+/**
+ * Converts a WebGPU GPUTexture into an ImageBitmap.
+ *
+ * @param {GPUDevice} device - The WebGPU device used to create GPU resources.
+ * @param {GPUTexture} texture - The GPUTexture to convert. Must be in `rgba8unorm` format.
+ * @param {number} width - The width of the texture in pixels.
+ * @param {number} height - The height of the texture in pixels.
+ * @returns {Promise<ImageBitmap>} A promise that resolves to an ImageBitmap containing the texture's contents.
+ *
+ * @example
+ * const bitmap = await textureToBitmap(device, queue, myTexture, 256, 256);
+ * const canvas = document.createElement("canvas");
+ * const ctx = canvas.getContext("2d");
+ * ctx.drawImage(bitmap, 0, 0);
+ */
+async function textureToBitmap(
+  device: GPUDevice,
+  texture: GPUTexture,
+  width: number,
+  height: number,
+): Promise<ImageBitmap> {
+  const bytesPerPixel = 4;
+  const bytesPerRow = Math.ceil((width * bytesPerPixel) / 256) * 256;
+  const bufferSize = bytesPerRow * height;
+
+  const readBuffer = device.createBuffer({
+    size: bufferSize,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+
+  const commandEncoder = device.createCommandEncoder();
+  commandEncoder.copyTextureToBuffer(
+    { texture: texture },
+    {
+      buffer: readBuffer,
+      bytesPerRow: bytesPerRow,
+      rowsPerImage: height,
+    },
+    {
+      width: width,
+      height: height,
+      depthOrArrayLayers: 1,
+    },
+  );
+
+  const commands = commandEncoder.finish();
+  device.queue.submit([commands]);
+
+  await readBuffer.mapAsync(GPUMapMode.READ);
+  const arrayBuffer = readBuffer.getMappedRange();
+  const data = new Uint8ClampedArray(arrayBuffer);
+
+  const imageData = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const rowStart = y * bytesPerRow;
+    const rowEnd = rowStart + width * 4;
+    imageData.set(data.subarray(rowStart, rowEnd), y * width * 4);
+  }
+
+  const image = new ImageData(imageData, width, height);
+  const bitmap = await createImageBitmap(image);
+
+  readBuffer.unmap();
+  return bitmap;
+}
+
+type PackedTexture = {
+  texture: ImageBitmap;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+type Rectangle = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};

package/src/utils/assert.ts

@@ -0,0 +1,5 @@
+export function assert(condition: any, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(message);
+  }
+}

package/src/utils/boilerplate.ts

@@ -0,0 +1,110 @@
+import {
+  makeBindGroupLayoutDescriptors,
+  makeShaderDataDefinitions,
+} from "webgpu-utils";
+import type { ShaderDescriptor } from "../shaders/ShaderDescriptor";
+import { assert } from "./assert";
+
+// convenience functions to wrap verbose webgpu apis - not part of public api
+
+export async function initGpu(
+  canvas: HTMLCanvasElement,
+  onUncapturedError?: (e: GPUUncapturedErrorEvent) => void,
+) {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) {
+    throw new Error("WebGPU not supported");
+  }
+
+  const device = await adapter.requestDevice();
+  device.lost.then((info) => {
+    console.error("GPU Device lost", info);
+  });
+  if (onUncapturedError) {
+    device.onuncapturederror = onUncapturedError;
+  }
+
+  const context = canvas.getContext("webgpu");
+
+  assert(device, "WebGPU not supported");
+  assert(context, "WebGPU not supported");
+
+  const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+
+  context.configure({
+    device,
+    format: presentationFormat,
+  });
+
+  return {
+    device,
+    context,
+    presentationFormat,
+  };
+}
+
+export function getGpuPipelineDescriptor(
+  shaderDescriptor: ShaderDescriptor,
+  module: GPUShaderModule,
+  presentationFormat: GPUTextureFormat,
+  blend?: GPUBlendState,
+): Omit<GPURenderPipelineDescriptor, "layout"> {
+  const pipelineDescriptor: Omit<GPURenderPipelineDescriptor, "layout"> = {
+    label: `${shaderDescriptor.label} pipeline`,
+    vertex: {
+      module,
+      entryPoint: shaderDescriptor.vertexEntrypoint,
+    },
+    fragment: {
+      module,
+      entryPoint: shaderDescriptor.fragmentEntrypoint,
+      targets: [
+        {
+          format: presentationFormat,
+          blend,
+        },
+      ],
+    },
+    primitive: {
+      topology: "triangle-strip",
+    },
+  };
+
+  return pipelineDescriptor;
+}
+
+export function setVertexInstanceBufferLayout(
+  pipeline: Omit<GPURenderPipelineDescriptor, "layout">,
+  bufferLayout: GPUVertexBufferLayout,
+): Omit<GPURenderPipelineDescriptor, "layout"> {
+  pipeline.vertex.buffers = [bufferLayout];
+  return pipeline;
+}
+
+export function attachVertexInstanceBuffer(
+  renderPass: GPURenderPassEncoder,
+  instanceBuffer: GPUBuffer,
+) {
+  renderPass.setVertexBuffer(0, instanceBuffer);
+}
+
+export function createGpuPipeline(
+  device: GPUDevice,
+  shaderDescriptor: ShaderDescriptor,
+  pipelineDescriptor: Omit<GPURenderPipelineDescriptor, "layout">,
+): GPURenderPipeline {
+  const defs = makeShaderDataDefinitions(shaderDescriptor.code);
+  const descriptors = makeBindGroupLayoutDescriptors(defs, pipelineDescriptor);
+
+  return device.createRenderPipeline({
+    ...pipelineDescriptor,
+    layout: device.createPipelineLayout({
+      bindGroupLayouts: descriptors.map((d, i) =>
+        device.createBindGroupLayout({
+          label: `${shaderDescriptor.label} bind group layout ${i}`,
+          ...d,
+        }),
+      ),
+    }),
+  });
+}

package/src/utils/error.ts

@@ -0,0 +1,14 @@
+const warnings: Map<string, boolean> = new Map<string, boolean>();
+/**
+ * Useful for warning in a function run every frame if you only want to warn once
+ *
+ * @param key a unique key to tag the warning
+ * @param msg message to console.warn
+ */
+export function warnOnce(key: string, msg?: string) {
+  if (warnings.has(key)) {
+    return;
+  }
+  warnings.set(key, true);
+  console.warn(msg ?? key);
+}

package/src/utils/mod.ts

@@ -0,0 +1,2 @@
+export * from "./assert";
+export * from "./pool";

package/src/utils/pool.ts

@@ -0,0 +1,42 @@
+/**
+ * A simple pool for creating and reusing objects to avoid allocation between frames
+ *
+ * @example
+ *
+ * const pool = new Pool(() => new SomeObject(), 10);
+ *
+ * function animate() {
+ *   const obj = pool.get();
+ *   console.log(obj);
+ *   pool.free();
+ *   requestAnimationFrame(animate);
+ * }
+ *
+ * requestAnimationFrame(animate);
+ */
+export class Pool<T> {
+  #items: T[] = [];
+  #create: () => T;
+  #index = 0;
+
+  constructor(create: () => T, initialSize = 0) {
+    this.#create = create;
+    if (initialSize > 0) {
+      this.#items = Array.from({ length: initialSize })
+        .fill(null)
+        .map(() => this.#create());
+    }
+  }
+
+  get() {
+    if (this.#index >= this.#items.length) {
+      this.#items.push(this.#create());
+    }
+
+    return this.#items[this.#index++];
+  }
+
+  free() {
+    this.#index = 0;
+  }
+}