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 в единицах мирового пространства. См. также 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)