Viewport

Inherits: Node < Object

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

描述

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

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

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

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

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

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

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

信号

  • 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_3DUSAGE_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。


  • float sharpen_intensity

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来将其翻转回去,例如。

var img = get_viewport().get_texture().get_data()
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 )

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