Loads a 3D scene (glTF / OBJ / FBX / GLB ... via Assimp/medialoader) into the ECS scene tree. 更多...

#include <SceneLoader.h>

类 eve::sceneloader::SceneLoader 继承关系图:

类
struct	CpuImage
	CPU-decoded texture (RGBA8) keyed by the same source+suffix key as TextureCache. 更多...

Public 类型
using	TextureCache = std::unordered_map< std::string, graphics::Texture * >
	Caches shared across the loader: textures by source key, GPU meshes per aiMesh.

using	MeshCache = std::unordered_map< const aiMesh , graphics::Mesh >

using	CpuImageMap = std::unordered_map< std::string, CpuImage >

Public 成员函数
	Module_REG (SceneLoader)

	SceneLoader ()
	Construct the loader and publish its optional action-block provider.

	~SceneLoader () override
	Scene loader.

scene::SceneHost *	load (const std::string &path, bool linkRenderables=true, const LoadOptions &options={})
	Full load: build the GameObject tree from `path`, mount it, return host.

scene::SceneHost *	load (const std::string &path, const LoadOptions &options)
	Loads .

scene::SceneHost *	loadPreset (const std::string &path, const std::string &preset)
	Load with a built-in preset: quality, balanced, mobile, or raw.

eve::Result< bool >	reload (const std::string &path, SceneDiff *out=nullptr, const LoadOptions &options={})
	Hot-reload `path`. Re-decodes, diffs, and applies only what changed.

SceneDiff	diff (const std::string &path)
	Dry-run diff for `path` against the currently mounted tree (no mutation).

eve::Result< SceneInspection >	inspect (const std::string &path, const LoadOptions &options={})
	Decode with explicit options and return copied metadata without mounting or GPU upload.

scene::SceneHost *	host (const std::string &path)
	The mounted host for `path`, or nullptr if not loaded.

void	unload (const std::string &path)
	Drop the loaded scene for `path`, destroying linked Renderable3D objects.

int	nodeCount (const std::string &path)
	Number of GameObjects (SceneNodes) currently mounted for `path`; 0 if none.

bool	loaded (const std::string &path)
	True if `path` is currently loaded.

bool	loadAsync (const std::string &path, const LoadOptions &options={}, std::function< void(scene::SceneHost *)> done=nullptr)
	Decode `path` on a worker thread, then apply it on the main thread the next time pollAsync() is called (GPU upload + ECS mount happen there). `done` fires on the main thread during pollAsync() with the mounted host. Returns false when a load for `path` is already in flight.

bool	loadAsyncDefault (const std::string &path)
	Script-friendly async load using the default import preset.

bool	loadAsyncPreset (const std::string &path, const std::string &preset)
	Loads async preset.

int	pollAsync ()
	Mount every decoded-but-not-applied scene. Must be called on the main / render thread. Returns the number of scenes applied this call.

bool	prewarmAsync (const std::string &path, const LoadOptions &options={})
	Decode and retain a scene without creating ECS/GPU objects.

bool	prewarm (const std::string &path)
	Script-friendly CPU prewarm using the default import preset.

bool	prewarmed (const std::string &path) const
	True when a decoded scene is ready for load() to consume.

void	clearPrewarm (const std::string &path)
	Drop a decoded prewarm result and release its CPU scene.

int	pendingAsyncCount () const
	Number of async loads still waiting to be mounted.

int	warningCount (const std::string &path) const
	Number of non-fatal import warnings retained for path.

std::string	warning (const std::string &path, int index) const
	Non-fatal import warning at index, or an empty string.

bool	setLod (const std::string &path, int level)
	Select imported name-convention LOD (_LOD0, _LOD1, ...).

int	socketCount (const std::string &path) const
	Number of imported SOCKET_ nodes.

std::string	socketName (const std::string &path, int index) const
	Name of an imported SOCKET_ node, or an empty string.

int	collisionCount (const std::string &path) const
	Number of imported UCX_/UBX_/USP_/UCP_ collision nodes.

std::string	collisionName (const std::string &path, int index) const
	Name of an imported collision node, or an empty string.

int	lightCount (const std::string &path)
	Number of imported Light3D entities for `path`; 0 if none / disabled.

graphics::Light3D *	light (const std::string &path, int index)
	Light.

int	cameraCount (const std::string &path)
	Number of imported Camera3D entities for `path`; 0 if none / disabled.

graphics::Camera3D *	camera (const std::string &path, int index)
	Camera.

int	animationCount (const std::string &path)
	Number of imported animation clips for `path`; 0 if none / disabled.

