The Op API offers a unified interface for manipulating the scene graph and modifying attributes, something that was previously only possible through a combination of SGGs and AMPs. All of Katana's shipped Ops are written with the Op API. More...

Classes
class	Foundry::Katana::GeolibCookInterface
	Provides a unified interface for querying and manipulating the scene graph. More...
class	Foundry::Katana::GeolibPrivateData
	Convenience base class that can be derived from to allow users who require private data in their Ops. More...
struct	Foundry::Katana::BoundPoint
	Utility structure that can be used to represent a point in 3D space. Multiple points can be used to describe a bounding box. More...
class	Foundry::Katana::GeolibOp
class	Foundry::Katana::GeolibSetupInterface
	Provides functions to allow an Op to configure how it's scheduled and evaluated by the Runtime. More...
Functions
std::string	Foundry::Katana::GetInputLocationType (const GeolibCookInterface &interface, FnPlatform::StringView location=FnPlatform::StringView(), int inputIndex=kFnKatGeolibDefaultInput)
	Returns the location type for specified location on the corresponding GeolibCookInterfaces's input.
std::string	Foundry::Katana::GetAbsOutputLocationPath (const GeolibCookInterface &interface, const std::string &outputLocationPath)
	Resolves a relative output scene graph location path to an absolute path.
std::string	Foundry::Katana::GetAbsInputLocationPath (const GeolibCookInterface &interface, const std::string &inputLocationPath)
	Resolves a relative input scene graph location path to an absolute path.
void	Foundry::Katana::RenameChild (GeolibCookInterface &interface, FnPlatform::StringView src, FnPlatform::StringView dst)
	Renames the specified child.
FnAttribute::Attribute	Foundry::Katana::GetGlobalAttr (const GeolibCookInterface &interface, FnPlatform::StringView name, FnPlatform::StringView location=FnPlatform::StringView(), int inputIndex=kFnKatGeolibDefaultInput)
	Returns attribute from the input scene, including inherited attributes.
void	Foundry::Katana::ReportError (GeolibCookInterface &interface, const std::string &message)
	Reports the specified error message to the scene graph at the current scene graph location.
void	Foundry::Katana::ReportWarning (GeolibCookInterface &interface, const std::string &message)
	Reports the specified warning message to the scene graph at the current scene graph location.
FnAttribute::GroupAttribute	Foundry::Katana::MergeImmediateGroupChildren (const std::vector< FnAttribute::GroupAttribute > &attrs)
	Merges the unique children of the specified GroupAttribute.
FnAttribute::GroupAttribute	Foundry::Katana::GetGlobalXFormGroup (const GeolibCookInterface &interface, const std::string &inputLocationPath=std::string(), int inputIndex=kFnKatGeolibDefaultInput)
	Returns the global transform as a GroupAttribute, where the immediate children represent all the entries from `/root` to the leaf which have an `'xform'` attribute present.
float	Foundry::Katana::GetCurrentTime (const GeolibCookInterface &interface)
	Returns the current time from the current Graph State.
float	Foundry::Katana::GetShutterOpen (const GeolibCookInterface &interface)
	Returns the shutter open time from the current Graph State.
float	Foundry::Katana::GetShutterClose (const GeolibCookInterface &interface)
	Returns the shutter close time from the current Graph State.
int	Foundry::Katana::GetNumSamples (const GeolibCookInterface &interface)
	Returns the number of time samples from the current Graph State.
FnAttribute::Attribute	Foundry::Katana::GetGraphStateVariable (const GeolibCookInterface &interface, FnPlatform::StringView variableName)
	Returns the specified variable from the current Graph State.
FnAttribute::DoubleAttribute	Foundry::Katana::GetBoundAttr (const GeolibCookInterface &interface, FnPlatform::StringView inputLocationPath=FnPlatform::StringView(), int inputIndex=kFnKatGeolibDefaultInput)
	Returns the bound attribute at the specified input scene graph location.
void	Foundry::Katana::GetBoundAttrValue (double outMinBound[3], double outMaxBound[3], const FnAttribute::DoubleAttribute &boundAttr, float sampleTime)
	Fills the array's `outMinBound` and `outMaxBound` with the values stored in the DoubleAttribute `boundAttr`.
