Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Camera3D

继承： Node3D < Node < Object

派生： XRCamera3D

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

描述

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

教程

第三人称射击（TPS）演示

属性

CameraAttributes	attributes
Compositor	compositor
int	cull_mask	`1048575`
bool	current	`false`
DopplerTracking	doppler_tracking	`0`
Environment	environment
float	far	`4000.0`
float	fov	`75.0`
Vector2	frustum_offset	`Vector2(0, 0)`
float	h_offset	`0.0`
KeepAspect	keep_aspect	`1`
float	near	`0.05`
ProjectionType	projection	`0`
float	size	`1.0`
float	v_offset	`0.0`

方法

void	clear_current(enable_next: bool = true)
Projection	get_camera_projection() const
RID	get_camera_rid() const
Transform3D	get_camera_transform() const
bool	get_cull_mask_value(layer_number: int) const
Array[Plane]	get_frustum() const
RID	get_pyramid_shape_rid()
bool	is_position_behind(world_point: Vector3) const
bool	is_position_in_frustum(world_point: Vector3) const
void	make_current()
Vector3	project_local_ray_normal(screen_point: Vector2) const
Vector3	project_position(screen_point: Vector2, z_depth: float) const
Vector3	project_ray_normal(screen_point: Vector2) const
Vector3	project_ray_origin(screen_point: Vector2) const
void	set_cull_mask_value(layer_number: int, value: bool)
void	set_frustum(size: float, offset: Vector2, z_near: float, z_far: float)
void	set_orthogonal(size: float, z_near: float, z_far: float)
void	set_perspective(fov: float, z_near: float, z_far: float)
Vector2	unproject_position(world_point: Vector3) const

枚举

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)