GFViewportUtility¶

路径：addons/gf/standard/utilities/display/gf_viewport_utility.gd
模块：Standard
继承：GFUtility
API：public
类别：运行时服务 (runtime_service)
首次版本：3.17.0

通用 SubViewport 布局管理工具。用于本地多人、调试监视器、小地图或多视角预览等场景。它只管理 Viewport 容器、相机挂载和后处理材质，不接管玩家、场景切换或输入规则。

成员概览¶

类型	名称	签名
信号	`split_screen_configured`	`signal split_screen_configured(viewports: Array)`
信号	`split_screen_cleared`	`signal split_screen_cleared`
属性	`viewport_resolution_scale`	`var viewport_resolution_scale: float = 1.0:`
属性	`default_disable_3d`	`var default_disable_3d: bool = false`
属性	`default_transparent_bg`	`var default_transparent_bg: bool = false`
方法	`setup_split_screen`	`func setup_split_screen(root: Control, viewport_count: int, options: Dictionary = {}) -> Array[SubViewport]:`
方法	`clear_split_screen`	`func clear_split_screen(free_cameras: bool = false) -> void:`
方法	`get_viewport_count`	`func get_viewport_count() -> int:`
方法	`get_viewports`	`func get_viewports() -> Array[SubViewport]:`
方法	`get_viewport`	`func get_viewport(index: int) -> SubViewport:`
方法	`get_container`	`func get_container(index: int) -> SubViewportContainer:`
方法	`set_viewport_camera`	`func set_viewport_camera(index: int, camera: Node) -> bool:`
方法	`set_postprocess_material`	`func set_postprocess_material(index: int, material: Material) -> bool:`
方法	`screen_to_world_ray_3d`	`func screen_to_world_ray_3d( camera: Camera3D, screen_position: Vector2, length: float = 1000.0 ) -> Dictionary:`
方法	`raycast_from_screen_3d`	`func raycast_from_screen_3d( camera: Camera3D, screen_position: Vector2, collision_mask: int = 0xffffffff, length: float = 1000.0, exclude: Array[RID] = [] ) -> Dictionary:`
方法	`world_to_screen_3d`	`func world_to_screen_3d(camera: Camera3D, world_position: Vector3) -> Vector2:`
方法	`world_to_screen_3d_report`	`func world_to_screen_3d_report(camera: Camera3D, world_position: Vector3) -> Dictionary:`
方法	`world_to_screen_2d`	`func world_to_screen_2d(canvas_item: CanvasItem, world_position: Vector2) -> Vector2:`
方法	`screen_to_world_2d`	`func screen_to_world_2d(canvas_item: CanvasItem, screen_position: Vector2) -> Vector2:`
方法	`calculate_control_window_rect`	`func calculate_control_window_rect( control_rect: Rect2, viewport_size: Vector2, window_size: Vector2i, options: Dictionary = {} ) -> Dictionary:`
方法	`get_control_window_rect`	`func get_control_window_rect(control: Control, viewport: Viewport = null) -> Dictionary:`
方法	`calculate_safe_area_margins`	`func calculate_safe_area_margins( safe_area: Rect2i, window_size: Vector2i, viewport_size: Vector2, extra_margins: Dictionary = {} ) -> Dictionary:`
方法	`get_display_safe_area_margins`	`func get_display_safe_area_margins(viewport: Viewport = null, extra_margins: Dictionary = {}) -> Dictionary:`
方法	`apply_safe_area_margins`	`func apply_safe_area_margins(container: MarginContainer, margins: Dictionary) -> bool:`
方法	`apply_display_safe_area_margins`	`func apply_display_safe_area_margins( container: MarginContainer, viewport: Viewport = null, extra_margins: Dictionary = {} ) -> Dictionary:`
方法	`get_debug_snapshot`	`func get_debug_snapshot() -> Dictionary:`
方法	`tick`	`func tick(_delta: float) -> void:`

信号¶

`split_screen_configured`¶

API：public

signal split_screen_configured(viewports: Array)

分屏布局创建完成后发出。

参数：

