Data Structures | Functions
AtParamEntry API

Querying and operation with node parameters. More...

Data Structures

class  AtParamValue
 Actual parameter value for each supported type. More...
 

Functions

AI_DEVICE bool const & AtParamValue::BOOL () const
 
AI_DEVICE uint8_t const & AtParamValue::BYTE () const
 
AI_DEVICE int const & AtParamValue::INT () const
 
AI_DEVICE unsigned const & AtParamValue::UINT () const
 
AI_DEVICE float const & AtParamValue::FLT () const
 
AI_DEVICE AtRGB const & AtParamValue::RGB () const
 
AI_DEVICE AtRGBA const & AtParamValue::RGBA () const
 
AI_DEVICE AtVector const & AtParamValue::VEC () const
 
AI_DEVICE AtVector2 const & AtParamValue::VEC2 () const
 
AI_DEVICE AtString const & AtParamValue::STR () const
 
AI_DEVICE void *const & AtParamValue::PTR () const
 
AtMatrix *const & AtParamValue::pMTX () const
 
AtArray *const & AtParamValue::ARRAY () const
 
AI_DEVICE AtClosureList const & AtParamValue::CLOSURE () const
 
AI_DEVICE bool & AtParamValue::BOOL ()
 
AI_DEVICE uint8_t & AtParamValue::BYTE ()
 
AI_DEVICE int & AtParamValue::INT ()
 
AI_DEVICE unsigned & AtParamValue::UINT ()
 
AI_DEVICE float & AtParamValue::FLT ()
 
AI_DEVICE AtRGB & AtParamValue::RGB ()
 
AI_DEVICE AtRGBA & AtParamValue::RGBA ()
 
AI_DEVICE AtVector & AtParamValue::VEC ()
 
AI_DEVICE AtVector2 & AtParamValue::VEC2 ()
 
AI_DEVICE AtString & AtParamValue::STR ()
 
AI_DEVICE void *& AtParamValue::PTR ()
 
AtMatrix *& AtParamValue::pMTX ()
 
AtArray *& AtParamValue::ARRAY ()
 
AI_DEVICE AtClosureList & AtParamValue::CLOSURE ()
 

AtParamEntry Methods

AI_API AI_PURE AtString AiParamGetName (const AtParamEntry *pentry)
 Return the name of a given parameter. More...
 
AI_API AI_PURE uint8_t AiParamGetType (const AtParamEntry *pentry)
 Return the type of a given parameter. More...
 
AI_API AI_PURE uint8_t AiParamGetSubType (const AtParamEntry *pentry)
 Return the sub-type of a given array parameter. More...
 
AI_API AI_PURE const AtParamValue * AiParamGetDefault (const AtParamEntry *pentry)
 Return the default value of a given parameter. More...
 
AI_API AI_PURE AtEnum AiParamGetEnum (const AtParamEntry *pentry)
 Return the enum type of a given enum parameter. More...
 
AI_API AI_PURE const char * AiParamGetTypeName (uint8_t type)
 Return the name of an Arnold data type. More...
 
AI_API AI_DEVICE AI_CONST int AiParamGetTypeSize (uint8_t type)
 Return the size of an Arnold data type. More...
 

AtUserParamEntry Methods

AI_API AI_DEVICE AI_PURE const char * AiUserParamGetName (const AtUserParamEntry *upentry)
 Look-up user-declared parameter name.
 
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetType (const AtUserParamEntry *upentry)
 Look-up user-declared parameter type (int, float, etc...)
 
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetArrayType (const AtUserParamEntry *upentry)
 Look-up user-declared parameter array-type (int, float, etc...)
 
AI_API AI_DEVICE AI_PURE uint8_t AiUserParamGetCategory (const AtUserParamEntry *upentry)
 Look-up user-declared parameter category (constant, uniform, varying)
 
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. More...
 

Parameter Installers

These macros are to be called from a node's node_parameters method only.

There is a different macro for each supported parameter data type. For example, a shader node that implemented a typical fractal noise would declare three parameters like this:

