MayaMan Help Contents

# Mixing Maya Shaders and RenderMan Shading Language

MayaMan has a mechanism for blending RenderMan Shading Language (SL) and Maya shading networks, this mechanism is the SLCodeNode, a repository for SL code that can be embedded into a shading network, the magic shaders mechanism will insert your code and connect any inputs/outputs.

### SLCodeNode

The SLCodeNode is a 'Utility' node. Once you have created one there are three phases to using it.

First, create inputs, use the controls in the 'Add Parameter' section to create inputs by selecting data type, parameter name and default value, then press the 'Create' button. A new value will be placed in the 'Extra Attributes' for each input. These inputs can be connected to other nodes in the same manner as any input of any maya shading node.

Second, create outputs, this procedure is the same as input creation except that you turn on the 'Output' checkbox. When an output parameter is created a declaration is added to the SL code. Due to a maya limitation output variables appear in the Extra Attributes panel, manipulating these values will have no effect on the result and they should be ignored... a good reason to create them all at once after the inputs.

Third, write the SL code. Write SL code as you normally would, don't declare any variables outside the curly braces that are automatically inserted. To refer to a input or output parameter put '$' in front of the name. The execution environment for the code will have several handy values pre-defined.... for example, for code to be used in surface or displacement shaders the PS variable contains the current point in shader space and Nf contains the normalized forward facing normal at the point (in current space) with the effect of any downstream bumping rolled in.

### Add Parameter Controls

#### Type

The SL data type for the variable.

#### Name

The name for the SL parameter... use this value prefixed with a '$' in the SL Code.

#### Node Output

The parameter is something that your SL Code produces for piping into other nodes.

#### Shader Output

The parameter is something that your SL Code produces for use with an AOV (extra output channel)... in which case it should not also be a Node Output!. Shader output variables should not be declared anywhere in the body of the shader code, it will be provided automatically by mayaman... the code only needs to write to it. For clarity, you may choose to not use the '$' in front of the parameter inside the shader code.

#### PrimVar

The parameter will always be have a shader arg declared, this allows the value to be overridden by the geometry. Normally if a value is an input and it's not varying the resulting shader will not have an argument for the value as the constant value will be substituted instead.

#### Array

Is the parameter a single instance of the data type or an array of them? NB: arrays must be declared with a fixed size at creation time.

#### Varying

The parameter will always have a shader parameter declared and it's storage class will be varying... useful in conjunction with PrimVar.

#### TexConv

Should the string parameter undergo texture conversion?

#### No Param

Does the attribute exist purely for the purposes of driving other attributes or other nefarious networking purposes? If so then there is no need for it to appear in the shader's parameter list as it will just contribute to shader bloat.

#### Default

The value the parameter will have if not connected, if it's an output variable then it's the result the parameter will have if you don't compute it.

### SL Code

#### SLInclude

If your code requires helper functions it may be a good idea to put them in a header file and put the name of the header file in here. At the moment there is no mechanism to set the include search path for the compiler so it's recommended that you either use a full path name or store your header files in the 'shaders' folder of the mayaman distribution.... the second way will make it easier for you to share code nodes with the rest of your crew.

#### Efficiency Considerations

MayaMan sets up several flags that provide context to your shader. Checking these flags and changing the behaviour of your shader code can provide large efficiency gains.

##### only_do_opacity

The only_do_opacity flag is set to 1 when the surface shader should only compute opacity information. Use this flag to skip lighting, reflection/refraction ray tracing, occlusion calculations, etc.

##### no_tracing

The no_tracing flag may be set by mayaman in certain contexts where reflection/refraction raytrace effects are to be globally suppressed, at the moment this is only during certain baking operations.

##### __importance/__refrDepth/__reflDepth

Thresholds at which __importance values operate can be set here. The __importance value (a color) starts out at 1/1/1 and is diminished in various ways (ie: transparency, fresnel fractions, etc.). You should add the following to calls to gather/occlusion/indirectdiffuse: `

    	SEND_IMPORTANCE_TO_SURFACE(importance_scale,is_refraction,is_reflection)

` Search maya_magic_shaders.h for examples of usage, in particular note that macro is not preceded by a comma in the argument list as it is an empty macro for some renderers.

The value passed to this macro as the importance_scale will be used to scale the current __importance value as passed to the next surface shader.

The is_refraction value is added to the current __refrDepth count, likewise with is_reflection and __reflDepth.

A typical usage for a reflection will look something like this: ``

    	float nsamps = ceil(samples * INTENSITY(__importance));
    	gather("illuminance", P, dir, PI/2, nsamps, ...., "label", "reflection" SEND_IMPORTANCE_TO_SURFACE(1/nsamps,0,1));

Note the second and third arguments to SEND_IMPORTANCE_TO_SURFACE, they will cause the refraction depth to stay the same and the reflection depth to go up by one.

MayaMan will use the fade/cull thresholds from it's GUI and the incoming __importance value to compute a blending value that should be used to attenuate the results from raytracing (so that the effect fades off rather than pops off at the culling threshold). SLCodeNode authors can use the 'importance_atten' variable to scale the result. There is also a convenience macro to check if this value is black so that raytracing can be avoided... and of course a reflection should only be gathered if the shader is not being asked to only compute opacity so a well formed check would look like this: ``

      color traced_color = 0;
      if(only_do_opacity==0 && no_tracing == 0 && CHECK_IMPORTANCE) {
        traced_color = gather(....);
        traced_color *= importance_atten;
      }

MayaMan Help Contents