@aethervtt/shard-texture 0.0.1

package/dist/pack.js

@@ -0,0 +1,147 @@
+class SkylinePacker {
+  width;
+  height;
+  /** Skyline segments: x, y (top of the free space), width. */
+  xs = [0];
+  ys = [0];
+  ws;
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.ws = [width];
+  }
+  /** Places a w×h rectangle; returns its top-left, or undefined when it doesn't fit. */
+  insert(w, h) {
+    let bestY = Infinity;
+    let bestX = 0;
+    let bestIndex = -1;
+    let bestWaste = Infinity;
+    for (let i = 0; i < this.xs.length; i++) {
+      const x = this.xs[i];
+      if (x + w > this.width) break;
+      let y = 0;
+      let covered = 0;
+      let j = i;
+      while (covered < w) {
+        y = Math.max(y, this.ys[j]);
+        covered += this.ws[j];
+        j++;
+      }
+      if (y + h > this.height) continue;
+      let waste = 0;
+      covered = 0;
+      for (let k = i; k < j; k++) {
+        const segW = Math.min(this.ws[k], w - covered);
+        waste += (y - this.ys[k]) * segW;
+        covered += segW;
+      }
+      if (y < bestY || y === bestY && waste < bestWaste) {
+        bestY = y;
+        bestX = x;
+        bestIndex = i;
+        bestWaste = waste;
+      }
+    }
+    if (bestIndex < 0) return void 0;
+    this.place(bestIndex, bestX, bestY + h, w);
+    return { x: bestX, y: bestY };
+  }
+  place(index, x, top, w) {
+    const end = x + w;
+    const i = index;
+    while (i < this.xs.length && this.xs[i] < end) {
+      const segEnd = this.xs[i] + this.ws[i];
+      if (segEnd <= end) {
+        this.xs.splice(i, 1);
+        this.ys.splice(i, 1);
+        this.ws.splice(i, 1);
+      } else {
+        this.ws[i] = segEnd - end;
+        this.xs[i] = end;
+        break;
+      }
+    }
+    this.xs.splice(index, 0, x);
+    this.ys.splice(index, 0, top);
+    this.ws.splice(index, 0, w);
+    for (let k = 0; k < this.xs.length - 1; k++) {
+      if (this.ys[k] === this.ys[k + 1]) {
+        this.ws[k] = this.ws[k] + this.ws[k + 1];
+        this.xs.splice(k + 1, 1);
+        this.ys.splice(k + 1, 1);
+        this.ws.splice(k + 1, 1);
+        k--;
+      }
+    }
+  }
+}
+function tryPack(items, order, w, h, padding, placements, page, partial) {
+  const packer = new SkylinePacker(w, h);
+  const left = [];
+  for (const i of order) {
+    const item = items[i];
+    const spot = packer.insert(item.width + padding * 2, item.height + padding * 2);
+    if (!spot) {
+      if (!partial) return order.slice();
+      left.push(i);
+      continue;
+    }
+    placements[i] = { page, x: spot.x + padding, y: spot.y + padding };
+  }
+  return left;
+}
+function packRects(items, maxSize = 2048, padding = 1) {
+  const placements = new Array(items.length);
+  const pages = [];
+  let remaining = items.map((_, i) => i).sort((a, b) => items[b].height - items[a].height || items[b].width - items[a].width);
+  for (const i of remaining) {
+    const it = items[i];
+    if (it.width + padding * 2 > maxSize || it.height + padding * 2 > maxSize) {
+      throw new RangeError(`A ${it.width}x${it.height} item doesn't fit a ${maxSize} page`);
+    }
+  }
+  while (remaining.length > 0) {
+    let area = 0;
+    let maxW = 0;
+    let maxH = 0;
+    for (const i of remaining) {
+      const it = items[i];
+      area += (it.width + padding * 2) * (it.height + padding * 2);
+      maxW = Math.max(maxW, it.width + padding * 2);
+      maxH = Math.max(maxH, it.height + padding * 2);
+    }
+    let packed = false;
+    for (let s = 64; s <= maxSize && !packed; s *= 2) {
+      for (const [w, h] of [
+        [s, s / 2],
+        [s, s]
+      ]) {
+        if (h < 32 || w * h < area || w < maxW || h < maxH || h > maxSize) continue;
+        const left2 = tryPack(items, remaining, w, h, padding, placements, pages.length, false);
+        if (left2.length === 0) {
+          pages.push({ width: w, height: h });
+          packed = true;
+          break;
+        }
+      }
+    }
+    if (packed) break;
+    const left = tryPack(
+      items,
+      remaining,
+      maxSize,
+      maxSize,
+      padding,
+      placements,
+      pages.length,
+      true
+    );
+    pages.push({ width: maxSize, height: maxSize });
+    remaining = left;
+  }
+  return { pages, placements };
+}
+export {
+  SkylinePacker,
+  packRects
+};