void	Foundry::Katana::GetTransformedBoundAttrValue (std::vector< BoundPoint > &outPoints, const FnAttribute::DoubleAttribute &boundAttr, float sampleTime, const double xform[16])
	Returns the bounding box specified by the bound attribute `boundAttr` after being transformed by the 4x4 transform matrix `xform`.
void	Foundry::Katana::GetTransformedBoundAttrValue (double outMinBound[3], double outMaxBound[3], const FnAttribute::DoubleAttribute &boundAttr, float sampleTime, const double xform[16])
	Returns the axis-aligned bounding box specified by the bound attribute `boundAttr` after being transformed by the 4 x 4 transform matrix `xform`.
FnAttribute::DoubleAttribute	Foundry::Katana::MergeLocalBoundAttrs (const std::vector< FnAttribute::DoubleAttribute > &boundAttrs)
	Returns a single bound attribute, given a vector of bounds in the same local coordinate system.
FnAttribute::GroupAttribute	Foundry::Katana::FilterNullAttributes (const FnAttribute::GroupAttribute &groupAttr)
	Returns a newly constructed GroupAttribute based on `groupAttr` with all NullAttribute removed.
FnAttribute::GroupAttribute	Foundry::Katana::ResolveReferentialInheritance (const FnGeolibOp::GeolibCookInterface &interface, FnPlatform::StringView keyAttrName, FnPlatform::StringView attrName, const std::string &inputLocationPath=std::string(), int inputIndex=kFnKatGeolibDefaultInput)
	Returns a GroupAttribute which contains the attributes stored at the location contained in the specified attribute `"keyAttrName"`.

Detailed Description

The Op API offers a unified interface for manipulating the scene graph and modifying attributes, something that was previously only possible through a combination of SGGs and AMPs. All of Katana's shipped Ops are written with the Op API.

Utility Functions

The Op API also provides a number of utility functions for a number of common tasks such as obtaining frequently used attributes (such as bounding boxes) and reporting errors to the scene graph. The majority of the utility functions are designed to be used within the context of an Op's cook() function and require a reference to the GeolibCookInterface that has been passed to the cook() function.

Function Documentation

FnAttribute::GroupAttribute Foundry::Katana::FilterNullAttributes ( const FnAttribute::GroupAttribute & groupAttr )

Returns a newly constructed GroupAttribute based on groupAttr with all NullAttribute removed.

Parameters:

groupAttr The GroupAttribute to filter.

Returns:: A new instance of type GroupAttribute which contains all values in groupAttr except NullAttributes.

std::string Foundry::Katana::GetAbsInputLocationPath	(	const GeolibCookInterface &	interface,
		const std::string &	inputLocationPath
	)

Resolves a relative input scene graph location path to an absolute path.

This method cannot be used to query output locations (such as those used with methods such as GeolibCookInterface::createChild()) but those methods that operate on the Op's output such as GeolibCookInterface::getAttr(). If you require the absolute scene graph location path for an output location you should use GetAbsOutputLocationPath().

Parameters:

interface	A reference to a valid GeolibCookInterface object.
inputLocationPath	The relative input scene graph location path.

Returns:: The corresponding absolute location path.

See also:: GetAbsOutputLocationPath()

std::string Foundry::Katana::GetAbsOutputLocationPath	(	const GeolibCookInterface &	interface,
		const std::string &	outputLocationPath
	)

Resolves a relative output scene graph location path to an absolute path.

This method cannot be used to query input locations (such as those used with methods such as GeolibCookInterface::getAttr()) but those methods that operate on the Op's output such as GeolibCookInterface::createChild(). If you require the absolute scene graph location path for an input location you should use GetAbsInputLocationPath().

Parameters:

interface	A reference to a valid GeolibCookInterface object.
outputLocationPath	The relative output scene graph location path.

Returns:: The corresponding absolute location path.

See also:: GetAbsInputLocationPath()

FnAttribute::DoubleAttribute Foundry::Katana::GetBoundAttr	(	const GeolibCookInterface &	interface,
		FnPlatform::StringView	inputLocationPath = `FnPlatform::StringView()`,
		int	inputIndex = `kFnKatGeolibDefaultInput`
	)

