Setting ShaderDef Attributes

 
 
 

Attributes can be defined on the shader definition as well as per parameter definition. For example, you can set one of the PPGLayout attributes directly on a shader definition, such as setting the help file location. On shader parameter definitions, attributes can be used to specify the parameter data type, set which property look-up or reference widget to use on the associated property page, or set the colour for a custom data type.

Like renderer options, attributes are stored on a ValueMap or ValueMap, which is similar to an associative array, being composed of name/value pairs. You access the value map containing a shader definition's attributes via the ShaderDef.Attributes or ShaderDef::GetAttributes member.

Note

You can also set attribute values before adding parameter definitions using the ShaderParamDefOptions.SetAttribute or ShaderParamDefOptions::SetAttribute method, as the ShaderParamDefOptions or ShaderParamDefOptions object stores parameter attributes and other settings

Here are the tasks you can perform on a ValueMap:

Task to perform

ValueMap member

Comments

Adding or modifying a single entry

ValueMap.Set or ValueMap::Set

Takes the name and value as its arguments. If there is no entry matching the specified name, a new entry is added; otherwise the existing value is overwritten.

Retrieving a single entry

ValueMap.Get or ValueMap::Get

Gets the value for the entry matching the specified name.

Note

If the value is undefined, the method throws an error.

Deleting a single entry

ValueMap.Remove or ValueMap::Remove

Removes the entry matching the specified name. The method will not throw an error if no match is found.

Iterating over the list of entries

Names and Values properties (Object Model)

The ValueMap interface gives you access to the list of names as well as the list of values, so you can skip the names completely and just iterate over the values, or you can iterate over the names and use each entry to access the matching value via the ValueMap.Get or ValueMap::Get member.

ValueMap::GetAll function (C++ API), which takes names and values output arrays as arguments

Python Example: Setting, Removing, and Iterating Over ShaderDef Attributes

Python and VBScript work well with safearrays, so iterating over the entries in a ValueMap is quite straightforward:

# Get the ValueMap from the shader definition and add a couple of entries
oAttribs = oShaderDef.Attributes
oAttribs.Set("user", "test")
oAttribs.Set("a", 123456)

# Get the safearray of names and use each name to find the matching value
aAttribNames = oAttribs.Names
Application.LogMessage("Before removal there are %d attributes" % len(aAttribNames))
for vKey in aAttribNames :
	Application.LogMessage("Attribute key,value: %s, %s" % (vKey, str(oAttribs.Get(vKey))))

# Remove one of the entries from the list
oAttribs.Remove("user")
aAttribValues = oAttribs.Values
Application.LogMessage("After removal there are %d attribute(s) left" % len(aAttribValues))

# Results:
# INFO : Before removal there are 2 attributes
# INFO : Attribute key,value: a, 123456
# INFO : Attribute key,value: user, test
# INFO : After removal there are 1 attribute(s) left

JScript Example: Setting a Writable Image Type for a ShaderParamDef

This example demonstrates how to set a shader parameter definition as a writable image data type.

// When you set up the options for your shader parameter definition you could
// set parameter attributes using the ShaderParamDefOptions object
var oParamDefOpts = XSIFactory.CreateShaderParamDefOptions();
oParamDefOpts.SetAttribute(siWritableImageAttribute, true);
oParamDefOpts.SetTexturable(true);
oParamDefOpts.SetInspectable(false);

// Alternatively, you could use the Attributes property to get the ValueMap and
// set the siWritableImageAttribute directly on the ValueMap
var oInParamDefs = oShaderDef.InputParamDefs;
var oParamDef = oInParamDefs.AddParamDef("texture", siShaderDataTypeImage, oParamDefOpts);
oParamDef.Attributes.Set(siWritableImageAttribute, true);