class `Package`

Inherits: IReflectable, INonCopyable

Contains Resources in a virtual file system, along with their associated meta-data.

Provides mechanisms to easily (de)serialize the package and load the individual resources within independently.

Public

Constructors

Package

Package(String name, const UUID &id)

Package

Package() = default

Methods

GetPackageName

const String &GetPackageName() const

Determines the name of the package for easier identification.

SetPackageName

void SetPackageName(const String &name)

GetPackageId

const UUID &GetPackageId() const

Globally unique identifier of the package.

SetPackageId

void SetPackageId(const UUID &id)

GetPackageMetaData

const SPtr<PackageMetaData> &GetPackageMetaData() const

User-settable meta-data for the package as a whole.

SetPackageMetaData

void SetPackageMetaData(const SPtr<PackageMetaData> &metaData)

GetResourceCount

u32 GetResourceCount() const

Returns the total number of resources in the package.

IsEmpty

bool IsEmpty() const

Returns true if the package contains no resources.

CreateResourceIdList

Vector<UUID> CreateResourceIdList() const

Creates a list of unique identifiers for all resources within the package.

CreateHierarchy

PackageHierarchy CreateHierarchy() const

Creates an object containing the folder hierarchy of all the resources within the package.

staticBreakCombinedPackagePath

static bool BreakCombinedPackagePath(const Path &combinedPath, Path &outPathToPackage, Path &outPathToResource)

Breaks a combined path to a package and a resource in that package into a separate path pointing to the package, and a separate path for the resource. e.g. 'D:/path/to/package.b3d/path/to/resource' will be broken into 'D:/path/to/package.b3d' and '/path/to/resource'.

Contains

bool Contains(const UUID &id) const

Returns true if the package contains a resource with the specified identifier.

Contains

bool Contains(const Path &path) const

Returns true if the package contains a resource at the specified path.

Paths are case sensitive.

GetResourceMetaData

SPtr<const PackageResourceMetaData> GetResourceMetaData(const UUID &id) const

Returns resource meta-data for resource with the specified identifier.

Returns null if not found.

GetResourceMetaData

SPtr<const PackageResourceMetaData> GetResourceMetaData(const Path &path) const

Returns resource meta-data for resource at the specified path.

Returns null if not found. Paths are case sensitive.

SetResourceMetaData

void SetResourceMetaData(const UUID &id, const SPtr<PackageResourceUserMetaData> &data)

Assigns additional meta-data for the resource with the specified identifier.

SetResourceMetaData

void SetResourceMetaData(const Path &path, const SPtr<PackageResourceUserMetaData> &data)

Assigns additional meta-data for the resource at the specified path.

Paths are case sensitive.

GetResourceLoadState

PackageResourceLoadState GetResourceLoadState(const UUID &id) const

Check if the resource is unloaded, loaded or in progress of being loaded.

GetResourceLoadProgress

float GetResourceLoadProgress(const UUID &id) const

Returns the load progress of the resource.

Only relevant of GetResourceLoadState returns the in-progress state.

AddResource

void AddResource(const Path &path, const HResource &resource)

Registers a new resource with the package at the specified path.

Paths are case sensitive. Empty entries are treated as folders.

AddResource

void AddResource(const Path &path, const SPtr<Resource> &resource)

Registers a new resource with the package at the specified path.

Paths are case sensitive. Empty entries are treated as folders.

RemoveResource

void RemoveResource(const Path &path, bool recursive)

Removes one or multiple resources from the provided path.

Paths are case sensitive. If the path represents a folder and is true, all resources within the folder will be removed.

RemoveResource

void RemoveResource(const UUID &id, bool recursive)

Removes a resource with the specified id.

If the id represents a folder and is true, all resources within the folder will be removed.

SetResource

void SetResource(const SPtr<Resource> &resource, bool markAsDirty = true)

Changes a resource instance associated with a particular ID.

Resource must have already been registered with the package.

resource: Resource to assign. Id of the resource will be used for determining which resource to update.
markAsDirty: If true the resource will be serialized during the next SerializePackage call. Non-dirty resources will just have their source data copied without re-serializing.

SetResourcePath

bool SetResourcePath(const Path &path, const Path &newPath, bool recursive)

Changes the path of one or multiple resources within the package.

path: Existing path to rename. Paths are case sensitive.
newPath: New path to the resource. Paths are case sensitive.
recursive: If the path represents a folder containing multiple resources, all the resources will be renamed.

Returns: True if the path was successfully changed.

SetResourcePath

bool SetResourcePath(const UUID &id, const Path &newPath, bool recursive)

Changes the path of one or multiple resources within the package.

id: Unique id of the resource.
newPath: New path to the resource. Paths are case sensitive.
recursive: If the id represents a folder containing multiple resources, all the resources will be renamed.

Returns: True if the path was successfully changed.

LoadResource

SPtr<Resource> LoadResource(const UUID &id)

Loads the resource with the specified id into memory, or returns an already loaded resource if previously loaded.

Resource will remain loaded for future calls, unless explicitly unloaded or destroyed.

id: Unique id of the resource.

Returns: Resource if successful, or null otherwise.

LoadResource

SPtr<Resource> LoadResource(const Path &path)

Loads the resource with the specified id into memory, or returns an already loaded resource if previously loaded.

Resource will remain loaded for future calls, unless explicitly unloaded or destroyed.

path: Path to the resource. Paths are case sensitive.

Returns: Resource if successful, or null otherwise.

DeserializeResource

SPtr<Resource> DeserializeResource(const UUID &id) const

Deserializes a new instance of the resource with the specified id.

This is similar to LoadResource(), but it does not cache the loaded resource internally, instead it always returns a fresh instance.

