Viewport

继承： Node < Object

派生： SubViewport, Window

视口的抽象基类。对绘图以及与游戏世界的交互进行了封装。

描述

Viewport 在屏幕中创建不同的视图，或在另一个视口内创建子视图。子 2D 节点将显示在其上，子 Camera3D 3D 节点也将在其上渲染。

视口也可以拥有自己的 2D 或 3D 世界，这样就不会与其他视口共享绘制的内容。

视口也可以选择作为音频监听器，这样就可以根据 2D 或 3D 相机子节点生成位置音频。

另外，在设备有多个屏幕的情况下，可以将视口分配给不同的屏幕。

最后，视口也可以充当渲染目标，在这种情况下，除非使用与其相关联的纹理进行绘制，否则它们将不可见。

教程

• 使用视口

• Viewport 和画布变换

• 3D 视口中的 GUI 演示

• 2D 视口中的 3D 演示

• 3D 视口中的 2D 演示

• 屏幕捕捉演示

• 动态分屏演示

• 3D 分辨率缩放演示

属性

方法

信号

gui_focus_changed(node: Control) 🔗

当控件节点获取键盘焦点时触发。

注意：控件节点失去焦点不会导致触发该信号。

size_changed() 🔗

当视口的大小被改变时发出，无论是通过调整窗口大小，还是通过其他方式改变的大小。

枚举

enum PositionalShadowAtlasQuadrantSubdiv: 🔗

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_DISABLED = 0

不使用该象限。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_1 = 1

该象限仅由一张阴影贴图使用。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_4 = 2

该象限将被分为 4 份，最多被 4 张阴影贴图使用。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_16 = 3

该象限将被分为 16 份，最多被 16 张阴影贴图使用。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_64 = 4

该象限将被分为 64 份，最多被 64 张阴影贴图使用。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_256 = 5

该象限将被分为 256 份，最多被 256 张阴影贴图使用。除非 positional_shadow_atlas_size 非常高，否则该象限中的阴影分辨率将非常低。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_1024 = 6

该象限将被分为 1024 份，最多被 1024 张阴影贴图使用。除非 positional_shadow_atlas_size 非常高，否则该象限中的阴影分辨率将非常低。

PositionalShadowAtlasQuadrantSubdiv SHADOW_ATLAS_QUADRANT_SUBDIV_MAX = 7

代表 PositionalShadowAtlasQuadrantSubdiv 枚举的大小。

enum Scaling3DMode: 🔗

Scaling3DMode SCALING_3D_MODE_BILINEAR = 0

对该视口的 3D 缓冲区使用双线性缩放。缩放的程度可以使用 scaling_3d_scale 设置。小于 1.0 的值会产生欠采样的效果，大于 1.0 会产生超采样的效果。值为 1.0 时禁用缩放。

Scaling3DMode SCALING_3D_MODE_FSR = 1

对该视口的 3D 缓冲区使用 AMD FidelityFX 超分辨率 1.0 升采样技术。缩放的程度可以使用 scaling_3d_scale 设置。小于 1.0 的值会使用 FSR 进行放大。不支持大于 1.0 的值，会改用双线性降采样。值为 1.0 时禁用缩放。

Scaling3DMode SCALING_3D_MODE_FSR2 = 2

对视口的 3D 缓冲区使用 AMD FidelityFX 超分辨率 2.2 放大。可以使用 scaling_3d_scale 设置缩放量。小于 1.0 的值将导致使用 FSR2 放大视口。不支持大于 1.0 的值，将改用双线性降采样。1.0 的值将使用原生分辨率下的 FSR2 作为 TAA 解决方案。

Scaling3DMode SCALING_3D_MODE_MAX = 3

代表 Scaling3DMode 枚举的大小。

enum MSAA: 🔗

MSAA MSAA_DISABLED = 0

禁用多重采样抗锯齿模式。这是默认值，也是最快的设置。

MSAA MSAA_2X = 1

使用 2 倍多重采样抗锯齿。性能成本中等。有助于显着减少锯齿，但 4× MSAA 看起来仍然要好得多。

MSAA MSAA_4X = 2

使用 4 倍多重采样抗锯齿。性能成本显著，通常是性能和质量之间的良好折衷。

MSAA MSAA_8X = 3

使用 8 倍多重采样抗锯齿。性能成本极高。在实际游戏条件下，4× 和 8× MSAA 之间的差异可能并不总是可见的。可能在低端和较旧的硬件上不受支持。

MSAA MSAA_MAX = 4

代表 MSAA 枚举的大小。

enum ScreenSpaceAA: 🔗

ScreenSpaceAA SCREEN_SPACE_AA_DISABLED = 0

不要在全屏后处理中执行抗锯齿。

ScreenSpaceAA SCREEN_SPACE_AA_FXAA = 1

使用快速近似抗锯齿（Fast Approximate Anti-Aliasing）。FXAA 是一种流行的屏幕空间抗锯齿方法，速度很快，但会让图像变模糊，使用较低分辨率时尤为显著。1440p 和 4K 等较高分辨率下效果仍然不错。

ScreenSpaceAA SCREEN_SPACE_AA_MAX = 2

