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...
Viewport
派生： SubViewport, Window
视口的抽象基类。对绘图以及与游戏世界的交互进行了封装。
描述
Viewport 在屏幕中创建不同的视图，或在另一个视口内创建子视图。子 2D 节点将显示在其上，子 Camera3D 3D 节点也将在其上渲染。
视口也可以拥有自己的 2D 或 3D 世界，这样就不会与其他视口共享绘制的内容。
视口也可以选择作为音频监听器，这样就可以根据 2D 或 3D 相机子节点生成位置音频。
另外，在设备有多个屏幕的情况下，可以将视口分配给不同的屏幕。
最后，视口也可以充当渲染目标，在这种情况下，除非使用与其相关联的纹理进行绘制，否则它们将不可见。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
physics_interpolation_mode |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
方法
信号
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_METALFX_SPATIAL = 3
Use the MetalFX spatial upscaler for the viewport's 3D buffer.
The amount of scaling can be set using scaling_3d_scale.
Values less than 1.0 will be result in the viewport being upscaled using MetalFX. Values greater than 1.0 are not supported and bilinear downsampling will be used instead. A value of 1.0 disables scaling.
More information: MetalFX.
Note: Only supported when the Metal rendering driver is in use, which limits this scaling mode to macOS and iOS.
Scaling3DMode SCALING_3D_MODE_METALFX_TEMPORAL = 4
Use the MetalFX temporal upscaler for the viewport's 3D buffer.
The amount of scaling can be set using scaling_3d_scale. To determine the minimum input scale, use the RenderingDevice.limit_get method with RenderingDevice.LIMIT_METALFX_TEMPORAL_SCALER_MIN_SCALE.
Values less than 1.0 will be result in the viewport being upscaled using MetalFX. Values greater than 1.0 are not supported and bilinear downsampling will be used instead. A value of 1.0 will use MetalFX at native resolution as a TAA solution.
More information: MetalFX.
Note: Only supported when the Metal rendering driver is in use, which limits this scaling mode to macOS and iOS.
Scaling3DMode SCALING_3D_MODE_MAX = 5
代表 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 AnisotropicFiltering: 🔗
AnisotropicFiltering ANISOTROPY_DISABLED = 0
Anisotropic filtering is disabled.
AnisotropicFiltering ANISOTROPY_2X = 1
Use 2× anisotropic filtering.
AnisotropicFiltering ANISOTROPY_4X = 2
Use 4× anisotropic filtering. This is the default value.
AnisotropicFiltering ANISOTROPY_8X = 3
Use 8× anisotropic filtering.
AnisotropicFiltering ANISOTROPY_16X = 4
Use 16× anisotropic filtering.
AnisotropicFiltering ANISOTROPY_MAX = 5
Represents the size of the AnisotropicFiltering enum.
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
Objects are displayed as wireframe models.
Note: RenderingServer.set_debug_generate_wireframes must be called before loading any meshes for wireframes to be visible when using the Compatibility renderer.
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 枚举的大小。
属性说明
AnisotropicFiltering anisotropic_filtering_level = 2 🔗
void set_anisotropic_filtering_level(value: AnisotropicFiltering)
AnisotropicFiltering get_anisotropic_filtering_level()
Sets the maximum number of samples to take when using anisotropic filtering on textures (as a power of two). A higher sample count will result in sharper textures at oblique angles, but is more expensive to compute. A value of 0 forcibly disables anisotropic filtering, even on materials where it is enabled.
The anisotropic filtering level also affects decals and light projectors if they are configured to use anisotropic filtering. See ProjectSettings.rendering/textures/decals/filter and ProjectSettings.rendering/textures/light_projectors/filter.
Note: In 3D, for this setting to have an effect, set BaseMaterial3D.texture_filter to BaseMaterial3D.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC or BaseMaterial3D.TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC on materials.
Note: In 2D, for this setting to have an effect, set CanvasItem.texture_filter to CanvasItem.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC or CanvasItem.TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC on the CanvasItem node displaying the texture (or in CanvasTexture). However, anisotropic filtering is rarely useful in 2D, so only enable it for textures in 2D if it makes a meaningful visual difference.
bool audio_listener_enable_2d = false 🔗
如果为 true，该视口将处理 2D 音频流。
bool audio_listener_enable_3d = false 🔗
如果为 true，该视口将处理 3D 音频流。
int canvas_cull_mask = 4294967295 🔗
渲染层，该 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 的屏幕位置很有用。相对于该视口的全局画布变换。
在调试时，用于测试渲染的几何图形的叠加模式。
禁用 3D 渲染（但保留 2D 渲染）。
确定使用 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 🔗
如果为 true，该视口将不接收输入事件。
bool gui_embed_subwindows = false 🔗
如果为 true，子窗口（弹出窗口和对话框）将和控件等节点一样嵌入到应用程序窗口中。如果为 false，它们将显示为操作系统处理的独立窗口。
bool gui_snap_controls_to_pixels = true 🔗
如果为 true，该视口上的 GUI 控件将完美地放置像素。
bool handle_input_locally = true 🔗
如果为 true，则这个视口会把收到的输入事件标记为已被自身处理。如果为 false，则由第一个设置本地处理输入的父级视口进行这样的操作。
SubViewportContainer 会自动将其包含的 Viewport 的这个属性设置为 false。
另见 set_input_as_handled 和 is_input_handled。
float mesh_lod_threshold = 1.0 🔗
用于在 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）。
The multisample antialiasing mode for 2D/Canvas rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of MSAA_2X or MSAA_4X is best unless targeting very high-end systems. This has no effect on shader-induced aliasing or texture aliasing.
See also ProjectSettings.rendering/anti_aliasing/quality/msaa_2d and RenderingServer.viewport_set_msaa_2d.
The multisample antialiasing mode for 3D rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of MSAA_2X or MSAA_4X is best unless targeting very high-end systems. See also bilinear scaling 3D scaling_3d_mode for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing.
See also ProjectSettings.rendering/anti_aliasing/quality/msaa_3d and RenderingServer.viewport_set_msaa_3d.
如果为 true，则该视口会使用 world_3d 中定义的 World3D 的唯一副本。
bool physics_object_picking = false 🔗
如果为 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 🔗
如果为 true，则对象会按照固定的顺序接收鼠标拾取事件，首先会按各自的 CanvasItem.z_index 排序，然后按它们在场景树中的位置排序。如果为 false，则顺序不确定。
注意：默认情况下禁用此设置，因为它可能会产生昂贵的计算成本。
注意：排序发生在选择可拾取对象之后。因为同时能够被拾取的对象最多只有 64 个，所以无法保证 CanvasItem.z_index 最大的对象能够接收到拾取事件。
bool positional_shadow_atlas_16_bits = true 🔗
使用 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 🔗
阴影图集的分辨率（用于全向灯和聚光灯）。该值将向上舍入到最接近的 2 次幂。
注意：如果设置为 0，将根本看不到任何阴影（包括定向阴影）。可以通过降低 CPU 和 GPU 负载来显著提升在低端系统上的性能（因为绘制不带阴影的场景需要的绘制调用更少）。
Scaling3DMode scaling_3d_mode = 0 🔗
void set_scaling_3d_mode(value: Scaling3DMode)
Scaling3DMode get_scaling_3d_mode()
Sets scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible.
To control this property on the root viewport, set the ProjectSettings.rendering/scaling_3d/mode project setting.
float scaling_3d_scale = 1.0 🔗
根据视口大小缩放 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()
Sets the screen-space antialiasing method used. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry.
See also ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa and RenderingServer.viewport_set_screen_space_aa.
SDFOversize sdf_oversize = 1 🔗
void set_sdf_oversize(value: SDFOversize)
SDFOversize get_sdf_oversize()
控制 2D 带符号距离场应该覆盖原始视口中多大的区域。该 SDF 可以在 CanvasItem 着色器中采样，用于 GPUParticles2D 碰撞。生成带符号距离场时，较高的值能够让部分处于视口外的遮挡器也纳入考虑范围，但会以牺牲性能为代价。如果你注意到 LightOccluder2D 离开视口时粒子会穿过遮挡器，就可以增大这个设置。
每一侧每个轴上都会添加指定的百分比。例如，使用默认的 SDF_OVERSIZE_120_PERCENT，带符号距离场将覆盖视口外每侧（顶部、右侧、底部、左侧）20% 的视口大小。
用于 2D 带符号距离场的分辨率比例。值越高，相机移动时带符号距离场越精确、越稳定，但性能会受到影响。
bool snap_2d_transforms_to_pixel = false 🔗
如果为 true，则 CanvasItem 节点将在内部捕捉到全像素。它们的位置仍然可以是亚像素，但小数不会产生影响。这会导致更清晰的外观，但代价是移动不太流畅，尤其是在启用 Camera2D 平滑时。
bool snap_2d_vertices_to_pixel = false 🔗
如果为 true，则 CanvasItem 节点的顶点将捕捉到完整像素。仅影响最终顶点位置，而不影响变换。这会导致更清晰的外观，但代价是移动不太流畅，尤其是在启用 Camera2D 平滑时。
float texture_mipmap_bias = 0.0 🔗
通过从更低或更高的 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。
如果为 true，该视口应使其背景渲染为透明。
If true, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is not affected by debanding unless the Environment.background_mode is Environment.BG_CANVAS.
In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
See also ProjectSettings.rendering/anti_aliasing/quality/use_debanding and RenderingServer.viewport_set_use_debanding.
If true, 2D rendering will use an high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be an RGBA16 framebuffer, while when using the Mobile renderer it will be an RGB10_A2 framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the 0-1 range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients.
Note: This setting will have no effect when using the Compatibility renderer, which always renders in low dynamic range for performance reasons.
bool use_occlusion_culling = false 🔗
如果为 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 可以启用。
Enables temporal antialiasing for this viewport. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion.
Note: The implementation is not complete yet, some visual instances such as particles and skinned meshes may show artifacts.
See also ProjectSettings.rendering/anti_aliasing/quality/use_taa and RenderingServer.viewport_set_use_taa.
如果为 true，则视口将使用主 XR 接口来渲染 XR 输出。如果适用，这可以得到立体图像，渲染结果会输出到头戴设备。
用于这个视口的可变速率着色（Variable Rate Shading，VRS）模式。请注意，如果硬件不支持 VRS，则会忽略此属性。
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，可以作为 2D 环境源。
自定义的 World3D，可以作为 3D 环境源。
方法说明
World2D find_world_2d() const 🔗
返回该视口的首个有效 World2D，在它自身及任何 Viewport 祖先节点的 world_2d 属性中查找。
World3D find_world_3d() const 🔗
返回这个视口的第一个有效 World3D，会在自身和 Viewport 祖先的 world_3d 属性中搜索。
AudioListener2D get_audio_listener_2d() const 🔗
Returns the currently active 2D audio listener. Returns null if there are no active 2D audio listeners, in which case the active 2D camera will be treated as listener.
AudioListener3D get_audio_listener_3d() const 🔗
Returns the currently active 3D audio listener. Returns null if there are no active 3D audio listeners, in which case the active 3D camera will be treated as listener.
Camera2D get_camera_2d() const 🔗
Returns the currently active 2D camera. Returns null if there are no active cameras.
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 🔗
返回从视口的坐标到包含窗口管理器窗口的屏幕坐标的变换。
Transform2D get_stretch_transform() const 🔗
Returns the automatically computed 2D stretch transform, taking the Viewport's stretch settings into account. The final value is multiplied by Window.content_scale_factor, but only for the root viewport. If this method is called on a SubViewport (e.g., in a scene tree with SubViewportContainer and SubViewport), the scale factor of the root window will not be applied. Using Transform2D.get_scale on the returned value, this can be used to compensate for scaling when zooming a Camera2D node, or to scale down a TextureRect to be pixel-perfect regardless of the automatically computed scale factor.
Note: Due to how pixel scaling works, the returned transform's X and Y scale may differ slightly, even when Window.content_scale_aspect is set to a mode that preserves the pixels' aspect ratio. If Window.content_scale_aspect is Window.CONTENT_SCALE_ASPECT_IGNORE, the X and Y scale may differ significantly.
ViewportTexture get_texture() const 🔗
Returns the viewport's texture.
Note: When trying to store the current texture (e.g. in a file), it might be completely black or outdated if used too early, especially when used in e.g. Node._ready. To make sure the texture you get is correct, you can await RenderingServer.frame_post_draw signal.
func _ready():
await RenderingServer.frame_post_draw
$Viewport.get_texture().get_image().save_png("user://Screenshot.png")
Note: When use_hdr_2d is true the returned texture will be an HDR image encoded in linear space.
RID get_viewport_rid() const 🔗
返回该视口在 RenderingServer 的 RID。
Rect2 get_visible_rect() const 🔗
返回全局屏幕坐标中的可见矩形。
void gui_cancel_drag() 🔗
Cancels the drag operation that was previously started through Control._get_drag_data or forced with Control.force_drag.
Variant gui_get_drag_data() const 🔗
返回 GUI 的拖动数据，该数据先前由 Control._get_drag_data 返回。
Control gui_get_focus_owner() const 🔗
Returns the currently focused Control within this viewport. If no Control is focused, returns null.
Control gui_get_hovered_control() const 🔗
Returns the Control that the mouse is currently hovering over in this viewport. If no Control has the cursor, returns null.
Typically the leaf Control node or deepest level of the subtree which claims hover. This is very useful when used together with Node.is_ancestor_of to find if the mouse is within a control tree.
bool gui_is_drag_successful() const 🔗
如果拖拽操作成功，则返回 true。
bool gui_is_dragging() const 🔗
Returns true if a drag operation is currently ongoing and where the drop action could happen in this viewport.
Alternative to Node.NOTIFICATION_DRAG_BEGIN and Node.NOTIFICATION_DRAG_END when you prefer polling the value.
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 notify_mouse_entered() 🔗
Inform the Viewport that the mouse has entered its area. Use this function before sending an InputEventMouseButton or InputEventMouseMotion to the Viewport with push_input. See also notify_mouse_exited.
Note: In most cases, it is not necessary to call this function because SubViewport nodes that are children of SubViewportContainer are notified automatically. This is only necessary when interacting with viewports in non-default ways, for example as textures in TextureRect or with an Area3D that forwards input events.
void notify_mouse_exited() 🔗
Inform the Viewport that the mouse has left its area. Use this function when the node that displays the viewport notices the mouse has left the area of the displayed viewport. See also notify_mouse_entered.
Note: In most cases, it is not necessary to call this function because SubViewport nodes that are children of SubViewportContainer are notified automatically. This is only necessary when interacting with viewports in non-default ways, for example as textures in TextureRect or with an Area3D that forwards input events.
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 进行重映射。
调用这个方法会将调用传播至子节点，按照以下顺序调用：
Control._gui_input 仅用于 Control 节点
如果某个方法使用 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，则该事件的位置使用的是视口坐标系。
调用这个方法会将调用传播至子节点，按照以下顺序调用：
如果某个方法使用 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 没有影响。