- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions

# MLightLinks Class Reference
OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Example C++ plug-in descriptions.

Search for all occurrences

## Detailed Description

Class providing read-only Light Linking API functions.

This class provides read-only access to the light linking information expressed in Maya's light linker nodes.

Usage

To extract Maya's light linking information, use the following sequence of calls:

1. Call parseLinks() once. MLightLinks will examine the connections to the scene's light linker nodes, and compile the information into a table of light-object links. parseLinks() needs to be recalled whenever the scene's light linking changes (objects/lights are added or deleted, or light links are made or broken).
2. Call getLinkedLights() or getLinkedObjects() to query the lights linked to a particular object, or the objects (and components) linked to a particular light.

Lights can be linked either to DAG hierarchies or to shading groups. Additionnally, light linking information can store a list of illuminating lights and a list excluded lights. The algorithm used to determine which light should contribute can be described by the pseudo code below.

- If the entire object is all in one shading group, then only consider object-level light links. The code to compute lightList will look like:

        MObject nullObj;                                     // A void component object
        getLinkedLights(objectPath, nullObj, lightList);

- If different parts of the object belong to different shading groups, then the list of lights is the union of object and shading group linked lights, where the ignored lights have been removed. The code to compute lightList will look like:

for each face group on the object, corresponding to each shading engine, do the following:

        MObject nullObj;                                     // A void component object
        getLinkedLights(objectPath, nullObj, ObjectLink);    // Lights linked to the whole object
        getIgnoredLights(objectPath, nullObj, ObjectIgnore); // Lights ignored on the whole object
        getLinkedLights(objectPath, component, FaceLink);    // Lights linked to the face component
        getIgnoredLights(objectPath, component, FaceIgnore); // Lights ignored for the face component

For the given face group, the set of lights illuminating it are then (ObjectLink - FaceIgnore) + (FaceLink - ObjectIgnore).

It is important to note that component linking works at the granularity of a shading group on a surface. In order to get results from the MLightLinks API, it is necessary to pass in components that correspond exactly to all the faces on that object in a particular shading group. For example, if pPlaneShape1.f[0:10] belongs to a shading group which is linked to a given light, then there will be no result from MLightLinks::getLinkedLights() if the argument is set to pPlaneShape1.f[0], or pPlaneShape1.f[0:5], or pPlaneShape1.f[10], etc - it must be exactly pPlaneShape1.f[0:10].

Examples:

  listLightLinksCmd.cpp.

`#include <MLightLinks.h>`

List of all members.

## Public Member Functions
| MLightLinks ()
| Constructor.
| ~MLightLinks ()
| Destructor.
MStatus | parseLinks (const MObject &linkNode=MObject::kNullObj, bool verbose=false, std::ostream *stream=NULL, bool useIgnore=false, bool componentSupport=true)
| Compiles the information contained in a light linker node into a table of object/light links.
MStatus | getLinkedLights (const MDagPath &path, const MObject &component, MDagPathArray &lights)
| Queries the light link table to find the lights that are linked to a particular object or object component.
MStatus | getLinkedObjects (const MDagPath &light, MSelectionList &objects)
| Queries the light link table to find the objects or object components that are linked to a particular light.
MStatus | getIgnoredLights (const MDagPath &path, const MObject &component, MDagPathArray &lights)
| Queries the light link table to find the lights that ignores a particular object or object component.
MStatus | getIgnoredObjects (const MDagPath &light, MSelectionList &objects)
| Queries the light link table to find the objects or object components that are ignored to a particular light.
MStatus | getShadowLinkedLights (const MDagPath &path, const MObject &component, MDagPathArray &lights)
| Queries the light link table to find the lights that are shadow linked to a particular object or object component.
MStatus | getShadowLinkedObjects (const MDagPath &light, MSelectionList &objects)
| Queries the light link table to find the objects or object components that are shadow linked to a particular light.
MStatus | getShadowIgnoredLights (const MDagPath &path, const MObject &component, MDagPathArray &lights)
| Queries the light link table to find the lights that ignore a particular object or object component when casting shadows.
MStatus | getShadowIgnoredObjects (const MDagPath &light, MSelectionList &objects)
| Queries the light link table to find the objects or object components that are ignored to a particular light when calculating shadows.

## Member Function Documentation

MStatus parseLinks | ( | const MObject & | linkNode = `MObject::kNullObj`,
|  | bool | verbose = `false`,
|  | std::ostream * | stream = `NULL`,
|  | bool | useIgnore = `false`,
|  | bool | componentSupport = `true`
| ) |  |

Search for all occurrences

Compiles the information contained in a light linker node into a table of object/light links.

The getLinkedLights() and getLinkedObjects() methods are used to query this table.

Whenever light linking information changes (objects are added/deleted or links are made/broken), the parseLinks() method must be called to update the table with the new link information, otherwise the query methods will return outdated information.