代表 ScreenSpaceAA 枚举的大小。

enum RenderInfo: 🔗

RenderInfo RENDER_INFO_OBJECTS_IN_FRAME = 0

帧中对象的数量。

RenderInfo RENDER_INFO_PRIMITIVES_IN_FRAME = 1

帧中的顶点数量。

RenderInfo RENDER_INFO_DRAW_CALLS_IN_FRAME = 2

帧中的绘制调用量。

RenderInfo RENDER_INFO_MAX = 3

代表 RenderInfo 枚举的大小。

enum RenderInfoType: 🔗

RenderInfoType RENDER_INFO_TYPE_VISIBLE = 0

可见渲染阶段（不含阴影）。

RenderInfoType RENDER_INFO_TYPE_SHADOW = 1

阴影渲染阶段。根据开启了阴影的灯光数以及方向阴影的拆分数，同一个对象可能会渲染多次。

RenderInfoType RENDER_INFO_TYPE_CANVAS = 2

画布项渲染。包括所有 2D 渲染。

RenderInfoType RENDER_INFO_TYPE_MAX = 3

代表 RenderInfoType 枚举的大小。

enum DebugDraw: 🔗

DebugDraw DEBUG_DRAW_DISABLED = 0

对象正常显示。

DebugDraw DEBUG_DRAW_UNSHADED = 1

显示的对象没有光照信息。

DebugDraw DEBUG_DRAW_LIGHTING = 2

显示对象时不使用纹理，仅使用光照信息。

DebugDraw DEBUG_DRAW_OVERDRAW = 3

对象通过加法混合显示为半透明，因此可以看到它们在彼此之上绘制的位置。更高的过度绘制意味着在绘制隐藏在其他像素后面的像素时浪费了性能。

DebugDraw DEBUG_DRAW_WIREFRAME = 4

以线框模型的形式显示对象。

DebugDraw DEBUG_DRAW_NORMAL_BUFFER = 5

显示对象时不使用光照信息，将纹理替换为法线贴图。

DebugDraw DEBUG_DRAW_VOXEL_GI_ALBEDO = 6

仅使用来自 VoxelGI 的反照率值显示对象。

DebugDraw DEBUG_DRAW_VOXEL_GI_LIGHTING = 7

仅使用来自 VoxelGI 的照明值显示对象。

DebugDraw DEBUG_DRAW_VOXEL_GI_EMISSION = 8

仅使用来自 VoxelGI 的自发光颜色显示对象。

DebugDraw DEBUG_DRAW_SHADOW_ATLAS = 9

在 Viewport 的左上象限中绘制存储来自 OmniLight3D 和 SpotLight3D 的阴影的阴影图集。

DebugDraw DEBUG_DRAW_DIRECTIONAL_SHADOW_ATLAS = 10

在 Viewport 的左上象限中绘制存储来自 DirectionalLight3D 的阴影的阴影图集。

DebugDraw DEBUG_DRAW_SCENE_LUMINANCE = 11

在 Viewport 的左上象限中绘制场景亮度缓冲（如果可用）。

DebugDraw DEBUG_DRAW_SSAO = 12

绘制屏幕空间环境光遮蔽纹理而不是场景，以便可以清楚地看到它是如何影响对象的。为了使该显示模式起作用，必须在 WorldEnvironment 中设置 Environment.ssao_enabled。

DebugDraw DEBUG_DRAW_SSIL = 13

绘制屏幕空间间接照明纹理而不是场景，以便可以清楚地看到它是如何影响对象的。为了使该显示模式起作用，必须在 WorldEnvironment 中设置 Environment.ssil_enabled。

DebugDraw DEBUG_DRAW_PSSM_SPLITS = 14

为场景中的 DirectionalLight3D 的每个 PSSM 分割着色不同的颜色，以便可以看到分割的位置。按顺序，它们将被着色为红色、绿色、蓝色和黄色。

DebugDraw DEBUG_DRAW_DECAL_ATLAS = 15

在 Viewport 的左上象限中绘制 Decal 使用的贴花和光投影仪的纹理。

DebugDraw DEBUG_DRAW_SDFGI = 16

绘制用于渲染带符号距离场全局光照（SDFGI）的级联。

如果当前环境的 Environment.sdfgi_enabled 为 false 或平台不支持 SDFGI，则不执行任何操作。

DebugDraw DEBUG_DRAW_SDFGI_PROBES = 17

绘制用于带符号距离场全局照明（SDFGI）的探测器。

如果当前环境的 Environment.sdfgi_enabled 为 false 或平台不支持 SDFGI，则不执行任何操作。

DebugDraw DEBUG_DRAW_GI_BUFFER = 18

绘制用于全局光照（GI）的缓冲。

DebugDraw DEBUG_DRAW_DISABLE_LOD = 19

使用最高多边形数绘制对象，不使用低细节层次（LOD）。

DebugDraw DEBUG_DRAW_CLUSTER_OMNI_LIGHTS = 20

绘制 OmniLight3D 节点优化光照渲染所使用的集群。

DebugDraw DEBUG_DRAW_CLUSTER_SPOT_LIGHTS = 21

绘制 SpotLight3D 节点优化光照渲染所使用的集群。

