ai_array.h
Go to the documentation of this file.
1// Copyright 2021 Autodesk, Inc. All rights reserved.
2//
3// Use of this software is subject to the terms of the Autodesk license
4// agreement provided at the time of installation or download, or which
5// otherwise accompanies this software in either electronic or hard copy form.
6
12#pragma once
13#include "ai_color.h"
14#include "ai_math.h"
15#include "ai_matrix.h"
16#include "ai_string.h"
17#include "ai_vector.h"
18#include "ai_api.h"
19#include <stdint.h> // uint32_t etc
20
39class AtArray;
40
42using AiArrayDestroyCB = void (*)(uint8_t nbuffer, const void **buffers, const void *userData);
43
44AI_API AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, ...);
45AI_API AtArray* AiArrayAllocate(uint32_t nelements, uint8_t nkeys, uint8_t type);
46AI_API AtArray* AiArrayMakeShared(uint32_t nelements, uint8_t nkeys, uint8_t type, const void** buffers, AiArrayDestroyCB callback=nullptr, void *callback_data=nullptr);
47AI_API void AiArrayDestroy(AtArray* array);
48AI_API AtArray* AiArrayConvert(uint32_t nelements, uint8_t nkeys, uint8_t type, const void* data);
49AI_API void AiArrayResize(AtArray* array, uint32_t nelements, uint8_t nkeys);
50AI_API AtArray* AiArrayCopy(const AtArray* array);
51AI_API bool AiArraySetKey(AtArray* array, uint8_t key, const void* data);
52AI_API void* AiArrayMap(AtArray* array);
53AI_API const void* AiArrayMapConst(const AtArray* array);
54AI_API void* AiArrayMapKey(AtArray* array, uint8_t key);
55AI_API const void* AiArrayMapKeyConst(const AtArray* array, uint8_t key);
56AI_API void AiArrayUnmap(AtArray* array);
57AI_API void AiArrayUnmapConst(const AtArray* array);
58AI_API AI_PURE uint32_t AiArrayGetNumElements(const AtArray* array);
59AI_API AI_PURE uint8_t AiArrayGetNumKeys(const AtArray* array);
60AI_API AI_PURE uint8_t AiArrayGetType(const AtArray* array);
61AI_API AI_PURE size_t AiArrayGetDataSize(const AtArray* array);
62AI_API AI_PURE size_t AiArrayGetKeySize(const AtArray* array);
63AI_API AI_PURE AtVector AiArrayInterpolateVec(const AtArray* array, float time, uint32_t idx);
64AI_API AI_PURE AtRGB AiArrayInterpolateRGB(const AtArray* array, float time, uint32_t idx);
65AI_API AI_PURE AtRGBA AiArrayInterpolateRGBA(const AtArray* array, float time, uint32_t idx);
66AI_API AI_PURE float AiArrayInterpolateFlt(const AtArray* array, float time, uint32_t idx);
67AI_API AI_PURE AtMatrix AiArrayInterpolateMtx(const AtArray* array, float time, uint32_t idx);
68
77AI_API AI_PURE bool AiArrayGetBool (const AtArray* a, uint32_t i);
78AI_API AI_PURE uint8_t AiArrayGetByte (const AtArray* a, uint32_t i);
79AI_API AI_PURE int AiArrayGetInt (const AtArray* a, uint32_t i);
80AI_API AI_PURE uint32_t AiArrayGetUInt (const AtArray* a, uint32_t i);
81AI_API AI_PURE float AiArrayGetFlt (const AtArray* a, uint32_t i);
82AI_API AI_PURE AtRGB AiArrayGetRGB (const AtArray* a, uint32_t i);
83AI_API AI_PURE AtRGBA AiArrayGetRGBA (const AtArray* a, uint32_t i);
84AI_API AI_PURE AtVector2 AiArrayGetVec2 (const AtArray* a, uint32_t i);
85AI_API AI_PURE AtVector AiArrayGetVec (const AtArray* a, uint32_t i);
86AI_API AI_PURE AtMatrix AiArrayGetMtx (const AtArray* a, uint32_t i);
87AI_API AI_PURE AtString AiArrayGetStr (const AtArray* a, uint32_t i);
88AI_API AI_PURE void* AiArrayGetPtr (const AtArray* a, uint32_t i);
89AI_API AI_PURE AtArray* AiArrayGetArray(const AtArray* a, uint32_t i);
90/*\}*/
91
101AI_API bool AiArraySetBool (AtArray* a, uint32_t i, bool val);
102AI_API bool AiArraySetByte (AtArray* a, uint32_t i, uint8_t val);
103AI_API bool AiArraySetInt (AtArray* a, uint32_t i, int val);
104AI_API bool AiArraySetUInt (AtArray* a, uint32_t i, uint32_t val);
105AI_API bool AiArraySetFlt (AtArray* a, uint32_t i, float val);
106AI_API bool AiArraySetRGB (AtArray* a, uint32_t i, AtRGB val);
107AI_API bool AiArraySetRGBA (AtArray* a, uint32_t i, AtRGBA val);
108AI_API bool AiArraySetVec2 (AtArray* a, uint32_t i, AtVector2 val);
109AI_API bool AiArraySetVec (AtArray* a, uint32_t i, AtVector val);
110AI_API bool AiArraySetMtx (AtArray* a, uint32_t i, AtMatrix val);
111AI_API bool AiArraySetStr (AtArray* a, uint32_t i, AtString val);
112AI_API bool AiArraySetPtr (AtArray* a, uint32_t i, void* val);
113AI_API bool AiArraySetArray(AtArray* a, uint32_t i, AtArray* val);
114/*\}*/
115
116/*\}*/
117
118#ifdef AI_CPU_COMPILER
119// this is slower than the AtString version
120inline bool AiArraySetStr(AtArray* a, uint32_t i, const char* val)
121{
122 return AiArraySetStr(a, i, AtString(val));
123}
124#endif
125
126// Helper function for passing a shared buffer.
127inline AtArray* AiArrayMakeShared(uint32_t nelements, uint8_t type, const void* buffer, AiArrayDestroyCB callback=nullptr, void *callback_data=nullptr)
128{
129 return AiArrayMakeShared(nelements, 1, type, &buffer, callback, callback_data);
130}
131
132// Helper functions for compilers that warn about trivial objects being passed
133// as variadic args:
134
135// do not use these directly.
136struct POD_tempf2{float f[2];};
137struct POD_tempf3{float f[3];};
138struct POD_tempf4{float f[4];};
139
140inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector v1) {
141 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1));
142}
143inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2) {
144 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2));
145}
146inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3) {
147 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3));
148}
149inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3, AtVector v4) {
150 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3), reinterpret_type<POD_tempf3>(v4));
151}
152inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector v1, AtVector v2, AtVector v3, AtVector v4, AtVector v5) {
153 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3), reinterpret_type<POD_tempf3>(v4), reinterpret_type<POD_tempf3>(v5));
154}
155
156inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1) {
157 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf2>(v1));
158}
159inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2) {
160 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf2>(v1), reinterpret_type<POD_tempf2>(v2));
161}
162inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3) {
163 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf2>(v1), reinterpret_type<POD_tempf2>(v2), reinterpret_type<POD_tempf2>(v3));
164}
165inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3, AtVector2 v4) {
166 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf2>(v1), reinterpret_type<POD_tempf2>(v2), reinterpret_type<POD_tempf2>(v3), reinterpret_type<POD_tempf2>(v4));
167}
168inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtVector2 v1, AtVector2 v2, AtVector2 v3, AtVector2 v4, AtVector2 v5) {
169 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf2>(v1), reinterpret_type<POD_tempf2>(v2), reinterpret_type<POD_tempf2>(v3), reinterpret_type<POD_tempf2>(v4), reinterpret_type<POD_tempf2>(v5));
170}
171
172inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGB v1) {
173 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1));
174}
175inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2) {
176 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2));
177}
178inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3) {
179 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3));
180}
181inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3, AtRGB v4) {
182 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3), reinterpret_type<POD_tempf3>(v4));
183}
184inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGB v1, AtRGB v2, AtRGB v3, AtRGB v4, AtRGB v5) {
185 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf3>(v1), reinterpret_type<POD_tempf3>(v2), reinterpret_type<POD_tempf3>(v3), reinterpret_type<POD_tempf3>(v4), reinterpret_type<POD_tempf3>(v5));
186}
187
188inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1) {
189 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf4>(v1));
190}
191inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2) {
192 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf4>(v1), reinterpret_type<POD_tempf4>(v2));
193}
194inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3) {
195 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf4>(v1), reinterpret_type<POD_tempf4>(v2), reinterpret_type<POD_tempf4>(v3));
196}
197inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3, AtRGBA v4) {
198 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf4>(v1), reinterpret_type<POD_tempf4>(v2), reinterpret_type<POD_tempf4>(v3), reinterpret_type<POD_tempf4>(v4));
199}
200inline AtArray* AiArray(uint32_t nelements, uint8_t nkeys, int type, AtRGBA v1, AtRGBA v2, AtRGBA v3, AtRGBA v4, AtRGBA v5) {
201 return AiArray(nelements, nkeys, type, reinterpret_type<POD_tempf4>(v1), reinterpret_type<POD_tempf4>(v2), reinterpret_type<POD_tempf4>(v3), reinterpret_type<POD_tempf4>(v4), reinterpret_type<POD_tempf4>(v5));
202}
ai_api.h
DLL export prefix for API functions (necessary for multi-platform development)
ai_color.h
Color types and utilities.
ai_math.h
Math operations.
ai_matrix.h
Matrix math type and methods.
ai_string.h
AtString class for fast comparisons.
ai_vector.h
Vector math types, operators and utilities.
AtString
Arnold String allows for fast string comparisons.
Definition: ai_string.h:54
AiArrayUnmapConst
AI_API void AiArrayUnmapConst(const AtArray *array)
Notifies the array that reading is finished.
Definition: ai_array.cpp:323
AiArrayInterpolateRGBA
AI_API AI_PURE AtRGBA AiArrayInterpolateRGBA(const AtArray *array, float time, uint32_t idx)
Interpolate an AtRGBA at a given time from an array.
Definition: ai_array.cpp:444
AiArrayDestroyCB
void(*)(uint8_t nbuffer, const void **buffers, const void *userData) AiArrayDestroyCB
Shared array callback function that is passed to the client to notify him it can release the buffers ...
Definition: ai_array.h:42
AiArrayCopy
AI_API AtArray * AiArrayCopy(const AtArray *array)
Create a copy of an array.
Definition: ai_array.cpp:169
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.
Definition: ai_array.cpp:291
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.
Definition: ai_array.cpp:138
AiArrayGetKeySize
AI_API AI_PURE size_t AiArrayGetKeySize(const AtArray *array)
Get the total size in bytes of the data for one key.
Definition: ai_array.cpp:379
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
AiArrayGetNumKeys
AI_API AI_PURE uint8_t AiArrayGetNumKeys(const AtArray *array)
Get the number of keys.
Definition: ai_array.cpp:346
AiArrayDestroy
AI_API void AiArrayDestroy(AtArray *array)
Deallocate an array object.
Definition: ai_array.cpp:61
AiArrayGetNumElements
AI_API AI_PURE uint32_t AiArrayGetNumElements(const AtArray *array)
Get the number of elements on each key of the array.
Definition: ai_array.cpp:335
AiArrayInterpolateMtx
AI_API AI_PURE AtMatrix AiArrayInterpolateMtx(const AtArray *array, float time, uint32_t idx)
Interpolate a matrix at a given time from an array.
Definition: ai_array.cpp:418
AiArrayMap
AI_API void * AiArrayMap(AtArray *array)
Obtains a pointer to the internal array data for construction.
Definition: ai_array.cpp:238
AiArrayAllocate
AI_API AtArray * AiArrayAllocate(uint32_t nelements, uint8_t nkeys, uint8_t type)
Create an empty (uninitialized) array of the specified type.
Definition: ai_array.cpp:29
AiArrayMapConst
AI_API const void * AiArrayMapConst(const AtArray *array)
Obtains a pointer to the internal array data for reading.
Definition: ai_array.cpp:255
AiArrayMakeShared
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.
Definition: ai_array.cpp:51
AiArrayInterpolateFlt
AI_API AI_PURE float AiArrayInterpolateFlt(const AtArray *array, float time, uint32_t idx)
Interpolate a float at a given time from an array.
Definition: ai_array.cpp:405
AiArrayInterpolateRGB
AI_API AI_PURE AtRGB AiArrayInterpolateRGB(const AtArray *array, float time, uint32_t idx)
Interpolate a color at a given time from an array.
Definition: ai_array.cpp:431
AiArrayInterpolateVec
AI_API AI_PURE AtVector AiArrayInterpolateVec(const AtArray *array, float time, uint32_t idx)
Interpolate a vector at a given time from an array.
Definition: ai_array.cpp:392
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.
Definition: ai_array.cpp:205
AiArrayGetType
AI_API AI_PURE uint8_t AiArrayGetType(const AtArray *array)
Get the type of array elements.
Definition: ai_array.cpp:357
AiArrayMapKey
AI_API void * AiArrayMapKey(AtArray *array, uint8_t key)
Obtains a pointer to a specific key in the internal array data for construction.
Definition: ai_array.cpp:273
AiArrayUnmap
AI_API void AiArrayUnmap(AtArray *array)
Notifies the array that construction is finished.
Definition: ai_array.cpp:307
AiArrayGetDataSize
AI_API AI_PURE size_t AiArrayGetDataSize(const AtArray *array)
Get the total size in bytes of the data buffer for this array.
Definition: ai_array.cpp:368
AiArrayResize
AI_API void AiArrayResize(AtArray *array, uint32_t nelements, uint8_t nkeys)
Resize an existing array contents in place.
Definition: ai_array.cpp:153
AtMatrix
Definition: ai_matrix.h:30
AtRGBA
RGB color + alpha.
Definition: ai_color.h:267
AtRGB
RGB color.
Definition: ai_color.h:32
AtVector2
2D point
Definition: ai_vector.h:255
AtVector
3D point (single precision)
Definition: ai_vector.h:30
POD_tempf2
Definition: ai_array.h:136
POD_tempf3
Definition: ai_array.h:137
POD_tempf4
Definition: ai_array.h:138

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