Parameters:

  [in] | linkNode | The light linker node to be parsed. If this parameter is set to the null object (the default), then all light linker nodes in the scene will be parsed. It is highly recommended that this default be used.
  [in] | verbose | Enables verbose output from the parsing procedure (default false).
  [in] | stream | Stream to which debugging information is output when 'verbose' is set to true.
  [in] | useIgnore | light/object relationship will be queried using getIgnoreObjects or getIgnoreLights. getLinkedObjects and getLinkedLights are not affected.
  [in] | componentSupport | Use component level light links where specified.

Returns:
  - MS::kSuccess Operation was successful, table was generated successfully.
  - MS::kInvalidParameter Operation failed because a non-lightlinker node was supplied for the 'linkNode' parameter.

Examples:
  listLightLinksCmd.cpp.

MStatus getLinkedLights | ( | const MDagPath & | objectPath,
|  | const MObject & | objectComponent,
|  | MDagPathArray & | linkedLights
| ) |  |

Search for all occurrences

Queries the light link table to find the lights that are linked to a particular object or object component.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | objectPath | The object whose linked lights are desired.
  [in] | objectComponent | If non-null, specifies that only lights linked to the specified component on the object should be returned. Otherwise, only lights linked to the entire object will be returned.
  [out] | linkedLights | Returns the DAG paths of the lights linked to the specified object or component.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getLinkedLights().

Examples:
  listLightLinksCmd.cpp.

MStatus getLinkedObjects | ( | const MDagPath & | lightPath,
|  | MSelectionList & | linkedObjects
| ) |  |

Search for all occurrences

Queries the light link table to find the objects or object components that are linked to a particular light.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | lightPath | The light whose linked objects are desired.
  [out] | linkedObjects | Returns the list of objects/components that are linked to the specified light.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getLinkedObjects().

Examples:
  listLightLinksCmd.cpp.

MStatus getIgnoredLights | ( | const MDagPath & | objectPath,
|  | const MObject & | objectComponent,
|  | MDagPathArray & | ignoredLights
| ) |  |

Search for all occurrences

Queries the light link table to find the lights that ignores a particular object or object component.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | objectPath | The object whose linked lights are desired.
  [in] | objectComponent | If non-null, specifies that only lights that ignore the specified component on the object should be returned. Otherwise, only lights that ignore the entire object will be returned.
  [out] | ignoredLights | Returns the DAG paths of the lights that ignores the specified object or component.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getIgnoredLights().

MStatus getIgnoredObjects | ( | const MDagPath & | lightPath,
|  | MSelectionList & | ignoredObjects
| ) |  |

Search for all occurrences

Queries the light link table to find the objects or object components that are ignored to a particular light.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | lightPath | The light whose ignored objects are desired.
  [out] | ignoredObjects | Returns the list of objects/components that are ignored to the specified light.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getIgnoredObjects().

MStatus getShadowLinkedLights | ( | const MDagPath & | objectPath,
|  | const MObject & | objectComponent,
|  | MDagPathArray & | linkedLights
| ) |  |

Search for all occurrences

Queries the light link table to find the lights that are shadow linked to a particular object or object component.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | objectPath | The object whose shadow linked lights are desired.
  [in] | objectComponent | If non-null, specifies that only lights shadow linked to the specified component on the object should be returned. Otherwise, only lights shadow linked to the entire object will be returned.
  [out] | linkedLights | Returns the DAG paths of the lights shadow linked to the specified object or component.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getShadowLinkedLights().

MStatus getShadowLinkedObjects | ( | const MDagPath & | lightPath,
|  | MSelectionList & | linkedObjects
| ) |  |

Search for all occurrences

Queries the light link table to find the objects or object components that are shadow linked to a particular light.

parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | lightPath | The light whose shadow linked objects are desired.
  [out] | linkedObjects | Returns the list of objects/components that are shadow linked to the specified light.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getShadowLinkedObjects().

MStatus getShadowIgnoredLights | ( | const MDagPath & | objectPath,
|  | const MObject & | objectComponent,
|  | MDagPathArray & | ignoredLights
| ) |  |

Search for all occurrences

Queries the light link table to find the lights that ignore a particular object or object component when casting shadows.

This is referred to as shadow ignoring the objects. parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | objectPath | The object whose shadow ignored lights are desired.
  [in] | objectComponent | If non-null, specifies that only lights that shadow ignore the specified component on the object should be returned. Otherwise, only lights that shadow ignore the entire object will be returned.
  [out] | ignoredLights | Returns the DAG paths of the lights that shadow ignores the specified object or component.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getShadowIgnoredLights().

MStatus getShadowIgnoredObjects | ( | const MDagPath & | lightPath,
|  | MSelectionList & | ignoredObjects
| ) |  |

Search for all occurrences

Queries the light link table to find the objects or object components that are ignored to a particular light when calculating shadows.

These are referred to as shadow ignored objects. parseLinks() must have been called at some point to generate the table that is being queried.

Parameters:

  [in] | lightPath | The light whose shadow ignored objects are desired.
  [out] | ignoredObjects | Returns the list of objects/components that are shadow ignored to the specified light.

Returns:
  - MS::kSuccess Operation was successful.
  - MS::kFailure Operation failed because a successful call to parseLinks() had not been performed prior to calling getShadowIgnoredObjects().

MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks
MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks MLightLinks