bplinejs 0.0.101-beta.10

package/lib/Group/index.d.ts

@@ -0,0 +1,70 @@
+import { Mat3 } from "bpmatrixjs/Math/Mat3";
+import type { AddObject } from "../global-types";
+import ObjectNode from "../Object";
+import type { ObjectNodeLike } from "../Object";
+import type { SceneLike } from "../Scene";
+interface GroupLike extends ObjectNodeLike {
+    children: AddObject[];
+    add(child: AddObject): void;
+    removeSelf(): boolean;
+    removeChild(child: AddObject): boolean;
+    removeAll(): void;
+    updateWorldMatrix(): Mat3;
+}
+/**
+ * 组对象
+ * 用于组织子节点和维护基础变换信息
+ * @class
+ */
+declare class Group extends ObjectNode implements GroupLike {
+    /**
+     * 对象类型
+     */
+    readonly type: string;
+    /**
+     * 子节点列表
+     */
+    children: AddObject[];
+    /**
+     * 创建组对象
+     * @param x 初始位置 X
+     * @param y 初始位置 Y
+     */
+    constructor(x: number, y: number);
+    /**
+     * 添加子节点
+     * @param child 子节点对象
+     * @returns 无返回值
+     */
+    add(child: AddObject): void;
+    /**
+     * 从父组中删除当前节点。
+     * 当前节点没有父组时不进行处理。
+     * @returns 是否成功从父组中删除
+     */
+    removeSelf(): boolean;
+    /**
+     * 删除当前组中的一个直接子节点。
+     * @param child 需要删除的直接子节点
+     * @returns 是否找到并删除了该子节点
+     */
+    removeChild(child: AddObject): boolean;
+    /**
+     * 删除当前组中的全部直接子节点。
+     * @returns 无返回值
+     */
+    removeAll(): void;
+    /**
+     * 强制更新当前节点及子节点世界矩阵
+     * @returns Mat3
+     */
+    updateWorldMatrix(): Mat3;
+    /**
+     * 从当前节点沿父级查找所属场景。
+     * @param node 起始节点
+     * @returns 所属场景，未加入场景时返回 undefined
+     */
+    protected getScene(node: AddObject): SceneLike | undefined;
+}
+export default Group;
+export type { GroupLike };

package/lib/Group/index.js

@@ -0,0 +1,110 @@
+import ObjectNode from "../Object/index.js";
+import "bpmatrixjs/Math/Mat3";
+//#region src/scripts/Group/index.ts
+/**
+* 组对象
+* 用于组织子节点和维护基础变换信息
+* @class
+*/
+var Group = class extends ObjectNode {
+	/**
+	* 对象类型
+	*/
+	type = "Group";
+	/**
+	* 子节点列表
+	*/
+	children = [];
+	/**
+	* 创建组对象
+	* @param x 初始位置 X
+	* @param y 初始位置 Y
+	*/
+	constructor(x, y) {
+		super(x, y);
+	}
+	/**
+	* 添加子节点
+	* @param child 子节点对象
+	* @returns 无返回值
+	*/
+	add(child) {
+		if (child === this) throw new Error("Cannot add a group to itself or one of its descendants.");
+		let current = this.parent;
+		while (current !== null) {
+			if (current === child) throw new Error("Cannot add a group to itself or one of its descendants.");
+			current = current.parent;
+		}
+		if (child.parent === this && this.children.includes(child)) return;
+		if (child.parent !== null && "removeChild" in child.parent) child.parent.removeChild(child);
+		child.parent = this;
+		this.children.push(child);
+		const scene = this.getScene(child);
+		if (scene !== void 0) {
+			scene.addToLists(child);
+			scene.updateVersion();
+		}
+	}
+	/**
+	* 从父组中删除当前节点。
+	* 当前节点没有父组时不进行处理。
+	* @returns 是否成功从父组中删除
+	*/
+	removeSelf() {
+		const parent = this.parent;
+		if (parent === null || !("removeChild" in parent)) return false;
+		return parent.removeChild(this);
+	}
+	/**
+	* 删除当前组中的一个直接子节点。
+	* @param child 需要删除的直接子节点
+	* @returns 是否找到并删除了该子节点
+	*/
+	removeChild(child) {
+		const childIndex = this.children.indexOf(child);
+		if (childIndex === -1) return false;
+		const scene = this.getScene(this);
+		this.children.splice(childIndex, 1);
+		child.parent = null;
+		if (scene !== void 0) scene.removeFromLists(child);
+		return true;
+	}
+	/**
+	* 删除当前组中的全部直接子节点。
+	* @returns 无返回值
+	*/
+	removeAll() {
+		if (this.children.length === 0) return;
+		const scene = this.getScene(this);
+		for (const child of this.children) {
+			scene?.removeFromLists(child);
+			child.parent = null;
+		}
+		this.children.length = 0;
+	}
+	/**
+	* 强制更新当前节点及子节点世界矩阵
+	* @returns Mat3
+	*/
+	updateWorldMatrix() {
+		super.updateWorldMatrix();
+		for (const child of this.children) child.updateWorldMatrix();
+		return this.worldMatrix;
+	}
+	/**
+	* 从当前节点沿父级查找所属场景。
+	* @param node 起始节点
+	* @returns 所属场景，未加入场景时返回 undefined
+	*/
+	getScene(node) {
+		let current = node;
+		while (current !== null) {
+			if (current.type === "Scene") return current;
+			current = current.parent;
+		}
+	}
+};
+//#endregion
+export { Group as default };
+
+//# sourceMappingURL=index.js.map

