@hypersoniclabs/helix-cli 0.1.25-helix3.508 → 0.1.25-helix3.511

package/dist/itemLod/atlas.d.ts

@@ -0,0 +1,223 @@
+import type { ItemModel, ModelGroup, ModelImage, ModelMaterial, ModelTextureRef } from './model';
+import { type MipChain, type UvRegion } from './mips';
+/**
+ * The material atlas of item-lod/1. A level draws every material of the item with at most one primitive per render state
+ * (opaque or alpha-blended, lit or unlit), because the runtime pays one draw call per primitive per placement band.
+ *
+ * Every source material becomes a "recipe": the texels and factors that decide its surface. Materials with the same recipe
+ * share one rectangle of the atlas. A rectangle holds the part of each source texture the material's UVs actually use (its
+ * footprint), already multiplied by the material's factors (base colour factor, metallic and roughness factors, normal
+ * scale, emissive factor and strength), so one set of atlas textures and one material per primitive reproduces them all.
+ * Vertex UVs are remapped affinely into their rectangle. Materials that repeat a texture a few times bake the repeats into
+ * the rectangle; materials that repeat it too finely for the atlas to resolve fall back to the texture's mean colour, which
+ * is what a mipmapped texture shows at that distance anyway. A material with no texture is a 4 x 4 swatch.
+ */
+/** Gutter around a textured rectangle, in atlas pixels at the colour resolution (the mip chain reaches it at level 2). */
+export declare const GUTTER_LOD1 = 4, GUTTER_LOD2 = 2;
+/** A rectangle is at least this many pixels on a side (one compression block). */
+export declare const MIN_RECT = 4;
+/** Tiled footprints larger than this many repeats (in total, or along one axis) fold to the mean colour. */
+export declare const MAX_TILE_CELLS = 36, MAX_TILE_AXIS = 12;
+export declare class AtlasOverflowError extends Error {
+    constructor(detail: string);
+}
+export interface PackItem {
+    id: number;
+    w: number;
+    h: number;
+}
+export interface PackedItem {
+    id: number;
+    x: number;
+    y: number;
+}
+/**
+ * Shelf packing, tallest first. Deterministic: ties break on width then id. Returns null when the items do not fit.
+ */
+export declare function packRects(items: readonly PackItem[], width: number, height: number): PackedItem[] | null;
+export interface RectRequest {
+    id: number;
+    /** Footprint in source texels (0 for a swatch). */
+    fullW: number;
+    fullH: number;
+    swatch: boolean;
+    /** Surface area (square metres) the recipe covers at this level. */
+    area: number;
+}
+export interface AtlasRect {
+    id: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    gutter: number;
+}
+export interface AtlasLayout {
+    width: number;
+    height: number;
+    rects: AtlasRect[];
+    gutter: number;
+    edge: number;
+}
+/**
+ * Chooses rectangle sizes and positions for an atlas of at most `edge` x `edge` pixels. Texel density is uniform across
+ * recipes (so the surface area a recipe covers decides its share) and capped at each recipe's own source resolution; the
+ * highest density that packs wins, in the smallest power-of-two box that holds the result.
+ */
+export declare function layoutAtlas(requests: readonly RectRequest[], edge: number): AtlasLayout;
+export type AtlasSlot = 'baseColor' | 'metallicRoughness' | 'normal' | 'emissive';
+type Transform = NonNullable<ModelTextureRef['transform']>;
+/** What a material samples and how: the UV set, transform and wrap shared by all of its textures. */
+export interface UvMapping {
+    texCoord: number;
+    transform?: Transform;
+    wrapS: number;
+    wrapT: number;
+}
+export type AlphaClass = 'OPAQUE' | 'MASK' | 'BLEND';
+export type FootprintClass = 'plain' | 'tiled' | 'mean' | 'swatch';
+/** A material reduced to the properties that decide its texels. */
+export interface ResolvedMaterial {
+    index: number;
+    mapping: UvMapping | null;
+    alpha: AlphaClass;
+    cutoff: number;
+    base: {
+        image: ModelImage | null;
+        factor: [number, number, number, number];
+    };
+    mr: {
+        image: ModelImage | null;
+        roughness: number;
+        metallic: number;
+    };
+    occlusion: {
+        image: ModelImage;
+        strength: number;
+    } | null;
+    normal: {
+        image: ModelImage;
+        scale: number;
+    } | null;
+    emissive: {
+        image: ModelImage | null;
+        factor: [number, number, number];
+        strength: number;
+    } | null;
+    notes: string[];
+}
+export declare function resolveMaterial(material: ModelMaterial): ResolvedMaterial;
+/** Everything that decides a material's texels except where on the texture it reads (which is the footprint) and how its UVs are transformed. */
+export declare function bakeKey(material: ResolvedMaterial): string;
+/** A material's UVs in the space of its texture: the UV set and KHR_texture_transform applied. Null when the group has no such set. */
+export declare function effectiveUv(group: ModelGroup, mapping: UvMapping | null): Float32Array | null;
+export interface Footprint {
+    u0: number;
+    u1: number;
+    v0: number;
+    v1: number;
+    repeatsU: number;
+    repeatsV: number;
+    klass: FootprintClass;
+}
+/** The part of the texture a set of UVs reads, and whether it is a plain crop, a small tiling, or a tiling too fine to keep. */
+export declare function footprintOf(bounds: {
+    u0: number;
+    u1: number;
+    v0: number;
+    v1: number;
+} | null, mapping: UvMapping | null): Footprint;
+export interface Recipe {
+    id: number;
+    key: string;
+    /** Resolved material every other member of the recipe agrees with. */
+    material: ResolvedMaterial;
+    klass: FootprintClass;
+    footprint: UvRegion;
+    /** Footprint in source texels of the sharpest image; the rectangle is never sized beyond it. */
+    fullW: number;
+    fullH: number;
+    area: number;
+    /** Source material indices in this recipe. */
+    members: number[];
+    /** Roughness and metalness this recipe averages to, for levels that drop the metallic-roughness map. */
+    meanMr: {
+        roughness: number;
+        metallic: number;
+    };
+    /** Source images that feed each atlas texture, and their byte total (the never-larger limit). */
+    sourceImages: Record<AtlasSlot, ModelImage[]>;
+}
+export interface BucketPlan {
+    alphaMode: AlphaClass;
+    doubleSided: boolean;
+    unlit: boolean;
+    group: ModelGroup;
+    /** Source material indices drawn by this primitive. */
+    materials: number[];
+    /** Recipes (atlas mode) in this bucket, with the surface area each covers. */
+    recipes: Array<{
+        recipe: number;
+        area: number;
+    }>;
+}
+export interface AtlasPlan {
+    layout: AtlasLayout;
+    recipes: Recipe[];
+    needs: {
+        normal: boolean;
+        metallicRoughness: boolean;
+        occlusion: boolean;
+        emissive: boolean;
+    };
+    /** The strength the baked emissive texels are divided by (the largest among emitting recipes). */
+    emissiveStrength: number;
+    /** Roughness and metalness shared by every recipe when no map is needed. */
+    constantMr: {
+        roughness: number;
+        metallic: number;
+    };
+    folded: number;
+}
+export interface LevelPlan {
+    kind: 'direct' | 'atlas';
+    buckets: BucketPlan[];
+    atlas: AtlasPlan | null;
+    /** Direct mode: the source material each bucket is written from. */
+    direct?: Array<{
+        material: number;
+    }>;
+    notes: string[];
+}
+export interface PlanContext {
+    /** Mip chain of a source image (decoded once per compile). */
+    chain(image: ModelImage): Promise<MipChain>;
+    /** Pixel size of a source image. */
+    size(image: ModelImage): Promise<{
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * Plans how a level's groups are drawn: one primitive per render state, with the material atlas that lets them share one
+ * material set. `edge` is the atlas edge cap (512 at LOD1, 256 at LOD2).
+ */
+export declare function planLevel(model: ItemModel, allGroups: readonly ModelGroup[], edge: number, context: PlanContext): Promise<LevelPlan>;
+export interface BakeContext {
+    chain(image: ModelImage): Promise<MipChain>;
+}
+/**
+ * Renders one atlas texture. `shrink` (1 or 0.5) scales the whole layout, for data maps kept at half the colour resolution.
+ */
+export declare function bakeAtlasSlot(plan: AtlasPlan, slot: AtlasSlot, shrink: number, context: BakeContext): Promise<{
+    data: Uint8Array;
+    width: number;
+    height: number;
+}>;
+/**
+ * Per-pixel weights for judging an encoded atlas texture: a pixel counts for the surface its rectangle is drawn on, shared by
+ * the rectangle's pixels, so a small palette strip that paints most of a vehicle is judged as the large area it is. Unused
+ * pixels weigh nothing. Same geometry as `bakeAtlasSlot`.
+ */
+export declare function atlasPixelWeights(plan: AtlasPlan, shrink: number): Float32Array;
+export {};