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

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 const AtParamValueAiParamGetDefault (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)
 

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:

{
AiParameterInt("octaves", 3);
AiParameterFlt("lacunarity", 1.92f);
AiParameterBool("turbulence", false);
}

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

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

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

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