package/dist/texture.d.ts

@@ -0,0 +1,97 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type TranscodeTarget } from './basis.js';
+import { type TextureUsage } from './mips.js';
+/** GPU formats a Texture can hold. */
+export type TextureFormat = 'rgba8unorm' | 'rgba16float' | 'bc7-rgba-unorm' | 'bc5-rg-unorm' | 'astc-4x4-unorm' | 'etc2-rgba8unorm' | 'eac-rg11unorm';
+/** Bytes per 4x4 block for compressed formats; bytes per texel otherwise (as blockBytes, block 1). */
+export declare const FORMAT_INFO: Record<TextureFormat, {
+    block: number;
+    bytes: number;
+    srgbView?: string;
+}>;
+export interface TextureInit {
+    width: number;
+    height: number;
+    format?: TextureFormat;
+    usage?: TextureUsage;
+    /** Level data, level 0 first. With `mipmaps` and one RGBA8 level, the rest are generated. */
+    mips: Uint8Array[];
+    mipmaps?: boolean;
+    /** Keep CPU pixels after upload (default true for textures made in code). */
+    cpu?: boolean;
+    /** 6 for a cube map: each level holds the faces +X, -X, +Y, -Y, +Z, -Z one after another. */
+    faces?: number;
+    /**
+     * Layers of a 2D texture array (materials bind it as `texture_2d_array`): each level holds the
+     * layers one after another. Default 1.
+     */
+    layers?: number;
+    /** Color is already multiplied by alpha (sprites blend it as is). */
+    premultiplied?: boolean;
+}
+/**
+ * A texture on the CPU, ready to upload. The renderer uploads it on first use and whenever
+ * `version` changes; imported textures drop their CPU pixels after upload (`levels` becomes
+ * undefined) and reload from their artifact if the GPU device is lost.
+ */
+export declare class Texture {
+    width: number;
+    height: number;
+    format: TextureFormat;
+    usage: TextureUsage;
+    levels: Uint8Array[] | undefined;
+    mipCount: number;
+    keepCpu: boolean;
+    /** 1, or 6 for a cube map. */
+    faces: number;
+    /** Layers of a texture array (1 for a plain texture). */
+    layers: number;
+    version: number;
+    /**
+     * Made and written on the GPU (`Texture.gpu`): no CPU pixels, and the GPU copy can be bound as
+     * a storage texture so compute passes fill it.
+     */
+    gpuOnly: boolean;
+    /** Color is already multiplied by alpha. */
+    premultiplied: boolean;
+    constructor(init: Required<Omit<TextureInit, 'mipmaps' | 'faces' | 'premultiplied' | 'layers'>> & {
+        faces?: number;
+        layers?: number;
+        premultiplied?: boolean;
+    });
+    static create(init: TextureInit): Texture;
+    /**
+     * A texture the GPU writes (a compute pass through a storage binding), with no CPU pixels: one
+     * level, `layers` array layers. Its GPU copy is made on first use and kept (see GpuAssets.texture).
+     */
+    static gpu(init: {
+        width: number;
+        height: number;
+        layers?: number;
+        format?: TextureFormat;
+        usage?: TextureUsage;
+    }): Texture;
+    /** Replaces the pixels; bumps the version so the GPU copy re-uploads. */
+    update(init: Partial<TextureInit> & {
+        mips: Uint8Array[];
+    }): void;
+    /** GPU bytes for all levels. */
+    get byteSize(): number;
+    private static validate;
+}
+export declare const Textures: import("@aethervtt/shard-core").ResourceDef<AssetStore<Texture, "Texture">>;
+/** What the GPU can sample, set by the renderer once it has a device. Decides Basis transcoding. */
+export interface TextureCapabilities {
+    bc: boolean;
+    astc: boolean;
+    etc2: boolean;
+}
+export declare function setTextureCapabilities(next: TextureCapabilities): void;
+export declare function textureCapabilities(): TextureCapabilities;
+/** The best transcode target for a usage on this device. */
+export declare function transcodeTarget(usage: TextureUsage, caps?: TextureCapabilities): TranscodeTarget;
+/** Turns a KTX2 artifact into a Texture, transcoding Basis payloads for this device. */
+export declare function textureFromKtx2(bytes: Uint8Array, options?: {
+    cpu?: boolean;
+}): Promise<Texture>;
+export declare const TextureAssetType: import("@aethervtt/shard-assets").AssetTypeDef<Texture>;

