carb::assets::IAssets

struct IAssets

Defines an interface for managing assets that are loaded asynchronously.

Public Functions

template<typename Type> Id loadAsset(carb::datasource::IDataSource *dataSource, carb::datasource::Connection *connection, const char *path, Pool pool, carb::tasking::Trackers trackers = carb::tasking::Trackers{})

Loads an asset of the given type.

This overload uses default LoadParameters.

Events:

Asset.BeginLoading - Sent in the calling thread if asset load starts. Also sent by reloadAnyDirty() or by a background thread if underlying data changes. Parameters:
- Path (const char*) - the path to the asset.
- AssetId (Id) - the asset ID that is loading.
Asset.EndLoading - Sent from a background thread whenever asset load finishes, only for assets that have previously sent a Asset.BeginLoading event.
- Path (const char*) - the path to the asset.
- AssetId (Id) - the asset ID that finished loading.
- Success (bool) - whether the load was successful or not. If true, acquireSnapshot() will acquire the new data for the asset.

See also

CARB_ASSET.

Template Parameters

Type – The type of the asset. A compile error will occur if getAssetType() for the given type does not resolve to a function.

Parameters

dataSource – The data source to load from.
connection – The connection (from the given data source) to load from.
path – The asset path to load.
pool – The pool to load the asset into.
loadParameters – The LoadParameters derived class containing information about how to load the asset.
trackers – (Optional) Trackers that can be queried to see when the asset is done loading.

Returns

A unique Id that identifies this asset. The asset system internally de-duplicates based on path, datasource, connection and LoadParameters, so several different asset Id results may reference the same underlying asset.

template<typename Type> ScopedSnapshot<Type> takeSnapshot(Id assetId)

Takes a snapshot of the asset in a RAII-style object.

Template Parameters: Type – The asset type.
Parameters: assetId – The assetId to take a snapshot of.
Returns: A RAII-style object that manages the snapshot of data for the object.

template<typename Type> void registerAssetType(const LoaderDesc &loaderDesc, const AssetTypeParams &params = AssetTypeParams::getDefault())

Used to register a loader for a specific asset Type.

Template Parameters

Type – The asset type to register.

Parameters

loaderDesc – The loader descriptor.
params – The AssetTypeParams settings for this assetType

template<typename Type> void unregisterAssetType()

Unregisters a specific asset loader.

Note

Typically unregisterAssetType() should be used instead of this lower-level function.

Note

This function will attempt to cancel all loading tasks for this assetType and will wait for all loading tasks to complete.

Warning

All data from any Snapshot objects (i.e. from acquireSnapshot()) is invalid after calling this function. The Snapshot handle remains valid but any attempts to retrieve data from the Snapshot (with getDataFromSnapshot()) will return nullptr. Using a ScopedSnapshot of the given Type after calling this function produces undefined behavior.

Template Parameters: Type – The asset type to unregister.

Public Members

Pool (*createPool)(const char *name)

Creates an asset pool for managing and caching assets together.

Param name: The name of the pool.
Return: The asset pool handle.

void (*destroyPool)(Pool pool)

Destroys an asset pool previously created with createPool().

Param pool: The pool to destroy.

void (*poolStats)(Pool pool, int &totalAssets, int &assetsLoading)

Gets basic statistics about a pool.

Note

The resulting values from this function are transitive and the values may have changed by other threads before the results can be read. They should be used for debugging purposes only.

Param pool: The pool to get stats about.
Param totalAssets: Receives the number of assets in the pool.
Param assetsLoading: Receives the number of assets currently loading.

void (*unloadAsset)(Id assetId)

Unloads an asset previously loaded with loadAsset().

If an asset that is currently loading is unloaded, this will attempt to cancel the load.

Param assetId: The asset to unload.

void (*unloadAssets)(Pool pool)

Unloads all assets from the specified asset pool.

If any assets in the pool are currently loading, this will attempt to cancel the load.

Param pool: The pool to clear the assets from.

void (*yieldForAsset)(Id assetId)

Pauses the current thread or task until the requested asset has finished loading.

Param assetId: The assetId to wait for.

void (*yieldForAssets)(Pool pool)

Pauses the current thread or task until all assets in the given pool have finished loading.

Param pool: The pool containing the assets to wait for.

void (*subscribeToChangeEvent)(Id assetId, OnChangeEventFn onChangeEvent, void *userData)

Registers a callback that will be notified when an asset changes.

The callback occurs after the asset has changed. At the point of the callback, acquireSnapshot() will return the updated data.

Note

Only one callback can be registered for a given assetId. If the given assetId already has a callback registered, it is revoked in favor of this new callback.

Param assetId: The asset to monitor for changes.
Param onChangeEvent: The callback function to be called once the changes are made.
Param userData: The user data associated with the callback.

void (*unsubscribeToChangeEvent)(Id assetId)

Unsubscribes any asset change callbacks for a given asset previously registered with subscribeToChangeEvent().

When this function returns, it is guaranteed that the previously registered onChangeEvent function is not currently being called from another thread, and will not be called again.

Param assetId: The assetId to remove subscriptions for.

Snapshot (*acquireSnapshot)(Id assetId, const Type &assetType, Reason &reason)

Acquires a Snapshot of the asset of the given type.

If an asset changes (i.e. a change event was issued for the given assetId), existing snapshots are not updated; you will have to release existing snapshots and acquire a new snapshot to get the updated data.

Note

It is the caller’s responsibility to release the snapshot via releaseSnapshot() when finished with it.

Param assetId: The asset to take a snapshot of.
Param assetType: The asset type being requested.
Param reason: The reason the snapshot could, or couldn’t be taken. While the snapshot is loading, it will return Reason::eLoading; any other value returned means the snapshot has finished loading. It is recommended to use carb::tasking::Trackers with loadAsset() instead of polling this function until Reason::eLoading is no longer returned.
Return: The snapshot handle for the asset at the present time.

void (*releaseSnapshot)(Snapshot snapshot)

Releases a snapshot of an asset previously returned by acquireSnapshot().

Param snapshot: The snapshot to release.

void *(*getDataFromSnapshot)(Snapshot snapshot)

Gets the underlying data for the asset based on a snapshot.

Param snapshot: The snapshot of the asset to get the data from.
Return: The raw data of the asset at the snapshot. If the asset’s Type has been unregistered then nullptr is returned.

void (*reloadAnyDirty)(Type assetType)

Forces all dirty (that is, assets with changed data) assets of a given Type to reload.

This function is only necessary for registered types where AssetTypeParams::autoReload is set to false.

Param assetType: The Type of asset to request a reload for.

void (*registerAssetTypeEx)(const Type &assetType, const LoaderDesc &desc, const AssetTypeParams &params)

Used to register a loader for a specific asset Type.

Warning

Typically registerAssetType() should be used instead of this lower-level function.

Param assetType: The asset type to register.
Param desc: The loader descriptor.
Param params: The AssetTypeParams settings for this assetType

void (*unregisterAssetTypeEx)(const Type &assetType)

Unregisters a specific asset loader.

Note

Typically unregisterAssetType() should be used instead of this lower-level function.

Note

This function will attempt to cancel all loading tasks for this assetType and will wait for all loading tasks to complete.

Warning

All data from any Snapshot objects (i.e. from acquireSnapshot()) is invalid after calling this function. The Snapshot handle remains valid but any attempts to retrieve data from the Snapshot (with getDataFromSnapshot()) will return nullptr. Using a ScopedSnapshot of the given Type after calling this function produces undefined behavior.

Param assetType: The asset type to unregister.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.