Camera¶

派生： XRCamera

摄像机节点，从一个角度显示。

描述¶

Camera是一个特殊的节点，显示从当前位置可见的内容。摄像机在最近的Viewport节点中注册自己（当树上升时）。每个视口只能激活一个摄像机。如果树上升时没有可用的视口，摄像机将在全局视口中注册。换句话说，摄像机只是向Viewport提供3D显示功能，如果没有Viewport，在该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

保持水平长宽比；也称为垂直缩放。这通常是竖屏项目的最佳选择，因为更高的纵横比将受益于更宽的垂直FOV。

KeepAspect KEEP_HEIGHT = 1

保留垂直长宽比；也称为Hor+缩放。这通常是在横向模式下运行的项目的最佳选择，因为更宽的纵横比将自动受益于更宽的水平FOV。

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

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

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

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

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

通过跟踪在_physics_process中改变的对象的位置来模拟多普勒效应。与这些对象相比，此摄像机的相对速度的变化会影响音频的感知方式（改变音频的AudioPlayer.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()

描述此摄像机渲染哪些VisualRender.layers的剔除蒙版。默认情况下，渲染所有20个用户可见图层。

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

要使用脚本更容易地调整cull_mask，请使用get_cull_mask_value()和set_cull_mask_value()。

注意：VoxelGI、SDFGI和Lightmass将始终考虑所有图层以确定有助于全局照明的因素。如果这是一个问题，请将网格的GeometryRender.gi_mode设置为GeometryRender.GI_MODE_DISABLED，将光源的Light.light_bake_mode设置为Light.BAKE_DISABLED以将它们排除在全局照明之外。

bool current = false 🔗

void set_current(value: bool)
bool is_current()

如果true，则祖先Viewport当前正在使用此摄像机。

如果场景中有多个摄像头，则始终将一个摄像头设为当前。例如，如果场景中存在两个Camera节点，但只有一个是当前的，则将一个摄像头的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设置另一个轴的视场角。

作为参考，默认的垂直视野值（75.0）等效于以下的水平FOV：

-~91.31度的4:3视口

-~101.67度在16:10的视口

-~107.51度在16:9的视口

-21:9视口中的121.63度

Vector2 frustum_offset = Vector2(0, 0) 🔗

void set_frustum_offset(value: Vector2)
Vector2 get_frustum_offset()

摄像机的平截头体偏移。这可以从默认更改为创建“倾斜平截头体”效果，例如Y剪切。

注：仅当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）偏移量；以及子类摄像机（如XRCamera）对摄像机位置和方向所做的任何其他调整。

bool get_cull_mask_value(layer_number: int) const 🔗

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

Array[Plane] get_frustum() const 🔗

按以下顺序返回摄像机在世界空间单位中的截头体平面作为Plane数组：近、远、左、上、右、下。不要与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()来防止它们出现：

# 此代码块是继承自 Item3D 的脚本的一部分。
# '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)