Resource::IResourceManager class
#include <Spore ModAPI/Spore/Resource/IResourceManager.h>

IResourceManager is a singleton class used to access resources in Spore's file system.

The main function of the ResourceManager is to access to the resources stored in Spore's files. The manager contains multiple IResourceFactory instances, which are assigned to certain typeIDs. When trying to get a resource, those factories will be used to generate an instance of the correct class according to the resource type. Therefore, the ResourceManager can only be used for those types that have factories assigned to them.

The manager distinguishes two different kinds of type IDs: the resource type and the record type. Record types are the type IDs you find in files, such as .rw4, .prop, etc. Resource types are used to differentiate between different kinds of ResourceObject; for example, .raster and .rw4 are assigned to the same resource type.

You can assign your own factories or delete existing ones, but if that is not an option, ResourceManager provides a method to find the Database that contains a certain file. This way, ResourceManager can always be used to get files, either via the GetResource method or the FindDatabase one. The databases are stored in the resource manager according to their priority.

The manager contains a list of ICache instances that is used to avoid repeteadly creating new instances of a resource that already exists. The IResourceManager::GetPrivateResource() method can be used instead of IResourceManager::GetResource() to forcibly create a new resource even if it's already in the cache.

This manager provides additional functionality relating files. It keeps a map of ResourceKey - eastl::string16 values, which can be used to store the original name of certain resources. For example:

ResourceManager.SetKeyName(ResourceKey(0x00000000, 0x40212002, 0x0469A3F7), u"ShaderFragments!LowQuality.graphics");
// Now you can access this file using the name we assigned instead of the original name, which had special IDs
ResourceKey dstKey = ResourceManager.GetKeyFromName(u"ShaderFragments!LowQuality.graphics");

Additionally, the manager also keeps a map of typeID - eastl::string16 values, which allows to map extension eastl::strings to certain typeIDs. For example:

// for example, we could have the mappings on a file and load it on startup
ResourceManager.SetTypename(0x2F7D0004, u"png");
// now, if we try to use the .png extension, we will receive the correct typeID, instead of using the FNV hash of "png" (which is not 0x2F7D0004)
ResourceKey dstKey = ResourceManager.GetFileName(u"MyImages!EditorUIFrame.png");

Derived classes

class cResourceManager: The implementation of IResourceManager; this should only be used for extending and detouring.

Public types

using ChangeNotificationCallback_t = void(*)(Database*, const ResourceKey&, void*)
using DatabaseList = eastl::list<Database*, ICoreAllocatorAdapter>

Public static functions

static auto Get() -> IResourceManager*: Gets the active resource manager.

Constructors, destructors, conversion operators

~IResourceManager() virtual

Public functions

