Asset Plug-ins (C++)¶

class Foundry::Katana::DefaultAssetPlugin¶

#include <FnDefaultAssetPlugin.h>

Allows the access to the currently set Asset Management System plugin.

This class can be used when a plugin (a Scenegraph Generator, for example) needs to resolve or publish assets using the Asset Management System Plugin set on the current scene (regardless if it is implemented in C++ or Python)....

Public Static Functions

static bool isAssetId(const std::string &str, bool throwOnError = false)¶

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.

Return

True if the string is valid asset id syntax.

Parameters

str -
The string to test.
throwOnError -
Boolean setting whether to throw an exception on error.

static bool containsAssetId(const std::string &str, bool throwOnError = false)¶

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.

Return

True if the string contains a valid asset id.

Parameters

str -
The string to test.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string resolveAsset(const std::string &assetId, bool throwOnError = false)¶

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

Return

The resolved asset string.

Parameters

assetId -
Asset id to resolve.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string resolveAllAssets(const std::string &inputString, bool throwOnError = false)¶

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

Return

The string with all asset ids replaced with resolved asset strings.

Parameters

inputString -
The string to be searched for asset ids.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string resolvePath(const std::string &path, int frame, bool throwOnError = false)¶

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.

Return

The resolved path string.

Parameters

path -
Input path string to resolve.
frame -
Frame number to resolve file sequences with.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string getUniqueScenegraphLocationFromAssetId(const std::string &assetId, bool includeVersion, bool throwOnError = false)¶

static std::string getRelatedAssetId(const std::string &assetId, const std::string &relation, bool throwOnError = false)¶

static bool getAssetAttributes(const std::string &assetId, const std::string &scope, std::map<std::string, std::string> &attributesMap, bool throwOnError = false)¶

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

Return

Parameters

assetId -
The id of the asset to search for metadata.
scope -
A scoped item name.
attributesMap -
A map to be filled with the metadata attributes of the given asset.
throwOnError -
Boolean setting whether to throw an exception on error.

static bool checkPermissions(const std::string &assetId, const std::map<std::string, std::string> &context, bool throwOnError = false)¶

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

Return

Parameters

assetId -
The id of the asset to check permission for.
context -
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string resolveAssetVersion(const std::string &assetId, const std::string &versionTag = std::string(), bool throwOnError = false)¶

Returns the version for a given asset id. If it is a partial asset id (which does not have a version) then an empty string is returned.

Return

String with the integer version number that this asset id resolves to, or an empty string if an error occurs.

Parameters

assetId -
The asset id to resolve.
versionTag -
An optional version tag to use for determining the resulting version. Can be an explicit version number or a special tag such as “latest” or “approved”.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string getAssetDisplayName(const std::string &assetId, bool throwOnError = false)¶

Returns a name suitable for displaying to the user for the given asset id.

Return

The display name of the given asset.

Parameters

assetId -
The asset id to look for display name.
throwOnError -
Boolean setting whether to throw an exception on error.

static bool getAssetVersions(const std::string &assetId, std::vector<std::string> &versions, bool throwOnError = false)¶

Gets a list of all the available versions of the given asset.

Return

True on success.

Parameters

assetId -
The asset id to look for available versions.
versions -
The vector to be filled with the available versions of the given asset.
throwOnError -
Boolean setting whether to throw an exception on error.

static bool getAssetFields(const std::string &assetId, bool includeDefaults, std::map<std::string, std::string> &returnFields, bool throwOnError = false)¶

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.

Return

True on success.

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 -
A map to be filled with the asset fields.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string buildAssetId(const std::map<std::string, std::string> &fields, bool throwOnError = false)¶

Builds and return a new asset id using the given fields.

Return

The new asset id, on success. Otherwise an empty string.

Parameters

fields -
A map of fields used to build the new asset id.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string getAssetIdForScope(const std::string &assetId, const std::string &scope, bool throwOnError = false)¶

Gets an 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”, returns 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.

Return

A string containing the result asset id.

Parameters

assetId -
The input asset id.
scope -
A string specifying scope for result asset id, such as “name” or “version”.
throwOnError -
Boolean setting whether to throw an exception on error.

class Foundry::Katana::DefaultFileSequencePlugin¶

#include <FnDefaultFileSequencePlugin.h>

Allows the access to the currently set File Sequence plugin.

This class can be used when a plugin (a Scenegraph Generator, for example) needs to do build or resolve a file sequence using the File Sequence Plugin set in the current Katana scene.

