Attribute suite. More...

#include <FnAttributeSuite.h>

Public Attributes
void(*	disableRefCounting )(FnAttributeHandle handle)
uint8_t(*	isRefCounted )(FnAttributeHandle handle)
void(*	dispose )(FnAttributeHandle handle)
FnAttributeSampleAccessor (	createAccessor )(FnAttributeHandle attr, FnKatAttributeType type, FnKatAttributeSampleAccessorOptions options, struct FnAttributeSampleAccessorStorage *storage)
void(*	retainAccessor )(FnAttributeSampleAccessor *accessor)
void(*	releaseAccessor )(FnAttributeSampleAccessor *accessor)
FnAttributeHandle(*	createIntAttrFactory )(const float times, int64_t timeCount, const int32_t values, int64_t valueCount, int64_t tupleSize, void context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)
FnAttributeHandle(*	createFloatAttrFactory )(const float times, int64_t timeCount, const float values, int64_t valueCount, int64_t tupleSize, void context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)
FnAttributeHandle(*	createDoubleAttrFactory )(const float times, int64_t timeCount, const double values, int64_t valueCount, int64_t tupleSize, void context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)
FnAttributeHandle(*	createStringAttrFactory )(const float times, int64_t timeCount, const char *values, int64_t valueCount, int64_t tupleSize, void context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)
uint64_t(*	getSize )(FnAttributeHandle handle)
uint64_t(*	getTotalSize )()

Detailed Description

Attribute suite.

This suite provides functions needed by a plugin for creating and querying attributes.

Any FnAttributeHandle instance returned from a function in this suite will already have a single reference. It is the responsibility of the caller to release the attribute by calling releaseAttr().

Member Data Documentation

FnAttributeSampleAccessor*(* FnAttributeHostSuite::createAccessor)(FnAttributeHandle attr, FnKatAttributeType type, FnKatAttributeSampleAccessorOptions options, struct FnAttributeSampleAccessorStorage *storage)

Creates a Sample Accessor object to access the sample data of an FnAttribute.

Parameters:

attr	handle to the attribute whose data is to be accessed.
type	type of attribute whose sample data is to be accessed.
options	bitset of accessor creation options.
storage	pointer to caller-owned memory to be used for auxiliary storage.

Returns:: a pointer to a Sample Accessor object, or NULL on error.

FnAttributeHandle(* FnAttributeHostSuite::createDoubleAttrFactory)(const float *times, int64_t timeCount, const double **values, int64_t valueCount, int64_t tupleSize, void *context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)

Creates and returns instances of DoubleAttributes.

This function can be used to create DoubleAttributes where the caller has an array or arrays of values available.

If the time sample array (times) is set to FnAttributeSuite::kOne then the factory will provide a default single time sample at 0.0f and interpret values as a const double* rather than const double**.

If context and freeOwnedDataFunc are supplied then the factory will return a 'zero copy' attribute instance. Zero copy attributes take ownership of the data pointed to by the values array. It does not take ownership of the times or values arrays themselves, just the data pointed to by values. When the attribute is deallocated freeOwnedDataFunc will be called passing context as an argument. This function should free any memory that was allocated to store the data pointed to by the values array.

Parameters:

times	array of floating point values speciying the sample times defined in values.
timeCount	the number of float values in in the times array.
values	an array of timeCount pointers which point to the values for each corresponding time sample.
valueCount	the number of values in each array pointed to by the pointers in the values array.
tupleSize	the number of data values per tuple.
context	if specified a pointer that will be passed to the freeOwnedDataFunc when the the attribute is deallocated.
freeOwnedDataFunc	pointer to function that will be called when the attribute is to be deallocated.

FnAttributeHandle(* FnAttributeHostSuite::createFloatAttrFactory)(const float *times, int64_t timeCount, const float **values, int64_t valueCount, int64_t tupleSize, void *context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)

Creates and returns instances of FloatAttributes.

This function can be used to create FloatAttribute where the caller has an array or arrays of values available.

If the time sample array (times) is set to FnAttributeSuite::kOne then the factory will provide a default single time sample at 0.0f and interpret values as a const float* rather than const float**.

If context and freeOwnedDataFunc are supplied then the factory will return a 'zero copy' attribute instance. Zero copy attributes take ownership of the data pointed to by the values array. It does not take ownership of the times or values arrays themselves, just the data pointed to by values. When the attribute is deallocated freeOwnedDataFunc will be called passing context as an argument. This function should free any memory that was allocated to store the data pointed to by the values array.

