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

package/dist/runtime/scene.d.ts

@@ -1,6 +1,5 @@
-import type { RenderFrame, Mesh, Renderer, Texture, Engine, math, CameraOptionsEx } from '@galacean/effects';
+import type { Mesh, Renderer, Texture, Engine, math, CameraOptionsEx } from '@galacean/effects';
 import { spec } from '@galacean/effects';
-import type { ModelItem, ModelVFXItem } from '../plugin/model-vfx-item';
 import { PMesh } from './mesh';
 import type { PCamera } from './camera';
 import { PCameraManager } from './camera';
@@ -8,57 +7,160 @@ import { PLight, PLightManager } from './light';
 import { Vector3, Matrix4, Box3 } from './math';
 import { PSkybox } from './skybox';
 import type { CompositionCache } from './cache';
-import { PShadowManager } from './shadow';
 import type { PEntity } from './object';
 import { TwoStatesSet } from '../utility/ts-helper';
 type Box3 = math.Box3;
 type Vector2 = math.Vector2;
+/**
+ * 场景参数接口，初始化场景对象时使用
+ */
 export interface PSceneOptions {
+    /**
+     * 合成名称
+     */
     componentName: string;
+    /**
+     * 渲染器
+     */
     renderer: Renderer;
+    /**
+     * 场景缓存
+     */
     sceneCache: CompositionCache;
+    /**
+     * 是否只渲染线框
+     */
     wireframeOnly?: boolean;
+    /**
+     * 运行时环境
+     */
     runtimeEnv?: string;
+    /**
+     * 兼容模式
+     */
     compatibleMode?: string;
+    /**
+     * 是否可视化包围盒
+     */
     visBoundingBox?: boolean;
+    /**
+     * 是否动态排序
+     */
     enableDynamicSort?: boolean;
+    /**
+     * 3D 渲染模式
+     */
     renderMode3D?: spec.RenderMode3D;
+    /**
+     * 3D 渲染模式中棋盘格大小
+     */
     renderMode3DUVGridSize?: number;
+    /**
+     * 是否渲染天空盒
+     */
     renderSkybox: boolean;
+    /**
+     * 灯光元素数目
+     */
     lightItemCount: number;
 }
+/**
+ * 场景状态接口，每次场景管理器 Tick 时都会生成
+ */
 export interface PSceneStates {
+    /**
+     * 时间间隔
+     */
     deltaSeconds: number;
+    /**
+     * 相机对象
+     */
     camera: PCamera;
+    /**
+     * 相机位置
+     */
     cameraPosition: Vector3;
+    /**
+     * 相机矩阵
+     */
     viewMatrix: Matrix4;
+    /**
+     * 投影矩阵
+     */
     projectionMatrix: Matrix4;
+    /**
+     * 相机投影矩阵
+     */
     viewProjectionMatrix: Matrix4;
+    /**
+     * 画布大小
+     */
     winSize: Vector2;
+    /**
+     * 场景半径
+     */
     sceneRadius: number;
     shadowMapSizeInv?: Vector2;
     lightViewMatrix?: Matrix4;
     lightProjectionMatrix?: Matrix4;
     lightViewProjectionMatrix?: Matrix4;
+    /**
+     * 灯光对象列表
+     */
     lightList: PLight[];
+    /**
+     * 最大灯光数目
+     */
     maxLightCount: number;
+    /**
+     * 天空盒对象
+     */
     skybox?: PSkybox;
 }