Public Static Functions

static bool isFileSequence(const std::string &path, bool throwOnError = false)¶

Return true if string is a valid file sequence.

Parameters

path -
The string to test.
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string buildFileSequenceString(const std::string &prefix, const std::string &suffix, int padding, bool throwOnError = false)¶

Return a valid file sequence string built from input prefix/suffix/padding.

Parameters

prefix -
A string with the portion of the sequence path before the frame symbol(s)
suffix -
A string with the portion of the sequence path after the frame symbol(s)
padding -
The size of the zero padding for the frame number
throwOnError -
Boolean setting whether to throw an exception on error.

static std::string resolveFileSequence(const std::string &path, int frame, bool throwOnError = false)¶

Resolves a file sequence string into an single real file path.

Given a sequence path string and a frame number, it returns the actual file path for that frame.

Parameters

path -
The sequence path string.
frame -
The frame number.
throwOnError -
Boolean setting whether to throw an exception on error.

static bool isFrameInFileSequence(const std::string &path, int frame, bool throwOnError = false)¶

Returns whether or not a given frame is a part of the file sequence.

Return

true if the frame is a part of the file sequence, false otherwise

Parameters

path -
The sequence path string
frame -
The frame number
throwOnError -
Boolean setting whether to throw an exception on error.

class Foundry::Katana::Asset¶

#include <FnAsset.h>

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.

Subclassed by FileAsset

Public Types

typedef std::map<std::string, std::string> StringMap¶

typedef std::vector<std::string> StringVector¶

Public Functions

Asset()¶

virtual ~Asset()¶

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.

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.

Return

True if the string is valid asset id syntax.

Parameters

str -
The string to test.

virtual bool containsAssetId(const std::string &str) = 0¶

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.

Return

True if the string contains a valid asset id.

Parameters

str -
The string to test.

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.

Return

True if 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.

virtual bool runAssetPluginCommand(const std::string &assetId, const std::string &command, const StringMap &commandArgs) = 0¶

Runs a custom command for the given asset id.

Return

True if the command execution succeeds.

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.

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.

Parameters

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

virtual void resolveAllAssets(const std::string &str, std::string &ret) = 0¶

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

Parameters

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

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.

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.

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.

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

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.

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.

virtual void getAssetDisplayName(const std::string &assetId, std::string &ret) = 0¶

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.

virtual void getAssetVersions(const std::string &assetId, StringVector &ret) = 0¶

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

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.

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

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.

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.

virtual void buildAssetId(const StringMap &fields, std::string &ret) = 0¶

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

virtual AssetTransaction *createTransaction()¶

Create a transaction object.

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

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

class Foundry::Katana::AssetTransaction¶

#include <FnAsset.h>

Virtual base for asset transactions.

Derive from this in your plugin to support transactions. A SimpleTransaction class is included here that maintains a list of actions to be executed on commit().

Subclassed by Foundry::Katana::SimpleTransaction

Public Functions

AssetTransaction()¶

virtual ~AssetTransaction()¶

virtual void cancel() = 0¶: Cancel transaction.

virtual bool commit() = 0¶: Commit transaction.

class Foundry::Katana::SimpleAction¶

#include <FnAsset.h>

Simple action base class for performing an action (doit) and rolling it back (rollback) in case of error in this or subsequent action.

Public Functions

virtual ~SimpleAction()¶

virtual bool doit() = 0¶

virtual void rollback() = 0¶

class Foundry::Katana::SimpleTransaction¶

#include <FnAsset.h>

Simple transaction maintains a list of actions. If an action returns failure during commit, execution is canceled and rollback() is called on all previously executed actions in transaction.

Inherits from Foundry::Katana::AssetTransaction

Public Functions

virtual ~SimpleTransaction()¶

void addAction(SimpleAction *action)¶

virtual void cancel()¶: Cancel transaction.

virtual bool commit()¶: Commit transaction.

class Foundry::Katana::FileSequence¶

#include <FnFileSequence.h>

Primary class to derive from when implementing file sequence plugin.

File sequences are closely related to the asset system. A file sequence spec is a file path that contains tokens to be substituted with the current frame number. Some file sequence specs may also specify the frame range of the sequence.

An example from the FileSeq plugin: /path/to/image.1-10#.exr

This example references a sequence of images, frames 1 through 10, with the frame number zero-padded to length 4.

