Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Camera3D¶

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

描述¶

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

教程¶

第三人称射击演示

属性¶

CameraAttributes	attributes
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 ( bool enable_next=true )
Projection	get_camera_projection ( ) const
RID	get_camera_rid ( ) const
Transform3D	get_camera_transform ( ) const
bool	get_cull_mask_value ( int layer_number ) const
Plane[]	get_frustum ( ) const
RID	get_pyramid_shape_rid ( )
bool	is_position_behind ( Vector3 world_point ) const
bool	is_position_in_frustum ( Vector3 world_point ) const
void	make_current ( )
Vector3	project_local_ray_normal ( Vector2 screen_point ) const
Vector3	project_position ( Vector2 screen_point, float z_depth ) const
Vector3	project_ray_normal ( Vector2 screen_point ) const
Vector3	project_ray_origin ( Vector2 screen_point ) const
void	set_cull_mask_value ( int layer_number, bool value )
void	set_frustum ( float size, Vector2 offset, float z_near, float z_far )
void	set_orthogonal ( float size, float z_near, float z_far )
void	set_perspective ( float fov, float z_near, float z_far )
Vector2	unproject_position ( Vector3 world_point ) 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 ( CameraAttributes value )
CameraAttributes get_attributes ( )

该相机所使用的 CameraAttributes。

int cull_mask = 1048575

void set_cull_mask ( int value )
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 ( bool value )
bool is_current ( )

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

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

DopplerTracking doppler_tracking = 0

void set_doppler_tracking ( DopplerTracking value )
DopplerTracking get_doppler_tracking ( )

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

Environment environment

void set_environment ( Environment value )
Environment get_environment ( )

此相机要使用的 Environment。

float far = 4000.0

void set_far ( float value )
float get_far ( )

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

float fov = 75.0

void set_fov ( float value )
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 ( Vector2 value )
Vector2 get_frustum_offset ( )

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

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

float h_offset = 0.0

void set_h_offset ( float value )
float get_h_offset ( )

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

KeepAspect keep_aspect = 1

void set_keep_aspect_mode ( KeepAspect value )
KeepAspect get_keep_aspect_mode ( )

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

float near = 0.05

void set_near ( float value )
float get_near ( )

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

ProjectionType projection = 0

void set_projection ( ProjectionType value )
ProjectionType get_projection ( )

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

float size = 1.0

void set_size ( float value )
float get_size ( )

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

float v_offset = 0.0

void set_v_offset ( float value )
float get_v_offset ( )

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

方法说明¶

void clear_current ( bool enable_next=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 ( int layer_number ) const

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

Plane[] get_frustum ( ) const

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

RID get_pyramid_shape_rid ( )

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

bool is_position_behind ( Vector3 world_point ) const

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

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

bool is_position_in_frustum ( Vector3 world_point ) const

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

void make_current ( )

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

Vector3 project_local_ray_normal ( Vector2 screen_point ) const

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

Vector3 project_position ( Vector2 screen_point, float z_depth ) const

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

Vector3 project_ray_normal ( Vector2 screen_point ) const

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

Vector3 project_ray_origin ( Vector2 screen_point ) const

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

void set_cull_mask_value ( int layer_number, bool value )

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

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

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

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

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

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

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

Vector2 unproject_position ( Vector3 world_point ) 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)