Returns the bound attribute at the specified input scene graph location.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
inputLocationPath	The scene graph location to obtain the bound attribute from.
inputIndex	The input index on which to find the scene graph location.

Returns:: A 6-element DoubleAttribute containing the bound attribute or an invalid DoubleAttribute if bounds do not exist at the specified location.

void Foundry::Katana::GetBoundAttrValue	(	double	outMinBound[3],
		double	outMaxBound[3],
		const FnAttribute::DoubleAttribute &	boundAttr,
		float	sampleTime
	)

Fills the array's outMinBound and outMaxBound with the values stored in the DoubleAttribute boundAttr.

Parameters:

outMinBound	A 3-element array that will contain x-min, y-min, z-min.
outMaxBound	A 3-element array that will contain x-max, y-max, z-max.
boundAttr	The bounds attribute to process.
sampleTime	The sample time that the bounds attribute `boundAttr` should be sampled at.

float Foundry::Katana::GetCurrentTime ( const GeolibCookInterface & interface )

Returns the current time from the current Graph State.

Parameters:

interface A reference to a valid GeolibCookInterface object.

Returns:: The current time.

FnAttribute::Attribute Foundry::Katana::GetGlobalAttr	(	const GeolibCookInterface &	interface,
		FnPlatform::StringView	name,
		FnPlatform::StringView	location = `FnPlatform::StringView()`,
		int	inputIndex = `kFnKatGeolibDefaultInput`
	)

Returns attribute from the input scene, including inherited attributes.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
name	The name of the attribute.
location	The location at which the attribute should be found.
inputIndex	The input index of which to search for the input scene graph location.

Returns:: The specified attribute at the given location including inherited attributes.

FnAttribute::GroupAttribute Foundry::Katana::GetGlobalXFormGroup	(	const GeolibCookInterface &	interface,
		const std::string &	inputLocationPath = `std::string()`,
		int	inputIndex = `kFnKatGeolibDefaultInput`
	)

Returns the global transform as a GroupAttribute, where the immediate children represent all the entries from /root to the leaf which have an 'xform' attribute present.

Note:: If a collapsed 4x4 transform matrix is required pass the result of this function to the FnGeolibServices::FnXFormUtil::CalcTransformMatrix..() functions.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
inputLocationPath	The input scene graph location to retrieve the global transform from.
inputIndex	The input index from which to retrieve the scene graph location.

Returns:: The global transform at the specified location.

FnAttribute::Attribute Foundry::Katana::GetGraphStateVariable	(	const GeolibCookInterface &	interface,
		FnPlatform::StringView	variableName
	)

Returns the specified variable from the current Graph State.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
variableName	The name of the graph state variable.

Returns:: The Graph State Variable specified by variableName.

std::string Foundry::Katana::GetInputLocationType	(	const GeolibCookInterface &	interface,
		FnPlatform::StringView	location = `FnPlatform::StringView()`,
		int	inputIndex = `kFnKatGeolibDefaultInput`
	)

Returns the location type for specified location on the corresponding GeolibCookInterfaces's input.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
location	The scene graph location path.
inputIndex	The input index on which to retrieve the specified scene graph location path.

Returns:: The location's 'type' attribute. If type attribute is invalid an empty string will be returned, if it is not set then group will be returned by default.

int Foundry::Katana::GetNumSamples ( const GeolibCookInterface & interface )

Returns the number of time samples from the current Graph State.

Parameters:

interface A reference to a valid GeolibCookInterface object.

Returns:: The number of time samples.

float Foundry::Katana::GetShutterClose ( const GeolibCookInterface & interface )

Returns the shutter close time from the current Graph State.

Parameters:

interface A reference to a valid GeolibCookInterface object.

Returns:: The shutter close time.

float Foundry::Katana::GetShutterOpen ( const GeolibCookInterface & interface )

Returns the shutter open time from the current Graph State.

Parameters:

interface A reference to a valid GeolibCookInterface object.

Returns:: The shutter open time.

void Foundry::Katana::GetTransformedBoundAttrValue	(	std::vector< BoundPoint > &	outPoints,
		const FnAttribute::DoubleAttribute &	boundAttr,
		float	sampleTime,
		const double	xform[16]
	)

Returns the bounding box specified by the bound attribute boundAttr after being transformed by the 4x4 transform matrix xform.

