Foundry::Katana::Asset Class Reference

Primary class to derive from when implementing asset system plugin. More...

#include <FnAsset.h>

Inheritance diagram for Foundry::Katana::Asset:

List of all members.

Public Member Functions
virtual void	reset ()=0
	Reset will be called when Katana flushes its caches, giving the plugin a chance to reset.
virtual bool	isAssetId (const std::string &str)=0
	Return whether the input string represents a valid asset id.
virtual bool	containsAssetId (const std::string &str)=0
	Return whether the input string contains a valid asset id anywhere within it.
virtual bool	checkPermissions (const std::string &assetId, const StringMap &context)=0
	Returns whether permissions for the given asset id are valid in the given context.
virtual bool	runAssetPluginCommand (const std::string &assetId, const std::string &command, const StringMap &commandArgs)=0
	Runs a custom command for the given asset id.
virtual void	resolveAsset (const std::string &assetId, std::string &ret)=0
	Lookup asset id in asset system and return path (or other string) that it references.
virtual void	resolveAllAssets (const std::string &str, std::string &ret)=0
	Replace any asset ids found in input string with resolved asset strings.
virtual void	resolvePath (const std::string &str, const int frame, std::string &ret)=0
	Resolve env vars in input path string, then resolve asset ids and file sequences.
virtual void	resolveAssetVersion (const std::string &assetId, std::string &ret, const std::string &versionStr=std::string())=0
	Return the version that this asset id resolves to.
virtual void	getUniqueScenegraphLocationFromAssetId (const std::string &assetId, bool includeVersion, std::string &ret)=0
	Return a valid scenegraph location path that uniquely represents the input asset id.
virtual void	getAssetDisplayName (const std::string &assetId, std::string &ret)=0
	Returns a string that can be used in GUIs, for example.
virtual void	getAssetVersions (const std::string &assetId, StringVector &ret)=0
	Returns a vector of strings listing the available versions for the given asset.
virtual void	getRelatedAssetId (const std::string &assetId, const std::string &relation, std::string &ret)=0
	Return asset id that is related to input asset, given a relationship type.
virtual void	getAssetFields (const std::string &assetId, bool includeDefaults, StringMap &returnFields)=0
	Convert from asset id to a set of named string fields defining the asset.
virtual void	buildAssetId (const StringMap &fields, std::string &ret)=0
	Convert from asset fields to asset id.
virtual void	getAssetAttributes (const std::string &assetId, const std::string &scope, StringMap &returnAttrs)=0
	Get metadata associated with an asset or a scoped item in the asset hierarchy.
virtual void	setAssetAttributes (const std::string &assetId, const std::string &scope, const StringMap &attrs)=0
	Set metadata associated with an asset or a scoped item in the asset hierarchy.
virtual void	getAssetIdForScope (const std::string &assetId, const std::string &scope, std::string &ret)=0
	Get partial asset id scoped to the specified level in the asset hierarchy.
virtual void	createAssetAndPath (AssetTransaction *txn, const std::string &assetType, const StringMap &assetFields, const StringMap &args, bool createDirectory, std::string &assetId)=0
	Create asset and optional directory path.
virtual void	postCreateAsset (AssetTransaction *txn, const std::string &assetType, const StringMap &assetFields, const StringMap &args, std::string &assetId)=0
	Creates an asset after the creation of the files to be published.
virtual AssetTransaction *	createTransaction ()
	Create a transaction object.

---

Detailed Description

Primary class to derive from when implementing asset system plugin.

This is a virtual base class to be extended in your plugin.

In addition to implementing all the pure virtual functions in this class, you must also implement a static method in your derived class:

 // return a new instance of your derived class, owned by caller.
 static Asset *create();

To indicate an error to the caller, your implemntation may throw an exception derived from std::exception.

---

Member Function Documentation

virtual void Foundry::Katana::Asset::buildAssetId	(	const StringMap &	fields,
		std::string &	ret
	)		[pure virtual]

Convert from asset fields to asset id.

The inverse of getAssetFields, this takes a set of asset fields and returns an asset id string.

Parameters:

fields	String map containing key/value strings representing asset fields.
ret	Set to asset id.

Implemented in FileAsset.

virtual bool Foundry::Katana::Asset::checkPermissions	(	const std::string &	assetId,
		const StringMap &	context
	)		[pure virtual]