package/lib/Group/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/scripts/Group/index.ts"],"sourcesContent":["import { Mat3 } from \"bpmatrixjs/Math/Mat3\";\nimport type { AddObject } from \"../global-types\";\nimport ObjectNode from \"../Object\";\nimport type { ObjectNodeLike } from \"../Object\";\nimport type { SceneLike } from \"../Scene\";\n\ninterface GroupLike extends ObjectNodeLike {\n    children: AddObject[];\n    add(child: AddObject): void;\n    removeSelf(): boolean;\n    removeChild(child: AddObject): boolean;\n    removeAll(): void;\n    updateWorldMatrix(): Mat3;\n}\n\n/**\n * 组对象\n * 用于组织子节点和维护基础变换信息\n * @class\n */\nclass Group extends ObjectNode implements GroupLike {\n    /**\n     * 对象类型\n     */\n    public readonly type: string = \"Group\";\n\n    /**\n     * 子节点列表\n     */\n    public children: AddObject[] = [];\n\n    /**\n     * 创建组对象\n     * @param x 初始位置 X\n     * @param y 初始位置 Y\n     */\n    public constructor(x: number, y: number) {\n        super(x, y);\n    }\n\n    /**\n     * 添加子节点\n     * @param child 子节点对象\n     * @returns 无返回值\n     */\n    public add(child: AddObject): void {\n        if (child === this) {\n            throw new Error(\"Cannot add a group to itself or one of its descendants.\");\n        }\n\n        let current: AddObject | null = this.parent;\n\n        // 禁止把自身或祖先作为子节点，否则 parent 链会形成死循环。\n        while (current !== null) {\n            if (current === child) {\n                throw new Error(\"Cannot add a group to itself or one of its descendants.\");\n            }\n\n            current = current.parent;\n        }\n\n        if (child.parent === this && this.children.includes(child)) {\n            return;\n        }\n\n        // 节点只能有一个父级，换父级前先从旧父级的 children 中移除。\n        if (child.parent !== null && \"removeChild\" in child.parent) {\n            (child.parent as GroupLike).removeChild(child);\n        }\n\n        child.parent = this;\n        this.children.push(child);\n        const scene: SceneLike | undefined = this.getScene(child);\n\n        if (scene !== undefined) {\n            scene.addToLists(child);\n            scene.updateVersion();\n        }\n    }\n\n    /**\n     * 从父组中删除当前节点。\n     * 当前节点没有父组时不进行处理。\n     * @returns 是否成功从父组中删除\n     */\n    public removeSelf(): boolean {\n        const parent: AddObject | null = this.parent;\n\n        if (parent === null || !(\"removeChild\" in parent)) {\n            return false;\n        }\n\n        const parentGroup: GroupLike = parent as GroupLike;\n        return parentGroup.removeChild(this);\n    }\n\n    /**\n     * 删除当前组中的一个直接子节点。\n     * @param child 需要删除的直接子节点\n     * @returns 是否找到并删除了该子节点\n     */\n    public removeChild(child: AddObject): boolean {\n        const childIndex: number = this.children.indexOf(child);\n\n        if (childIndex === -1) {\n            return false;\n        }\n\n        const scene: SceneLike | undefined = this.getScene(this);\n\n        this.children.splice(childIndex, 1);\n        child.parent = null;\n\n        if (scene !== undefined) {\n            scene.removeFromLists(child);\n        }\n\n        return true;\n    }\n\n    /**\n     * 删除当前组中的全部直接子节点。\n     * @returns 无返回值\n     */\n    public removeAll(): void {\n        if (this.children.length === 0) {\n            return;\n        }\n\n        const scene: SceneLike | undefined = this.getScene(this);\n\n        for (const child of this.children) {\n            scene?.removeFromLists(child);\n            child.parent = null;\n        }\n\n        this.children.length = 0;\n    }\n\n    /**\n     * 强制更新当前节点及子节点世界矩阵\n     * @returns Mat3\n     */\n    public updateWorldMatrix(): Mat3 {\n        super.updateWorldMatrix();\n\n        for (const child of this.children) {\n            child.updateWorldMatrix();\n        }\n        return this.worldMatrix;\n    }\n\n    /**\n     * 从当前节点沿父级查找所属场景。\n     * @param node 起始节点\n     * @returns 所属场景，未加入场景时返回 undefined\n     */\n    protected getScene(node: AddObject): SceneLike | undefined {\n        let current: AddObject | null = node;\n\n        while (current !== null) {\n            if (current.type === \"Scene\") {\n                return current as SceneLike;\n            }\n\n            current = current.parent;\n        }\n\n        return undefined;\n    }\n}\n\nexport default Group;\nexport type { GroupLike };\n"],"mappings":";;;;;;;;AAoBA,IAAM,QAAN,cAAoB,WAAgC;;;;CAIhD,OAA+B;;;;CAK/B,WAA+B,CAAC;;;;;;CAOhC,YAAmB,GAAW,GAAW;EACrC,MAAM,GAAG,CAAC;CACd;;;;;;CAOA,IAAW,OAAwB;EAC/B,IAAI,UAAU,MACV,MAAM,IAAI,MAAM,yDAAyD;EAG7E,IAAI,UAA4B,KAAK;EAGrC,OAAO,YAAY,MAAM;GACrB,IAAI,YAAY,OACZ,MAAM,IAAI,MAAM,yDAAyD;GAG7E,UAAU,QAAQ;EACtB;EAEA,IAAI,MAAM,WAAW,QAAQ,KAAK,SAAS,SAAS,KAAK,GACrD;EAIJ,IAAI,MAAM,WAAW,QAAQ,iBAAiB,MAAM,QAChD,MAAO,OAAqB,YAAY,KAAK;EAGjD,MAAM,SAAS;EACf,KAAK,SAAS,KAAK,KAAK;EACxB,MAAM,QAA+B,KAAK,SAAS,KAAK;EAExD,IAAI,UAAU,KAAA,GAAW;GACrB,MAAM,WAAW,KAAK;GACtB,MAAM,cAAc;EACxB;CACJ;;;;;;CAOA,aAA6B;EACzB,MAAM,SAA2B,KAAK;EAEtC,IAAI,WAAW,QAAQ,EAAE,iBAAiB,SACtC,OAAO;EAIX,OAAO,OAAY,YAAY,IAAI;CACvC;;;;;;CAOA,YAAmB,OAA2B;EAC1C,MAAM,aAAqB,KAAK,SAAS,QAAQ,KAAK;EAEtD,IAAI,eAAe,IACf,OAAO;EAGX,MAAM,QAA+B,KAAK,SAAS,IAAI;EAEvD,KAAK,SAAS,OAAO,YAAY,CAAC;EAClC,MAAM,SAAS;EAEf,IAAI,UAAU,KAAA,GACV,MAAM,gBAAgB,KAAK;EAG/B,OAAO;CACX;;;;;CAMA,YAAyB;EACrB,IAAI,KAAK,SAAS,WAAW,GACzB;EAGJ,MAAM,QAA+B,KAAK,SAAS,IAAI;EAEvD,KAAK,MAAM,SAAS,KAAK,UAAU;GAC/B,OAAO,gBAAgB,KAAK;GAC5B,MAAM,SAAS;EACnB;EAEA,KAAK,SAAS,SAAS;CAC3B;;;;;CAMA,oBAAiC;EAC7B,MAAM,kBAAkB;EAExB,KAAK,MAAM,SAAS,KAAK,UACrB,MAAM,kBAAkB;EAE5B,OAAO,KAAK;CAChB;;;;;;CAOA,SAAmB,MAAwC;EACvD,IAAI,UAA4B;EAEhC,OAAO,YAAY,MAAM;GACrB,IAAI,QAAQ,SAAS,SACjB,OAAO;GAGX,UAAU,QAAQ;EACtB;CAGJ;AACJ"}

