@galacean/effects-plugin-model 1.2.3 → 2.0.0-alpha.1

package/dist/runtime/mesh.d.ts

@@ -1,51 +1,106 @@
-import type { Geometry, Engine, math } from '@galacean/effects';
+import type { Geometry, Engine, math, VFXItemContent, VFXItem, Renderer } from '@galacean/effects';
 import { spec, Mesh, Material } from '@galacean/effects';
-import type { ModelItemMesh, ModelMaterialOptions, ModelPrimitiveOptions } from '../index';
-import { PShadowType } from './common';
+import type { ModelMeshContent, ModelMaterialOptions, ModelPrimitiveOptions } from '../index';
 import { PEntity } from './object';
 import type { PMaterial } from './material';
 import { Matrix4, Vector3, Box3 } from './math';
 import { PSkin, PMorph } from './animation';
-import type { PSceneStates } from './scene';
+import type { PSceneManager, PSceneStates } from './scene';
 import type { PSkybox } from './skybox';
-import type { PMaterialShadowBase, PShadowRuntimeOptions } from './shadow';
-import type { ModelVFXItem } from '../plugin/model-vfx-item';
 import { BoxMesh } from '../utility/ri-helper';
-import type { ModelTreeVFXItem } from '../plugin';
+import type { ModelMeshComponent } from '../plugin/model-item';
 type Box3 = math.Box3;
+/**
+ * Mesh 类，负责 Mesh 相关的骨骼动画和 PBR 渲染
+ */
 export declare class PMesh extends PEntity {
     private engine;
     /**
-     * 3D 元素父节点
+     * 所属的 Mesh 组件
+     */
+    owner?: ModelMeshComponent;
+    /**
+     * 父节点索引
      */
     parentIndex: number;
     /**
-     * 元素的父节点
+     * 父元素
      */
-    parentItem?: ModelTreeVFXItem;
+    parentItem?: VFXItem<VFXItemContent>;
     /**
-     * 元素的父节点 Id
+     * 父元素索引
      */
     parentItemId?: string;
+    /**
+     * 蒙皮
+     */
     skin?: PSkin;
     /**
      * morph 动画状态数据，主要是 weights 数组
      */
     morph?: PMorph;
+    /**
+     * primitive 对象数组
+     */
     primitives: PPrimitive[];
+    /**
+     * 是否隐藏，默认是隐藏
+     */
     hide: boolean;
+    /**
+     * 优先级
+     */
     priority: number;
+    /**
+     * 包围盒
+     */
     boundingBox: Box3;
+    /**
+     * 是否显示包围盒
+     */
     visBoundingBox: boolean;
+    /**
+     * 包围盒 Mesh
+     */
     boundingBoxMesh?: BoxMesh;
+    /**
+     * 是否调用 Build
+     */
     isBuilt: boolean;
+    /**
+     * 是否销毁
+     */
     isDisposed: boolean;
-    constructor(engine: Engine, itemMesh: ModelItemMesh, ownerItem?: ModelVFXItem, parentItem?: ModelTreeVFXItem);
-    build(lightCount: number, uniformSemantics: {
-        [k: string]: any;
-    }, skybox?: PSkybox): void;
-    tick(deltaSeconds: number): void;
-    addToRenderObjectSet(renderObjectSet: Set<Mesh>): void;
+    /**
+     * 构造函数，创建 Mesh 对象，并与所属组件和父元素相关联
+     * @param engine - 引擎
+     * @param name - 名称
+     * @param meshContent - Mesh 参数
+     * @param owner - 所属的 Mesh 组件
+     * @param parentId - 父元素索引
+     * @param parent - 父元素
+     */
+    constructor(engine: Engine, name: string, meshContent: ModelMeshContent, owner?: ModelMeshComponent, parentId?: string, parent?: VFXItem<VFXItemContent>);
+    /**
+     * 创建 GE 的 Mesh、Geometry 和 Material 对象
+     * @param scene - 场景管理器
+     * @returns
+     */
+    build(scene: PSceneManager): void;
+    /**
+     * 更新变换数据和蒙皮数据
+     */
+    update(): void;
+    /**
+     * 渲染 Mesh 对象，需要将内部相关数据传给渲染器
+     * @param scene - 场景
+     * @param renderer - 渲染器
+     */
+    render(scene: PSceneManager, renderer: Renderer): void;
+    /**
+     * 销毁，需要主动释放蒙皮、morph 和 Mesh 等相关的对象
+     * @returns
+     */
     dispose(): void;
     /**
      * 更新 Morph 动画权重
@@ -55,16 +110,48 @@ export declare class PMesh extends PEntity {
      * @param weightsArray - Morph 动画的权重数组
      */
     updateMorphWeights(weightsArray: Float32Array): void;
-    updateParentItem(parentItem: ModelTreeVFXItem): void;
-    updateUniformsForScene(sceneStates: PSceneStates): void;
-    updateUniformForShadow(shadowOptions: PShadowRuntimeOptions): void;
+    /**
+     * 更新父 VFX 元素
+     * @param parentId - 父元素索引
+     * @param parentItem - 父 VFX 元素
+     */
+    updateParentInfo(parentId: string, parentItem: VFXItem<VFXItemContent>): void;
+    /**
+     * 根据当前场景状态更新内部材质数据
+     * @param scene - 场景管理器
+     */
+    updateMaterial(scene: PSceneManager): void;
+    /**
+     * 点击测试，对于编辑器模式会进行精准的点击测试，否则就和内部的包围盒进行测试
+     * @param rayOrigin - 射线原点
+     * @param rayDirection - 射线方向
+     * @returns 交点列表
+     */
     hitTesting(rayOrigin: Vector3, rayDirection: Vector3): Vector3[];
+    /**
+     * 计算包围盒，根据传入的世界矩阵
+     * @param worldMatrix - 世界矩阵
+     * @returns
+     */
     computeBoundingBox(worldMatrix: Matrix4): Box3;
     private getItemBoundingBox;
+    /**
+     * 获取父节点 id
+     * @returns
+     */
     getParentId(): string | undefined;
+    /**
+     * 是否有蒙皮
+     */
     get hasSkin(): boolean;
+    /**
+     * 获取 GE Mesh 数组
+     */
     get mriMeshs(): Mesh[];
 }