名称	说明
`viewports`	当前 SubViewport 列表副本。

结构：

viewports: Array，由分屏布局创建的 SubViewport 实例。

`split_screen_cleared`¶

API：public

signal split_screen_cleared

分屏布局被清理后发出。

属性¶

`viewport_resolution_scale`¶

API：public

var viewport_resolution_scale: float = 1.0:

子 viewport 渲染尺寸缩放。1 表示使用配置尺寸。

`default_disable_3d`¶

API：public

var default_disable_3d: bool = false

新建 SubViewport 是否禁用 3D。

`default_transparent_bg`¶

API：public

var default_transparent_bg: bool = false

新建 SubViewport 是否启用透明背景。

方法¶

`setup_split_screen`¶

API：public

func setup_split_screen(root: Control, viewport_count: int, options: Dictionary = {}) -> Array[SubViewport]:

创建 1 到 4 个 SubViewport 的分屏布局。

参数：

名称	说明
`root`	承载布局的 Control。
`viewport_count`	目标 viewport 数量；小于等于 0 时只清理。
`options`	可选设置，支持 viewport_size、columns、disable_3d、transparent_bg、stretch。

返回：当前 SubViewport 列表副本。

结构：

options: Dictionary，包含 viewport_size: Vector2i 或 Vector2、columns: int、disable_3d: bool、transparent_bg: bool 和 stretch: bool。

`clear_split_screen`¶

API：public

func clear_split_screen(free_cameras: bool = false) -> void:

清理当前分屏布局。

参数：

名称	说明
`free_cameras`	是否连同已挂载相机一起释放。

`get_viewport_count`¶

API：public

func get_viewport_count() -> int:

获取当前 SubViewport 数量。

返回：viewport 数量。

`get_viewports`¶

API：public

func get_viewports() -> Array[SubViewport]:

获取当前 SubViewport 列表副本。

返回：viewport 列表。

`get_viewport`¶

API：public

func get_viewport(index: int) -> SubViewport:

获取指定索引的 SubViewport。

参数：

名称	说明
`index`	viewport 索引。

返回：SubViewport；不存在时返回 null。

`get_container`¶

API：public

func get_container(index: int) -> SubViewportContainer:

获取指定索引的 SubViewportContainer。

参数：

名称	说明
`index`	viewport 索引。

返回：SubViewportContainer；不存在时返回 null。

`set_viewport_camera`¶

API：public

func set_viewport_camera(index: int, camera: Node) -> bool:

将相机挂载到指定 SubViewport。

参数：

名称	说明
`index`	viewport 索引。
`camera`	Camera2D 或 Camera3D 节点。

返回：挂载成功返回 true。

`set_postprocess_material`¶

API：public

func set_postprocess_material(index: int, material: Material) -> bool:

设置指定 SubViewportContainer 的后处理材质。

参数：

名称	说明
`index`	viewport 索引。
`material`	材质；传 null 可清除。

返回：设置成功返回 true。

`screen_to_world_ray_3d`¶

API：public

func screen_to_world_ray_3d( camera: Camera3D, screen_position: Vector2, length: float = 1000.0 ) -> Dictionary:

从屏幕/Viewport 坐标构建 3D 射线。

参数：

名称	说明
`camera`	用于投射的 Camera3D。
`screen_position`	Viewport 内的屏幕坐标。
`length`	射线长度。

返回：包含 ok、origin、direction、end 的字典。

结构：

return: Dictionary，包含 ok: bool、origin: Vector3、direction: Vector3 和 end: Vector3。

`raycast_from_screen_3d`¶

API：public

func raycast_from_screen_3d( camera: Camera3D, screen_position: Vector2, collision_mask: int = 0xffffffff, length: float = 1000.0, exclude: Array[RID] = [] ) -> Dictionary:

从屏幕/Viewport 坐标执行 3D 射线检测。

参数：

名称	说明
`camera`	用于投射的 Camera3D。
`screen_position`	Viewport 内的屏幕坐标。
`collision_mask`	物理碰撞层掩码。
`length`	射线长度。
`exclude`	要排除的 RID 列表。

