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.

Camera3D

继承: Node3D < Node < Object

派生: XRCamera3D

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

描述

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

教程

属性

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 🔗

该相机所使用的 CameraAttributes


Compositor 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_valueset_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 🔗

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


Environment environment 🔗

此相机要使用的 Environment


float far = 4000.0 🔗

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


float fov = 75.0 🔗

相机的视野角度(单位为度)。仅适用于透视模式。由于 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 一样的“倾斜的视锥”效果。

注意:仅在 projectionPROJECTION_FRUSTUM 时有效。


float h_offset = 0.0 🔗

  • void set_h_offset(value: float)

  • float get_h_offset()

相机视口的水平(X)偏移量。


KeepAspect keep_aspect = 1 🔗

fov/size 调整时要锁定的轴。可以是 KEEP_WIDTHKEEP_HEIGHT


float near = 0.05 🔗

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


ProjectionType projection = 0 🔗

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


float size = 1.0 🔗

该相机的大小,单位为米,描述的是完整的宽度或者高度,取决于 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_nexttrue,则请求使下一个相机(如果有)成为当前相机。


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) 🔗

通过指定的以世界空间单位为单位的 sizeoffset、以及 z_nearz_far 裁剪平面,将相机投影设置为视锥模式(见 PROJECTION_FRUSTUM)。另见 frustum_offset


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

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


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

通过指定的以度为单位的 fov(视野)角度,以及以世界空间单位为单位的 z_nearz_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)