+/**
+ * 场景管理类，如果存在 Model 插件中的元素才会创建
+ */
 export declare class PSceneManager {
+    /**
+     * 合成名称
+     */
     compName: string;
+    /**
+     * 实体列表
+     */
     itemList: PEntity[];
+    /**
+     * Mesh 列表
+     */
     meshList: PMesh[];
+    /**
+     * 灯光管理器
+     */
     lightManager: PLightManager;
+    /**
+     * 相机管理器
+     */
     cameraManager: PCameraManager;
-    shadowManager: PShadowManager;
     /**
      * 是否动态排序 Mesh 渲染优先级
      * 默认 false，需要和 Tiny 对齐时为 true
      */
     enableDynamicSort: boolean;
+    /**
+     * IBL 渲染时的 BRDF 查询纹理
+     */
     brdfLUT?: Texture;
+    /**
+     * 天空盒
+     */
     skybox?: PSkybox;
+    /**
+     * Tick 次数
+     */
     tickCount: number;
+    /**
+     * 最近 Tick 时间
+     */
     lastTickSecond: number;
     /**
      * 当前场景包围盒缓存，在阴影渲染中使用
@@ -69,65 +171,92 @@ export declare class PSceneManager {
      */
     renderedMeshSet: TwoStatesSet<Mesh>;
     /**
-     * 场景中所有渲染过的 Mesh 集合
+     * 最多灯光数目
+     */
+    maxLightCount: number;
+    /**
+     * 场景状态
      */
-    allRenderedMeshSet: Set<Mesh>;
+    sceneStates: PSceneStates;
     private renderer?;
     private sceneCache?;
     private parentId2Mesh;
-    private maxLightCount;
     private renderSkybox;
     private engine;
     constructor(engine: Engine);
+    /**
+     * 初始化场景管理器，设置全局状态
+     * @param opts - 场景参数
+     */
     initial(opts: PSceneOptions): void;
     private initGlobalState;
     private clean;
+    /**
+     * 销毁，需要销毁各种管理器和创建的 WebGL 资源
+     */
     dispose(): void;
-    addItem(item: ModelVFXItem): void;
-    removeItem(item: ModelVFXItem): void;
-    updateDefaultCamera(camera: CameraOptionsEx): void;
-    buildItem(item: ModelItem): void;
     /**
-     * 编译运行时需要的 Shader 代码，包括 PBR、天空盒与阴影。
+     * 添加插件元素到场景中
+     * @param item - 插件元素
      */
-    private build;
-    tick(deltaTime: number): void;
+    addItem(item: PMesh | PCamera | PLight | PSkybox): void;
+    /**
+     * 从场景中删除插件元素
+     * @param item - 插件元素
+     */
+    removeItem(item: PMesh | PCamera | PLight | PSkybox): void;
+    /**
+     * 更新默认相机状态，根据传入的相机参数
+     * @param camera - 相机参数
+     */
+    updateDefaultCamera(camera: CameraOptionsEx): void;
     /**
-     * 更新 RI 帧对象中默认 Pass 的渲染队列
-     * 如果是动态排序模式，需要重新添加所有的 mesh，这样优先级才能生效
-     * 如果是正常模式，那就增量添加和删除
-     *
-     * @param frame - RI 帧对象
+     * 更新插件场景，需要更新内部的相关的插件对象，特别是 Mesh 对象的骨骼动画
+     * 并将需要渲染的对象添加到渲染对象集合中
+     * @param deltaTime - 更新间隔
      */
-    updateDefaultRenderPass(frame: RenderFrame): void;
+    tick(deltaTime: number): void;
     /**
      * 动态调整 Mesh 渲染优先级
      * 主要是为了和 Tiny 渲染对齐，正常渲染不进行调整
-     *
      * @param states - 场景中的状态数据
      */
     dynamicSortMeshes(states: PSceneStates): void;
     /**
      * 查询场景中的 Mesh
      * 通过 parentId 查询 Mesh 对象，可能找不到 Mesh 对象
-     *
      * @param parentId - Item 中定义的 parentId
      * @returns 查询到的 PMesh，或者是没找到。如果 Mesh 不可见，也是没找到。
      */
     queryMesh(parentId: string): PMesh | undefined;
     /**
-     * 删除 RenderFrame DefaultRenderPass 中添加的 Mesh，Player 要执行 Reset 操作
-     *
-     * @param renderFrame - 当前渲染帧对象
+     * 获取场景的包围盒
+     * @param box - 包围盒
+     * @returns 场景的包围盒
      */
-    removeAllMeshesFromDefaultPass(renderFrame: RenderFrame): void;
     getSceneAABB(box?: Box3): Box3;
     printDebugInfo(): void;
+    /**
+     * 获取渲染器
+     * @returns
+     */
     getRenderer(): Renderer;
+    /**
+     * 获取场景中缓存
+     * @returns
+     */
     getSceneCache(): CompositionCache;
+    /**
+     * 获取激活的相机
+     */
     get activeCamera(): PCamera;
+    /**
+     * 获取灯光数目
+     */
     get lightCount(): number;
+    /**
+     * 获取着色器灯光数目，最小是 10
+     */
     get shaderLightCount(): number;
-    get enableShadowPass(): boolean;
 }
 export {};

