视口系统

相关源文件

• doc/classes/Control.xml
• doc/classes/Node.xml
• doc/classes/SceneTree.xml
• doc/classes/Theme.xml
• doc/classes/Viewport.xml
• doc/classes/Window.xml
• scene/gui/control.cpp
• scene/gui/control.h
• scene/main/node.cpp
• scene/main/node.h
• scene/main/scene_tree.cpp
• scene/main/scene_tree.h
• scene/main/viewport.cpp
• scene/main/viewport.h
• scene/main/window.cpp
• scene/main/window.h
• scene/resources/theme.cpp
• scene/resources/theme.h

Godot 中的视口系统是创建游戏世界视图的核心组件。它封装了游戏内容的绘制和交互。视口是渲染 2D 和 3D 内容、处理输入事件以及组织游戏视觉层级的基础。

有关场景整体组织的更多信息，请参阅 节点和场景系统。有关渲染管线的详细信息，请参阅 渲染系统。

概述

Godot 中的视口提供了一个渲染视觉内容的表面。每个视口都有自己的坐标系，并且可以显示 2D 和 3D 内容。视口可以嵌套在一起，作为纹理显示，或用于创建各种视觉效果。

视口系统的主要功能包括：

• 渲染 2D 和 3D 内容
• 输入事件处理和传播
• 创建多个摄像机视图
• 渲染到纹理，用于传送门、小地图和安全摄像头等效果
• 分屏功能
• 在 3D 环境中嵌入 UI
• 多窗口管理

来源： scene/main/viewport.h94-748 doc/classes/Viewport.xml1-20

架构

视口系统围绕着几个协同工作的核心类构建，以提供渲染和输入功能。

视口类层级

关键组件

1. 视口类：封装游戏世界视图的基类。
2. 视口纹理：允许将视口内容用作纹理。
3. 窗口：扩展了视口，增加了窗口管理功能。
4. 场景树：管理节点层级并处理主游戏循环。

来源： scene/main/viewport.h94-172 scene/main/window.h43-54

视口层级

视口在场景树中形成一个层级。根视口（附加到主窗口）构成了该层级的基础。

视口关系

• 父子关系：当一个视口是另一个视口的子项时，它会继承其父项的属性和坐标。
• 世界共享：子视口可以与其父项共享相同的 2D/3D 世界，或者拥有自己的世界。
• 输入传播：输入事件从根视口向下流向子视口。

来源： scene/main/viewport.cpp242-265 scene/main/viewport.cpp534-552

渲染能力

渲染流程

视口处理各种渲染配置

功能	描述	相关属性
透明度	背景透明	transparent_bg
MSAA	多重采样抗锯齿	msaa_2d, msaa_3d
屏幕空间抗锯齿	额外的抗锯齿	screen_space_aa
扩展	3D内容缩放	scaling_3d_mode, scaling_3d_scale
HDR	高动态范围	use_hdr_2d
调试可视化	视觉调试	debug_draw
阴影	阴影渲染	positional_shadow_atlas_size

来源： scene/main/viewport.cpp1080-1164 scene/main/viewport.h98-226

视口纹理

ViewportTexture 类允许将视口内容用作纹理

ViewportTexture 引用一个特定的视口，并将其渲染输出作为纹理提供。这可以用于：

• 将场景渲染到纹理，用于材质
• 创建传送门、镜子或安全摄像头显示
• 画中画效果
• 小地图或其他 UI 元素

来源： scene/main/viewport.cpp66-240 scene/main/viewport.h54-92

输入处理

视口处理输入事件并将其传播到场景树。主要功能包括：

1. 输入事件传播：事件从根视口流向子视口。
2. 物理对象拾取：通过射线投射检测鼠标光标下的对象。
3. GUI 输入处理：处理 UI 元素交互。

输入的流程是：

来源： scene/main/viewport.cpp710-1007 doc/classes/Viewport.xml83-173

视口变换

视口管理多个坐标系和变换

变换	目的
canvas_transform	应用于 2D 内容的变换
global_canvas_transform	附加的画布变换（例如，用于摄像机抖动）
stretch_transform	在 size_2d_override 使用时应用
final_transform	从视口到屏幕坐标的变换

坐标转换包括：

• 局部视口坐标
• 全局屏幕坐标
• 画布（2D 世界）坐标

来源： scene/main/viewport.cpp1080-1158 scene/main/viewport.h253-264

子窗口管理

视口可以嵌入窗口，而窗口被实现为一种特殊的视口。

子窗口管理的关键方面

• 可以使用 gui_embed_subwindows 属性在视口内嵌入窗口。
• 窗口之间的焦点管理
• 拖放操作
• 窗口的 Z 顺序
• 输入事件重定向

来源： scene/main/viewport.cpp291-505 scene/main/window.cpp284-340

视口 GUI 系统

视口管理 GUI 元素，包括：

• 控件的输入焦点跟踪
• 鼠标悬停状态
• 工具提示
• 拖放操作
• 模态窗口

来源： scene/main/viewport.h369-398 scene/gui/control.h64-97

与其他系统集成

视口系统集成了引擎中的多个其他核心系统

系统	集成
节点系统	视口是场景树的节点
渲染系统	视口创建和管理渲染表面
输入系统	视口处理和分发输入事件
物理系统	视口支持物理对象拾取
音频系统	视口可以拥有音频监听器
窗口系统	视口可以与窗口关联

来源： scene/main/viewport.cpp534-635 scene/main/scene_tree.cpp572-654

常见用例

1. 主游戏视图：显示主游戏内容的根视口。
2. 分屏多人游戏：多个视口显示不同视角。
3. 小地图：显示游戏世界概览的小视口。
4. 画中画：将一个视口嵌入另一个视口中。
5. 渲染到纹理：将视口的输出用作材质的纹理。
6. UI 叠加 3D：将 UI 元素嵌入 3D 内容之上。
7. 传送门效果：使用视口创建传送门或镜子。

来源： doc/classes/Viewport.xml3-22

性能考量

视口可能很耗费资源，因为它们涉及渲染可能不可见的内容。请考虑：

• 使用 visible 属性禁用未使用的视口。
• 为不太重要的视口调整渲染质量设置。
• 使用适当的视口大小，以避免不必要的渲染。
• 使用 update_mode 属性来控制视口的更新时机。

来源： scene/main/viewport.h102-225