+/**
+ * Primitive 类，负责 Sub Mesh相关的功能，支持骨骼动画和 PBR 渲染
+ */
 export declare class PPrimitive {
     private engine;
     /**
@@ -82,66 +169,189 @@ export declare class PPrimitive {
     private jointNormalMatList?;
     private jointMatrixTexture?;
     private jointNormalMatTexture?;
+    /**
+     * 名称
+     */
     name: string;
+    /**
+     * GE Mesh
+     */
     effectsMesh: Mesh;
+    /**
+     * 渲染优先级
+     */
     effectsPriority: number;
+    /**
+     * 包围盒
+     */
     boundingBox: math.Box3;
+    /**
+     * 是否压缩，模式不压缩
+     */
     isCompressed: boolean;
-    shadowType: PShadowType;
-    shadowMesh?: Mesh;
-    shadowMaterial?: PMaterialShadowBase;
     constructor(engine: Engine);
+    /**
+     * 创建 Primitive 对象
+     * @param options - Primitive 参数
+     * @param parent - 所属 Mesh 对象
+     */
     create(options: ModelPrimitiveOptions, parent: PMesh): void;
+    /**
+     * 创建 GE Mesh、Geometry 和 Material 对象，用于后面的渲染
+     * 着色器部分 Uniform 数据来自 uniformSemantics
+     * @param lightCount - 灯光数目
+     * @param uniformSemantics - Uniform 语义数据
+     * @param skybox - 天空盒
+     */
     build(lightCount: number, uniformSemantics: {
         [k: string]: any;
     }, skybox?: PSkybox): void;
     private getFeatureList;
-    addToRenderObjectSet(renderObjectSet: Set<Mesh>): void;
+    /**
+     * 销毁，需要释放创建的 GE 对象
+     */
     dispose(): void;
-    updateUniformsForScene(worldMatrix: Matrix4, nomralMatrix: Matrix4, sceneStates: PSceneStates): void;
-    updateUniformForShadow(shadowOpts: PShadowRuntimeOptions): void;
+    /**
+     * 更新内部 GE 材质着色器 Uniform 数据，根据场景状态
+     * @param worldMatrix - 世界矩阵
+     * @param nomralMatrix - 法线矩阵
+     * @param sceneStates - 场景状态
+     */
+    updateMaterial(worldMatrix: Matrix4, nomralMatrix: Matrix4, sceneStates: PSceneStates): void;
+    /**
+     * 点击测试，先进行简单的包围合测试，然后再计算精准的点击测试，这个测试非常耗时不要在移动端上使用
+     * @param newOrigin - 射线原点
+     * @param newDirection - 射线方向
+     * @param worldMatrix - 世界矩阵
+     * @param invWorldMatrix - 逆世界矩阵
+     * @returns 射线的 t 参数
+     */
     hitTesting(newOrigin: Vector3, newDirection: Vector3, worldMatrix: Matrix4, invWorldMatrix: Matrix4): number | undefined;
+    /**
+     * 计算包围盒
+     * @param inverseWorldMatrix - 逆世界矩阵
+     * @returns
+     */
     computeBoundingBox(inverseWorldMatrix: Matrix4): Box3;
     /**
-     * 渲染输出模式转成 Shader 中的宏定义
-     *
+     * 渲染输出模式转成着色器中的宏定义
      * @param mode - 渲染输出模式
-     * @returns none 模式返回 undefined，其他模式返回相应宏定义
+     * @returns 返回相应的宏定义
      */
     getRenderMode3DDefine(mode: spec.RenderMode3D): string | undefined;
     private updateUniformsByAnimation;
     private updateUniformsByScene;
+    /**
+     * 是否有蒙皮
+     * @returns
+     */
     hasSkin(): boolean;
+    /**
+     * 获取 GE 几何体
+     * @returns
+     */
     getEffectsGeometry(): Geometry;
+    /**
+     * 设置几何体
+     * @param val - 插件或 GE 几何体
+     */
     setGeometry(val: PGeometry | Geometry): void;
+    /**
+     * 设置材质
+     * @param val - 插件材质对象或材质参数
+     */
     setMaterial(val: PMaterial | ModelMaterialOptions): void;
+    /**
+     * 获取 GE 材质
+     * @returns
+     */
     getModelMaterial(): Material;
-    getShadowModelMaterial(): Material | undefined;
-    isEnableShadow(): boolean;
+    /**
+     * 是否无光照材质
+     * @returns
+     */
     isUnlitMaterial(): boolean;
     /**
      * 是否有 Morph 动画：
      * 需要注意 Morph 对象存在，但还是没有 Morph 动画的情况
-     *
      * @returns 返回是否有 Morph 动画
      */
     hasMorph(): boolean;
+    /**
+     * 获取世界坐标下的包围盒
+     * @returns
+     */
     getWorldBoundingBox(): Box3;
 }
