Viewport¶

继承： Item < Object

派生： SubViewport, Window

视口的抽象基类。封装绘图和与虚拟世界的交互。

描述¶

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

可选地，视口可以有自己的2D或3D世界，因此它不会与其他视口共享它绘制的内容。

视口也可以选择成为音频侦听器，因此它们会根据它的2D或3D摄像机子级生成位置音频。

此外，如果设备有多个屏幕，可以将视口分配给不同的屏幕。

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

属性¶

AnisotropicFiltering	anisotropic_filtering_level	`2`
bool	audio_listener_enable_2d	`false`
bool	audio_listener_enable_3d	`false`
int	canvas_cull_mask	`4294967295`
DefaultCanvasItemTextureFilter	canvas_item_default_texture_filter	`1`
DefaultCanvasItemTextureRepeat	canvas_item_default_texture_repeat	`0`
Transform2D	canvas_transform
DebugDraw	debug_draw	`0`
bool	disable_3d	`false`
float	fsr_sharpness	`0.2`
Transform2D	global_canvas_transform
bool	gui_disable_input	`false`
bool	gui_embed_subwindows	`false`
bool	gui_snap_controls_to_pixels	`true`
bool	handle_input_locally	`true`
float	mesh_lod_threshold	`1.0`
MSAA	msaa_2d	`0`
MSAA	msaa_3d	`0`
bool	own_world_3d	`false`
PhysicsInterpolationMode	physics_interpolation_mode	`1` (overrides Item)
bool	physics_object_picking	`false`
bool	physics_object_picking_first_only	`false`
bool	physics_object_picking_sort	`false`
bool	positional_shadow_atlas_16_bits	`true`
PositionalShadowAtlasQuadrantSubdiv	positional_shadow_atlas_quad_0	`2`
PositionalShadowAtlasQuadrantSubdiv	positional_shadow_atlas_quad_1	`2`
PositionalShadowAtlasQuadrantSubdiv	positional_shadow_atlas_quad_2	`3`
PositionalShadowAtlasQuadrantSubdiv	positional_shadow_atlas_quad_3	`4`
int	positional_shadow_atlas_size	`2048`
Scaling3DMode	scaling_3d_mode	`0`
float	scaling_3d_scale	`1.0`
ScreenSpaceAA	screen_space_aa	`0`
SDFOversize	sdf_oversize	`1`
SDFScale	sdf_scale	`1`
bool	snap_2d_transforms_to_pixel	`false`
bool	snap_2d_vertices_to_pixel	`false`
float	texture_mipmap_bias	`0.0`
bool	transparent_bg	`false`
bool	use_debanding	`false`
bool	use_hdr_2d	`false`
bool	use_occlusion_culling	`false`
bool	use_taa	`false`
bool	use_xr	`false`
VRSMode	vrs_mode	`0`
Texture2D	vrs_texture
VRSUpdateMode	vrs_update_mode	`1`
World2D	world_2d
World3D	world_3d

方法¶

World2D	find_world_2d() const
World3D	find_world_3d() const
AudioListener2D	get_audio_listener_2d() const
AudioListener	get_audio_listener_3d() const
Camera2D	get_camera_2d() const
Camera	get_camera_3d() const
bool	get_canvas_cull_mask_bit(layer: int) const
Array[Window]	get_embedded_subwindows() const
Transform2D	get_final_transform() const
Vector2	get_mouse_position() const
PositionalShadowAtlasQuadrantSubdiv	get_positional_shadow_atlas_quadrant_subdiv(quadrant: int) const
int	get_render_info(type: RenderInfoType, info: RenderInfo)
Transform2D	get_screen_transform() const
Transform2D	get_stretch_transform() const
ViewportTexture	get_texture() const
RID	get_viewport_rid() const
Rect2	get_visible_rect() const
void	gui_cancel_drag()
Variant	gui_get_drag_data() const
Control	gui_get_focus_owner() const
Control	gui_get_hovered_control() const
bool	gui_is_drag_successful() const
bool	gui_is_dragging() const
void	gui_release_focus()
bool	is_input_handled() const
void	notify_mouse_entered()
void	notify_mouse_exited()
void	push_input(event: InputEvent, in_local_coords: bool = false)
void	push_text_input(text: String)
void	push_unhandled_input(event: InputEvent, in_local_coords: bool = false)
void	set_canvas_cull_mask_bit(layer: int, enable: bool)
void	set_input_as_handled()
void	set_positional_shadow_atlas_quadrant_subdiv(quadrant: int, subdiv: PositionalShadowAtlasQuadrantSubdiv)
void	update_mouse_cursor_state()
void	warp_mouse(position: Vector2)

信号¶

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

使用MetalFX空间升级器作为视口的3D缓冲区。

