Viewport

Inherits: Node < Object

在屏幕中创建一个子视图。

描述

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

另外，视窗可以有自己的 2D 或 3D 世界，所以它们不会与其他视窗共享其所绘制的内容。

如果视窗是 ViewportContainer 的子节点，它将自动占用其大小，否则必须手动设置。

视窗也可以选择成为音频监听者，会根据它的 2D 或 3D 摄像机的子节点来产生位置音频。

另外，如果设备有多个屏幕，视窗可以被分配到不同的屏幕。

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

注意：默认情况下，Godot 3.x 新创建的 Viewport 是上下颠倒的。启用 render_target_v_flip 可以使该 Viewport 使用正确的朝向显示。

教程

属性

bool

arvr

false

bool

audio_listener_enable_2d

false

bool

audio_listener_enable_3d

false

Transform2D

canvas_transform

bool

debanding

false

DebugDraw

debug_draw

0

bool

disable_3d

false

bool

fxaa

false

Transform2D

global_canvas_transform

bool

gui_disable_input

false

bool

gui_snap_controls_to_pixels

true

bool

handle_input_locally

true

bool

hdr

true

bool

keep_3d_linear

false

MSAA

msaa

0

bool

own_world

false

bool

physics_object_picking

false

bool

render_direct_to_screen

false

ClearMode

render_target_clear_mode

0

UpdateMode

render_target_update_mode

2

bool

render_target_v_flip

false

ShadowAtlasQuadrantSubdiv

shadow_atlas_quad_0

2

ShadowAtlasQuadrantSubdiv

shadow_atlas_quad_1

2

ShadowAtlasQuadrantSubdiv

shadow_atlas_quad_2

3

ShadowAtlasQuadrantSubdiv

shadow_atlas_quad_3

4

int

shadow_atlas_size

0

float

sharpen_intensity

0.0

Vector2

size

Vector2( 0, 0 )

bool

size_override_stretch

false

bool

transparent_bg

false

Usage

usage

2

World

world

World2D

world_2d

方法

World

find_world ( ) const

World2D

find_world_2d ( ) const

Camera

get_camera ( ) const

Transform2D

get_final_transform ( ) const

Control

get_modal_stack_top ( ) const

Vector2

get_mouse_position ( ) const

int

get_render_info ( RenderInfo info )

ShadowAtlasQuadrantSubdiv

get_shadow_atlas_quadrant_subdiv ( int quadrant ) const

Vector2

get_size_override ( ) const

ViewportTexture

get_texture ( ) const

RID

get_viewport_rid ( ) const

Rect2

get_visible_rect ( ) const

Variant

gui_get_drag_data ( ) const

bool

gui_has_modal_stack ( ) const

bool

gui_is_dragging ( ) const

void

input ( InputEvent local_event )

bool

is_input_handled ( ) const

bool

is_size_override_enabled ( ) const

void

set_attach_to_screen_rect ( Rect2 rect )

void

set_input_as_handled ( )

void

set_shadow_atlas_quadrant_subdiv ( int quadrant, ShadowAtlasQuadrantSubdiv subdiv )

void

set_size_override ( bool enable, Vector2 size=Vector2( -1, -1 ), Vector2 margin=Vector2( 0, 0 ) )

void

unhandled_input ( InputEvent local_event )

void

update_worlds ( )

void

warp_mouse ( Vector2 to_position )

信号

  • gui_focus_changed ( Control node )

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

  • size_changed ( )

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

枚举

enum UpdateMode:

  • UPDATE_DISABLED = 0 —- 不要更新渲染目标。

  • UPDATE_ONCE = 1 —- 更新渲染目标一次，然后切换到 UPDATE_DISABLED。

  • UPDATE_WHEN_VISIBLE = 2 —- 仅在渲染目标可见时更新渲染目标。这是默认值。

  • UPDATE_ALWAYS = 3 —- 始终更新渲染目标。

enum ShadowAtlasQuadrantSubdiv:

  • SHADOW_ATLAS_QUADRANT_SUBDIV_DISABLED = 0 —- 此象限将不使用。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_1 = 1 —- 此象限仅由一张阴影贴图使用。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_4 = 2 —- 此象限将分为 4 个，最多使用 4 个阴影贴图。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_16 = 3 —- 此象限将被分成16个方向，并被最多16张阴影贴图使用。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_64 = 4 —- 这个象限将被分成64个方向，并被最多64张阴影贴图使用。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_256 = 5 —- 这个象限将被分成256个方向，并被最多256个阴影贴图使用。除非 shadow_atlas_size 非常高，否则这个象限内的阴影分辨率会非常低。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_1024 = 6 —- 这个象限将被分成1024个方向，并被最多1024个阴影贴图使用。除非 shadow_atlas_size 非常高，否则这个象限内的阴影分辨率会非常低。

  • SHADOW_ATLAS_QUADRANT_SUBDIV_MAX = 7 —- 代表ShadowAtlasQuadrantSubdiv枚举的大小。