animation::AnimSkeleton *	skeleton (const std::string &path)
	Imported skeleton for `path` (nullptr when the scene has no animations).

animation::AnimClip *	clip (const std::string &path, int index)
	Clip.

Public 成员函数继承自 eve::Module
virtual	~Module ()
	Module.

virtual std::string	getName () const =0
	Returns the name.

静态 Public 成员函数
static scene::NodeDesc	buildNodeDesc (const aiScene scene, MeshSlotMap slotsOut=nullptr)
	Flatten an Assimp scene into a scene::NodeDesc tree (id = object id).

static SceneDiff	diffTree (scene::SceneHost *host, const scene::NodeDesc &newRoot)
	Diff a mounted host tree against a freshly built NodeDesc tree.

static bool	applyTreeDiff (scene::SceneHost host, const scene::NodeDesc &newRoot, const SceneDiff &diff, graphics::Graphics gfx, const MeshSlotMap *slots)
	Apply a diff to the host arena in place. Creates/destroys Renderable3D for added/removed mesh objects when `gfx` and `slots` are provided; otherwise only the GameObject tree is mutated (useful for logic-only tests).

static void	fillSceneBounds (scene::SceneHost *host, const MeshSlotMap &slots)
	Fill node bounds from Assimp mesh AABBs (mesh GameObjects get the exact local-space AABB; ancestors get the union of their children in local space), so picking / frustum culling work on loaded models.

详细描述

Loads a 3D scene (glTF / OBJ / FBX / GLB ... via Assimp/medialoader) into the ECS scene tree.

For every aiNode it creates a scene::SceneHost GameObject (SceneNode) mirroring the source hierarchy, and for every referenced aiMesh it creates a child GameObject that links a graphics::Renderable3D (mesh + material). Materials import the PBR base-color / metallic / roughness / normal / height factors and textures. Textures are cached by path and shared across meshes; meshes referenced by several nodes share one GPU buffer (LoadOptions::sharedMeshes). aiLight / aiCamera / aiAnimation entries are imported as graphics::Light3D / graphics::Camera3D entities and animation::AnimSkeleton + AnimClip objects when the corresponding LoadOptions flags are enabled.

Hot-reload: reload() re-decodes the file, diffs the new tree against the mounted tree, and applies only the changed GameObjects in place — transform / visibility edits patch the existing node, added objects are appended (mesh uploaded once), removed objects are destroyed, and identical objects are left completely untouched (no re-upload, no rebuild).

在文件 SceneLoader.h 第 153 行定义.

成员类型定义说明

◆ CpuImageMap

using eve::sceneloader::SceneLoader::CpuImageMap = std::unordered_map<std::string, CpuImage>

在文件 SceneLoader.h 第 279 行定义.

◆ MeshCache

using eve::sceneloader::SceneLoader::MeshCache = std::unordered_map<const aiMesh *, graphics::Mesh *>

在文件 SceneLoader.h 第 272 行定义.

◆ TextureCache

using eve::sceneloader::SceneLoader::TextureCache = std::unordered_map<std::string, graphics::Texture *>

Caches shared across the loader: textures by source key, GPU meshes per aiMesh.

在文件 SceneLoader.h 第 271 行定义.

构造及析构函数说明

◆ SceneLoader()

eve::sceneloader::SceneLoader::SceneLoader ( )

Construct the loader and publish its optional action-block provider.

在文件 SceneLoader.cpp 第 64 行定义.

引用了 eve::sceneloader::registerPrefabActionCapabilities().

◆ ~SceneLoader()

eve::sceneloader::SceneLoader::~SceneLoader ( )

override

Scene loader.

在文件 SceneLoader.cpp 第 66 行定义.

引用了 eve::sceneloader::shutdownPrefabActionCapabilities().

成员函数说明

◆ animationCount()

int eve::sceneloader::SceneLoader::animationCount ( const std::string & path )

Number of imported animation clips for path; 0 if none / disabled.

在文件 SceneLoader.cpp 第 1316 行定义.

引用了 path.

◆ applyTreeDiff()

bool eve::sceneloader::SceneLoader::applyTreeDiff	(	scene::SceneHost *	host,
		const scene::NodeDesc &	newRoot,
		const SceneDiff &	diff,
		graphics::Graphics *	gfx,
		const MeshSlotMap *	slots
	)

static

Apply a diff to the host arena in place. Creates/destroys Renderable3D for added/removed mesh objects when gfx and slots are provided; otherwise only the GameObject tree is mutated (useful for logic-only tests).

