Data Structures | Typedefs | Functions
AtArray API

Data Structures

struct  AtArray
 Generic array data type. More...
 

Typedefs

typedef struct AtArray AtArray
 Generic array data type.
 

Functions

AI_API AtArrayAiArray (AtUInt32 nelements, AtByte nkeys, AtByte type,...)
 Create an array with the supplied data. More...
 
AI_API AtArrayAiArrayAllocate (AtUInt32 nelements, AtByte nkeys, AtByte type)
 Create an empty array of the specified type. More...
 
AI_API void AiArrayDestroy (AtArray *array)
 Deallocate an array object. More...
 
AI_API AtArrayAiArrayConvert (AtUInt32 nelements, AtByte nkeys, AtByte type, const void *data)
 Create an array structure from the corresponding data buffer. More...
 
AI_API AtArrayAiArrayModify (AtArray *array, AtUInt32 nelements, AtByte nkeys, AtByte type,...)
 Modify an existing array's contents on the fly. More...
 
AI_API AtArrayAiArrayCopy (const AtArray *array)
 Create a copy of an array. More...
 
AI_API bool AiArraySetKey (AtArray *array, AtByte key, const void *data)
 Writes all the elements for a given key of an array. More...
 
AI_API AtPoint AiArrayInterpolatePnt (const AtArray *array, float time, AtUInt32 idx)
 Interpolate a point at a given time from an array. More...
 
AI_API AtVector AiArrayInterpolateVec (const AtArray *array, float time, AtUInt32 idx)
 Interpolate a vector at a given time from an array. More...
 
AI_API AtColor AiArrayInterpolateRGB (const AtArray *array, float time, AtUInt32 idx)
 Interpolate a color at a given time from an array. More...
 
AI_API AtRGBA AiArrayInterpolateRGBA (const AtArray *array, float time, AtUInt32 idx)
 Interpolate an AtRGBA at a given time from an array. More...
 
AI_API float AiArrayInterpolateFlt (const AtArray *array, float time, AtUInt32 idx)
 Interpolate a float at a given time from an array. More...
 
AI_API void AiArrayInterpolateMtx (const AtArray *array, float time, AtUInt32 idx, AtMatrix result)
 Interpolate a matrix at a given time from an array. More...
 

AtArray Getters

The following getter functions return the i'th element in an array of the given type. In case of out-of-bounds access, an error message is generated with the source code location of the offending call.

Note that, for ease of use, these are actually macros, which are shorter to type than the full functions. The actual functions can be found in ai_array.h.

#define AiArrayGetBool(a, i)   AiArrayGetBoolFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetByte(a, i)   AiArrayGetByteFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetInt(a, i)   AiArrayGetIntFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetUInt(a, i)   AiArrayGetUIntFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetFlt(a, i)   AiArrayGetFltFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetRGB(a, i)   AiArrayGetRGBFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetRGBA(a, i)   AiArrayGetRGBAFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetPnt(a, i)   AiArrayGetPntFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetPnt2(a, i)   AiArrayGetPnt2Func (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetVec(a, i)   AiArrayGetVecFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetMtx(a, i, out)   AiArrayGetMtxFunc (a,i,out,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetStr(a, i)   AiArrayGetStrFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetPtr(a, i)   AiArrayGetPtrFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetArray(a, i)   AiArrayGetArrayFunc(a,i,__AI_FILE__,__AI_LINE__)
 

AtArray Setters

The following functions write an element of a given type into the i'th position in an array.

#define AiArraySetBool(a, i, val)   AiArraySetBoolFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetByte(a, i, val)   AiArraySetByteFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetInt(a, i, val)   AiArraySetIntFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetUInt(a, i, val)   AiArraySetUIntFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetFlt(a, i, val)   AiArraySetFltFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetRGB(a, i, val)   AiArraySetRGBFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetRGBA(a, i, val)   AiArraySetRGBAFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetPnt(a, i, val)   AiArraySetPntFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetPnt2(a, i, val)   AiArraySetPnt2Func (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetVec(a, i, val)   AiArraySetVecFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetMtx(a, i, val)   AiArraySetMtxFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetStr(a, i, val)   AiArraySetStrFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetPtr(a, i, val)   AiArraySetPtrFunc (a,i,val,__AI_FILE__,__AI_LINE__)
 
#define AiArraySetArray(a, i, val)   AiArraySetArrayFunc(a,i,val,__AI_FILE__,__AI_LINE__)
 

Detailed Description

The AtArray object encapsulates an array of any of the Arnold built-in data types like AI_TYPE_BYTE, AI_TYPE_FLOAT, AI_TYPE_STRING, etc. Its API has easy-to-use accessor functions for reading and writing elements, and there are a number of functions for manipulating arrays (such as copying them). An AtArray is specified by the element data type, the number of motion keys in the array, and the number of elements per motion key. The data is grouped together by motion keys.

Function Documentation

AI_API AtArray* AiArray ( AtUInt32  nelements,
AtByte  nkeys,
AtByte  type,
  ... 
)

Create an array with the supplied data.

This function should always have nelements * nkeys number of data elements. To create an array without supplying any data see AiArrayAllocate() instead. To create an array out of an existing memory buffer, use AiArrayConvert().

