Struct Loader

• Defined in File asset-loader.h

Inheritance Relationships

Base Type

• public CE::State::Singleton< Loader > (Template Class Singleton)

Struct Documentation

struct Loader : public CE::State::Singleton<Loader>

Declaration: final

One immutable root; owned loaders can share the one supported cache domain.

CPU preparation changes no caches and can run on workers. Upload/publication must be serialized on the active provider’s loading owner. Relative roots are interpreted against the working directory at preparation time. Automatic discovery uses normalized absolute file/image keys. This loader does not create a separate provider domain or atomic hot reload.

Public Functions

inline explicit Loader(const std::filesystem::path &root_path)

Configure an owned loader without discovering files or uploading resources.

Parameters:

root_path – Copied, lexically normalized asset root; relative roots resolve against the working directory when preparation or discovery runs.

Prepared prepare() const

Declaration: [[nodiscard]]

Rescan the root, decode its PNG images and validate graphics definitions.

CPU-only preparation can run on a worker. Discovery, decoding or validation failure leaves caches and this loader’s retained metadata unchanged.

Returns:

Owned definitions, shader sources, pixels and file discovery for upload().

Prepared prepare_graphics(const std::vector<std::filesystem::path> &indexes) const

Declaration: [[nodiscard]]

Prepare selected graphics indexes against full-root discovery.

Decode only referenced images; a shader-only selection decodes none. Empty selections and discovery, decoding or validation failures reject preparation without publishing cache entries or retained metadata.

Parameters:

indexes – Nonempty index selection; relative paths resolve against the asset root.

Returns:

Owned data for upload(), prepared without a provider or backend calls.

void upload(Prepared prepared, CE::Rendering::Resources::Provider &provider, bool replace_shaders = false)

Consumes one prepared value without reopening its image files.

Existing keys remain; each successful new entry can become visible immediately. Failure can leave any completed cache entries, including all entries if final metadata allocation fails. manifests() retains the previous snapshot. Retry by preparing again or by keeping a copy before moving the input; a consumed failed value is not returned. Retry preserves existing keys, not replacement of their contents. Pending platform requests may cancel before execution; once executing, upload has no rollback/cancellation API. Explicit shader replacement leaves image/grid keys intact. Earlier successful replacements remain visible if a later candidate fails.

Parameters:

• prepared – Owned batch consumed by value; retain a copy when retry needs it.

• provider – Active resource backend, used on its loading owner/current context.

• replace_shaders – Whether existing shader programs/materials may be replaced.

void load_assets(CE::Rendering::Resources::Provider &provider)

Prepare the complete root and synchronously upload it without shader replacement.

Preparation failures leave caches unchanged; upload failures retain the partial-publication behavior of upload().

Parameters:

provider – Active backend, used on its loading owner/current context.

void register_files() const

Discover and register unmanaged paths for manual asset loading.

No JSON parsing, image decoding or provider is required. Filesystem and allocation failures propagate; PNG images remain outside the untyped registry.

void publish_events_to(CE::Events::EventBus::Publisher publisher)

Select a weak publication route on the loading owner while idle and with no pending outcomes.

Standalone use remains independent of Context. Empty routing disables observations.

void publish_pending_events() noexcept

Drain a bounded snapshot on the loading owner, outside loader/cache locks.

upload() invokes this automatically after settling. Callback-created outcomes wait for the next upload or explicit drain; destruction never drains. At most 64 outcomes are pending; staging/overflow failures use independent emergency reporting and preserve the direct upload result.

inline std::uint64_t source_id() const noexcept

Declaration: [[nodiscard]]

Checked identity for filtering this loader’s observations on a shared bus.

UploadStats diagnostics() const

Declaration: [[nodiscard]]

Observe the last upload attempt, including partial publication.

The snapshot is synchronized, but provides no upload/rollback ordering guarantee beyond the loading-owner contract.

Returns:

Copied counters and completion status for the last attempt.

inline std::shared_ptr<const std::vector<CE::Assets::Manifests::Graphics>> manifests() const

Declaration: [[nodiscard]]

Returns:

Owned snapshot of the last successfully submitted asset definitions. Readers retain it across later uploads and loader destruction. This is metadata, not an atomic snapshot of the global caches.

inline std::shared_ptr<const std::vector<CE::Assets::Shaders::Manifest>> shader_manifests() const

Declaration: [[nodiscard]]

Returns:

Owned snapshot of the last successfully submitted shader definitions, with the same lifetime and cache-observation limits as manifests().

Public Static Functions

static Loader &get(const std::filesystem::path &root_path)

Configure or retrieve the legacy singleton on the loading owner before producers start.

A different normalized root is rejected. Prefer owned Loader instances for separate roots/lifetimes; they still share the supported cache domain.

Parameters:

root_path – Root to initialize, or match against the existing singleton.

Returns:

Borrowed process-lifetime loader with that root.

static Loader &get()

Retrieve the configured legacy singleton without initializing it.

Returns:

Borrowed process-lifetime loader; fails if initialization is unpublished.