可以使用scaling_3d_scale设置缩放量。

小于1.0的值将导致使用MetalFX升级视口。不支持大于1.0的值，将使用双线性下采样。1.0的值禁用缩放。

更多信息：MetalFX。

注意：仅在使用Metal渲染驱动程序时受支持，这将此缩放模式限制为macOS和iOS。

Scaling3DMode SCALING_3D_MODE_METALFX_TEMPORAL = 4

使用MetalFX时间升级器作为视口的3D缓冲区。

可以使用scaling_3d_scale设置缩放量。要确定最小输入缩放，请使用带有RenderingDevice.LIMIT_METALFX_TEMPORAL_SCALER_MIN_SCALE的RenderingDevice.limit_get()方法。

小于1.0的值将导致使用MetalFX升级视口。不支持大于1.0的值，将使用双线性下采样。1.0的值将使用MetalFX作为TAA解决方案。

更多信息：MetalFX。

注意：仅在使用Metal渲染驱动程序时受支持，这将此缩放模式限制为macOS和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

各向异性过滤被禁用。

AnisotropicFiltering ANISOTROPY_2X = 1

使用2×各向异性滤波。

AnisotropicFiltering ANISOTROPY_4X = 2

使用4×各向异性滤波。这是默认值。

AnisotropicFiltering ANISOTROPY_8X = 3

使用8×各向异性滤波。

AnisotropicFiltering ANISOTROPY_16X = 4

使用16×各向异性滤波。

AnisotropicFiltering ANISOTROPY_MAX = 5

表示AnisotropicFiltering枚举的大小。

enum ScreenSpaceAA: 🔗

ScreenSpaceAA SCREEN_SPACE_AA_DISABLED = 0

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

ScreenSpaceAA SCREEN_SPACE_AA_FXAA = 1

使用快速近似抗锯齿。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

对象显示为线框图模型。

注意：RenderingServer.set_debug_generate_wireframes()必须在加载任何网格之前调用，以便在使用兼容性渲染器时线框可见。

DebugDraw DEBUG_DRAW_NORMAL_BUFFER = 5

对象在没有照明信息的情况下显示，它们的纹理被正常映射替换。

DebugDraw DEBUG_DRAW_VOXEL_GI_ALBEDO = 6

仅使用VoxelGIs中的反照率值显示对象。

DebugDraw DEBUG_DRAW_VOXEL_GI_LIGHTING = 7

仅使用VoxelGIs中的照明值显示对象。

DebugDraw DEBUG_DRAW_VOXEL_GI_EMISSION = 8

对象仅显示VoxelGIs的发射颜色。

DebugDraw DEBUG_DRAW_SHADOW_ATLAS = 9

绘制阴影图集，该图集将PointLight和SpotLight的阴影存储在Viewport的左上象限中。

DebugDraw DEBUG_DRAW_DIRECTIONAL_SHADOW_ATLAS = 10

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

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

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

DebugDraw DEBUG_DRAW_DECAL_ATLAS = 15

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

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

绘制PointLight节点用于优化光源渲染的集群。

DebugDraw DEBUG_DRAW_CLUSTER_SPOT_LIGHTS = 21

绘制SpotLight节点用于优化光源渲染的集群。

DebugDraw DEBUG_DRAW_CLUSTER_DECALS = 22

绘制DecalActor节点用于优化贴花渲染的集群。

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

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

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR = 1

纹理过滤器在最近的4个像素之间混合。这使得纹理从近距离看很光滑，从远处看很颗粒状（由于mipmap没有被采样）。

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 2

纹理过滤器在最近的4个像素和最近的2个mipmap之间混合（或者使用最近的mipmap，如果ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter是真）。这使得纹理近距离看起来很光滑，远距离看起来很光滑。

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

DefaultCanvasItemTextureFilter DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤器从最近的像素读取并在最近的2个mipmap之间混合（或者使用最近的mipmap，如果ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter是真）。这使得纹理从近距离看是像素化的，从远处看是平滑的。

将其用于可以以低比例查看的非像素艺术纹理，因为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

符号距离字段扩展为覆盖边框周围视口大小的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()

设置对纹理使用各向异性过滤时的最大样本数（2的幂）。更高的样本数将导致倾斜角度的纹理更清晰，但计算成本更高。0的值会强制禁用各向异性过滤，即使在启用它的材质上也是如此。

如果贴花和投影仪配置为使用各向异性过滤，各向异性过滤级别也会影响它们。请参阅ProjectSettings.rendering/textures/decals/filter和ProjectSettings.rendering/textures/light_projectors/filter。

注意：在3D中，为了使此设置具有效果，请将材质上的BaseMaterial3D.texture_filter设置为BaseMaterial3D.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC或BaseMaterial3D.TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC。

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()

