@galacean/effects-plugin-model 1.2.1 → 2.0.0-alpha.0

package/dist/runtime/animation.d.ts

@@ -1,33 +1,86 @@
-import type { Geometry, Engine } from '@galacean/effects';
+import type { Geometry, Engine, VFXItemContent, VFXItem } from '@galacean/effects';
 import { Texture } from '@galacean/effects';
 import type { ModelSkinOptions, ModelAnimTrackOptions, ModelAnimationOptions, ModelTreeOptions } from '../index';
 import { Matrix4 } from './math';
 import { PObject } from './object';
 import type { PSceneManager } from './scene';
-import type { ModelTreeVFXItem } from '../plugin';
+/**
+ * 纹理数据模式，包含浮点和半精度浮点
+ */
 export declare enum TextureDataMode {
     none = 0,
     float = 1,
     half_float = 2
 }
+/**
+ * 蒙皮类，支持蒙皮动画
+ */
 export declare class PSkin extends PObject {
-    parentItem?: ModelTreeVFXItem;
+    /**
+     * 场景树父元素
+     */
+    parentItem?: VFXItem<VFXItemContent>;
+    /**
+     * 骨骼索引
+     */
     skeleton: number;
+    /**
+     * 关节索引
+     */
     jointList: number[];
+    /**
+     * 逆绑定矩阵
+     */
     inverseBindMatrices: Matrix4[];
+    /**
+     * 动画矩阵
+     */
     animationMatrices: Matrix4[];
+    /**
+     * 纹理数据模式
+     */
     textureDataMode: TextureDataMode;
-    create(options: ModelSkinOptions, engine: Engine, parentItem?: ModelTreeVFXItem): void;
+    /**
+     * 创建蒙皮对象
+     * @param options - 蒙皮相关数据
+     * @param engine - 引擎对象
+     * @param parentItem - 场景树父元素
+     */
+    create(options: ModelSkinOptions, engine: Engine, parentItem?: VFXItem<VFXItemContent>): void;
+    /**
+     * 更新蒙皮矩阵
+     */
     updateSkinMatrices(): void;
+    /**
+     * 计算 Mesh 的动画矩阵
+     * @param worldMatrix - 世界矩阵
+     * @param matrixList - 矩阵列表
+     * @param normalMatList - 法线矩阵列表
+     */
     computeMeshAnimMatrices(worldMatrix: Matrix4, matrixList: Float32Array, normalMatList: Float32Array): void;
-    updateParentItem(parentItem: ModelTreeVFXItem): void;
+    /**
+     * 更新父元素
+     * @param parentItem - 场景树父元素
+     */
+    updateParentItem(parentItem: VFXItem<VFXItemContent>): void;
+    /**
+     * 获取关节点数
+     * @returns
+     */
     getJointCount(): number;
+    /**
+     * 是否纹理数据模式
+     * @returns
+     */
     isTextureDataMode(): boolean;
+    /**
+     * 销毁
+     */
     dispose(): void;
     private getTextureDataMode;
 }
 /**
- * Morph 动画状态：
+ * Morph 动画类
  * 保存了动画状态相关的数据，包括 weights 数组数据
  * 增加了状态数据的检查，保证数据的正确性
  * Morph 动画非常消耗内存，谨慎使用。
@@ -57,28 +110,25 @@ export declare class PMorph extends PObject {
     hasTangentMorph: boolean;
     /**
      * 通过 Geometry 数据创建 Morph 动画相关状态，并进行必要的正确性检查
-     *
-     * @param geometry - Mesh 的几何对象，是否包含 Morph 动画都是可以的
+     * @param geometry - Mesh 的几何体，是否包含 Morph 动画都是可以的
+     * @returns 是否创建成功
      */
     create(geometry: Geometry): boolean;
     dispose(): void;
     /**
      * 初始化 Morph target 的权重数组
-     *
      * @param weights - glTF Mesh 的权重数组，长度必须严格一致
      */
     initWeights(weights: number[]): void;
     /**
      * 当前状态是否有 Morph 动画：
      * 需要判断 weights 数组长度，以及 Position、Normal 和 Tangent 是否有动画
-     *
      * @returns 返回是否有 Morph 动画
      */
     hasMorph(): boolean;
     /**
      * 两个 Morph 动画状态是否相等：
      * 这里只比较初始状态是否一样，不考虑 weights 数组的情况，提供给 Mesh 进行 Geometry 检查使用
-     *
      * @param morph - Morph 动画状态对象
      * @returns 返回两个 Morph 动画状态是否相等
      */
