Viewport

继承： Node < Object

派生： SubViewport, Window

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

描述

Viewport（视口）会在屏幕中创建不同的视图，或是在其他视口中创建子视图。视口上会显示 2D 子节点，也会渲染 Camera3D 3D 子节点。

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

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

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

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

教程

• 使用视口

• Viewport 和画布变换

• 3D GUI 演示

• 2D 中的 3D 演示

• 3D 中的 2D 演示

• 屏幕捕捉演示

• 动态分屏演示

• 3D Viewport 缩放演示

属性

方法

信号

gui_focus_changed ( Control node )

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

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_MAX = 2

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

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

DebugDraw DEBUG_DRAW_SDFGI_PROBES = 17

DebugDraw DEBUG_DRAW_GI_BUFFER = 18

DebugDraw DEBUG_DRAW_DISABLE_LOD = 19

DebugDraw DEBUG_DRAW_CLUSTER_OMNI_LIGHTS = 20

DebugDraw DEBUG_DRAW_CLUSTER_SPOT_LIGHTS = 21

DebugDraw DEBUG_DRAW_CLUSTER_DECALS = 22

DebugDraw DEBUG_DRAW_CLUSTER_REFLECTION_PROBES = 23

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

SDFOversize SDF_OVERSIZE_150_PERCENT = 2

SDFOversize SDF_OVERSIZE_200_PERCENT = 3

SDFOversize SDF_OVERSIZE_MAX = 4

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

enum VRSMode:

VRSMode VRS_DISABLED = 0

VRS 已禁用。

VRSMode VRS_TEXTURE = 1

VRS 使用一个纹理。请注意，对于立体视觉，请为每个视图使用带有纹理的纹理图集。

VRSMode VRS_XR = 2

VRS 纹理由主 XRInterface 提供。

VRSMode VRS_MAX = 3

代表 VRSMode 枚举的大小。

属性说明

bool audio_listener_enable_2d = false

• void set_as_audio_listener_2d ( bool value )

• bool is_audio_listener_2d ( )

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

bool audio_listener_enable_3d = false

• void set_as_audio_listener_3d ( bool value )

• bool is_audio_listener_3d ( )

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

int canvas_cull_mask = 4294967295

• void set_canvas_cull_mask ( int value )

• int get_canvas_cull_mask ( )

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

DefaultCanvasItemTextureFilter canvas_item_default_texture_filter = 1

• void set_default_canvas_item_texture_filter ( DefaultCanvasItemTextureFilter value )

• DefaultCanvasItemTextureFilter get_default_canvas_item_texture_filter ( )

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

DefaultCanvasItemTextureRepeat canvas_item_default_texture_repeat = 0

• void set_default_canvas_item_texture_repeat ( DefaultCanvasItemTextureRepeat value )

• DefaultCanvasItemTextureRepeat get_default_canvas_item_texture_repeat ( )

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

Transform2D canvas_transform

• void set_canvas_transform ( Transform2D value )

• Transform2D get_canvas_transform ( )

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

DebugDraw debug_draw = 0

• void set_debug_draw ( DebugDraw value )

• DebugDraw get_debug_draw ( )

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

bool disable_3d = false

• void set_disable_3d ( bool value )

• bool is_3d_disabled ( )

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

float fsr_sharpness = 0.2

• void set_fsr_sharpness ( float value )

• 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 ( Transform2D value )

• Transform2D get_global_canvas_transform ( )

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

bool gui_disable_input = false

• void set_disable_input ( bool value )

• bool is_input_disabled ( )

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

bool gui_embed_subwindows = false

• void set_embedding_subwindows ( bool value )

• bool is_embedding_subwindows ( )

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

bool gui_snap_controls_to_pixels = true

• void set_snap_controls_to_pixels ( bool value )

• bool is_snap_controls_to_pixels_enabled ( )

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

bool handle_input_locally = true

• void set_handle_input_locally ( bool value )

• 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 ( float value )

• 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 ( MSAA value )

• MSAA get_msaa_2d ( )

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

MSAA msaa_3d = 0

• void set_msaa_3d ( MSAA value )

• MSAA get_msaa_3d ( )

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

bool own_world_3d = false

• void set_use_own_world_3d ( bool value )

• bool is_using_own_world_3d ( )

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

bool physics_object_picking = false

• void set_physics_object_picking ( bool value )

• bool get_physics_object_picking ( )

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

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

bool physics_object_picking_sort = false

• void set_physics_object_picking_sort ( bool value )

• 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 ( bool value )

• bool get_positional_shadow_atlas_16_bits ( )

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

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_0 = 2

• void set_positional_shadow_atlas_quadrant_subdiv ( int quadrant, PositionalShadowAtlasQuadrantSubdiv subdiv )

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv ( int quadrant ) const

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

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_1 = 2

