@codexo/exojs 0.12.0 → 0.13.0

package/dist/esm/rendering/sprite/repeatingSpritePlan.js

@@ -0,0 +1,156 @@
+import { planRepeat } from '../texture/repeat.js';
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+const validRepeatModes = new Set(['stretch', 'repeat', 'mirror-repeat']);
+const validRepeatFits = new Set(['clip', 'round']);
+function validateSizeInput(width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height)) {
+        throw new Error(`RepeatingSprite: width and height must be finite numbers (got ${width}, ${height}).`);
+    }
+    if (width < 0) {
+        throw new Error(`RepeatingSprite: width must be non-negative (got ${width}).`);
+    }
+    if (height < 0) {
+        throw new Error(`RepeatingSprite: height must be non-negative (got ${height}).`);
+    }
+}
+function validateMode(mode, label) {
+    if (typeof mode !== 'string' || !validRepeatModes.has(mode)) {
+        throw new Error(`RepeatingSprite: ${label} must be "stretch", "repeat", or "mirror-repeat" (got ${String(mode)}).`);
+    }
+}
+function validateFit(fit, label) {
+    if (typeof fit !== 'string' || !validRepeatFits.has(fit)) {
+        throw new Error(`RepeatingSprite: ${label} must be "clip" or "round" (got ${String(fit)}).`);
+    }
+}
+function validateOffset(value, label) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`RepeatingSprite: ${label} must be a finite number (got ${value}).`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shader-path tiling helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute the UV tiling scale for the standalone shader path.
+ *
+ * Returns how many times the source repeats across the destination span.
+ * - `stretch`: always 1.0
+ * - `repeat`/`mirror-repeat` + `round`: nearest integer count (≥ 1)
+ * - `repeat`/`mirror-repeat` + `clip`: exact fraction `destLen / srcLen`
+ * @internal
+ */
+function computeShaderTiling(srcLen, destLen, mode, fit) {
+    if (mode === 'stretch' || srcLen <= 0 || destLen <= 0) {
+        return 1;
+    }
+    if (fit === 'round') {
+        return Math.max(1, Math.round(destLen / srcLen));
+    }
+    return destLen / srcLen;
+}
+// ---------------------------------------------------------------------------
+// Geometry-path quad builder
+// ---------------------------------------------------------------------------
+const halfTexelInset = 0.5;
+/**
+ * Build the geometry quads for the atlas-region repeat path.
+ *
+ * Runs {@link planRepeat} independently on both X and Y axes with optional
+ * phase offsets, then generates the Cartesian-product quad list.  Each quad
+ * carries UV coordinates clamped inside the region's UV bounds, with
+ * extrusion-aware outer insets.
+ * @internal
+ */
+function buildRepeatingSpriteQuads(region, width, height, modeX, modeY, fitX, fitY, offsetX, offsetY) {
+    if (width === 0 || height === 0 || region.width <= 0 || region.height <= 0) {
+        return [];
+    }
+    const tw = region.texture.width;
+    const th = region.texture.height;
+    const ext = region.extrusion;
+    const outerInsetU = (ext.left > 0 || ext.right > 0) ? 0 : halfTexelInset / tw;
+    const outerInsetV = (ext.top > 0 || ext.bottom > 0) ? 0 : halfTexelInset / th;
+    const uMin = region.u0 + outerInsetU;
+    const uMax = region.u1 - outerInsetU;
+    const vMin = region.v0 + outerInsetV;
+    const vMax = region.v1 - outerInsetV;
+    const srcW = region.width;
+    const srcH = region.height;
+    const uRange = uMax - uMin;
+    const vRange = vMax - vMin;
+    const segsX = buildAxisSegmentsWithOffset(srcW, width, modeX, fitX, offsetX);
+    const segsY = buildAxisSegmentsWithOffset(srcH, height, modeY, fitY, offsetY);
+    const quads = [];
+    for (const sy of segsY) {
+        const qy0 = sy.destinationStart;
+        const qy1 = sy.destinationStart + sy.destinationLength;
+        const qv0 = vMin + sy.sourceStart * vRange;
+        const qv1 = vMin + sy.sourceEnd * vRange;
+        for (const sx of segsX) {
+            const qx0 = sx.destinationStart;
+            const qx1 = sx.destinationStart + sx.destinationLength;
+            const qu0 = uMin + sx.sourceStart * uRange;
+            const qu1 = uMin + sx.sourceEnd * uRange;
+            quads.push({ x0: qx0, y0: qy0, x1: qx1, y1: qy1, u0: qu0, v0: qv0, u1: qu1, v1: qv1 });
+        }
+    }
+    return quads;
+}
+/**
+ * Build repeat segments for one axis with an optional phase offset.
+ *
+ * The offset shifts the starting phase of the repeat in source-pixel units.
+ * For `stretch` mode the offset is silently ignored.
+ *
+ * Implementation: generates a plan for `(destLen + phase)`, shifts all
+ * segment destinations back by `phase`, and clips to `[0, destLen]`.  This
+ * is correct for `clip` fit; for `round` fit the extended-span count may
+ * differ slightly from the zero-offset count — atlas scrolling is
+ * discouraged by design.
+ * @internal
+ */
+function buildAxisSegmentsWithOffset(srcLen, destLen, mode, fit, offset) {
+    if (destLen === 0 || srcLen <= 0) {
+        return [];
+    }
+    if (mode === 'stretch') {
+        return [...planRepeat(srcLen, destLen, mode, fit).segments];
+    }
+    const phase = ((offset % srcLen) + srcLen) % srcLen;
+    if (phase === 0) {
+        return [...planRepeat(srcLen, destLen, mode, fit).segments];
+    }
+    const extendedPlan = planRepeat(srcLen, destLen + phase, mode, fit);
+    const result = [];
+    for (const seg of extendedPlan.segments) {
+        const dStart = seg.destinationStart - phase;
+        const dEnd = dStart + seg.destinationLength;
+        if (dEnd <= 0 || dStart >= destLen) {
+            continue;
+        }
+        const clippedStart = Math.max(0, dStart);
+        const clippedEnd = Math.min(destLen, dEnd);
+        const clippedLen = clippedEnd - clippedStart;
+        if (clippedLen <= 0) {
+            continue;
+        }
+        const t0 = (clippedStart - dStart) / seg.destinationLength;
+        const t1 = (clippedEnd - dStart) / seg.destinationLength;
+        const srcRange = seg.sourceEnd - seg.sourceStart;
+        result.push({
+            destinationStart: clippedStart,
+            destinationLength: clippedLen,
+            sourceStart: seg.sourceStart + t0 * srcRange,
+            sourceEnd: seg.sourceStart + t1 * srcRange,
+            mirrored: seg.mirrored,
+        });
+    }
+    return result;
+}
+
+export { buildRepeatingSpriteQuads, computeShaderTiling, validateFit, validateMode, validateOffset, validateSizeInput };
+//# sourceMappingURL=repeatingSpritePlan.js.map