Returns whether permissions for the given asset id are valid in the given context.

Parameters:

assetId	Asset id to check permissions for.
context	Additional strings used to specify more details about permissions to be checked. Examples include current user or current show environment.

Returns:

True if permissions for the given asset id are valid in the given context.

Implemented in FileAsset.

virtual bool Foundry::Katana::Asset::containsAssetId

(

const std::string &

str

)

[pure virtual]

Return whether the input string contains a valid asset id anywhere within it.

Should parse the input string to determine whether it contains a valid asset id. Should not attempt to determine whether any asset ids found in the string actually exist in the asset database.

Parameters:

str	The string to test.

Returns:

True if the string contains a valid asset id.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::createAssetAndPath	(	AssetTransaction *	txn,
		const std::string &	assetType,
		const StringMap &	assetFields,
		const StringMap &	args,
		bool	createDirectory,
		std::string &	assetId
	)		[pure virtual]

Create asset and optional directory path.

Parameters:

txn	Handle to transaction object. If null, asset/directory creation is done immediately.
assetType	Type of Katana asset to create (e.g. katana scene, image, shadow, etc)
assetFields	GroupAttribute representing asset fields for asset to create (same as getAssetFields output).
args	Additional args used to specify more details (may differ based on assetType). Examples include "versionUp", which is a boolean determining whether to version up an existing asset or "colorspace" if the assetId is of the type "image" (in which if this is provided it should be seen as an Attribute to be associated with the asset)
createDirectory	Boolean specifying whether to create the directory associated with this asset.
assetId	Set to the asset id created (or that will be created on transaction commit).

Implemented in FileAsset.

virtual AssetTransaction* Foundry::Katana::Asset::createTransaction

(

)

[virtual]

Create a transaction object.

Transaction objects are used to group asset/directory creation actions to allow them to succeed or fail as a unit.

Returns:

Pointer to heap-allocated instance of derived AssetTransaction. Caller owns returned instance. If asset plugin does not support transactions, always return 0x0.

virtual void Foundry::Katana::Asset::getAssetAttributes	(	const std::string &	assetId,
		const std::string &	scope,
		StringMap &	returnAttrs
	)		[pure virtual]

Get metadata associated with an asset or a scoped item in the asset hierarchy.

This differs from the above "asset fields" which are the fields that uniquely define the asset itself. This metadata may include fields such as asset creator, creation time, etc.

Parameters:

assetId	Asset for which to return metadata.
scope	Optional string specifying scope for metadata lookup, such as "name" or "version".
returnAttrs	Fill with key/value strings representing metadata attributes.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getAssetDisplayName	(	const std::string &	assetId,
		std::string &	ret
	)		[pure virtual]

Returns a string that can be used in GUIs, for example.

Parameters:

assetId	The asset for which the display name is required
ret	Return value with the display name.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getAssetFields	(	const std::string &	assetId,
		bool	includeDefaults,
		StringMap &	returnFields
	)		[pure virtual]

Convert from asset id to a set of named string fields defining the asset.

The minimum set of fields are "name" and "version". Other fields are preserved but ignored by Katana.

Parameters:

assetId	Input asset id.
includeDefaults	If true, return the full set of fields for this asset system, including defaults not specified in the asset id. If false, return only the fields specified in the asset id.
returnFields	Fill map with key/value strings representing asset fields.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getAssetIdForScope	(	const std::string &	assetId,
		const std::string &	scope,
		std::string &	ret
	)		[pure virtual]

Get partial asset id scoped to the specified level in the asset hierarchy.

Should return a more general asset reference to the given asset id. For instance, if scope is "name", return an asset id that doesn't include a specific version number. This may not make sense in some asset systems, in which case, return the input asset id.

Parameters:

assetId	Input asset id.
scope	String specifying scope for result asset id, such as "name" or "version".
ret	Set to result asset id.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getAssetVersions	(	const std::string &	assetId,
		StringVector &	ret
	)		[pure virtual]

Returns a vector of strings listing the available versions for the given asset.

Parameters:

assetId	The asset who's versions we want
ret	The string vector of available versions

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getRelatedAssetId	(	const std::string &	assetId,
		const std::string &	relation,
		std::string &	ret
	)		[pure virtual]

Return asset id that is related to input asset, given a relationship type.

A general function for getting related assets. An current example in Katana is an "argsxml" asset defining the UI for a renderer procedural asset.