• void set_positional_shadow_atlas_quadrant_subdiv ( int quadrant, PositionalShadowAtlasQuadrantSubdiv subdiv )

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv ( int quadrant ) const

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

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_2 = 3

• void set_positional_shadow_atlas_quadrant_subdiv ( int quadrant, PositionalShadowAtlasQuadrantSubdiv subdiv )

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv ( int quadrant ) const

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

PositionalShadowAtlasQuadrantSubdiv positional_shadow_atlas_quad_3 = 4

• void set_positional_shadow_atlas_quadrant_subdiv ( int quadrant, PositionalShadowAtlasQuadrantSubdiv subdiv )

• PositionalShadowAtlasQuadrantSubdiv get_positional_shadow_atlas_quadrant_subdiv ( int quadrant ) const

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

int positional_shadow_atlas_size = 2048

• void set_positional_shadow_atlas_size ( int value )

• int get_positional_shadow_atlas_size ( )

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

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

Scaling3DMode scaling_3d_mode = 0

• void set_scaling_3d_mode ( Scaling3DMode value )

• 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 ( float value )

• 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 ( ScreenSpaceAA value )

• ScreenSpaceAA get_screen_space_aa ( )

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

SDFOversize sdf_oversize = 1

• void set_sdf_oversize ( SDFOversize value )

• SDFOversize get_sdf_oversize ( )

目前没有这个属性的描述。请帮我们贡献一个！

SDFScale sdf_scale = 1

• void set_sdf_scale ( SDFScale value )

• SDFScale get_sdf_scale ( )

目前没有这个属性的描述。请帮我们贡献一个！

bool snap_2d_transforms_to_pixel = false

• void set_snap_2d_transforms_to_pixel ( bool value )

• bool is_snap_2d_transforms_to_pixel_enabled ( )

目前没有这个属性的描述。请帮我们贡献一个！

bool snap_2d_vertices_to_pixel = false

• void set_snap_2d_vertices_to_pixel ( bool value )

• bool is_snap_2d_vertices_to_pixel_enabled ( )

目前没有这个属性的描述。请帮我们贡献一个！

float texture_mipmap_bias = 0.0

• void set_texture_mipmap_bias ( float value )

• 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 ( bool value )

• bool has_transparent_background ( )

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

bool use_debanding = false

• void set_use_debanding ( bool value )

• 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 ( bool value )

• bool is_using_hdr_2d ( )

如果为 true，则 2D 渲染会使用高动态范围格式的帧缓冲，与 3D 帧缓冲的位深度一致。使用 Forward+ 渲染器时为 RGBA16 帧缓冲，而使用 Mobile 渲染器时为 RGB10_A2 帧缓冲。另外，2D 渲染是发生在线性色彩空间的，会在传输至屏幕前转换至 sRGB 空间（如果 Viewport 与屏幕进行了关联）。这意味着在实际情况下，Viewport 的最终效果不会被限制在 0-1 的范围内，无需色彩空间调整就能够用于 3D 渲染。这样 2D 渲染就能够利用到需要高动态范围的效果（例如 2D 辉光），并且能够大幅提升需要大量细节内容的效果。

注意：使用 GL Compatibility 渲染器时无效，因为 GL Compatibility 渲染器出于性能的原因始终使用低动态范围。

bool use_occlusion_culling = false

• void set_use_occlusion_culling ( bool value )

• 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 ( bool value )

• bool is_using_taa ( )

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

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

bool use_xr = false

• void set_use_xr ( bool value )

• bool is_using_xr ( )

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

VRSMode vrs_mode = 0

• void set_vrs_mode ( VRSMode value )

• VRSMode get_vrs_mode ( )

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

Texture2D vrs_texture

• void set_vrs_texture ( Texture2D value )

• Texture2D get_vrs_texture ( )

vrs_mode 为 VRS_TEXTURE 时使用的纹理。

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

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

World2D world_2d

• void set_world_2d ( World2D value )

• World2D get_world_2d ( )

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

World3D world_3d

• void set_world_3d ( World3D value )

• 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 ( int layer ) const

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

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 ( int quadrant ) const

返回指定象限的 PositionalShadowAtlasQuadrantSubdiv。

int get_render_info ( RenderInfoType type, RenderInfo info )

返回给定类型的渲染统计。选项见 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。

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 ( InputEvent event, bool in_local_coords=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 ( String text )

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

void push_unhandled_input ( InputEvent event, bool in_local_coords=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._shortcut_input

• Node._unhandled_key_input

• Node._unhandled_input

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

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

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

已弃用。请改用 push_input。

void set_canvas_cull_mask_bit ( int layer, bool enable )

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

void set_input_as_handled ( )

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

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

void set_positional_shadow_atlas_quadrant_subdiv ( int quadrant, PositionalShadowAtlasQuadrantSubdiv subdiv )

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

void update_mouse_cursor_state ( )

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

void warp_mouse ( Vector2 position )

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

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

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.