Parameters:

times	array of floating point values speciying the sample times defined in values.
timeCount	the number of float values in in the times array.
values	an array of timeCount pointers which point to the values for each corresponding time sample.
valueCount	the number of values in each array pointed to by the pointers in the values array.
tupleSize	the number of data values per tuple.
context	if specified a pointer that will be passed to the freeOwnedDataFunc when the the attribute is deallocated.
freeOwnedDataFunc	pointer to function that will be called when the attribute is to be deallocated.

FnAttributeHandle(* FnAttributeHostSuite::createIntAttrFactory)(const float *times, int64_t timeCount, const int32_t **values, int64_t valueCount, int64_t tupleSize, void *context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)

Creates and returns instances of IntAttributes.

This function can be used to create IntAttributes where the caller has an array or arrays of values available.

If the time sample array (times) is set to FnAttributeSuite::kOne then the factory will provide a default single time sample at 0.0f and interpret values as a const int* rather than const int**.

If context and freeOwnedDataFunc are supplied then the factory will return a 'zero copy' attribute instance. Zero copy attributes take ownership of the data pointed to by the values array. It does not take ownership of the times or values arrays themselves, just the data pointed to by values. When the attribute is deallocated freeOwnedDataFunc will be called passing context as an argument. This function should free any memory that was allocated to store the data pointed to by the values array.

Parameters:

times	array of floating point values speciying the sample times defined in values.
timeCount	the number of float values in in the times array.
values	an array of timeCount pointers which point to the values for each corresponding time sample.
valueCount	the number of values in each array pointed to by the pointers in the values array.
tupleSize	the number of data values per tuple.
context	if specified a pointer that will be passed to the freeOwnedDataFunc when the the attribute is deallocated.
freeOwnedDataFunc	pointer to function that will be called when the attribute is to be deallocated.

FnAttributeHandle(* FnAttributeHostSuite::createStringAttrFactory)(const float *times, int64_t timeCount, const char ***values, int64_t valueCount, int64_t tupleSize, void *context, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc)

Creates and returns instances of StringAttributes.

This function can be used to create StringAttributes where the caller has an array or arrays of values available.

If the time sample array (times) is set to FnAttributeSuite::kOne then the factory will provide a default single time sample at 0.0f and interpret values as a const char** rather than const char***.

If context and freeOwnedDataFunc are supplied then the factory will return a 'zero copy' attribute instance. Zero copy attributes take ownership of the data pointed to by the values array. It does not take ownership of the times or values arrays themselves, just the data pointed to by values. When the attribute is deallocated freeOwnedDataFunc will be called passing context as an argument. This function should free any memory that was allocated to store the data pointed to by the values array.

Parameters:

times	array of floating point values speciying the sample times defined in values.
timeCount	the number of float values in in the times array.
values	an array of timeCount pointers which point to the values for each corresponding time sample.
valueCount	the number of values in each array pointed to by the pointers in the values array.
tupleSize	the number of data values per tuple.
context	if specified a pointer that will be passed to the freeOwnedDataFunc when the the attribute is deallocated.
freeOwnedDataFunc	pointer to function that will be called when the attribute is to be deallocated.

void(* FnAttributeHostSuite::disableRefCounting)(FnAttributeHandle handle)

Disables reference counting for the specified FnAttribute.

Certain attributes are pre-allocated at boot for performance reasons. For these attributes (and other attributes with a similar allocation strategy) reference counting is not applicable and can be disabled.

This function must be called prior to any calls to retainAttr or releaseAttr for a given attribute. This function is not thread safe and is intended to be called during serial sections of code during attribute initialization.

Note: This function is not recommended for general usage.

Parameters:

handle handle to the attribute to disable reference counting.

void(* FnAttributeHostSuite::dispose)(FnAttributeHandle handle)

Deallocate the specified handle.

Once this function returns the attribute pointed to by handle is no longer valid for use.

Parameters:

handle the handle to delete.

uint64_t(* FnAttributeHostSuite::getSize)(FnAttributeHandle handle)

Returns the total memory in bytes that was allocated when the attribute was created.

For GroupAttribute, this value includes, apart from the allocated size of the group internals, also the size of all its children. If an attribute is included more than once in the group, the size of said attribute will be added just as many times as it appears.

Releasing the last reference to the attribute will potentially free as much data as returned by this function.

Note:: Katana may optimize the storage of certain attributes by caching small, frequently-used values internally. In these cases, it will not be possible to release the last reference.

Parameters:

handle Handle to the attribute.