DebugDraw DEBUG_DRAW_CLUSTER_DECALS = 22

绘制 Decal 节点优化贴花渲染所使用的集群。

DebugDraw DEBUG_DRAW_CLUSTER_REFLECTION_PROBES = 23

绘制 ReflectionProbe 节点优化贴花渲染所使用的集群。

DebugDraw DEBUG_DRAW_OCCLUDERS = 24

绘制用于遮挡剔除的缓冲。

DebugDraw DEBUG_DRAW_MOTION_VECTORS = 25

在视口中绘制向量线段，表示帧与帧之间像素的移动。

DebugDraw DEBUG_DRAW_INTERNAL_BUFFER = 26

在应用后处理之前绘制场景的内部分辨率缓冲区。

enum DefaultCanvasItemTextureFilter: 🔗

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST = 0

纹理过滤仅从最近的像素读取。这使得纹理从近距离看是像素化的，从远处看是颗粒状的（由于多级渐远纹理没有被采样）。

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR = 1

纹理过滤在最近的 4 个像素之间进行混合。这使得纹理从近处看起来很平滑，从远处看起来却有颗粒感（由于多级渐远纹理没有被采样）。

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 2

纹理过滤在最近的 4 个像素和最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来平滑，从远处看起来也平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤从最近的像素读取并在最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来像素化，从远处看起来平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_MAX = 4

代表 DefaultCanvasItemTextureFilter 枚举的大小。

enum DefaultCanvasItemTextureRepeat: 🔗

DefaultCanvasItemTextureRepeat DEFAULT_CANVAS_ITEM_TEXTURE_REPEAT_DISABLED = 0

禁用纹理重复。相反，当读取 0-1 范围之外的 UV 时，该值将被钳制在纹理的边缘，从而导致纹理的边界看起来被拉长。

DefaultCanvasItemTextureRepeat DEFAULT_CANVAS_ITEM_TEXTURE_REPEAT_ENABLED = 1

当 UV 坐标超出 0-1 范围时，使纹理能够重复。如果使用其中一种线性过滤模式，则当采样器过滤纹理边缘时，这可能会导致纹理边缘出现伪影。

DefaultCanvasItemTextureRepeat DEFAULT_CANVAS_ITEM_TEXTURE_REPEAT_MIRROR = 2

重复时翻转该纹理，使边缘对齐而不是突然改变。

DefaultCanvasItemTextureRepeat DEFAULT_CANVAS_ITEM_TEXTURE_REPEAT_MAX = 3

代表 DefaultCanvasItemTextureRepeat 枚举的大小。

enum SDFOversize: 🔗

SDFOversize SDF_OVERSIZE_100_PERCENT = 0

带符号距离场仅覆盖视口矩形本身。

SDFOversize SDF_OVERSIZE_120_PERCENT = 1

带符号距离场的每个边界都覆盖超出视口大小 20% 的范围。

SDFOversize SDF_OVERSIZE_150_PERCENT = 2

带符号距离场的每个边界都覆盖超出视口大小 50% 的范围。

SDFOversize SDF_OVERSIZE_200_PERCENT = 3

带符号距离场的每个边界都覆盖超出视口大小 100% 的范围（翻倍）。

SDFOversize SDF_OVERSIZE_MAX = 4

代表 SDFOversize 枚举的大小。

enum SDFScale: 🔗

SDFScale SDF_SCALE_100_PERCENT = 0

使用完整分辨率渲染带符号距离场。

SDFScale SDF_SCALE_50_PERCENT = 1

使用视口一半的分辨率渲染带符号距离场。

SDFScale SDF_SCALE_25_PERCENT = 2

使用视口四分之一的分辨率渲染带符号距离场。

SDFScale SDF_SCALE_MAX = 3

代表 SDFScale 枚举的大小。

enum VRSMode: 🔗

VRSMode VRS_DISABLED = 0

禁用可变速率着色。

VRSMode VRS_TEXTURE = 1

可变速率着色使用纹理。请注意，使用立体视觉时请使用为每个视图提供纹理的纹理图集。

VRSMode VRS_XR = 2

可变速率着色纹理由主 XRInterface 提供。

VRSMode VRS_MAX = 3

代表 VRSMode 枚举的大小。

enum VRSUpdateMode: 🔗

VRSUpdateMode VRS_UPDATE_DISABLED = 0

可变速率着色的输入纹理将不会被处理。

VRSUpdateMode VRS_UPDATE_ONCE = 1

可变速率着色的输入纹理将被处理一次。

VRSUpdateMode VRS_UPDATE_ALWAYS = 2

可变速率着色的输入纹理将每帧进行处理。

VRSUpdateMode VRS_UPDATE_MAX = 3

代表 VRSUpdateMode 枚举的大小。

属性说明

bool audio_listener_enable_2d = false 🔗

• void set_as_audio_listener_2d(value: bool)

• bool is_audio_listener_2d()

如果为 true，该视口将处理 2D 音频流。

bool audio_listener_enable_3d = false 🔗

• void set_as_audio_listener_3d(value: bool)

• bool is_audio_listener_3d()

如果为 true，该视口将处理 3D 音频流。