package/dist/runtime/shader-libs/standard-shader-source.d.ts

@@ -1,3 +1,13 @@
+/**
+ * GLSL 着色器代码编译预处理
+ */
 export declare namespace StandardShaderSource {
+    /**
+     * GLSL 代码预处理和生成最终代码
+     * @param source - GLSL 代码
+     * @param features - 宏定义
+     * @param isWebGL2 - 是否 WebGL2
+     * @returns 最终代码
+     */
     function build(source: string, features: string[], isWebGL2: boolean): string;
 }

package/dist/runtime/shader-libs/standard-shader.d.ts

@@ -1,6 +1,22 @@
 import type { PShaderContext } from '../shader';
+/**
+ * 着色器代码生成类
+ */
 export declare class StandardShader {
+    /**
+     * WebGL 环境
+     */
     static environment: string;
+    /**
+     * 获取顶点着色器代码
+     * @param context - 着色器上下文
+     * @returns
+     */
     static getVertexShaderCode(context: PShaderContext): string;
+    /**
+     * 获取片段着色器代码
+     * @param context - 着色器上下文
+     * @returns
+     */
     static getFragmentShaderCode(context: PShaderContext): string;
 }

package/dist/runtime/shader.d.ts

@@ -1,18 +1,50 @@
 import type { PMaterialBase } from './material';
+/**
+ * 着色器上下文
+ */
 export interface PShaderContext {
+    /**
+     * 材质
+     */
     material: PMaterialBase;
+    /**
+     * 是否 WebGL2
+     */
     isWebGL2: boolean;
+    /**
+     * 特性列表
+     */
     featureList: string[];
 }
+/**
+ * 着色器返回的代码结果
+ */
 export interface PShaderResults {
+    /**
+     * 顶点着色器代码
+     */
     vertexShaderCode: string;
+    /**
+     * 片段着色器代码
+     */
     fragmentShaderCode: string;
 }
-export type ShaderCodeFuncType = (context: PShaderContext) => PShaderResults;
+/**
+ * 着色器管理类
+ */
 export declare class PShaderManager {
     private funcMap;
     private static _instance;
+    /**
+     * 获取着色器单例对象
+     * @returns
+     */
     static getInstance(): PShaderManager;
     private constructor();
+    /**
+     * 生成着色器代码
+     * @param context - 着色器上下文
+     * @returns
+     */
     genShaderCode(context: PShaderContext): PShaderResults;
 }

package/dist/runtime/skybox.d.ts

@@ -1,86 +1,310 @@
-import type { Mesh, Material, TextureSourceOptions, Engine } from '@galacean/effects';
+import type { Mesh, Material, TextureSourceOptions, Engine, Renderer } from '@galacean/effects';
 import { Texture } from '@galacean/effects';
-import type { ModelItemSkybox, ModelSkyboxOptions } from '../index';
+import type { ModelSkyboxOptions } from '../index';
 import { PEntity } from './object';
 import { PMaterialBase } from './material';