Parameters:

[out]	outPoints	An empty vector that will filled with the 8 points of the transformed bounding box.
	boundAttr	A 6-element DoubleAttribute specifying the bounding box to be transformed.
	sampleTime	The sample time that the bounds attribute `boundAttr` should be sampled at.
	xform	A 4x4 transform matrix by which `boundAttr` will be transformed.

See also:: BoundPoint

void Foundry::Katana::GetTransformedBoundAttrValue	(	double	outMinBound[3],
		double	outMaxBound[3],
		const FnAttribute::DoubleAttribute &	boundAttr,
		float	sampleTime,
		const double	xform[16]
	)

Returns the axis-aligned bounding box specified by the bound attribute boundAttr after being transformed by the 4 x 4 transform matrix xform.

Parameters:

[out]	outMinBound	A 3-element array that will contain the transformed x-min, y-min, z-min.
[out]	outMaxBound	A 3-element array that will contain the transformed x-max, y-max, z-max.
	boundAttr	A 6-element DoubleAttribute specifying the bounding box to be transformed.
	sampleTime	The sample time that the bounds attribute `boundAttr` should be sampled at.
	xform	A 4x4 transform matrix by which `boundAttr` will be transformed.

FnAttribute::GroupAttribute Foundry::Katana::MergeImmediateGroupChildren ( const std::vector< FnAttribute::GroupAttribute > & attrs )

Merges the unique children of the specified GroupAttribute.

The left-most definition for a child attribute "wins", and the left-most attribute ordering is preserved.

Note:: This matches the combination logic used in Merge for lightList, renderSettings.outputs, relativeScopedCoordinateSystems, collections, etc.

Parameters:

attrs A vector of GroupAttribute to be merged.

Returns:: A GroupAttribute containing the merged GroupAttributes.

FnAttribute::DoubleAttribute Foundry::Katana::MergeLocalBoundAttrs ( const std::vector< FnAttribute::DoubleAttribute > & boundAttrs )

Returns a single bound attribute, given a vector of bounds in the same local coordinate system.

If any of the bounds are multi-sampled the result will promoted to a multi-sampled attribute. The resulting time samples will be the union of the supplied sample times. Missing values will be synthesized using either DoubleAttribute::fillInterpSample(). This is the same combination logic used by Merge Op's sumBounds option.

Parameters:

boundAttrs A vector of 6-element bound attributes in the same local coordinate system to be merged.

Returns:: The merged bound attributes.

void Foundry::Katana::RenameChild	(	GeolibCookInterface &	interface,
		FnPlatform::StringView	src,
		FnPlatform::StringView	dst
	)

Renames the specified child.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
src	The name of the child to rename.
dst	The new name of the child.

void Foundry::Katana::ReportError	(	GeolibCookInterface &	interface,
		const std::string &	message
	)

Reports the specified error message to the scene graph at the current scene graph location.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
message	The error message.

void Foundry::Katana::ReportWarning	(	GeolibCookInterface &	interface,
		const std::string &	message
	)

Reports the specified warning message to the scene graph at the current scene graph location.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
message	The warning message.

FnAttribute::GroupAttribute Foundry::Katana::ResolveReferentialInheritance	(	const FnGeolibOp::GeolibCookInterface &	interface,
		FnPlatform::StringView	keyAttrName,
		FnPlatform::StringView	attrName,
		const std::string &	inputLocationPath = `std::string()`,
		int	inputIndex = `kFnKatGeolibDefaultInput`
	)

Returns a GroupAttribute which contains the attributes stored at the location contained in the specified attribute "keyAttrName".

Note:: Currently attrName is ignored.

Parameters:

interface	A reference to a valid GeolibCookInterface object.
keyAttrName	The attribute name on the input scene graph location that contains the reference location(s).
attrName	The attribute(s) that will be merged with those at the referenced location. If an empty string is specified then all attributes will be used.
inputLocationPath	The input scene graph location path at which `attrName` will be found.
inputIndex	The input index on which `inputLocationPath` can be found.

Returns:: A GroupAttribute which is a combination of those attributes at the location specified in keyAttrName and those attributes stored under the attribute specified at attrName.

Op API

Classes

Functions

Detailed Description

Function Documentation