enum RenderInfo:

  • RENDER_INFO_OBJECTS_IN_FRAME = 0 —- 帧中对象的数量。

  • RENDER_INFO_VERTICES_IN_FRAME = 1 —- 帧中的顶点数量。

  • RENDER_INFO_MATERIAL_CHANGES_IN_FRAME = 2 —- 帧中的材质更改量。

  • RENDER_INFO_SHADER_CHANGES_IN_FRAME = 3 —- 帧中着色器的更改量。

  • RENDER_INFO_SURFACE_CHANGES_IN_FRAME = 4 —- 帧中的表面更改量。

  • RENDER_INFO_DRAW_CALLS_IN_FRAME = 5 —- 帧中的绘制调用量。

  • RENDER_INFO_2D_ITEMS_IN_FRAME = 6 —- 帧中的项或联合项的数量。

  • RENDER_INFO_2D_DRAW_CALLS_IN_FRAME = 7 —- 帧中的绘制调用量。

  • RENDER_INFO_MAX = 8 —- 表示 RenderInfo 枚举的大小。

enum DebugDraw:

  • DEBUG_DRAW_DISABLED = 0 —- 对象显示正常。

  • DEBUG_DRAW_UNSHADED = 1 —- 显示的对象没有光照信息。

  • DEBUG_DRAW_OVERDRAW = 2 —- 对象以半透明的方式显示，并进行加法混合，因此你可以看到它们的相交处。

  • DEBUG_DRAW_WIREFRAME = 3 —- 对象以线框风格显示。

enum MSAA:

  • MSAA_DISABLED = 0 —- 禁用多重采样抗锯齿模式。这是默认值。

  • MSAA_2X = 1 —- 使用 2x 多重采样抗锯齿。

  • MSAA_4X = 2 —- 使用 4x 多重采样抗锯齿。

  • MSAA_8X = 3 —- 使用 8x 多重采样抗锯齿。在低端和旧硬件上可能不受支持。

  • MSAA_16X = 4 —- 使用 16x 多重采样抗锯齿。在中低端硬件上可能不受支持。

enum Usage:

  • USAGE_2D = 0 —- 分配绘制2D场景所需的所有缓冲区。这比3D使用模式占用更少的VRAM。请注意，使用这种模式时，诸如辉光和HDR等3D渲染效果是不可用的。

  • USAGE_2D_NO_SAMPLING = 1 —- 分配2D场景所需的缓冲区，而不分配屏幕拷贝的缓冲区。相应地，你不能从屏幕上读取。在Usage类型中，这需要最少的VRAM。注意，使用这种模式时，诸如辉光和HDR等3D渲染效果是不可用的。

  • USAGE_3D = 2 —- 为绘制3D场景和所有3D效果分配完整的缓冲区，包括2D场景和效果所需的缓冲区。

  • USAGE_3D_NO_EFFECTS = 3 —- 分配绘制3D场景所需的缓冲区。但不分配从屏幕上读取和后期处理效果所需的缓冲区。节省了一些VRAM。

enum ClearMode:

  • CLEAR_MODE_ALWAYS = 0 —- 绘制前始终清除渲染目标。

  • CLEAR_MODE_NEVER = 1 —- 永不清除渲染目标。

  • CLEAR_MODE_ONLY_NEXT_FRAME = 2 —- 在下一帧清除渲染目标，然后切换到 CLEAR_MODE_NEVER。

属性说明

Default

false

Setter

set_use_arvr(value)

Getter

use_arvr()

如果true，视窗将用于AR/VR进程。

  • bool audio_listener_enable_2d

Default

false

Setter

set_as_audio_listener_2d(value)

Getter

is_audio_listener_2d()

如果true，视窗将处理2D音频流。

  • bool audio_listener_enable_3d

Default

false

Setter

set_as_audio_listener(value)

Getter

is_audio_listener()

如果true，视窗将处理3D音频流。

Setter

