Functions
AtArray API

AtArray objects construction and manipulation. More...

Functions

AI_API AtArray * AiArray (uint32_t nelements, uint8_t nkeys, int type,...)
 Create an array and initialize it with supplied data. More...
 
AI_API AtArray * AiArrayAllocate (uint32_t nelements, uint8_t nkeys, uint8_t type)
 Create an empty (uninitialized) array of the specified type. More...
 
AI_API void AiArrayDestroy (AtArray *array)
 Deallocate an array object. More...
 
AI_API AtArray * AiArrayConvert (uint32_t nelements, uint8_t nkeys, uint8_t type, const void *data)
 Create an array and initialize it from an existing data buffer. More...
 
AI_API void AiArrayResize (AtArray *array, uint32_t nelements, uint8_t nkeys)
 Resize an existing array contents in place. More...
 
AI_API AtArray * AiArrayCopy (const AtArray *array)
 Create a copy of an array. More...
 
AI_API bool AiArraySetKey (AtArray *array, uint8_t key, const void *data)
 Initializes data for all the elements in a specific key of an array. More...
 
AI_API void * AiArrayMap (AtArray *array)
 Obtains a pointer to the internal array data for construction. More...
 
AI_API void * AiArrayMapKey (AtArray *array, uint8_t key)
 Obtains a pointer to a specific key in the internal array data for construction. More...
 
AI_API void AiArrayUnmap (AtArray *array)
 Notifies the array that construction is finished. More...
 
AI_API AI_PURE uint32_t AiArrayGetNumElements (const AtArray *array)
 Get the number of elements on each key of the array. More...
 
AI_API AI_PURE uint8_t AiArrayGetNumKeys (const AtArray *array)
 Get the number of keys. More...
 
AI_API AI_PURE uint8_t AiArrayGetType (const AtArray *array)
 Get the type of array elements. More...
 
AI_API AI_PURE size_t AiArrayGetDataSize (const AtArray *array)
 Get the total size in bytes of the data buffer for this array. More...
 
AI_API AI_PURE size_t AiArrayGetKeySize (const AtArray *array)
 Get the total size in bytes of the data for one key. More...
 
AI_API AI_PURE AtVector AiArrayInterpolateVec (const AtArray *array, float time, uint32_t idx)
 Interpolate a vector at a given time from an array. More...
 
AI_API AI_PURE AtRGB AiArrayInterpolateRGB (const AtArray *array, float time, uint32_t idx)
 Interpolate a color at a given time from an array. More...
 
AI_API AI_PURE AtRGBA AiArrayInterpolateRGBA (const AtArray *array, float time, uint32_t idx)
 Interpolate an AtRGBA at a given time from an array. More...
 
AI_API AI_PURE float AiArrayInterpolateFlt (const AtArray *array, float time, uint32_t idx)
 Interpolate a float at a given time from an array. More...
 
AI_API AI_PURE AtMatrix AiArrayInterpolateMtx (const AtArray *array, float time, uint32_t idx)
 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 AiArrayGetVec2(a, i)   AiArrayGetVec2Func (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetVec(a, i)   AiArrayGetVecFunc (a,i,__AI_FILE__,__AI_LINE__)
 
#define AiArrayGetMtx(a, i)   AiArrayGetMtxFunc (a,i,__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. If the write was succesful, these functions will return true, otherwise a detailed error message will be logged and false will be returned.

#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 AiArraySetVec2(a, i, val)   AiArraySetVec2Func (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

AtArray objects construction and manipulation.

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 ( uint32_t  nelements,
uint8_t  nkeys,
int  type,
  ... 
)

Create an array and initialize it with supplied data.

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

Usage example:

1 AtArray* a = AiArray(4, 1, AI_TYPE_FLOAT, 10.f, 11.f, 12.f, 13.f);
2 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 ( uint32_t  nelements,
uint8_t  nkeys,
uint8_t  type 
)

Create an empty (uninitialized) array of the specified type.

The returned array has data fully allocated (but not initialized) and its elements can be set with the ArraySet*() functions/macros.

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 array 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 ( uint32_t  nelements,
uint8_t  nkeys,
uint8_t  type,
const void *  data 
)

Create an array and initialize it from an existing data buffer.

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

Usage example:

1 float data[4];
2 data[0] = 10.f;
3 data[1] = 11.f;
4 data[2] = 12.f;
5 data[3] = 13.f;
6 AtArray* a = AiArrayConvert(4, 1, AI_TYPE_FLOAT, data);
7 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 void AiArrayResize ( AtArray *  array,
uint32_t  nelements,
uint8_t  nkeys 
)

Resize an existing array contents in place.

This function will resize the array keeping the current contents.

Parameters
arrayarray to resize
nelementsnumber of elements per motion key
nkeysnumber of motion keys
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,
uint8_t  key,
const void *  data 
)

