raisin::RayraiGlobalAsset

class · #include <rayrai/RayraiGlobalAsset.hpp>

A caching asset manager for 3D models and primitive meshes.

This class loads models on demand and keeps them in memory as long as they are being used. Once all references to a model are released, its memory can be reclaimed. It also owns reusable meshes for primitives such as cubes, spheres, cylinders, and capsules.

Returned mesh lists are shared: every caller that requests the same asset gets the same std::shared_ptr, so mutating a mesh's material affects all users. Not thread-safe; use it from the thread that owns the GL context.

Nested classes

• struct MeshLodChain — Internal: cached automatic-LOD chain shared by Visuals of the same source mesh.
• struct SharedGpuAssetStats — Counters of the process-wide shared GPU-asset cache (see sharedGpuAssetStats()).

Constructors & destructor

RayraiGlobalAsset

RayraiGlobalAsset()

Construct the asset cache and generate primitive meshes.

Requires a current OpenGL context (primitive meshes are uploaded here, or reused from another context in the same share group).

~RayraiGlobalAsset

~RayraiGlobalAsset()

Destroy the asset cache.

Public member functions

getMeshes

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getMeshes(const std::string &name)

Retrieves a model's meshes by its asset name (usually file path).

Assets are keyed by canonical path, so different spellings of the same file share one mesh list. With async loading enabled (the default; USD files always load synchronously) a new file returns an empty list at once that is filled in place by a later pollAsyncLoads(); if that import fails the list stays empty. The cache holds only weak references. Requires a current GL context for synchronous loads.

Parameters

Parameter	Description
name	The unique identifier for the asset, typically the file path.

Returns Shared mesh list (possibly still empty while loading), or nullptr if the path does not exist or a synchronous load fails.

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getMeshes(
    const std::string &name,
    std::string *canonicalKeyOut)

Retrieves meshes and returns the canonical cache key used for the lookup.

Parameters

Parameter	Description
name	The unique identifier for the asset, typically the file path.
canonicalKeyOut	Optional output for the canonical mesh key ("" if the path cannot be resolved).

Returns Same as getMeshes(const std::string&).

findLoadedMeshes

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> findLoadedMeshes(const std::string &name) const

The meshes of a model file this cache has already read, without reading it.

Parameters

Parameter	Description
name	File path, as passed to getMeshes().

Returns The cached mesh list (possibly still empty while an asynchronous read runs), or nullptr when the file was not read or nothing holds it any more.

canonicalMeshKey

std::string canonicalMeshKey(const std::string &path) const

Resolve a mesh path to the canonical key used by getMeshes() / the LOD cache.

Parameters

Parameter	Description
path	File path; results are memoized per input string.

Returns Canonical absolute path, or "" if the path cannot be canonicalized (does not exist, etc.).

getCachedMeshLods

std::shared_ptr<MeshLodChain> getCachedMeshLods(const std::string &canonicalKey) const

Look up a cached automatic-LOD chain.

Parameters

Parameter	Description
canonicalKey	Key from canonicalMeshKey().

Returns The chain, or nullptr on miss or when it has expired.

cacheMeshLods

void cacheMeshLods(
    const std::string &canonicalKey,
    const std::shared_ptr<MeshLodChain> &chain)

Register an automatic-LOD chain for a canonical source-mesh key. The cache holds weak references, so the chain stays alive only while at least one caller (typically a Visuals) keeps the returned shared_ptr.

Parameters

Parameter	Description
canonicalKey	Key from canonicalMeshKey(); empty keys are ignored.
chain	Chain to register; null is ignored.

getCachedMeshPreprocessMetadata

std::shared_ptr<MeshPreprocessMetadata> getCachedMeshPreprocessMetadata(const std::string &canonicalKey) const

Look up file-backed mesh preprocessing metadata.

Parameters

Parameter	Description
canonicalKey	Key from canonicalMeshKey().

Returns The metadata, or nullptr on miss or when it has expired.

cacheMeshPreprocessMetadata

void cacheMeshPreprocessMetadata(
    const std::string &canonicalKey,
    const std::shared_ptr<MeshPreprocessMetadata> &metadata)

Register file-backed mesh preprocessing metadata for later visuals.

Held by weak reference, like cacheMeshLods().

Parameters

Parameter	Description
canonicalKey	Key from canonicalMeshKey(); empty keys are ignored.
metadata	Metadata to register; null or invalid metadata is ignored.

pollAsyncLoads

size_t pollAsyncLoads(size_t maxAssets=1)

Advance ready import, worker geometry, and incremental GPU upload stages.

This must be called on the OpenGL/render thread because it creates textures, vertex buffers, and vertex array objects. Each processed asset advances one stage (import, geometry preparation, or one submesh upload) per call. Throws std::logic_error as requireUploadContext() does, before advancing any.

Parameters

Parameter	Description
maxAssets	Maximum number of pending assets advanced in this call.

Returns Number of assets finalized (successfully or not) in this call.

pollAsyncLoadsUntil

size_t pollAsyncLoadsUntil(std::chrono::steady_clock::time_point deadline)

Advance every pending import as far as it can go before deadline.

Like pollAsyncLoads(), on the OpenGL/render thread, but an asset keeps advancing (one submesh upload after another) until it waits for a worker or the deadline passes. Imports whose worker finished go first, so the next worker stages start early. With async loading enabled, an import is finished only once the background decodes of its textures are done, so the render thread decodes no image. At least one ready stage runs per call. Throws std::logic_error as requireUploadContext() does, before advancing any.

