class `ProjectLibrary`

Inherits: Module<ProjectLibrary>, IProjectLibraryEventNotifier

Project library is the primary location for interacting with all the resources in the current project.

A complete hierarchy of resources is provided which can be interacted with by importing new ones, deleting them, moving, renaming and similar.

Public

Constructors

ProjectLibrary

ProjectLibrary()

Methods

~ProjectLibrary

~ProjectLibrary() noexcept

SaveResourceAs

Result SaveResourceAs(const HResource &resource, const Path &relativePath)

Registers a new resource in the library.

resource: Resource instance to add to the library. A copy of the resource will be saved at the provided path.
relativePath: Path where where to store the resource, relative to the project library imported resources folder.

Returns: Operation result and optional error message if failed.

SaveResource

Result SaveResource(const HResource &resource)

Re-saves an existing resource in the library.

resource: Resource which to re-save. Resource must have been previously saved in the library.

Returns: Operation result and optional error message if failed.

Import

Result Import(const Path &sourceResourcePath, const Path &destinationFolderRelativePath, const SPtr<ImportOptions> &importOptions = nullptr)

Imports a new resource from the provided path.

Destination path must not contain a file or import will fail.

sourceResourcePath: Absolute path to the source resource to import.
destinationFolderRelativePath: Path to the folder where the imported resources will be stored. Relative to the project library imported resources folder.
importOptions: Options used to control the import. Must match the imported file type.

Returns: Operation result and optional error message if failed.

ImportSynchronized

Result ImportSynchronized(const Path &sourceResourcePath, const Path &destinationFolderRelativePath, const SPtr<ImportOptions> &importOptions = nullptr)

Similar to Import(), but also copies the source resource into the project library 'Resources/Source/' folder.

Imported packages will be linked with the source resource.

Performing move, rename, copy or delete operation on such entries will also apply the same operation to the source resource in the 'Resources/Source/' folder. Both the source and imported asset will be placed at the same relative path in 'Resources/Source/' and 'Resources/Imported' folders, respectively. You will not be able to edit, move, rename or delete synchronized sub-resources individually. You will only be able to reimport the entirety of the source resource.

sourceResourcePath: Absolute path to the source resource to import.
destinationFolderRelativePath: Path to the folder where the imported resources will be stored. Relative to the project library imported resources folder.
importOptions: Options used to control the import. Must match the imported file type.

Returns: Operation result and optional error message if failed.

Reimport

Result Reimport(const Path &relativePath, const SPtr<ImportOptions> &importOptions = nullptr)

Re-imports the resource at the provided path.

Source file to reimport from will be looked up from the existing resource meta-data. Note that if the resource was imported using ImportSynchronized(), you should call ReimportSynchronized() instead, otherwise the operation will fail and individual sub-resources cannot be updated when they are synchronized with their source asset.

relativePath: Path where the existing resource is stored, relative to the project library imported resource folder.
importOptions: Import options to import the source resource with. Can be null, in which case previously used import options will be used.

Returns: Operation result and optional error message if failed.

ReimportSynchronized

Result ReimportSynchronized(const Path &relativePath, const SPtr<ImportOptions> &importOptions = nullptr)

Re-imports the synchronized source resource associated with the provided path.

The operation will fail if the resource at the provided path was not imported via ImportSynchronized(). All imported resources from the source resource will be overwritten from the newly imported data, and resources that not longer exist in the source resource will be deleted.

relativePath: Path to the synchronized package entry, relative to the project library imported resource folder.
importOptions: Import options to import the source resource with. Can be null, in which case previously used import options will be used.

Returns: Operation result and optional error message if failed.

Move

Result Move(const Path &sourceRelativePath, const Path &destinationRelativePath)

Moves a file or folder from one location to another.

If the entry is a folder, all the children will be moved as well. If destination already contains an entry with the same name, the move operation will be skipped for that source entry - except if both source and destination is a folder, in which case their contents will be merged.

sourceRelativePath: Path of the file or folder to move. Relative to the project library imported resources folder.
destinationRelativePath: Path to the new location of the source file or folder. Relative to the project library imported resources folder.

Returns: Operation result and optional error message if failed.

Copy

Result Copy(const Path &sourceRelativePath, const Path &destinationRelativePath)

Copies a file or folder from one location to another.

If the entry is a folder, all the children will be copied as well. If destination already contains an entry with the same name, the copy operation will be skipped for that source entry - except if both source and destination is a folder, in which case their contents will be merged.

sourceRelativePath: Path of the file or folder to copy. Relative to the project library imported resources folder.
destinationRelativePath: Path to the location where to place the copied file or folder. Relative to the project library imported resources folder.

Returns: Operation result and optional error message if failed.

Delete

Result Delete(const Path &relativePath)

Deletes a file or a folder at the specified path.

If the entry is a folder, all the children will be deleted as well.

relativePath: Path to the file or folder to delete. relative to the project library imported resources folder.

Returns: Operation result and optional error message if failed.

CreateFolder

Result CreateFolder(const Path &folderRelativePath)

Creates a folder at the specified path.

folderRelativePath: Path to the folder to create, relative to the project library imported resources folder.

Returns: Operation result and optional error message if failed.

SetMetaData

Result SetMetaData(const UUID &resourceId, const SPtr<IReflectable> &metaData)

Associates meta-data with the specified resource.

Meta-data can be anything, but should be kept small.

resourceId: ID of the resource whose meta-data to update.
metaData: Meta-data to set.

SetIncludeInBuild

Result SetIncludeInBuild(const UUID &resourceId, bool includeInBuild)

Updates the include-in-build flag on the specified resource.

When enabled, the resource is guaranteed to be included in the build, even if not referenced by anything. If false, only resources that are referenced by other resources and the default scene list will be included in the build.

resourceId: ID of the resource whose flag to update.
includeInBuild: Value to set.

FindEntry

SPtr<ProjectLibraryEntry> FindEntry(const Path &relativePath) const

Attempts to a find a library entry at the specified path.

relativePath: Path to the entry to search. Relative to the project library imported resources folder.

Returns: Found entry, or null if not found.

FindEntry

SPtr<ProjectLibraryResourceEntry> FindEntry(const UUID &resourceId) const

Attempts to find a library resource entry from the resource ID.

resourceId: ID of the resource to find.

Returns: Found entry, or null if not found.

Search

Vector<SPtr<ProjectLibraryEntry>> Search(const String &pattern) const

Searches the library for a pattern and returns all entries matching it.

pattern: Pattern to search for. Use wildcard * to match any character(s).

Returns: A list of entries matching the pattern.

Search

Vector<SPtr<ProjectLibraryEntry>> Search(const String &pattern, const Vector<u32> &typeIds) const

Searches the library for a pattern, but only among specific resource types.

pattern: Pattern to search for. Use wildcard * to match any character(s).
typeIds: RTTI type IDs of the resource types to limit the search for.

Returns: A list of entries matching the pattern.

Search

Vector<SPtr<ProjectLibraryEntry>> Search(const Path &relativePath, const String &pattern, const Vector<u32> &typeIds, bool recurse) const

Searches a particular folder or package for a pattern, but only among specific resource types.

relativePath: Path to the folder or package to search.
pattern: Pattern to search for. Use wildcard * to match any character(s).
typeIds: RTTI type IDs of the resource types to limit the search for.
recurse: If true, child folders or packages of the current folder will also be searched.

Returns: A list of entries matching the pattern.

GetResourcesIncludedInBuild

Vector<SPtr<ProjectLibraryResourceEntry>> GetResourcesIncludedInBuild() const

Returns a list of all resources with IncludedInBuild property set to true.

Exists

bool Exists(const Path &relativePath) const

Checks if the specified path exists in the library.

relativePath: Path to the entry to look up. Relative to the project library imported resources folder.

Returns: True if found an existing entry, false otherwise.

Exists

bool Exists(const UUID &resourceId) const

Checks if resource with the specified ID exists in the library.

resourceId: ID to the entry to look up.

Returns: True if found an existing entry, false otherwise.

CheckSourceResourceFolderForChanges

void CheckSourceResourceFolderForChanges(const Path &relativePath = Path::kBlank)

Scans the Resources/Source folder for any changes and automatically triggers import, reimport or delete operations depending on the change: - If a source resource file is found that is not present in the database, import operation is triggered - If a source resource file is found that is present in the database, but has a newer timestamp than the imported package, reimport operation is triggered - If an entry is found in the database and its source resource cannot be found, delete operation is triggered

relativePath: Path which to scan, relative to the source resource folder. If empty, entire source resource folder will be checked.

BlockUntilWorkerIdle

void BlockUntilWorkerIdle()

Blocks the calling thread until the worker has completed all operations.

IsImportInProgress

bool IsImportInProgress(const Path &sourceResourcePath) const

Checks is an import operation currently in progress for the specified source resource.

sourceResourcePath: Absolute path to the source resource that is potentially being imported.

Returns: True if import is in progress, false otherwise.

IsImportInProgress

bool IsImportInProgress() const

Returns true if there is any import operation in progress.

GetActiveWorkerOperationCount

u32 GetActiveWorkerOperationCount() const