+/**
+ * 3D 几何类
+ */
 export declare class PGeometry {
     geometry: Geometry;
+    /**
+     * 属性名称数组
+     */
     attributeNames: string[];
+    /**
+     * 创建 3D 几何体，根据 GE 几何体
+     * @param geometry - GE 几何体
+     */
     constructor(geometry: Geometry);
+    /**
+     * 销毁
+     */
     dispose(): void;
+    /**
+     * 是否有某个属性
+     * @param name - 属性名
+     * @returns
+     */
     hasAttribute(name: string): boolean;
+    /**
+     * 设置隐藏，通过修改几何体中的渲染数目
+     * @param hide - 隐藏值
+     */
     setHide(hide: boolean): void;
+    /**
+     * 是否压缩格式
+     * @returns
+     */
     isCompressed(): boolean;
+    /**
+     * 是否有位置属性
+     * @returns
+     */
     hasPositions(): boolean;
+    /**
+     * 是否有法线属性
+     * @returns
+     */
     hasNormals(): boolean;
+    /**
+     * 是否有切线属性
+     * @returns
+     */
     hasTangents(): boolean;
+    /**
+     * 是否有纹理坐标属性
+     * @param index - 纹理坐标索引
+     * @returns
+     */
     hasUVCoords(index: number): boolean;
+    /**
+     * 是否有颜色属性
+     * @returns
+     */
     hasColors(): boolean;
+    /**
+     * 是否有关节点属性
+     * @returns
+     */
     hasJoints(): boolean;
+    /**
+     * 是否有权重属性
+     * @returns
+     */
     hasWeights(): boolean;
 }
 export {};