Parameters

Parameter	Description
deadline	Time after which no further stage starts.

Returns Number of assets finalized (successfully or not) in this call.

pendingAsyncLoadCount

size_t pendingAsyncLoadCount() const

Returns Number of mesh file imports that have not been finalized yet.

requireUploadContext

void requireUploadContext()

Fails unless the OpenGL context current at construction is current.

The store's textures, vertex arrays and staging regions belong to that context, so its loads advance only there. Elsewhere every pending load first gives its staged copies back to the staging buffer (it stages again, or uploads directly, once polled in its context), and then this throws std::logic_error.

setAsyncMeshLoadingEnabled

void setAsyncMeshLoadingEnabled(bool enabled)

Enable or disable async mesh file import for future getMeshes() calls.

Loads already pending keep loading asynchronously (they wait for the background decodes of their textures and copy through the staging buffer), unless a synchronous getMeshes() waits for one of them or loadPendingSynchronously() is called.

Parameters

Parameter	Description
enabled	True (default) to import on a worker thread; finalize with pollAsyncLoads().

loadPendingSynchronously

void loadPendingSynchronously()

Makes every pending load finish synchronously as it is polled: it no longer waits for the background decodes of its textures or for room in the staging buffer.

RayraiWindow::setAsyncMeshLoadingEnabled(false) calls this before finishing them.

forgetChangedModelFiles

void forgetChangedModelFiles()

Forget every cached model file whose sources changed since it was read.

A model's sources are its file and every file its import read (glTF buffers, an OBJ material library, ...). A changed one makes the next getMeshes() read the model again, even while visuals still hold the meshes read before. RayraiWindow::swapWorld() calls this, so a rebuilt scene shows edited files.

releaseRecentlyReadModels

void releaseRecentlyReadModels()

Release the models read from files since the last call.

A model read from a file stays referenced until this is called, so every visual created in the same frame shares one read, even when a visual keeps only meshes derived from it (instanced foliage keeps its partitioned meshes, and a terrain foliage layer adds one visual per chunk). RayraiWindow calls this at the end of each update(), renderWithExternalCamera(), and depth-only render.

asyncMeshLoadingEnabled

bool asyncMeshLoadingEnabled() const

Returns True when future mesh file imports start on a worker thread.

getCubeMesh

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCubeMesh()

Get a unit cube mesh (side length 1, centred at the origin).

Returns Shared mesh list for a cube.

getCylinderMesh

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCylinderMesh()

Get a unit cylinder mesh (radius 1, height 1 along local Z).

Returns Shared mesh list for a cylinder.

getCapsuleMesh

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getCapsuleMesh()

Get a unit capsule mesh (radius 1, cylinder height 1, along local Z).

Returns Shared mesh list for a capsule.

getSphereMesh

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getSphereMesh()

Get a unit sphere mesh (radius 1).

Returns Shared mesh list for a sphere.

getPlaneMesh

std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> getPlaneMesh()

Get a unit plane mesh (1 x 1, centred on the XY plane).

Returns Shared mesh list for a plane.

setDefaultPrimitivePbrEnabled

void setDefaultPrimitivePbrEnabled(bool enabled)

Enable High/Ultra primitive PBR defaults for shared primitive assets.

Applies configureDefaultPrimitivePbrMaterial() to the cube, sphere, cylinder and capsule meshes (not the plane).

Parameters

Parameter	Description
enabled	True to allow the PBR pass.

defaultPrimitivePbrEnabled

bool defaultPrimitivePbrEnabled() const

Returns True when shared primitive assets currently use the High/Ultra PBR path.

Static member functions

configureDefaultPrimitivePbrMaterial static

static void configureDefaultPrimitivePbrMaterial(
    const std::shared_ptr<std::vector<std::shared_ptr<OpenGLMesh>>> &meshes,
    bool enabled)

Configure the default material used by built-in primitive meshes.

The material remains a PBR material, but enabled controls whether it is allowed to enter the PBR pass or forced through the cheaper simple shader. Overwrites the base color, metallic, roughness and IBL strengths of every mesh in meshes.

Parameters

Parameter	Description
meshes	Mesh list to modify in place; null is ignored.
enabled	False sets Material::forceSimpleShading.

sharedGpuAssetStats static

static SharedGpuAssetStats sharedGpuAssetStats()

Process-wide shared GPU-asset cache diagnostics.

Byte counts cover indexed mesh VBO/EBO allocations. Textures and context-local VAOs are intentionally excluded. Thread-safe.

Returns Snapshot of the counters.

resetSharedGpuAssetStats static

static void resetSharedGpuAssetStats()

Reset the process-wide counters to zero (cached assets are kept). Thread-safe.

setSharedGpuAssetCacheEnabled static

static void setSharedGpuAssetCacheEnabled(bool enabled)

Enable process-wide reuse of immutable mesh buffers across compatible contexts.

Compatibility is probed with OpenGL object visibility, so contexts outside the same share group automatically retain independent uploads. Enabled by default.

Parameters

Parameter	Description
enabled	True to reuse uploads; false makes every lookup upload anew.

sharedGpuAssetCacheEnabled static

static bool sharedGpuAssetCacheEnabled()

Returns True when process-wide mesh-buffer reuse is enabled.