Resolving this sequence at frame 5 would result in: /path/to/image.0005.exr

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

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

 // return true if string is a valid file sequence
 static bool isFileSequence(const char*);

 // return a valid file sequence string built from input prefix/suffix/padding
 std::string buildFileSequenceString(const std::string &prefix, const std::string &suffix, int padding);

 // return a new FileSequenceArray instance containing sequences and non-sequence file paths found
 // in input file path list
 FileSequenceArray* findSequence(const char** fileList, unsigned int fileCount);

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

Subclassed by FileSeq

Public Functions

FileSequence()¶

FileSequence(const std::string&)¶

virtual ~FileSequence()¶

virtual bool isValid() const = 0¶: Return whether this instance contains a valid file sequence.

virtual FileSequence *clone() const = 0¶: Return new copy of this class instance.

virtual void getAsString(std::string &retValue) = 0¶

Get string representation of the file sequence.

Parameters

retValue -
Set to file sequence string.

virtual void getDirectory(std::string &retValue) = 0¶

Get the directory portion of file sequence.

Parameters

retValue -
Set to directory portion of file sequence (e.g. “/a/b/c” for fileseq “/a/b/c/d.#.exr”).

virtual void getPrefix(std::string &retValue) = 0¶

Get the portion of file sequence before the frame number.

Parameters

retValue -
Set to prefix portion of file sequence (e.g. “/a/b/c/d.” for fileseq “/a/b/c/d.#.exr”).

virtual void getSuffix(std::string &retValue) = 0¶

Get the portion of file sequence after the frame number.

Parameters

retValue -
Set to suffix portion of file sequence (e.g. ”.exr” for fileseq “/a/b/c/d.#.exr”).

virtual unsigned int getPadding() = 0¶

Get the padding of the file sequence frame number.

Return: Padding amount of file sequence (e.g. 4 for fileseq that expands to image.0001.exr)

virtual void getResolvedPath(const int frame, std::string &retValue) = 0¶

Get the filename for file sequence with sequence portion replaced by correctly padded frame.

Parameters

frame -
The frame to get the filename.
retValue -
Set to resolved filename.

virtual bool hasFrameSet() = 0¶

Return whether file sequence has explicit frame set.

Return: True if file sequence has explicit frame range (set) embedded in it (e.g. “image.1-10#.exr”).

virtual bool isFrameInFrameSet(const int frame) = 0¶

Test whether frame is within explicit frame set.

Return: True if frame is in frame set. If file sequence does not have explicit frame set, always return true.

virtual int getFirstFrameInFrameSet() = 0¶

Return first frame in explicit frame set.

Return: First (minimum) frame in frame set. If file sequence does not have explicit frame set, always return 0.

virtual int getLastFrameInFrameSet() = 0¶

Return last frame in explicit frame set.

Return: Last (maximum) frame in frame set. If file sequence does not have explicit frame set, always return 0.

virtual void getNearestFramesInFrameSet(int frame, bool *hasLeft, int *nearestLeft, bool *hasRight, int *nearestRight) = 0¶

Return nearest frame to left and right of frame.

Set return values to (false, 0, false, 0) if file sequence does not have explicit fram set.

Parameters

frame -
Frame number to return nearest frames of.
hasLeft -
Set to true if frame exists in list to left of specified frame.
nearestLeft -
Set to nearest frame in list to left of specified frame.
hasRight -
Set to true if frame exists in list to right of specified frame.
nearestRight -
Set to nearest frame in list to right of specified frame.

virtual void getFrameListFromFrameSet(std::vector<int> &returnList) = 0¶

Get frame set as list of integers.

Parameters

returnList -
Fill with integer frame numbers (e.g. [1,2,3,4,5] for “image.1-5#.exr”).

class Foundry::Katana::FileSequenceArray¶

#include <FnFileSequence.h>

Container class that holds a vector of FileSequence instances and a vector of non-sequence filenames.

Public Functions

FileSequenceArray(std::vector<FileSequence *> &seq, std::vector<std::string> &nonseq)¶

virtual ~FileSequenceArray()¶

virtual int getFileSequenceCount()¶: Number of file sequence objects in vector.

virtual FileSequence *getFileSequence(const unsigned int index)¶: Get FileSequence object ptr by index. The caller does not own the FileSequence object returned.

virtual void getFileNames(std::vector<std::string> &fileNames)¶: Get vector of non-sequence file names.