auto Initialize() -> bool pure virtual
auto Dispose() -> bool pure virtual
auto GetResource(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, void* factoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) -> bool pure virtual: Gets the resource that has the given ResourceKey name.
auto GetResourceAsync(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, IAsyncRequestPtr* ppDstAsync = nullptr, void* arg_C = nullptr, void* factoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) -> bool pure virtual: Similar usage to ResourceManager::GetResource(), but this method returns inmediately and loads the resource asynchronously.
auto GetLoadedResource(const ResourceKey& name, ResourceObjectPtr* pDst) -> bool pure virtual: Gets a resource from the resource cache in this manager.
auto ReloadResource(const ResourceKey& name, ResourceObject* pResource, void* pFactoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr) -> bool pure virtual
auto GetPrivateResource(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, void* pFactoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) -> bool pure virtual: Similar usage to ResourceManager::GetResource .
auto WriteResource(const ResourceObject* pResource, void* pFactoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pNameKey = nullptr) -> bool pure virtual: Writes the given resource to a package file.
auto SetTypeMapping(uint32_t resourceType, uint32_t* recordTypes, size_t count) -> void pure virtual: Maps all the record types to the given resource type.
auto GetRecordTypesFromResourceType(eastl::vector<uint32_t>& dst, uint32_t resourceType) -> size_t pure virtual: Gets all the record type IDs mapped to the given.
auto GetTypeMapping(uint32_t recordType) -> uint32_t pure virtual: Gets the general resource type ID that the given record type is assigned to.
auto FindRecord(const ResourceKey& nameKey, ResourceKey* pDst = nullptr, Database* pDatabase = nullptr) -> Database* pure virtual: Finds the real record key of a given resource, as well as the database that contaiend it.
auto GetResourceKeyList(eastl::vector<ResourceKey>& pDst, IKeyFilter* filter) -> size_t pure virtual: Gets a list of the keys of all the loaded resources in this manager.
auto GetRecordKeyList(eastl::vector<ResourceKey>& dst, IKeyFilter* filter, eastl::vector<Database*>* pDstDatabases = nullptr) -> size_t pure virtual: Gets all the file keys in this manager that match the criteria specified by the given request.
auto GetRecordKeyList2(eastl::vector<ResourceKey>& dst, IKeyFilter* filter, bool cached) -> size_t pure virtual
auto RegisterChangeNotification(bool, ChangeNotificationCallback_t callback, void* data, IKeyFilter* filter, int) -> bool pure virtual
auto RegisterFactory(bool add, IResourceFactory* pFactory, uint32_t arg_8) -> bool pure virtual: Adds or removes the given IResourceFactory to this manager.
auto FindFactory(uint32_t resourceTypeID, uint32_t recordTypeID = ResourceKey::kWildcardID) -> IResourceFactory* pure virtual: Returns the IResourceFactory that belongs to the specified typeID.
auto GetFactoryList(eastl::list<IResourceFactory*>& dst, uint32_t resourceTypeID = ResourceKey::kWildcardID) -> size_t pure virtual: Puts all the IResourceFactory instances that are assigned to the specified resourceTypeID into the given list.
auto RegisterDatabase(bool add, Database* pDatabase, int priority = 1000) -> bool pure virtual: Adds/removes the given DatabasePackedFile to this manager, using the priority specified.
auto IsDatabaseRegistered(Database* pDatabase, int* dstPriority = nullptr) -> bool pure virtual: Checks if a database is already registered in this manager, and optionally gets its priority.
auto FindDatabase(const ResourceKey& name) -> Database* pure virtual: Returns the first database that contains the given file.
auto GetDatabaseList(DatabaseList& dst, const ResourceKey* pFileKey = nullptr) -> size_t pure virtual: Gets all the Database objects in this manager and puts it to the dst list.
auto DoDatabaseChanged(Database* pDatabase, eastl::vector<ResourceKey>& keys) -> void pure virtual: Calls the registered database change listeners that were added with RegisterChangeNotification()
auto RegisterCache(bool add, ICache* pCache, int) -> bool pure virtual
auto FindCache(const ResourceKey& name) -> ICache* pure virtual: Returns the cache that contains a resource with this name (if any).
auto CacheResource(ResourceObject* pResource, bool) -> bool pure virtual
auto FlushCache(ICache* pCache, IKeyFilter* pFilter = nullptr) -> void pure virtual: Removes certain (or all) elements from a cache.
auto GetCacheList(eastl::list<ICache*>& dst) -> size_t pure virtual: Puts all the resource caches used in this manager into the given list.
auto GetKeyFromName(const char16_t* fileName, uint32_t defaultTypeID = 0, uint32_t defaultGroupID = 0) -> ResourceKey pure virtual: Adds this file name to the list, so that it can be accessed using the corresponding ResourceKey.
auto GetNameFromKey(const ResourceKey& key, eastl::string16& dst) -> void pure virtual: Gets the file name that corresponds to the specified ResourceKey.
auto SetKeyName(const ResourceKey& key, const char16_t* fileName) -> bool pure virtual: Maps the given ResourceKey to the file name specified, which is in the format "groupID!instanceID.typeID".
auto ForgetKeyName(const ResourceKey& key) -> bool pure virtual: Removes the file name mapped for the given ResourceKey.
auto GetTypeFromTypename(const char16_t* typeName) -> uint32_t pure virtual: Returns the typeID that has the given extension mapped to it, or 0xFFFFFFFF if no typeID has this extension mapped.
auto GetTypenameFromType(uint32_t typeID) -> const char16_t* pure virtual: Returns the extension that is mapped to the given type ID, or nullptr if there's no mapping.
auto SetTypename(uint32_t typeID, const char16_t* pExtension) -> bool pure virtual: Maps the given typeID to the specified extension string.
auto ResetTypename(uint32_t typeID) -> bool pure virtual: Removes the extension the given typeID it is mapped to.

