Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
Viewport¶
派生： SubViewport, Window
视口的抽象基类。对绘图以及与游戏世界的交互进行了封装。
描述¶
Viewport（视口）会在屏幕中创建不同的视图，或是在其他视口中创建子视图。视口上会显示 2D 子节点，也会渲染 Camera3D 3D 子节点。
视口也可以拥有自己的 2D 或 3D 世界，这样就不会与其他视口共享绘制的内容。
视口也可以选择作为音频监听器，这样就可以根据 2D 或 3D 相机子节点生成位置音频。
另外，在设备有多个屏幕的情况下，可以将视口分配给不同的屏幕。
最后，视口也可以充当渲染目标，在这种情况下，除非使用与其相关联的纹理进行绘制，否则它们将不可见。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
方法¶
信号¶
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 个像素之间混合。如果你想要避免像素化风格，但又不想使用 mipmap，那么请使用这个选项。
DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 2
纹理过滤器读取最邻近的 mipmap 中的最邻近的像素。带有 mipmap 的纹理的最快读取方法。
DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3
纹理过滤在最近的 4 个像素之间和最近的 2 个 mipmap 之间混合。
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
如果为 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 ( 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
在调试时，用于测试渲染的几何图形的叠加模式。
bool disable_3d = false
禁用 3D 渲染（但保留 2D 渲染）。
float fsr_sharpness = 0.2
确定使用 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
如果为 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）。
MSAA msaa_2d = 0
2D/画布渲染的多重采样抗锯齿模式。数字越高，得到的边缘越平滑，代价是性能也会显著降低。设为 2 或 4 为佳，除非目标是非常高端的系统。对由着色器或纹理导致的锯齿无效。
MSAA msaa_3d = 0
3D 渲染的多重采样抗锯齿模式。数字越高，得到的边缘越平滑，代价是性能也会显著降低。设为 2 或 4 为佳，除非目标是非常高端的系统。另请参阅 3D 的双线性缩放 scaling_3d_mode 实现超采样，能够提供更高的质量，但消耗也更高。对由着色器或纹理导致的锯齿无效。
bool own_world_3d = false
如果为 true，则该视口会使用 world_3d 中定义的 World3D 的唯一副本。
bool physics_object_picking = false
如果为 true，则视口中渲染的对象会成为鼠标拾取过程中的候选。
注意：同时能够被拾取的对象最多只有 64 个，选择的顺序是不确定的，每次拾取可能都不相同。
bool physics_object_picking_sort = false
如果为 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
阴影图集的分辨率（用于全向灯和聚光灯）。该值将向上舍入到最接近的 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