返回：包含射线信息、hit 标记和 result 的字典。

结构：

return: Dictionary，包含物理射线检测得到的 ok、origin、direction、end、hit 和 result。

`world_to_screen_3d`¶

API：public
首次版本：8.0.0

func world_to_screen_3d(camera: Camera3D, world_position: Vector3) -> Vector2:

将 3D 世界坐标转换为屏幕/Viewport 坐标。

参数：

名称	说明
`camera`	用于投影的 Camera3D。
`world_position`	3D 世界坐标。

返回：屏幕坐标；camera 无效时返回 Vector2.ZERO。需要失败原因时使用 world_to_screen_3d_report()。

`world_to_screen_3d_report`¶

API：public
首次版本：8.0.0

func world_to_screen_3d_report(camera: Camera3D, world_position: Vector3) -> Dictionary:

将 3D 世界坐标转换为结构化屏幕/Viewport 坐标报告。

参数：

名称	说明
`camera`	用于投影的 Camera3D。
`world_position`	3D 世界坐标。

返回：投影报告。

结构：

return: Dictionary，包含 ok、reason、screen_position 和 world_position；失败时 screen_position 为 Vector2.ZERO。

`world_to_screen_2d`¶

API：public

func world_to_screen_2d(canvas_item: CanvasItem, world_position: Vector2) -> Vector2:

将 CanvasItem 所在世界坐标转换为屏幕/Viewport 坐标。

参数：

名称	说明
`canvas_item`	参考 CanvasItem。
`world_position`	2D 世界坐标。

返回：屏幕坐标。

`screen_to_world_2d`¶

API：public

func screen_to_world_2d(canvas_item: CanvasItem, screen_position: Vector2) -> Vector2:

将屏幕/Viewport 坐标转换为 CanvasItem 所在世界坐标。

参数：

名称	说明
`canvas_item`	参考 CanvasItem。
`screen_position`	屏幕坐标。

返回：2D 世界坐标。

`calculate_control_window_rect`¶

API：public
首次版本：8.0.0

func calculate_control_window_rect( control_rect: Rect2, viewport_size: Vector2, window_size: Vector2i, options: Dictionary = {} ) -> Dictionary:

将 Viewport 逻辑坐标中的 Control 矩形换算为物理窗口像素矩形。适合需要把 Godot UI 区域同步给原生 overlay、平台控件或工具预览的桥接层。该方法只做坐标换算，不创建或管理任何外部视图。

参数：

名称	说明
`control_rect`	Control 的全局矩形，单位为 Viewport 逻辑坐标。
`viewport_size`	Viewport 可见尺寸。
`window_size`	DisplayServer 物理窗口尺寸。
`options`	可选项，支持 content_rect 与 viewport_offset，用于 letterbox、HiDPI 或嵌入窗口映射。

返回：窗口矩形报告。

结构：

options: Dictionary，可包含 content_rect: Rect2i 或 Rect2；未提供 content_rect 时可用 viewport_offset: Vector2i/Vector2 叠加窗口偏移。
return: Dictionary，包含 ok、rect、position、size、scale_x、scale_y、mapping_mode、content_rect、viewport_offset、control_rect、viewport_size 和 window_size。

`get_control_window_rect`¶

API：public
首次版本：8.0.0

func get_control_window_rect(control: Control, viewport: Viewport = null) -> Dictionary:

读取 Control 当前全局矩形并换算为物理窗口像素矩形。

参数：

名称	说明
`control`	目标 Control。
`viewport`	可选 Viewport；为空时使用 control 所在 Viewport。

返回：窗口矩形报告。

结构：

return: Dictionary，包含 ok、rect、position、size、scale_x、scale_y、mapping_mode、content_rect、viewport_offset、control_rect、viewport_size 和 window_size。

`calculate_safe_area_margins`¶

API：public
首次版本：5.2.0

func calculate_safe_area_margins( safe_area: Rect2i, window_size: Vector2i, viewport_size: Vector2, extra_margins: Dictionary = {} ) -> Dictionary:

根据物理屏幕安全区计算 Viewport 逻辑坐标中的边距。 extra_margins 使用已经转换到 Viewport 逻辑坐标的 top、left、bottom、right，可用于叠加项目自己的遮挡区域。

参数：

名称	说明
`safe_area`	DisplayServer 返回的物理像素安全区。
`window_size`	DisplayServer 返回的物理窗口尺寸。
`viewport_size`	当前 Viewport 可见尺寸。
`extra_margins`	额外逻辑边距。

返回：安全区边距报告。

结构：

extra_margins: Dictionary，可选 top、left、bottom、right，单位为 Viewport 逻辑坐标。
return: Dictionary，包含 ok、top、left、bottom、right、scale_x、scale_y、safe_area、window_size 和 viewport_size。

`get_display_safe_area_margins`¶

API：public
首次版本：5.2.0

func get_display_safe_area_margins(viewport: Viewport = null, extra_margins: Dictionary = {}) -> Dictionary:

读取当前 DisplayServer 安全区并转换为 Viewport 逻辑边距。

参数：

名称	说明
`viewport`	可选 Viewport；为空时使用物理窗口尺寸作为逻辑尺寸。
`extra_margins`	额外逻辑边距。

返回：安全区边距报告。

结构：

extra_margins: Dictionary，可选 top、left、bottom、right，单位为 Viewport 逻辑坐标。
return: Dictionary，包含 ok、top、left、bottom、right、scale_x、scale_y、safe_area、window_size 和 viewport_size。

`apply_safe_area_margins`¶

API：public
首次版本：5.2.0

func apply_safe_area_margins(container: MarginContainer, margins: Dictionary) -> bool:

将边距字典应用到 MarginContainer。

参数：

名称	说明
`container`	目标 MarginContainer。
`margins`	边距字典。

返回：应用成功返回 true。

结构：

margins: Dictionary，包含 top、left、bottom、right，单位为 Viewport 逻辑坐标。

`apply_display_safe_area_margins`¶

API：public
首次版本：5.2.0

func apply_display_safe_area_margins( container: MarginContainer, viewport: Viewport = null, extra_margins: Dictionary = {} ) -> Dictionary:

读取当前 DisplayServer 安全区并应用到 MarginContainer。

参数：

名称	说明
`container`	目标 MarginContainer。
`viewport`	可选 Viewport；为空时优先使用 container 所在 Viewport。
`extra_margins`	额外逻辑边距。

返回：安全区边距报告，applied 表示是否成功写入 container。

结构：

extra_margins: Dictionary，可选 top、left、bottom、right，单位为 Viewport 逻辑坐标。
return: Dictionary，包含 ok、applied、top、left、bottom、right、scale_x、scale_y、safe_area、window_size 和 viewport_size。

`get_debug_snapshot`¶

API：public

func get_debug_snapshot() -> Dictionary:

获取调试快照。

返回：调试信息字典。

结构：

return: Dictionary，包含 viewport_count、container_count、has_root、has_grid 和 resolution_scale。

`tick`¶

API：public

func tick(_delta: float) -> void:

驱动布局生命周期清理。

参数：

名称	说明
`_delta`	本帧时间增量。

GFViewportUtility¶

成员概览¶

信号¶

split_screen_configured¶

split_screen_cleared¶

属性¶

viewport_resolution_scale¶

default_disable_3d¶

default_transparent_bg¶

方法¶

setup_split_screen¶

clear_split_screen¶

get_viewport_count¶

get_viewports¶

get_viewport¶

get_container¶

set_viewport_camera¶

set_postprocess_material¶

screen_to_world_ray_3d¶

raycast_from_screen_3d¶

world_to_screen_3d¶

world_to_screen_3d_report¶

world_to_screen_2d¶

screen_to_world_2d¶

calculate_control_window_rect¶

get_control_window_rect¶

calculate_safe_area_margins¶

get_display_safe_area_margins¶

apply_safe_area_margins¶

apply_display_safe_area_margins¶

get_debug_snapshot¶

tick¶