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 ()
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)

Member Enumeration Documentation

Priority

enum CYIAssetLocator::Priority

strong

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:

• asset/YiAssetLocator.h