Update api doc for core/renderer/scene (#10962)

* Update api doc for core/renderer/scenne

* Improve doc
This commit is contained in:
pandamicro
2022-05-06 16:23:39 +08:00
committed by GitHub
parent 52b29e0160
commit 6912ea1c62
16 changed files with 1035 additions and 472 deletions
+5 -5
View File
@@ -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)
+35 -2
View File
@@ -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;
}
+18 -18
View File
@@ -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 {
+12 -3
View File
@@ -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,
+20 -3
View File
@@ -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!;
}
+531 -327
View File
@@ -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>): 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) {
+51 -27
View File
@@ -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);
+4
View File
@@ -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 是否启用全局雾效
+52
View File
@@ -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;
}
+67 -67
View File
@@ -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
*/
+8 -4
View File
@@ -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 {
+42
View File
@@ -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();
+27 -2
View File
@@ -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;
+37
View File
@@ -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);
+62 -14
View File
@@ -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 () {
+64
View File
@@ -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;