set_canvas_transform(value)

Getter

get_canvas_transform()

视窗的画布变换，对改变所有子CanvasItem的屏幕位置很有用。这与视窗的全局画布变换有关。

Default

false

Setter

set_use_debanding(value)

Getter

get_use_debanding()

如果true，则使用一个快速的后期处理滤波器，使带状现象明显减少。在某些情况下，去带可能会引入稍微明显的抖动模式。建议只有在实际需要时才启用去带，因为抖动模式会使无损压缩的屏幕截图变大。

注意： 仅在GLES3后端可用。hdr也必须是true才能使debanding去带生效。

Default

0

Setter

set_debug_draw(value)

Getter

get_debug_draw()

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

Default

false

Setter

set_disable_3d(value)

Getter

is_3d_disabled()

如果true，视窗将禁用3D渲染。对于实际禁用，使用usage。

Default

false

Setter

set_use_fxaa(value)

Getter

get_use_fxaa()

启用快速近似抗锯齿。FXAA是一种流行的屏幕空间抗锯齿方法，它的速度很快，但会使图像看起来很模糊，特别是在较低的分辨率。在1440p和4K这样的大分辨率下，它仍然可以较好工作。一些损失的锐度可以通过启用对比度适应性锐化来恢复，参阅sharpen_intensity。

Setter

set_global_canvas_transform(value)

Getter

get_global_canvas_transform()

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

  • bool gui_disable_input

Default

false

Setter

set_disable_input(value)

Getter

is_input_disabled()

如果true，视窗将不接收输入事件。

  • bool gui_snap_controls_to_pixels

Default

true

Setter

set_snap_controls_to_pixels(value)

Getter

is_snap_controls_to_pixels_enabled()

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

  • bool handle_input_locally

Default

true

Setter

set_handle_input_locally(value)

Getter

is_handling_input_locally()

Default

true

Setter

set_hdr(value)

Getter

get_hdr()

如果true，视窗的渲染将获得高动态范围算法的收益。高动态范围允许视窗接收0-1范围以外的数值。在Godot中HDR使用16比特，这意味着它不能存储浮点数的全部范围。

注意： 需要将 usage设置为USAGE_3D或USAGE_3D_NO_EFFECTS，2D不支持HDR。

  • bool keep_3d_linear

Default

false

Setter

set_keep_3d_linear(value)

Getter

get_keep_3d_linear()

如果true，3D渲染后的结果将不会应用线性到sRGB的颜色转换。当视窗被用作渲染目标时，这点很重要，因为渲染结果会被用作另一个视窗中渲染的三维物体的纹理。如果视窗被用来创建不基于颜色的数据，噪声、高度图、采图等，这也很重要。当视窗被用作2D对象的纹理时，或者视窗是你的最终输出时，请不要启用这个功能。对于GLES2驱动来说，这将把sRGB输出转换为线性输出，这应该只用于需要线性色彩空间输入的VR插件!

Default

0

Setter

set_msaa(value)

Getter

get_msaa()

多重采样抗锯齿模式。一个较高的数字会使边缘更平滑，但代价是性能明显下降。除非是针对非常高端的系统，否则数值为4是最好的。

Default

false

Setter

set_use_own_world(value)

Getter

is_using_own_world()

如果true，视窗将使用world属性中定义的World。

  • bool physics_object_picking

Default

false

Setter

set_physics_object_picking(value)

Getter

get_physics_object_picking()

如果true，则视窗渲染的对象将成为鼠标拾取过程的对象。

  • bool render_direct_to_screen

Default

false

Setter

set_use_render_direct_to_screen(value)

Getter

is_using_render_direct_to_screen()

如果true，直接将视窗渲染到屏幕上，而不是渲染到根视窗上。只在GLES2中可用。这是一个低级别的优化，在大多数情况下不应该使用。如果使用，从视窗或从SCREEN_TEXTURE读取将变得不可用。更多信息参阅VisualServer.viewport_set_render_direct_to_screen。

Default

0

Setter

set_clear_mode(value)

Getter

get_clear_mode()

视窗用作渲染目标时的清除模式。

注意： 此属性适用于 2D 使用。

Default

2

Setter

set_update_mode(value)

Getter

get_update_mode()

视窗用作渲染目标时的更新模式。

  • bool render_target_v_flip

Default

false

Setter

set_vflip(value)

Getter

get_vflip()