package/dist/texture.js

@@ -0,0 +1,218 @@
+import { AssetStore, defineAssetType } from "@aethervtt/shard-assets";
+import { defineResource, ShardError } from "@aethervtt/shard-core";
+import { transcodeBasis } from "./basis.js";
+import { buildMips } from "./mips.js";
+const FORMAT_INFO = {
+  rgba8unorm: { block: 1, bytes: 4, srgbView: "rgba8unorm-srgb" },
+  rgba16float: { block: 1, bytes: 8 },
+  "bc7-rgba-unorm": { block: 4, bytes: 16, srgbView: "bc7-rgba-unorm-srgb" },
+  "bc5-rg-unorm": { block: 4, bytes: 16 },
+  "astc-4x4-unorm": { block: 4, bytes: 16, srgbView: "astc-4x4-unorm-srgb" },
+  "etc2-rgba8unorm": { block: 4, bytes: 16, srgbView: "etc2-rgba8unorm-srgb" },
+  "eac-rg11unorm": { block: 4, bytes: 16 }
+};
+class Texture {
+  width;
+  height;
+  format;
+  usage;
+  levels;
+  mipCount;
+  keepCpu;
+  /** 1, or 6 for a cube map. */
+  faces;
+  /** Layers of a texture array (1 for a plain texture). */
+  layers;
+  version = 0;
+  /**
+   * Made and written on the GPU (`Texture.gpu`): no CPU pixels, and the GPU copy can be bound as
+   * a storage texture so compute passes fill it.
+   */
+  gpuOnly = false;
+  /** Color is already multiplied by alpha. */
+  premultiplied;
+  constructor(init) {
+    this.width = init.width;
+    this.height = init.height;
+    this.format = init.format;
+    this.usage = init.usage;
+    this.levels = init.mips;
+    this.mipCount = init.mips.length;
+    this.keepCpu = init.cpu;
+    this.faces = init.faces ?? 1;
+    this.layers = init.layers ?? 1;
+    this.premultiplied = init.premultiplied ?? false;
+    Texture.validate(this);
+  }
+  static create(init) {
+    const format = init.format ?? "rgba8unorm";
+    const usage = init.usage ?? "color";
+    let mips = init.mips;
+    if (init.mipmaps && mips.length === 1 && format === "rgba8unorm" && (init.faces ?? 1) === 1 && (init.layers ?? 1) === 1) {
+      mips = buildMips(
+        { width: init.width, height: init.height, kind: "u8", data: mips[0] },
+        { usage, mipmaps: true, maxSize: 16384, flipY: false, premultiplyAlpha: false }
+      ).levels;
+    }
+    return new Texture({
+      width: init.width,
+      height: init.height,
+      format,
+      usage,
+      mips,
+      cpu: init.cpu ?? true,
+      faces: init.faces ?? 1,
+      layers: init.layers ?? 1,
+      premultiplied: init.premultiplied ?? false
+    });
+  }
+  /**
+   * A texture the GPU writes (a compute pass through a storage binding), with no CPU pixels: one
+   * level, `layers` array layers. Its GPU copy is made on first use and kept (see GpuAssets.texture).
+   */
+  static gpu(init) {
+    const t = new Texture({
+      width: init.width,
+      height: init.height,
+      format: init.format ?? "rgba8unorm",
+      usage: init.usage ?? "data",
+      mips: [],
+      cpu: false,
+      layers: init.layers ?? 1
+    });
+    t.levels = void 0;
+    t.mipCount = 1;
+    t.gpuOnly = true;
+    return t;
+  }
+  /** Replaces the pixels; bumps the version so the GPU copy re-uploads. */
+  update(init) {
+    const next = Texture.create({
+      width: init.width ?? this.width,
+      height: init.height ?? this.height,
+      format: init.format ?? this.format,
+      usage: init.usage ?? this.usage,
+      mips: init.mips,
+      mipmaps: init.mipmaps ?? this.mipCount > 1,
+      cpu: this.keepCpu,
+      faces: init.faces ?? this.faces,
+      layers: init.layers ?? this.layers,
+      premultiplied: init.premultiplied ?? this.premultiplied
+    });
+    this.width = next.width;
+    this.height = next.height;
+    this.format = next.format;
+    this.usage = next.usage;
+    this.levels = next.levels;
+    this.mipCount = next.mipCount;
+    this.faces = next.faces;
+    this.layers = next.layers;
+    this.premultiplied = next.premultiplied;
+    this.version++;
+  }
+  /** GPU bytes for all levels. */
+  get byteSize() {
+    const info = FORMAT_INFO[this.format];
+    let total = 0;
+    for (let l = 0; l < this.mipCount; l++) {
+      const w = Math.max(1, this.width >> l);
+      const h = Math.max(1, this.height >> l);
+      total += Math.ceil(w / info.block) * Math.ceil(h / info.block) * info.bytes;
+    }
+    return total * this.faces * this.layers;
+  }
+  static validate(t) {
+    const info = FORMAT_INFO[t.format];
+    if (!info)
+      throw new ShardError("texture/unsupported-format", `Unknown texture format "${t.format}"`);
+    t.levels?.forEach((level, l) => {
+      const w = Math.max(1, t.width >> l);
+      const h = Math.max(1, t.height >> l);
+      const expected = Math.ceil(w / info.block) * Math.ceil(h / info.block) * info.bytes * t.faces * t.layers;
+      if (level.byteLength < expected) {
+        throw new ShardError(
+          "texture/invalid",
+          `Level ${l} has ${level.byteLength} bytes; ${t.format} ${w}x${h} needs ${expected}`
+        );
+      }
+    });
+  }
+}
+const Textures = defineResource("texture/Textures", {
+  description: "Loaded textures by guid.",
+  init: () => new AssetStore("Texture")
+});
+let capabilities = { bc: false, astc: false, etc2: false };
+function setTextureCapabilities(next) {
+  capabilities = { ...next };
+}
+function textureCapabilities() {
+  return { ...capabilities };
+}
+function transcodeTarget(usage, caps = capabilities) {
+  if (usage === "normal")
+    return caps.bc ? "bc5" : caps.astc ? "astc" : caps.etc2 ? "eac-rg11" : "rgba8";
+  return caps.bc ? "bc7" : caps.astc ? "astc" : caps.etc2 ? "etc2" : "rgba8";
+}
+const TARGET_FORMAT = {
+  bc7: "bc7-rgba-unorm",
+  bc5: "bc5-rg-unorm",
+  astc: "astc-4x4-unorm",
+  etc2: "etc2-rgba8unorm",
+  "eac-rg11": "eac-rg11unorm",
+  rgba8: "rgba8unorm"
+};
+async function textureFromKtx2(bytes, options = {}) {
+  const { readKtx2 } = await import("./ktx2.js");
+  const ktx = readKtx2(bytes);
+  if (ktx.basis) {
+    const out = await transcodeBasis(bytes, transcodeTarget(ktx.usage));
+    return new Texture({
+      width: out.width,
+      height: out.height,
+      format: TARGET_FORMAT[out.format],
+      usage: ktx.usage,
+      mips: out.levels,
+      cpu: options.cpu ?? false,
+      premultiplied: ktx.premultiplied
+    });
+  }
+  const format = ktx.usage === "hdr" ? "rgba16float" : "rgba8unorm";
+  return new Texture({
+    width: ktx.width,
+    height: ktx.height,
+    format,
+    usage: ktx.usage,
+    mips: ktx.levels,
+    cpu: options.cpu ?? false,
+    faces: ktx.faces,
+    layers: ktx.layers,
+    premultiplied: ktx.premultiplied
+  });
+}
+const TextureAssetType = defineAssetType("Texture", {
+  store: Textures,
+  load: (artifact) => textureFromKtx2(artifact.bytes),
+  update: (existing, next) => {
+    existing.width = next.width;
+    existing.height = next.height;
+    existing.format = next.format;
+    existing.usage = next.usage;
+    existing.levels = next.levels;
+    existing.mipCount = next.mipCount;
+    existing.faces = next.faces;
+    existing.layers = next.layers;
+    existing.premultiplied = next.premultiplied;
+    existing.version++;
+  }
+});
+export {
+  FORMAT_INFO,
+  Texture,
+  TextureAssetType,
+  Textures,
+  setTextureCapabilities,
+  textureCapabilities,
+  textureFromKtx2,
+  transcodeTarget
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aethervtt/shard-texture",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "vendor",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@jsquash/webp": "^1.5.0",
+    "@aethervtt/shard-assets": "0.0.1",
+    "@aethervtt/shard-core": "0.0.1",
+    "fzstd": "^0.1.1",
+    "jpeg-js": "^0.4.4",
+    "ktx-parse": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/texture"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}