int canvas_cull_mask = 4294967295 🔗

• void set_canvas_cull_mask(value: int)

• int get_canvas_cull_mask()

渲染层，该 Viewport 会渲染位于这些层中的 CanvasItem 节点。

DefaultCanvasItemTextureFilter canvas_item_default_texture_filter = 1 🔗

• void set_default_canvas_item_texture_filter(value: DefaultCanvasItemTextureFilter)

• DefaultCanvasItemTextureFilter get_default_canvas_item_texture_filter()

设置该 Viewport 中 CanvasItem 所使用的默认过滤模式。选项见 DefaultCanvasItemTextureFilter。

DefaultCanvasItemTextureRepeat canvas_item_default_texture_repeat = 0 🔗

• void set_default_canvas_item_texture_repeat(value: DefaultCanvasItemTextureRepeat)

• DefaultCanvasItemTextureRepeat get_default_canvas_item_texture_repeat()

设置该 Viewport 中 CanvasItem 所使用的默认重复模式。选项见 DefaultCanvasItemTextureRepeat。

Transform2D canvas_transform 🔗

• void set_canvas_transform(value: Transform2D)

• Transform2D get_canvas_transform()

该视口的画布变换，对改变所有子 CanvasItem 的屏幕位置很有用。相对于该视口的全局画布变换。

DebugDraw debug_draw = 0 🔗

• void set_debug_draw(value: DebugDraw)

• DebugDraw get_debug_draw()

在调试时，用于测试渲染的几何图形的叠加模式。

bool disable_3d = false 🔗

• void set_disable_3d(value: bool)

• bool is_3d_disabled()

禁用 3D 渲染（但保留 2D 渲染）。

float fsr_sharpness = 0.2 🔗

• void set_fsr_sharpness(value: float)

• float get_fsr_sharpness()

确定使用 FSR 放大模式时，放大后的图像的锐度。每个整数的锐度减半。值从 0.0（最锐利）到 2.0。高于 2.0 的值不会产生明显的差异。

要在根视口上控制此属性，请设置 ProjectSettings.rendering/scaling_3d/fsr_sharpness 项目设置。

Transform2D global_canvas_transform 🔗

• void set_global_canvas_transform(value: Transform2D)

• Transform2D get_global_canvas_transform()

该视口的全局画布变换。画布变换是相对于这个的。

bool gui_disable_input = false 🔗

• void set_disable_input(value: bool)

• bool is_input_disabled()

如果为 true，该视口将不接收输入事件。

bool gui_embed_subwindows = false 🔗

• void set_embedding_subwindows(value: bool)

• bool is_embedding_subwindows()

如果为 true，子窗口（弹出窗口和对话框）将和控件等节点一样嵌入到应用程序窗口中。如果为 false，它们将显示为操作系统处理的独立窗口。

bool gui_snap_controls_to_pixels = true 🔗

• void set_snap_controls_to_pixels(value: bool)

• bool is_snap_controls_to_pixels_enabled()

如果为 true，该视口上的 GUI 控件将完美地放置像素。

bool handle_input_locally = true 🔗

• void set_handle_input_locally(value: bool)

• bool is_handling_input_locally()

如果为 true，则这个视口会把收到的输入事件标记为已被自身处理。如果为 false，则由第一个设置本地处理输入的父级视口进行这样的操作。

SubViewportContainer 会自动将其包含的 Viewport 的这个属性设置为 false。

另见 set_input_as_handled 和 is_input_handled。

float mesh_lod_threshold = 1.0 🔗

• void set_mesh_lod_threshold(value: float)

• float get_mesh_lod_threshold()

用于在 Viewport 中渲染的网格的自动 LOD 偏置（类似于 ReflectionProbe.mesh_lod_threshold）。较高的值将使用生成了 LOD 变化的网格的较不详细版本。如果被设置为 0.0，则自动 LOD 将被禁用。增加 mesh_lod_threshold，以牺牲几何细节为代价提高性能。

要在根视口上控制该属性，请设置 ProjectSettings.rendering/mesh_lod/lod_change/threshold_pixels 项目设置。

注意：mesh_lod_threshold 不影响 GeometryInstance3D 可见性范围（也称为“手动”LOD 或分层 LOD）。

MSAA msaa_2d = 0 🔗

• void set_msaa_2d(value: MSAA)

• MSAA get_msaa_2d()

2D/画布渲染的多重采样抗锯齿模式。数字越高，得到的边缘越平滑，代价是性能也会显著降低。设为 2 或 4 为佳，除非目标是非常高端的系统。对由着色器或纹理导致的锯齿无效。

MSAA msaa_3d = 0 🔗

• void set_msaa_3d(value: MSAA)

• MSAA get_msaa_3d()

3D 渲染的多重采样抗锯齿模式。数字越高，得到的边缘越平滑，代价是性能也会显著降低。设为 2 或 4 为佳，除非目标是非常高端的系统。另请参阅 3D 的双线性缩放 scaling_3d_mode 实现超采样，能够提供更高的质量，但消耗也更高。对由着色器或纹理导致的锯齿无效。

bool own_world_3d = false 🔗

• void set_use_own_world_3d(value: bool)

• bool is_using_own_world_3d()