node_parameters
{
AiParameterInt("octaves", 3);
AiParameterFlt("lacunarity", 1.92f);
AiParameterBool("turbulence", false);
}
node_parameters
#define node_parameters
Parameter declaration method.
Definition: ai_nodes.h:71

Please refer to ai_params.h for a description of the functions called by these macros.

Parameters
nthe name of the parameter that will be installed
defaultthe default value of the new parameter (the actual number of arguments passed in depends on the parameter's data type, for example three floats for a RGB type)
AI_API void AiNodeParamByte (AtList *params, int varoffset, const char *pname, uint8_t pdefault)
 
AI_API void AiNodeParamInt (AtList *params, int varoffset, const char *pname, int pdefault)
 
AI_API void AiNodeParamUInt (AtList *params, int varoffset, const char *pname, unsigned int pdefault)
 
AI_API void AiNodeParamBool (AtList *params, int varoffset, const char *pname, bool pdefault)
 
AI_API void AiNodeParamFlt (AtList *params, int varoffset, const char *pname, float pdefault)
 
AI_API void AiNodeParamRGB (AtList *params, int varoffset, const char *pname, float r, float g, float b)
 
AI_API void AiNodeParamRGBA (AtList *params, int varoffset, const char *pname, float r, float g, float b, float a)
 
AI_API void AiNodeParamVec (AtList *params, int varoffset, const char *pname, float x, float y, float z)
 
AI_API void AiNodeParamVec2 (AtList *params, int varoffset, const char *pname, float x, float y)
 
AI_API void AiNodeParamStr (AtList *params, int varoffset, const char *pname, const char *pdefault)
 
AI_API void AiNodeParamPtr (AtList *params, int varoffset, const char *pname, void *pdefault)
 
AI_API void AiNodeParamNode (AtList *params, int varoffset, const char *pname, AtNode *pdefault)
 
AI_API void AiNodeParamArray (AtList *params, int varoffset, const char *pname, AtArray *pdefault)
 
AI_API void AiNodeParamMtx (AtList *params, int varoffset, const char *pname, AtMatrix matrix)
 
AI_API void AiNodeParamEnum (AtList *params, int varoffset, const char *pname, int pdefault, AtEnum enum_type)
 
AI_API void AiNodeParamClosure (AtList *params, int varoffset, const char *pname)
 
AI_API void AiNodeOutputByte (AtList *params, const char *pname)
 
AI_API void AiNodeOutputInt (AtList *params, const char *pname)
 
AI_API void AiNodeOutputUInt (AtList *params, const char *pname)
 
AI_API void AiNodeOutputBool (AtList *params, const char *pname)
 
AI_API void AiNodeOutputFlt (AtList *params, const char *pname)
 
AI_API void AiNodeOutputRGB (AtList *params, const char *pname)
 
AI_API void AiNodeOutputRGBA (AtList *params, const char *pname)
 
AI_API void AiNodeOutputVec (AtList *params, const char *pname)
 
AI_API void AiNodeOutputVec2 (AtList *params, const char *pname)
 
AI_API void AiNodeOutputStr (AtList *params, const char *pname)
 
AI_API void AiNodeOutputPtr (AtList *params, const char *pname)
 
AI_API void AiNodeOutputNode (AtList *params, const char *pname)
 
AI_API void AiNodeOutputArray (AtList *params, const char *pname, int array_type)
 
AI_API void AiNodeOutputMtx (AtList *params, const char *pname)
 
AI_API void AiNodeOutputEnum (AtList *params, const char *pname, AtEnum enum_type)
 
AI_API void AiNodeOutputClosure (AtList *params, const char *pname)
 
#define AiParameterByte(n, c)   AiNodeParamByte (params,-1,n,c);
 
#define AiParameterInt(n, c)   AiNodeParamInt (params,-1,n,c);
 
#define AiParameterUInt(n, c)   AiNodeParamUInt (params,-1,n,c);
 
#define AiParameterBool(n, c)   AiNodeParamBool (params,-1,n,c);
 
#define AiParameterFlt(n, c)   AiNodeParamFlt (params,-1,n,c);
 
#define AiParameterRGB(n, r, g, b)   AiNodeParamRGB (params,-1,n,r,g,b);
 
#define AiParameterRGBA(n, r, g, b, a)   AiNodeParamRGBA (params,-1,n,r,g,b,a);
 
#define AiParameterVec(n, x, y, z)   AiNodeParamVec (params,-1,n,x,y,z);
 
#define AiParameterVec2(n, x, y)   AiNodeParamVec2 (params,-1,n,x,y);
 
#define AiParameterStr(n, c)   AiNodeParamStr (params,-1,n,c);
 
#define AiParameterPtr(n, c)   AiNodeParamPtr (params,-1,n,c);
 
#define AiParameterNode(n, c)   AiNodeParamNode (params,-1,n,c);
 
#define AiParameterArray(n, c)   AiNodeParamArray (params,-1,n,c);
 
#define AiParameterMtx(n, c)   AiNodeParamMtx (params,-1,n,c);
 
#define AiParameterEnum(n, c, e)   AiNodeParamEnum (params,-1,n,c,e);
 
#define AiParameterClosure(n)   AiNodeParamClosure(params,-1,n);
 
#define AiOutputByte(n)   AiNodeOutputByte (params,n);
 
#define AiOutputInt(n)   AiNodeOutputInt (params,n);
 
#define AiOutputUInt(n)   AiNodeOutputUInt (params,n);
 
#define AiOutputBool(n)   AiNodeOutputBool (params,n);
 
#define AiOutputFlt(n)   AiNodeOutputFlt (params,n);
 
#define AiOutputRGB(n)   AiNodeOutputRGB (params,n);
 
#define AiOutputRGBA(n)   AiNodeOutputRGBA (params,n);
 
#define AiOutputVec(n)   AiNodeOutputVec (params,n);
 
#define AiOutputVec2(n)   AiNodeOutputVec2 (params,n);
 
#define AiOutputStr(n)   AiNodeOutputStr (params,n);
 
#define AiOutputPtr(n)   AiNodeOutputPtr (params,n);
 
#define AiOutputNode(n)   AiNodeOutputNode (params,n);
 
#define AiOutputArray(n, t)   AiNodeOutputArray (params,n,t);
 
#define AiOutputMtx(n)   AiNodeOutputMtx (params,n);
 
#define AiOutputEnum(n, t)   AiNodeOutputEnum (params,n,t);
 
#define AiOutputClosure(n)   AiNodeOutputClosure(params,n);
 

Parameter Types

See AtParamValue for the actual primitive data types that these macros refer to.

#define AI_TYPE_BYTE   0x00
 uint8_t (an 8-bit sized unsigned integer)
 
#define AI_TYPE_INT   0x01
 int (32-bit integer)
 
#define AI_TYPE_UINT   0x02
 unsigned int (32-bit unsigned integer)
 
#define AI_TYPE_BOOLEAN   0x03
 bool (either true or false)
 
#define AI_TYPE_FLOAT   0x04
 float (Single-precision floating point number)
 
#define AI_TYPE_RGB   0x05
 RGB struct.
 
#define AI_TYPE_RGBA   0x06
 RGBA struct.
 
#define AI_TYPE_VECTOR   0x07
 XYZ vector or point.
 
#define AI_TYPE_VECTOR2   0x09
 XY vector or point.
 
#define AI_TYPE_STRING   0x0A
 AtString character string.
 
#define AI_TYPE_POINTER   0x0B
 Arbitrary pointer.
 
#define AI_TYPE_NODE   0x0C
 Pointer to an Arnold node.
 
#define AI_TYPE_ARRAY   0x0D
 AtArray.
 
#define AI_TYPE_MATRIX   0x0E
 4x4 matrix
 
#define AI_TYPE_ENUM   0x0F
 Enumeration (see AtEnum)
 
#define AI_TYPE_CLOSURE   0x10
 Shader closure.
 
#define AI_TYPE_USHORT   0x11
 unsigned short (16-bit unsigned integer) (used by drivers only)
 
#define AI_TYPE_HALF   0x12
 16-bit, half-precision float (used by drivers only)
 
#define AI_TYPE_UNDEFINED   0xFF
 Undefined, you should never encounter a parameter of this type.
 
#define AI_TYPE_NONE   0xFF
 No type.
 

Parameter Categories for User-Data

#define AI_USERDEF_UNDEFINED   0
 Undefined, you should never encounter a parameter of this category.
 
#define AI_USERDEF_CONSTANT   1
 User-defined: per-object parameter.
 
#define AI_USERDEF_UNIFORM   2
 User-defined: per-face parameter.
 
#define AI_USERDEF_VARYING   3
 User-defined: per-vertex parameter.
 
#define AI_USERDEF_INDEXED   4
 User-defined: per-face-vertex parameter.
 

Detailed Description

Querying and operation with node parameters.

Methods like AiNodeEntryGetParameter() return a AtParamEntry object that can be used to query information about a given parameter. For a discussion of Arnold's object-oriented system of pluggable nodes, please refer to AtNode API and AtNodeEntry API.

Function Documentation

◆ AiParamGetName()

AI_API AI_PURE AtString AiParamGetName ( const AtParamEntry *  pentry)

Return the name of a given parameter.

Parameters
pentrythe parameter entry
Returns
the name string, or an empty string if the input pentry was NULL

◆ AiParamGetType()

AI_API AI_PURE uint8_t AiParamGetType ( const AtParamEntry *  pentry)

Return the type of a given parameter.

Parameters
pentrythe parameter entry
Returns
the data type of the parameter, one of AI_TYPE_INT, AI_TYPE_FLOAT etc, or AI_TYPE_UNDEFINED if the input pentry was NULL

◆ AiParamGetSubType()

AI_API AI_PURE uint8_t AiParamGetSubType ( const AtParamEntry *  pentry)

Return the sub-type of a given array parameter.

Parameters
pentrythe parameter entry
Returns
the data type of the parameter, one of AI_TYPE_INT, AI_TYPE_FLOAT etc, or AI_TYPE_UNDEFINED if the input pentry was NULL

◆ AiParamGetDefault()

AI_API AI_PURE const AtParamValue * AiParamGetDefault ( const AtParamEntry *  pentry)

Return the default value of a given parameter.

Parameters
pentrythe parameter entry
Returns
the default value for the given parameter as a pointer to a AtParamValue union, or NULL if the input pentry was NULL

◆ AiParamGetEnum()

AI_API AI_PURE AtEnum AiParamGetEnum ( const AtParamEntry *  pentry)

Return the enum type of a given enum parameter.

Parameters
pentrythe parameter entry
Returns
the enumerated type of the parameter, or NULL if the parameter is not an enumeration
See also
AtEnum

◆ AiParamGetTypeName()

AI_API AI_PURE const char * AiParamGetTypeName ( uint8_t  type)

Return the name of an Arnold data type.

For example, a parameter type AI_TYPE_RGB would return the string "RGB".

Parameters
typea parameter data type (one of AI_TYPE_FLOAT etc)
Returns
the name string for the given data type, or NULL if the type was invalid

◆ AiParamGetTypeSize()

AI_API AI_DEVICE AI_CONST int AiParamGetTypeSize ( uint8_t  type)

Return the size of an Arnold data type.

Parameters
typea parameter data type (one of AI_TYPE_FLOAT etc)
Returns
the size (in bytes) of the given data type, or 0 if the type was invalid

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

For instance, AiParamTypeConvertible(AI_TYPE_FLOAT, AI_TYPE_INT) would return true since an AtParamValue containing an int can be converted into an AtParamValue containing a float.

Parameters
dst_typetype of the destination value
src_typetype of the source value

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