package/lib/ID.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 获取全局唯一的递增对象 ID。
+ * @returns 新对象的 ID
+ */
+declare const GETID: () => number;
+export { GETID };

package/lib/ID.js

@@ -0,0 +1,15 @@
+//#region src/scripts/ID.ts
+var currentId = 0;
+/**
+* 获取全局唯一的递增对象 ID。
+* @returns 新对象的 ID
+*/
+var GETID = () => {
+	const id = currentId;
+	currentId += 1;
+	return id;
+};
+//#endregion
+export { GETID };
+
+//# sourceMappingURL=ID.js.map

package/lib/ID.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ID.js","names":[],"sources":["../src/scripts/ID.ts"],"sourcesContent":["let currentId = 0;\n\n/**\n * 获取全局唯一的递增对象 ID。\n * @returns 新对象的 ID\n */\nconst GETID = (): number => {\n    const id = currentId;\n    currentId += 1;\n    return id;\n};\n\nexport { GETID };\n"],"mappings":";AAAA,IAAI,YAAY;;;;;AAMhB,IAAM,cAAsB;CACxB,MAAM,KAAK;CACX,aAAa;CACb,OAAO;AACX"}

package/lib/IMesh/index.d.ts

@@ -0,0 +1,104 @@
+import type { VersionedMath } from "bpmatrixjs/Math";
+import Mesh from "../Mesh";
+import type { Geometry2d, Material2d } from "../global-types";
+import Raws, { Raw } from "../Raws";
+import type { RawChange, RawOptions, RawSubscriber } from "../Raws";
+import TextureLayers from "../Texture/Layers";
+/** 实例管理设置；raw 为构建时选择，避免丢失的原始值被误认为可以恢复。 */
+export interface IMeshOptions {
+    /** 保留原始值和订阅，默认 true，构建后不可切换。 */
+    raw?: boolean;
+    /** 初始槽数，默认 2，必须是正整数。 */
+    capacity?: number;
+    /** 扩容倍率，默认 2，必须是不小于 2 的整数。 */
+    growthFactor?: number;
+}
+/** 共用 Geometry / Material 的实例网格，每个槽位独立储存世界矩阵和样式。 */
+declare class IMesh extends Mesh implements RawSubscriber {
+    /** 对象类型；Scene 仍通过 Mesh 基类识别。 */
+    readonly type: string;
+    private readonly _raw;
+    private readonly _raws;
+    private _growthFactor;
+    private readonly _ids;
+    private readonly _pendingMatrices;
+    private readonly _pendingStyles;
+    private readonly _local;
+    private readonly _world;
+    private readonly _sources;
+    private readonly _textures;
+    private readonly _layerIndices;
+    private _layersPending;
+    /**
+     * @param data 共用几何模板，提前启用需要生成的分区
+     * @param material 共用管线和采样器设置，不接管其 Style
+     * @param options 默认管理原始值，容量 2，按 2 倍扩容
+     */
+    constructor(data: Geometry2d, material: Material2d, options?: IMeshOptions);
+    /** 是否保留并订阅原始值，只读。 */
+    get raw(): boolean;
+    /** 原始记录按稳定 ID 查询；raw=false 时 Map 为空。 */
+    get raws(): Raws;
+    /** 扩容倍率，默认 2；达到 100000 槽后每批追加 100000。 */
+    get growthFactor(): number;
+    /** @param value 不小于 2 的整数倍率，不改变已有记录 */
+    set growthFactor(value: number);
+    /** 已分配的槽数，不等于有效条数 count。 */
+    get capacity(): number;
+    /**
+     * 显式预留容量；不缩容、不丢弃记录。GPU 限制在 Render 上传前校验。
+     * @param value 不小于 count 的正整数
+     */
+    set capacity(value: number);
+    /** 三套独立图片层表；普通 Mesh 在相同绑定位置只使用一层。 */
+    get textures(): readonly TextureLayers[];
+    /**
+     * 按 push 顺序绘制，返回 ID 而非槽位。raw=false 冻结本次调用时的世界矩阵。
+     * @param options 原始值；省略 style 使用当前材质样式
+     * @returns 稳定 ID，通过 raws.map.get(id) 获取受管记录
+     */
+    push(options?: RawOptions): number;
+    /**
+     * 手动完整覆盖一个槽位，省略值使用默认值，不是局部 patch。
+     * raw=false 不建立订阅，按当前 IMesh 世界矩阵重新计算这个槽位。
+     * @param index 连续数组下标
+     * @param options 新的完整原始值
+     */
+    updateAt(index: number, options: RawOptions): void;
+    /**
+     * 变化只登记槽位；共享 Style 可以通知多个记录，不同步上传 GPU。
+     * @param record 来源记录
+     * @param change 变化区域
+     */
+    onRawChange(record: Raw, change: RawChange): void;
+    /**
+     * 只在受管模式下由父级世界矩阵变化安排全体矩阵重算。
+     * @param source 数学对象
+     * @param field 关联字段
+     */
+    onMathChange(source: VersionedMath, field: string): void;
+    /** 按待处理槽位打包，静止帧不重新分配数组；世界矩阵仅储存一份。 */
+    updateInstanceData(): void;
+    /** 清空记录并解绑，保留已分配 CPU 容量供后续 push 使用。 */
+    clear(): void;
+    /** 解除原始记录、贴图层表和资源订阅，不销毁共享几何、材质或图片。 */
+    dispose(): void;
+    /** @param count 即将使用的条数 */
+    private ensureCapacity;
+    /** @param options 完整输入 @returns 校验后的值，不保留临时默认对象 */
+    private resolve;
+    /** @param index 槽位 @param values 局部变换，输出只保存 world * local */
+    private writeMatrix;
+    /** @param index 槽位 @param style 样式 @param enabled 整条记录开关 */
+    private writeStyle;
+    /** @param index 槽位 @param style 只截取图片引用，不保留整个 Style */
+    private setSources;
+    /** 图片引用变化时才重建去重层表，避免反复换图后无限积累废弃层。 */
+    private updateTextureLayers;
+    /** @param index 将三套纹理层号写到样式最后一个 vec4 */
+    private writeLayers;
+    /** 拦截销毁后复用。 */
+    private assertActive;
+}
+export default IMesh;
+export type { RawOptions } from "../Raws";