如果为 true，则该视口会使用 world_3d 中定义的 World3D 的唯一副本。

bool physics_object_picking = false 🔗

• void set_physics_object_picking(value: bool)

• bool get_physics_object_picking()

如果为 true，则视口中渲染的对象会成为鼠标拾取过程中的候选。

注意：同时能够被拾取的对象最多只有 64 个，选择的顺序是不确定的，每次拾取可能都不相同。

bool physics_object_picking_first_only = false 🔗

• void set_physics_object_picking_first_only(value: bool)

• bool get_physics_object_picking_first_only()

如果为 true，则鼠标拾取的过程中只会将 input_event 信号发送给一个物理对象。如果你只希望获取最顶层的对象，就必须同时启用 physics_object_picking_sort。

如果为 false，则鼠标拾取的过程中会将 input_event 信号发送给所有物理对象。

仅适用于 2D CanvasItem 对象的拾取。

bool physics_object_picking_sort = false 🔗

• void set_physics_object_picking_sort(value: bool)

• bool get_physics_object_picking_sort()

如果为 true，则对象会按照固定的顺序接收鼠标拾取事件，首先会按各自的 CanvasItem.z_index 排序，然后按它们在场景树中的位置排序。如果为 false，则顺序不确定。

注意：默认情况下禁用此设置，因为它可能会产生昂贵的计算成本。

注意：排序发生在选择可拾取对象之后。因为同时能够被拾取的对象最多只有 64 个，所以无法保证 CanvasItem.z_index 最大的对象能够接收到拾取事件。

bool positional_shadow_atlas_16_bits = true 🔗

• void set_positional_shadow_atlas_16_bits(value: bool)

• bool get_positional_shadow_atlas_16_bits()

使用 16 位的全向灯/聚光灯阴影深度贴图。启用后，阴影的精度会降低，可能造成阴影失真，但能够在部分设备上提升性能。

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_0 = 2 🔗

• void set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv)

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const

阴影图集上第一象限的细分量。

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_1 = 2 🔗

• void set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv)

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const

阴影图集上第二象限的细分量。

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_2 = 3 🔗

• void set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv)

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const

阴影图集上第三象限的细分量。

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_3 = 4 🔗

• void set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv)

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const

阴影图集上第四象限的细分量。

int positional_shadow_atlas_size = 2048 🔗

• void set_positional_shadow_atlas_size(value: int)

• int get_positional_shadow_atlas_size()

阴影图集的分辨率（用于全向灯和聚光灯）。该值将向上舍入到最接近的 2 次幂。

注意：如果设置为 0，将根本看不到任何阴影（包括定向阴影）。可以通过降低 CPU 和 GPU 负载来显著提升在低端系统上的性能（因为绘制不带阴影的场景需要的绘制调用更少）。

Scaling3DMode scaling_3d_mode = 0 🔗

• void set_scaling_3d_mode(value: Scaling3DMode)

• Scaling3DMode get_scaling_3d_mode()

设置缩放 3D 模式。双线性缩放会以不同的分辨率进行渲染，对视口进行欠采样或超采样。FidelityFX Super Resolution 1.0，缩写为 FSR，是一种放大技术，通过使用一种空间感知放大算法，以快速帧速率生成高质量图像。FSR 比双线性的性能消耗略高一些，但产生的图像质量却高得多。应尽可能使用 FSR。

要在根视口上控制这个属性，请使用项目设置 ProjectSettings.rendering/scaling_3d/mode。

float scaling_3d_scale = 1.0 🔗

• void set_scaling_3d_scale(value: float)

• float get_scaling_3d_scale()

根据视口大小缩放 3D 渲染缓冲区，使用 ProjectSettings.rendering/scaling_3d/mode 中指定的图像过滤器将输出图像缩放到完整的视口大小。比 1.0 小的值可以牺牲质量加速 3D 渲染（欠采样）。比 1.0 大的值仅在双线性模式下可用，可以提升 3D 渲染质量，但性能消耗较高（超采样）。另见多重采样抗锯齿 ProjectSettings.rendering/anti_aliasing/quality/msaa_3d，性能消耗明显更低，但只会对多边形的边缘进行平滑。

使用 FSR 放大时，AMD 推荐将以下值作为预设选项暴露给用户“极致质量：0.77”“质量：0.67”“平衡：0.59”“性能：0.5”，不暴露特定的缩放值。

要在根视口上控制这个属性，请使用项目设置 ProjectSettings.rendering/scaling_3d/scale。

ScreenSpaceAA screen_space_aa = 0 🔗

• void set_screen_space_aa(value: ScreenSpaceAA)

• ScreenSpaceAA get_screen_space_aa()

设置使用的屏幕空间抗锯齿方法。屏幕空间抗锯齿的原理是在后期处理着色器中选择性地模糊边缘。它与 MSAA 不同，后者在渲染对象时采用多个覆盖样本。屏幕空间抗锯齿方法通常比 MSAA 更快，并且会平滑高光锯齿，但往往会使场景显得模糊。

SDFOversize sdf_oversize = 1 🔗

• void set_sdf_oversize(value: SDFOversize)

• SDFOversize get_sdf_oversize()

