From 0ec93f11b03a571da20ee6bac8a97be5680fc0fc Mon Sep 17 00:00:00 2001 From: hyde zhou Date: Fri, 8 Dec 2023 19:02:33 +0800 Subject: [PATCH] V3.8.2 comment (#16581) --- cocos/rendering/custom/pipeline.ts | 294 +++++++++++++++++- .../pipeline/custom/RenderInterfaceTypes.h | 284 ++++++++++++++++- 2 files changed, 550 insertions(+), 28 deletions(-) diff --git a/cocos/rendering/custom/pipeline.ts b/cocos/rendering/custom/pipeline.ts index 652c711b1e..e50ae821bf 100644 --- a/cocos/rendering/custom/pipeline.ts +++ b/cocos/rendering/custom/pipeline.ts @@ -129,7 +129,14 @@ export interface PipelineRuntime { /** * @en Get shading scale. * Shading scale affects shading texels per pixel. + * Currently it affects classic native forward pipeline and builtin custom pipeline. + * Users can change the size of the render targets according to the shading scale, + * when writing their own custom pipelines. + * To change screen size, please check director.root.resize. * @zh 获得渲染倍率(ShadingScale),每像素(pixel)绘制的纹素(texel)会根据渲染倍率进行调整。 + * 目前仅对原有原生Forward管线以及内置自定义管线生效。 + * 用户编写自定义管线时,可以根据渲染倍率进行渲染目标尺寸大小的调整。 + * 如果要修改屏幕大小,详见director.root.resize。 */ shadingScale: number; /** @@ -378,21 +385,107 @@ export interface Setter extends RenderNode { * @param name @en descriptor name in shader. @zh 填写着色器中的描述符(descriptor)名字 */ setSampler (name: string, sampler: Sampler): void; + /** + * @en Set builtin camera constants of CCCamera, such as cc_matView. + * For list of constants, please check CCCamera in cc-global.chunk. + * @zh 设置内置相机常量,例如cc_matView。 + * 具体常量见cc-global.chunk中的CCCamera. + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinCameraConstants (camera: Camera): void; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Same as setBuiltinDirectionalLightConstants + * @zh 同setBuiltinDirectionalLightConstants + * @param light @en The main light. @zh 主光 + */ setBuiltinShadowMapConstants (light: DirectionalLight): void; + /** + * @en Set builtin directional light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCCamera in cc-global.chunk. + * @zh 设置内置方向光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-global.chunk中的CCCamera。 + * @param light @en The main light. @zh 主光 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinDirectionalLightConstants (light: DirectionalLight, camera: Camera): void; + /** + * @en Set builtin sphere light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置球形光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The sphere light. @zh 球形光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinSphereLightConstants (light: SphereLight, camera: Camera): void; + /** + * @en Set builtin spot light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置探照光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The spot light. @zh 探照光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinSpotLightConstants (light: SpotLight, camera: Camera): void; + /** + * @en Set builtin point light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置点光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The point light. @zh 点光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinPointLightConstants (light: PointLight, camera: Camera): void; + /** + * @en Set builtin ranged directional light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置区间平行光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The ranged directional light. @zh 区间平行光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ setBuiltinRangedDirectionalLightConstants (light: RangedDirectionalLight, camera: Camera): void; + /** + * @en Set builtin directional light frustum and shadow constants. + * These constants are used in builtin shadow map, cascaded shadow map and planar shadow. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCCSM in cc-csm.chunk. + * @zh 设置内置平行光视锥与阴影常量。 + * 这些常量用于内置的阴影、级联阴影与平面阴影。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-csm.chunk中的CCCSM。 + * @param light @en The directional light. @zh 平行光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + * @param csmLevel @en Curent level of cascaded shadow map @zh 级联阴影等级 + */ setBuiltinDirectionalLightFrustumConstants ( camera: Camera, light: DirectionalLight, csmLevel?: number): void; + /** + * @en Set builtin spot light frustum and shadow constants. + * These constants are used in builtin shadow map. + * For list of constants, please check CCShadow in cc-shadow.chunk. + * @zh 设置内置探照光视锥与阴影常量。 + * 这些常量用于内置的阴影。 + * 具体常量见cc-shadow.chunk中的CCShadow。 + * @param light @en The spot light. @zh 探照光源 + */ setBuiltinSpotLightFrustumConstants (light: SpotLight): void; } +/** + * @en Scene + * A scene is an abstraction of content for rendering. + * @zh 场景。需要绘制的场景内容。 + */ export interface SceneBuilder extends Setter { + /** + * @en Use the frustum information of light instead of camera. + * Often used in building shadow map. + * @zh 使用光源视锥进行投影,而不是用相机。常用于shadow map的生成。 + * @param light @en The light used for projection @zh 用于投影的光源 + * @param csmLevel @en Curent level of cascaded shadow map @zh 级联阴影等级 + * @param optCamera @en Additional scene culling camera. @zh 额外的场景裁切相机 + */ useLightFrustum ( light: Light, csmLevel?: number, @@ -420,6 +513,16 @@ export interface RenderQueueBuilder extends Setter { camera: Camera, light: LightInfo, sceneFlags?: SceneFlags): void; + /** + * @en Add the scene to be rendered. + * If SceneFlags.NON_BUILTIN is specified, no builtin constants will be set. + * Otherwise, related builtin constants will be set automatically. + * @zh 添加需要绘制的场景。 + * 如果设置了SceneFlags.NON_BUILTIN,那么不会自动设置内置常量。 + * @param camera @en Camera used for projection @zh 用于投影的相机 + * @param sceneFlags @en Rendering flags of the scene @zh 场景渲染标志位 + * @param light @en Light used for lighting computation @zh 用于光照的光源 + */ addScene ( camera: Camera, sceneFlags: SceneFlags, @@ -561,8 +664,27 @@ export interface BasicRenderPassBuilder extends Setter { showStatistics: boolean; } +/** + * @en Basic multisample render pass builder + * Support resolve render targets and depth stencil. + * This render pass only contains one render subpass. + * If resolve targets are specified, they will be resolved at the end of the render pass. + * After resolving, the contents of multisample render targets and depth stencils are unspecified. + * @zh 基础的多重采样渲染通道。支持决算(Resolve)渲染目标与深度缓冲。 + * 此渲染通道只包含一个渲染子通道。 + * 如果添加了决算对象,那么在渲染通道结束时,会进行决算。 + * 决算后多重采样渲染目标与深度缓冲的内容是未定义的。 + */ export interface BasicMultisampleRenderPassBuilder extends BasicRenderPassBuilder { + /** + * @en Set resolve render target + * @zh 设置决算渲染目标 + */ resolveRenderTarget (source: string, target: string): void; + /** + * @en Set resolve depth stencil + * @zh 设置决算深度模板缓冲 + */ resolveDepthStencil ( source: string, target: string, @@ -575,11 +697,13 @@ export interface BasicMultisampleRenderPassBuilder extends BasicRenderPassBuilde * Basic pipeline provides basic rendering features which are supported on all platforms. * User can register resources which will be used in the render graph. * Theses resources are generally read and write, and will be managed by the pipeline. + * The residency information of resource should not be changed after registration. * In each frame, user can create a render graph to be executed by the pipeline. * @zh 基础渲染管线。 * 基础渲染管线提供基础的渲染能力,能在全平台使用。 * 用户可以在渲染管线中注册资源,这些资源将由管线托管,用于render graph。 * 这些资源一般是可读写的资源。 + * 资源在注册后,不能更改驻留属性。 * 用户可以每帧构建一个render graph,然后交由管线执行。 */ export interface BasicPipeline extends PipelineRuntime { @@ -597,6 +721,10 @@ export interface BasicPipeline extends PipelineRuntime { * @zh 结束管线构建 */ endSetup (): void; + /** + * @en Enable cpu culling of objects affected by the light. Enabled by default. + * @zh 光照计算时,裁切受光源影响的物件。默认开启。 + */ enableCpuLightCulling: boolean; /** * @en Check whether the resource has been registered in the pipeline. @@ -606,8 +734,8 @@ export interface BasicPipeline extends PipelineRuntime { */ containsResource (name: string): boolean; /** - * @en Add render window to the pipeline. - * @zh 注册渲染窗口(RenderWindow) + * @en Add or update render window to the pipeline. + * @zh 注册或更新渲染窗口(RenderWindow) * @param name @en Resource name @zh 资源名字 * @param format @en Expected format of the render window @zh 期望的渲染窗口格式 * @param width @en Expected width of the render window @zh 期望的渲染窗口宽度 @@ -622,6 +750,7 @@ export interface BasicPipeline extends PipelineRuntime { height: number, renderWindow: RenderWindow): number; /** + * @deprecated Method will be removed in 3.9.0 * @en Update render window information. * When render window information is updated, such as resized, user should notify the pipeline. * @zh 更新渲染窗口信息。当渲染窗口发生更新时,用户应通知管线。 @@ -629,8 +758,8 @@ export interface BasicPipeline extends PipelineRuntime { */ updateRenderWindow (name: string, renderWindow: RenderWindow): void; /** - * @en Add 2D render target. - * @zh 添加2D渲染目标 + * @en Add or update 2D render target. + * @zh 添加或更新2D渲染目标 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -645,8 +774,8 @@ export interface BasicPipeline extends PipelineRuntime { height: number, residency?: ResourceResidency): number; /** - * @en Add 2D depth stencil. - * @zh 添加2D深度模板缓冲 + * @en Add or update 2D depth stencil. + * @zh 添加或更新2D深度模板缓冲 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -661,6 +790,7 @@ export interface BasicPipeline extends PipelineRuntime { height: number, residency?: ResourceResidency): number; /** + * @deprecated Method will be removed in 3.9.0 * @en Update render target information. * @zh 更新渲染目标的信息 * @param name @en Resource name @zh 资源名字 @@ -674,6 +804,7 @@ export interface BasicPipeline extends PipelineRuntime { height: number, format?: Format): void; /** + * @deprecated Method will be removed in 3.9.0 * @en Update depth stencil information. * @zh 更新深度模板缓冲的信息 * @param name @en Resource name @zh 资源名字 @@ -686,17 +817,65 @@ export interface BasicPipeline extends PipelineRuntime { width: number, height: number, format?: Format): void; + /** + * @en Add or update buffer. + * @zh 添加或更新缓冲 + * @param name @en Resource name @zh 资源名字 + * @param size @en Size of the resource in bytes @zh 资源的大小 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ addBuffer ( name: string, size: number, flags: ResourceFlags, residency: ResourceResidency): number; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update buffer information. + * @zh 更新缓冲的信息 + * @param name @en Resource name @zh 资源名字 + * @param size @en Size of the resource in bytes @zh 资源的大小 + */ updateBuffer (name: string, size: number): void; + /** + * @en Add or update external texture. + * Must be readonly. + * @zh 添加或更新外部的贴图。贴图必须是只读的。 + * @param name @en Resource name @zh 资源名字 + * @param texture @en External unmanaged texture @zh 外部不受管理的贴图 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @returns Resource ID + */ addExternalTexture ( name: string, texture: Texture, flags: ResourceFlags): number; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update external texture information. + * @zh 更新外部的贴图信息 + * @param name @en Resource name @zh 资源名字 + * @param texture @en External unmanaged texture @zh 外部不受管理的贴图 + */ updateExternalTexture (name: string, texture: Texture): void; + /** + * @en Add or update texture. + * @zh 添加或更新外部的贴图。 + * @param name @en Resource name @zh 资源名字 + * @param type @en Type of the texture @zh 贴图的类型 + * @param format @en Format of the texture @zh 贴图的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 贴图的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 贴图的采样数目 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ addTexture ( name: string, type: TextureType, @@ -709,6 +888,19 @@ export interface BasicPipeline extends PipelineRuntime { sampleCount: SampleCount, flags: ResourceFlags, residency: ResourceResidency): number; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update texture information. + * @zh 更新贴图信息 + * @param name @en Resource name @zh 资源名字 + * @param format @en Format of the texture @zh 贴图的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 贴图的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 贴图的采样数目 + */ updateTexture ( name: string, format: Format, @@ -718,6 +910,22 @@ export interface BasicPipeline extends PipelineRuntime { arraySize: number, mipLevels: number, sampleCount: SampleCount): void; + /** + * @en Add or update resource. + * @zh 添加或更新资源 + * @param name @en Resource name @zh 资源名字 + * @param dimension @en Dimension of the resource @zh 资源的维度 + * @param format @en Format of the texture @zh 资源的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 资源的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 资源的采样数目 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ addResource ( name: string, dimension: ResourceDimension, @@ -730,6 +938,19 @@ export interface BasicPipeline extends PipelineRuntime { sampleCount: SampleCount, flags: ResourceFlags, residency: ResourceResidency): number; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update resource information. + * @zh 更新资源信息 + * @param name @en Resource name @zh 资源名字 + * @param format @en Format of the texture @zh 资源的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 资源的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 资源的采样数目 + */ updateResource ( name: string, format: Format, @@ -812,6 +1033,11 @@ export interface BasicPipeline extends PipelineRuntime { * @param copyPairs @en Array of copy source and target @zh 拷贝来源与目标的数组 */ addCopyPass (copyPairs: CopyPair[]): void; + /** + * @en Builtin reflection probe pass + * @zh 添加内置环境光反射通道 + * @param camera @en Capturing camera @zh 用于捕捉的相机 + */ addBuiltinReflectionProbePass (camera: Camera): void; /** * @engineInternal @@ -1151,11 +1377,29 @@ export interface RenderPassBuilder extends BasicRenderPassBuilder { setCustomShaderStages (name: string, stageFlags: ShaderStageFlagBit): void; } +/** + * @en Multisample render pass builder + * @zh 多重采样渲染通道。 + */ export interface MultisampleRenderPassBuilder extends BasicMultisampleRenderPassBuilder { + /** + * @en Add storage buffer + * @zh 添加存储缓冲 + * @param name @en Name of the storage buffer @zh 存储缓冲的名字 + * @param accessType @en Access type of the buffer in the render pass @zh 渲染通道中缓冲的读写状态 + * @param slotName @en name of the descriptor in shader @zh 着色器中描述符的名字 + */ addStorageBuffer ( name: string, accessType: AccessType, slotName: string): void; + /** + * @en Add storage image + * @zh 添加存储贴图 + * @param name @en Name of the storage texture @zh 存储贴图的名字 + * @param accessType @en Access type of the texture in the render pass @zh 渲染通道中贴图的读写状态 + * @param slotName @en name of the descriptor in shader @zh 着色器中描述符的名字 + */ addStorageImage ( name: string, accessType: AccessType, @@ -1247,11 +1491,11 @@ export interface ComputePassBuilder extends Setter { */ export interface Pipeline extends BasicPipeline { /** - * @en Add storage buffer. - * @zh 添加存储缓冲 + * @en Add or update storage buffer. + * @zh 添加或更新存储缓冲 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 - * @param size @en Size of the resource @zh 资源的大小 + * @param size @en Size of the resource in bytes @zh 资源的大小 * @param residency @en Residency of the resource. @zh 资源的驻留性 */ addStorageBuffer ( @@ -1260,8 +1504,8 @@ export interface Pipeline extends BasicPipeline { size: number, residency?: ResourceResidency): number; /** - * @en Add 2D storage texture - * @zh 添加2D存储贴图 + * @en Add or update 2D storage texture + * @zh 添加或更新2D存储贴图 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -1276,8 +1520,8 @@ export interface Pipeline extends BasicPipeline { residency?: ResourceResidency): number; /** * @experimental - * @en Add 2D shading rate texture - * @zh 添加2D着色率贴图 + * @en Add or update 2D shading rate texture + * @zh 添加或更新2D着色率贴图 * @param name @en Resource name @zh 资源名字 * @param width @en Width of the resource @zh 资源的宽度 * @param height @en Height of the resource @zh 资源的高度 @@ -1292,7 +1536,7 @@ export interface Pipeline extends BasicPipeline { * @en Update storage buffer information. * @zh 更新存储缓冲的信息 * @param name @en Resource name @zh 资源名字 - * @param size @en Size of the resource @zh 资源的大小 + * @param size @en Size of the resource in bytes @zh 资源的大小 * @param format @en Format of the resource @zh 资源的格式 */ updateStorageBuffer ( @@ -1335,6 +1579,16 @@ export interface Pipeline extends BasicPipeline { width: number, height: number, passName: string): RenderPassBuilder; + /** + * @en Add multisample render pass + * @zh 添加多重采样渲染通道 + * @param width @en Width of the render pass @zh 渲染通道的宽度 + * @param height @en Height of the render pass @zh 渲染通道的高度 + * @param count @en Sample count @zh 采样数目 + * @param quality @en Sample quality (default is 0) @zh 采样质量(默认为0) + * @param passName @en Pass name declared in the effect. Default value is 'default' @zh effect中的pass name,缺省为'default' + * @returns Multisample render pass builder + */ addMultisampleRenderPass ( width: number, height: number, @@ -1390,10 +1644,18 @@ export interface Pipeline extends BasicPipeline { * @param movePairs @en Array of move source and target @zh 移动来源与目标的数组 */ addMovePass (movePairs: MovePair[]): void; + /** + * @experimental + * @engineInternal + */ addBuiltinGpuCullingPass ( camera: Camera, hzbName?: string, light?: Light): void; + /** + * @experimental + * @engineInternal + */ addBuiltinHzbGenerationPass (sourceDepthStencilName: string, targetHzbName: string): void; /** * @experimental @@ -1427,6 +1689,10 @@ export interface PipelineBuilder { * @param pipeline @en Current render pipeline @zh 当前管线 */ setup (cameras: Camera[], pipeline: BasicPipeline): void; + /** + * @en Callback of pipeline state changed + * @zh 渲染管线状态更新的回调 + */ onGlobalPipelineStateChanged? (): void; } diff --git a/native/cocos/renderer/pipeline/custom/RenderInterfaceTypes.h b/native/cocos/renderer/pipeline/custom/RenderInterfaceTypes.h index 09dd08e0c2..69579a3de6 100644 --- a/native/cocos/renderer/pipeline/custom/RenderInterfaceTypes.h +++ b/native/cocos/renderer/pipeline/custom/RenderInterfaceTypes.h @@ -173,7 +173,14 @@ public: /** * @en Get shading scale. * Shading scale affects shading texels per pixel. + * Currently it affects classic native forward pipeline and builtin custom pipeline. + * Users can change the size of the render targets according to the shading scale, + * when writing their own custom pipelines. + * To change screen size, please check director.root.resize. * @zh 获得渲染倍率(ShadingScale),每像素(pixel)绘制的纹素(texel)会根据渲染倍率进行调整。 + * 目前仅对原有原生Forward管线以及内置自定义管线生效。 + * 用户编写自定义管线时,可以根据渲染倍率进行渲染目标尺寸大小的调整。 + * 如果要修改屏幕大小,详见director.root.resize。 */ virtual float getShadingScale() const = 0; virtual void setShadingScale(float scale) = 0; @@ -457,24 +464,110 @@ public: * @param name @en descriptor name in shader. @zh 填写着色器中的描述符(descriptor)名字 */ virtual void setSampler(const ccstd::string &name, gfx::Sampler *sampler) = 0; + /** + * @en Set builtin camera constants of CCCamera, such as cc_matView. + * For list of constants, please check CCCamera in cc-global.chunk. + * @zh 设置内置相机常量,例如cc_matView。 + * 具体常量见cc-global.chunk中的CCCamera. + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinCameraConstants(const scene::Camera *camera) = 0; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Same as setBuiltinDirectionalLightConstants + * @zh 同setBuiltinDirectionalLightConstants + * @param light @en The main light. @zh 主光 + */ virtual void setBuiltinShadowMapConstants(const scene::DirectionalLight *light) = 0; + /** + * @en Set builtin directional light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCCamera in cc-global.chunk. + * @zh 设置内置方向光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-global.chunk中的CCCamera。 + * @param light @en The main light. @zh 主光 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinDirectionalLightConstants(const scene::DirectionalLight *light, const scene::Camera *camera) = 0; + /** + * @en Set builtin sphere light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置球形光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The sphere light. @zh 球形光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinSphereLightConstants(const scene::SphereLight *light, const scene::Camera *camera) = 0; + /** + * @en Set builtin spot light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置探照光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The spot light. @zh 探照光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinSpotLightConstants(const scene::SpotLight *light, const scene::Camera *camera) = 0; + /** + * @en Set builtin point light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置点光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The point light. @zh 点光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinPointLightConstants(const scene::PointLight *light, const scene::Camera *camera) = 0; + /** + * @en Set builtin ranged directional light and shadow constants. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCForwardLight in cc-forward-light.chunk. + * @zh 设置内置区间平行光与阴影常量。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-forward-light.chunk中的CCForwardLight。 + * @param light @en The ranged directional light. @zh 区间平行光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + */ virtual void setBuiltinRangedDirectionalLightConstants(const scene::RangedDirectionalLight *light, const scene::Camera *camera) = 0; + /** + * @en Set builtin directional light frustum and shadow constants. + * These constants are used in builtin shadow map, cascaded shadow map and planar shadow. + * For list of constants, please check CCShadow in cc-shadow.chunk and CCCSM in cc-csm.chunk. + * @zh 设置内置平行光视锥与阴影常量。 + * 这些常量用于内置的阴影、级联阴影与平面阴影。 + * 具体常量见cc-shadow.chunk中的CCShadow与cc-csm.chunk中的CCCSM。 + * @param light @en The directional light. @zh 平行光源 + * @param camera @en The camera instance to be set. @zh 当前相机 + * @param csmLevel @en Curent level of cascaded shadow map @zh 级联阴影等级 + */ virtual void setBuiltinDirectionalLightFrustumConstants(const scene::Camera *camera, const scene::DirectionalLight *light, uint32_t csmLevel) = 0; + /** + * @en Set builtin spot light frustum and shadow constants. + * These constants are used in builtin shadow map. + * For list of constants, please check CCShadow in cc-shadow.chunk. + * @zh 设置内置探照光视锥与阴影常量。 + * 这些常量用于内置的阴影。 + * 具体常量见cc-shadow.chunk中的CCShadow。 + * @param light @en The spot light. @zh 探照光源 + */ virtual void setBuiltinSpotLightFrustumConstants(const scene::SpotLight *light) = 0; void setBuiltinDirectionalLightFrustumConstants(const scene::Camera *camera, const scene::DirectionalLight *light) { setBuiltinDirectionalLightFrustumConstants(camera, light, 0); } }; +/** + * @en Scene + * A scene is an abstraction of content for rendering. + * @zh 场景。需要绘制的场景内容。 + */ class SceneBuilder : public Setter { public: SceneBuilder() noexcept = default; + /** + * @en Use the frustum information of light instead of camera. + * Often used in building shadow map. + * @zh 使用光源视锥进行投影,而不是用相机。常用于shadow map的生成。 + * @param light @en The light used for projection @zh 用于投影的光源 + * @param csmLevel @en Curent level of cascaded shadow map @zh 级联阴影等级 + * @param optCamera @en Additional scene culling camera. @zh 额外的场景裁切相机 + */ virtual void useLightFrustum(IntrusivePtr light, uint32_t csmLevel, const scene::Camera *optCamera) = 0; void useLightFrustum(IntrusivePtr light) { useLightFrustum(std::move(light), 0, nullptr); @@ -505,6 +598,16 @@ public: * @param sceneFlags @en Rendering flags of the scene @zh 场景渲染标志位 */ virtual void addSceneOfCamera(scene::Camera *camera, LightInfo light, SceneFlags sceneFlags) = 0; + /** + * @en Add the scene to be rendered. + * If SceneFlags.NON_BUILTIN is specified, no builtin constants will be set. + * Otherwise, related builtin constants will be set automatically. + * @zh 添加需要绘制的场景。 + * 如果设置了SceneFlags.NON_BUILTIN,那么不会自动设置内置常量。 + * @param camera @en Camera used for projection @zh 用于投影的相机 + * @param sceneFlags @en Rendering flags of the scene @zh 场景渲染标志位 + * @param light @en Light used for lighting computation @zh 用于光照的光源 + */ virtual SceneBuilder *addScene(const scene::Camera *camera, SceneFlags sceneFlags, scene::Light *light) = 0; /** * @en Render a full-screen quad. @@ -677,11 +780,30 @@ public: } }; +/** + * @en Basic multisample render pass builder + * Support resolve render targets and depth stencil. + * This render pass only contains one render subpass. + * If resolve targets are specified, they will be resolved at the end of the render pass. + * After resolving, the contents of multisample render targets and depth stencils are unspecified. + * @zh 基础的多重采样渲染通道。支持决算(Resolve)渲染目标与深度缓冲。 + * 此渲染通道只包含一个渲染子通道。 + * 如果添加了决算对象,那么在渲染通道结束时,会进行决算。 + * 决算后多重采样渲染目标与深度缓冲的内容是未定义的。 + */ class BasicMultisampleRenderPassBuilder : public BasicRenderPassBuilder { public: BasicMultisampleRenderPassBuilder() noexcept = default; + /** + * @en Set resolve render target + * @zh 设置决算渲染目标 + */ virtual void resolveRenderTarget(const ccstd::string &source, const ccstd::string &target) = 0; + /** + * @en Set resolve depth stencil + * @zh 设置决算深度模板缓冲 + */ virtual void resolveDepthStencil(const ccstd::string &source, const ccstd::string &target, gfx::ResolveMode depthMode, gfx::ResolveMode stencilMode) = 0; void resolveDepthStencil(const ccstd::string &source, const ccstd::string &target) { resolveDepthStencil(source, target, gfx::ResolveMode::SAMPLE_ZERO, gfx::ResolveMode::SAMPLE_ZERO); @@ -696,11 +818,13 @@ public: * Basic pipeline provides basic rendering features which are supported on all platforms. * User can register resources which will be used in the render graph. * Theses resources are generally read and write, and will be managed by the pipeline. + * The residency information of resource should not be changed after registration. * In each frame, user can create a render graph to be executed by the pipeline. * @zh 基础渲染管线。 * 基础渲染管线提供基础的渲染能力,能在全平台使用。 * 用户可以在渲染管线中注册资源,这些资源将由管线托管,用于render graph。 * 这些资源一般是可读写的资源。 + * 资源在注册后,不能更改驻留属性。 * 用户可以每帧构建一个render graph,然后交由管线执行。 */ class BasicPipeline : public PipelineRuntime { @@ -721,6 +845,10 @@ public: * @zh 结束管线构建 */ virtual void endSetup() = 0; + /** + * @en Enable cpu culling of objects affected by the light. Enabled by default. + * @zh 光照计算时,裁切受光源影响的物件。默认开启。 + */ virtual bool getEnableCpuLightCulling() const = 0; virtual void setEnableCpuLightCulling(bool enable) = 0; /** @@ -731,8 +859,8 @@ public: */ virtual bool containsResource(const ccstd::string &name) const = 0; /** - * @en Add render window to the pipeline. - * @zh 注册渲染窗口(RenderWindow) + * @en Add or update render window to the pipeline. + * @zh 注册或更新渲染窗口(RenderWindow) * @param name @en Resource name @zh 资源名字 * @param format @en Expected format of the render window @zh 期望的渲染窗口格式 * @param width @en Expected width of the render window @zh 期望的渲染窗口宽度 @@ -742,6 +870,7 @@ public: */ virtual uint32_t addRenderWindow(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, scene::RenderWindow *renderWindow) = 0; /** + * @deprecated Method will be removed in 3.9.0 * @en Update render window information. * When render window information is updated, such as resized, user should notify the pipeline. * @zh 更新渲染窗口信息。当渲染窗口发生更新时,用户应通知管线。 @@ -749,8 +878,8 @@ public: */ virtual void updateRenderWindow(const ccstd::string &name, scene::RenderWindow *renderWindow) = 0; /** - * @en Add 2D render target. - * @zh 添加2D渲染目标 + * @en Add or update 2D render target. + * @zh 添加或更新2D渲染目标 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -760,8 +889,8 @@ public: */ virtual uint32_t addRenderTarget(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, ResourceResidency residency) = 0; /** - * @en Add 2D depth stencil. - * @zh 添加2D深度模板缓冲 + * @en Add or update 2D depth stencil. + * @zh 添加或更新2D深度模板缓冲 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -771,6 +900,7 @@ public: */ virtual uint32_t addDepthStencil(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, ResourceResidency residency) = 0; /** + * @deprecated Method will be removed in 3.9.0 * @en Update render target information. * @zh 更新渲染目标的信息 * @param name @en Resource name @zh 资源名字 @@ -780,6 +910,7 @@ public: */ virtual void updateRenderTarget(const ccstd::string &name, uint32_t width, uint32_t height, gfx::Format format) = 0; /** + * @deprecated Method will be removed in 3.9.0 * @en Update depth stencil information. * @zh 更新深度模板缓冲的信息 * @param name @en Resource name @zh 资源名字 @@ -788,13 +919,103 @@ public: * @param format @en Format of the resource @zh 资源的格式 */ virtual void updateDepthStencil(const ccstd::string &name, uint32_t width, uint32_t height, gfx::Format format) = 0; + /** + * @en Add or update buffer. + * @zh 添加或更新缓冲 + * @param name @en Resource name @zh 资源名字 + * @param size @en Size of the resource in bytes @zh 资源的大小 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ virtual uint32_t addBuffer(const ccstd::string &name, uint32_t size, ResourceFlags flags, ResourceResidency residency) = 0; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update buffer information. + * @zh 更新缓冲的信息 + * @param name @en Resource name @zh 资源名字 + * @param size @en Size of the resource in bytes @zh 资源的大小 + */ virtual void updateBuffer(const ccstd::string &name, uint32_t size) = 0; + /** + * @en Add or update external texture. + * Must be readonly. + * @zh 添加或更新外部的贴图。贴图必须是只读的。 + * @param name @en Resource name @zh 资源名字 + * @param texture @en External unmanaged texture @zh 外部不受管理的贴图 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @returns Resource ID + */ virtual uint32_t addExternalTexture(const ccstd::string &name, gfx::Texture *texture, ResourceFlags flags) = 0; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update external texture information. + * @zh 更新外部的贴图信息 + * @param name @en Resource name @zh 资源名字 + * @param texture @en External unmanaged texture @zh 外部不受管理的贴图 + */ virtual void updateExternalTexture(const ccstd::string &name, gfx::Texture *texture) = 0; + /** + * @en Add or update texture. + * @zh 添加或更新外部的贴图。 + * @param name @en Resource name @zh 资源名字 + * @param type @en Type of the texture @zh 贴图的类型 + * @param format @en Format of the texture @zh 贴图的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 贴图的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 贴图的采样数目 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ virtual uint32_t addTexture(const ccstd::string &name, gfx::TextureType type, gfx::Format format, uint32_t width, uint32_t height, uint32_t depth, uint32_t arraySize, uint32_t mipLevels, gfx::SampleCount sampleCount, ResourceFlags flags, ResourceResidency residency) = 0; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update texture information. + * @zh 更新贴图信息 + * @param name @en Resource name @zh 资源名字 + * @param format @en Format of the texture @zh 贴图的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 贴图的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 贴图的采样数目 + */ virtual void updateTexture(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, uint32_t depth, uint32_t arraySize, uint32_t mipLevels, gfx::SampleCount sampleCount) = 0; + /** + * @en Add or update resource. + * @zh 添加或更新资源 + * @param name @en Resource name @zh 资源名字 + * @param dimension @en Dimension of the resource @zh 资源的维度 + * @param format @en Format of the texture @zh 资源的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 资源的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 资源的采样数目 + * @param flags @en Flags of the resource @zh 资源的标志位 + * @param residency @en Residency of the resource. @zh 资源的驻留性 + * @returns Resource ID + */ virtual uint32_t addResource(const ccstd::string &name, ResourceDimension dimension, gfx::Format format, uint32_t width, uint32_t height, uint32_t depth, uint32_t arraySize, uint32_t mipLevels, gfx::SampleCount sampleCount, ResourceFlags flags, ResourceResidency residency) = 0; + /** + * @deprecated Method will be removed in 3.9.0 + * @en Update resource information. + * @zh 更新资源信息 + * @param name @en Resource name @zh 资源名字 + * @param format @en Format of the texture @zh 资源的格式 + * @param width @en Width of the resource @zh 资源的宽度 + * @param height @en Height of the resource @zh 资源的高度 + * @param depth @en Depth of the resource @zh 资源的深度 + * @param arraySize @en Size of the array @zh 资源数组的大小 + * @param mipLevels @en Mip levels of the texture @zh 资源的Mipmap数目 + * @param sampleCount @en Sample count of the texture @zh 资源的采样数目 + */ virtual void updateResource(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, uint32_t depth, uint32_t arraySize, uint32_t mipLevels, gfx::SampleCount sampleCount) = 0; /** * @engineInternal @@ -861,6 +1082,11 @@ public: * @param copyPairs @en Array of copy source and target @zh 拷贝来源与目标的数组 */ virtual void addCopyPass(const ccstd::vector ©Pairs) = 0; + /** + * @en Builtin reflection probe pass + * @zh 添加内置环境光反射通道 + * @param camera @en Capturing camera @zh 用于捕捉的相机 + */ virtual void addBuiltinReflectionProbePass(const scene::Camera *camera) = 0; /** * @engineInternal @@ -1253,11 +1479,29 @@ public: } }; +/** + * @en Multisample render pass builder + * @zh 多重采样渲染通道。 + */ class MultisampleRenderPassBuilder : public BasicMultisampleRenderPassBuilder { public: MultisampleRenderPassBuilder() noexcept = default; + /** + * @en Add storage buffer + * @zh 添加存储缓冲 + * @param name @en Name of the storage buffer @zh 存储缓冲的名字 + * @param accessType @en Access type of the buffer in the render pass @zh 渲染通道中缓冲的读写状态 + * @param slotName @en name of the descriptor in shader @zh 着色器中描述符的名字 + */ virtual void addStorageBuffer(const ccstd::string &name, AccessType accessType, const ccstd::string &slotName) = 0; + /** + * @en Add storage image + * @zh 添加存储贴图 + * @param name @en Name of the storage texture @zh 存储贴图的名字 + * @param accessType @en Access type of the texture in the render pass @zh 渲染通道中贴图的读写状态 + * @param slotName @en name of the descriptor in shader @zh 着色器中描述符的名字 + */ virtual void addStorageImage(const ccstd::string &name, AccessType accessType, const ccstd::string &slotName) = 0; }; @@ -1354,17 +1598,17 @@ public: Pipeline() noexcept = default; /** - * @en Add storage buffer. - * @zh 添加存储缓冲 + * @en Add or update storage buffer. + * @zh 添加或更新存储缓冲 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 - * @param size @en Size of the resource @zh 资源的大小 + * @param size @en Size of the resource in bytes @zh 资源的大小 * @param residency @en Residency of the resource. @zh 资源的驻留性 */ virtual uint32_t addStorageBuffer(const ccstd::string &name, gfx::Format format, uint32_t size, ResourceResidency residency) = 0; /** - * @en Add 2D storage texture - * @zh 添加2D存储贴图 + * @en Add or update 2D storage texture + * @zh 添加或更新2D存储贴图 * @param name @en Resource name @zh 资源名字 * @param format @en Format of the resource @zh 资源的格式 * @param width @en Width of the resource @zh 资源的宽度 @@ -1374,8 +1618,8 @@ public: virtual uint32_t addStorageTexture(const ccstd::string &name, gfx::Format format, uint32_t width, uint32_t height, ResourceResidency residency) = 0; /** * @experimental - * @en Add 2D shading rate texture - * @zh 添加2D着色率贴图 + * @en Add or update 2D shading rate texture + * @zh 添加或更新2D着色率贴图 * @param name @en Resource name @zh 资源名字 * @param width @en Width of the resource @zh 资源的宽度 * @param height @en Height of the resource @zh 资源的高度 @@ -1386,7 +1630,7 @@ public: * @en Update storage buffer information. * @zh 更新存储缓冲的信息 * @param name @en Resource name @zh 资源名字 - * @param size @en Size of the resource @zh 资源的大小 + * @param size @en Size of the resource in bytes @zh 资源的大小 * @param format @en Format of the resource @zh 资源的格式 */ virtual void updateStorageBuffer(const ccstd::string &name, uint32_t size, gfx::Format format) = 0; @@ -1458,7 +1702,15 @@ public: * @param movePairs @en Array of move source and target @zh 移动来源与目标的数组 */ virtual void addMovePass(const ccstd::vector &movePairs) = 0; + /** + * @experimental + * @engineInternal + */ virtual void addBuiltinGpuCullingPass(const scene::Camera *camera, const std::string &hzbName, const scene::Light *light) = 0; + /** + * @experimental + * @engineInternal + */ virtual void addBuiltinHzbGenerationPass(const std::string &sourceDepthStencilName, const std::string &targetHzbName) = 0; /** * @experimental @@ -1515,6 +1767,10 @@ public: * @param pipeline @en Current render pipeline @zh 当前管线 */ virtual void setup(const ccstd::vector &cameras, BasicPipeline *pipeline) = 0; + /** + * @en Callback of pipeline state changed + * @zh 渲染管线状态更新的回调 + */ virtual void onGlobalPipelineStateChanged() = 0; };