Camera3D

继承： Node3D < Node < Object

派生： XRCamera3D

相机节点，会从某个角度进行显示。

描述

Camera3D 是一个特殊节点，用于显示从其当前位置可见的内容。相机在最近的 Viewport 节点中注册自己（当树上行）。每个视口中只能有一个激活的相机。如果在树上没有可用的视口，相机将在全局视口中注册。换句话说，相机只是用来为 Viewport 提供 3D 显示能力的，如果没有，则在该 Viewport（或更高层视口）中注册的场景无法显示。

教程

• 第三人称射击（TPS）演示

属性

方法

枚举

enum ProjectionType: 🔗

ProjectionType PROJECTION_PERSPECTIVE = 0

透视投影。物体距离相机屏幕越远显示就越小。

ProjectionType PROJECTION_ORTHOGONAL = 1

正交投影，又称正交投影。物体无论距离多远，在屏幕上都保持相同的大小。

ProjectionType PROJECTION_FRUSTUM = 2

视锥投影。通过该模式可以调整 frustum_offset 来创建“倾斜的视锥”效果。

enum KeepAspect: 🔗

KeepAspect KEEP_WIDTH = 0

保留水平长宽比，也称为 Vert- 缩放。这通常是在纵向模式下运行的项目的最佳选择，因为较高的纵横比将从更宽的垂直视场中受益。

KeepAspect KEEP_HEIGHT = 1

保留垂直长宽比，也称为 Hor+ 缩放。这通常是在横向模式下运行的项目的最佳选择，因为较宽的纵横比会自动从较宽的水平视场中受益。

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

禁用多普勒效应模拟（默认）。

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

通过跟踪在 _process 中改变的物体位置来模拟多普勒效应。与这些物体相比，该相机的相对速度的变化会影响音频的感知方式（改变音频的 AudioStreamPlayer3D.pitch_scale）。

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

通过跟踪在 _process 中改变的物体位置来模拟多普勒效应。与这些物体相比，该相机的相对速度的变化会影响音频的感知方式（改变音频的 AudioStreamPlayer3D.pitch_scale）。

属性说明

CameraAttributes attributes 🔗

• void set_attributes(value: CameraAttributes)

• CameraAttributes get_attributes()

该相机所使用的 CameraAttributes。

Compositor compositor 🔗

• void set_compositor(value: Compositor)

• Compositor get_compositor()

该相机所使用的 Compositor。

int cull_mask = 1048575 🔗

• void set_cull_mask(value: int)

• int get_cull_mask()

剔除掩码，描述该相机渲染了哪些 VisualInstance3D.layers。默认情况下，20 个用户可见层全都被渲染。

注意：由于 cull_mask 允许总共存储 32 个层，因此另外 12 个层仅供引擎内部使用，不会在编辑器中公开。使用脚本设置 cull_mask 允许你切换那些保留层，这对编辑器插件很有用。

要使用脚本更轻松地调整 cull_mask，请使用 get_cull_mask_value 和 set_cull_mask_value。

注意：VoxelGI、SDFGI 和 LightmapGI 将始终考虑所有层以确定对全局光照有贡献的内容。如果这是一个问题，请将网格的 GeometryInstance3D.gi_mode 设置为 GeometryInstance3D.GI_MODE_DISABLED，并将灯光的 Light3D.light_bake_mode 设置为 Light3D.BAKE_DISABLED，以将它们从全局光照中排除。

bool current = false 🔗

• void set_current(value: bool)

• bool is_current()

如果为 true，则祖级 Viewport 正在使用这个相机。

如果场景中有多个相机，总会有一个被设为当前相机。例如，假设场景中存在两个 Camera3D 节点并且只有一个为当前相机，那么如果把某一个相机的 current 设为 false 就会导致另一个相机被设为当前相机。

DopplerTracking doppler_tracking = 0 🔗

• void set_doppler_tracking(value: DopplerTracking)

• DopplerTracking get_doppler_tracking()

如果不是 DOPPLER_TRACKING_DISABLED，此相机将为在 _process 中变化的对象模拟多普勒效应。可能的值见 DopplerTracking。

Environment environment 🔗

• void set_environment(value: Environment)

• Environment get_environment()

此相机要使用的 Environment。

float far = 4000.0 🔗

• void set_far(value: float)

• float get_far()

该相机相对于其局部 Z 轴到远剔除边界的距离。较高的值允许相机看得更远，而减少 far 如果会导致对象被部分或完全剔除，则可以提高性能。

float fov = 75.0 🔗

• void set_fov(value: float)

• float get_fov()

相机的视野角度（单位为度）。仅适用于透视模式。由于 keep_aspect 锁定一个轴，因此 fov 设置另一个轴的视角。

作为参考，默认的垂直视野值（70.0）相当于以下水平 FOV：

• 在 4:3 视口中约 91.31 度

• 在 16:10 视口中约 101.67 度

• 在 16:9 视口中约 107.51 度

• 在 21:9 视口中约 121.63 度

Vector2 frustum_offset = Vector2(0, 0) 🔗

• void set_frustum_offset(value: Vector2)

• Vector2 get_frustum_offset()

相机的视锥偏移。可以更改默认值，以创建如 Y-shearing 一样的“倾斜的视锥”效果。

注意：仅在 projection 为 PROJECTION_FRUSTUM 时有效。

float h_offset = 0.0 🔗

• void set_h_offset(value: float)

• float get_h_offset()

相机视口的水平（X）偏移量。

KeepAspect keep_aspect = 1 🔗

• void set_keep_aspect_mode(value: KeepAspect)

• KeepAspect get_keep_aspect_mode()