控制 2D 带符号距离场应该覆盖原始视口中多大的区域。该 SDF 可以在 CanvasItem 着色器中采样，用于 GPUParticles2D 碰撞。生成带符号距离场时，较高的值能够让部分处于视口外的遮挡器也纳入考虑范围，但会以牺牲性能为代价。如果你注意到 LightOccluder2D 离开视口时粒子会穿过遮挡器，就可以增大这个设置。

每一侧每个轴上都会添加指定的百分比。例如，使用默认的 SDF_OVERSIZE_120_PERCENT，带符号距离场将覆盖视口外每侧（顶部、右侧、底部、左侧）20% 的视口大小。

SDFScale sdf_scale = 1 🔗

• void set_sdf_scale(value: SDFScale)

• SDFScale get_sdf_scale()

用于 2D 带符号距离场的分辨率比例。值越高，相机移动时带符号距离场越精确、越稳定，但性能会受到影响。

bool snap_2d_transforms_to_pixel = false 🔗

• void set_snap_2d_transforms_to_pixel(value: bool)

• bool is_snap_2d_transforms_to_pixel_enabled()

如果为 true，则 CanvasItem 节点将在内部捕捉到全像素。它们的位置仍然可以是亚像素，但小数不会产生影响。这会导致更清晰的外观，但代价是移动不太流畅，尤其是在启用 Camera2D 平滑时。

bool snap_2d_vertices_to_pixel = false 🔗

• void set_snap_2d_vertices_to_pixel(value: bool)

• bool is_snap_2d_vertices_to_pixel_enabled()

如果为 true，则 CanvasItem 节点的顶点将捕捉到完整像素。仅影响最终顶点位置，而不影响变换。这会导致更清晰的外观，但代价是移动不太流畅，尤其是在启用 Camera2D 平滑时。

float texture_mipmap_bias = 0.0 🔗

• void set_texture_mipmap_bias(value: float)

• float get_texture_mipmap_bias()

通过从更低或更高的 mipmap 中读取数据影响最终纹理的锐度（也叫“纹理 LOD 偏置”）。负值会让 mipmap 纹理更锐利，但从较远处观察时颗粒更明显，而正值会让 mipmap 纹理更模糊（即便凑近看也一样）。

启用时间抗锯齿（use_taa）会对这个值应用 -0.5 的偏移量，而启用 FXAA（screen_space_aa）则会对这个值应用 -0.25 的偏移量。如果同时启用 TAA 和 FXAA，则会对这个值应用 -0.75 的偏移量。

注意：如果 scaling_3d_scale 比 1.0 小（包含），则会使用 texture_mipmap_bias 自动调整 mipmap 偏置，内部会根据缩放系数进行计算。公式为 log2(scaling_3d_scale) + mipmap_bias。

要在根视口上控制这个属性，请使用项目设置 ProjectSettings.rendering/textures/default_filters/texture_mipmap_bias。

bool transparent_bg = false 🔗

• void set_transparent_background(value: bool)

• bool has_transparent_background()

如果为 true，该视口应使其背景渲染为透明。

bool use_debanding = false 🔗

• void set_use_debanding(value: bool)

• bool is_using_debanding()

如果为 true，则使用一个快速的后期处理滤镜，使 3D 的带状现象明显减少。除非 Environment.background_mode 为 Environment.BG_CANVAS，否则 2D 渲染不会受到去条带的影响。另见 ProjectSettings.rendering/anti_aliasing/quality/use_debanding。

在某些情况下，去条带可能会引入稍微明显的抖动图案。建议仅在实际需要时才启用去条带，因为抖动图案会使无损压缩的屏幕截图变大。

bool use_hdr_2d = false 🔗

• void set_use_hdr_2d(value: bool)

• bool is_using_hdr_2d()

如果为 true，则 2D 渲染将使用与 3D 帧缓冲的位深度相匹配的高动态范围（HDR）格式的帧缓冲。使用 Forward+ 渲染器时，这将是一个 RGBA16 帧缓冲，而使用 Mobile 渲染器时，这将是一个 RGB10_A2 帧缓冲。此外，2D 渲染将在线性色彩空间中进行，并将在传输到屏幕之前立即转换到 sRGB 空间（如果视口已连接到屏幕）。实际上，这意味着视口的最终结果不会被限制在 0-1 范围内，并且可以在 3D 渲染中使用而无需调整色彩空间。这使得 2D 渲染能够利用需要高动态范围的效果（例如 2D 辉光），并显著改善需要高度详细渐变的效果的外观。

注意：使用 GL Compatibility 渲染器时该设置将不起作用，因为 GL Compatibility 渲染器出于性能原因始终在低动态范围内渲染。

bool use_occlusion_culling = false 🔗

• void set_use_occlusion_culling(value: bool)

• bool is_using_occlusion_culling()

如果为 true，OccluderInstance3D 节点将被用于该视口中的 3D 遮挡剔除。对于根视口，ProjectSettings.rendering/occlusion_culling/use_occlusion_culling 必须改为被设置为 true。

