AtArray API

AtArray objects construction and manipulation. More...

Data Structures
struct	POD_tempf2
struct	POD_tempf3
struct	POD_tempf4

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...

Variables
float	POD_tempf2::f [2]
float	POD_tempf3::f [3]
float	POD_tempf4::f [4]

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
AI_API AI_PURE bool	AiArrayGetBool (const AtArray *a, uint32_t i)
AI_API AI_PURE uint8_t	AiArrayGetByte (const AtArray *a, uint32_t i)
AI_API AI_PURE int	AiArrayGetInt (const AtArray *a, uint32_t i)
AI_API AI_PURE uint32_t	AiArrayGetUInt (const AtArray *a, uint32_t i)
AI_API AI_PURE float	AiArrayGetFlt (const AtArray *a, uint32_t i)
AI_API AI_PURE AtRGB	AiArrayGetRGB (const AtArray *a, uint32_t i)
AI_API AI_PURE AtRGBA	AiArrayGetRGBA (const AtArray *a, uint32_t i)
AI_API AI_PURE AtVector2	AiArrayGetVec2 (const AtArray *a, uint32_t i)
AI_API AI_PURE AtVector	AiArrayGetVec (const AtArray *a, uint32_t i)
AI_API AI_PURE AtMatrix	AiArrayGetMtx (const AtArray *a, uint32_t i)
AI_API AI_PURE AtString	AiArrayGetStr (const AtArray *a, uint32_t i)
AI_API AI_PURE void *	AiArrayGetPtr (const AtArray *a, uint32_t i)
AI_API AI_PURE AtArray *	AiArrayGetArray (const AtArray *a, uint32_t i)

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.
AI_API bool	AiArraySetBool (AtArray *a, uint32_t i, bool val)
AI_API bool	AiArraySetByte (AtArray *a, uint32_t i, uint8_t val)
AI_API bool	AiArraySetInt (AtArray *a, uint32_t i, int val)
AI_API bool	AiArraySetUInt (AtArray *a, uint32_t i, uint32_t val)
AI_API bool	AiArraySetFlt (AtArray *a, uint32_t i, float val)
AI_API bool	AiArraySetRGB (AtArray *a, uint32_t i, AtRGB val)
AI_API bool	AiArraySetRGBA (AtArray *a, uint32_t i, AtRGBA val)
AI_API bool	AiArraySetVec2 (AtArray *a, uint32_t i, AtVector2 val)
AI_API bool	AiArraySetVec (AtArray *a, uint32_t i, AtVector val)
AI_API bool	AiArraySetMtx (AtArray *a, uint32_t i, AtMatrix val)
AI_API bool	AiArraySetStr (AtArray *a, uint32_t i, AtString val)
AI_API bool	AiArraySetPtr (AtArray *a, uint32_t i, void *val)
AI_API bool	AiArraySetArray (AtArray *a, uint32_t i, AtArray *val)
bool	AiArraySetStr (AtArray *a, uint32_t i, const char *val)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector v1)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3, AtVector v4)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3, AtVector v4, AtVector v5)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3, AtVector2 v4)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3, AtVector2 v4, AtVector2 v5)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGB v1)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3, AtRGB v4)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3, AtRGB v4, AtRGB v5)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3, AtRGBA v4)
AtArray *	AiArray (uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3, AtRGBA v4, AtRGBA v5)

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

AiArray()

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:

AtArray* a = AiArray(4, 1, AI_TYPE_FLOAT, 10.f, 11.f, 12.f, 13.f);
assert(AiArrayGetFlt(a,3) == 13.f);

Parameters

nelements	number of elements per motion key in the new array
nkeys	number of motion keys in the new array
type	array 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

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.

Parameters

nelements	number of elements per motion key in the new array
nkeys	number of motion keys in the new array
type	type 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

AiArrayDestroy()

AI_API void AiArrayDestroy

(

AtArray *

array

)

Deallocate an array object.

Parameters

array

the array to destroy

AiArrayConvert()

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:

float data[4];
data[0] = 10.f;
data[1] = 11.f;
data[2] = 12.f;
data[3] = 13.f;
AtArray* a = AiArrayConvert(4, 1, AI_TYPE_FLOAT, data);
assert(AiArrayGetFlt(a,3) == 13.f);

Parameters

nelements	number of elements per motion key
nkeys	number of motion keys
type	element type
data	input data buffer

Returns

pointer to the new array filled with data, or NULL if the array couldn't be allocated

AiArrayResize()

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

array	array to resize
nelements	number of elements per motion key
nkeys	number of motion keys

AiArrayCopy()

AI_API AtArray * AiArrayCopy

(

const AtArray *

array

)

Create a copy of an array.

Parameters

array

source array to copy

Returns

new array which is a copy of the source array, or NULL if there was an error

AiArraySetKey()

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:

// 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

array	array to write to
key	value of the key we want to write to (must be in 0 .. array->nkeys - 1)
data	input data buffer, with a size of exactly array->getNumElements() * sizeof(type of elements in array)

Returns

true if the write operation was successful

AiArrayMap()

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

array

array to write to

Returns

pointer to the internal array data buffer

AiArrayMapKey()

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

array	array to write to
key	index of the specific key to read from/write to

Returns

pointer to the specific key in the internal array data buffer

AiArrayUnmap()

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

array

array to notify about the end of construction

AiArrayGetNumElements()

AI_API AI_PURE uint32_t AiArrayGetNumElements

(

const AtArray *

array

)

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

Parameters

array

source array

Returns

number of elements per array key

AiArrayGetNumKeys()

AI_API AI_PURE uint8_t AiArrayGetNumKeys

(

const AtArray *

array

)

Get the number of keys.

Parameters

array

source array

Returns

number of keys for this array

AiArrayGetType()

AI_API AI_PURE uint8_t AiArrayGetType

(

const AtArray *

array

)

Get the type of array elements.

Parameters

array

source array

Returns

type of elements in this array

AiArrayGetDataSize()

AI_API AI_PURE size_t AiArrayGetDataSize

(

const AtArray *

array

)

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

Parameters

array

source array

Returns

size in bytes of the whole data

AiArrayGetKeySize()

AI_API AI_PURE size_t AiArrayGetKeySize

(

const AtArray *

array

)

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

Parameters

array

source array

Returns

size in bytes of one key

AiArrayInterpolateVec()

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

array	source array
time	time to calculate the interpolation for the array item
index	index in the array of the element to interpolate

Returns

value of the array item, interpolated to the given time

AiArrayInterpolateRGB()

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

array	source array
time	time to calculate the interpolation for the array item
index	index in the array of the element to interpolate

Returns

value of the array item, interpolated to the given time

AiArrayInterpolateRGBA()

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

array	source array
time	time to calculate the interpolation for the array item
index	index in the array of the element to interpolate

Returns

value of the array item, interpolated to the given time

AiArrayInterpolateFlt()

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

array	source array
time	time to calculate the interpolation for the array item
index	index in the array of the element to interpolate

Returns

value of the array item, interpolated to the given time

AiArrayInterpolateMtx()

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

array	source array
time	time to calculate the interpolation for the array item
index	index in the array of the element to interpolate

Returns

value of the array item, interpolated to the given time