设置此视口中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()

设置此视口中CanvasItem使用的默认重复模式。有关选项，请参阅DefaultCanvasItemTextureRepeat。

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项目设置。

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将自动将此属性设置为false，用于其中包含的Viewport。

另见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不影响GeometryRender可见性范围（也称为“手动”LOD或分层LOD）。

MSAA msaa_2d = 0 🔗

void set_msaa_2d(value: MSAA)
MSAA get_msaa_2d()

2D/Canvas渲染的多采样抗锯齿模式。更高的数字会导致更平滑的边缘，但代价是性能明显更差。除非针对非常高端的系统，否则最好使用MSAA_2X或MSAA_4X的值。这对着色器引起的混淆现象或纹理混淆现象没有影响。

另见ProjectSettings.rendering/anti_aliasing/quality/msaa_2d和RenderingServer.viewport_set_msaa_2d()。

MSAA msaa_3d = 0 🔗

void set_msaa_3d(value: MSAA)
MSAA get_msaa_3d()

3D渲染的多采样抗锯齿模式。更高的数字会导致更平滑的边缘，但代价是性能明显更差。MSAA_2X或MSAA_4X的值最好，除非针对非常高端的系统。另请参阅双线性缩放3Dscaling_3d_mode以获得超采样，这提供了更高的质量，但成本要高得多。这对着色器引起的混淆现象或纹理混淆现象没有影响。

另见ProjectSettings.rendering/anti_aliasing/quality/msaa_3d和RenderingServer.viewport_set_msaa_3d()。

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，则对象接收鼠标拾取事件，按其在场景树中的位置排序。如果false，则顺序未确定。

注意：此设置默认禁用，因为其潜在的昂贵计算成本。

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超级分辨率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，后者在渲染对象时获取多个覆盖样本。屏幕空间AA方法通常比MSAA更快，并且会消除镜面混淆现象，但往往会使场景看起来模糊。

另见ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa和RenderingServer.viewport_set_screen_space_aa()。

SDFOversize sdf_oversize = 1 🔗

void set_sdf_oversize(value: SDFOversize)
SDFOversize get_sdf_oversize()

控制2D有符号距离字段应覆盖原始视口大小的多少。较高的值允许位于视口之外的部分遮挡物仍被考虑到生成的有符号距离字段中，但以性能为代价。

在每个轴和两侧添加百分比。例如，使用默认的SDF_OVERSIZE_120_PERCENT，带符号的距离字段将覆盖每一侧（上、右、下、左）视口外的视口大小的20%。

SDFScale sdf_scale = 1 🔗

void set_sdf_scale(value: SDFScale)
SDFScale get_sdf_scale()

用于2D符号距离字段的分辨率标度。随着摄像机的移动，更高的值会导致更精确和更稳定的符号距离字段，但会以性能为代价。

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中显着不那么明显。2D渲染不受去条带影响，除非Environment.background_mode是Environment.BG_CANVAS。

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

另见ProjectSettings.rendering/anti_aliasing/quality/use_debanding和RenderingServer.viewport_set_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空间（如果Viewport连接到屏幕）。实际上，这意味着Viewport的最终结果不会被钳制在0-1范围内，并且可以在无需色彩空间调整的情况下用于3D渲染。这允许2D渲染利用需要高动态范围的效果（例如2D发光），以及大幅改善需要高度详细渐变的效果的外观。

注意：此设置在使用兼容性渲染器时无效，出于性能原因，它总是在低动态范围内渲染。

bool use_occlusion_culling = false 🔗

void set_use_occlusion_culling(value: bool)
bool is_using_occlusion_culling()

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

注意：启用遮挡剔除在CPU上有成本。只有在您实际计划使用它时才启用遮挡剔除，并考虑您的场景是否真的可以从遮挡剔除中受益。具有很少或没有物体阻挡视图的大型开放场景通常不会从遮挡剔除中受益太多。与遮挡剔除相比，大型开放场景通常从网格LOD和可见性范围（GeometryRender.visibility_range_begin和GeometryRender.visibility_range_end）中受益更多。

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

bool use_taa = false 🔗

void set_use_taa(value: bool)
bool is_using_taa()

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

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

另见ProjectSettings.rendering/anti_aliasing/quality/use_taa和RenderingServer.viewport_set_use_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()

用于此视口的可变速率着色（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 - Not supported on most hardware
- 8×4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware
- 8×8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware

VRSUpdateMode vrs_update_mode = 1 🔗

void set_vrs_update_mode(value: VRSUpdateMode)
VRSUpdateMode get_vrs_update_mode()

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

World3D world_3d 🔗

void set_world_3d(value: World3D)
World3D get_world_3d()