-import type { CompositionCache } from './cache';
-import type { PSceneStates } from './scene';
-import type { ModelVFXItem } from '../plugin/model-vfx-item';
+import type { PSceneManager } from './scene';
+import type { ModelSkyboxComponent } from '../plugin/model-item';
+/**
+ * 天空盒类，支持天空盒的渲染和 IBL 光照效果
+ */
 export declare class PSkybox extends PEntity {
+    /**
+     * 所属的天空盒组件
+     */
+    owner?: ModelSkyboxComponent;
+    /**
+     * 是否渲染
+     */
     renderable: boolean;
+    /**
+     * 强度
+     */
     intensity: number;
+    /**
+     * 反射强度
+     */
     reflectionsIntensity: number;
+    /**
+     * 辐射照度系数
+     */
     irradianceCoeffs?: number[][];
+    /**
+     * 漫反射贴图
+     */
     diffuseImage?: Texture;
+    /**
+     * 高光贴图
+     */
     specularImage: Texture;
+    /**
+     * 高光贴图大小
+     */
     specularImageSize: number;
+    /**
+     * 高光贴图 Mip 层数目
+     */
     specularMipCount: number;
+    /**
+     * BRDF 查询纹理
+     */
     brdfLUT?: Texture;
+    /**
+     * 优先级
+     */
     priority: number;
+    /**
+     * 天空盒 Mesh
+     */
     skyboxMesh?: Mesh;
+    /**
+     * 天空盒材质
+     */
     skyboxMaterial?: PMaterialSkyboxFilter;
+    /**
+     * 是否构建过
+     */
     isBuilt: boolean;
-    constructor(skybox: ModelItemSkybox, ownerItem?: ModelVFXItem);
+    /**
+     * 构造函数
+     * @param name - 名称
+     * @param options - 天空盒参数
+     * @param owner - 所属天空盒组件元素
+     */
+    constructor(name: string, options: ModelSkyboxOptions, owner?: ModelSkyboxComponent);
+    /**
+     * 设置 BRDF 查询纹理
+     * @param brdfLUT - 纹理
+     */
     setup(brdfLUT?: Texture): void;
-    build(sceneCache: CompositionCache): void;
+    /**
+     * 构建天空盒，创建天空盒材质，从场景缓存中创建天空盒 Mesh
+     * @param sceneCache - 场景缓存
+     * @returns
+     */
+    build(scene: PSceneManager): void;
+    /**
+     * 渲染天空盒
+     * @param scene - 场景
+     * @param renderer - 渲染器
+     */
+    render(scene: PSceneManager, renderer: Renderer): void;
+    /**
+     * 销毁
+     */
     dispose(): void;
-    addToRenderObjectSet(renderObjectSet: Set<Mesh>): void;
-    updateUniformsForScene(sceneStates: PSceneStates): void;
+    private updateMaterial;
+    /**
+     * 是否可用，根据内部的强度、辐射照度系数、漫反射贴图和高光贴图状态
+     */
     get available(): boolean;
+    /**
+     * 当前强度，如果不可见返回 0
+     */
     get currentIntensity(): number;
+    /**
+     * 当前反射强度，如果不可见返回 0
+     */
     get currentReflectionsIntensity(): number;
+    /**
+     * 是否有漫反射贴图
+     */
     get hasDiffuseImage(): boolean;
+    /**
+     * 是否有辐射照度系数
+     */
     get hasIrradianceCoeffs(): boolean;
 }
+/**
+ * 天空盒材质类
+ */
 export declare class PMaterialSkyboxFilter extends PMaterialBase {
+    /**
+     * 强度
+     */
     intensity: number;
+    /**
+     * 反射强度
+     */
     reflectionsIntensity: number;
+    /**
+     * BRDF 查询纹理
+     */
     brdfLUT?: Texture;
+    /**
+     * 辐射照度系数
+     */
     irradianceCoeffs?: number[][];
+    /**
+     * 漫反射贴图
+     */
     diffuseImage?: Texture;
+    /**
+     * 高光贴图
+     */
     specularImage: Texture;
+    /**
+     * 高光贴图 Mip 数目
+     */
     specularMipCount: number;
+    /**
+     * 创建天空盒材质，从天空盒对象
+     * @param skybox - 天空盒对象
+     */
     create(skybox: PSkybox): void;
+    /**
+     * 销毁，需要解除资源引用
+     */
     dispose(): void;
+    /**
+     * 获取着色器特性列表
+     * @returns
+     */
     getShaderFeatures(): string[];
+    /**
+     * 更新着色器 Uniform 数据
+     * @param material - 对应的 Core 层材质
+     */
     updateUniforms(material: Material): void;
+    /**
+     * 设置对应的材质状态
+     * @param material - 对应的 Core 层材质
+     */
     setMaterialStates(material: Material): void;
 }
+/**
+ * 图像缓冲区数据接口
+ */
 export interface PImageBufferData {
+    /**
+     * 类型，总是 buffer
+     */
     type: 'buffer';
+    /**
+     * 数组
+     */
     data: Uint8Array;
+    /**
+     * MIME 类型
+     */
     mimeType: string;
 }