注意：启用遮挡剔除会消耗一定的 CPU。仅当确实打算使用遮挡剔除时才启用它，并考虑场景是否真的可以从遮挡剔除中受益。具有很少或没有对象阻挡视图的大型开放场景，通常不会从遮挡剔除中受益更多。与遮挡剔除相比，大型开放场景通常从网格 LOD 和可见性范围（GeometryInstance3D.visibility_range_begin 和 GeometryInstance3D.visibility_range_end）中受益更多。

注意：由于内存限制，Web 导出模板中默认不支持遮挡剔除。编译自定义 Web 导出模板时使用 module_raycast_enabled=yes 可以启用。

bool use_taa = false 🔗

• void set_use_taa(value: bool)

• bool is_using_taa()

为该视口启用时间抗锯齿。TAA 通过抖动相机并累积最后渲染帧的图像来工作，运动向量渲染被用于解释相机和对象的运动。

注意：实现尚未完成，一些可视实例，如粒子和蒙皮网格可能会出现伪影。

bool use_xr = false 🔗

• void set_use_xr(value: bool)

• bool is_using_xr()

如果为 true，则视口将使用主 XR 接口来渲染 XR 输出。如果适用，这可以得到立体图像，渲染结果会输出到头戴设备。

VRSMode vrs_mode = 0 🔗

• void set_vrs_mode(value: VRSMode)

• VRSMode get_vrs_mode()

用于这个视口的可变速率着色（Variable Rate Shading，VRS）模式。请注意，如果硬件不支持 VRS，则会忽略此属性。

Texture2D vrs_texture 🔗

• void set_vrs_texture(value: Texture2D)

• Texture2D get_vrs_texture()

vrs_mode 为 VRS_TEXTURE 时使用的纹理。

该纹理必须使用无损压缩格式，以便可以精确匹配颜色。以下 VRS 密度会映射为各种颜色，较亮的颜色代表较低的着色精度。

- 1×1 = rgb(0, 0, 0) - #000000
- 1×2 = rgb(0, 85, 0) - #005500
- 2×1 = rgb(85, 0, 0) - #550000
- 2×2 = rgb(85, 85, 0) - #555500
- 2×4 = rgb(85, 170, 0) - #55aa00
- 4×2 = rgb(170, 85, 0) - #aa5500
- 4×4 = rgb(170, 170, 0) - #aaaa00
- 4×8 = rgb(170, 255, 0) - #aaff00 - 大多数硬件不支持
- 8×4 = rgb(255, 170, 0) - #ffaa00 - 大多数硬件不支持
- 8×8 = rgb(255, 255, 0) - #ffff00 - 大多数硬件不支持

VRSUpdateMode vrs_update_mode = 1 🔗

• void set_vrs_update_mode(value: VRSUpdateMode)

• VRSUpdateMode get_vrs_update_mode()

设置视口的可变速率着色（VRS）的更新模式。VRS 要求将输入纹理转换为硬件支持的 VRS 方法可用的格式。更新模式定义该操作发生的频率。如果 GPU 不支持 VRS，或者未启用 VRS，则该属性将被忽略。

World2D world_2d 🔗

• void set_world_2d(value: World2D)

• World2D get_world_2d()

自定义的 World2D，可以作为 2D 环境源。

World3D world_3d 🔗

• void set_world_3d(value: World3D)

• World3D get_world_3d()

自定义的 World3D，可以作为 3D 环境源。

方法说明

World2D find_world_2d() const 🔗

返回该视口的首个有效 World2D，在它自身及任何 Viewport 祖先节点的 world_2d 属性中查找。

World3D find_world_3d() const 🔗

返回这个视口的第一个有效 World3D，会在自身和 Viewport 祖先的 world_3d 属性中搜索。

Camera2D get_camera_2d() const 🔗

返回当前活动的 2D 相机。如果没有活动的相机，则返回 null。

Camera3D get_camera_3d() const 🔗

返回当前活动的 3D 相机。

bool get_canvas_cull_mask_bit(layer: int) const 🔗

返回渲染层遮罩上的某个比特位。

Array[Window] get_embedded_subwindows() const 🔗

返回该视口内可见的嵌入 Window 的列表。

注意：其他视口内的 Window 不会被列出。

Transform2D get_final_transform() const 🔗

返回从该视口的坐标系到嵌入器坐标系统的变换。

Vector2 get_mouse_position() const 🔗

返回该 Viewport 中鼠标的位置，使用该 Viewport 的坐标系。

PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const 🔗

返回指定象限的位置阴影图集象限细分。

int get_render_info(type: RenderInfoType, info: RenderInfo) 🔗

返回给定类型的渲染统计。选项见 RenderInfoType 和 RenderInfo。

Transform2D get_screen_transform() const 🔗

返回从视口的坐标到包含窗口管理器窗口的屏幕坐标的变换。

ViewportTexture get_texture() const 🔗

返回该视口的纹理

注意：保存当前纹理时（例如保存到文件中），如果时机过早则可能是全黑或过时的图片，尤其是在 Node._ready 等函数中使用时。要确保获得正确的纹理，你可以等待 RenderingServer.frame_post_draw 信号。

func _ready():
    await RenderingServer.frame_post_draw
    $Viewport.get_texture().get_image().save_png("user://Screenshot.png")

