diff --git a/cocos/3d/lights/spot-light-component.ts b/cocos/3d/lights/spot-light-component.ts index 669d9c503a..ce580491e6 100644 --- a/cocos/3d/lights/spot-light-component.ts +++ b/cocos/3d/lights/spot-light-component.ts @@ -210,8 +210,8 @@ export class SpotLight extends Light { } /** - * @en get or set shadow pcf. - * @zh 获取或者设置阴影pcf等级。 + * @en The pcf level of the shadow generation. + * @zh 获取或者设置阴影 pcf 等级。 */ @visible(() => (legacyCC.director.root as Root).pipeline.pipelineSceneData.shadows.type === ShadowType.ShadowMap) @property({ group: { name: 'DynamicShadowSettings', displayOrder: 2 } }) @@ -228,8 +228,8 @@ export class SpotLight extends Light { } /** - * @en get or set shadow map sampler offset - * @zh 获取或者设置阴影纹理偏移值 + * @en The depth offset of shadow to avoid moire pattern artifacts + * @zh 阴影的深度偏移, 可以减弱跨像素导致的条纹状失真 */ @visible(() => (legacyCC.director.root as Root).pipeline.pipelineSceneData.shadows.type === ShadowType.ShadowMap) @property({ group: { name: 'DynamicShadowSettings', displayOrder: 3 } }) @@ -246,7 +246,7 @@ export class SpotLight extends Light { } /** - * @en get or set normal bias. + * @en The normal bias of the shadow map. * @zh 设置或者获取法线偏移。 */ @visible(() => (legacyCC.director.root as Root).pipeline.pipelineSceneData.shadows.type === ShadowType.ShadowMap) diff --git a/cocos/core/components/camera-component.ts b/cocos/core/components/camera-component.ts index 3e70c6bc85..d6b7964d61 100644 --- a/cocos/core/components/camera-component.ts +++ b/cocos/core/components/camera-component.ts @@ -23,8 +23,6 @@ THE SOFTWARE. */ - - import { EDITOR } from 'internal:constants'; import { ccclass, help, executeInEditMode, menu, tooltip, displayOrder, type, serializable, visible } from 'cc.decorator'; import { RenderTexture } from '../assets/render-texture'; @@ -82,12 +80,40 @@ export declare namespace Camera { @menu('Rendering/Camera') @executeInEditMode export class Camera extends Component { + /** + * @en The projection type enumeration of the camera. + * @zh 相机的投影类型枚举。 + */ public static ProjectionType = ProjectionType; + /** + * @en The axis type of the fov + * @zh FOV 的轴向枚举 + */ public static FOVAxis = FOVAxis; + /** + * @en The clear flag enumeration of the camera. + * @zh 相机的清除标志位枚举。 + */ public static ClearFlag = ClearFlag; + /** + * @en The aperture value's enumeration of the camera. + * @zh 相机的光圈值枚举。 + */ public static Aperture = Aperture; + /** + * @en The shutter value's enumeration of the camera. + * @zh 相机的快门值枚举。 + */ public static Shutter = Shutter; + /** + * @en The ISO value's enumeration of the camera. + * @zh 相机的感光度值枚举。 + */ public static ISO = ISO; + /** + * @en The event for target texture changing. + * @zh 目标贴图修改的事件。 + */ public static TARGET_TEXTURE_CHANGE = 'tex-change'; @serializable @@ -131,6 +157,10 @@ export class Camera extends Component { protected _inEditorMode = false; protected _flows: string[] | undefined = undefined; + /** + * @en The render camera representation. + * @zh 渲染场景中的相机对象。 + */ get camera () { return this._camera!; } @@ -444,6 +474,9 @@ export class Camera extends Component { if (this._camera) { this._camera.screenScale = val; } } + /** + * @internal + */ get inEditorMode () { return this._inEditorMode; } diff --git a/cocos/core/geometry/deprecated-3.0.0.ts b/cocos/core/geometry/deprecated-3.0.0.ts index c0a218d409..55432581fb 100644 --- a/cocos/core/geometry/deprecated-3.0.0.ts +++ b/cocos/core/geometry/deprecated-3.0.0.ts @@ -152,9 +152,9 @@ function deprecatedClassMessage (oldClassName: string, newClassName) { /** * @en - * Alias of [[Line]] + * Alias of [[geometry.Line]] * @zh - * [[Line]] 别名类 + * [[geometry.Line]] 别名类 * * @deprecated Since v3.0, please use Line instead */ @@ -167,10 +167,10 @@ export class line extends Line { /** * @en - * Alias of [[Plane]] + * Alias of [[geometry.Plane]] * * @zh - * [[Plane]] 别名类 + * [[geometry.Plane]] 别名类 * * @deprecated Since v3.0, please use Plane instead */ @@ -183,9 +183,9 @@ export class plane extends Plane { /** * @en - * Alias of [[Ray]] + * Alias of [[geometry.Ray]] * @zh - * [[Ray]] 别名类 + * [[geometry.Ray]] 别名类 * @deprecated Since v3.0, please use Ray instead */ export class ray extends Ray { @@ -197,10 +197,10 @@ export class ray extends Ray { /** * @en - * Alias of [[Triangle]] + * Alias of [[geometry.Triangle]] * * @zh - * [[Triangle]] 别名类 + * [[geometry.Triangle]] 别名类 * @deprecated Since v3.0, please use Triangle instead */ export class triangle extends Triangle { @@ -212,10 +212,10 @@ export class triangle extends Triangle { /** * @en - * Alias of [[Sphere]] + * Alias of [[geometry.Sphere]] * * @zh - * [[Sphere]] 别名类 + * [[geometry.Sphere]] 别名类 * @deprecated Since v3.0, please use Sphere instead */ export class sphere extends Sphere { @@ -227,10 +227,10 @@ export class sphere extends Sphere { /** * @en - * Alias of [[AABB]] + * Alias of [[geometry.AABB]] * * @zh - * [[AABB]] 别名类 + * [[geometry.AABB]] 别名类 * @deprecated Since v3.0, please use AABB instead */ export class aabb extends AABB { @@ -242,10 +242,10 @@ export class aabb extends AABB { /** * @en - * Alias of [[OBB]] + * Alias of [[geometry.OBB]] * * @zh - * [[OBB]] 别名类 + * [[geometry.OBB]] 别名类 * @deprecated Since v3.0, please use OBB instead */ export class obb extends OBB { @@ -257,10 +257,10 @@ export class obb extends OBB { /** * @en - * Alias of [[Capsule]] + * Alias of [[geometry.Capsule]] * * @zh - * [[Capsule]] 别名类 + * [[geometry.Capsule]] 别名类 * @deprecated Since v3.0, please use Capsule instead */ export class capsule extends Capsule { @@ -272,10 +272,10 @@ export class capsule extends Capsule { /** * @en - * Alias of [[Frustum]] + * Alias of [[geometry.Frustum]] * * @zh - * [[Frustum]] 别名类 + * [[geometry.Frustum]] 别名类 * @deprecated Since v3.0, please use Frustum instead */ export class frustum extends Frustum { diff --git a/cocos/core/platform/macro.ts b/cocos/core/platform/macro.ts index 45c7b6a541..d6381bbe2a 100644 --- a/cocos/core/platform/macro.ts +++ b/cocos/core/platform/macro.ts @@ -842,7 +842,16 @@ const KEY = { */ dpadCenter: 1005, }; - +/** + * @en + * Predefined constants, see [[Macro]] for detailed contents. + * @zh + * 预定义常量,具体内容参考 [[Macro]] 文档。 + */ +/** + * @en Interface declaration for predefined constants, for usage you should be importing [[macro]] directly. + * @zh 预定义常量的接口声明,实际使用应该直接导入 [[macro]]。 + */ interface Macro { /** * @en @@ -1065,9 +1074,9 @@ interface Macro { /** * @en - * Predefined constants + * Predefined constants, see [[Macro]] for detailed contents. * @zh - * 预定义常量。 + * 预定义常量,具体内容参考 [[Macro]] 文档。 */ const macro: Macro = { SUPPORT_TEXTURE_FORMATS, diff --git a/cocos/core/renderer/scene/ambient.ts b/cocos/core/renderer/scene/ambient.ts index cd275edb4a..9c1197e490 100644 --- a/cocos/core/renderer/scene/ambient.ts +++ b/cocos/core/renderer/scene/ambient.ts @@ -29,8 +29,22 @@ import { legacyCC } from '../../global-exports'; import type { AmbientInfo } from '../../scene-graph/scene-globals'; import { NativeAmbient } from '../native-scene'; +/** + * @en Ambient lighting representation in the render scene. + * The initial data is setup in [[SceneGlobals.ambient]]. + * @zh 渲染场景中的环境光照设置。 + * 初始值是由 [[SceneGlobals.ambient]] 设置的。 + */ export class Ambient { + /** + * @en Default sun illuminance + * @zh 默认太阳亮度 + */ public static SUN_ILLUM = 65000.0; + /** + * @en Default sky illuminance + * @zh 默认天空亮度 + */ public static SKY_ILLUM = 20000.0; /** @@ -58,7 +72,6 @@ export class Ambient { return this._skyColorLDR; } } - set skyColor (color: Vec4) { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -83,7 +96,6 @@ export class Ambient { return this._skyIllumLDR; } } - set skyIllum (illum: number) { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -107,7 +119,6 @@ export class Ambient { return this._groundAlbedoLDR; } } - set groundAlbedo (color: Vec4) { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -130,8 +141,14 @@ export class Ambient { protected _skyIllumLDR = 0; protected _enabled = false; + /** + * @internal + */ protected declare _nativeObj: NativeAmbient | null; + /** + * @internal + */ get native (): NativeAmbient { return this._nativeObj!; } diff --git a/cocos/core/renderer/scene/camera.ts b/cocos/core/renderer/scene/camera.ts index 9ab331fd0f..58be79ec00 100644 --- a/cocos/core/renderer/scene/camera.ts +++ b/cocos/core/renderer/scene/camera.ts @@ -118,8 +118,455 @@ export const SKYBOX_FLAG = ClearFlagBit.STENCIL << 1; const correctionMatrices: Mat4[] = []; +/** + * @en The render camera representation in the render scene, it's managed by [[CameraComponent]] + * @zh 渲染场景中的相机对象,由项目层的 [[CameraComponent]] 管理。 + */ export class Camera { + /** + * @en This exposure value corresponding to default standard camera exposure parameters. + * @zh 默认相机的曝光值。 + */ + public static get standardExposureValue () { + return 1.0 / 38400.0; + } + + /** + * @en The luminance unit scale used by area lights. + * @zh 默认局部光源使用的亮度单位缩放。 + */ + public static get standardLightMeterScale () { + return 10000.0; + } + + /** + * @en The name of the camera + * @zh 相机的名称 + */ + get name () { + return this._name; + } + + /** + * @en The render scene to which the camera is attached + * @zh 相机所挂载的场景 + */ + get scene () { + return this._scene; + } + + /** + * @en The node of the camera which determines its transform in world space. + * @zh 相机绑定的节点,决定了它在世界空间的变换矩阵 + */ + set node (val: Node) { + this._node = val; + if (JSB) { + this._nativeObj!.node = this._node.native; + } + } + get node () { + return this._node!; + } + + /** + * @en The render window of the camera + * @zh 相机关联的渲染窗口 + */ + set window (val) { + this._window = val; + if (JSB && val) { + this._nativeObj!.window = this._window.native; + } + } + get window () { + return this._window!; + } + + /** + * @en Whether the camera is enabled, a disabled camera won't be processed in the render pipeline. + * @zh 相机是否启用,未启用的相机不会被渲染 + */ + set enabled (val) { + this._enabled = val; + } + get enabled () { + return this._enabled; + } + + /** + * @en Visibility mask of the camera, declaring a set of node layers that will be visible to this camera. + * @zh 相机的可见性掩码,声明在当前相机中可见的节点层级集合。 + */ + set visibility (vis: number) { + this._visibility = vis; + if (JSB) { + this._nativeObj!.visibility = this._visibility; + } + } + get visibility (): number { + return this._visibility; + } + + /** + * @en Render priority of the camera. Cameras with higher depth are rendered after cameras with lower depth. + * @zh 相机的渲染优先级,值越小越优先渲染。 + */ + get priority (): number { + return this._priority; + } + + set priority (val: number) { + this._priority = val; + } + + /** + * @en The width of the camera's view size + * @zh 相机的视图宽度 + */ + get width () { + return this._width; + } + + /** + * @en The height of the camera's view size + * @zh 相机的视图高度 + */ + get height () { + return this._height; + } + + /** + * @en The world position of the camera + * @zh 相机的世界坐标 + */ + set position (val) { + this._position = val; + if (JSB) { + this._nativeObj!.position = this._position; + } + } + get position () { + return this._position; + } + + /** + * @en The forward vector of the camera's look direction + * @zh 指向相机观察方向的向量 + */ + set forward (val) { + this._forward = val; + if (JSB) { + this._nativeObj!.forward = this._forward; + } + } + get forward () { + return this._forward; + } + + /** + * @en Camera aperture, controls the exposure parameter. + * @zh 相机光圈,影响相机的曝光参数。 + */ + set aperture (val: CameraAperture) { + this._aperture = val; + this._apertureValue = FSTOPS[this._aperture]; + this.updateExposure(); + } + get aperture (): CameraAperture { + return this._aperture; + } + + /** + * @en Camera aperture value. + * @zh 相机光圈值。 + */ + get apertureValue (): number { + return this._apertureValue; + } + + /** + * @en Camera shutter, controls the exposure parameter. + * @zh 相机快门,影响相机的曝光参数。 + */ + set shutter (val: CameraShutter) { + this._shutter = val; + this._shutterValue = SHUTTERS[this._shutter]; + this.updateExposure(); + } + get shutter (): CameraShutter { + return this._shutter; + } + + /** + * @en Camera shutter value. + * @zh 相机快门值。 + */ + get shutterValue (): number { + return this._shutterValue; + } + + /** + * @en Camera ISO, controls the exposure parameter. + * @zh 相机感光度,影响相机的曝光参数。 + */ + set iso (val: CameraISO) { + this._iso = val; + this._isoValue = ISOS[this._iso]; + this.updateExposure(); + } + get iso (): CameraISO { + return this._iso; + } + + /** + * @en Camera ISO value. + * @zh 相机感光度值。 + */ + get isoValue (): number { + return this._isoValue; + } + + /** + * @en The calculated exposure of the camera + * @zh 相机的曝光参数 + */ + get exposure (): number { + return this._exposure; + } + + /** + * @en Clearing flags of the camera, specifies which part of the framebuffer will be actually cleared every frame. + * @zh 相机的缓冲清除标志位,指定帧缓冲的哪部分要每帧清除。 + */ + get clearFlag () : ClearFlags { + return this._clearFlag; + } + set clearFlag (flag: ClearFlags) { + this._clearFlag = flag; + if (JSB) { + this._nativeObj!.clearFlag = flag; + } + } + + /** + * @en Clearing color of the camera. + * @zh 相机的颜色缓冲默认值。 + */ + set clearColor (val) { + this._clearColor.x = val.x; + this._clearColor.y = val.y; + this._clearColor.z = val.z; + this._clearColor.w = val.w; + if (JSB) { + this._nativeObj!.clearColor = this._clearColor; + } + } + get clearColor () { + return this._clearColor as IVec4Like; + } + + /** + * @en Clearing depth of the camera. + * @zh 相机的深度缓冲默认值。 + */ + get clearDepth () : number { + return this._clearDepth; + } + set clearDepth (depth: number) { + this._clearDepth = depth; + if (JSB) { + this._nativeObj!.clearDepth = depth; + } + } + + /** + * @en Clearing stencil of the camera. + * @zh 相机的模板缓冲默认值。 + */ + get clearStencil () : number { + return this._clearStencil; + } + set clearStencil (stencil: number) { + this._clearStencil = stencil; + if (JSB) { + this._nativeObj!.clearStencil = stencil; + } + } + + /** + * @en The projection type of the camera. + * @zh 相机的投影类型。 + */ + set projectionType (val) { + this._proj = val; + this._isProjDirty = true; + } + get projectionType () { + return this._proj; + } + + /** + * @en The aspect ratio of the camera + * @zh 相机视图的长宽比 + */ + get aspect () { + return this._aspect; + } + + /** + * @en The viewport height of the orthogonal type camera. + * @zh 正交相机的视角高度。 + */ + set orthoHeight (val) { + this._orthoHeight = val; + this._isProjDirty = true; + } + get orthoHeight () { + return this._orthoHeight; + } + + /** + * @en The axis on which the FOV would be fixed regardless of screen aspect changes. + * @zh 指定视角的固定轴向,在此轴上不会跟随屏幕长宽比例变化。 + */ + set fovAxis (axis) { + this._fovAxis = axis; + this._isProjDirty = true; + } + get fovAxis () { + return this._fovAxis; + } + + /** + * @en Field of view of the camera. + * @zh 相机的视角大小。 + */ + set fov (fov) { + this._fov = fov; + if (JSB) { + this._nativeObj!.fov = fov; + } + this._isProjDirty = true; + } + get fov () { + return this._fov; + } + + /** + * @en Near clipping distance of the camera, should be as large as possible within acceptable range. + * @zh 相机的近裁剪距离,应在可接受范围内尽量取最大。 + */ + set nearClip (nearClip) { + this._nearClip = nearClip; + if (JSB) { + this._nativeObj!.nearClip = this._nearClip; + } + this._isProjDirty = true; + } + get nearClip () { + return this._nearClip; + } + + /** + * @en Far clipping distance of the camera, should be as small as possible within acceptable range. + * @zh 相机的远裁剪距离,应在可接受范围内尽量取最小。 + */ + set farClip (farClip) { + this._farClip = farClip; + if (JSB) { + this._nativeObj!.farClip = this._farClip; + } + this._isProjDirty = true; + } + get farClip () { + return this._farClip; + } + + /** + * @en The viewport rect of the camera, pre-rotated (i.e. always in identity/portrait mode) if possible. + * @zh 相机的视口矩形,如果设备允许的话,这个视口会永远保持竖屏状态,由渲染流程保障旋转的正确。 + */ + get viewport () { + return this._viewport; + } + set viewport (val) { + warnID(8302); + this.setViewportInOrientedSpace(val); + } + + /** + * @en The view frustum of the camera + * @zh 相机的视锥体 + */ + set frustum (val) { + this._frustum = val; + if (JSB) { + this._nativeObj!.frustum = this._frustum; + } + } + get frustum () { + return this._frustum; + } + + /** + * @en The view matrix of the camera + * @zh 相机的视图矩阵 + */ + get matView () { + return this._matView; + } + + /** + * @en The projection matrix of the camera + * @zh 相机的投影矩阵 + */ + get matProj () { + return this._matProj; + } + + /** + * @en The inverse of the projection matrix of the camera + * @zh 相机的逆投影矩阵 + */ + get matProjInv () { + return this._matProjInv; + } + + /** + * @en The view projection matrix of the camera + * @zh 相机的视图投影矩阵 + */ + get matViewProj () { + return this._matViewProj; + } + + /** + * @en The inverse of the view projection matrix of the camera + * @zh 相机的逆视图投影矩阵 + */ + get matViewProjInv () { + return this._matViewProjInv; + } + + /** + * @internal + */ + get native (): any { + return this._nativeObj; + } + + /** + * @en Whether the camera is fixed size or matching the window size. + * @zh 相机是固定尺寸还是跟随屏幕尺寸 + */ public isWindowSize = true; + + /** + * @en Scale of the internal buffer size, + * set to 1 to keep the same with the canvas size. + * @zh 相机内部缓冲尺寸的缩放值, 1 为与 canvas 尺寸相同。 + */ public screenScale: number; private _device: Device; @@ -154,7 +601,6 @@ export class Camera { private _shutterValue = 0.0; private _iso: CameraISO = CameraISO.ISO100; private _isoValue = 0.0; - private _ec = 0.0; private declare _nativeObj: NativeCamera | null; private _window: RenderWindow | null = null; private _width = 1; @@ -164,6 +610,7 @@ export class Camera { private _visibility = CAMERA_DEFAULT_MASK; private _exposure = 0; private _clearStencil = 0; + constructor (device: Device) { this._device = device; this._apertureValue = FSTOPS[this._aperture]; @@ -216,6 +663,9 @@ export class Camera { if (JSB) this._nativeObj!.aspect = this._aspect; } + /** + * @internal + */ protected _init (info: ICameraInfo) { if (JSB) { this._nativeObj = new NativeCamera(); @@ -225,19 +675,16 @@ export class Camera { } /** - * this exposure value corresponding to default standard camera exposure parameters + * @internal */ - public static get standardExposureValue () { - return 1.0 / 38400.0; + protected _destroy () { + if (JSB) this._nativeObj = null; } /** - * luminance unit scale used by area lights + * @en Initialize the camera, normally you shouldn't invoke this function, it's managed automatically. + * @zh 初始化相机,开发者通常不应该使用这个方法,初始化流程是自动管理的。 */ - public static get standardLightMeterScale () { - return 10000.0; - } - public initialize (info: ICameraInfo) { this._init(info); this.node = info.node; @@ -254,10 +701,10 @@ export class Camera { this.changeTargetWindow(info.window); } - protected _destroy () { - if (JSB) this._nativeObj = null; - } - + /** + * @en Destroy the camera, you shouldn't invoke this function, it's managed by the render scene. + * @zh 销毁相机,开发者不应该使用这个方法,销毁流程是由 RenderScene 管理的。 + */ public destroy () { if (this._window) { this._window.detachCamera(this); @@ -267,17 +714,32 @@ export class Camera { this._destroy(); } + /** + * @en Attach the camera to the given render scene so that it will be rendered in it. + * @zh 将相机添加到相关的渲染场景中,以便可以被渲染器渲染。 + * @param scene @en The render scene @zh 渲染场景 + */ public attachToScene (scene: RenderScene) { this._enabled = true; this._setScene(scene); } + /** + * @en Detach the camera from previously attached render scene. It will no longer be rendered. + * @zh 将相机从之前设置的渲染场景移除,之后将不会再被渲染。 + */ public detachFromScene () { this._enabled = false; this._setScene(null); } - public resize (width: number, height: number) { + /** + * @en Resize the view size of the camera. + * @zh 重置相机视图尺寸 + * @param width The width of the view size + * @param height The height of the view size + */ + public resize (width: number, height: number): void { if (!this._window) return; this._setWidth(width); @@ -285,6 +747,12 @@ export class Camera { this._updateAspect(); } + /** + * @en Set a fixed size for the camera view. + * @zh 设置固定相机视图尺寸 + * @param width The width of the view size + * @param height The height of the view size + */ public setFixedSize (width: number, height: number) { this._setWidth(width); this._setHeight(height); @@ -292,7 +760,10 @@ export class Camera { this.isWindowSize = false; } - // Editor specific gizmo camera logic + /** + * Editor specific gizmo camera logic + * @internal + */ public syncCameraEditor (camera) { if (EDITOR) { this.position = camera.position; @@ -304,7 +775,12 @@ export class Camera { } } - public update (forceUpdate = false) { // for lazy eval situations like the in-editor preview + /** + * @en Update the camera's builtin matrixes + * @zh 更新相机的视图、投影等矩阵 + * @param forceUpdate If force update, then dirty flag will be ignored + */ + public update (forceUpdate = false): void { // for lazy eval situations like the in-editor preview if (!this._node) return; let viewProjDirty = false; @@ -366,116 +842,9 @@ export class Camera { } } - set node (val: Node) { - this._node = val; - if (JSB) { - this._nativeObj!.node = this._node.native; - } - } - - get node () { - return this._node!; - } - - set enabled (val) { - this._enabled = val; - } - - get enabled () { - return this._enabled; - } - - set orthoHeight (val) { - this._orthoHeight = val; - this._isProjDirty = true; - } - - get orthoHeight () { - return this._orthoHeight; - } - - set projectionType (val) { - this._proj = val; - this._isProjDirty = true; - } - - get projectionType () { - return this._proj; - } - - set fovAxis (axis) { - this._fovAxis = axis; - this._isProjDirty = true; - } - - get fovAxis () { - return this._fovAxis; - } - - set fov (fov) { - this._fov = fov; - if (JSB) { - this._nativeObj!.fov = fov; - } - this._isProjDirty = true; - } - - get fov () { - return this._fov; - } - - set nearClip (nearClip) { - this._nearClip = nearClip; - if (JSB) { - this._nativeObj!.nearClip = this._nearClip; - } - this._isProjDirty = true; - } - - get nearClip () { - return this._nearClip; - } - - set farClip (farClip) { - this._farClip = farClip; - if (JSB) { - this._nativeObj!.farClip = this._farClip; - } - this._isProjDirty = true; - } - - get farClip () { - return this._farClip; - } - - set clearColor (val) { - this._clearColor.x = val.x; - this._clearColor.y = val.y; - this._clearColor.z = val.z; - this._clearColor.w = val.w; - if (JSB) { - this._nativeObj!.clearColor = this._clearColor; - } - } - - get clearColor () { - return this._clearColor as IVec4Like; - } - /** - * Pre-rotated (i.e. always in identity/portrait mode) if possible. - */ - get viewport () { - return this._viewport; - } - - set viewport (val) { - warnID(8302); - this.setViewportInOrientedSpace(val); - } - - /** - * Set the viewport in oriented space (local to screen rotations) + * @en Set the viewport in oriented space (equal to the actual screen rotation) + * @zh 在目标朝向空间(实际屏幕朝向)内设置相机视口 */ public setViewportInOrientedSpace (val: Rect) { const { x, width, height } = val; @@ -522,199 +891,11 @@ export class Camera { this.resize(this.width, this.height); } - get scene () { - return this._scene; - } - - get name () { - return this._name; - } - - get width () { - return this._width; - } - - get height () { - return this._height; - } - - get aspect () { - return this._aspect; - } - - get matView () { - return this._matView; - } - - get matProj () { - return this._matProj; - } - - get matProjInv () { - return this._matProjInv; - } - - get matViewProj () { - return this._matViewProj; - } - - get matViewProjInv () { - return this._matViewProjInv; - } - - set frustum (val) { - this._frustum = val; - if (JSB) { - this._nativeObj!.frustum = this._frustum; - } - } - - get frustum () { - return this._frustum; - } - - set window (val) { - this._window = val; - if (JSB && val) { - this._nativeObj!.window = this._window.native; - } - } - - get window () { - return this._window!; - } - - set forward (val) { - this._forward = val; - if (JSB) { - this._nativeObj!.forward = this._forward; - } - } - - get forward () { - return this._forward; - } - - set position (val) { - this._position = val; - if (JSB) { - this._nativeObj!.position = this._position; - } - } - - get position () { - return this._position; - } - - set visibility (vis: number) { - this._visibility = vis; - if (JSB) { - this._nativeObj!.visibility = this._visibility; - } - } - get visibility (): number { - return this._visibility; - } - - get priority (): number { - return this._priority; - } - - set priority (val: number) { - this._priority = val; - } - - set aperture (val: CameraAperture) { - this._aperture = val; - this._apertureValue = FSTOPS[this._aperture]; - this.updateExposure(); - } - - get aperture (): CameraAperture { - return this._aperture; - } - - get apertureValue (): number { - return this._apertureValue; - } - - set shutter (val: CameraShutter) { - this._shutter = val; - this._shutterValue = SHUTTERS[this._shutter]; - this.updateExposure(); - } - - get shutter (): CameraShutter { - return this._shutter; - } - - get shutterValue (): number { - return this._shutterValue; - } - - set iso (val: CameraISO) { - this._iso = val; - this._isoValue = ISOS[this._iso]; - this.updateExposure(); - } - - get iso (): CameraISO { - return this._iso; - } - - get isoValue (): number { - return this._isoValue; - } - - set ec (val: number) { - this._ec = val; - } - - get ec (): number { - return this._ec; - } - - get exposure (): number { - return this._exposure; - } - - get clearFlag () : ClearFlags { - return this._clearFlag; - } - - set clearFlag (flag: ClearFlags) { - this._clearFlag = flag; - if (JSB) { - this._nativeObj!.clearFlag = flag; - } - } - - get clearDepth () : number { - return this._clearDepth; - } - - set clearDepth (depth: number) { - this._clearDepth = depth; - if (JSB) { - this._nativeObj!.clearDepth = depth; - } - } - - get clearStencil () : number { - return this._clearStencil; - } - - set clearStencil (stencil: number) { - this._clearStencil = stencil; - if (JSB) { - this._nativeObj!.clearStencil = stencil; - } - } - - get native (): any { - return this._nativeObj; - } - + /** + * @en Change the target render window to another one + * @zh 修改相机的目标渲染窗口 + * @param window The target render window, could be null + */ public changeTargetWindow (window: RenderWindow | null = null) { if (this._window) { this._window.detachCamera(this); @@ -732,6 +913,10 @@ export class Camera { } } + /** + * @en Detach camera from the render window + * @zh 将 camera 从渲染窗口移除 + */ public detachCamera () { if (this._window) { this._window.detachCamera(this); @@ -739,7 +924,12 @@ export class Camera { } /** - * transform a screen position (in oriented space) to a world space ray + * @en Transform a screen position (in oriented space) to a world space ray + * @zh 将一个屏幕空间(在实际朝向下)点转换到世界空间的射线 + * @param out the resulting ray + * @param x the screen x of the position + * @param y the screen y of the position + * @returns the resulting ray */ public screenPointToRay (out: Ray, x: number, y: number): Ray { if (!this._node) return null!; @@ -774,7 +964,11 @@ export class Camera { } /** - * transform a screen position (in oriented space) to world space + * @en Transform a screen position (in oriented space) to world space + * @zh 将一个屏幕空间(在实际朝向下)位置转换到世界空间 + * @param out the resulting vector + * @param screenPos the screen position to be transformed + * @returns the resulting vector */ public screenToWorld (out: Vec3, screenPos: Vec3): Vec3 { const width = this.width; @@ -820,7 +1014,11 @@ export class Camera { } /** - * transform a world space position to screen space + * @en Transform a world space position to screen space rendered by the camera + * @zh 将一个世界空间位置转换到相机渲染后的屏幕空间 + * @param out the resulting vector + * @param worldPos the world position to be transformed + * @returns the resulting vector */ public worldToScreen (out: Vec3, worldPos: Vec3 | Readonly): Vec3 { const ySign = this._device.capabilities.clipSpaceSignY; @@ -847,12 +1045,13 @@ export class Camera { } /** - * transform a world space matrix to screen space - * @param {Mat4} out the resulting vector - * @param {Mat4} worldMatrix the world space matrix to be transformed - * @param {number} width framebuffer width - * @param {number} height framebuffer height - * @returns {Mat4} the resulting vector + * @en Transform a world space matrix to screen space rendered by the camera + * @zh 将一个世界空间矩阵转换到相机渲染后的屏幕空间 + * @param out the resulting matrix + * @param worldMatrix the world space matrix to be transformed + * @param width framebuffer width + * @param height framebuffer height + * @returns the resulting matrix */ public worldMatrixToScreen (out: Mat4, worldMatrix: Mat4, width: number, height: number) { Mat4.multiply(out, this._matViewProj, worldMatrix); @@ -869,6 +1068,11 @@ export class Camera { return out; } + /** + * @en Set exposure with actual value. + * @zh 设置相机的曝光值 + * @param ev100 + */ protected setExposure (ev100) { this._exposure = 0.833333 / (2.0 ** ev100); if (JSB) { diff --git a/cocos/core/renderer/scene/directional-light.ts b/cocos/core/renderer/scene/directional-light.ts index f8f0c16d93..51e8f0cfe0 100644 --- a/cocos/core/renderer/scene/directional-light.ts +++ b/cocos/core/renderer/scene/directional-light.ts @@ -34,6 +34,11 @@ import { PCFType, Shadows } from './shadows'; const _forward = new Vec3(0, 0, -1); const _v3 = new Vec3(); +/** + * @en The directional light representation in the render scene, it acts as the main light source in a scene. + * As main light, only one directional light can be created in a scene, it can generate realtime shadows with configuration. + * @zh 渲染场景中的方向光抽象,这是场景中的主光源。作为主光源,每个场景只能有一个方向光,它也包含阴影配置,用来生成实时阴影。 + */ export class DirectionalLight extends Light { protected _dir: Vec3 = new Vec3(1.0, -1.0, -1.0); protected _illuminanceHDR: number = Ambient.SUN_ILLUM; @@ -56,6 +61,10 @@ export class DirectionalLight extends Light { protected _shadowFar = 10.0; protected _shadowOrthoSize = 5; + /** + * @en The direction vector of the light + * @zh 光源的方向 + */ set direction (dir: Vec3) { Vec3.normalize(this._dir, dir); if (JSB) { @@ -67,7 +76,10 @@ export class DirectionalLight extends Light { return this._dir; } - // in Lux(lx) + /** + * @en The illuminance of the light in Lux(lx) + * @zh 光源的辐照度,单位是 Lux(lx) + */ get illuminance (): number { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -85,6 +97,10 @@ export class DirectionalLight extends Light { } } + /** + * @en The illuminance of the light in HDR mode + * @zh HDR 模式下光源的辐照度 + */ get illuminanceHDR () { return this._illuminanceHDR; } @@ -95,6 +111,10 @@ export class DirectionalLight extends Light { } } + /** + * @en The illuminance of the light in LDR mode + * @zh LDR 模式下光源的辐照度 + */ get illuminanceLDR () { return this._illuminanceLDR; } @@ -120,9 +140,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow pcf. - * @zh 获取或者设置阴影pcf等级。 - */ + * @en get or set shadow pcf. + * @zh 获取或者设置阴影pcf等级。 + */ get shadowPcf () { return this._shadowPcf; } @@ -134,9 +154,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow map sampler offset - * @zh 获取或者设置阴影纹理偏移值 - */ + * @en get or set shadow map sampler offset + * @zh 获取或者设置阴影纹理偏移值 + */ get shadowBias () { return this._shadowBias; } @@ -148,9 +168,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set normal bias. - * @zh 设置或者获取法线偏移。 - */ + * @en get or set normal bias. + * @zh 设置或者获取法线偏移。 + */ get shadowNormalBias () { return this._shadowNormalBias; } @@ -176,9 +196,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow camera far - * @zh 获取或者设置潜在阴影产生的范围 - */ + * @en get or set shadow camera far + * @zh 获取或者设置潜在阴影产生的范围 + */ get shadowDistance () { return this._shadowDistance; } @@ -190,8 +210,8 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow camera far - * @zh 获取或者设置潜在阴影产生的范围 + * @en get or set shadow camera far + * @zh 获取或者设置潜在阴影产生的范围 */ get shadowInvisibleOcclusionRange () { return this._shadowInvisibleOcclusionRange; @@ -204,9 +224,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set fixed area shadow - * @zh 是否是固定区域阴影 - */ + * @en get or set fixed area shadow + * @zh 是否是固定区域阴影 + */ get shadowFixedArea () { return this._shadowFixedArea; } @@ -218,9 +238,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow camera near - * @zh 获取或者设置阴影相机近裁剪面 - */ + * @en The near clip plane of the shadow camera + * @zh 获取或者设置阴影相机近裁剪面 + */ get shadowNear () { return this._shadowNear; } @@ -232,9 +252,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow camera far - * @zh 获取或者设置阴影相机远裁剪面 - */ + * @en The far clip plane of the shadow camera + * @zh 获取或者设置阴影相机远裁剪面 + */ get shadowFar () { return this._shadowFar; } @@ -246,9 +266,9 @@ export class DirectionalLight extends Light { } /** - * @en get or set shadow camera orthoSize - * @zh 获取或者设置阴影相机正交大小 - */ + * @en get or set shadow camera orthoSize + * @zh 获取或者设置阴影相机正交大小 + */ get shadowOrthoSize () { return this._shadowOrthoSize; } @@ -271,6 +291,10 @@ export class DirectionalLight extends Light { this.direction = new Vec3(1.0, -1.0, -1.0); } + /** + * @en Update the direction + * @zh 更新方向 + */ public update () { if (this._node && this._node.hasChangedFlags) { this.direction = Vec3.transformQuat(_v3, _forward, this._node.worldRotation); diff --git a/cocos/core/renderer/scene/fog.ts b/cocos/core/renderer/scene/fog.ts index 751190e858..50c12c5eb0 100644 --- a/cocos/core/renderer/scene/fog.ts +++ b/cocos/core/renderer/scene/fog.ts @@ -78,6 +78,10 @@ export const FogType = Enum({ const FOG_TYPE_NONE = FogType.LAYERED + 1; +/** + * @en The fog representation in the render scene. + * @zh 渲染场景中的全局雾效配置 + */ export class Fog { /** * @zh 是否启用全局雾效 diff --git a/cocos/core/renderer/scene/light.ts b/cocos/core/renderer/scene/light.ts index 3f52498eea..024f7e04ac 100644 --- a/cocos/core/renderer/scene/light.ts +++ b/cocos/core/renderer/scene/light.ts @@ -66,6 +66,10 @@ export enum LightType { export const nt2lm = (size: number) => 4 * Math.PI * Math.PI * size * size; +/** + * @en The abstract light class of the render scene + * @zh 渲染场景中的光源基类 + */ export class Light { protected declare _nativeObj: NativeLight | null; protected _init (): void { @@ -92,6 +96,10 @@ export class Light { } } + /** + * @en Whether it's a baked light source, baked light will be ignored in real time lighting pass + * @zh 是否是烘焙光源,烘焙光源会在实时光照计算中被忽略 + */ get baked () { return this._baked; } @@ -103,6 +111,10 @@ export class Light { } } + /** + * @en The color of the light + * @zh 光源的颜色 + */ set color (color: Vec3) { this._color.set(color); if (JSB) { @@ -114,6 +126,10 @@ export class Light { return this._color; } + /** + * @en Whether to use color temperature + * @zh 是否使用光源的色温 + */ set useColorTemperature (enable: boolean) { this._useColorTemperature = enable; if (JSB) { @@ -125,6 +141,10 @@ export class Light { return this._useColorTemperature; } + /** + * @en The color temperature of the light + * @zh 光源的色温 + */ set colorTemperature (val: number) { this._colorTemp = val; ColorTemperatureToRGB(this._colorTempRGB, this._colorTemp); @@ -137,6 +157,10 @@ export class Light { return this._colorTemp; } + /** + * @en The float RGB value of the color temperature, each channel is from 0 to 1 + * @zh 色温的浮点数颜色值,每个通道都是从 0 到 1 + */ get colorTemperatureRGB (): Vec3 { return this._colorTempRGB; } @@ -151,14 +175,26 @@ export class Light { } } + /** + * @en The node which owns the light source + * @zh 光源归属的节点 + */ get node () { return this._node; } + /** + * @en The type of the light source, e.g. directional light, spot light, etc + * @zh 光源的类型,比如方向光、聚光灯等 + */ get type () : LightType { return this._type; } + /** + * @en The name of the light source + * @zh 光源的名字 + */ get name () { return this._name; } @@ -167,10 +203,17 @@ export class Light { this._name = n; } + /** + * @en The render scene which owns the current light + * @zh 光源所属的渲染场景 + */ get scene () { return this._scene; } + /** + * @internal + */ get native (): NativeLight { return this._nativeObj!; } @@ -199,10 +242,19 @@ export class Light { this.colorTemperature = 6550.0; } + /** + * @en Attach the light to a render scene + * @zh 将光源挂载到渲染场景上 + * @param scene @en The render scene @zh 渲染场景 + */ public attachToScene (scene: RenderScene) { this._scene = scene; } + /** + * @en Detach the light from the render scene + * @zh 将光源从渲染场景上移除 + */ public detachFromScene () { this._scene = null; } diff --git a/cocos/core/renderer/scene/model.ts b/cocos/core/renderer/scene/model.ts index d5c037f8b5..71c582abed 100644 --- a/cocos/core/renderer/scene/model.ts +++ b/cocos/core/renderer/scene/model.ts @@ -101,7 +101,7 @@ const lightmapSamplerWithMipHash = new SamplerInfo( */ export class Model { /** - * @en return sub models + * @en Sub models of the current model * @zh 获取所有子模型 */ get subModels () { @@ -109,7 +109,7 @@ export class Model { } /** - * @en is inited + * @en Whether the model is initialized * @zh 是否初始化 */ get inited (): boolean { @@ -117,7 +117,7 @@ export class Model { } /** - * @en return world aabb + * @en The axis-aligned bounding box of the model in the world space * @zh 获取世界空间包围盒 */ get worldBounds () { @@ -125,23 +125,23 @@ export class Model { } /** - * @en return model aabb - * @zh 获取模型包围盒 + * @en The axis-aligned bounding box of the model in the model space + * @zh 获取模型空间包围盒 */ get modelBounds () { return this._modelBounds; } /** - * @en return model ubo buffer - * @zh 获取模型 ubo 缓冲 + * @en The ubo buffer of the model + * @zh 获取模型的 ubo 缓冲 */ get localBuffer () { return this._localBuffer; } /** - * @en return world bound buffer + * @en The world bound ubo buffer * @zh 获取世界包围盒 ubo 缓冲 */ get worldBoundBuffer () { @@ -149,15 +149,15 @@ export class Model { } /** - * @en return update time stamp - * @zh 获取更新时间戳 + * @en The time stamp of last update + * @zh 获取上次更新时间戳 */ get updateStamp () { return this._updateStamp; } /** - * @en is GPU instancing enabled for the current model + * @en Whether GPU instancing is enabled for the current model * @zh 是否开启实例化渲染 */ get isInstancingEnabled () { @@ -165,7 +165,7 @@ export class Model { } /** - * @en shadow bias + * @en Model level shadow bias * @zh 阴影偏移值 */ get shadowBias () { @@ -180,7 +180,7 @@ export class Model { } /** - * @en shadow normal bias + * @en Model level shadow normal bias * @zh 阴影法线偏移值 */ get shadowNormalBias () { @@ -195,7 +195,7 @@ export class Model { } /** - * @en receive shadow or not + * @en Whether the model should receive shadow * @zh 是否接收阴影 */ get receiveShadow () { @@ -208,7 +208,7 @@ export class Model { } /** - * @en cast shadow or not + * @en Whether the model should cast shadow * @zh 是否投射阴影 */ get castShadow () { @@ -223,7 +223,7 @@ export class Model { } /** - * @en model's node + * @en The node to which the model belongs * @zh 模型所在的节点 */ get node () : Node { @@ -238,7 +238,7 @@ export class Model { } /** - * @en model's transform + * @en Model's transform * @zh 模型的变换 */ get transform () : Node { @@ -253,7 +253,7 @@ export class Model { } /** - * @en model's visibility tag + * @en Model's visibility tag * Model's visibility flags, it's different from [[Node.layer]], * but it will also be compared with [[Camera.visibility]] during culling process. * @zh 模型的可见性标志 @@ -271,8 +271,8 @@ export class Model { } /** - * @en enabled - * @zh 模型是否启用 + * @en Whether the model is enabled in the render scene so that it will be rendered + * @zh 模型是否在渲染场景中启用并被渲染 */ get enabled () : boolean { return this._enabled; @@ -286,103 +286,103 @@ export class Model { } /** - * @en model type + * @en The type of the model * @zh 模型类型 */ public type = ModelType.DEFAULT; /** - * @en model's render scene + * @en The render scene to which the model belongs * @zh 模型所在的场景 */ public scene: RenderScene | null = null; /** - * @en is dynamic batching + * @en Whether dynamic batching is enabled for model * @zh 是否动态合批 */ public isDynamicBatching = false; /** - * @en instance attributes + * @en The instance attributes * @zh 实例化属性 */ public instancedAttributes: IInstancedAttributeBlock = { buffer: null!, views: [], attributes: [] }; /** - * @en world aabb + * @en The world axis-aligned bounding box * @zh 世界空间包围盒 */ protected _worldBounds: AABB | null = null; /** - * @en model aabb + * @en The model axis-aligned bounding box * @zh 模型空间包围盒 */ protected _modelBounds: AABB | null = null; /** - * @en sub models + * @en Sub models * @zh 子模型 */ protected _subModels: SubModel[] = []; /** - * @en model's node - * @zh 子模型所在的节点 + * @en The node to which the model belongs + * @zh 模型所在的节点 */ protected _node: Node = null!; /** - * @en model's transform + * @en Model's transform * @zh 子模型的变换 */ protected _transform: Node = null!; /** - * @en current device - * @zh 当前设备 + * @en Current gfx device + * @zh 当前 GFX 设备 */ protected _device: Device; /** - * @en is inited + * @en Whether the model is initialized * @zh 是否初始化过 */ protected _inited = false; /** - * @en descriptor set count + * @en Descriptor set count * @zh 描述符集合个数 */ protected _descriptorSetCount = 1; /** - * @en update time stamp + * @en Time stamp for last update * @zh 更新时间戳 */ protected _updateStamp = -1; /** - * @en local ubo data dirty flag + * @en Local ubo data dirty flag * @zh 本地 ubo 数据是否修改过 */ protected _localDataUpdated = true; /** - * @en local ubo data + * @en Local ubo data * @zh 本地 ubo 数据 */ protected _localData = new Float32Array(UBOLocal.COUNT); /** - * @en local ubo buffer + * @en Local ubo buffer * @zh 本地 ubo 缓冲 */ protected _localBuffer: Buffer | null = null; /** - * @en instance matrix id + * @en Instance matrix id * @zh 实例矩阵索引 */ private _instMatWorldIdx = -1; @@ -390,43 +390,43 @@ export class Model { private _lightmapUVParam: Vec4 = new Vec4(); /** - * @en world aabb buffer + * @en World AABB buffer * @zh 世界空间包围盒缓冲 */ protected _worldBoundBuffer: Buffer | null = null; /** - * @en receive shadow or not + * @en Whether the model should receive shadow * @zh 是否接收阴影 */ protected _receiveShadow = false; /** - * @en cast shadow or not + * @en Whether the model should cast shadow * @zh 是否投射阴影 */ protected _castShadow = false; /** - * @en shadow bias + * @en Shadow bias * @zh 阴影偏移 */ protected _shadowBias = 0; /** - * @en shadow normal bias + * @en Shadow normal bias * @zh 阴影法线偏移 */ protected _shadowNormalBias = 0; /** - * @en enable or not - * @zh 是否启用 + * @en Whether the model is enabled in the render scene so that it will be rendered + * @zh 模型是否在渲染场景中启用并被渲染 */ protected _enabled = true; /** - * @en visible flag + * @en The visibility flags * @zh 可见性标志位 */ protected _visFlags = Layers.Enum.NONE; @@ -448,7 +448,7 @@ export class Model { } /** - * @en create a empty model + * @en Constructor to create an empty model * @zh 创建一个空模型 */ constructor () { @@ -469,7 +469,7 @@ export class Model { } /** - * @en init model + * @en Initialize the model * @zh 初始化模型 */ public initialize () { @@ -495,7 +495,7 @@ export class Model { } /** - * @en destroy model + * @en Destroy the model * @zh 销毁模型 */ public destroy () { @@ -525,7 +525,7 @@ export class Model { } /** - * @en attach model to [[RenderScene]] + * @en Attach the model to a [[RenderScene]] * @zh 添加模型到渲染场景 [[RenderScene]] 中 * @param scene destination scene */ @@ -535,7 +535,7 @@ export class Model { } /** - * @en detach model from scene + * @en Detach the model from its render scene * @zh 移除场景中的模型 */ public detachFromScene () { @@ -543,7 +543,7 @@ export class Model { } /** - * @en update model's transform + * @en Update the model's transform * @zh 更新模型的变换 * @param stamp time stamp */ @@ -562,7 +562,7 @@ export class Model { } /** - * @en update model's world aabb + * @en Update the model's world AABB * @zh 更新模型的世界空间包围盒 */ public updateWorldBound () { @@ -597,7 +597,7 @@ export class Model { } /** - * @en update model's ubo + * @en Update the model's ubo * @zh 更新模型的 ubo * @param stamp time stamp */ @@ -641,10 +641,10 @@ export class Model { } /** - * @en create model's aabb + * @en Create the model's AABB * @zh 创建模型的包围盒 - * @param minPos min positoin of the aabb - * @param maxPos max positoin of the aabb + * @param minPos min position of the AABB + * @param maxPos max position of the AABB */ public createBoundingShape (minPos?: Vec3, maxPos?: Vec3) { if (!minPos || !maxPos) { return; } @@ -658,7 +658,7 @@ export class Model { } /** - * @en init a sub model + * @en Initialize a sub model * @zh 初始化一个子模型 * @param idx sub model's index * @param subMeshData sub mesh @@ -688,7 +688,7 @@ export class Model { } /** - * @en set material for a given sub model + * @en Set material for a given sub model * @zh 为指定的子模型设置材质 * @param idx sub model's index * @param subMesh sub mesh @@ -699,7 +699,7 @@ export class Model { } /** - * @en set a sub material + * @en Set a sub material * @zh 设置一个子材质 * @param idx sub model's index * @param mat sub material @@ -711,7 +711,7 @@ export class Model { } /** - * @en pipeline changed callback + * @en Pipeline changed callback * @zh 管线更新回调 */ public onGlobalPipelineStateChanged () { @@ -722,8 +722,8 @@ export class Model { } /** - * @en shader macro changed callback - * @zh shader宏更新回调 + * @en Shader macro changed callback + * @zh Shader 宏更新回调 */ public onMacroPatchesStateChanged () { const subModels = this._subModels; @@ -733,7 +733,7 @@ export class Model { } /** - * @en update light map + * @en Update the light map * @zh 更新光照贴图 * @param texture light map * @param uvParam uv coordinate @@ -768,7 +768,7 @@ export class Model { } /** - * @en update shadow bias + * @en Update the shadow bias * @zh 更新阴影偏移 */ public updateLocalShadowBias () { @@ -781,7 +781,7 @@ export class Model { } /** - * @en return shader macro + * @en Return shader's macro patches * @zh 获取 shader 宏 * @param subModelIndex sub model's index */ diff --git a/cocos/core/renderer/scene/octree.ts b/cocos/core/renderer/scene/octree.ts index eeb68b1461..15368e69e0 100644 --- a/cocos/core/renderer/scene/octree.ts +++ b/cocos/core/renderer/scene/octree.ts @@ -28,9 +28,13 @@ import { Vec3 } from '../../math/vec3'; import type { OctreeInfo } from '../../scene-graph/scene-globals'; import { NativeOctree } from '../native-scene'; +/** + * @en The octree culling configuration of the render scene + * @zh 渲染场景的八叉树剔除配置 + */ export class Octree { /** - * @en enable octree + * @en Whether octree culling is enabled in the render scene * @zh 是否开启八叉树加速剔除 */ set enabled (val: boolean) { @@ -44,7 +48,7 @@ export class Octree { } /** - * @en min pos of scene bounding box + * @en Minimum position of the scene's bounding box * @zh 场景包围盒最小值 */ get minPos (): Vec3 { @@ -58,7 +62,7 @@ export class Octree { } /** - * @en max pos of scene bounding box + * @en Maximum position of the scene's bounding box * @zh 场景包围盒最大值 */ get maxPos (): Vec3 { @@ -72,7 +76,7 @@ export class Octree { } /** - * @en depth of octree + * @en The depth of the octree * @zh 八叉树深度 */ get depth (): number { diff --git a/cocos/core/renderer/scene/shadows.ts b/cocos/core/renderer/scene/shadows.ts index 2fd5fa44c5..a9c485431e 100644 --- a/cocos/core/renderer/scene/shadows.ts +++ b/cocos/core/renderer/scene/shadows.ts @@ -124,6 +124,10 @@ export const PCFType = Enum({ const SHADOW_TYPE_NONE = ShadowType.ShadowMap + 1; +/** + * @en The global shadow's configuration of the render scene + * @zh 渲染场景的全局阴影配置 + */ export class Shadows { /** * @en MAX_FAR. This is shadow camera max far. @@ -235,6 +239,10 @@ export class Shadows { } } + /** + * @en The transform matrix of the light source + * @zh 光源的变换矩阵 + */ public get matLight () { return this._matLight; } @@ -260,10 +268,29 @@ export class Shadows { public maxReceived = 4; // local set + /** + * @internal + */ public firstSetCSM = false; + /** + * @en The far clip plane of the shadow camera + * @zh 阴影相机的远裁剪平面 + */ public shadowCameraFar = 0; + /** + * @en Shadow camera's view matrix + * @zh 阴影相机的视图矩阵 + */ public matShadowView = new Mat4(); + /** + * @en Shadow camera's projection matrix + * @zh 阴影相机的投影矩阵 + */ public matShadowProj = new Mat4(); + /** + * @en Shadow camera's view projection matrix + * @zh 阴影相机的视图投影矩阵 + */ public matShadowViewProj = new Mat4(); protected _enabled = false; @@ -280,6 +307,9 @@ export class Shadows { protected declare _nativeObj: NativeShadow | null; + /** + * @internal + */ get native (): NativeShadow { return this._nativeObj!; } @@ -290,6 +320,12 @@ export class Shadows { } } + /** + * @en Get the shader for the planar shadow with macro patches + * @zh 通过指定宏获取平面阴影的 Shader 对象 + * @param patches The macro patches for the shader + * @returns The shader for the planar shadow + */ public getPlanarShader (patches: IMacroPatch[] | null): Shader | null { if (!this._material) { this._material = new Material(); @@ -302,6 +338,12 @@ export class Shadows { return this._material.passes[0].getShaderVariant(patches); } + /** + * @en Get the shader which support instancing draw for the planar shadow with macro patches + * @zh 通过指定宏获取支持实例化渲染的平面阴影的 Shader 对象 + * @param patches The macro patches for the shader + * @returns The shader for the planar shadow + */ public getPlanarInstanceShader (patches: IMacroPatch[] | null): Shader | null { if (!this._instancingMaterial) { this._instancingMaterial = new Material(); diff --git a/cocos/core/renderer/scene/skybox.ts b/cocos/core/renderer/scene/skybox.ts index 505405444f..7e91ebb5bc 100644 --- a/cocos/core/renderer/scene/skybox.ts +++ b/cocos/core/renderer/scene/skybox.ts @@ -69,7 +69,16 @@ export const EnvironmentLightingType = Enum({ DIFFUSEMAP_WITH_REFLECTION: 2, }); +/** + * @en The skybox configuration of the render scene, + * currently some rendering options like hdr and ibl lighting configuration is also here. + * @zh 渲染场景的天空盒配置,目前一些渲染配置,比如 HDR 模式和环境光照配置也在 Skybox 中。 + */ export class Skybox { + /** + * @en The Model object of the skybox + * @zh 天空盒的 Model 对象 + */ get model (): Model | null { return this._model; } @@ -86,8 +95,9 @@ export class Skybox { this._setEnabled(val); if (val) this.activate(); else this._updatePipeline(); } + /** - * @en HDR + * @en Whether HDR mode is enabled * @zh 是否启用HDR? */ get useHDR (): boolean { @@ -100,7 +110,7 @@ export class Skybox { } /** - * @en Whether use IBL + * @en Whether use image based lighting for PBR materials * @zh 是否启用IBL? */ get useIBL (): boolean { @@ -193,6 +203,9 @@ export class Skybox { protected _useDiffuseMap = false; protected declare _nativeObj: NaitveSkybox | null; + /** + * @internal + */ get native (): NaitveSkybox { return this._nativeObj!; } @@ -238,6 +251,12 @@ export class Skybox { this._setUseHDR(skyboxInfo.useHDR); } + /** + * @en Set the environment maps for HDR and LDR mode + * @zh 为 HDR 和 LDR 模式设置环境贴图 + * @param envmapHDR @en Environment map for HDR mode @zh HDR 模式下的环境贴图 + * @param envmapLDR @en Environment map for LDR mode @zh LDR 模式下的环境贴图 + */ public setEnvMaps (envmapHDR: TextureCube | null, envmapLDR: TextureCube | null) { this._envmapHDR = envmapHDR; this._envmapLDR = envmapLDR; @@ -246,6 +265,12 @@ export class Skybox { this._updatePipeline(); } + /** + * @en Set the diffuse maps + * @zh 设置环境光漫反射贴图 + * @param diffuseMapHDR @en Diffuse map for HDR mode @zh HDR 模式下的漫反射贴图 + * @param diffuseMapLDR @en Diffuse map for LDR mode @zh LDR 模式下的漫反射贴图 + */ public setDiffuseMaps (diffuseMapHDR: TextureCube | null, diffuseMapLDR: TextureCube | null) { this._diffuseMapHDR = diffuseMapHDR; this._diffuseMapLDR = diffuseMapLDR; diff --git a/cocos/core/renderer/scene/sphere-light.ts b/cocos/core/renderer/scene/sphere-light.ts index 6cb23d055f..1bfab1a51b 100644 --- a/cocos/core/renderer/scene/sphere-light.ts +++ b/cocos/core/renderer/scene/sphere-light.ts @@ -30,6 +30,11 @@ import { Vec3 } from '../../math'; import { Light, LightType, nt2lm } from './light'; import { NativeSphereLight } from '../native-scene'; +/** + * @en The sphere light representation in the render scene, it will light up a spherical area in the scene. + * It doesn't support shadow generation currently. + * @zh 渲染场景中的球面光抽象,可以照亮场景中的一个球形区域,目前还不支持生成阴影。 + */ export class SphereLight extends Light { protected _init (): void { super._init(); @@ -43,10 +48,18 @@ export class SphereLight extends Light { super._destroy(); } + /** + * @en The world position of the light source + * @zh 光源中心点的世界坐标 + */ get position () { return this._pos; } + /** + * @en The size of the light source + * @zh 球面光源的尺寸 + */ set size (size: number) { this._size = size; if (JSB) { @@ -58,6 +71,10 @@ export class SphereLight extends Light { return this._size; } + /** + * @en The lighting range of the light source + * @zh 球面光源的光照范围 + */ set range (range: number) { this._range = range; if (JSB) { @@ -71,6 +88,10 @@ export class SphereLight extends Light { return this._range; } + /** + * @en The luminance of the light source + * @zh 光源的亮度 + */ get luminance (): number { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -88,6 +109,10 @@ export class SphereLight extends Light { } } + /** + * @en The luminance of the light source in HDR mode + * @zh HDR 模式下光源的亮度 + */ get luminanceHDR () { return this._luminanceHDR; } @@ -99,6 +124,10 @@ export class SphereLight extends Light { } } + /** + * @en The luminance of the light source in LDR mode + * @zh LDR 模式下光源的亮度 + */ set luminanceLDR (value: number) { this._luminanceLDR = value; @@ -107,6 +136,10 @@ export class SphereLight extends Light { } } + /** + * @en The AABB bounding box of the lighting area + * @zh 受光源影响范围的 AABB 包围盒 + */ get aabb () { return this._aabb; } @@ -136,6 +169,10 @@ export class SphereLight extends Light { this.luminanceLDR = 1.0; } + /** + * @en Update the lighting area + * @zh 更新光源影响范围 + */ public update () { if (this._node && (this._node.hasChangedFlags || this._needUpdate)) { this._node.getWorldPosition(this._pos); diff --git a/cocos/core/renderer/scene/spot-light.ts b/cocos/core/renderer/scene/spot-light.ts index 46ca59addf..fbda4299d9 100644 --- a/cocos/core/renderer/scene/spot-light.ts +++ b/cocos/core/renderer/scene/spot-light.ts @@ -38,15 +38,15 @@ const _matProj = new Mat4(); const _matViewProj = new Mat4(); const _matViewProjInv = new Mat4(); +/** + * @en The spot light representation in the render scene, it will light up a cone area in the direction of the light, it supports shadow generation. + * @zh 渲染场景中的聚光灯抽象,可以照亮光源方向上的一个锥形区域,支持生成阴影。 + */ export class SpotLight extends Light { protected _dir: Vec3 = new Vec3(1.0, -1.0, -1.0); protected _range = 5.0; - /** - * @en Cached uniform variables. - * @zh 缓存下来的 uniform 变量。 - */ protected _spotAngle: number = Math.cos(Math.PI / 6); protected _pos: Vec3; @@ -99,10 +99,18 @@ export class SpotLight extends Light { } } + /** + * @en The world position of the light source + * @zh 光源的世界坐标 + */ get position () { return this._pos; } + /** + * @en The size of the spot light source + * @zh 聚光灯的光源尺寸 + */ set size (size: number) { this._size = size; if (JSB) { @@ -114,6 +122,10 @@ export class SpotLight extends Light { return this._size; } + /** + * @en The lighting range of the spot light + * @zh 聚光灯的光照范围 + */ set range (range: number) { this._range = range; if (JSB) { @@ -127,6 +139,10 @@ export class SpotLight extends Light { return this._range; } + /** + * @en The luminance of the light source + * @zh 光源的亮度 + */ get luminance (): number { const isHDR = (legacyCC.director.root).pipeline.pipelineSceneData.isHDR; if (isHDR) { @@ -144,6 +160,10 @@ export class SpotLight extends Light { } } + /** + * @en The luminance of the light source in HDR mode + * @zh HDR 模式下光源的亮度 + */ get luminanceHDR () { return this._luminanceHDR; } @@ -155,6 +175,10 @@ export class SpotLight extends Light { } } + /** + * @en The luminance of the light source in LDR mode + * @zh LDR 模式下光源的亮度 + */ get luminanceLDR () { return this._luminanceLDR; } @@ -166,16 +190,25 @@ export class SpotLight extends Light { } } + /** + * @en The direction of the spot light + * @zh 聚光灯的照明方向 + */ get direction (): Vec3 { return this._dir; } - // 获取 cache 下来的 cos(angle / 2) 属性值,uniform 里需要 + /** + * @en The setter will take the value as the cone angle, + * but the getter will give you the cosine value of the half cone angle: `cos(angle / 2)`. + * As the in-consistence is not acceptable for a property, please do not use it. + * @zh 赋值时这个属性会把输入值当做聚光灯光照区域的锥角,但是获取时返回的是 cos(angle / 2)。 + * 由于这种不一致性,请不要使用这个属性。 + */ get spotAngle () { return this._spotAngle; } - // 设置用户指定的全角弧度,同时计算 cache 下来的 cos(angle / 2) 属性值,uniform 里需要。 set spotAngle (val: number) { this._angle = val; this._spotAngle = Math.cos(val * 0.5); @@ -186,10 +219,17 @@ export class SpotLight extends Light { this._needUpdate = true; } + /** + * @en The cone angle of the lighting area + * @zh 聚光灯锥角 + */ get angle () { return this._angle; } + /** + * @internal + */ set aspect (val: number) { this._aspect = val; if (JSB) { @@ -203,16 +243,24 @@ export class SpotLight extends Light { return this._aspect; } + /** + * @en The AABB bounding box of the lighting area + * @zh 受光源影响范围的 AABB 包围盒 + */ get aabb () { return this._aabb; } + /** + * @en The frustum of the lighting area + * @zh 受光源影响范围的截椎体 + */ get frustum () { return this._frustum; } /** - * @en Whether activate shadow + * @en Whether shadow casting is enabled * @zh 是否启用阴影? */ get shadowEnabled () { @@ -226,9 +274,9 @@ export class SpotLight extends Light { } /** - * @en get or set shadow pcf. - * @zh 获取或者设置阴影pcf等级。 - */ + * @en The pcf level of the shadow generation. + * @zh 获取或者设置阴影 pcf 等级。 + */ get shadowPcf () { return this._shadowPcf; } @@ -240,9 +288,9 @@ export class SpotLight extends Light { } /** - * @en get or set shadow map sampler offset - * @zh 获取或者设置阴影纹理偏移值 - */ + * @en The depth offset of shadow to avoid moire pattern artifacts + * @zh 阴影的深度偏移, 可以减弱跨像素导致的条纹状失真 + */ get shadowBias () { return this._shadowBias; } @@ -254,7 +302,7 @@ export class SpotLight extends Light { } /** - * @en get or set normal bias. + * @en The normal bias of the shadow map. * @zh 设置或者获取法线偏移。 */ get shadowNormalBias () { diff --git a/cocos/core/renderer/scene/submodel.ts b/cocos/core/renderer/scene/submodel.ts index 78e8dd9c5f..5f7289bf96 100644 --- a/cocos/core/renderer/scene/submodel.ts +++ b/cocos/core/renderer/scene/submodel.ts @@ -39,6 +39,13 @@ import { Root } from '../../root'; const _dsInfo = new DescriptorSetInfo(null!); const MAX_PASS_COUNT = 8; + +/** + * @en A sub part of the model, it describes how to render a specific sub mesh. + * It contains geometry information in [[RenderingSubMesh]] and all sort of rendering configuration like shaders, macro patches, passes etc. + * @zh 组成模型对象的子模型,它用来描述如何渲染模型的一个子网格。 + * 它包含 [[RenderingSubMesh]] 代表的几何网格信息和所有渲染需要的数据,比如着色器程序,着色器宏定义,渲染 pass,等。 + */ export class SubModel { protected _device: Device | null = null; protected _passes: Pass[] | null = null; @@ -93,6 +100,10 @@ export class SubModel { } } + /** + * @en Render passes for the sub-model + * @zh 子模型的渲染 pass + */ set passes (passes) { const passLengh = passes.length; if (passLengh > MAX_PASS_COUNT) { @@ -118,10 +129,18 @@ export class SubModel { return this._passes!; } + /** + * @en Shaders for the sub-model, each shader corresponds to one of the [[passes]] + * @zh 子模型的着色器程序列表,每个着色器程序对应其中一个渲染 [[passes]] + */ get shaders (): Shader[] { return this._shaders!; } + /** + * @en The rendering sub mesh for the sub-model, each sub-model can only have one sub mesh. + * @zh 用于渲染的子网格对象,每个子模型只能包含一个子网格。 + */ set subMesh (subMesh) { this._inputAssembler!.destroy(); this._inputAssembler!.initialize(subMesh.iaInfo); @@ -133,6 +152,10 @@ export class SubModel { return this._subMesh!; } + /** + * @en The rendering priority of the sub-model + * @zh 子模型的渲染优先级 + */ set priority (val) { this._priority = val; if (JSB) { @@ -144,26 +167,50 @@ export class SubModel { return this._priority; } + /** + * @en The low level input assembler which contains geometry data + * @zh 底层渲染用的输入汇集器,包含几何信息 + */ get inputAssembler (): InputAssembler { return this._inputAssembler!; } + /** + * @en The descriptor set used for sub-model rendering + * @zh 底层渲染子模型用的描述符集组 + */ get descriptorSet (): DescriptorSet { return this._descriptorSet!; } + /** + * @en The descriptor set for world bound + * @zh 用于存储世界包围盒的描述符集组 + */ get worldBoundDescriptorSet (): DescriptorSet { return this._worldBoundDescriptorSet!; } + /** + * @en The macro patches for the shaders + * @zh 着色器程序所用的宏定义组合 + */ get patches (): IMacroPatch[] | null { return this._patches; } + /** + * @en The shader for rendering the planar shadow, instancing draw version. + * @zh 用于渲染平面阴影的着色器,适用于实例化渲染(instancing draw) + */ get planarInstanceShader (): Shader | null { return this._planarInstanceShader; } + /** + * @en The shader for rendering the planar shadow. + * @zh 用于渲染平面阴影的着色器。 + */ get planarShader (): Shader | null { return this._planarShader; } @@ -182,6 +229,9 @@ export class SubModel { } } + /** + * @internal + */ get native (): NativeSubModel { return this._nativeObj!; } @@ -261,6 +311,9 @@ export class SubModel { } } + /** + * @internal + */ // This is a temporary solution // It should not be written in a fixed way, or modified by the user public initPlanarShadowShader () { @@ -276,6 +329,9 @@ export class SubModel { } } + /** + * @internal + */ // This is a temporary solution // It should not be written in a fixed way, or modified by the user public initPlanarShadowInstanceShader () { @@ -318,6 +374,10 @@ export class SubModel { this._worldBoundDescriptorSet!.update(); } + /** + * @en Pipeline changed callback + * @zh 管线更新回调 + */ public onPipelineStateChanged (): void { const passes = this._passes; if (!passes) { return; } @@ -332,6 +392,10 @@ export class SubModel { this._flushPassInfo(); } + /** + * @en Shader macro changed callback + * @zh Shader 宏更新回调 + */ public onMacroPatchesStateChanged (patches: IMacroPatch[] | null): void { this._patches = patches;