+/**
+ * 图像数据类型，字符串（URL）或者图像缓冲区数据
+ */
 export type PImageData = string | PImageBufferData;
+/**
+ * 天空盒基础参数接口
+ */
 export interface PSkyboxBaseParams {
+    /**
+     * 是否渲染
+     */
     renderable: boolean;
+    /**
+     * 强度
+     */
     intensity: number;
+    /**
+     * 反射强度
+     */
     reflectionsIntensity: number;
+    /**
+     * 辐射照度系数
+     */
     irradianceCoeffs?: number[][];
+    /**
+     * 高光贴图 Mip 层数
+     */
     specularMipCount: number;
+    /**
+     * 高光贴图大小
+     */
     specularImageSize: number;
 }
+/**
+ * 天空盒 URL 参数接口
+ */
 export interface PSkyboxURLParams extends PSkyboxBaseParams {
+    /**
+     * 类型，总是 url
+     */
     type: 'url';
+    /**
+     * 漫反射贴图 URL 列表
+     */
     diffuseImage?: string[];
+    /**
+     * 高光贴图 URL 二级列表
+     */
     specularImage: string[][];
 }
+/**
+ * 天空盒缓冲区参数接口
+ */
 export interface PSkyboxBufferParams extends PSkyboxBaseParams {
+    /**
+     * 类型，总是 buffer
+     */
     type: 'buffer';
+    /**
+     * 漫反射贴图列表
+     */
     diffuseImage?: PImageBufferData[];
+    /**
+     * 高光贴图二级列表
+     */
     specularImage: PImageBufferData[][];
 }
+/**
+ * 天空盒参数类型
+ */
 export type PSkyboxParams = PSkyboxURLParams | PSkyboxBufferParams;
 export declare enum PSkyboxType {
     NFT = 0,
     FARM = 1
 }
+/**
+ * 天空盒创建类
+ */
 export declare class PSkyboxCreator {
+    /**
+     * 获取 BRDF 查询纹理选项
+     * @returns 纹理源选项
+     */
     static getBrdfLutTextureOptions(): Promise<TextureSourceOptions>;
+    /**
+     * 创建 BRDF 查询纹理
+     * @param engine - 引擎
+     * @returns 纹理
+     */
     static createBrdfLutTexture(engine: Engine): Promise<Texture>;
+    /**
+     * 创建天空盒选项
+     * @param engine - 引擎
+     * @param params - 天空盒参数
+     * @returns 天空盒选项
+     */
     static createSkyboxOptions(engine: Engine, params: PSkyboxParams): Promise<ModelSkyboxOptions>;
+    /**
+     * 创建高光 Cube Map 纹理
+     * @param engine - 引擎
+     * @param params - 天空盒参数
+     * @returns 纹理
+     */
     static createSpecularCubeMap(engine: Engine, params: PSkyboxParams): Promise<Texture>;
+    /**
+     * 创建漫反射纹理
+     * @param engine - 引擎
+     * @param params - 天空盒参数
+     * @returns 纹理或未定义
+     */
     static createDiffuseCubeMap(engine: Engine, params: PSkyboxParams): Promise<Texture | undefined>;
+    /**
+     * 创建天空盒参数
+     * @param skyboxType - 天空盒类型
+     * @returns 天空盒参数
+     */
     static getSkyboxParams(skyboxType?: PSkyboxType): PSkyboxURLParams;
     private checkCubeMapImage;
     private static getIrradianceCoeffs;

package/dist/utility/debug-helper.d.ts

@@ -1,7 +1,21 @@
 import type { Player } from '@galacean/effects';
 import type { PMesh } from '../runtime/mesh';
 type WebGLContext = WebGL2RenderingContext | WebGLRenderingContext;
+/**
+ * Hook WebGL 相关的 API 调用
+ * @param ctx - WebGL 上下文
+ */
 export declare function HookOGLFunc(ctx: WebGLContext): void;
+/**
+ * 获取播放器关联的 GPU 信息
+ * @param player - 播放器
+ * @returns
+ */
 export declare function getRendererGPUInfo(player: Player): string;
+/**
+ * 获取播放器中 PMesh 对象列表
+ * @param player - 播放器
+ * @returns
+ */
 export declare function getPMeshList(player: Player): PMesh[];
 export {};