在文件 SceneLoader.cpp 第 705 行定义.

引用了 c, d, diff(), eve::sceneloader::SceneDiff::empty(), fillSceneBounds(), eve::scene::findLinkKind(), host, eve::scene::SceneNode::id, idx, n, nodes, r, root, slots , 以及 t.

被这些函数引用 reload().

◆ buildNodeDesc()

scene::NodeDesc eve::sceneloader::SceneLoader::buildNodeDesc	(	const aiScene *	scene,
		MeshSlotMap *	slotsOut = `nullptr`
	)

static

Flatten an Assimp scene into a scene::NodeDesc tree (id = object id).

在文件 SceneLoader.cpp 第 663 行定义.

引用了 counts, root , 以及 scene.

被这些函数引用 diff().

◆ camera()

graphics::Camera3D * eve::sceneloader::SceneLoader::camera	(	const std::string &	path,
		int	index
	)

Camera.

在文件 SceneLoader.cpp 第 1308 行定义.

引用了 index , 以及 path.

◆ cameraCount()

int eve::sceneloader::SceneLoader::cameraCount ( const std::string & path )

Number of imported Camera3D entities for path; 0 if none / disabled.

在文件 SceneLoader.cpp 第 1303 行定义.

引用了 path.

◆ clearPrewarm()

void eve::sceneloader::SceneLoader::clearPrewarm ( const std::string & path )

Drop a decoded prewarm result and release its CPU scene.

在文件 SceneLoader.cpp 第 1212 行定义.

引用了 path.

◆ clip()

animation::AnimClip * eve::sceneloader::SceneLoader::clip	(	const std::string &	path,
		int	index
	)

Clip.

在文件 SceneLoader.cpp 第 1326 行定义.

引用了 index , 以及 path.

◆ collisionCount()

int eve::sceneloader::SceneLoader::collisionCount ( const std::string & path ) const

Number of imported UCX_/UBX_/USP_/UCP_ collision nodes.

在文件 SceneLoader.cpp 第 1274 行定义.

引用了 path.

◆ collisionName()

std::string eve::sceneloader::SceneLoader::collisionName	(	const std::string &	path,
		int	index
	)		const

Name of an imported collision node, or an empty string.

在文件 SceneLoader.cpp 第 1280 行定义.

引用了 index, name, nodes , 以及 path.

◆ diff()

SceneDiff eve::sceneloader::SceneLoader::diff ( const std::string & path )

Dry-run diff for path against the currently mounted tree (no mutation).

在文件 SceneLoader.cpp 第 1036 行定义.

引用了 eve::sceneloader::SceneDiffEntry::Add, buildNodeDesc(), c, d, diffTree(), eve::ResourceManager::getInstance(), eve::model3d::ModelData::getScene(), key, n, parent, path, eve::ResourceManager::reload() , 以及 slots.

被这些函数引用 applyTreeDiff() , 以及 reload().

◆ diffTree()

SceneDiff eve::sceneloader::SceneLoader::diffTree	(	scene::SceneHost *	host,
		const scene::NodeDesc &	newRoot
	)

static

Diff a mounted host tree against a freshly built NodeDesc tree.

在文件 SceneLoader.cpp 第 671 行定义.

引用了 c, d, eve::sceneloader::SceneDiff::entries, host, eve::scene::SceneNode::id, n, eve::sceneloader::SceneDiffEntry::Remove, eve::sceneloader::SceneDiff::removed , 以及 t.

被这些函数引用 diff(), inspect() , 以及 reload().

◆ fillSceneBounds()

void eve::sceneloader::SceneLoader::fillSceneBounds	(	scene::SceneHost *	host,
		const MeshSlotMap &	slots
	)

static

Fill node bounds from Assimp mesh AABBs (mesh GameObjects get the exact local-space AABB; ancestors get the union of their children in local space), so picking / frustum culling work on loaded models.

在文件 SceneLoader.cpp 第 819 行定义.

引用了 host, n, slots , 以及 t.

被这些函数引用 applyTreeDiff().

◆ host()

scene::SceneHost * eve::sceneloader::SceneLoader::host ( const std::string & path )

The mounted host for path, or nullptr if not loaded.

在文件 SceneLoader.cpp 第 1105 行定义.

引用了 path.

◆ inspect()

eve::Result< SceneInspection > eve::sceneloader::SceneLoader::inspect	(	const std::string &	path,
		const LoadOptions &	options = `{}`
	)

Decode with explicit options and return copied metadata without mounting or GPU upload.

在文件 SceneLoader.cpp 第 1067 行定义.

