AtArray objects construction and manipulation. More...

Data Structures
struct	POD_tempf2

struct	POD_tempf3

struct	POD_tempf4

Typedefs
using	AiArrayDestroyCB = void()(uint8_t nbuffer, const void buffers, const void userData)
	Shared array callback function that is passed to the client to notify him it can release the buffers passed as argument.

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 AtArray *	AiArrayMakeShared (uint32_t nelements, uint8_t nkeys, uint8_t type, const void *buffers, AiArrayDestroyCB callback=nullptr, void callback_data=nullptr)
	Create a shared read only array holding buffer pointing to the key buffers allocated by the client. 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 const void *	AiArrayMapConst (const AtArray *array)
	Obtains a pointer to the internal array data for reading. 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 const void *	AiArrayMapKeyConst (const AtArray *array, uint8_t key)
	Obtains a const pointer to a specific key in the internal array data for reading. More...

AI_API void	AiArrayUnmap (AtArray *array)
	Notifies the array that construction is finished. More...

AI_API void	AiArrayUnmapConst (const AtArray *array)
	Notifies the array that reading 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 *	AiArrayMakeShared (uint32_t nelements, uint8_t type, const void buffer, AiArrayDestroyCB callback=nullptr, void callback_data=nullptr)

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);

AiArray

AI_API AtArray * AiArray(uint32_t nelements, uint8_t nkeys, int type,...)

Create an array and initialize it with supplied data.

Definition: ai_array.cpp:94

AI_TYPE_FLOAT

#define AI_TYPE_FLOAT

float (Single-precision floating point number)

Definition: ai_params.h:74

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

◆ AiArrayMakeShared()

AI_API AtArray * AiArrayMakeShared	(	uint32_t	nelements,
		uint8_t	nkeys,
		uint8_t	type,
		const void **	keys,
		AiArrayDestroyCB	callback,
		void *	callback_data
	)

Create a shared read only array holding buffer pointing to the key buffers allocated by the client.

The returned array holds the buffers passed as argument.

Parameters

nelements	number of elements 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.)
keys	pointer to the keys shared with Arnold. They must not be modified or destroyed while Arnold is using them.
callback	pointer function called when the last reference to the buffer is destroyed and the buffer can safely be destroyed.
callback_data	blind pointer used by the callback

Returns: pointer to a shared read only array nelements or NULL

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

◆ AiArrayMapConst()

AI_API const void * AiArrayMapConst ( const AtArray * array )

Obtains a pointer to the internal array data for reading.

(const)

Return a pointer to the internal buffer storage for this array data. This pointer can be used to read directly from the array buffer, and it has to be unmap'ed when reading 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

◆ AiArrayMapKeyConst()

AI_API const void * AiArrayMapKeyConst	(	const AtArray *	array,
		uint8_t	key
	)

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

Return a const pointer to a specific key in the internal buffer storage for this array data. This pointer can be used to read 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 read from
key	index of the specific key to read from

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

◆ AiArrayUnmapConst()

AI_API void AiArrayUnmapConst ( const AtArray * array )

Notifies the array that reading is finished.

(const version)

After calling this function, any pointers previously obtained with AiArrayMapConst or AiArrayMapKeyConst 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

Data Structures

Typedefs

Functions

Variables

AtArray Getters

AtArray Setters

Detailed Description

Function Documentation

◆ AiArray()

◆ AiArrayAllocate()

◆ AiArrayMakeShared()

◆ AiArrayDestroy()

◆ AiArrayConvert()

◆ AiArrayResize()

◆ AiArrayCopy()

◆ AiArraySetKey()

◆ AiArrayMap()

◆ AiArrayMapConst()

◆ AiArrayMapKey()

◆ AiArrayMapKeyConst()

◆ AiArrayUnmap()

◆ AiArrayUnmapConst()

◆ AiArrayGetNumElements()

◆ AiArrayGetNumKeys()

◆ AiArrayGetType()

◆ AiArrayGetDataSize()

◆ AiArrayGetKeySize()

◆ AiArrayInterpolateVec()

◆ AiArrayInterpolateRGB()

◆ AiArrayInterpolateRGBA()

◆ AiArrayInterpolateFlt()

◆ AiArrayInterpolateMtx()