package/dist/runtime/object.d.ts

@@ -1,46 +1,124 @@
-import type { spec, Mesh, math } from '@galacean/effects';
-import type { ModelVFXItem } from '../plugin/model-vfx-item';
+import type { spec, Renderer } from '@galacean/effects';
 import type { BaseTransform } from '../index';
 import type { Quaternion, Euler, Vector3, Matrix4 } from './math';
 import { PObjectType, PTransform, PCoordinate } from './common';
-import type { PSceneStates } from './scene';
-type Euler = math.Euler;
+import type { PSceneManager } from './scene';
+/**
+ * 抽象对象类，提供公共的成员变量和成员函数
+ */
 export declare abstract class PObject {
+    /**
+     * 名称
+     */
     name: string;
+    /**
+     * 类型
+     */
     type: PObjectType;
+    /**
+     * 销毁
+     */
     dispose(): void;
+    /**
+     * 是否空对象
+     * @returns
+     */
     isNone(): boolean;
+    /**
+     * 是否有效，也就是类型不是 PObjectType.none
+     * @returns
+     */
     isValid(): boolean;
     protected genName(name: string): string;
 }
+/**
+ * 抽象实体类，支持可见性、变换和所属 VFX 元素
+ */
 export declare abstract class PEntity extends PObject {
     private _visible;
     private _transform;
+    /**
+     * 是否删除
+     */
     deleted: boolean;
-    ownerItem?: ModelVFXItem;
-    tick(deltaSeconds: number): void;
+    /**
+     * 逻辑更新
+     */
+    update(): void;
+    /**
+     * 渲染对象
+     * @param scene - 场景管理器
+     * @param renderer 渲染器
+     */
+    render(scene: PSceneManager, renderer: Renderer): void;
+    /**
+     * 外部改变可见性时的回调
+     * @param visible - 可见性
+     */
     onVisibleChanged(visible: boolean): void;
-    addToRenderObjectSet(renderObjectSet: Set<Mesh>): void;
-    updateUniformsForScene(sceneStates: PSceneStates): void;
     /**
      * 仅标记不可见和删除状态，但不进行 WebGL 相关资源的释放
      * 最终释放 WebGL 相关资源是在 plugin destroy 的时候
      */
-    onEntityRemoved(): void;
+    dispose(): void;
+    /**
+     * 获取可见性，如果实体非法也是不可见
+     */
     get visible(): boolean;
+    /**
+     * 设置可见性
+     */
     set visible(val: boolean);
+    /**
+     * 获取变换
+     */
     get transform(): PTransform;
+    /**
+     * 设置变换，可以传入插件变换对象或变换参数
+     */
     set transform(val: PTransform | BaseTransform);
+    /**
+     * 获取位移
+     */
     get translation(): Vector3;
+    /**
+     * 设置位移
+     */
     set translation(val: Vector3 | spec.vec3);
+    /**
+     * 获取位置
+     */
     get position(): Vector3;
+    /**
+     * 设置位置
+     */
     set position(val: Vector3 | spec.vec3);
+    /**
+     * 获取旋转
+     */
     get rotation(): Quaternion;
+    /**
+     * 设置旋转
+     */
     set rotation(val: Quaternion | Euler | Vector3 | spec.vec4 | spec.vec3);
+    /**
+     * 获取缩放
+     */
     get scale(): Vector3;
+    /**
+     * 设置缩放
+     */
     set scale(val: Vector3 | spec.vec3);
+    /**
+     * 获取矩阵
+     */
     get matrix(): Matrix4;
+    /**
+     * 设置矩阵
+     */
     set matrix(val: Matrix4);
+    /**
+     * 获取坐标系
+     */
     get coordinate(): PCoordinate;
 }
-export {};