被这些函数引用 eve::sceneloader_editing::SceneImportPreflightRuntime::inspect().

◆ light()

graphics::Light3D * eve::sceneloader::SceneLoader::light	(	const std::string &	path,
		int	index
	)

Light.

在文件 SceneLoader.cpp 第 1295 行定义.

引用了 index , 以及 path.

◆ lightCount()

int eve::sceneloader::SceneLoader::lightCount ( const std::string & path )

Number of imported Light3D entities for path; 0 if none / disabled.

在文件 SceneLoader.cpp 第 1290 行定义.

引用了 path.

◆ load() [1/2]

scene::SceneHost * eve::sceneloader::SceneLoader::load	(	const std::string &	path,
		bool	linkRenderables = `true`,
		const LoadOptions &	options = `{}`
	)

Full load: build the GameObject tree from path, mount it, return host.

在文件 SceneLoader.cpp 第 970 行定义.

引用了 eve::scene::SceneHost::createHost(), d, host, key, eve::Loaded, options, path , 以及 eve::scene::TransformSystem::updateHost().

被这些函数引用 load(), loadPreset() , 以及 reload().

◆ load() [2/2]

scene::SceneHost * eve::sceneloader::SceneLoader::load	(	const std::string &	path,
		const LoadOptions &	options
	)

Loads .

在文件 SceneLoader.cpp 第 993 行定义.

引用了 load(), options , 以及 path.

◆ loadAsync()

bool eve::sceneloader::SceneLoader::loadAsync	(	const std::string &	path,
		const LoadOptions &	options = `{}`,
		std::function< void(scene::SceneHost *)>	done = `nullptr`
	)

Decode path on a worker thread, then apply it on the main thread the next time pollAsync() is called (GPU upload + ECS mount happen there). done fires on the main thread during pollAsync() with the mounted host. Returns false when a load for path is already in flight.

参数

done Void.

在文件 SceneLoader.cpp 第 1139 行定义.

引用了 d, key, options , 以及 path.

被这些函数引用 loadAsyncPreset().

◆ loadAsyncDefault()

bool eve::sceneloader::SceneLoader::loadAsyncDefault ( const std::string & path )

inline

Script-friendly async load using the default import preset.

在文件 SceneLoader.h 第 212 行定义.

引用了 path.

◆ loadAsyncPreset()

bool eve::sceneloader::SceneLoader::loadAsyncPreset	(	const std::string &	path,
		const std::string &	preset
	)

Loads async preset.

在文件 SceneLoader.cpp 第 1163 行定义.

引用了 loadAsync() , 以及 path.

◆ loaded()

bool eve::sceneloader::SceneLoader::loaded ( const std::string & path )

True if path is currently loaded.

在文件 SceneLoader.cpp 第 1115 行定义.

引用了 path.

◆ loadPreset()

scene::SceneHost * eve::sceneloader::SceneLoader::loadPreset	(	const std::string &	path,
		const std::string &	preset
	)

Load with a built-in preset: quality, balanced, mobile, or raw.

在文件 SceneLoader.cpp 第 997 行定义.

引用了 load() , 以及 path.

◆ Module_REG()

eve::sceneloader::SceneLoader::Module_REG ( SceneLoader )

◆ nodeCount()

int eve::sceneloader::SceneLoader::nodeCount ( const std::string & path )

Number of GameObjects (SceneNodes) currently mounted for path; 0 if none.

在文件 SceneLoader.cpp 第 1110 行定义.

引用了 h, host , 以及 path.

◆ pendingAsyncCount()

int eve::sceneloader::SceneLoader::pendingAsyncCount ( ) const

Number of async loads still waiting to be mounted.

在文件 SceneLoader.cpp 第 1218 行定义.

◆ pollAsync()

int eve::sceneloader::SceneLoader::pollAsync ( )

Mount every decoded-but-not-applied scene. Must be called on the main / render thread. Returns the number of scenes applied this call.

在文件 SceneLoader.cpp 第 1167 行定义.

引用了 d , 以及 h.

◆ prewarm()

bool eve::sceneloader::SceneLoader::prewarm ( const std::string & path )

inline

Script-friendly CPU prewarm using the default import preset.

在文件 SceneLoader.h 第 225 行定义.

引用了 path.

◆ prewarmAsync()

bool eve::sceneloader::SceneLoader::prewarmAsync	(	const std::string &	path,
		const LoadOptions &	options = `{}`
	)

Decode and retain a scene without creating ECS/GPU objects.

在文件 SceneLoader.cpp 第 1185 行定义.

