CubeTextureLoader

Loader for cube map texture assets.

Provides both synchronous and asynchronous interfaces for loading the six face images of a cube map from disk. Supported formats include PNG, JPEG, TGA, BMP, and HDR. It is intended to be accessed through the shared runtime context and used directly by application or node code when cube map resources are needed.

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

The asynchronous LoadAsync method schedules file I/O off the main thread and returns a CubeTextureLoadHandle immediately. The handle can later be queried from the main thread to retrieve the loaded texture once the operation completes. Ownership of the texture 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 cube_texture = context->cube_texture_loader->Load({
    .positive_x = "assets/skybox/px.png",
    .negative_x = "assets/skybox/nx.png",
    .positive_y = "assets/skybox/py.png",
    .negative_y = "assets/skybox/ny.png",
    .positive_z = "assets/skybox/pz.png",
    .negative_z = "assets/skybox/nz.png",
});

Types

CubeTextureLoader::Parameters struct

Paths to the six face images that make up a cube map.

Parameter	Description
positive_x fs::path	Right face (+X).
negative_x fs::path	Left face (-X).
positive_y fs::path	Top face (+Y).
negative_y fs::path	Bottom face (-Y).
positive_z fs::path	Front face (+Z).
negative_z fs::path	Back face (-Z).

Functions

Load() std::expected<std::shared_ptr<CubeTexture>, std::string >

Loads a cube texture synchronously from six image files.

Performs file I/O and texture creation on the calling thread. If loading succeeds a fully constructed CubeTexture 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::shared_ptr< CubeTexture>, std::string > CubeTextureLoader::Load(const Parameters& params) const;

Parameter	Description
params	Paths to the six face images.

LoadAsync() CubeTextureLoadHandle

Loads a cube texture asynchronously from six image files.

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

Ownership of the texture 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.

CubeTextureLoadHandle CubeTextureLoader::LoadAsync(const Parameters& params) const;

Parameter	Description
params	Paths to the six face images.