@bloopjs/toodle 0.0.100

package/src/scene/JumboQuadNode.ts

@@ -0,0 +1,219 @@
+import { type Mat3, mat3 } from "wgpu-matrix";
+import type { Size } from "../coreTypes/Size";
+import type { Vec2 } from "../coreTypes/Vec2";
+import type { TextureId } from "../textures/AssetManager";
+import type { AtlasCoords } from "../textures/types";
+import { assert } from "../utils/assert";
+import type { Pool } from "../utils/pool";
+import { QuadNode, type QuadOptions } from "./QuadNode";
+import type { SceneNode } from "./SceneNode";
+
+const MAT3_SIZE = 12;
+const VEC4F_SIZE = 4;
+
+export type JumboTileDef = Required<JumboTileOptions>;
+
+export type JumboTileOptions = {
+  /** Texture id of the tile */
+  textureId: TextureId;
+  /** The offset of this tile in texels from the top left of the full texture */
+  offset: Vec2;
+  /** The size of the tile in texels. If not provided, the size will be inferred from the texture atlas. */
+  size?: Size;
+  /** The coordinates of the tile in the texture atlas. If not provided, the size will be read from the loaded texture. */
+  atlasCoords?: AtlasCoords;
+};
+
+export type JumboQuadOptions = Omit<QuadOptions, "atlasCoords"> & {
+  tiles: JumboTileOptions[];
+};
+
+export class JumboQuadNode extends QuadNode {
+  #tiles: Required<JumboTileOptions>[];
+  #matrixPool: Pool<Mat3>;
+
+  constructor(options: JumboQuadOptions, matrixPool: Pool<Mat3>) {
+    assert(
+      options.shader,
+      "JumboQuadNode requires a shader to be explicitly provided",
+    );
+
+    assert(
+      options.tiles && options.tiles.length > 0,
+      "JumboQuadNode requires at least one tile to be provided",
+    );
+
+    options.render ??= {
+      shader: options.shader,
+      writeInstance: writeJumboQuadInstance,
+    };
+
+    super(
+      {
+        ...options,
+        atlasCoords: options.tiles[0].atlasCoords,
+      },
+      matrixPool,
+    );
+
+    this.#matrixPool = matrixPool;
+
+    this.#tiles = [];
+
+    for (const tile of options.tiles) {
+      assert(
+        tile.atlasCoords,
+        "JumboQuadNode requires atlas coords to be provided",
+      );
+
+      assert(tile.size, "JumboQuadNode requires a size to be provided");
+
+      this.#tiles.push({
+        textureId: tile.textureId,
+        offset: tile.offset,
+        size: tile.size,
+        atlasCoords: tile.atlasCoords,
+      });
+    }
+  }
+
+  get atlasCoords(): AtlasCoords {
+    throw new Error("JumboQuadNode does not have a single atlas coords");
+  }
+
+  get tiles(): JumboTileDef[] {
+    return this.#tiles;
+  }
+
+  getTileMatrix(tile: JumboTileDef) {
+    const matrix = mat3.clone(this.matrix, this.#matrixPool.get());
+
+    // Find maximum dimensions across all tiles
+    const originalSize = {
+      width: Math.max(...this.#tiles.map((t) => t.offset.x + t.size.width)),
+      height: Math.max(...this.#tiles.map((t) => t.offset.y + t.size.height)),
+    };
+
+    const proportionalSize = {
+      width: this.size.width / originalSize.width,
+      height: this.size.height / originalSize.height,
+    };
+
+    // Apply translation
+    // calculate the offset of the tile's center from the center of the jumbo quad
+    // eg if the tile is at (0,0) in texels and is 4000x4000 and the whole texture is 5000x5000 this would give us
+    // (2000 - 2500) / 2 = -250, -(2000 - 2500) / 2 = 250
+    const centerOffset = {
+      x: tile.offset.x + tile.size.width / 2 - originalSize.width / 2,
+      y: -(tile.offset.y + tile.size.height / 2 - originalSize.height / 2),
+    };
+    mat3.translate(
+      matrix,
+      [
+        centerOffset.x * proportionalSize.width,
+        centerOffset.y * proportionalSize.height,
+      ],
+      matrix,
+    );
+
+    // Scale proportionally by size of the jumbo quad
+    mat3.scale(
+      matrix,
+      [
+        tile.size.width * proportionalSize.width * (this.flipX ? -1 : 1),
+        tile.size.height * proportionalSize.height * (this.flipY ? -1 : 1),
+      ],
+      matrix,
+    );
+
+    return matrix;
+  }
+}
+
+function writeJumboQuadInstance(
+  node: SceneNode,
+  array: Float32Array,
+  offset: number,
+): number {
+  if (!(node instanceof JumboQuadNode)) {
+    throw new Error(
+      "JumboQuadNode.writeJumboQuadInstance can only be called on JumboQuadNodes",
+    );
+  }
+
+  // Initialize the local offset for each tile to render...
+  let tileOffset = 0;
+
+  // Iterate through each AtlasCoords found in the coords...
+  for (const tile of node.tiles) {
+    const coord = tile.atlasCoords;
+
+    // write model matrix
+    const matrix = node.getTileMatrix(tile);
+    array.set(matrix, offset + tileOffset);
+    tileOffset += MAT3_SIZE;
+
+    // write tint color
+    array.set(
+      [node.color.r, node.color.g, node.color.b, node.color.a],
+      offset + tileOffset,
+    );
+    //...increment the local offset by the size of our color vector
+    tileOffset += VEC4F_SIZE;
+
+    // write uv offset and scale
+    // location 4 are the uv offset and scale used to sample the texture atlas. these are in normalized texel coordinates.
+    // @location(4) uvOffsetAndScale: vec4<f32>,
+    array.set(
+      [
+        coord.uvOffset.x,
+        coord.uvOffset.y,
+        coord.uvScale.width,
+        coord.uvScale.height,
+      ],
+      offset + tileOffset,
+    );
+    tileOffset += VEC4F_SIZE;
+
+    const cropRatio = !coord.uvScaleCropped
+      ? { width: 1, height: 1 }
+      : {
+          width: coord.uvScaleCropped.width / coord.uvScale.width,
+          height: coord.uvScaleCropped.height / coord.uvScale.height,
+        };
+    // write crop offset and scale
+    // location 5 is the crop offset from center and scale. These are ratios applied to the unit quad.
+    // @location(5) cropOffsetAndScale: vec4<f32>,
+    array.set(
+      [
+        // convert the offset in world space to the offset in the local space of the quad
+        // this offset is applied to the unit quad _before_ the model matrix is applied
+        // we divide by 2 because we want the center of the remaining region and not the full shift.
+        // for example, if we crop the leftmost 90px of a 100px wide texture
+        // we want the offset to be 45px and not 90px
+        tile.atlasCoords.cropOffset.x /
+          2 /
+          (tile.atlasCoords.originalSize.width || 1),
+        tile.atlasCoords.cropOffset.y /
+          2 /
+          (tile.atlasCoords.originalSize.height || 1),
+        cropRatio.width,
+        cropRatio.height,
+      ],
+      offset + tileOffset,
+    );
+    tileOffset += VEC4F_SIZE;
+
+    // write atlas index
+    new DataView(array.buffer).setUint32(
+      array.byteOffset + (offset + tileOffset) * Float32Array.BYTES_PER_ELEMENT,
+      coord.atlasIndex,
+      true,
+    );
+    tileOffset += VEC4F_SIZE;
+  }
+
+  // Write our instance and return the number of sprites added to the buffer...
+  node.writeInstance?.(array, offset + tileOffset);
+  return node.tiles.length;
+}

package/src/scene/QuadNode.ts

@@ -0,0 +1,403 @@
+import { type Mat3, mat3 } from "wgpu-matrix";
+import type { Color } from "../coreTypes/Color";
+import type { Size } from "../coreTypes/Size";
+import type { Vec2 } from "../coreTypes/Vec2";
+import type { IShader } from "../shaders/IShader";
+import type { Toodle } from "../Toodle";
+import type { AssetManager, TextureId } from "../textures/AssetManager";
+import type { AtlasCoords, TexelRegion } from "../textures/types";
+import { assert } from "../utils/assert";
+import type { Pool } from "../utils/pool";
+import { type NodeOptions, SceneNode } from "./SceneNode";
+
+const PRIMITIVE_TEXTURE = "__primitive__";
+const RESERVED_PRIMITIVE_INDEX_START = 1000;
+// this must match the circle index in the default fragment shader of quad.wgsl.ts
+const CIRCLE_INDEX = 1001;
+
+// a default region used for shapes
+const DEFAULT_REGION: TexelRegion = {
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+};
+
+/**
+ * A node in the scene graph that renders a textured quad.
+ *
+ * This is a base class and is fairly low level. You will probably want to interact with
+ * the wrapper class {@link Toodle.Quad} instead.
+ */
+export class QuadNode extends SceneNode {
+  assetManager: AssetManager;
+
+  #color: Color;
+  #atlasCoords: AtlasCoords;
+  #region: TexelRegion;
+  #matrixPool: Pool<Mat3>;
+  #flip: Vec2;
+  /**
+   * The offset of the cropped texture from the original texture
+   * If uncropped, this will be 0,0
+   */
+  #cropOffset: Vec2;
+  /**
+   * The ratio of the cropped texture width and height to the original texture width and height
+   * If uncropped, this will be 1,1
+   */
+  #cropRatio: Size;
+  #atlasSize: Size;
+
+  #textureId: TextureId;
+  #writeInstance?: (array: Float32Array, offset: number) => void;
+
+  constructor(options: QuadOptions, matrixPool: Pool<Mat3>) {
+    assert(
+      options.shader,
+      "QuadNode requires a shader to be explicitly provided",
+    );
+    assert(
+      options.idealSize,
+      "QuadNode requires an ideal size to be explicitly provided",
+    );
+
+    assert(
+      options.atlasCoords,
+      "QuadNode requires atlas coords to be explicitly provided",
+    );
+
+    options.render ??= {
+      shader: options.shader,
+      writeInstance: writeQuadInstance,
+    };
+
+    super(options);
+
+    assert(options.assetManager, "QuadNode requires an asset manager");
+    this.assetManager = options.assetManager;
+
+    if (
+      options.atlasCoords &&
+      options.atlasCoords.atlasIndex >= RESERVED_PRIMITIVE_INDEX_START
+    ) {
+      this.#textureId = PRIMITIVE_TEXTURE;
+      this.#region = DEFAULT_REGION;
+      this.#atlasSize = DEFAULT_REGION;
+    } else {
+      assert(
+        options.textureId,
+        "QuadNode requires texture id to be explicitly provided",
+      );
+      this.#textureId = options.textureId;
+
+      assert(
+        options.region,
+        "QuadNode requires a region to be explicitly provided",
+      );
+      this.#region = options.region;
+
+      assert(
+        options.atlasSize,
+        "QuadNode requires atlas size to be explicitly provided",
+      );
+      this.#atlasSize = options.atlasSize;
+    }
+
+    this.#atlasCoords = options.atlasCoords;
+    this.#color = options.color ?? { r: 1, g: 1, b: 1, a: 1 };
+    this.#matrixPool = matrixPool;
+    this.#flip = { x: options.flipX ? -1 : 1, y: options.flipY ? -1 : 1 };
+    this.#cropOffset = options.cropOffset ?? { x: 0, y: 0 };
+    this.#cropRatio = !this.#atlasCoords.uvScaleCropped
+      ? { width: 1, height: 1 }
+      : {
+          width:
+            this.#atlasCoords.uvScaleCropped.width /
+            this.#atlasCoords.uvScale.width,
+          height:
+            this.#atlasCoords.uvScaleCropped.height /
+            this.#atlasCoords.uvScale.height,
+        };
+    this.#writeInstance = options.writeInstance;
+  }
+
+  /**
+   * The tint color of the quad.
+   * When drawing shapes, this will be the fill color.
+   * When drawing textures, this will be the color multiplier by default.
+   * You can also use this value in fragment shaders by referencing `vertex.engine_tint`
+   */
+  get color() {
+    return this.#color;
+  }
+
+  set color(value: Color) {
+    this.#color = value;
+  }
+
+  /**
+   * The size of the quad. See https://toodle.gg/f849595b3ed13fc956fc1459a5cb5f0228f9d259/examples/quad-size-scale.html
+   */
+  get size() {
+    const size = super.size;
+    if (!size) {
+      throw new Error("QuadNode requires a size");
+    }
+    return size;
+  }
+
+  /**
+   * This is the final model matrix used to render the quad, which
+   * may differ from the matrix passed down to the node's children.
+   * Properties like `flipX` and `flipY` or `size` are applied here but not inherited by children.
+   */
+  get matrixWithSize() {
+    const matrix = mat3.clone(this.matrix, this.#matrixPool.get());
+    mat3.scale(
+      matrix,
+      [this.size.width * this.#flip.x, this.size.height * this.#flip.y],
+      matrix,
+    );
+
+    return matrix;
+  }
+
+  /**
+   * The atlas coordinates for the quad. These determine the region in the texture atlas
+   * that is sampled for rendering in normalized uv space.
+   */
+  get atlasCoords() {
+    return this.#atlasCoords;
+  }
+
+  /**
+   * A subregion of the texture to render.
+   * This is useful for rendering a single sprite from a spritesheet for instance.
+   * It defaults to the full texture.
+   */
+  get region() {
+    return this.#region;
+  }
+
+  get writeInstance() {
+    return this.#writeInstance;
+  }
+
+  /**
+   * Whether the image is mirrored horizontally.
+   *
+   * `true` means the image is mirrored (equivalent to a scale.x of -1),
+   * `false` means it is not mirrored.
+   */
+  get flipX(): boolean {
+    return this.#flip.x === -1;
+  }
+
+  /**
+   * Sets whether the image is mirrored horizontally.
+   *
+   * `true` mirrors the image (equivalent to a scale.x of -1),
+   * `false` restores normal orientation.
+   */
+  set flipX(value: boolean) {
+    this.#flip.x = value ? -1 : 1;
+    this.setDirty();
+  }
+
+  /**
+   * Whether the image is mirrored vertically.
+   *
+   * `true` means the image is mirrored (equivalent to a scale.y of -1),
+   * `false` means it is not mirrored.
+   */
+  get flipY(): boolean {
+    return this.#flip.y === -1;
+  }
+
+  /**
+   * Sets whether the image is mirrored vertically.
+   *
+   * `true` mirrors the image (equivalent to a scale.y of -1),
+   * `false` restores normal orientation.
+   */
+  set flipY(value: boolean) {
+    this.#flip.y = value ? -1 : 1;
+    this.setDirty();
+  }
+
+  /**
+   * The drawing offset of the texture.
+   * This can be used to offset the texture from the origin of the quad.
+   */
+  get cropOffset(): Vec2 {
+    return this.#cropOffset;
+  }
+
+  /**
+   * The drawing offset of the texture.
+   * This can be used to offset the texture from the origin of the quad.
+   */
+  set cropOffset(value: Vec2) {
+    this.#cropOffset = value;
+  }
+
+  get textureId() {
+    return this.#textureId;
+  }
+
+  /**
+   * Whether this quad is rendering a primitive shape like a line or a circle/rect.
+   */
+  get isPrimitive() {
+    return this.#textureId === PRIMITIVE_TEXTURE;
+  }
+
+  /**
+   * Whether this quad is rendering a circle.
+   */
+  get isCircle() {
+    return this.#atlasCoords.atlasIndex === CIRCLE_INDEX;
+  }
+
+  extra = {
+    /**
+     * Sets the atlas coords for the quad. This is for advanced use cases and by default these are
+     * set automatically to reference the right texture atlas region.
+     * @param value - The new atlas coords.
+     */
+    setAtlasCoords: (value: AtlasCoords) => {
+      this.#atlasCoords = value;
+    },
+
+    /**
+     * Returns the crop ratio for the quad. This is the relative difference in size
+     * between the cropped and uncropped texture, and will be 1 if the quad has no transparent pixels
+     * or if it is loaded without cropping..
+     */
+    cropRatio: () => {
+      return this.#cropRatio;
+    },
+
+    /**
+     * Returns the size of the texture atlas in texels, by default this is 4096x4096
+     */
+    atlasSize: () => {
+      return this.#atlasSize;
+    },
+  };
+}
+
+export type QuadOptions = NodeOptions & {
+  textureId?: TextureId;
+  /**
+   * A subregion of the texture to render.
+   * This is useful for rendering a single sprite from a spritesheet for instance.
+   * It defaults to the full texture.
+   */
+  region?: TexelRegion;
+  /**
+   * Atlas coordinates are almost always set by toodle and the asset manager.
+   * For advanced use cases, you can set these yourself to control what uvs are sampled
+   * from the texture atlas.
+   */
+  atlasCoords?: AtlasCoords;
+
+  assetManager?: AssetManager;
+
+  shader?: IShader;
+  writeInstance?: (array: Float32Array, offset: number) => void;
+  color?: Color;
+  /**
+   * flipX mirrors the image horizontally (equivalent to a scale.x multiplication
+   * by -1) but allows for independent scaling
+   */
+  flipX?: boolean;
+  /**
+   * flipY mirrors the image vertically (equivalent to a scale.y multiplication
+   * by -1) but allows for independent scaling
+   */
+  flipY?: boolean;
+  /**
+   * The offset of the cropped texture from the original texture
+   * If uncropped, this will be 0,0
+   */
+  cropOffset?: Vec2;
+
+  /**
+   * The size of the texture atlas in texels. This is almost always set by toodle.
+   */
+  atlasSize?: Size;
+
+  /**
+   * The matrix pool to use for the quad.
+   * This is used to avoid creating new matrices for each quad.
+   */
+  matrixPool?: Pool<Mat3>;
+};
+
+function writeQuadInstance(
+  node: SceneNode,
+  array: Float32Array,
+  offset: number,
+) {
+  if (!(node instanceof QuadNode)) {
+    throw new Error("QuadNode.writeInstance can only be called on QuadNodes");
+  }
+
+  array.set(node.matrixWithSize, offset);
+
+  array.set(
+    [node.color.r, node.color.g, node.color.b, node.color.a],
+    offset + 12,
+  );
+
+  const region = node.region;
+  if (node.textureId === PRIMITIVE_TEXTURE) {
+    array.set(
+      [
+        node.atlasCoords.uvOffset.x,
+        node.atlasCoords.uvOffset.y,
+        node.atlasCoords.uvScale.width,
+        node.atlasCoords.uvScale.height,
+      ],
+      offset + 16,
+    );
+  } else {
+    const atlasSize = node.extra.atlasSize();
+    array.set(
+      [
+        node.atlasCoords.uvOffset.x + region.x / atlasSize.width,
+        node.atlasCoords.uvOffset.y + region.y / atlasSize.height,
+        region.width / atlasSize.width,
+        region.height / atlasSize.height,
+      ],
+      offset + 16,
+    );
+  }
+
+  array.set(
+    [
+      // convert the offset in world space to the offset in the local space of the quad
+      // this offset is applied to the unit quad _before_ the model matrix is applied
+      // we divide by 2 because we want the center of the remaining region and not the full shift.
+      // for example, if we crop the leftmost 90px of a 100px wide texture
+      // we want the offset to be 45px and not 90px
+      node.cropOffset.x / 2 / (node.atlasCoords.originalSize.width || 1),
+      node.cropOffset.y / 2 / (node.atlasCoords.originalSize.height || 1),
+      node.extra.cropRatio().width,
+      node.extra.cropRatio().height,
+    ],
+    offset + 20,
+  );
+
+  new DataView(array.buffer).setUint32(
+    array.byteOffset + (offset + 24) * Float32Array.BYTES_PER_ELEMENT,
+    node.atlasCoords.atlasIndex,
+    true,
+  );
+
+  node.writeInstance?.(array, offset + 28);
+
+  return 1;
+}

package/src/scene/RenderComponent.ts

@@ -0,0 +1,12 @@
+import type { IShader } from "../shaders/IShader";
+import type { SceneNode } from "./SceneNode";
+
+export type RenderComponent = {
+  shader: IShader;
+  data?: Float32Array;
+
+  /**
+   * Write cpu instance data to the buffer. Returns number of instances written
+   */
+  writeInstance: (node: SceneNode, dst: Float32Array, offset: number) => number;
+};