Function documentation

bool Resource::IResourceManager::GetResource(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, void* factoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) pure virtual

Gets the resource that has the given ResourceKey name.

Parameters
name in	The ResourceKey name to find. If the typeID is mapped in the manager to other alternative typeIDs, all them will be tested.
ppDst out	[Optional] A pointer to a ResourceObject*. It will be assigned with the generated resource.
factoryData in	[Optional] Additional data that is passed to the resource factory, usually null.
pDatabase in	[Optional] The Database where the file will be searched. Use nullptr to search in all available databases.
pFactory in	[Optional] The IResourceFactory used to generate the resource. Use nullptr to use the appropiate factory according to the typeID mapping in this manager.
pCacheName in	[Optional] The ResourceKey name used to search the resource in the cache.
Returns	True if the resource was found or generated, false otherwise.

If the resource is contained in the cache, that will be used. The name will be modified to use the correct types, according to the mappings in this manager. The resource will be seached in all the databases in this manager, unless a specific one is specified. Once the file is found, the correct factory will be used to generate the appropiate resource, unless a specific IResourceFactory is specified.

bool Resource::IResourceManager::GetResourceAsync(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, IAsyncRequestPtr* ppDstAsync = nullptr, void* arg_C = nullptr, void* factoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) pure virtual

Similar usage to ResourceManager::GetResource(), but this method returns inmediately and loads the resource asynchronously.

Parameters
name in
ppDst out
ppDstAsync out
arg_C in
factoryData in
pDatabase in
pFactory in
pCacheName in

bool Resource::IResourceManager::GetLoadedResource(const ResourceKey& name, ResourceObjectPtr* pDst) pure virtual

Gets a resource from the resource cache in this manager.

Parameters
name
pDst
Returns	True if the file was present in the cache, false otherwise.

If it isn't present in the cache, nothing will happen.

bool Resource::IResourceManager::GetPrivateResource(const ResourceKey& name, ResourceObjectPtr* ppDst = nullptr, void* pFactoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pCacheName = nullptr) pure virtual

Similar usage to ResourceManager::GetResource .

Parameters
name in	The ResourceKey name to find. If the typeID is mapped in the manager to other alternative typeIDs, all them will be tested.
ppDst out	[Optional] A pointer to a ResourceObject*. It will be assigned with the generated resource.
pFactoryData
pDatabase in	[Optional] The Database where the file will be searched. Use nullptr to search in all available databases.
pFactory in	[Optional] The IResourceFactory used to generate the resource. Use nullptr to use the appropiate factory according to the typeID mapping in this manager.
pCacheName in	[Optional] The ResourceKey name used to search the resource in the cache.
Returns	True if the resource was successfully generated and read, false otherwise.

This method does not check the cache, however, therefore always generating a new resource.

bool Resource::IResourceManager::WriteResource(const ResourceObject* pResource, void* pFactoryData = nullptr, Database* pDatabase = nullptr, IResourceFactory* pFactory = nullptr, const ResourceKey* pNameKey = nullptr) pure virtual

Writes the given resource to a package file.

Returns	True if the resource was successfuly written, false otherwise.

If the database is specified in this method, a new file will always be created on it even if it does not exist yet; however, if no database is specified, the resource will be written in the first database that contains a file with the given name. If there is a problem while writing the resource, the file on the database will be deleted.

