GFRenderWarmupUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/display/gf_render_warmup_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
通用渲染资源预热工具。 通过清单或节点树收集 Mesh、Material、Texture 等渲染资源，并按帧预算提前加载和触碰 RID。 它不决定项目何时预热、预热哪些场景或如何展示加载进度。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | warmup_queued |
signal warmup_queued(queue_id: int, manifest_id: StringName, entry_count: int) |
| 信号 | warmup_entry_processed |
signal warmup_entry_processed(queue_id: int, entry_index: int, result: Dictionary) |
| 信号 | warmup_completed |
signal warmup_completed(queue_id: int, summary: Dictionary) |
| 枚举 | TouchMode |
enum TouchMode |
| 属性 | default_entries_per_tick |
var default_entries_per_tick: int = 4 |
| 属性 | default_max_seconds |
var default_max_seconds: float = 0.0 |
| 属性 | default_touch_mode |
var default_touch_mode: TouchMode = TouchMode.RID_ONLY |
| 属性 | keep_resources_cached |
var keep_resources_cached: bool = true |
| 属性 | instantiate_packed_scenes |
var instantiate_packed_scenes: bool = false |
| 方法 | tick |
func tick(_delta: float) -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | queue_manifest |
func queue_manifest(manifest: GFRenderWarmupManifest, options: Dictionary = {}) -> int: |
| 方法 | warmup_manifest_now |
func warmup_manifest_now(manifest: GFRenderWarmupManifest, options: Dictionary = {}) -> Dictionary: |
| 方法 | process_queue |
func process_queue(max_entries: int = 1) -> int: |
| 方法 | build_manifest_from_tree |
func build_manifest_from_tree(root: Node, options: Dictionary = {}) -> GFRenderWarmupManifest: |
| 方法 | build_manifest_from_scene |
func build_manifest_from_scene(scene: PackedScene, options: Dictionary = {}) -> GFRenderWarmupManifest: |
| 方法 | build_manifest_from_scene_path |
func build_manifest_from_scene_path(scene_path: String, options: Dictionary = {}) -> GFRenderWarmupManifest: |
| 方法 | clear_queue |
func clear_queue() -> void: |
| 方法 | release_cached_resources |
func release_cached_resources() -> void: |
| 方法 | release_temporary_render_nodes |
func release_temporary_render_nodes() -> void: |
| 方法 | get_cached_resource_count |
func get_cached_resource_count() -> int: |
| 方法 | get_queue_size |
func get_queue_size() -> int: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
warmup_queued¶
- API：
public
清单加入预热队列时发出。
参数：
| 名称 | 说明 |
|---|---|
queue_id |
预热队列标识。 |
manifest_id |
清单标识。 |
entry_count |
清单条目数量。 |
warmup_entry_processed¶
- API：
public
单个条目预热完成后发出。
参数：
| 名称 | 说明 |
|---|---|
queue_id |
预热队列标识。 |
entry_index |
清单条目索引。 |
result |
单个条目的预热结果。 |
结构：
result: Dictionary，包含 ok、resource_path、kind、resource_class、touched_count、error、metadata 和 entry_index。
warmup_completed¶
- API：
public
单个清单预热完成后发出。
参数：
| 名称 | 说明 |
|---|---|
queue_id |
预热队列标识。 |
summary |
清单预热摘要。 |
结构：
summary: Dictionary，包含 queue_id、manifest_id、total_count、processed_count、failed_count、ok、elapsed_seconds、stopped_by_budget、completed_at_unix 和 results。
枚举¶
TouchMode¶
- API：
public
enum TouchMode { ## 只加载资源并触碰 RID。 RID_ONLY, ## 使用离屏临时渲染节点让材质或 Mesh 参与一次渲染。 TEMPORARY_RENDER_NODES, }
预热触碰模式。
属性¶
default_entries_per_tick¶
- API：
public
每次 tick 默认处理的最大条目数。
default_max_seconds¶
- API：
public
默认预热时间预算，单位秒。小于等于 0 表示不限制。
default_touch_mode¶
- API：
public
默认触碰模式。
keep_resources_cached¶
- API：
public
是否保留已加载资源引用，避免预热后立刻被释放。
instantiate_packed_scenes¶
- API：
public
从 PackedScene 条目预热时是否实例化场景并扫描其渲染资源。默认关闭以避免触发项目脚本副作用。
方法¶
tick¶
- API：
public
推进预热队列。
参数：
| 名称 | 说明 |
|---|---|
_delta |
本帧时间增量。 |
dispose¶
- API：
public
清空预热队列、缓存资源和临时渲染节点。
queue_manifest¶
- API：
public
将预热清单加入队列。
参数：
| 名称 | 说明 |
|---|---|
manifest |
预热清单。 |
options |
可选参数，支持 entries_per_tick、max_seconds、touch_mode、keep_cached、instantiate_packed_scenes。 |
返回：队列标识；失败返回 -1。
结构：
options: Dictionary，包含 entries_per_tick、max_seconds、touch_mode、keep_cached、instantiate_packed_scenes、temporary_parent 和 temporary_viewport_size。
warmup_manifest_now¶
- API：
public
立即预热整个清单。
参数：
| 名称 | 说明 |
|---|---|
manifest |
预热清单。 |
options |
可选参数，支持 max_seconds、touch_mode、keep_cached、instantiate_packed_scenes。 |
返回：预热摘要。
结构：
options: Dictionary，包含 max_seconds、touch_mode、keep_cached、instantiate_packed_scenes、temporary_parent 和 temporary_viewport_size。return: Dictionary，包含 queue_id、manifest_id、total_count、processed_count、failed_count、ok、elapsed_seconds、stopped_by_budget、completed_at_unix 和 results。
process_queue¶
- API：
public
按预算处理队列。
参数：
| 名称 | 说明 |
|---|---|
max_entries |
最多处理条目数。 |
返回：实际处理条目数。
build_manifest_from_tree¶
- API：
public
从节点树收集可预热的渲染资源。
参数：
| 名称 | 说明 |
|---|---|
root |
根节点。 |
options |
可选参数，支持 manifest_id、include_materials、include_meshes、include_textures。 |
返回：预热清单。
结构：
options: Dictionary，包含 manifest_id、include_materials、include_meshes 和 include_textures。
build_manifest_from_scene¶
- API：
public
func build_manifest_from_scene(scene: PackedScene, options: Dictionary = {}) -> GFRenderWarmupManifest:
从场景资源收集可预热的渲染资源。
参数：
| 名称 | 说明 |
|---|---|
scene |
场景资源。 |
options |
可选参数，支持 manifest_id、include_materials、include_meshes、include_textures。 |
返回：预热清单。
结构：
options: Dictionary，包含 manifest_id、include_materials、include_meshes 和 include_textures。
build_manifest_from_scene_path¶
- API：
public
func build_manifest_from_scene_path(scene_path: String, options: Dictionary = {}) -> GFRenderWarmupManifest:
从场景路径收集可预热的渲染资源。
参数：
| 名称 | 说明 |
|---|---|
scene_path |
场景资源路径。 |
options |
可选参数，支持 manifest_id、include_materials、include_meshes、include_textures。 |
返回：预热清单。
结构：
options: Dictionary，包含 manifest_id、include_materials、include_meshes 和 include_textures。
clear_queue¶
- API：
public
清空尚未处理的预热队列。
release_cached_resources¶
- API：
public
释放预热缓存的资源引用。
release_temporary_render_nodes¶
- API：
public
释放尚未清理的离屏临时渲染节点。
get_cached_resource_count¶
- API：
public
获取预热缓存资源数量。
返回：缓存资源数量。
get_queue_size¶
- API：
public
获取待处理队列数量。
返回：队列数量。
get_debug_snapshot¶
- API：
public
获取调试快照。
返回：调试信息字典。
结构：
return: Dictionary，包含 queue_size、cached_resource_count、processed_entry_count、failed_entry_count、default_entries_per_tick、default_max_seconds、default_touch_mode、keep_resources_cached、instantiate_packed_scenes 和 temporary_render_node_count。