Arnold - C++ Shaders
Adding Parameters

return to main index

Links:
    Cutter & Writing Arnold C++ Shaders

Overview

This page demonstrates how to use Cutter to add and use a float parameter and a enum parameter to a shader.

Step 1

Go to the Templates->Arnold Shaders->mkSampleShader.cpp menu item.

Save the document, for example, mkParamDemo.cpp in your
    maya/projects/Arnold_Shaders/src_c++/
directory.
Go to line 32 and change,
    node->name = "NAME_OF_YOUR_SHADER";
to
    node->name = "mkParamDemo";
Make sure the node name matches exactly the name of the document (without the .cpp extension).

Step 2 - Adding a Float Parameter

At line 19 use the right mouse button and select,
    Declare Shader Parameters->AiParameterFlt

Figure 1

Edit line 19 so that the new parameter has a name (no spaces are allowed in the name) and a default value. For example,

    AiParameterFlt("patternOffset", 0.5);

Add additional named constant to the paramIndex enum (line 13). For example,

namespace {
    enum paramIndex { k_base_color, k_pat_color, k_pat_offset };
    };

Step 3 - Adding a Enumerated Parameter

When used in Maya an enumerated parameter will be displayed as a dropdown menu. At line 20 use the right mouse button and select,
    Declare Shader Parameters->AiParameterEnum

Figure 2

Edit line 20 so that the new parameter has a name, a default index and the name of the array that will list the labels for the dropdown. For example,

     AiParameterEnum("patternMode", 0, uv_mode);

Add additional named constant to the paramIndex enum (line 13). For example,

namespace {
    enum paramIndex { k_base_color, k_pat_color, k_pat_offset, k_pat_mode };
    };

At line 15 insert the following declaration of an array of strings that will be used as labels for the dropdown menu.

    static const char* uv_mode[] = { "U", "V", NULL };

Step 3 - Using the Float and Enum Parameters

At line 27 use the right mouse button and select,
    Evaluate Shader Parameters->AiShaderEvalParamFlt
Edit the line as follows.

    float offset = AiShaderEvalParamFlt(k_pat_offset);

At line 28 again use the pupup menu and select,
    Evaluate Shader Parameters->AiShaderEvalParamEnum
Edit the line as follows.

    int   mode = AiShaderEvalParamEnum(k_pat_mode);

Replace this code,

    sg->out.RGB() = (sg->u >= 0.5) ? pat : base;

with the following lines of code.

    if(mode == 0)
        sg->out.RGB() = (sg->u >= offset) ? pat : base;
    else
        sg->out.RGB() = (sg->v >= offset) ? pat : base;

Finally, recompile and build the shader using the keyboard shortcuts Alt+e, Control+e or Apple+e.

Step 4 - Using the Shader in Maya

Launch Maya, open HyperShade, select the new shader and confirm the shader's UI is correct.

Figure 3

Listing 1 (mkParamDemo.cpp)

#include <ai.h>
#include <cstring>
  
AI_SHADER_NODE_EXPORT_METHODS(SampleMethods);
 
namespace {
    enum paramIndex { k_base_color, k_pat_color, k_pat_offset, k_pat_mode };
    };
static const char* uv_mode[] = { "U", "V", NULL };
  
node_parameters {
    AiParameterRGB("baseColor", 0.7f, 0.7f, 0);
    AiParameterRGB("patternColor", 0.7f, 0, 0);
    AiParameterFlt("patternOffset", 0.5);
    AiParameterEnum("patternMode", 0, uv_mode);
    }
 
shader_evaluate {
    AtRGB base = AiShaderEvalParamRGB(k_base_color);
    AtRGB pat = AiShaderEvalParamRGB(k_pat_color);
    float offset = AiShaderEvalParamFlt(k_pat_offset);
    int   mode = AiShaderEvalParamEnum(k_pat_mode);
    if(mode == 0)
        sg->out.RGB() = (sg->u >= offset) ? pat : base;
    else
        sg->out.RGB() = (sg->v >= offset) ? pat : base;
    }
 
node_loader {
    if (i > 0)
        return false; 
    node->methods        = SampleMethods;
    node->output_type    = AI_TYPE_RGB;
    node->name           = "mkParamDemo";
    node->node_type      = AI_NODE_SHADER;
    strcpy(node->version, AI_VERSION);
    return true;
    }
    
// The remaining macros can be left "empty"
node_initialize { }
node_update { }
node_finish { }