Initializes data for all the elements in a specific 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:

1 // create an array of two motion keys, three elements per key
2 AtArray* array = AiArray(3, 2, AI_TYPE_FLOAT, 1.0f, 1.0f, 1.0f, 2.0f, 2.0f, 2.0f);
3 // at this point, the array contains: 1, 1, 1, 2, 2, 2
4 
5 float newdata[3] = { 9.0f, 9.0f, 9.0f };
6 bool success = AiArraySetKey(array, 1, newdata);
7 // 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->getNumElements() * sizeof(type of elements in array)
Returns
true if the write operation was successful
AI_API void* AiArrayMap ( AtArray *  array)

Obtains a pointer to the internal array data for construction.

Return a pointer to the internal buffer storage for this array data. This pointer can be used to read or write directly into the array buffer, avoiding an extra memory copy, and it has to be unmap'ed when writing is finished.

NOTE: The array will be unmap'ed automatically when set to a node parameter.

Parameters
arrayarray to write to
Returns
pointer to the internal array data buffer
AI_API void* AiArrayMapKey ( AtArray *  array,
uint8_t  key 
)

Obtains a pointer to a specific key in the internal array data for construction.

Return a pointer to a specific key in the internal buffer storage for this array data. This pointer can be used to read or write directly into the key data, avoiding an extra memory copy, and it has to be unmap'ed when writing is finished.

NOTE: The array will be unmap'ed automatically when set to a node parameter.

Parameters
arrayarray to write to
keyindex of the specific key to read from/write to
Returns
pointer to the specific key in the internal array data buffer
AI_API void AiArrayUnmap ( AtArray *  array)

Notifies the array that construction is finished.

After calling this function, any pointers previously obtained with AiArrayMap or AiArrayMapKey will no longer be valid.

NOTE: The array will be unmap'ed automatically when set to a node parameter.

Parameters
arrayarray to notify about the end of construction
AI_API AI_PURE uint32_t AiArrayGetNumElements ( const AtArray *  array)

Get the number of elements on each key of the array.

Parameters
arraysource array
Returns
number of elements per array key
AI_API AI_PURE uint8_t AiArrayGetNumKeys ( const AtArray *  array)

Get the number of keys.

Parameters
arraysource array
Returns
number of keys for this array
AI_API AI_PURE uint8_t AiArrayGetType ( const AtArray *  array)

Get the type of array elements.

Parameters
arraysource array
Returns
type of elements in this array
AI_API AI_PURE size_t AiArrayGetDataSize ( const AtArray *  array)

Get the total size in bytes of the data buffer for this array.

Parameters
arraysource array
Returns
size in bytes of the whole data
AI_API AI_PURE size_t AiArrayGetKeySize ( const AtArray *  array)

Get the total size in bytes of the data for one key.

Parameters
arraysource array
Returns
size in bytes of one key
AI_API AI_PURE AtVector AiArrayInterpolateVec ( const AtArray *  array,
float  time,
uint32_t  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 AI_PURE AtRGB AiArrayInterpolateRGB ( const AtArray *  array,
float  time,
uint32_t  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 AI_PURE AtRGBA AiArrayInterpolateRGBA ( const AtArray *  array,
float  time,
uint32_t  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 AI_PURE float AiArrayInterpolateFlt ( const AtArray *  array,
float  time,
uint32_t  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 AI_PURE AtMatrix AiArrayInterpolateMtx ( const AtArray *  array,
float  time,
uint32_t  index 
)

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
Returns
value of the array item, interpolated to the given time

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com