Usage example:

AtArray* a = AiArray(4, 1, AI_TYPE_FLOAT, 10.f, 11.f, 12.f, 13.f);
assert(AiArrayGetFlt(a,3) == 13.f);
Parameters
nelementsnumber of elements per motion key in the new array
nkeysnumber of motion keys in the new array
typearray type (AI_TYPE_BYTE, etc.)
...array data
Returns
pointer to the new array filled with data, or NULL if the array couldn't be allocated
See Also
AiArrayAllocate
AI_API AtArray* AiArrayAllocate ( AtUInt32  nelements,
AtByte  nkeys,
AtByte  type 
)

Create an empty array of the specified type.

The returned array has been fully-allocated and its elements can be set with the AiArraySet*() functions/macros. The allocated data will be initialized to zero.

Parameters
nelementsnumber of elements per motion key in the new array
nkeysnumber of motion keys in the new array
typetype of the elements in the new array (AI_TYPE_BYTE, etc.)
Returns
pointer to an allocated AtArray of nelements * nkeys elements, or NULL if the array couldn't be allocated
See Also
AiArray
AI_API void AiArrayDestroy ( AtArray array)

Deallocate an array object.

Parameters
arraythe array to destroy
AI_API AtArray* AiArrayConvert ( AtUInt32  nelements,
AtByte  nkeys,
AtByte  type,
const void *  data 
)

Create an array structure from the corresponding data buffer.

This is the recommended constructor when programmatically creating arrays of arbitrary size. For on-the-fly creation of small arrays of known values, the AiArray() constructor can also be used.

Usage example:

float data[4];
data[0] = 10.f;
data[1] = 11.f;
data[2] = 12.f;
data[3] = 13.f;
assert(AiArrayGetFlt(a,3) == 13.f);
Parameters
nelementsnumber of elements per motion key
nkeysnumber of motion keys
typeelement type
datainput data buffer
Returns
pointer to the new array filled with data, or NULL if the array couldn't be allocated
AI_API AtArray* AiArrayModify ( AtArray array,
AtUInt32  nelements,
AtByte  nkeys,
AtByte  type,
  ... 
)

Modify an existing array's contents on the fly.

This function will replace the contents of the existing array with the supplied data. The existing array will not be resized nor will its type be converted to match the supplied data.

Parameters
arrayarray to overwrite
nelementsnumber of elements per motion key
nkeysnumber of motion keys
typeelement type
...array data
Returns
the input array with modified data
AI_API AtArray* AiArrayCopy ( const AtArray array)

Create a copy of an array.

Parameters
arraysource array to copy
Returns
new array which is a copy of the source array, or NULL if there was an error
AI_API bool AiArraySetKey ( AtArray array,
AtByte  key,
const void *  data 
)

Writes all the elements for a given key of an array.

The data buffer will be copied into the appropiate place in the array, overwriting the existing values in memory. The values passed in aren't required later on; data can be safely destroyed.

Usage example:

// create an array of two motion keys, three elements per key
AtArray* array = AiArray(3, 2, AI_TYPE_FLOAT, 1.0f, 1.0f, 1.0f, 2.0f, 2.0f, 2.0f);
// at this point, the array contains: 1, 1, 1, 2, 2, 2
float newdata[3] = { 9.0f, 9.0f, 9.0f };
bool success = AiArraySetKey(array, 1, newdata);
// at this point, the array contains: 1, 1, 1, 9, 9, 9
Parameters
arrayarray to write to
keyvalue of the key we want to write to (must be in 0 .. array->nkeys - 1)
datainput data buffer, with a size of exactly array->nelements * sizeof(type of elements in array)
Returns
TRUE if the write operation was successful
AI_API AtPoint AiArrayInterpolatePnt ( const AtArray array,
float  time,
AtUInt32  index 
)

Interpolate a point at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
Returns
value of the array item, interpolated to the given time
AI_API AtVector AiArrayInterpolateVec ( const AtArray array,
float  time,
AtUInt32  index 
)

Interpolate a vector at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
Returns
value of the array item, interpolated to the given time
AI_API AtColor AiArrayInterpolateRGB ( const AtArray array,
float  time,
AtUInt32  index 
)

Interpolate a color at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
Returns
value of the array item, interpolated to the given time
AI_API AtRGBA AiArrayInterpolateRGBA ( const AtArray array,
float  time,
AtUInt32  index 
)

Interpolate an AtRGBA at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
Returns
value of the array item, interpolated to the given time
AI_API float AiArrayInterpolateFlt ( const AtArray array,
float  time,
AtUInt32  index 
)

Interpolate a float at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
Returns
value of the array item, interpolated to the given time
AI_API void AiArrayInterpolateMtx ( const AtArray array,
float  time,
AtUInt32  index,
AtMatrix  result 
)

Interpolate a matrix at a given time from an array.

Parameters
arraysource array
timetime to calculate the interpolation for the array item
indexindex in the array of the element to interpolate
[out]resultvalue of the array item, interpolated to the given time

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com
Generated for Arnold 4.0.14.0 by Doxygen 1.8.3.1