自定义World3D可用作3D环境源。

方法说明¶

World3D find_world_3d() const 🔗

返回此视口的第一个有效World3D，搜索自身和任何视口祖先的world_3d属性。

AudioListener get_audio_listener_3d() const 🔗

返回当前活动的3D音频侦听器。如果没有活动的3D音频侦听器，则返回null，在这种情况下，活动的3D摄像机将被视为侦听器。

Camera get_camera_3d() const 🔗

返回当前活动的3D摄像机。

bool get_canvas_cull_mask_bit(layer: int) const 🔗

返回渲染层蒙版上的单个位。

Array[Window] get_embedded_subwindows() const 🔗

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

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

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。

ViewportTexture get_texture() const 🔗

返回视口的纹理。

** 注意：** 当尝试存储当前纹理（例如保存到文件中）时，如果使用时机过早，纹理可能会完全变黑或过时，特别是在例如 Item.iStart() 中使用时。为确保获取的纹理正确，可以等待 RenderingServer.frame_post_draw 信号。

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

注意：当 use_hdr_2d 为 true 时，返回的纹理将是一个在线性空间中编码的 HDR 图像

RID get_viewport_rid() const 🔗

从RenderingServer返回视口的RID。

Rect2 get_visible_rect() const 🔗

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

void gui_cancel_drag() 🔗

取消以前通过Control._get_drag_data()启动或使用Control.force_drag()强制执行的拖动操作。

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节点或子树的最深层，它声称悬停。当与Item.is_ancestor_of()一起使用以查找鼠标是否在控制树中时，这非常有用。

bool gui_is_drag_successful() const 🔗

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

bool gui_is_dragging() const 🔗

如果拖动操作当前正在进行并且拖放操作可能在此视口中发生，则返回true。

替代Item.NOTIFICATION_DRAG_BEGIN和Item.NOTIFICATION_DRAG_END当您喜欢轮询值时。

void gui_release_focus() 🔗

从此视口中当前聚焦的Control中删除焦点。如果没有Control有焦点，则什么也不做。

bool is_input_handled() const 🔗

返回当前的InputEvent是否已被处理。在InputEvent的生命周期内调用set_input_as_handled()之前，不会处理输入事件。

这通常作为输入处理方法的一部分完成，如Item.OnInput()、Control._gui_input()或其他方法，以及相应的信号处理程序。

如果handle_input_locally设置为false，则此方法将尝试查找设置为在本地处理输入的第一个父视口，并返回is_input_handled()的值。

void notify_mouse_entered() 🔗

通知视口鼠标已进入其区域。在使用push_input()向Viewport发送InputEventMouseButton或InputEventMouseMotion之前使用此功能。另见notify_mouse_exited()。

注意：在大多数情况下，没有必要调用此函数，因为SubViewportContainer的子节点SubViewport会自动通知。这仅在以非默认方式与视口交互时才是必要的，例如作为TextureRect中的纹理或与转发输入事件的AreaTrigger交互。

void notify_mouse_exited() 🔗

通知视口鼠标已离开其区域。当显示视口的节点注意到鼠标已离开显示视口的区域时使用此功能。另请参见notify_mouse_entered()。

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。

调用此方法将按照给定顺序将以下方法的调用传播到子节点：

-Item.OnIinput()

-Control._gui_input()用于Control节点

-Item.shortcut_input()

-Item.unhandled_key_input()

-Item.unhandled_input()

如果前面的方法将输入标记为通过set_input_as_handled()处理，则不会调用此列表中的任何后面的方法。

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

void push_text_input(text: String) 🔗

Helper方法，它在当前聚焦的Control上调用set_text（）方法，前提是它已定义（例如，如果聚焦的Control是Button或LineEdit）。

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

已弃用： 请改用 push_input()。

触发此Viewport中给定的event。这可用于在视口之间传递InputEvent，或在本地应用通过网络发送或保存到文件中的输入。

如果in_local_coords为false，则事件的位置在嵌入器的坐标中，并将转换为视口坐标。如果in_local_coords为true，则事件的位置在视口坐标中。

调用此方法将按照给定顺序将以下方法的调用传播到子节点：

-Item.shortcut_input()

-Item.unhandled_key_input()

-Item.unhandled_input()

如果前面的方法将输入标记为通过set_input_as_handled()处理，则不会调用此列表中的任何后面的方法。

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

注意：此方法不会将输入事件传播到嵌入的Windows或SubViewports。

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、ColliderObjectBase.mouse_entered和Window.mouse_entered信号及其各自的mouse_exited对应物。

void warp_mouse(position: Vector2) 🔗

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

注意：warp_mouse()仅在Windows、macOS和Linux上受支持，对Android、iOS和Web没有影响。