LoadHandle

Handle representing the result of an asynchronous load request.

LoadHandle is returned immediately when an asynchronous load is initiated and represents the eventual outcome of that request. It can be polled to retrieve either a loaded value or an error message once the loader finishes and the result is committed.

Ownership is transferred out of the handle when the value is successfully taken. Handles are single-consumption: once a value or error is retrieved the internal state is cleared and subsequent calls return no result. This makes the handoff explicit at the call site and avoids accidental double-ownership.

Typical usage is to load in Node::OnAttached and poll for completion in Node::OnUpdate.

struct MyNode : public vglx::Node {
  vglx::TextureLoadHandle handle_;

  auto OnAttached(SharedContextPointer context) -> void override {
    handle_ = context->texture_loader->LoadAsync("assets/albedo.tex");
  }

  auto OnUpdate([[maybe_unused]] float delta) -> void override {
    if (auto texture = handle_.TryTake()) {
      // use *texture
    }
  }
};

To learn more about loaders see the Importing Assets Guide.

Types

MeshLoadHandle typedef

Handle type returned by asynchronous mesh load requests.

Represents the eventual result of MeshLoader::LoadAsync.

using MeshLoadHandle = LoadHandle<std::unique_ptr<Node>>

TextureLoadHandle typedef

Handle type returned by asynchronous texture load requests.

Represents the eventual result of TextureLoader::LoadAsync.

using TextureLoadHandle = LoadHandle<std::shared_ptr<Texture2D>>

Functions

TryError() std::optional<std::string>

Attempts to retrieve an error produced during loading.

If the asset has finished loading and failed this returns the error message and clears it from the handle. If the asset is not ready or no error occurred an empty optional is returned.

Use this method only if you want to explicitly handle load failures. Otherwise, errors are reported through the logger.

std::optional<std::string> LoadHandle<T>::TryError();

TryTake() std::optional<T>

Attempts to take ownership of the loaded asset.

If the asset has finished loading successfully, this transfers ownership of the value out of the handle and clears the internal state. If the asset is not ready or failed to load an empty optional is returned.

std::optional<T> LoadHandle<T>::TryTake();