@@ -87,7 +137,6 @@ export declare class PMorph extends PObject {
     /**
      * 统计 Geometry 中 Attribute 名称个数：
      * 主要用于统计 Morph 动画中新增的 Attribute 名称的个数，会作为最终的 weights 数组长度使用
-     *
      * @param attributeNameList - Attribute 名数组列表，只与 Morph Target 中的属性有关
      * @param geometry - Geometry 对象，是否有 Morph 动画都可以
      * @returns 存在的 Attribute 名称数目
@@ -106,28 +155,72 @@ export declare class PMorph extends PObject {
      */
     private static tangentNameList;
 }
+/**
+ * 动画插值类型
+ */
 export declare enum PAnimInterpType {
     linear = 0,
     step = 1,
     cubicSpline = 2
 }
+/**
+ * 动画路径类型
+ */
 export declare enum PAnimPathType {
     translation = 0,
     rotation = 1,
     scale = 2,
     weights = 3
 }
+/**
+ * 动画轨道类
+ */
 export declare class PAnimTrack {
+    /**
+     * 节点索引
+     */
     node: number;
+    /**
+     * 时间数组
+     */
     timeArray: Float32Array;
+    /**
+     * 数据数组
+     */
     dataArray: Float32Array;
+    /**
+     * 路径类型
+     */
     path: PAnimPathType;
+    /**
+     * 插值类型
+     */
     interp: PAnimInterpType;
+    /**
+     * 分量
+     */
     component: number;
     private sampler?;
+    /**
+     * 创建动画轨道对象
+     * @param options - 动画轨道参数
+     */
     constructor(options: ModelAnimTrackOptions);
+    /**
+     * 销毁
+     */
     dispose(): void;
-    tick(time: number, treeItem: ModelTreeVFXItem, sceneManager?: PSceneManager): void;
+    /**
+     * 更新节点动画数据
+     * @param time - 当前播放时间
+     * @param treeItem - 节点树元素
+     * @param sceneManager - 3D 场景管理器
+     */
+    tick(time: number, treeItem: VFXItem<VFXItemContent>, sceneManager?: PSceneManager): void;
+    /**
+     * 获取动画结束时间
+     * @returns
+     */
     getEndTime(): number;
     /**
      * 生成 Mesh 元素的父节点
@@ -141,6 +234,9 @@ export declare class PAnimTrack {
     private getPathInfo;
     private getInterpInfo;
 }
+/**
+ * 动画纹理类
+ */
 export declare class PAnimTexture {
     private engine;
     private isHalfFloat;
@@ -149,20 +245,60 @@ export declare class PAnimTexture {
     private buffer?;
     private texture?;
     constructor(engine: Engine);
+    /**
+     * 创建动画纹理对象
+     * @param jointCount - 骨骼数目
+     * @param isHalfFloat - 是否半浮点精度
+     * @param name - 名称
+     */
     create(jointCount: number, isHalfFloat: boolean, name: string): void;
+    /**
+     * 更新动画数据
+     * @param buffer - 新的动画数据
+     */
     update(buffer: Float32Array): void;
+    /**
+     * 销毁
+     */
     dispose(): void;
+    /**
+     * 获取纹理大小
+     * @returns
+     */
     getSize(): number;
+    /**
+     * 获取纹理对象
+     * @returns
+     */
     getTexture(): Texture;
 }
+/**
+ * 动画类，负责动画数据创建、更新和销毁
+ */
 export declare class PAnimation extends PObject {
     private time;
     private duration;
     private tracks;
+    /**
+     * 创建动画对象
+     * @param options - 动画参数
+     */
     create(options: ModelAnimationOptions): void;
-    tick(time: number, treeItem: ModelTreeVFXItem, sceneManager?: PSceneManager): void;
+    /**
+     * 动画更新
+     * @param time - 当前时间
+     * @param treeItem - 场景树元素
+     * @param sceneManager - 3D 场景管理器
+     */
+    tick(time: number, treeItem: VFXItem<VFXItemContent>, sceneManager?: PSceneManager): void;
+    /**
+     * 销毁
+     */
     dispose(): void;
 }
+/**
+ * 动画管理类，负责管理动画对象
+ */
 export declare class PAnimationManager extends PObject {
     private ownerItem;
     private animation;
@@ -170,19 +306,36 @@ export declare class PAnimationManager extends PObject {
     private delay;
     private time;
     private animations;
-    private sceneManager;
-    constructor(treeOptions: ModelTreeOptions, ownerItem: ModelTreeVFXItem);
+    private sceneManager?;
+    /**
+     * 创建动画管理器
+     * @param treeOptions - 场景树参数
+     * @param ownerItem - 场景树所属元素
+     */
+    constructor(treeOptions: ModelTreeOptions, ownerItem: VFXItem<VFXItemContent>);
+    /**
+     * 设置场景管理器
+     * @param sceneManager - 场景管理器
+     */
+    setSceneManager(sceneManager: PSceneManager): void;
+    /**
+     * 创建动画对象
+     * @param animationOpts - 动画参数
+     * @returns 动画对象
+     */
     createAnimation(animationOpts: ModelAnimationOptions): PAnimation;
+    /**
+     * 动画更新
+     * @param deltaSeconds - 更新间隔
+     */
     tick(deltaSeconds: number): void;
+    /**
+     * 销毁
+     */
     dispose(): void;
-    getTreeItem(): ModelTreeVFXItem;
-}
-export declare class PAnimationSystem {
-    private engine;
-    private managers;
-    constructor(engine: Engine);
-    create(treeItems: ModelTreeVFXItem[]): void;
-    insert(animationManager: PAnimationManager): void;
-    delete(animationManager: PAnimationManager): void;
-    dispose(): void;
+    /**
+     * 获取场景树元素
+     * @returns
+     */
+    getTreeItem(): VFXItem<VFXItemContent>;
 }

package/dist/runtime/cache.d.ts

@@ -4,6 +4,9 @@ import type { ModelSkyboxOptions } from '../index';
 import type { FBOOptions } from '../utility/ri-helper';
 import type { PMaterialBase } from './material';
 import type { PSkyboxParams } from './skybox';
+/**
+ * 合成缓存类，负责管理插件 WebGL 相关资源加载和创建
+ */
 export declare class CompositionCache {
     private engine;
     private loadSkybox;
@@ -14,21 +17,93 @@ export declare class CompositionCache {
     private renderPassCache;
     private static brdfLutTexOptions?;
     private static skyboxOptions?;
+    /**
+     * 加载静态的纹理数据
+     * @returns
+     */
     static loadStaticResources(): Promise<void>;
+    /**
+     * 创建天空盒数据，如果传入的 params 为空，会使用内置的天空盒参数
+     * @param engine - 引擎
+     * @param params - 天空盒参数
+     * @returns 天空盒数据
+     */
     static genSkyboxOptions(engine: Engine, params?: PSkyboxParams): Promise<ModelSkyboxOptions>;
     constructor(engine: Engine);
+    /**
+     * 记录是否加载天空盒，缓存天空盒相关的查询纹理
+     * @param loadSkybox - 是否加载天空盒
+     */
     setup(loadSkybox: boolean): void;
+    /**
+     * 获取缓存的纹理对象
+     * @param name - 名称
+     * @returns 纹理对象
+     */
     getTexture(name: string): Texture | undefined;
+    /**
+     * 设置纹理对象缓存
+     * @param name - 名称
+     * @param tex - 纹理对象
+     */
     setTexture(name: string, tex: Texture): void;
+    /**
+     * 获取或者创建纹理对象
+     * @param name - 名称
+     * @param options - 纹理参数
+     * @returns 纹理对象
+     */
     getOrCreateTexture(name: string, options: TextureSourceOptions): Texture;
+    /**
+     * 根据名称删除纹理对象
+     * @param name - 名称
+     * @returns 是否删除成功
+     */
     deleteTexture(name: string): boolean;
+    /**
+     * 获取或者创建几何体
+     * @param name - 名称
+     * @param geomJson - 几何体参数
+     * @param bins - 几何体数据
+     * @returns 几何体
+     */
     getOrCreateGeometry(name: string, geomJson: spec.GeometryOptionsJSON, bins: ArrayBuffer[]): Geometry;
+    /**
+     * 获取滤波 Mesh
+     * @param name - 名称
+     * @param material - 材质
+     * @param uniformSemantics - Uniform 语义信息
+     * @returns
+     */
     getFilterMesh(name: string, material: PMaterialBase, uniformSemantics: Record<string, any>): Mesh;
     getShadowBasePass(name: string, priority: number, meshList: Mesh[], fboOptions: FBOOptions): RenderPass;
     getShadowFilterPass(name: string, priority: number, meshList: Mesh[], fboOptions: FBOOptions): RenderPass;
+    /**
+     * 获取渲染 Pass
+     * @param name - 名称
+     * @param priority - 优先级
+     * @param meshList - Mesh 列表
+     * @param fboOptions - FBO 参数
+     * @returns
+     */
     getRenderPass(name: string, priority: number, meshList: Mesh[], fboOptions: FBOOptions): RenderPass;
+    /**
+     * 销毁缓存，释放所有缓存的对象
+     */
     dispose(): void;
+    /**
+     * 获取所有的渲染 Pass
+     * @returns
+     */
     getRenderPasses(): RenderPass[];
+    /**
+     * 获取纹理对象，用户 IBL 渲染
+     * @returns
+     */
     getBrdfLutTexture(): Texture | undefined;
+    /**
+     * 获取天空盒参数
+     * @returns
+     */
     getSkyboxOptions(): ModelSkyboxOptions | undefined;
 }

package/dist/runtime/camera.d.ts

@@ -1,46 +1,171 @@
 import type { math } from '@galacean/effects';
 import { spec } from '@galacean/effects';
-import type { ModelVFXItem } from '../plugin/model-vfx-item';
-import type { ModelItemCamera } from '../index';
+import type { ModelCameraOptions } from '../index';
 import { Vector2, Vector3, Matrix4 } from './math';
 import { PEntity } from './object';
+import type { ModelCameraComponent } from '../plugin/model-item';
 type Box3 = math.Box3;
 type Quaternion = math.Quaternion;
+/**
+ * 相机类，支持基础的相机功能
+ */
 export declare class PCamera extends PEntity {
+    /**
+     * 所属的相机组件
+     */
+    owner?: ModelCameraComponent;
+    /**
+     * 画布宽度
+     */
     width: number;
+    /**
+     * 画布高度
+     */
     height: number;
+    /**
+     * 近裁剪平面
+     */
     nearPlane: number;
+    /**
+     * 远裁剪平面
+     */
     farPlane: number;
+    /**
+     * Y 轴上视角
+     */
     fovy: number;
+    /**
+     * 纵横比
+     */
     aspect: number;
+    /**
+     * 剪裁模式，默认是剪裁左右
+     */
     clipMode: spec.CameraClipMode;
+    /**
+     * 投影矩阵
+     */
     projectionMatrix: Matrix4;
+    /**
+     * 相机矩阵
+     */
     viewMatrix: Matrix4;
-    constructor(camera: ModelItemCamera, width: number, height: number, ownerItem?: ModelVFXItem);
+    /**
+     * 构造函数，创建相机对象
+     * @param camera - 相机数据
+     * @param width - 画布宽度
+     * @param height - 画布高度
+     * @param owner - 所属的相机组件
+     */
+    constructor(name: string, width: number, height: number, options: ModelCameraOptions, owner?: ModelCameraComponent);
+    /**
+     * 更新相机矩阵和投影矩阵，从所属的元素中获取变换数据
+     */
     update(): void;
+    /**
+     * 获取新的透视矩阵，视角大小乘 1.25 倍
+     * @param fov - 视角大小
+     * @returns 投影矩阵
+     */
     getNewProjectionMatrix(fov: number): Matrix4;
+    /**
+     * 计算视角中的包围盒大小
+     * @param box - 包围盒
+     * @returns 视角中的包围盒
+     */
     computeViewAABB(box: Box3): Box3;
+    /**
+     * 获取画布大小
+     * @returns
+     */
     getSize(): Vector2;
+    /**
+     * 是否剪裁上下
+     * @returns
+     */
     isReversed(): boolean;
+    /**
+     * 获取眼睛位置
+     * @returns
+     */
     getEye(): Vector3;
+    /**
+     * 设置眼睛位置
+     * @param val - 眼睛位置
+     */
     setEye(val: Vector3): void;
 }
+/**
+ * 相机管理类，负责管理场景中的 3D 相机对象
+ */
 export declare class PCameraManager {
     private winWidth;
     private winHeight;
     private cameraList;
     private defaultCamera;
     constructor();
+    /**
+     * 初始化画布大小，更新默认相机
+     * @param width - 画布宽度
+     * @param height - 画布高度
+     */
     initial(width: number, height: number): void;
-    insert(inCamera: ModelItemCamera, ownerItem?: ModelVFXItem): PCamera;
+    /**
+     * 插入相机数据，创建新的相机对象
+     * @param inCamera - 相机数据
+     * @param owner - 所属的相机组件
+     * @returns 新的相机对象
+     */
+    insert(name: string, options: ModelCameraOptions, owner?: ModelCameraComponent): PCamera;
+    /**
+     * 插入相机对象
+     * @param camera - 相机对象
+     */
     insertCamera(camera: PCamera): void;
+    /**
+     * 根据对象或者索引，删除相机对象
+     * @param camera - 索引或相机对象
+     */
     remove(camera: PCamera | number): void;
+    /**
+     * 销毁相机管理对象
+     */
     dispose(): void;
-    updateDefaultCamera(fovy: number, nearPlane: number, farPlane: number, position: Vector3, rotation: Quaternion, aspect: number, clipMode: number): void;
+    /**
+     * 更新默认相机状态，并计算新的透视和相机矩阵
+     * @param fovy - 视角
+     * @param aspect - 纵横比
+     * @param nearPlane - 近裁剪平面
+     * @param farPlane - 远裁剪平面
+     * @param position - 位置
+     * @param rotation - 旋转
+     * @param clipMode - 剪裁模式
+     */
+    updateDefaultCamera(fovy: number, aspect: number, nearPlane: number, farPlane: number, position: Vector3, rotation: Quaternion, clipMode: number): void;
+    /**
+     * 获取相机对象列表
+     * @returns
+     */
     getCameraList(): PCamera[];
+    /**
+     * 获取默认相机对象
+     * @returns
+     */
     getDefaultCamera(): PCamera;
+    /**
+     * 获取相机数目
+     * @returns
+     */
     getCameraCount(): number;
+    /**
+     * 获取激活的相机对象
+     * @returns
+     */
     getActiveCamera(): PCamera;
+    /**
+     * 获取画布纵横比
+     * @returns
+     */
     getAspect(): number;
 }
 export {};