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. Если viewport не доступен при подъеме по дереву, камера зарегистрируется в глобальном viewport. Другими словами, камера просто предоставляет возможности 3D-отображения для Viewport, и без него сцена, зарегистрированная в этом Viewport (или в более высоких 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-масштабирование. Обычно это лучший вариант для проектов, работающих в портретном режиме, так как более высокие соотношения сторон выиграют от более широкого вертикального FOV.

KeepAspect KEEP_HEIGHT = 1

Сохраняет вертикальное соотношение сторон; также известно как масштабирование Hor+. Обычно это лучший вариант для проектов, работающих в ландшафтном режиме, поскольку более широкие соотношения сторон автоматически выигрывают от более широкого горизонтального поля зрения (FOV).

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

Отключает имитацию эффекта Доплера (по умолчанию).

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

Имитация эффекта Доплера путем отслеживания положений объектов, которые изменяются в _process. Изменения относительной скорости этой камеры по сравнению с этими объектами влияют на восприятие звука (изменяя AudioStreamPlayer3D.pitch_scale звука).

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

Имитация эффекта Доплера путем отслеживания положений объектов, которые изменяются в _physics_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.

Примечание: Эффект Доплера будет слышен на AudioStreamPlayer3D только в том случае, если AudioStreamPlayer3D.doppler_tracking не задано как AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED.

Environment environment 🔗

void set_environment(value: Environment)
Environment get_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
~121,63 градуса в окне просмотра 21:9

Vector2 frustum_offset = Vector2(0, 0) 🔗

void set_frustum_offset(value: Vector2)
Vector2 get_frustum_offset()

Смещение фрустума (frustum) камеры. Его можно изменить со значения по умолчанию, чтобы создать эффекты «наклонного фрустума», такие как 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 🔗

Возвращает RID камеры из RenderingServer.

Transform3D get_camera_transform() const 🔗

Возвращает преобразование камеры плюс вертикальное (v_offset) и горизонтальное (h_offset) смещения; и любые другие корректировки, внесенные в положение и ориентацию камеры подклассами камер, такими как XRCamera3D.

bool get_cull_mask_value(layer_number: int) const 🔗

Возвращает, включен ли указанный слой cull_mask, учитывая layer_number от 1 до 20.

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 🔗

Возвращает трехмерную точку в мировом пространстве, которая сопоставляется с заданной двухмерной координатой в прямоугольнике Viewport на плоскости, которая находится на заданном расстоянии z_depth от камеры вглубь сцены.

Vector3 project_ray_normal(screen_point: Vector2) const 🔗

Возвращает вектор нормали в мировом пространстве, который является результатом проецирования точки на прямоугольник Viewport обратной проекцией камеры. Это полезно для отбрасывания лучей в форме (origin, normal) для пересечения или выбора объектов.

Vector3 project_ray_origin(screen_point: Vector2) const 🔗

Возвращает 3D-позицию в мировом пространстве, которая является результатом проецирования точки на прямоугольник Viewport обратной проекцией камеры. Это полезно для отбрасывания лучей в форме (origin, normal) для пересечения или выбора объектов.

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

На основе value включает или отключает указанный слой в cull_mask при заданном layer_number от 1 до 20.

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

Устанавливает проекцию камеры в режим усеченного конуса (см. PROJECTION_FRUSTUM), указывая size, offset и плоскости отсечения z_near и z_far в единицах мирового пространства. Параметр size представляет размер ближней плоскости, либо ее ширину, либо высоту в зависимости от значения keep_aspect. См. также frustum_offset.

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

Устанавливает проекцию камеры в ортогональный режим (см. PROJECTION_ORTHOGONAL), указывая size и плоскости отсечения z_near и z_far в единицах мирового пространства.

Кстати, в 3D-играх, которые выглядят как 2D, часто используется эта проекция, где size указывается в пикселях.

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

Устанавливает проекцию камеры в режим перспективы (см. PROJECTION_PERSPECTIVE), указывая угол fov (поле зрения) в градусах, а также плоскости отсечения z_near и z_far в единицах мирового пространства.

Vector2 unproject_position(world_point: Vector3) const 🔗

Возвращает 2D-координату в прямоугольнике Viewport, которая сопоставляется с заданной 3D-точкой в мировом пространстве.

Примечание: При использовании этого для позиционирования элементов GUI в 3D-окне просмотра используйте is_position_behind(), чтобы предотвратить их появление, если 3D-точка находится за камерой:

# Этот блок кода является частью скрипта, наследуемого от 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)