#include <InstanceDatabase.h>
Inherits AZ::Data::InstanceDatabaseInterface.
Public Member Functions | |
AZ_CLASS_ALLOCATOR (InstanceDatabase, AZ::SystemAllocator) | |
Data::Instance< Type > | Find (const InstanceId &id) const |
Data::Instance< Type > | FindOrCreate (const InstanceId &id, const Asset< AssetData > &asset, const AZStd::any *param=nullptr) |
Data::Instance< Type > | FindOrCreate (const Asset< AssetData > &asset, const AZStd::any *param=nullptr) |
Calls the above FindOrCreate using an InstanceId created from the asset. | |
Data::Instance< Type > | Create (const Asset< AssetData > &asset, const AZStd::any *param=nullptr) |
Calls FindOrCreate using a random InstanceId. | |
void | TEMPOrphan (const InstanceId &id) |
void | ForEach (AZStd::function< void(Type &)> callback) |
void | ForEach (AZStd::function< void(const Type &)> callback) const |
Static Public Member Functions | |
static void | Create (const AssetType &assetType, const InstanceHandler< Type > &handler, bool checkAssetIds=true) |
static void | Destroy () |
static bool | IsReady () |
static InstanceDatabase & | Instance () |
Additional Inherited Members | |
virtual void | ReleaseInstance (InstanceData *instance, const InstanceId &instanceId)=0 |
This class is a simple database of typed instances. An 'instance' in this context is any class which inherits from InstanceData, is created at runtime from an asset, and has a unique instance id. The purpose of this system is to control de-duplication of instances at runtime, and to associate instance types with their originating asset types.
The database has itself singleton access, but it should be owned by the corresponding system (which is in charge of creation / destruction of the database). To use the database, you may instantiate it using one of the following approaches: 1) Instantiate one InstanceDatabase for each concrente instance class. Use this approach if all concrete instance classes are known at compile time. 2) Instantiate one InstanceDatabase for a known instance base class, and then register multiple InstanceHandlers for each concrete instance class. Use this approach if only the instance base class is known at compile time and the concrete instance classes are only known at runtime. For example, Atom provides abstract StreamingImageControllerAsset and StreamingImageController classes, and a game-specific gem can provide custom implementations by adding a handler to InstanceDatabase<StreamingImageController>.
The database allows you to find an instance from its corresponding InstanceId. Alternatively, you can 'find or create' an instance, which will create the instance if it doesn't already exist, or return you the existing instance. The 'find or create' operation takes an asset as input. Instances are designed to be trivially created from their parent asset.
The database does NOT own instances. Ownership is returned to you in the form of a smart pointer (Data::Instance<>). This is the same ownership model used by the asset manager.
The system is thread-safe. You can create / destroy instances from any thread, however Instances should not be copied between threads, they should always be retrieved from the InstanceDatabase directly.
Example Usage (using instantiation approach #1 described above):
|
static |
Create the InstanceDatabase with a single handler. Use this function when creating an InstanceDatabase that will handle concrete classes of Type.
assetType | - All instances will be based on subclasses of this asset type. |
handler | - An InstanceHandler that creates instances of assetType assets. |
checkAssetIds | - If true, it will be validated that "instance->m_assetId == asset.GetId()" |
Data::Instance< Type > AZ::Data::InstanceDatabase< Type >::Find | ( | const InstanceId & | id | ) | const |
Attempts to find an instance associated with the provided id. If the instance exists, it is returned. If no instance is found, nullptr is returned. It is safe to call this from multiple threads.
id | The id used to find an instance in the database. |
Data::Instance< Type > AZ::Data::InstanceDatabase< Type >::FindOrCreate | ( | const InstanceId & | id, |
const Asset< AssetData > & | asset, | ||
const AZStd::any * | param = nullptr |
||
) |
Attempts to find an instance associated with the provided id. If it exists, it is returned. Otherwise, it is created using the provided asset data and then returned. It is safe to call this method from multiple threads, even with the same id. The call is synchronous and other threads will block until creation is complete.
PERFORMANCE NOTE: If the asset data is not loaded and creation is required, the system will perform a BLOCKING load on the asset. If this behavior is not desired, the user should either ensure the asset is loaded prior to calling this method, or call Find instead.
id | The id used to find or create an instance in the database. |
asset | The asset used to initialize the instance, if it does NOT already exist. If the instance exists, the asset id is checked against the existing instance. If validation is enabled, the system will error if the created asset id does not match the provided asset id. It is required that you consistently provide the same asset when acquiring an instance. |
void AZ::Data::InstanceDatabase< Type >::ForEach | ( | AZStd::function< void(Type &)> | callback | ) |
A helper function to visit every instance in the database and calls the provided callback method. Note: this function can be slow depending on how many instances in the database
void AZ::Data::InstanceDatabase< Type >::TEMPOrphan | ( | const InstanceId & | id | ) |
Removes the instance data from the database. Does not release it. References to existing instances will remain valid, but new calls to Create/FindOrCreate will create a new instance This function is temporary, to provide functionality needed for Model hot-reloading, but will be removed once the Model class does not need it anymore.
id | The id of the instance to remove |