Camera Component

The camera component can project a 3D scene onto a 2D screen. Based on the camera component, we can customize various rendering effects.

First, you need to mount the camera component onto an activated Entity in the scene. Editor projects usually come with a camera component by default, but you can also add one manually.

After adding it, you can view the camera properties in the inspector, and the camera preview in the lower left corner allows you to conveniently see the camera effect during the actual project runtime:

You can also mount the camera component to an Entity in the script with the following code:

// 创建实体
const entity = root.createChild("cameraEntity");
// 创建相机组件
const camera = entity.addComponent(Camera);

Properties

By modifying the properties of the camera component, you can customize the rendering effects. Below are the property settings exposed by the camera component in the Inspector Panel.

You can also get the camera component and set the corresponding properties through the script.

// 从挂载相机的节点上获取相机组件
const camera = entity.getComponent(Camera);
// 设置相机类型
camera.isOrthographic = true;
// 设置相机的近平面
camera.nearClipPlane = 0.1;
// 设置相机的远平面
camera.farClipPlane = 100;
// 设置相机的 FOV（角度制）
camera.fieldOfView = 45;
// 设置相机在画布上的渲染区域（归一化）
camera.viewport = new Vector4(0, 0, 1, 1);
// 设置相机的渲染优先级（值越小，渲染优先级越高）
camera.priority = 0;
// 设置相机是否开启视锥体裁剪
camera.enableFrustumCulling = true;
// 设置相机渲染前的清除标记
camera.clearFlags = CameraClearFlags.All;
// 开启后处理
camera.enablePostProcess = true;
// 开启 HDR
camera.enableHDR = true;

The functionality corresponding to each property is as follows:

Culling Mask

The camera component can selectively render the rendering components in the scene by setting the cullingMask.

Render Target

The camera component can render the result to different targets by setting the renderTarget.

Frustum Culling

The enableFrustumCulling property is enabled by default because, in a 3D world, "things that are not visible do not need to be rendered" is a very natural logic and is the most basic performance optimization. Disabling frustum culling means turning off this optimization. If you want to keep this optimization but always render a specific node, you can set the bounding box of the node's renderer to be infinite.

Methods

The camera component provides various methods (mainly related to rendering and space transformation) to facilitate developers in achieving the desired customization capabilities. Before that, you need to learn how to get the camera component. If you know which node the camera component is mounted on, you can directly get it through getComponent or getComponentsIncludeChildren:

// 从挂载相机的节点上获取相机组件
const camera = entity.getComponent(Camera);
// 从挂载相机节点的父节点上获取相机组件（不推荐）
const cameras = entity.getComponentsIncludeChildren(Camera, []);

If you are not sure which node the camera component is mounted on, you can also get all the camera components in the scene through a more hacky way:

// Get all camera components in this scene (not recommended)
const cameras = scene._componentsManager._activeCameras;

Shader Replacement

With the ability of setReplacementShader to globally replace shaders, you can observe specific rendering effects:

Space Transformation

It should be noted that the Z of the point passed into methods like screenToWorldPoint and viewportToWorldPoint represents the distance from the returned point to the camera.

onBeginRender and onEndRender

The camera component additionally includes two lifecycle callbacks, onBeginRender and onEndRender. Their sequence can be referenced in the script lifecycle sequence diagram.