package/dist/esm/rendering/sprite/repeatingSpritePlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatingSpritePlan.js","sources":["../../../../../src/rendering/sprite/repeatingSpritePlan.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/texture/TextureRegion.d.ts

@@ -0,0 +1,100 @@
+import type { Texture } from './Texture';
+/**
+ * Per-edge extrusion/padding metadata for a {@link TextureRegion}.
+ *
+ * Describes the number of duplicated/extruded source texels available outside
+ * each logical edge so that linear filtering can sample safely without
+ * bleeding from neighbouring atlas regions.
+ * @stable
+ */
+export interface TextureRegionInsets {
+    /** Extrusion texels on the left edge (outside `x`). */
+    readonly left: number;
+    /** Extrusion texels on the top edge (outside `y`). */
+    readonly top: number;
+    /** Extrusion texels on the right edge (outside `x + width`). */
+    readonly right: number;
+    /** Extrusion texels on the bottom edge (outside `y + height`). */
+    readonly bottom: number;
+}
+/**
+ * Options passed to the {@link TextureRegion} constructor.
+ * @stable
+ */
+export interface TextureRegionOptions {
+    /** Left pixel coordinate of the region within the texture. */
+    readonly x: number;
+    /** Top pixel coordinate of the region within the texture. */
+    readonly y: number;
+    /** Width of the region in texture pixels. */
+    readonly width: number;
+    /** Height of the region in texture pixels. */
+    readonly height: number;
+    /**
+     * Number of duplicated/extruded source texels available outside each
+     * logical edge for safe linear filtering.
+     *
+     * A uniform `number` sets all four sides equally. Provide a
+     * {@link TextureRegionInsets} for per-side control.
+     *
+     * Defaults to `{ left: 0, top: 0, right: 0, bottom: 0 }`.
+     */
+    readonly extrusion?: number | TextureRegionInsets;
+}
+/**
+ * An immutable descriptor for a rectangular sub-region of a {@link Texture}.
+ *
+ * Stores the pixel-space source rectangle, pre-computed normalised UV bounds,
+ * and optional extrusion/padding metadata for atlas-safe linear filtering.
+ * Constructed once and reused across sprites, tile-sets, atlas lookups, and
+ * the scalable-sprite repeat planners.
+ *
+ * All region descriptor fields are stable after construction. Extrusion
+ * metadata is copied and frozen during construction — the caller retains no
+ * mutable reference to the stored object. The underlying {@link Texture}
+ * reference is stable, but the Texture's own lifecycle and sampler state
+ * remain owned by {@link Texture}.
+ *
+ * Texture dimensions **must** be known at construction time; a texture with
+ * zero dimensions will cause the constructor to throw.
+ *
+ * @example
+ * ```ts
+ * const region = new TextureRegion(texture, {
+ *   x: 32,  y: 16,
+ *   width: 64, height: 32,
+ * });
+ * ```
+ * @stable
+ */
+export declare class TextureRegion {
+    /** The underlying {@link Texture} this region belongs to. */
+    readonly texture: Texture;
+    /** Left edge of the region in texture pixels. */
+    readonly x: number;
+    /** Top edge of the region in texture pixels. */
+    readonly y: number;
+    /** Width of the region in texture pixels. */
+    readonly width: number;
+    /** Height of the region in texture pixels. */
+    readonly height: number;
+    /** Normalised left texture coordinate (U-min). */
+    readonly u0: number;
+    /** Normalised top texture coordinate (V-min). */
+    readonly v0: number;
+    /** Normalised right texture coordinate (U-max). */
+    readonly u1: number;
+    /** Normalised bottom texture coordinate (V-max). */
+    readonly v1: number;
+    /** Per-edge extrusion/padding metadata (engine-owned, frozen). */
+    readonly extrusion: Readonly<TextureRegionInsets>;
+    /**
+     * Create a new immutable region.
+     *
+     * @throws When coordinates or dimensions are non-finite, zero, negative, or
+     *         extend beyond the texture bounds, or when extrusion values are
+     *         invalid.
+     */
+    constructor(texture: Texture, options: TextureRegionOptions);
+}
+//# sourceMappingURL=TextureRegion.d.ts.map