package/lib/IMesh/index.js

@@ -0,0 +1,333 @@
+import { GETID } from "../ID.js";
+import { WriteStyleData } from "../Style/WriteStyleData.js";
+import Style from "../Style/index.js";
+import Mesh from "../Mesh/index.js";
+import Raws, { Raw } from "../Raws/index.js";
+import TextureLayers from "../Texture/Layers.js";
+import { Mat3, Vec2 } from "bpmatrixjs/Math";
+//#region src/scripts/IMesh/index.ts
+/** 共用 Geometry / Material 的实例网格，每个槽位独立储存世界矩阵和样式。 */
+var IMesh = class extends Mesh {
+	/** 对象类型；Scene 仍通过 Mesh 基类识别。 */
+	type = "IMesh";
+	_raw;
+	_raws = new Raws();
+	_growthFactor = 2;
+	_ids = [];
+	_pendingMatrices = /* @__PURE__ */ new Set();
+	_pendingStyles = /* @__PURE__ */ new Set();
+	_local = new Mat3();
+	_world = new Mat3();
+	_sources = [];
+	_textures = [
+		new TextureLayers(),
+		new TextureLayers(),
+		new TextureLayers()
+	];
+	_layerIndices = [
+		/* @__PURE__ */ new Map(),
+		/* @__PURE__ */ new Map(),
+		/* @__PURE__ */ new Map()
+	];
+	_layersPending = false;
+	/**
+	* @param data 共用几何模板，提前启用需要生成的分区
+	* @param material 共用管线和采样器设置，不接管其 Style
+	* @param options 默认管理原始值，容量 2，按 2 倍扩容
+	*/
+	constructor(data, material, options = {}) {
+		ValidateOptions(options);
+		super(data, material, false);
+		this._raw = options.raw ?? true;
+		this._count = 0;
+		this._capacity = 0;
+		this.growthFactor = options.growthFactor ?? 2;
+		try {
+			this.capacity = options.capacity ?? 2;
+		} catch (error) {
+			super.dispose();
+			throw error;
+		}
+	}
+	/** 是否保留并订阅原始值，只读。 */
+	get raw() {
+		return this._raw;
+	}
+	/** 原始记录按稳定 ID 查询；raw=false 时 Map 为空。 */
+	get raws() {
+		return this._raws;
+	}
+	/** 扩容倍率，默认 2；达到 100000 槽后每批追加 100000。 */
+	get growthFactor() {
+		return this._growthFactor;
+	}
+	/** @param value 不小于 2 的整数倍率，不改变已有记录 */
+	set growthFactor(value) {
+		if (!Number.isSafeInteger(value) || value < 2) throw new RangeError("growthFactor must be an integer >= 2.");
+		this._growthFactor = value;
+	}
+	/** 已分配的槽数，不等于有效条数 count。 */
+	get capacity() {
+		return this._capacity;
+	}
+	/**
+	* 显式预留容量；不缩容、不丢弃记录。GPU 限制在 Render 上传前校验。
+	* @param value 不小于 count 的正整数
+	*/
+	set capacity(value) {
+		this.assertActive();
+		if (!Number.isSafeInteger(value) || value < 1 || value < this._count) throw new RangeError("Invalid capacity.");
+		if (value <= this._capacity) return;
+		if (value > Math.floor(4294967295 / 176)) throw new RangeError("CPU array capacity exceeds 4 GiB.");
+		const matrices = new Float32Array(value * 12);
+		const styles = new Float32Array(value * 44);
+		matrices.set(this._matrixData.subarray(0, this._count * 12));
+		styles.set(this._styleData.subarray(0, this._count * 44));
+		this._matrixData = matrices;
+		this._styleData = styles;
+		this._capacity = value;
+		this._matrixVersion++;
+		this._styleVersion++;
+		this.updateVersion();
+	}
+	/** 三套独立图片层表；普通 Mesh 在相同绑定位置只使用一层。 */
+	get textures() {
+		this.updateTextureLayers();
+		return this._textures;
+	}
+	/**
+	* 按 push 顺序绘制，返回 ID 而非槽位。raw=false 冻结本次调用时的世界矩阵。
+	* @param options 原始值；省略 style 使用当前材质样式
+	* @returns 稳定 ID，通过 raws.map.get(id) 获取受管记录
+	*/
+	push(options = {}) {
+		this.assertActive();
+		const values = this.resolve(options);
+		this.ensureCapacity(this._count + 1);
+		this.ensureWorldMatrix();
+		const index = this._count;
+		const record = this._raw ? new Raw(index, values) : void 0;
+		const id = record?.id ?? GETID();
+		this._count++;
+		this._ids.push(id);
+		if (record !== void 0) {
+			this._raws.add(record);
+			record.add(this);
+		}
+		this.writeMatrix(index, values);
+		this.writeStyle(index, values.style, values.enabled);
+		this.setSources(index, values.style);
+		this._matrixVersion++;
+		this._styleVersion++;
+		this.updateVersion();
+		return id;
+	}
+	/**
+	* 手动完整覆盖一个槽位，省略值使用默认值，不是局部 patch。
+	* raw=false 不建立订阅，按当前 IMesh 世界矩阵重新计算这个槽位。
+	* @param index 连续数组下标
+	* @param options 新的完整原始值
+	*/
+	updateAt(index, options) {
+		this.assertActive();
+		if (!Number.isSafeInteger(index) || index < 0 || index >= this._count) throw new RangeError("Invalid slot index.");
+		const values = this.resolve(options);
+		const record = this._raws.map.get(this._ids[index]);
+		if (record !== void 0) {
+			record.position = values.position;
+			record.rotation = values.rotation;
+			record.scale = values.scale;
+			record.style = values.style;
+			record.enabled = values.enabled;
+		}
+		this.ensureWorldMatrix();
+		this.writeMatrix(index, values);
+		this.writeStyle(index, values.style, values.enabled);
+		this.setSources(index, values.style);
+		this._pendingMatrices.delete(index);
+		this._pendingStyles.delete(index);
+		this._matrixVersion++;
+		this._styleVersion++;
+		this.updateVersion();
+	}
+	/**
+	* 变化只登记槽位；共享 Style 可以通知多个记录，不同步上传 GPU。
+	* @param record 来源记录
+	* @param change 变化区域
+	*/
+	onRawChange(record, change) {
+		if (this._disposed || this._raws.map.get(record.id) !== record) return;
+		if (change === "matrix") this._pendingMatrices.add(record.index);
+		else if (change !== "textureData" && change !== "sampler") this._pendingStyles.add(record.index);
+		if (change === "texture") this.setSources(record.index, record.style);
+		this._materialPending = true;
+	}
+	/**
+	* 只在受管模式下由父级世界矩阵变化安排全体矩阵重算。
+	* @param source 数学对象
+	* @param field 关联字段
+	*/
+	onMathChange(source, field) {
+		super.onMathChange(source, field);
+		if (!this._raw && field === "worldMatrix") this._matrixPending = false;
+	}
+	/** 按待处理槽位打包，静止帧不重新分配数组；世界矩阵仅储存一份。 */
+	updateInstanceData() {
+		this.assertActive();
+		this.ensureWorldMatrix();
+		if (this._geometryPending && this.data !== void 0) this.material?.addGeometryType(this.data.type);
+		let matricesChanged = false;
+		let stylesChanged = false;
+		if (this._raw && this._matrixPending) {
+			for (const record of this._raws.map.values()) this.writeMatrix(record.index, record);
+			matricesChanged = this._count > 0;
+		} else for (const index of this._pendingMatrices) {
+			const record = this._raws.map.get(this._ids[index]);
+			if (record !== void 0) {
+				this.writeMatrix(index, record);
+				matricesChanged = true;
+			}
+		}
+		this.updateTextureLayers();
+		for (const index of this._pendingStyles) {
+			const record = this._raws.map.get(this._ids[index]);
+			if (record !== void 0) {
+				this.writeStyle(index, record.style, record.enabled);
+				stylesChanged = true;
+			}
+		}
+		if (matricesChanged) this._matrixVersion++;
+		if (stylesChanged) this._styleVersion++;
+		this._pendingMatrices.clear();
+		this._pendingStyles.clear();
+		this._matrixPending = false;
+		this._stylePending = false;
+		this._geometryPending = false;
+		this._materialPending = false;
+	}
+	/** 清空记录并解绑，保留已分配 CPU 容量供后续 push 使用。 */
+	clear() {
+		this.assertActive();
+		this._raws.clear();
+		this._count = 0;
+		this._ids.length = 0;
+		this._sources.length = 0;
+		this._pendingMatrices.clear();
+		this._pendingStyles.clear();
+		for (const texture of this._textures) texture.set([]);
+		for (const indices of this._layerIndices) indices.clear();
+		this._layersPending = false;
+		this._matrixVersion++;
+		this._styleVersion++;
+		this.updateVersion();
+		this.getScene(this)?.updateVersion();
+	}
+	/** 解除原始记录、贴图层表和资源订阅，不销毁共享几何、材质或图片。 */
+	dispose() {
+		if (this._disposed) return;
+		this.clear();
+		for (const texture of this._textures) texture.dispose();
+		super.dispose();
+	}
+	/** @param count 即将使用的条数 */
+	ensureCapacity(count) {
+		let capacity = this._capacity;
+		while (capacity < count) capacity = capacity < 1e5 ? Math.min(capacity * this._growthFactor, 1e5) : Math.ceil(count / 1e5) * 1e5;
+		if (capacity !== this._capacity) this.capacity = capacity;
+	}
+	/** @param options 完整输入 @returns 校验后的值，不保留临时默认对象 */
+	resolve(options) {
+		const values = {
+			position: options.position ?? new Vec2(),
+			rotation: options.rotation ?? 0,
+			scale: options.scale ?? new Vec2(1, 1),
+			style: options.style ?? this.material?.style ?? new Style(),
+			enabled: options.enabled ?? true
+		};
+		if (![
+			values.position.x,
+			values.position.y,
+			values.scale.x,
+			values.scale.y,
+			values.rotation
+		].every(Number.isFinite)) throw new RangeError("Transform components must be finite.");
+		return values;
+	}
+	/** @param index 槽位 @param values 局部变换，输出只保存 world * local */
+	writeMatrix(index, values) {
+		const c = Math.cos(values.rotation);
+		const s = Math.sin(values.rotation);
+		this._local.set([
+			c * values.scale.x,
+			s * values.scale.x,
+			0,
+			-s * values.scale.y,
+			c * values.scale.y,
+			0,
+			values.position.x,
+			values.position.y,
+			1
+		]);
+		this._world.mul(this.worldMatrix, this._local);
+		this._matrixData.set(this._world.GPUData, index * 12);
+	}
+	/** @param index 槽位 @param style 样式 @param enabled 整条记录开关 */
+	writeStyle(index, style, enabled) {
+		const offset = index * 44;
+		WriteStyleData(style, this._styleData, offset);
+		if (!enabled) this._styleData.fill(0, offset + 36, offset + 40);
+		this.writeLayers(index);
+	}
+	/** @param index 槽位 @param style 只截取图片引用，不保留整个 Style */
+	setSources(index, style) {
+		const previous = this._sources.at(index);
+		const next = [
+			style.solid.texture,
+			style.edge.texture,
+			style.points.texture
+		];
+		if (previous !== void 0 && next.every((texture, part) => texture === previous[part])) return;
+		this._sources[index] = next;
+		this._layersPending = true;
+		this.getScene(this)?.updateVersion();
+	}
+	/** 图片引用变化时才重建去重层表，避免反复换图后无限积累废弃层。 */
+	updateTextureLayers() {
+		if (!this._layersPending) return;
+		for (let part = 0; part < 3; part++) {
+			const indices = this._layerIndices[part];
+			const layers = [];
+			indices.clear();
+			for (const sources of this._sources) {
+				const texture = sources[part];
+				if (!indices.has(texture)) {
+					indices.set(texture, layers.length);
+					layers.push(texture);
+				}
+			}
+			this._textures[part].set(layers);
+		}
+		for (let index = 0; index < this._count; index++) this.writeLayers(index);
+		this._styleVersion++;
+		this._layersPending = false;
+	}
+	/** @param index 将三套纹理层号写到样式最后一个 vec4 */
+	writeLayers(index) {
+		for (let part = 0; part < 3; part++) this._styleData[index * 44 + 40 + part] = this._layerIndices[part].get(this._sources[index]?.[part]) ?? 0;
+	}
+	/** 拦截销毁后复用。 */
+	assertActive() {
+		if (this._disposed) throw new Error("Disposed IMesh cannot be reused.");
+	}
+};
+/** @param options 构建选项；不创建任何订阅或分配大数组 */
+var ValidateOptions = (options) => {
+	const capacity = options.capacity ?? 2;
+	const factor = options.growthFactor ?? 2;
+	if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > Math.floor(4294967295 / 176)) throw new RangeError("Invalid initial capacity.");
+	if (!Number.isSafeInteger(factor) || factor < 2) throw new RangeError("growthFactor must be an integer >= 2.");
+};
+//#endregion
+export { IMesh as default };
+
+//# sourceMappingURL=index.js.map