MeshLoader

Loader for mesh assets.

Provides both synchronous and asynchronous interfaces for loading mesh data from disk. Supported formats include OBJ. It is intended to be accessed through the shared runtime context and used directly by application or node code when mesh resources are needed.

The synchronous Load method performs the entire load on the calling thread and returns either a fully constructed node hierarchy or an error message.

The asynchronous LoadAsync method schedules file I/O off the main thread and returns a MeshLoadHandle immediately. The handle can later be queried from the main thread to retrieve the loaded mesh once the operation completes. Ownership of the returned node is transferred out of the handle when it is successfully taken.

Internally, asynchronous loading is coordinated through a LoadScheduler instance, which ensures that background work and main-thread commits are clearly separated.

auto MyScene::OnAttached(SharedContextPointer context) -> void {
  mesh_handle_ = context->mesh_loader->LoadAsync("assets/robot.obj");
}

auto MyScene::OnUpdate(float _) -> void {
  if (auto node = mesh_handle_.TryTake()) {
    // nodes are uniquely owned by the scene so we move
    Add(std::move(node.value()));
  }
}

To learn more about how meshes are imported and loaded see the Importing Assets Guide.

Functions

Load() std::expected<std::unique_ptr<Node>, std::string >

Loads a mesh synchronously from a mesh file.

Performs file I/O and mesh construction on the calling thread. If loading succeeds a fully constructed Node is returned. On failure an error message describing the problem is returned instead.

This method is intended for tooling, offline processing, or scenarios where blocking behavior is acceptable.

std::expected<std::unique_ptr< Node>, std::string > MeshLoader::Load(const fs::path& path) const;

Parameter	Description
path	Filesystem path to the mesh asset.

LoadAsync() MeshLoadHandle

Loads a mesh asynchronously from a mesh file.

Schedules file I/O work to run off the main thread and returns immediately with a MeshLoadHandle. The handle can later be polled to retrieve the loaded mesh once the operation completes.

Ownership of the returned node is transferred out of the handle when it is successfully taken. Errors can be retrieved explicitly from the handle or will be reported through the logger.

MeshLoadHandle MeshLoader::LoadAsync(const fs::path& path) const;

Parameter	Description
path	Filesystem path to the mesh asset.