You.i Engine
CYIAssetLocator Class Reference

Detailed Description

Using a base file path, determines the path to an asset given a file name and an asset type.

Asset Configurations

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.

Asset Type Directories

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.

Directory Structure

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:

drawable/
default/
hdpi/
layout/
default/
s7/
s7-land/
s10/
s10-land/
TV/

Resolving the Path to an Asset

When a particular asset path needs to be resolved:

  1. The top-level directory name will be determined from the asset type.
  2. Directories with qualifiers that contradict the current device configuration are disqualified.
  3. Each directory will be checked for the file name, from highest to lowest priority. If the file name was found in one of these configuration directories, the best path is returned.
  4. If the file name has not been found, the fallback directories will be checked. If the file name is found in a fallback directory, the path is returned.
  5. If the file name cannot be resolved, filename will be returned as-is.

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.

  1. The asset type directory is resolved as "layout".
  2. The following directories are disqualified because they contradict the current device coniguration:
    • s10/ : The specified screen size is too large for the current device configuration.
    • s10-land/ : The specified screen size is too large for the current device configuration.
    • TV/ : The current device is not a TV.
  3. A search is done in the remaining directories for the file name, in the ranked order:
    • s7-land/ : The "land" qualifier is higher priority than orientation being unspecified.
    • s7
    • default/
  4. Fallback directories are not specific to device configurations and all of them will always be checked in the same order.
  5. Doesn't depend on device configuration. The file name will be returned as is, if it can not be resolved.

If we are loading the same asset on an 11 inch tablet in portrait orientation, steps 2 & 3 get updated to:

  1. The following directories are disqualified because they contradict the current device coniguration:
    • s7-land/ : The current device configuration is portrait.
    • s10-land/ : The current device configuration is portrait.
    • TV/ : The current device is not a TV.
  2. A search is done in the remaining directories for the file name, in the ranked order:
    • s10/ : 10 is closer to the device screen size (11) than 7 is, so it is a higher priority.
    • s7/
    • default/

The default directory is a special directory that is never disqualified and is always the worst match when ranking directories.

Use in You.i Engine

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.

See also
CYIAbstractAssetConfiguration
CYIAssetLoader

#include <asset/YiAssetLocator.h>

Public Types

enum  Priority {
  Priority::Lowest,
  Priority::Highest
}
 

Public Member Functions

 CYIAssetLocator ()
 
 CYIAssetLocator (const CYIAssetLocator &other)
 
 CYIAssetLocator (CYIAssetLocator &&other)
 
 ~CYIAssetLocator ()
 
CYIAssetLocatoroperator= (const CYIAssetLocator &other)
 
CYIAssetLocatoroperator= (CYIAssetLocator &&other)
 
void SetBase (const CYIString &basepath)
 
const CYIStringGetBase () 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)
 

Member Enumeration Documentation

◆ Priority

See also
AddConfigurationProperty
Enumerator
Lowest 
Highest 

Constructor & Destructor Documentation

◆ CYIAssetLocator() [1/3]

CYIAssetLocator::CYIAssetLocator ( )

Creates a new asset locator with a set of default CYIAbstractAssetConfiguration instances and no base path.

◆ CYIAssetLocator() [2/3]

CYIAssetLocator::CYIAssetLocator ( const CYIAssetLocator other)

◆ CYIAssetLocator() [3/3]

CYIAssetLocator::CYIAssetLocator ( CYIAssetLocator &&  other)

◆ ~CYIAssetLocator()

CYIAssetLocator::~CYIAssetLocator ( )

Member Function Documentation

◆ AddAssetTypeDirectory()

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.

See also
Refresh
RemoveAssetTypeDirectory

◆ AddConfigurationProperty()

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.

See also
Refresh
CYIAbstractAssetConfiguration
RemoveConfigurationProperties
ClearConfigurationProperties

◆ AddFallbackDirectory()

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.

Note
On the Tizen platform a manifest file which lists asset files is required. For the fallback directory to function on Tizen a fallback manifest (YouiEngineManifest.json) must be generated and located at rPath. The fallback manifest can be generated using the buildAssetManifest.rb script located in the tools folder of the SDK.

◆ ClearConfigurationProperties()

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.

See also
Refresh
CYIAbstractAssetConfiguration
AddConfigurationProperty
RemoveConfigurationProperties

◆ ClearFallbackDirectories()

void CYIAssetLocator::ClearFallbackDirectories ( )

Removes any previously-assigned fallback directories.

See also
AddFallbackDirectory

◆ GetBase()

const CYIString& CYIAssetLocator::GetBase ( ) const

Returns the base path for this asset locator.

See also
SetBase

◆ GetPath()

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.

See also
CYIAssetLoader

◆ operator=() [1/2]

CYIAssetLocator& CYIAssetLocator::operator= ( const CYIAssetLocator other)

◆ operator=() [2/2]

CYIAssetLocator& CYIAssetLocator::operator= ( CYIAssetLocator &&  other)

◆ Refresh()

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.

See also
AddConfigurationProperty
RemoveConfigurationProperties
ClearConfigurationProperties
AddAssetTypeDirectory

◆ RemoveAssetTypeDirectory()

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.

See also
Refresh
AddAssetTypeDirectory

◆ RemoveConfigurationProperties()

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.

See also
Refresh
CYIAbstractAssetConfiguration
AddConfigurationProperty
ClearConfigurationProperties

◆ SetBase()

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.

See also
CYIApp::GetAssetsPath

The documentation for this class was generated from the following file: