Using a base file path, determines the path to an asset given a file name and an asset type.
Alternate assets can be provided so the application can support a variety of device configurations. When assets are loaded, the current device configuration is detected and the appropriate assets are loaded.
A new instance of this class is created with the following default asset configurations:
Name | Qualifiers | Description |
---|---|---|
Screen Orientation | "land", "port" | The orientation of the device, defined by the aspect ratio of the CYIScreen. This can change during the lifetime of the application on devices that support screen rotation. |
Form Factor | "tv", "handset", "tablet" | The type of device provided by CYIDeviceTypeBridge. The "tv" form factor provides a "10-foot" experience, and input is typically from a DPAD. The "handset" and "tablet" form factors are typically hand-held and receive touch input. |
Screen Size | s<number> | A minimum diagonal CYIScreen size in inches. The highest priority is defined as being closest to (without exceeding) the current CYIScreen size. |
Surface Width | w<number> | A minimum CYISurface width in inches. The highest priority is defined as being closest to (without exceeding) the current CYISurface width. |
Surface Height | h<number> | A minimum CYISurface height in inches. The highest priority is defined as being closest to (without exceeding) the current CYISurface height. |
Screen Density | "ldpi", "mdpi", "hdpi", "xhdpi", "xxhdpi", "nodpi" | These map to dpi cutoff values: ldpi: 120, mdpi: 160, hdpi: 240, xhdpi: 320, xxhdpi: 480, nodpi: 0. The highest priority is defined as being closest to (without exceeding) the current CYIScreen X density. |
Locale | "xx_xx", eg: "en_US" | The current locale provided by CYILocale::GetLocale. |
The configurations will be evaluated in the order listed. Custom configurations can be added, either before or after the system ones.
Assets are loaded from the appropriate top-level directory according to their base type.
Asset Type | Directory Name |
---|---|
CYIAssetViewTemplate | "layout" |
CYIAssetTimelineSource | "layout" |
CYIAssetTextureBase | "drawable" |
CYIAssetBif | "drawable" |
CYIAssetShaderObject | "shader" |
CYIAssetTranslation | "text" |
CYIAssetSound | "audio" |
CYIAssetScript | "script" |
CYIAssetVideo | "video" |
CYIAssetJSON | "json" |
Custom asset types can be associated with a new or existing top-level directory using AddAssetTypeDirectory.
The qualifiers can be used and combined to create directories from which assets are loaded. The values can be combined in any order, and are separated by dashes.
A sample asset directory structure might look like:
When a particular asset path needs to be resolved:
For example, resolving the path to a CYIAssetViewTemplate, given the sample directory structure above and the device configuration: 8 inch tablet in the landscape orientation.
If we are loading the same asset on an 11 inch tablet in portrait orientation, steps 2 & 3 get updated to:
The default directory is a special directory that is never disqualified and is always the worst match when ranking directories.
The CYIAssetLoader owns an instance of this class and uses CYIAssetLocator::GetPath to resolve paths. The default instance is generated and configured and has its base path set to CYIApp::GetAssetsPath by the framework during app initialization.
#include <asset/YiAssetLocator.h>
Public Types | |
enum | Priority { Priority::Lowest, Priority::Highest } |
Public Member Functions | |
CYIAssetLocator () | |
CYIAssetLocator (const CYIAssetLocator &other) | |
CYIAssetLocator (CYIAssetLocator &&other) | |
~CYIAssetLocator () | |
CYIAssetLocator & | operator= (const CYIAssetLocator &other) |
CYIAssetLocator & | operator= (CYIAssetLocator &&other) |
void | SetBase (const CYIString &basepath) |
const CYIString & | GetBase () const |
void | Refresh () |
void | AddConfigurationProperty (std::unique_ptr< CYIAbstractAssetConfiguration > pConfiguration, Priority priority=Priority::Lowest) |
void | RemoveConfigurationProperties (const CYIString &qualifier) |
void | ClearConfigurationProperties () |
void | AddFallbackDirectory (const CYIString &rPath) |
void | ClearFallbackDirectories () |
CYIString | GetPath (const CYIString &filename, const CYIRuntimeTypeInfo &assetType) const |
bool | AddAssetTypeDirectory (const CYIString &directoryName, const CYIRuntimeTypeInfo &assetType) |
void | RemoveAssetTypeDirectory (const CYIRuntimeTypeInfo &assetType) |
|
strong |
Enumerator | |
---|---|
Lowest | |
Highest |
CYIAssetLocator::CYIAssetLocator | ( | ) |
Creates a new asset locator with a set of default CYIAbstractAssetConfiguration instances and no base path.
CYIAssetLocator::CYIAssetLocator | ( | const CYIAssetLocator & | other | ) |
CYIAssetLocator::CYIAssetLocator | ( | CYIAssetLocator && | other | ) |
CYIAssetLocator::~CYIAssetLocator | ( | ) |
bool CYIAssetLocator::AddAssetTypeDirectory | ( | const CYIString & | directoryName, |
const CYIRuntimeTypeInfo & | assetType | ||
) |
Associates assetType with the asset type directory, directoryName. assetType must be a subclass of CYIAsset and must not already be associated with a directory. Additionally, assetType must not be a subclass or superclass of another asset type already associated with a directory. Asset types provided by You.i Engine and any of their subclasses cannot be associated with new asset type directories.
Returns true if the above conditions are met.
Refresh must be called so the new asset type directory can be considered in future asset path resolutions.
void CYIAssetLocator::AddConfigurationProperty | ( | std::unique_ptr< CYIAbstractAssetConfiguration > | pConfiguration, |
Priority | priority = Priority::Lowest |
||
) |
Adds a custom configuration pConfiguration to this asset locator.
After adding a custom configuration, CYIAssetLocator::Refresh should be called so pConfiguration can be considered in future asset path resolutions.
The priority parameter can be used to specify the priority of this configuration relative to the other configurations in the list. When CYIAssetLocator::Priority::Lowest is selected, the configuration is evaluated after all existing configurations. When CYIAssetLocator::Priority::Highest is selected, the configuration is evaluated prior to any existing configurations.
void CYIAssetLocator::AddFallbackDirectory | ( | const CYIString & | rPath | ) |
Adds a fallback directory for assets lookup. When an asset cannot be found in any of the valid directories, the fallback directories list will be checked. By default, there are no fallback directories.
void CYIAssetLocator::ClearConfigurationProperties | ( | ) |
Removes all configurations from this asset locator, including the system configurations created by default.
After clearing the configurations, CYIAssetLocator::Refresh should be called so the configurations will not longer be considered in future asset path resolutions.
void CYIAssetLocator::ClearFallbackDirectories | ( | ) |
Removes any previously-assigned fallback directories.
const CYIString& CYIAssetLocator::GetBase | ( | ) | const |
Returns the base path for this asset locator.
CYIString CYIAssetLocator::GetPath | ( | const CYIString & | filename, |
const CYIRuntimeTypeInfo & | assetType | ||
) | const |
Returns the absolute path to the file named filename which can be represented as a CYIAsset subtype, assetType. If the path cannot be resolved filename will be returned as-is.
This is used during asset loading to resolve paths for filenames.
CYIAssetLocator& CYIAssetLocator::operator= | ( | const CYIAssetLocator & | other | ) |
CYIAssetLocator& CYIAssetLocator::operator= | ( | CYIAssetLocator && | other | ) |
void CYIAssetLocator::Refresh | ( | ) |
Updates the asset locator in case CYIAbstractAssetConfiguration instances have been added, removed, the information used by a current configuration has changed, or a new asset type directory has been added or removed.
For example: if the surface orientation configuration is present, CYIAssetLocator::Refresh should be called when the surface aspect ratio changes so the new orientation can be considered.
void CYIAssetLocator::RemoveAssetTypeDirectory | ( | const CYIRuntimeTypeInfo & | assetType | ) |
Removes association between assetType and its asset type directory.
Refresh must be called so the removed asset type directory will not be considered in future asset path resolutions.
void CYIAssetLocator::RemoveConfigurationProperties | ( | const CYIString & | qualifier | ) |
Removes asset configurations which make use of the provided qualifier qualifier. This function will remove both user-provided configurations and system-defined configurations.
After removing a configuration, CYIAssetLocator::Refresh should be called so the configuration will no longer be considered in future asset path resolutions.
void CYIAssetLocator::SetBase | ( | const CYIString & | basepath | ) |
Sets basepath as the base file path for this asset locator. This updates the asset locator, processing the directory structure at this new location.
The base is set by the framework during app initilization to the CYIApp asset path, and does not typically need to be set manually.