Attribute Modifier Plug-ins¶

class Foundry::Katana::AttributeModifier¶

#include <FnAttributeModifier.h>

Class that represents an AMP. Must be be extended in an AMP plugin.

It is responsible for processing the Attributes on a given Location. This class accepts arguments that can define how this processing should happen. These arguments are passed to the constructor as a GroupAttribute with children.

Public Functions

AttributeModifier(GroupAttribute args)¶

Constructor. Any initialization should be done here.

Parameters

• args -

  An GroupAttribute that can contain several Attributes that can be used as arguments for the AMP. The valuese of these argument Attributes can be stored in member variables or can be used to initialize internal data-structures in AttributeModifier’s sub-class. These member variables and data-structures can be later used by the cook() method.

virtual ~AttributeModifier()¶

virtual std::string getCacheId()¶

Returns an hash that defines if an AMP should run or not. In its default implementation the hash is automatically generated from the AMP argument values, which means that it will force the AMP to run whenever the value of an argument is changed by the user. This function can also be overriden so that the conditions in which an AMP should execute again can be under the developer’s control.

virtual void cook(AttributeModifierInput &input) = 0¶

The function that does all the Scenegraph Attributes processing on a given location. It receives an AttributeModifierInput which provides all the information related with the location being processed. It should make use of the addOverride() function on AttributeModifierInput to perform the attribute changes.

Public Static Functions

static GroupAttribute getArgumentTemplate()¶

A static function that allows Katana to query the AMP about which arguments it expects. This should return a GroupAttribute with the same structure as the one that is passed to the constructor, in which the Attribute values will be the default values of the correspondent AMP argument.

class Foundry::Katana::AttributeModifierInput¶

#include <FnAttributeModifierInput.h>

Provides functions that inspect and manipulate the Scenegraph that contains the Location being processed by the AMP (the current Location).

Once fed into an AMP’s AttributeModifier::cook() function, it provides a methods to override/remove Attributes in the current Location and allows the inspection of the Attributes at different Locations.

Public Functions

AttributeModifierInput(FnAttributeModifierHostHandle handle)¶

Constructor. Only used internally by Katana - an AMP always receives an already instantiated object of this type.

std::string getName() const¶

Returns the name of the current Location. (ex: “pony” in “/root/world/geo/pony”)

std::string getFullName() const¶

Returns the full path name of the current Location. (ex: “/root/world/geo/pony”)

std::string getType() const¶

Returns the type of the current Location. (ex: “subdmesh” or “group”)

float getFrameTime() const¶

Returns the current frame time (as selected in Katana’s timebar)

std::string getHostString() const¶

Provides a AttributeModifier with a string representation of current host (i.e. “katana 1.0”) for version specific behavior.

float getShutterOpen() const¶

When motion blur is being used then several time samples will be processed from a start time to an end time. This function returns the start time of the current frame.

float getShutterClose() const¶

When motion blur is being used then several time samples will be processed from a start time to an end time. This function returns the end time of the current frame.

int getNumSamples() const¶

When motion blur is being used then several time samples will be processed. This function Returns the number of motion blur samples chosen on the scene.

void addOverride(const std::string &name, Attribute attr, bool inheritGroup)¶

Function that overrides or creates an Attribute under the current Location. This is the function that must be called from within AttributeModifier::cook() function in order to arr/modify an attribute. In order to delete an attribute an NullAttribute can be used with the name of the attribute to be deleted.

Parameters

• name -

  Name of the attribute to be modified/created/deleted.

• attr -

  The new attribute that should be added or replace the existing one. If this is a null pointer (0x0, not a NullAttribute), any existing attribute with this name will be deleted.

• inheritGroup -

  If the attribute being overridden is a Group Attribute this flag defines if this group will be inherited by the child Locations of the current Location.

Attribute getAttribute(const std::string &name, bool global = false, const std::string &atLocation = "") const¶

Returns an existing Attribute from the specified Location, or from the current Location if no location is specified. If there isn’t any Attribute with the given name on the given Location then an invalid Attribute is returned (which can be checked with the function Attribute::isValid()).

Return

A valid Attribute if there is an attribute with the given name on the given location, or an invalid one otherwise. If the global parameter is set to false and the Attribute is a global attribute then an invalid attribute is returned.

Parameters

• name -

  The name of the attribute - can be a child of a GroupAttribute (ex: “geometry.point.P”)

• global -

  If false then the global attributes (inherited from parent Locations) will be ignored. In this case if the requested Attribute is global, then an invalid attribute is returned.

• atLocation -

  The location from where the attribute will be retrieved (optional - if not specified the current Location will be used)

void getAttributeNames(std::vector<std::string> &names, bool global = false) const¶

Fills a vector of strings with the names of the top level attributes (which doesn’t include the children of Group Attributes) on the current Location.

Parameters

• names -

  A reference to a vector that will be filled with the Attribute names

• global -

  If false then the global attributes (inherited from parent Locations) will be ignored.

DoubleAttribute getWorldSpaceXform(bool multiSample = false, const std::string &atLocation = "") const¶

Returns a Double Attribute with the world space transform matrix of a given Location. Katana stores the transforms in a structured Group Attribute that contains the translate, rotate and scale values on the three axes. This function crunches these attributes down into a Matrix.

Parameters

• multiSample -

  If true then all the samples of the Transform stored on the Location will be returned in the resulting Double Attribute (that will return the number of different matrices using the DoubleAttribute::getNumberOfTuples() function)

• atLocation -

  The location from where the transforms will be retrieved (optional - if not specified the current Location will be used)

DoubleAttribute getWorldSpaceXformForSamples(const std::vector<float> &samples, const std::string &atLocation = "") const¶

Returns a Double Attribute with the world space transform matrix of a given Location and for a certain set of sample times.

Parameters

• samples -

  A vector of float containing the samples for which the transforms will be returned.

• atLocation -

  The location from where the attribute names will be retrieved (optional - if not specified the current Location will be used)

void getChildNames(std::vector<std::string> &names, const std::string &atLocation = "") const¶

Fills a vector with the names of the children of the given Location.

Parameters

• names -

  A reference to a vector of strings that will be filled with the child names.

• atLocation -

  The location for which the child names will be retrieved (optional - if not specified the current Location will be used)

void addErrorOverride(const std::string &errorMessage, bool isFatal)¶

Convenience function for reporting error via attribute overrides. Will set “errorMessage” attribute and optionally, set “type” to “error” (for a fatal error).

void setAttribute(const std::string &name, Attribute attr, bool inheritGroup)¶

Set an attribute at this location. Overrides existing attribute or adds new attribute. Equivalent to “addOverride(name, attr, inheritGroup)”.

void deleteAttribute(const std::string &name)¶

Delete an attribute at this location. Equivalent to “addOverride(name, 0x0, false)”.