MayaMan Help Contents

# MayaMan Light Attributes Dialog

The MayaMan Light Attributes dialog allows you to attach attributes to particular lights in your scene, so that they are rendered differently with MayaMan.

### Adding and Accessing the MayaMan Light Attributes

Before you can modify the MayaMan Light Attributes, you will have to add the attributes to the lights. You do this by selecting the light(s) you want to add the attributes to, then select "Add Light Attributes" from the MayaMan menu. All attributes are stored on a separate node, so several lights can easily share the same set of attributes.

By default, "Add Light Attributes" will add one shared/common attribute node for all the lights in the selection that do not already have attributes attached to them. In the optionBox of the menu, there are alternative ways in which to add the attributes, eg adding separate nodes to each object etc.

Once a light has a MayaMan Light Attribute node, you can simply access all attribute parameters in their own panel in the Maya Attribute Editor

## Depth Map Shadow Attributes

### Depth Map General

#### One Map For All Frames

This option will result in MayaMan generating a single shadow map for the light at the beginning of a render sequence, and reusing it for subsequent frames. This can be a large time saving if the shadows are not changing over the sequence.

#### Custom Shadow Map

This option allows you to specify an existing shadow map to be used by this light rather than MayaMan generating a name for you, or to specify a specific name to be used for maps that MayaMan generates. Be sure to turn on Reuse and turn off Delete for this light if you intend to use preexisting shadow maps.

If the value is a full path name then it is used as provided otherwise it will be interpreted as relative to the $RIBDIR/shadow_maps/<renderer> directory.

If it is a preexisting map and you don't provide a full path then you may need to add to the texture search path.

#### Reuse Mode

This option let's you take fine-grained control over which shadow maps get reused and which are recomputed.

#### Delete Mode

This option let's you take fine-grained control over which shadow maps get deleted at the end of the render and which are saved.

### Depth Map Use

#### Samples

The number of samples used when testing the shadow map. This can reduce the grain in the blurry areas of the shadow map. 16 is recommended as the minimum, and blurry maps can require values of 64 or more.

This value is also used to set the number of samples for an area light when the light this attribute node is attached to is NOT doing ray traced shadows and the light is the 'helper light' for the geometry that is being used as an area light.

#### Filter

You can choose a filter to use when sampling the shadow map for slightly different sampling effects.

### Depth Map Creation

#### Depth Filter

You can choose depth filtering as selected in Global Shadow Options, the global default only when the light it is not requesting MidDist, or an explicit depth filter.

#### Resolution

If either the X or Y value is 0 then the regular maya shadow map resolution will be used, otherwise the specified values will be used and rounded up to the nearest power of two. In the case of a directional light the map will still have square pixels... the map will have extra coverage on either the sides or the top and bottom. In the case of a spotlight the pixels will not be square... which may be useful if the shadow map (when projected into the scene) is stretched in one direction.

#### Auto Map / AutoMap Size

In Air a spotlight can have it's shadow map computed on the fly rather than up-front. This can be particularly useful with TweakAir

#### Z-Clipping

##### Near clipping distance

Objects which are closer to the light than this value will not cast shadows.

##### Far clipping distance

When enabled objects which are farther away from the light than this value will not cast shadows. When disabled the value used is effectively infinite.

#### ScanLine Options

It can be advantageous to adjust the bucketsize and gridsize options during the shadow map computation. These controls allow you to customize the values or to refer to the global settings for them. The new default behaviour is to use the global setting, prior to 1.2.34 the shadow ribs used the renderer's default settings rather than the global ones.

Note, some of these options may not be supported by some renderers.

##### BucketSize

When 'global' the shadow ribs for this light will contain the same bucket size settings as the main rib (if any)

When 'none' the behaviour is as it was prior to 1.2.34, that is to say, the shadow ribs did not contain a bucket size directive

When 'override' the bucket size is set from the X/Y values, unless the X values is -1, in which it's the same as the 'global'

##### GridSize

The mode and value work just like the BucketSize options above

#### Air 'MidDist' Extensions

##### MidDist Position

Set the mid point position during shadow map gen, a value of 0.5 gives classic midpoint behaviour, a value of 0 gives the equivalent of 'min' filtering, adjusting this value (usually to a value between 0 and 0.5) may reduce or eliminate midpoint shadow artifacts that can crop up when wide filtering is being used.

##### MidDist Max

Sets the max absolute distance between the mid postion and the nearest surface point, the default value (1e9) means that there is no restriction on the maximum distance between the near surface and the midpoint, smaller values may be useful for eliminating midpoint shadow artifacts.

#### PRMan Deep Shadows/Air Fragment Shadows

Enables PRman deep shadow computations or Air shadow fragment for this light.

#### Custom Display Driver

Normally MayaMan select the right type of display drivers for the creation of mapped shadows... very advanced users may have reason to use a custom display driver though.

#### Display Driver Arguments

The shadow display driver can have extra arguments added. This can be particularly useful for things like prman's pyramidal shadow map feature... just put the following in the arguments field:

``

    	"pyramid" [1]

Note that this can be used independently of the Custom Display Driver feature.

#### User Defined Shadow RIB Statements

RIB statements that are only inserted into the rib for this light.

## Ray Traced Shadow Attributes

#### Blur

Controls the focus of the ray bundle used to calculate the shadow

#### Bias

Controls the ray-bias used for calculating shadows, useful for avoiding self-shadowing artifacts.

#### Occlusion Shadows

When enabled, and raytraced shadowing is also enabled for the light, and the blur is > 0 and the number of shadow samples is > 0 this switch will trigger use of an alternate mechanism for shadow computation that is almost always far faster than a regular soft raytraced shadow.