为 true 时，渲染结果会被垂直翻转。因为 Godot 3.x 中 Viewport 渲染的内容是上下颠倒的，所以推荐在大多数情况下将其设置为 true。

Default

2

Setter

set_shadow_atlas_quadrant_subdiv(value)

Getter

get_shadow_atlas_quadrant_subdiv()

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

Default

2

Setter

set_shadow_atlas_quadrant_subdiv(value)

Getter

get_shadow_atlas_quadrant_subdiv()

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

Default

3

Setter

set_shadow_atlas_quadrant_subdiv(value)

Getter

get_shadow_atlas_quadrant_subdiv()

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

Default

4

Setter

set_shadow_atlas_quadrant_subdiv(value)

Getter

get_shadow_atlas_quadrant_subdiv()

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

  • int shadow_atlas_size

Default

0

Setter

set_shadow_atlas_size(value)

Getter

get_shadow_atlas_size()

阴影图集的分辨率，注，用于泛光灯和聚光灯。该值将四舍五入到最接近的 2 的幂。

注意：如果设置为0，阴影将不可见。由于用户创建的视窗默认值为 0，因此必须手动将此值设置为大于 0。

Default

0.0

Setter

set_sharpen_intensity(value)

Getter

get_sharpen_intensity()

如果设置为大于0.0的值，对比度适应性锐化将被应用到3D视窗中。这具有较低的性能成本，可以用来恢复使用FXAA所损失的一些锐度。一般来说，0.5左右的数值可以得到最好的效果。参阅fxaa。

Default

Vector2( 0, 0 )

Setter

set_size(value)

Getter

get_size()

视窗的宽度和高度。必须在两个维度上设置为大于或等于2像素的值。否则，将不会显示任何东西。

  • bool size_override_stretch

Default

false

Setter

set_size_override_stretch(value)

Getter

is_size_override_stretch_enabled()

如果true，尺寸重写也会影响拉伸。

  • bool transparent_bg

Default

false

Setter

set_transparent_background(value)

Getter

has_transparent_background()

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

Default

2

Setter

set_usage(value)

Getter

get_usage()

视窗的渲染模式。

Setter

set_world(value)

Getter

get_world()

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

Setter

set_world_2d(value)

Getter

get_world_2d()

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

方法说明

  • World find_world ( ) const

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

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

返回激活的3D相机。

返回视窗的总的变换。

  • Control get_modal_stack_top ( ) const

返回堆栈中最顶层的模型。

  • Vector2 get_mouse_position ( ) const

返回相对于视窗的鼠标位置。

返回渲染管道中关于视窗的信息。

返回指定象限的ShadowAtlasQuadrantSubdiv。

  • Vector2 get_size_override ( ) const

返回用set_size_override设置的尺寸重写。

返回视窗的纹理。

注意： 由于OpenGL的工作方式，产生的ViewportTexture是垂直翻转的。你可以在Texture.get_data的结果上使用Image.flip_y来将其翻转回去，例如。

  1. var img = get_viewport().get_texture().get_data()
  2. img.flip_y()
  • RID get_viewport_rid ( ) const

从VisualServer返回视窗的RID。

  • Rect2 get_visible_rect ( ) const

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

  • Variant gui_get_drag_data ( ) const

返回GUI中的拖动数据，该数据之前由 Control.get_drag_data 返回。

  • bool gui_has_modal_stack ( ) const

如果屏幕上有可见的模型，返回true。

  • bool gui_is_dragging ( ) const

如果当前视窗正在执行拖动操作，则返回true。

  • bool is_input_handled ( ) const
  • bool is_size_override_enabled ( ) const

如果启用了尺寸重写，返回true。参阅set_size_override。

  • void set_attach_to_screen_rect ( Rect2 rect )

用指定的矩形将这个Viewport附加到根Viewport视窗上。这就绕过了另一个节点来显示这个Viewport的需要，但让你负责手动更新这个Viewport的坐标。

  • void set_input_as_handled ( )

阻止输入继续向下传播SceneTree。

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

  • void set_size_override ( bool enable, Vector2 size=Vector2( -1, -1 ), Vector2 margin=Vector2( 0, 0 ) )

设置视窗的尺寸重写。如果enable参数是true，就会使用重写，否则就使用默认尺寸。如果尺寸参数是(-1, -1)，它将不会更新尺寸。

  • void update_worlds ( )

强制更新 2D 和 3D 世界。

  • void warp_mouse ( Vector2 to_position )

将鼠标偏移到相对于视窗的位置。