package/dist/esm/rendering/texture/TextureRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextureRegion.d.ts","sourceRoot":"","sources":["../../../../src/rendering/texture/TextureRegion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;CACnD;AA0FD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACxB,6DAA6D;IAC7D,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC,iDAAiD;IACjD,SAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,SAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,kDAAkD;IAClD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B,kEAAkE;IAClE,SAAgB,SAAS,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAEzD;;;;;;OAMG;gBACgB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB;CA+BnE"}

package/dist/esm/rendering/texture/TextureRegion.js

@@ -0,0 +1,144 @@
+function isFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function normalizeExtrusion(extrusion) {
+    if (extrusion === undefined) {
+        return Object.freeze({
+            left: 0,
+            top: 0,
+            right: 0,
+            bottom: 0,
+        });
+    }
+    if (typeof extrusion === 'number') {
+        return Object.freeze({
+            left: extrusion,
+            top: extrusion,
+            right: extrusion,
+            bottom: extrusion,
+        });
+    }
+    // Copy caller-owned values into an engine-owned frozen object so that
+    // external mutation of the original never affects the region.
+    return Object.freeze({
+        left: extrusion.left,
+        top: extrusion.top,
+        right: extrusion.right,
+        bottom: extrusion.bottom,
+    });
+}
+function validateExtrusion(extrusion, x, y, width, height, textureWidth, textureHeight) {
+    const { left, top, right, bottom } = extrusion;
+    if (!isFinite(left) || !isFinite(top) || !isFinite(right) || !isFinite(bottom)) {
+        throw new Error(`TextureRegion extrusion values must be finite numbers (got left=${left}, top=${top}, right=${right}, bottom=${bottom}).`);
+    }
+    if (left < 0 || top < 0 || right < 0 || bottom < 0) {
+        throw new Error(`TextureRegion extrusion values must be non-negative (got left=${left}, top=${top}, right=${right}, bottom=${bottom}).`);
+    }
+    if (left > x || top > y || right > textureWidth - (x + width) || bottom > textureHeight - (y + height)) {
+        throw new Error(`TextureRegion extrusion exceeds available source texture bounds: left=${left} (>${x}), top=${top} (>${y}), ` +
+            `right=${right} (>${textureWidth - (x + width)}), bottom=${bottom} (>${textureHeight - (y + height)}).`);
+    }
+}
+function validateOptions(options, textureWidth, textureHeight) {
+    const { x, y, width, height } = options;
+    if (!isFinite(x) || !isFinite(y) || !isFinite(width) || !isFinite(height)) {
+        throw new Error(`TextureRegion coordinates and dimensions must be finite numbers (got x=${x}, y=${y}, width=${width}, height=${height}).`);
+    }
+    if (width <= 0 || height <= 0) {
+        throw new Error(`TextureRegion dimensions must be positive (got width=${width}, height=${height}).`);
+    }
+    if (textureWidth <= 0 || textureHeight <= 0) {
+        throw new Error(`Texture must have positive dimensions (got ${textureWidth}x${textureHeight}).`);
+    }
+    if (x < 0 || y < 0) {
+        throw new Error(`TextureRegion origin must be non-negative (got x=${x}, y=${y}).`);
+    }
+    if (x >= textureWidth || y >= textureHeight) {
+        throw new Error(`TextureRegion origin (${x}, ${y}) is outside texture bounds (${textureWidth}x${textureHeight}).`);
+    }
+    if (x + width > textureWidth) {
+        throw new Error(`TextureRegion right edge (${x + width}) exceeds texture width (${textureWidth}).`);
+    }
+    if (y + height > textureHeight) {
+        throw new Error(`TextureRegion bottom edge (${y + height}) exceeds texture height (${textureHeight}).`);
+    }
+}
+/**
+ * An immutable descriptor for a rectangular sub-region of a {@link Texture}.
+ *
+ * Stores the pixel-space source rectangle, pre-computed normalised UV bounds,
+ * and optional extrusion/padding metadata for atlas-safe linear filtering.
+ * Constructed once and reused across sprites, tile-sets, atlas lookups, and
+ * the scalable-sprite repeat planners.
+ *
+ * All region descriptor fields are stable after construction. Extrusion
+ * metadata is copied and frozen during construction — the caller retains no
+ * mutable reference to the stored object. The underlying {@link Texture}
+ * reference is stable, but the Texture's own lifecycle and sampler state
+ * remain owned by {@link Texture}.
+ *
+ * Texture dimensions **must** be known at construction time; a texture with
+ * zero dimensions will cause the constructor to throw.
+ *
+ * @example
+ * ```ts
+ * const region = new TextureRegion(texture, {
+ *   x: 32,  y: 16,
+ *   width: 64, height: 32,
+ * });
+ * ```
+ * @stable
+ */
+class TextureRegion {
+    /** The underlying {@link Texture} this region belongs to. */
+    texture;
+    /** Left edge of the region in texture pixels. */
+    x;
+    /** Top edge of the region in texture pixels. */
+    y;
+    /** Width of the region in texture pixels. */
+    width;
+    /** Height of the region in texture pixels. */
+    height;
+    /** Normalised left texture coordinate (U-min). */
+    u0;
+    /** Normalised top texture coordinate (V-min). */
+    v0;
+    /** Normalised right texture coordinate (U-max). */
+    u1;
+    /** Normalised bottom texture coordinate (V-max). */
+    v1;
+    /** Per-edge extrusion/padding metadata (engine-owned, frozen). */
+    extrusion;
+    /**
+     * Create a new immutable region.
+     *
+     * @throws When coordinates or dimensions are non-finite, zero, negative, or
+     *         extend beyond the texture bounds, or when extrusion values are
+     *         invalid.
+     */
+    constructor(texture, options) {
+        if (!texture) {
+            throw new Error('TextureRegion requires a non-null Texture.');
+        }
+        const textureWidth = texture.width;
+        const textureHeight = texture.height;
+        validateOptions(options, textureWidth, textureHeight);
+        const extrusion = normalizeExtrusion(options.extrusion);
+        validateExtrusion(extrusion, options.x, options.y, options.width, options.height, textureWidth, textureHeight);
+        this.texture = texture;
+        this.x = options.x;
+        this.y = options.y;
+        this.width = options.width;
+        this.height = options.height;
+        this.u0 = options.x / textureWidth;
+        this.v0 = options.y / textureHeight;
+        this.u1 = (options.x + options.width) / textureWidth;
+        this.v1 = (options.y + options.height) / textureHeight;
+        this.extrusion = extrusion;
+    }
+}
+
+export { TextureRegion };
+//# sourceMappingURL=TextureRegion.js.map