Note that this is for PRMan users, Air users should use area lights which are implemented in mayaman with Air's areashadow() shadeop.

The blur value is handled in the same way as the other tracing so you'll get the same look from existing setups, just much faster.

#### Max Variation

For use with occlusion shadows, a time/quality knob.

## Caustics/Photon Mapping

For Air and Entropy you can set the number of photons to be shot from the light source in calculating caustics. Zero effectively turns off caustics for the light. Higher values will slow down the render. The Photons Only flag is not used.

For PRMan11 the controls are different, the number of photons is not set directly at the light source and the number here has no meaning, however, a light will only go into the photon map rib if it's 'Enabled' flag is turned on and there are a non-zero number of photons requested, this provides a way to only get photons from a certain set of lights. Sometimes it's useful to have lights in the scene that only generate photons but don't participate in regular lighting (ie: they simulate injection of photons from an environmental image), in this case turn on the Photons Only checkbox. Use the Photon Type setting to determine which photon maps a light will contribute to.

## Misc

#### Atmospheric

This enables the __foglight parameter which is used to control the behaviour of some lights, especially their interaction with volume shaders (primarily a BMRT concept, though if the light shaders are written to look for this parameter it can be used in other renderers as well).

#### Motion Blur Shadows

When enabled an RiPixelSamples statement will go into the shadow map rib. When and how this is useful is left to the reader as an exercise.

#### Categories

RenderMan supports the concept of light categories and here is where you supply them. Use commas to seperate category names if you need more than one. For a category to actually have any effect you'll need to write your own illuminance loops.

#### Include Default Categories

When enabled MayaMan will add various categories to the light so that surface shaders can do things like avoid running specular only lights on a non-specular surface. Sometimes these default categories can get in the way of users who are setting up advanced lighting effects. Turning this option off ensures that the category list supplied in the above option is used as is. You may also want to add some of the default categories back into the Categories explicitly, ie: if this option is off then the light will not properly respond to turning off the 'Emit Diffuse' flag, in this case you need to add 'nondiffuse' into the list of categories explicitly. The inbuilt categories are:

Category | Meaning
ambient | the light emits ambient light
diffuse | the light emits diffuse light
specular | the light emits specular light
hasshadows | the light will produce shadows
nondiffuse | the light does not emit diffuse light
nonspecular | the light does not emit specular light
noshadows | the light does not produce shadows

#### MaxDist

Some renderers will avoid running light shaders on lights that are far away... how far is controlled by this value.

## Custom Light Shader

This section allows you to attach a custom RenderMan light shader to your light. You need to first create a MayaManCustomLight node by pressing the 'Create New Custom Shader Node' button in the dialog. If you have any existing nodes you can type their name or browse to them. This will associate the custom light shader node with this light. You then view the light using the Maya Attribute Editor to set the shader file to use and any shader parameters.

## Shadow Casting Override Sets

These sets allow fine grained control over what objects contribute to shadows for a particular light (as far as depth mapped shadows goes anyhow).

Any surface in the 'On' group will cast shadows even if it is not a shadow caster. Any surface in the 'Off' group will not cast shadows.

It may be useful to use a set with more than one light... ie: an extra shadowing set applied to all key lights.

Clicking the checker icon in the attribute editor will create an empty set with an appropriate name.

Be sure to add shape nodes to the set... just as it's Maya's shape nodes that carry shadow casting information so too the override link. The sets contain full paths so individual instances of a particular shape can be in more than one set.

When drag-n-dropping a set from the Overview into the drop slot the connection editor will open, you need to connect the message output of the set to the appropriate attribute of the attributes node.

## Shadow Location Cheating

This section allows the combining or shadow maps from several lights into a shadow for one light. If the shadow from the light asking for the cheat is to be rolled into the mix then the light must also be listed in the shadow cheater slots.

The lights listed as shadow cheaters do not add light to the scene, mayaman automatically supresses them as they are assumed to exist purely to create a shadow map. If these lights are also supposed to cast light then they should also be configured as shadow cheaters and list themselves as shadow creators.

The Blend Width value for each shadow map controls how it's rolled into the mix. Typically you'll want to have a shadow map blended in in one of two ways, you'll want some group of high quality maps to be min'd together, that is to say, the shadow value should be the most shadowed of any of them. The other way of blending is to select the highest quality sample where highest quality is defined as the most number of shadow map pixels covered by projecting the micropolygon being shaded into the raster space of the shadow map. Telling MayaMan how to blend each shadow map into the result comes down to the order the maps are specified and the blend widths assigned. All the maps that should be combined with the min method should be listed first and should have a blend width of 0. These should then be followed by the maps that are expected to be of lower quality (ie: env fill).

The Bias value for each shadow map will set the bias value used for each lookup. The default value of -1 will cause the light's main bias value to be used instead.

## Soft Shadows

This section is similar to Shadow Location Cheating but is for renderers that support soft shadows.

## User Defined RIB Statements

A chunk of rib that will be inserted into the rib just after the RiLightSource call.

# Additional Light Related Attributes

## Ray Marching in Light Fog and Volume Fog

When a lightFog node is processed it's check for a couple of attributes which control how the raymarch quality. If the attributes don't exist they will be automatically created. MayaManStepSize is how far each integration step moves in world space, smaller values give higher quality. MayaManMaxSteps clamps the total number of steps, if the ray distance divided by the step size would rezult in more steps than this then the step size is increased regardless of the setting in MayaManStepSize.

MayaMan Help Contents