在 fov/size 调整时要锁定的轴。可以是 KEEP_WIDTH 或 KEEP_HEIGHT。

float near = 0.05 🔗

• void set_near(value: float)

• float get_near()

该相机相对于其局部 Z 轴到近剔除边界的距离。较低的值允许相机看到更靠近其原点的对象，但代价是整个范围内的精度较低。低于默认值的值会导致 Z 冲突增加。

ProjectionType projection = 0 🔗

• void set_projection(value: ProjectionType)

• ProjectionType get_projection()

相机的投影模式。在 PROJECTION_PERSPECTIVE 模式下，物体与相机局部空间的Z距离会影响其感知的大小。

float size = 1.0 🔗

• void set_size(value: float)

• float get_size()

该相机的大小，单位为米，描述的是完整的宽度或者高度，取决于 keep_aspect。仅适用于正交和视锥模式。

float v_offset = 0.0 🔗

• void set_v_offset(value: float)

• float get_v_offset()

相机视口的垂直（Y）偏移量。

方法说明

void clear_current(enable_next: bool = true) 🔗

如果这是当前相机，则将其从当前相机中移除。如果 enable_next 为 true，则请求使下一个相机（如果有）成为当前相机。

Projection get_camera_projection() const 🔗

返回该相机用于渲染至关联视口的投影矩阵。相机必须是场景树的一部分才能正常工作。

RID get_camera_rid() const 🔗

从 RenderingServer 返回该相机的 RID。

Transform3D get_camera_transform() const 🔗

返回该相机的变换，该变换会加上垂直（v_offset）和水平（h_offset）偏移；以及 XRCamera3D 等子类相机对相机位置和方向所做的任何其他调整。

bool get_cull_mask_value(layer_number: int) const 🔗

返回是否启用了 cull_mask 的指定层，该层由一个介于 1 和 20 之间的给定 layer_number 指定。

Array[Plane] get_frustum() const 🔗

以世界空间单位将相机的视锥平面作为 Plane 数组按以下顺序返回：near、far、left、top、right、bottom。不要与 frustum_offset 混淆。

RID get_pyramid_shape_rid() 🔗

返回包含该相机视锥的锥体形状的 RID，忽略相机的近处平面。锥体的尖端代表该相机的位置。

bool is_position_behind(world_point: Vector3) const 🔗

如果给定位置在相机后面（链接图的蓝色部分），则返回 true。查看此图以了解位置查询方法的概述。

注意：返回 false 的位置可能仍然在相机的视野之外。

bool is_position_in_frustum(world_point: Vector3) const 🔗

如果给定位置在相机的视锥内（位于链接图中的绿色部分），则返回 true。查看此图以了解位置查询方法的概述。

void make_current() 🔗

使此相机成为 Viewport 的当前相机（见类的说明）。如果相机节点在场景树之外，一旦添加，它将尝试成为当前相机。

Vector3 project_local_ray_normal(screen_point: Vector2) const 🔗

返回从屏幕点位置沿相机方向的法向量。正交相机会被归一化。透视相机考虑到透视、屏幕宽度/高度等因素。

Vector3 project_position(screen_point: Vector2, z_depth: float) const 🔗

返回世界空间中的 3D 点，该点映射到平面上 Viewport 矩形中的给定 2D 坐标，该平面是距相机到场景的给定 z_depth 距离。

Vector3 project_ray_normal(screen_point: Vector2) const 🔗

返回世界空间中的法线向量，即通过逆相机投影将点投影到 Viewport 矩形上的结果。这对于以（原点，法线）的形式投射光线，以进行对象相交或拾取很有用。

Vector3 project_ray_origin(screen_point: Vector2) const 🔗

返回世界空间中的 3D 位置，即通过逆相机投影将点投影到 Viewport 矩形上的结果。这对于以（原点，法线）的形式投射光线，以进行对象相交或拾取很有用。

void set_cull_mask_value(layer_number: int, value: bool) 🔗

基于 value，启用或禁用 cull_mask 中的指定层，该层由一个介于 1 和 20 之间的给定 layer_number 指定。

void set_frustum(size: float, offset: Vector2, z_near: float, z_far: float) 🔗

通过指定的以世界空间单位为单位的 size、offset、以及 z_near 和 z_far 裁剪平面，将相机投影设置为视锥模式（见 PROJECTION_FRUSTUM）。另见 frustum_offset。

void set_orthogonal(size: float, z_near: float, z_far: float) 🔗

通过指定的以世界空间单位为单位的 size、以及 z_near 和 z_far 裁剪平面，将相机投影设置为正交模式（参见 PROJECTION_ORTHOGONAL）。（作为提示，2D 游戏经常使用这种投影，其值以像素为单位指定。）

void set_perspective(fov: float, z_near: float, z_far: float) 🔗

通过指定的以度为单位的 fov（视野）角度，以及以世界空间单位为单位的 z_near 和 z_far 裁剪平面，将相机投影设置为透视模式（参见 PROJECTION_PERSPECTIVE）。

Vector2 unproject_position(world_point: Vector3) const 🔗

返回映射到世界空间中给定 3D 点的 Viewport 矩形中的 2D 坐标。

注意：当使用它在 3D 视口上定位 GUI 元素时，如果 3D 点在相机后面，请使用 is_position_behind 来防止它们出现：

# 该代码块是从 Node3D 继承的脚本的一部分。
# `control` 是对从 Control 继承的节点的引用。
control.visible = not get_viewport().get_camera_3d().is_position_behind(global_transform.origin)
control.position = get_viewport().get_camera_3d().unproject_position(global_transform.origin)