引用了 d, key, options , 以及 path.

◆ prewarmed()

bool eve::sceneloader::SceneLoader::prewarmed ( const std::string & path ) const

True when a decoded scene is ready for load() to consume.

在文件 SceneLoader.cpp 第 1208 行定义.

引用了 path.

◆ reload()

eve::Result< bool > eve::sceneloader::SceneLoader::reload	(	const std::string &	path,
		SceneDiff *	out = `nullptr`,
		const LoadOptions &	options = `{}`
	)

Hot-reload path. Re-decodes, diffs, and applies only what changed.

返回: A checked result whose value is true when anything changed. A successful false value is a decoded no-op; decode failures are reported through the structured status and leave the old scene intact.

参数

out	Optional borrowed output written with the applied diff.
options	Import options used for the fresh decode.

在文件 SceneLoader.cpp 第 1001 行定义.

引用了 eve::Applied, applyTreeDiff(), d, diff(), diffTree(), eve::sceneloader::SceneDiff::empty(), eve::Diagnostic::error(), eve::Failed, eve::Result< T >::failure(), key, load(), eve::Loaded, message, eve::NoOp, options, path, eve::Status::success(), eve::Result< T >::success() , 以及 eve::scene::TransformSystem::updateHost().

◆ setLod()

bool eve::sceneloader::SceneLoader::setLod	(	const std::string &	path,
		int	level
	)

Select imported name-convention LOD (_LOD0, _LOD1, ...).

在文件 SceneLoader.cpp 第 1243 行定义.

引用了 found, h, host, level, node, path , 以及 tag.

◆ skeleton()

animation::AnimSkeleton * eve::sceneloader::SceneLoader::skeleton ( const std::string & path )

Imported skeleton for path (nullptr when the scene has no animations).

在文件 SceneLoader.cpp 第 1321 行定义.

引用了 path.

◆ socketCount()

int eve::sceneloader::SceneLoader::socketCount ( const std::string & path ) const

Number of imported SOCKET_ nodes.

在文件 SceneLoader.cpp 第 1260 行定义.

引用了 path.

◆ socketName()

std::string eve::sceneloader::SceneLoader::socketName	(	const std::string &	path,
		int	index
	)		const

Name of an imported SOCKET_ node, or an empty string.

在文件 SceneLoader.cpp 第 1266 行定义.

引用了 index, name , 以及 path.

◆ unload()

void eve::sceneloader::SceneLoader::unload ( const std::string & path )

Drop the loaded scene for path, destroying linked Renderable3D objects.

在文件 SceneLoader.cpp 第 1117 行定义.

引用了 c, clip, eve::scene::findLinkKind(), n, path , 以及 t.

◆ warning()

std::string eve::sceneloader::SceneLoader::warning	(	const std::string &	path,
		int	index
	)		const

Non-fatal import warning at index, or an empty string.

在文件 SceneLoader.cpp 第 1235 行定义.

引用了 index , 以及 path.

被这些函数引用 inspect().

◆ warningCount()

int eve::sceneloader::SceneLoader::warningCount ( const std::string & path ) const

Number of non-fatal import warnings retained for path.

在文件 SceneLoader.cpp 第 1229 行定义.

引用了 path.

被这些函数引用 inspect().

该类的文档由以下文件生成:

src/modules/scene/loader/SceneLoader.h
src/modules/scene/loader/SceneLoader.cpp

类

Public 类型

Public 成员函数

静态 Public 成员函数

详细描述

成员类型定义说明

◆ CpuImageMap

◆ MeshCache

◆ TextureCache

构造及析构函数说明

◆ SceneLoader()

◆ ~SceneLoader()

成员函数说明

◆ animationCount()

◆ applyTreeDiff()

◆ buildNodeDesc()

◆ camera()

◆ cameraCount()

◆ clearPrewarm()

◆ clip()

◆ collisionCount()

◆ collisionName()

◆ diff()

◆ diffTree()

◆ fillSceneBounds()

◆ host()

◆ inspect()

◆ light()

◆ lightCount()

◆ load() [1/2]

◆ load() [2/2]

◆ loadAsync()

◆ loadAsyncDefault()

◆ loadAsyncPreset()

◆ loaded()

◆ loadPreset()

◆ Module_REG()

◆ nodeCount()

◆ pendingAsyncCount()

◆ pollAsync()

◆ prewarm()

◆ prewarmAsync()

◆ prewarmed()

◆ reload()

◆ setLod()

◆ skeleton()

◆ socketCount()

◆ socketName()

◆ unload()

◆ warning()

◆ warningCount()