Returns number of operations that are currently in progress.

SaveLibrary

void SaveLibrary()

Saves all the project library data so it may be restored later, at the default save location in the project folder.

LoadLibrary

void LoadLibrary(const Path &projectFolder)

Loads previously saved project library data from the default save location in the project folder.

Nothing is loaded if it doesn't exist. This must be called before using the project library.

projectFolder: Project folder in which to initialize the library.

UnloadLibrary

void UnloadLibrary()

Clears all library data.

GetProjectFolder

const Path &GetProjectFolder() const

Returns the project folder that the library was initialized with during LoadLibrary call.

Returned path is absolute.

GetImportedResourceFolder

const Path &GetImportedResourceFolder() const

Returns the root folder in which all imported resources are stored in.

Returned path is absolute.

GetSourceResourceFolder

const Path &GetSourceResourceFolder() const

Returns the root folder from which source resources are stored.

Resources in this folder will be automatically imported and kept in sync with their counterparts in the imported resource folder.

CreateOperationContext

ProjectLibraryOperationContext CreateOperationContext()

Creates context used for running project library operations from the currently loaded library.

GetDatabase

const ProjectLibraryDatabase &GetDatabase() const

Returns the database that can be used for searching and manipulating library entries directly.

staticInstance

static T &Instance()

Returns a reference to the module instance.

Module has to have been started up first otherwise an exception will be thrown.

staticInstancePtr

static T *InstancePtr()

Returns a pointer to the module instance.

Module has to have been started up first otherwise an exception will be thrown.

staticShutDown

static void ShutDown()

Shuts down this module and frees any resources it is using.

staticIsStarted

static bool IsStarted()

Query if the module has been started.

Fields

OnEntryAdded

Event<void (const Path &)> OnEntryAdded

Triggered whenever an entry is added to the library.

Path provided is relative to the project library imported resources folder.

OnEntryRemoved

Event<void (const Path &)> OnEntryRemoved

Triggered whenever an entry is removed from the library.

Path provided is relative to the project library imported resources folder.

OnEntryUpdated

Event<void (const Path &)> OnEntryUpdated

Triggered whenever an entry in the library is updated.

Path provided is relative to the project library imported resources folder.

Protected

Methods

~Module<T>

virtual ~Module<T>() = default

OnStartUp

virtual void OnStartUp()

Override if you want your module to be notified once it has been constructed and started.

OnShutDown

virtual void OnShutDown()

Override if you want your module to be notified just before it is deleted.

staticInstanceInternal

static T *&InstanceInternal()

Returns a singleton instance of this module.

staticIsDestroyed

static bool &IsDestroyed()

Checks has the Module been shut down.

staticIsStartedUp

static bool &IsStartedUp()

Checks has the Module been started up.

Private

Methods

NotifyEntryAdded

void NotifyEntryAdded(const Path &relativePath) override

Notifies the event listeners that an entry was added to the library.

relativePath: Path provided is relative to the project library imported resources folder.

NotifyEntryRemoved

void NotifyEntryRemoved(const Path &relativePath) override

Notifies the event listeners that an entry was removed from the library.

relativePath: Path provided is relative to the project library imported resources folder.

NotifyEntryUpdated

void NotifyEntryUpdated(const Path &relativePath) override

Notifies the event listeners that an entry in the library was updated.

relativePath: Path provided is relative to the project library imported resources folder.

DoOnOperationFinished

void DoOnOperationFinished(u32 operationId)

Callback triggered when a worker has finished executing an operation.

Always called on the main thread.

RegisterInProgressImportOperation

void RegisterInProgressImportOperation(u32 operationId, const SPtr<ProjectLibraryImportOperation> &operation)

Registers a new in-progress import operation.

operationId: ID of the operation, as returned by the worker.
operation: Import operation being executed.

GetResourceMetaData

TResult<SPtr<ProjectLibraryResourceMetaData>> GetResourceMetaData(const UUID &resourceId) const

Attempts to retrieve the project library resource meta-data for a resource with the specified ID.

Fields

mDatabase

SPtr<ProjectLibraryDatabase> mDatabase

mWorker

ProjectLibraryWorker mWorker

mProjectFolder

Path mProjectFolder

mImportedResourcesFolder

Path mImportedResourcesFolder

mSourceResourcesFolder

Path mSourceResourcesFolder

mInProgressImportOperationsById

UnorderedMap<u32, SPtr<ProjectLibraryImportOperation>> mInProgressImportOperationsById

mInProgressImportOperationsByPath

UnorderedMap<Path, InProgressImportOperationInformation> mInProgressImportOperationsByPath