RID get_viewport_rid() const 🔗

返回该视口在 RenderingServer 的 RID。

Rect2 get_visible_rect() const 🔗

返回全局屏幕坐标中的可见矩形。

Variant gui_get_drag_data() const 🔗

返回 GUI 的拖动数据，该数据先前由 Control._get_drag_data 返回。

Control gui_get_focus_owner() const 🔗

返回这个视口中聚焦的 Control。如果没有聚焦任何 Control 则返回 null。

Control gui_get_hovered_control() const 🔗

返回当前鼠标在该视口中悬停的 Control。如果鼠标没有对应的 Control 则返回 null。

获取到悬停的通常是末端的 Control 节点或子树中最深的一级。与 Node.is_ancestor_of 配合的时候非常有用，可以查到鼠标是否位于某个控件树中。

bool gui_is_drag_successful() const 🔗

如果拖拽操作成功，则返回 true。

bool gui_is_dragging() const 🔗

如果该视口目前正在执行拖拽操作，则返回 true。

如果你更倾向于对其进行轮询，那么就可以作为 Node.NOTIFICATION_DRAG_BEGIN 和 Node.NOTIFICATION_DRAG_END 的替代品。

void gui_release_focus() 🔗

移除这个视口中当前聚焦 Control 的焦点。如果没有聚焦任何 Control，则什么都不做。

bool is_input_handled() const 🔗

返回当前的 InputEvent 是否已被处理。在 InputEvent 生命周期中调用 set_input_as_handled 前，输入事件都处于未处理状态。

通常作为 Node._input、Control._gui_input 等输入处理方法以及对应的信号处理函数的一部分来实现。

如果 handle_input_locally 为 false，则这个方法会尝试查找第一个本地处理输入的父级视口，并返回该视口的 is_input_handled。

void push_input(event: InputEvent, in_local_coords: bool = false) 🔗

在该 Viewport 中触发给定的 event 事件。可用于在不同视口之间传递 InputEvent，或者在本地应用通过网络传输或保存在文件中的事件。

如果 in_local_coords 为 false，则该事件中的位置使用的是嵌入器坐标系，会被转换至视口坐标系。如果 in_local_coords 为 true，则该事件的位置使用的是视口坐标系。

虽然这个方法的用途和 Input.parse_input_event 类似，但不会根据 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse 等项目设置对指定的 event 进行重映射。

调用这个方法会将调用传播至子节点，按照以下顺序调用：

• Node._input

• Control._gui_input 仅用于 Control 节点

• Node._shortcut_input

• Node._unhandled_key_input

• Node._unhandled_input

如果某个方法使用 set_input_as_handled 将输入标记为已处理，则列表中的后续方法均不会被调用。

如果没有任何方法处理该事件，并且 physics_object_picking 为 true，则该事件将用于物理对象的拾取。

void push_text_input(text: String) 🔗

辅助方法，会调用当前聚焦 Control 的 set_text() 方法，前提是该控件上定义了这个方法（例如聚焦 Control 为 Button 或 LineEdit）。

void push_unhandled_input(event: InputEvent, in_local_coords: bool = false) 🔗

已弃用： Use push_input instead.

在该 Viewport 中触发给定的 event 事件。可用于在不同视口之间传递 InputEvent，或者在本地应用通过网络传输或保存在文件中的事件。

如果 in_local_coords 为 false，则该事件中的位置使用的是嵌入器坐标系，会被转换至视口坐标系。如果 in_local_coords 为 true，则该事件的位置使用的是视口坐标系。

调用这个方法会将调用传播至子节点，按照以下顺序调用：

• Node._shortcut_input

• Node._unhandled_key_input

• Node._unhandled_input

如果某个方法使用 set_input_as_handled 将输入标记为已处理，则列表中的后续方法均不会被调用。

如果上述方法均未处理事件，并且 physics_object_picking 为 true，则该事件将用于物理对象的拾取。

注意：这个方法不会将输入事件传播至嵌入的 Window 和 SubViewport。

void set_canvas_cull_mask_bit(layer: int, enable: bool) 🔗

设置或清除碰撞掩码上的比特位。可以简化 Viewport 层的编辑。

void set_input_as_handled() 🔗

让输入停止继续沿着 SceneTree 向下传播。

注意：不会影响 Input 中的方法，只会影响事件的传播。

void set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv) 🔗

设置在指定象限内使用的细分数。较多的细分数可以让你在场景中一次拥有更多的阴影，但是会降低阴影的质量。一个好的做法是让象限具有不同数量的细分，并尽可能地减少细分。

void update_mouse_cursor_state() 🔗

根据当前鼠标光标的位置强制立即更新显示。包括更新鼠标光标的形状以及发送必要的 Control.mouse_entered、CollisionObject2D.mouse_entered、CollisionObject3D.mouse_entered、Window.mouse_entered 等信号，以及这些信号对应的 mouse_exited 版本。

void warp_mouse(position: Vector2) 🔗

使用该 Viewport 的坐标系，将鼠标指针移动到该 Viewport 中的指定位置。

注意：warp_mouse 仅支持 Windows、macOS 和 Linux。它对 Android、iOS 和 Web 没有影响。