TextureLoader

Loader for 2D texture assets.

Provides both synchronous and asynchronous interfaces for loading texture data 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 texture resources are needed.

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

The asynchronous LoadAsync method schedules file I/O off the main thread and returns a TextureLoadHandle 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 MyScene::OnAttached(SharedContextPointer context) -> void {
  texture_handle_ = context->texture_loader->LoadAsync("assets/diffuse.png");
}

auto MyScene::OnUpdate(float _) -> void {
  if (auto texture = texture_handle_.TryTake()) {
    material_->texture_map = texture.value();
  }
}

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

Functions

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

Loads a texture synchronously from an image file.

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

Parameter	Description
path	Filesystem path to the texture asset.

LoadAsync() TextureLoadHandle

Loads a texture asynchronously from an image file.

Schedules file I/O work to run off the main thread and returns immediately with a TextureLoadHandle. 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.

TextureLoadHandle TextureLoader::LoadAsync(const fs::path& path) const;

Parameter	Description
path	Filesystem path to the texture asset.