ai_params.h
Go to the documentation of this file.
1// Copyright 2025 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_array.h"
14#include "ai_closure.h"
15#include "ai_color.h"
16#include "ai_enum.h"
17#include "ai_math.h"
18#include "ai_matrix.h"
19#include "ai_vector.h"
20#include "ai_api.h"
21#include <stdint.h> // uint32_t etc
22
23#ifdef _WIN32
24# ifndef WIN32_LEAN_AND_MEAN
25# define WIN32_LEAN_AND_MEAN
26# endif
27# ifndef VC_EXTRALEAN
28# define VC_EXTRALEAN
29# endif
30# ifndef NOMINMAX
31# define NOMINMAX
32# endif
33// Force an include of windows.h to make sure it can't be included after this header
34// (thanks to its own internal include guard) and the RGB() macro is not defined again
35# include <windows.h>
36# ifdef RGB
37# undef RGB
38// The RGB() macro in WinGDI.h returns a COLORREF, which we know to be a DWORD, which
39// in turn is an unsigned long, see:
40// https://msdn.microsoft.com/en-us/library/windows/desktop/aa383751%28v=vs.85%29.aspx
41// Let's recreate this as a function instead of as a macro.
42inline constexpr unsigned long RGB(unsigned long r, unsigned long g, unsigned long b)
43{
44 return r | g << 8 | b << 16;
45}
46# endif
47#endif
48
49// forward declaration
50struct AtList;
51struct AtNode;
52
70#define AI_TYPE_BYTE 0x00
71#define AI_TYPE_INT 0x01
72#define AI_TYPE_UINT 0x02
73#define AI_TYPE_BOOLEAN 0x03
74#define AI_TYPE_FLOAT 0x04
75#define AI_TYPE_RGB 0x05
76#define AI_TYPE_RGBA 0x06
77#define AI_TYPE_VECTOR 0x07
78#define AI_TYPE_VECTOR2 0x09
79#define AI_TYPE_STRING 0x0A
80#define AI_TYPE_POINTER 0x0B
81#define AI_TYPE_NODE 0x0C
82#define AI_TYPE_ARRAY 0x0D
83#define AI_TYPE_MATRIX 0x0E
84#define AI_TYPE_ENUM 0x0F
85#define AI_TYPE_CLOSURE 0x10
86#define AI_TYPE_USHORT 0x11
87#define AI_TYPE_HALF 0x12
88#define AI_TYPE_UNDEFINED 0xFF
89#define AI_TYPE_NONE 0xFF
90/* \}*/
91
95#define AI_USERDEF_UNDEFINED 0
96#define AI_USERDEF_CONSTANT 1
97#define AI_USERDEF_UNIFORM 2
98#define AI_USERDEF_VARYING 3
99#define AI_USERDEF_INDEXED 4
100#define AI_USERDEF_PER_INSTANCE 5
101/* \}*/
102
106class AtParamValue
107{
108public:
109 AI_DEVICE bool const& BOOL() const { return data._bool; }
110 AI_DEVICE uint8_t const& BYTE() const { return data._byte; }
111 AI_DEVICE int const& INT() const { return data._int; }
112 AI_DEVICE unsigned const& UINT() const { return data._uint; }
113 AI_DEVICE float const& FLT() const { return data._float; }
114 AI_DEVICE AtRGB const& RGB() const { return data._rgb; }
115 AI_DEVICE AtRGBA const& RGBA() const { return data._rgba; }
116 AI_DEVICE AtVector const& VEC() const { return data._vec; }
117 AI_DEVICE AtVector2 const& VEC2() const { return data._vec2; }
118 AI_DEVICE AtString const& STR() const { return data._str; }
119 AI_DEVICE void* const& PTR() const { return data._ptr; }
120 AtMatrix* const& pMTX() const { return data._matrix_ptr; }
121 AtArray* const& ARRAY() const { return data._array_ptr; }
122 AI_DEVICE AtClosureList const& CLOSURE() const { return data._closure_list; }
123
124 AI_DEVICE bool& BOOL() { return data._bool; }
125 AI_DEVICE uint8_t& BYTE() { return data._byte; }
126 AI_DEVICE int& INT() { return data._int; }
127 AI_DEVICE unsigned& UINT() { return data._uint; }
128 AI_DEVICE float& FLT() { return data._float; }
129 AI_DEVICE AtRGB& RGB() { return data._rgb; }
130 AI_DEVICE AtRGBA& RGBA() { return data._rgba; }
131 AI_DEVICE AtVector& VEC() { return data._vec; }
132 AI_DEVICE AtVector2& VEC2() { return data._vec2; }
133 AI_DEVICE AtString& STR() { return data._str; }
134 AI_DEVICE void*& PTR() { return data._ptr; }
135 AtMatrix*& pMTX() { return data._matrix_ptr; }
136 AtArray*& ARRAY() { return data._array_ptr; }
137 AI_DEVICE AtClosureList& CLOSURE() { return data._closure_list; }
138
139private:
140 union Data
141 {
142 constexpr Data() : _rgba(0.f, 0.f, 0.f, 0.f) {}
143 bool _bool;
144 uint8_t _byte;
145 int _int;
146 unsigned _uint;
147 float _float;
148 AtRGB _rgb;
149 AtRGBA _rgba;
150 AtVector _vec;
151 AtVector2 _vec2;
152 AtString _str;
153 void* _ptr;
154 AtMatrix* _matrix_ptr;
155 AtArray* _array_ptr;
156 AtClosureList _closure_list;
157 } data;
158};
159
166struct AtParamEntry;
167
172AI_API AI_PURE AtString AiParamGetName (const AtParamEntry* pentry);
173AI_API AI_PURE uint8_t AiParamGetType (const AtParamEntry* pentry);
174AI_API AI_PURE uint8_t AiParamGetSubType (const AtParamEntry* pentry);
175AI_API AI_PURE const AtParamValue* AiParamGetDefault (const AtParamEntry* pentry);
176AI_API AI_PURE AtEnum AiParamGetEnum (const AtParamEntry* pentry);
177AI_API AI_PURE const char* AiParamGetTypeName(uint8_t type);
178AI_API AI_DEVICE AI_CONST int AiParamGetTypeSize(uint8_t type);
179/* \}*/
180
187struct AtUserParamEntry;
188
193AI_API AI_DEVICE AI_PURE const char* AiUserParamGetName (const AtUserParamEntry* upentry);
194AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetType (const AtUserParamEntry* upentry);
195AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetArrayType(const AtUserParamEntry* upentry);
196AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetCategory (const AtUserParamEntry* upentry);
197/* \}*/
198
210AI_API AI_CONST bool AiParamTypeConvertible(uint8_t dst_type, uint8_t src_type);
211
237#define AiParameterByte(n,c) AiNodeParamByte (params,-1,n,c);
238#define AiParameterInt(n,c) AiNodeParamInt (params,-1,n,c);
239#define AiParameterUInt(n,c) AiNodeParamUInt (params,-1,n,c);
240#define AiParameterBool(n,c) AiNodeParamBool (params,-1,n,c);
241#define AiParameterFlt(n,c) AiNodeParamFlt (params,-1,n,c);
242#define AiParameterRGB(n,r,g,b) AiNodeParamRGB (params,-1,n,r,g,b);
243#define AiParameterRGBA(n,r,g,b,a) AiNodeParamRGBA (params,-1,n,r,g,b,a);
244#define AiParameterVec(n,x,y,z) AiNodeParamVec (params,-1,n,x,y,z);
245#define AiParameterVec2(n,x,y) AiNodeParamVec2 (params,-1,n,x,y);
246#define AiParameterStr(n,c) AiNodeParamStr (params,-1,n,c);
247#define AiParameterPtr(n,c) AiNodeParamPtr (params,-1,n,c);
248#define AiParameterNode(n,c) AiNodeParamNode (params,-1,n,c);
249#define AiParameterArray(n,c) AiNodeParamArray (params,-1,n,c);
250#define AiParameterMtx(n,c) AiNodeParamMtx (params,-1,n,c);
251#define AiParameterEnum(n,c,e) AiNodeParamEnum (params,-1,n,c,e);
252#define AiParameterClosure(n) AiNodeParamClosure(params,-1,n);
253
254#define AiOutputByte(n) AiNodeOutputByte (params,n);
255#define AiOutputInt(n) AiNodeOutputInt (params,n);
256#define AiOutputUInt(n) AiNodeOutputUInt (params,n);
257#define AiOutputBool(n) AiNodeOutputBool (params,n);
258#define AiOutputFlt(n) AiNodeOutputFlt (params,n);
259#define AiOutputRGB(n) AiNodeOutputRGB (params,n);
260#define AiOutputRGBA(n) AiNodeOutputRGBA (params,n);
261#define AiOutputVec(n) AiNodeOutputVec (params,n);
262#define AiOutputVec2(n) AiNodeOutputVec2 (params,n);
263#define AiOutputStr(n) AiNodeOutputStr (params,n);
264#define AiOutputPtr(n) AiNodeOutputPtr (params,n);
265#define AiOutputNode(n) AiNodeOutputNode (params,n);
266#define AiOutputArray(n,t) AiNodeOutputArray (params,n,t);
267#define AiOutputMtx(n) AiNodeOutputMtx (params,n);
268#define AiOutputEnum(n,t) AiNodeOutputEnum (params,n,t);
269#define AiOutputClosure(n) AiNodeOutputClosure(params,n);
270/* \}*/
271
272/*\}*/
273
274/* for convenience, the macros above call these functions */
275AI_API void AiNodeParamByte (AtList* params, int varoffset, const char* pname, uint8_t pdefault);
276AI_API void AiNodeParamInt (AtList* params, int varoffset, const char* pname, int pdefault);
277AI_API void AiNodeParamUInt (AtList* params, int varoffset, const char* pname, unsigned int pdefault);
278AI_API void AiNodeParamBool (AtList* params, int varoffset, const char* pname, bool pdefault);
279AI_API void AiNodeParamFlt (AtList* params, int varoffset, const char* pname, float pdefault);
280AI_API void AiNodeParamRGB (AtList* params, int varoffset, const char* pname, float r, float g, float b);
281AI_API void AiNodeParamRGBA (AtList* params, int varoffset, const char* pname, float r, float g, float b, float a);
282AI_API void AiNodeParamVec (AtList* params, int varoffset, const char* pname, float x, float y, float z);
283AI_API void AiNodeParamVec2 (AtList* params, int varoffset, const char* pname, float x, float y);
284AI_API void AiNodeParamStr (AtList* params, int varoffset, const char* pname, const char* pdefault);
285AI_API void AiNodeParamPtr (AtList* params, int varoffset, const char* pname, void* pdefault);
286AI_API void AiNodeParamNode (AtList* params, int varoffset, const char* pname, AtNode* pdefault);
287AI_API void AiNodeParamArray (AtList* params, int varoffset, const char* pname, AtArray* pdefault);
288AI_API void AiNodeParamMtx (AtList* params, int varoffset, const char* pname, AtMatrix matrix);
289AI_API void AiNodeParamEnum (AtList* params, int varoffset, const char* pname, int pdefault, AtEnum enum_type);
290AI_API void AiNodeParamClosure(AtList* params, int varoffset, const char* pname);
291
292AI_API void AiNodeOutputByte (AtList* params, const char* pname);
293AI_API void AiNodeOutputInt (AtList* params, const char* pname);
294AI_API void AiNodeOutputUInt (AtList* params, const char* pname);
295AI_API void AiNodeOutputBool (AtList* params, const char* pname);
296AI_API void AiNodeOutputFlt (AtList* params, const char* pname);
297AI_API void AiNodeOutputRGB (AtList* params, const char* pname);
298AI_API void AiNodeOutputRGBA (AtList* params, const char* pname);
299AI_API void AiNodeOutputVec (AtList* params, const char* pname);
300AI_API void AiNodeOutputVec2 (AtList* params, const char* pname);
301AI_API void AiNodeOutputStr (AtList* params, const char* pname);
302AI_API void AiNodeOutputPtr (AtList* params, const char* pname);
303AI_API void AiNodeOutputNode (AtList* params, const char* pname);
304AI_API void AiNodeOutputArray (AtList* params, const char* pname, int array_type);
305AI_API void AiNodeOutputMtx (AtList* params, const char* pname);
306AI_API void AiNodeOutputEnum (AtList* params, const char* pname, AtEnum enum_type);
307AI_API void AiNodeOutputClosure(AtList* params, const char* pname);
ai_api.h
DLL export prefix for API functions (necessary for multi-platform development)
ai_array.h
Generic array data type and methods.
ai_closure.h
Closure type and utilities.
ai_color.h
Color types and utilities.
ai_enum.h
Enum data type and utility functions.
ai_math.h
Math operations.
ai_matrix.h
Matrix math type and methods.
ai_vector.h
Vector math types, operators and utilities.
AtParamValue
Actual parameter value for each supported type.
Definition: ai_params.h:107
AtString
Arnold String allows for fast string comparisons.
Definition: ai_string.h:54
AtEnum
const char ** AtEnum
String-based enumerated data type.
Definition: ai_enum.h:31
AiParamGetTypeSize
AI_API AI_DEVICE AI_CONST int AiParamGetTypeSize(uint8_t type)
Return the size of an Arnold data type.
Definition: ai_paramentry.cpp:165
AiUserParamGetType
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetType(const AtUserParamEntry *upentry)
Look-up user-declared parameter type (int, float, etc...)
Definition: ai_userdefs.cpp:24
AiUserParamGetCategory
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetCategory(const AtUserParamEntry *upentry)
Look-up user-declared parameter category (constant, uniform, varying)
Definition: ai_userdefs.cpp:46
AiParamGetDefault
AI_API AI_PURE const AtParamValue * AiParamGetDefault(const AtParamEntry *pentry)
Return the default value of a given parameter.
Definition: ai_paramentry.cpp:204
AiParamGetTypeName
AI_API AI_PURE const char * AiParamGetTypeName(uint8_t type)
Return the name of an Arnold data type.
Definition: ai_paramentry.cpp:141
AiUserParamGetName
AI_API AI_DEVICE AI_PURE const char * AiUserParamGetName(const AtUserParamEntry *upentry)
Look-up user-declared parameter name.
Definition: ai_userdefs.cpp:12
AiParamGetType
AI_API AI_PURE uint8_t AiParamGetType(const AtParamEntry *pentry)
Return the type of a given parameter.
Definition: ai_paramentry.cpp:103
AiParamTypeConvertible
AI_API AI_CONST bool AiParamTypeConvertible(uint8_t dst_type, uint8_t src_type)
Returns whether an AtParamValue of type src_type can be converted to dst_type.
Definition: ai_paramentry.cpp:783
AiParamGetName
AI_API AI_PURE AtString AiParamGetName(const AtParamEntry *pentry)
Return the name of a given parameter.
Definition: ai_paramentry.cpp:87
AiParamGetEnum
AI_API AI_PURE AtEnum AiParamGetEnum(const AtParamEntry *pentry)
Return the enum type of a given enum parameter.
Definition: ai_paramentry.cpp:220
AiParamGetSubType
AI_API AI_PURE uint8_t AiParamGetSubType(const AtParamEntry *pentry)
Return the sub-type of a given array parameter.
Definition: ai_paramentry.cpp:119
AiUserParamGetArrayType
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetArrayType(const AtUserParamEntry *upentry)
Look-up user-declared parameter array-type (int, float, etc...)
Definition: ai_userdefs.cpp:35
AtClosureList
Definition: ai_closure.h:85
AtMatrix
Definition: ai_matrix.h:30
AtNode
This represents a node in Arnold.
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

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