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:

// Create an entity
const entity = root.createChild("cameraEntity");
// Create camera
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.

// Get the camera component from the node where the camera is mounted
const camera = entity.getComponent(Camera);
 
// Enable post-processing
camera.enablePostProcess = true;
// Enable HDR
camera.enableHDR = true;
// Enable FXAA
camera.antiAliasing = AntiAliasing.FXAA;
// Preserve the alpha channel in the output
camera.isAlphaOutputRequired = 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.