package/dist/esm/rendering/texture/TextureRegion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextureRegion.js","sources":["../../../../../src/rendering/texture/TextureRegion.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/texture/repeat.d.ts

@@ -0,0 +1,96 @@
+/**
+ * How a scalable sprite fills its destination span.
+ *
+ * Shared by {@link NineSliceSprite} edges/center and {@link RepeatingSprite}.
+ * @stable
+ */
+export type RepeatMode = 'stretch' | 'repeat' | 'mirror-repeat';
+/**
+ * How a `'repeat'` or `'mirror-repeat'` run fits its destination span exactly.
+ * @stable
+ */
+export type RepeatFit = 'clip' | 'round';
+/**
+ * A single placement segment produced by the repeat planner.
+ *
+ * Each segment describes one contiguous destination slice and the corresponding
+ * normalised source texel interval.
+ * @advanced
+ */
+export interface RepeatSegment {
+    /** Start position of this segment within the destination span. */
+    readonly destinationStart: number;
+    /** Length of this segment in destination units. */
+    readonly destinationLength: number;
+    /**
+     * Normalised source start coordinate (0..1 range in logical source space).
+     * For mirrored segments this is greater than {@link sourceEnd}.
+     */
+    readonly sourceStart: number;
+    /**
+     * Normalised source end coordinate (0..1 range in logical source space).
+     * For mirrored segments this is less than {@link sourceStart}.
+     */
+    readonly sourceEnd: number;
+    /**
+     * `true` when this segment should be rendered with mirrored (flipped)
+     * orientation. Always consistent with `sourceStart > sourceEnd`.
+     */
+    readonly mirrored: boolean;
+}
+/**
+ * Result of a repeat-planning call.
+ *
+ * Contains the resolved destination length and the ordered list of segments
+ * that collectively fill the span.
+ * @advanced
+ */
+export interface RepeatPlan {
+    /** Total destination span length (equal to the requested length). */
+    readonly destinationLength: number;
+    /**
+     * The source length that was passed to the planner.
+     * Useful for consumers that need to map back to source scale.
+     */
+    readonly sourceLength: number;
+    /** Ordered, non-overlapping segments that fill the destination span. */
+    readonly segments: readonly RepeatSegment[];
+}
+/**
+ * Compute a deterministic repeat plan for filling a destination span with a
+ * tiled or stretched source pattern.
+ *
+ * This is a **pure, renderer-independent** function used as the shared repeat
+ * layout engine by {@link NineSliceSprite} edges/center,
+ * {@link RepeatingSprite} geometry path, and tilemap chunk builders.
+ *
+ * ## Modes
+ *
+ * | Mode             | Behaviour |
+ * |------------------|-----------|
+ * | `'stretch'`      | One segment stretched to the full destination. `fit` is ignored. |
+ * | `'repeat'`       | Native-size repeats; final segment is clipped when the destination is not an exact multiple. |
+ * | `'mirror-repeat'`| Alternating normal/mirrored segments (period-2). Clipped final segment when non-exact. |
+ *
+ * ## Fit
+ *
+ * | Fit      | Effect |
+ * |----------|--------|
+ * | `'clip'` | Native-size segments; the final segment is clipped if necessary. |
+ * | `'round'`| Integer count of equally-sized segments stretched or squeezed so the destination fills exactly. |
+ *
+ * ## Allocation and caching
+ *
+ * The planner returns a new result object on every call. Callers should
+ * cache the plan and recompute only when `sourceLength`, `destinationLength`,
+ * `mode`, or `fit` changes — typically on resize or texture change.
+ *
+ * @param sourceLength - Native size of the source pattern in destination units.
+ * @param destinationLength - Total span to fill.
+ * @param mode - Fill strategy.
+ * @param fit - Fitting strategy for `'repeat'` / `'mirror-repeat'`. Ignored for `'stretch'`.
+ * @throws When inputs are non-finite, negative, or zero-length source.
+ * @advanced
+ */
+export declare function planRepeat(sourceLength: number, destinationLength: number, mode: RepeatMode, fit?: RepeatFit): RepeatPlan;
+//# sourceMappingURL=repeat.d.ts.map

package/dist/esm/rendering/texture/repeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../../../src/rendering/texture/repeat.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,QAAQ,GACR,eAAe,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,OAAO,CAAC;AAEZ;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AA+HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,UAAU,EAChB,GAAG,GAAE,SAAmB,GACvB,UAAU,CA2BZ"}