Parameters:

assetId	Input asset id for which to find related asset.
relation	String representing relationship type.
ret	Set to related assed id (or empty string if no related asset is found).

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::getUniqueScenegraphLocationFromAssetId	(	const std::string &	assetId,
		bool	includeVersion,
		std::string &	ret
	)		[pure virtual]

Return a valid scenegraph location path that uniquely represents the input asset id.

This will be used as the default location for look file materials loaded into the Katana scene, for example. (Example: /name/version/other/fields).

Parameters:

assetId	Input asset id to represent as scenegraph location path.
includeVersion	allows to specify if the scenegraph location path should contain the asset version
ret	Set to scenegraph location path.

Implemented in FileAsset.

virtual bool Foundry::Katana::Asset::isAssetId

(

const std::string &

str

)

[pure virtual]

Return whether the input string represents a valid asset id.

Should parse the input string to determine whether it is a valid asset id. Should not attempt to determine whether the asset actually exists in the asset database.

Parameters:

str	The string to test.

Returns:

True if the string is valid asset id syntax.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::postCreateAsset	(	AssetTransaction *	txn,
		const std::string &	assetType,
		const StringMap &	assetFields,
		const StringMap &	args,
		std::string &	assetId
	)		[pure virtual]

Creates an asset after the creation of the files to be published.

Parameters:

txn	Handle to transaction object. If null, asset/directory creation is done immediately.
assetType	Type of Katana asset to create (e.g. katana scene, image, shadow, etc)
assetFields	GroupAttribute representing asset fields for asset to create (same as getAssetFields output).
args	Additional args used to specify more details (may differ based on assetType). Examples include "versionUp", which is a boolean determining whether to version up an existing asset.
assetId	Set to the asset id created (or that will be created on transaction commit).

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::resolveAllAssets	(	const std::string &	str,
		std::string &	ret
	)		[pure virtual]

Replace any asset ids found in input string with resolved asset strings.

Parameters:

str	Input string to resolve.
ret	Set to resolved asset string.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::resolveAsset	(	const std::string &	assetId,
		std::string &	ret
	)		[pure virtual]

Lookup asset id in asset system and return path (or other string) that it references.

Parameters:

assetId	Asset id to resolve.
ret	Set to resolved asset string.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::resolveAssetVersion	(	const std::string &	assetId,
		std::string &	ret,
		const std::string &	versionStr = std::string()
	)		[pure virtual]

Return the version that this asset id resolves to.

Parameters:

assetId	Input asset id resolve.
ret	Returns the version that this asset id resolves to.
versionStr	In some asset management systems the version can be specified by keywords (example: latest, aproved, etc) that might be associated to a specific version number. If versionStr is specified, then the plugin will try to return (on ret) the resolved string number for the assetId specified by str and the given version keyword (the versionStr value).

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::resolvePath	(	const std::string &	str,
		const int	frame,
		std::string &	ret
	)		[pure virtual]

Resolve env vars in input path string, then resolve asset ids and file sequences.

File sequence will most likely be resolved using default file sequence plugin from host. This is a good candidate for some base functionality in the C++ wrappers on the plugin side.

Parameters:

str	Input path string to resolve.
frame	Frame number to resolve file sequences with.
ret	Set to resolved path string.

Implemented in FileAsset.

virtual bool Foundry::Katana::Asset::runAssetPluginCommand	(	const std::string &	assetId,
		const std::string &	command,
		const StringMap &	commandArgs
	)		[pure virtual]

Runs a custom command for the given asset id.

Parameters:

assetId	Asset id the command will be run on.
command	Name of the command to run.
commandArgs	Key-string pair representing the command arguments.

Returns:

True if the command execution succeeds.

Implemented in FileAsset.

virtual void Foundry::Katana::Asset::setAssetAttributes	(	const std::string &	assetId,
		const std::string &	scope,
		const StringMap &	attrs
	)		[pure virtual]

Set metadata associated with an asset or a scoped item in the asset hierarchy.

This differs from the above "asset fields" which are the fields that uniquely define the asset itself. This metadata may include fields such as asset creator, creation time, etc.

Parameters:

assetId	Asset for which to set metadata.
scope	Optional string specifying scope for metadata lookup, such as "name" or "version".
attrs	String map containing key/value strings representing metadata attributes.

Implemented in FileAsset.

---

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

• FnAsset.h