void Resource::IResourceManager::SetTypeMapping(uint32_t resourceType, uint32_t* recordTypes, size_t count) pure virtual

Maps all the record types to the given resource type.

Parameters
resourceType
recordTypes
count	Number of entries in `recordTypes`

size_t Resource::IResourceManager::GetRecordTypesFromResourceType(eastl::vector<uint32_t>& dst, uint32_t resourceType) pure virtual

Gets all the record type IDs mapped to the given.

Parameters
dst out
resourceType
Returns	The number of record types mapped.

uint32_t Resource::IResourceManager::GetTypeMapping(uint32_t recordType) pure virtual

Gets the general resource type ID that the given record type is assigned to.

Parameters
recordType
Returns

Record types are the ones found in files, whereas resource types are for ResourceObject (for example, .raster and .rw4 are different record types but they all map to the same resource type).

Database* Resource::IResourceManager::FindRecord(const ResourceKey& nameKey, ResourceKey* pDst = nullptr, Database* pDatabase = nullptr) pure virtual

Finds the real record key of a given resource, as well as the database that contaiend it.

Parameters
nameKey in	The original ResourceKey of the file.
pDst out	[Optional] The ResourceKey where the real key of the file will be put, with the correct typeID.
pDatabase in	[Optional] The database where the file will be searched. If not specified, it will be searched in all available databases.
Returns	The database that contains this file, or null if it is not in any database.

size_t Resource::IResourceManager::GetResourceKeyList(eastl::vector<ResourceKey>& pDst, IKeyFilter* filter) pure virtual

Gets a list of the keys of all the loaded resources in this manager.

Parameters
pDst out
filter

size_t Resource::IResourceManager::GetRecordKeyList(eastl::vector<ResourceKey>& dst, IKeyFilter* filter, eastl::vector<Database> pDstDatabases = nullptr) pure virtual

Gets all the file keys in this manager that match the criteria specified by the given request.

Parameters
dst out	The vector where all the files ResourceKey names will be added.
filter in	The criteria that the files must match in order to be added to the vector.
pDstDatabases out	[Optional] A vector where all the Database objects that contained the files will be added.
Returns	The number of file keys that matched the criteria.

If request is nullptr, all the files in the manager will be given.

bool Resource::IResourceManager::RegisterFactory(bool add, IResourceFactory* pFactory, uint32_t arg_8) pure virtual

Adds or removes the given IResourceFactory to this manager.

Parameters
add	If true, pFactory will be added to the manager; if false, it will be removed from the manager.
pFactory	The IResourceFactory to add to/remove from this manager.
arg_8	Unknown usage, usually 0.
Returns	True if the factory was successfully added/removed, false otherwise.

Resource factories are used to generate resource objects depending on their type. The factory will be assigned to the types returned by IResourceFactory::GetSupportedTypes.

IResourceFactory* Resource::IResourceManager::FindFactory(uint32_t resourceTypeID, uint32_t recordTypeID = ResourceKey::kWildcardID) pure virtual

Returns the IResourceFactory that belongs to the specified typeID.

Parameters
resourceTypeID
recordTypeID
Returns

If recordTypeID is ResourceKey::kWildcardID, the first factory assigned to the resourceTypeID will be returned; Otherwise, IResourceFactory::CanConvert() will be called on every factory using the types provided here, and the first one that returns true will be returned.

size_t Resource::IResourceManager::GetFactoryList(eastl::list<IResourceFactory*>& dst, uint32_t resourceTypeID = ResourceKey::kWildcardID) pure virtual

Puts all the IResourceFactory instances that are assigned to the specified resourceTypeID into the given list.

Parameters
dst out
resourceTypeID in
Returns	The number of factories found.

If resourceTypeID is ResourceKey::kWildcardID, all the factories in this manager will be added.

bool Resource::IResourceManager::RegisterDatabase(bool add, Database* pDatabase, int priority = 1000) pure virtual

Adds/removes the given DatabasePackedFile to this manager, using the priority specified.

Parameters
add	If true, the database is added to the manager; if false, the database is removed from the manager
pDatabase	The database to add/remove
priority	The priority of this database, this determines in which order files are searched in databases
Returns	Whether the database was registered or not.

The priority of a database is used when getting files from the resource manager; since a certain file name can be contained in multiple packages, the one with the most priority will be chosen. The usage of the first argument is unknown, but it is usually 'true'.

bool Resource::IResourceManager::IsDatabaseRegistered(Database* pDatabase, int* dstPriority = nullptr) pure virtual

Checks if a database is already registered in this manager, and optionally gets its priority.

Parameters
pDatabase in	The database
dstPriority out	[Optional] A pointer to an integer that will contain the priority. This parameter can be nullptr.
Returns	True if the manager contained the database, false otherwise.

Database* Resource::IResourceManager::FindDatabase(const ResourceKey& name) pure virtual

Returns the first database that contains the given file.

Parameters
name
Returns	name

Databases are searched in descending order of priority.

size_t Resource::IResourceManager::GetDatabaseList(DatabaseList& dst, const ResourceKey* pFileKey = nullptr) pure virtual

Gets all the Database objects in this manager and puts it to the dst list.

Parameters
dst out	A list of Database pointers where the databases will be added.
pFileKey in	[Optional] A ResourceKey that the returned databases must contain, or nullptr if no filtering is wanted.
Returns	The number of databases added to the list.

Optionally, a ResourceKey can be specified; in that case, only the databases that contain that file will be added.

void Resource::IResourceManager::DoDatabaseChanged(Database* pDatabase, eastl::vector<ResourceKey>& keys) pure virtual

Calls the registered database change listeners that were added with RegisterChangeNotification()

Parameters
pDatabase
keys

ICache* Resource::IResourceManager::FindCache(const ResourceKey& name) pure virtual

Returns the cache that contains a resource with this name (if any).

Parameters
name

void Resource::IResourceManager::FlushCache(ICache* pCache, IKeyFilter* pFilter = nullptr) pure virtual

Removes certain (or all) elements from a cache.

Parameters
pCache
pFilter

size_t Resource::IResourceManager::GetCacheList(eastl::list<ICache*>& dst) pure virtual

Puts all the resource caches used in this manager into the given list.

Returns	The number of caches.

ResourceKey Resource::IResourceManager::GetKeyFromName(const char16_t* fileName, uint32_t defaultTypeID = 0, uint32_t defaultGroupID = 0) pure virtual

Adds this file name to the list, so that it can be accessed using the corresponding ResourceKey.

Parameters
fileName
defaultTypeID	[Optional] Type ID used if the file name does not have an extension
defaultGroupID	[Optional] Group ID used if the file name does not have a folder
Returns	True if the file name was mapped successfully, false otherwise. Returns the resource key that maps to the given file name.

The file name is in the format "groupID!instanceID.typeID", and it will be mapped to the key generated using the ResourceKey::Parse function.

void Resource::IResourceManager::GetNameFromKey(const ResourceKey& key, eastl::string16& dst) pure virtual

Gets the file name that corresponds to the specified ResourceKey.

Parameters
key in	The ResourceKey that will be represented as a eastl::string.
dst out	A string16 that will contain the resulting text.

The file name will be in the format "groupID!instanceID.typeID". The file name can be parsed to a key again using the ResourceKey::Parse() method. A file name wil be generated even if it's not mapped; when that happens, the ResourceKey members are displayed in hexadecimal format.

bool Resource::IResourceManager::SetKeyName(const ResourceKey& key, const char16_t* fileName) pure virtual

Maps the given ResourceKey to the file name specified, which is in the format "groupID!instanceID.typeID".

Parameters
key
fileName
Returns	True if it was successfully mapped.

The file name can be parsed to a key again using the ResourceKey::Parse method.

bool Resource::IResourceManager::ForgetKeyName(const ResourceKey& key) pure virtual

Removes the file name mapped for the given ResourceKey.

Parameters
key
Returns	True if the file name mapping was removed, false if it did not exist.