id: Unique id of the resource.

Returns: Resource if successful, or null otherwise.

DeserializeResource

SPtr<Resource> DeserializeResource(const Path &path) const

Deserializes a new instance of the resource with the specified path.

This is similar to LoadResource(), but it does not cache the loaded resource internally, instead it always returns a fresh instance.

path: Path to the resource. Paths are case sensitive.

Returns: Resource if successful, or null otherwise.

GetResource

SPtr<Resource> GetResource(const UUID &id) const

Returns a previously loaded resource.

id: Unique id of the resource.

Returns: Resource if present and loaded, null otherwise.

GetResource

SPtr<Resource> GetResource(const Path &path) const

Returns a previously loaded resource.

path: Path to the resource. Paths are case sensitive.

Returns: Resource if present and loaded, null otherwise.

UnloadResource

void UnloadResource(const UUID &id)

Unloads the resource with specified id.

UnloadAllResources

void UnloadAllResources()

Unloads all resources loaded with LoadResource().

GetResourceSizeInDataStream

u64 GetResourceSizeInDataStream(const UUID &id) const

Returns the size of the resource when serialized to the data stream, in bytes.

Returns 0 if resource has not yet been serialized, or if resource was not found. Might return an out of date value if runtime resource changed but hasn't been serialized yet.

Save

bool Save(const SPtr<DataStream> &stream, const SavePackageOptions &options)

Saves the package into the provided data stream.

stream: Stream into which to save the package.
options: Options controlling the save operation.

Returns: True if successful, false otherwise. If saving meta-data only, if false it returned it means the meta-data doesn't fit and you must attempt to re-save the entire package.

staticCreate

static SPtr<Package> Create(const String &name = StringUtility::kBlank, const UUID &id = UUID::kEmpty)

Creates a new empty package.

staticLoad

static SPtr<Package> Load(const Path &path)

Loads the package from the provided path.

staticLoad

static SPtr<Package> Load(const SPtr<DataStream> &strean)

Loads the package from the provided data stream.

staticGetRttiStatic

static RTTIType *GetRttiStatic()

GetRtti

RTTIType *GetRtti() const override

Returns an interface you can use to access class' Run Time Type Information.

Internal

Methods

AssociateFileWithPackage

void AssociateFileWithPackage(const Path &path)

Associates a file with the package.

Any resource load attempts will be done from this file. A file will be automatically associated with the package once the package is saved to a file, or when a package is loaded from a file.

Clone

SPtr<Package> Clone() const

Creates a clone of the package, with all the meta-data deep copied into the new package.

Loaded resources are not copied and the cloned package will still be referencing the original resources.

As both packages are pointing to the same resources, and to the same file (if serialized), you should never keep multiple clones of the package persistently active.

Generally you only wish to clone to update the package contents and potentially serialize it to some new location, while the original location can be used for regular load purposes (to avoid blocking users of the package). When the slow serialization operation completes, you will generally kill the original package and replace it with the clone.

Note that in this scenario it's important to call CopyResourceLoadStatesFrom() before the package is replaced, as the original package's resource load states could have been modified.

CopyResourceLoadStatesFromClone

void CopyResourceLoadStatesFromClone(const Package &otherPackage)

Copies the resource load states from a clone of this package.

Caller must ensure no in-progress loads are happening in . See .

Private

Methods

LoadAndDeserializeResource

SPtr<Resource> LoadAndDeserializeResource(const UUID &id, u64 offsetInStream, u64 sizeInStream, CompressionType compressionType, std::atomic<float> &outProgress) const

Deserializes a resource from a specific location in the package data stream.

id: Id of the resource to deserialize.
offsetInStream: Offset into the stream at which the resource starts, in bytes.
sizeInStream: Size of the resources in the stream, in bytes.
compressionType: Compression method that was used to compress the data, if any.
outProgress: Parameter in which to report the load progress, ranging [0, 1].

Returns: Loaded resource if successful.

UnloadResource

void UnloadResource(ResourceInformation *resourceInfo)

Unloads the resource with the associated resource information.

GetResourceInformation

ResourceInformation *GetResourceInformation(const UUID &id, bool warnIfMissing = true) const

Returns package internal information about the resource with specified id.

id: Id of the resource to look for.
warnIfMissing: If true, a warning will be logged if the resource information cannot be found.

Returns: Resource information if found, or null otherwise.

GetResourceInformation

ResourceInformation *GetResourceInformation(const Path &path, bool warnIfMissing = true) const

Returns package internal information about the resource with specified path.

path: Path of the resource to look for. Paths are case sensitive.
warnIfMissing: If true, a warning will be logged if the resource information cannot be found.

Returns: Resource information if found, or null otherwise.

Fields

mName

String mName

mId

UUID mId

mAssociatedPackageFilePath

Path mAssociatedPackageFilePath

Path to the file in which the package data has been saved.

Empty if package hasn't been saved yet.

mPackageMetaData

SPtr<PackageMetaData> mPackageMetaData

mSerializedMetaDataEnd

size_t mSerializedMetaDataEnd

mMetaDataPaddingByteCount

size_t mMetaDataPaddingByteCount

Extra empty bytes in the file after meta-data.

Allows meta-data to grow without having to re-write the whole file.

mResourceInformationByPath

UnorderedMap<Path, ResourceInformation *, PathHashFunction<true>, PathEqualsFunction<true>> mResourceInformationByPath

mResourceInformationByUUID

UnorderedMap<UUID, UPtr<ResourceInformation>> mResourceInformationByUUID

mMetaDataMutex

Mutex mMetaDataMutex

mDataMutex

SharedMutex mDataMutex