Object Lights – mental ray 3.11 *small update*

**UPDATE** Maya 2016 makes these lights an integrated option using the create menu.

Create Lights menu Maya 2016

Create Lights menu Maya 2016

**Maya 2015 SP3 delivers the builtin_object_light shader and works correctly/stably with mental ray 3.12 Be sure and follow the other tips like turning off the shading engine until integration is done.**

One of the most requested features for mental ray has been an object, or mesh, light. This is a somewhat experimental feature since it’s not exposed it was not tested in the Maya Betas. *There has been some talk of crashes, but sporadic. The cause has been found and is up for a fix now in mental ray, thanks for the extra reports to find it. Also, be sure and select not to Export with the Shading Engine in the Shading Group node to avoid the naming emission irregularity.*

Lighting a space using Final Gather from self-illuminated objects can be tedious to tune and costly in render times. Typically you need large amounts of rays (accuracy) from Final Gather to achieve smooth lighting this way. You can see such an example below with accuracy set to 1024.

Lighting using Final Father

Lighting using Final Father

An object light is the ability to define a shape as a light source. This allows greater flexibility in lighting scenes where a physical object is better (like a neon tube sign) or more efficient for rendering than an emissive plane with Final Gather.

The ability to make an object into a light has been available in mental ray for a long time and in an .mi file it’s a simple line that tells the renderer that the object is a light.

mental ray also supports geometric area light sources for point lights, specified by the object keyword. Its first argument must be the instance of a single-group object that defines the geometry of the area light source. All points on the surface of the object will emit light uniformly. It is generally a good idea to keep the triangle count of the object as low as possible for maximum performance. The sampling rates usually have to be set much higher for object lights.

If you look at the .mel for the area light AEtemplates in Maya, you’ll see legacy code where this was accomplished at some point in the past but disabled. The usual reasoning is that object lights can generate a lot of noise in a render that is difficult to clean up.

However, since the inclusion of Unified Sampling, you’ll see that cleaning up area light noise is much easier with fewer samples than before. This makes for a faster render that’s easier to control.

mental ray 3.11 includes a new shader called the builtin_object_light that tells mental ray that the object is a light. This circumvents anything that might be required by integration to work.

There is no library file that is needed for this shader, e.g. .dll, .so etc. Since it is “builtin” you just need the .mi declaration saved in the include folder for the mental ray plug-in. You can copy the code below and save the file. Keep in mind you should save these scenes as .ma if you wish to maximize compatibility since there are no node IDs for this shader.

    declare shader
       color "builtin_object_light" (
       color "surface" default 1 1 1 1,
       light "light"
       version 1
       apply material, photon
    end declare

I saved it in Windows here: C:\Program Files\Autodesk\mentalrayForMaya2014\shaders\include

Opening Maya (being sure it’s loaded under the Shader Manager).

Shader Manager

Shader Manager

You can now see the simple UI below.

Builtin Object Light

Builtin Object Light

The simple workflow is:

Assign builtin_object_light material to Object -> create area light -> attach area light .message to Light parameter of builtin_object_light shader. (This picture needs updated below, you should attach the transform, not the shape)

Area Light connected to the Object Light Shader

Area Light connected to the Object Light Shader


Object Light, no FInal Gather

Object Light, no Final Gather

You will notice that the object light still follows the shape node rendering flags like cast and receive shadows. That’s why there is a ring shadow around the box. This is not particularly intuitive so you can turn off cast and receive shadows and render again.

Control certain attributes through the Shape node

Control certain attributes through the Shape node

Cast and Receive Shadows Off

Cast and Receive Shadows Off

For these examples I have the “visible” parameter of the Area Light On. This means the object light primary ‘look’ is controlled through the “shape intensity” of the Area Light and the light shader. If this option is off, the look is controlled through the builtin_object_light “surface” control.

I actually recommend you leave that parameter On when possible. Having the Area Light Visible set to “Off” causes direct reflection sampling of the light even if the object is still visible. Instead you should use the Shape Node Render Stats to control the visibility of the light like you would any object in the scene.

Below I have the walls of the box semi-reflective and moved the light so that it’s more obvious when it’s hidden.

Box with reflective sides

Box with reflective sides

Now I will turn off the primary visibility on the Shape Node as seen below.

Primary Visibility Off

Primary Visibility Off

Here is the resulting render:

Primary Visibility Off

Primary Visibility Off

So now you can control how the light is sampled and seen in your image.

Also notice that light shaders applied to the area light will work as well but may have unintuitive consequences. In some cases light quadratic falloff of the visible light and not just the light effect itself is noticed. This means as the light is scaled or moved into the distance, it will change primary intensity (its lighting effect remains the same).

Being creative with node networks will also allow you to do things like cutouts and transparency on a light as seen below. The light in the scene is a solid plane with a checkerboard attached as illumination as well as connected to a mib_continue to allow rays to pass through. The alpha of the light is also controlled in the same way. The box is left slightly reflective as above to show the reflection of the checkerboard on the back wall.

Checkerboard Procedural along with alpha transparency.

Checkerboard Procedural along with alpha transparency.

These options will also combine with the new Light Importance Sampling found in 3.11 for textured lights.

Light Importance Sampling (light IS)

Light Importance Sampling in mental ray 3.11 will allow mental ray to distribute samples more effectively on textured area lights.

Why would I use Light IS?

This means samples are more efficient when lighting a scene where you may have textured object lights or bounce cards using an HDRI as the light source. This is similar to the user_ibl shaders but is now a core feature, potentially applying to more light types in your scene through a global option. In this way, once it is integrated it will deprecate the user_ibl shaders.

You can find more about this in the release notes and enable them in Maya using String Options. Below is an example from the documentation of settings:

The String Option: “light importance sampling” has three settings.

  • off or "off", default. Importance sampling is not applied.
  • on or "on". Importance sampling is enabled for rectangular and disc area lights with high emission variance, and for all spherical, cylindrical and object lights. This mode is useful for rectangular and disk light with uniform intensity. In this case the core will check to see if the light emission has sufficient variance (between light and dark) to justify light importance sampling (Light IS). Non-planar lights (like an object light for example) always compute for light IS. This also applies to planes being used as Object Lights despite being similar to a rectangular light. This means it is sampled for Light IS but may not make a difference in render quality if not textured.
  • "always". In addition to “on”, importance sampling is enabled on all rectangle and disk lights. This mode means Light IS is used even if the variance of the light emission is low and might be ignored otherwise. (An additional variance option exists if you want to tweak what is considered to be enough variance to trigger light IS)

There is also “light importance sampling precomp” string option with values of on or off. This option presamples lights (there’s some overhead before rendering) for lights with HDRI attached to them. This can reduce the variance (noise) in a final image. Take note your image might look slightly different with this option on. This option is a compliment to the settings above as it changes how the lights are sampled during the render but not required. Recommended if a lot of your lights are using HDRI or high variance textures.

All of the modes will present log output telling you if the lights you have are being considered for Light IS. If there is more overhead for sampling but your log tells you the lights aren’t using Light IS (not textured or not enough variance) then you might switch it off and render normally.

Take care that since the mayastate shader has not been updated to be aware of this option it will generate a long warning log with “unexpected ray” readouts.

This is a feature that will have more explanation at a later time since it is more involved.

About David

I am a VFX artist that specializes in Lighting and Rendering. I spend a fair amount of my time supplying clients with artistic solutions as well as technology solutions. With a background in fine art and technical animation training, I strive to bridge the divide between the artist and technologist.

Posted on April 21, 2013, in Lighting and tagged , , , . Bookmark the permalink. 65 Comments.

  1. thanks for the post David. things are coming together. really looking forward to getting this all working

  2. I like finalFather!

  3. Really loving this technique!

    But strange things are happening from the moment you use more than 1 of these object lights. Only the last object casts light (the other a tiny bit). Even with separate Builtin_object_lights and seperate area lights.
    Might it be linked to the lack of node ID’s for this shader?
    Hope there is a workaround.

    Thanks for all the knowledge here!

    • The Node ID is related to the fact that other Maya versions and scene import might have trouble recognizing the shader since there are no IDs. You may find that if the shader is removed from the mental ray plug-in, those scenes might suddenly think a different shader is applied.

      Not experienced that issue yet with multiple lights but if I can reproduce it I will certainly send it. Since it’s experimental right now there are still changes to come to it.

    • Crash cause has been found, now just waiting for the fix and AD to update the version of mental ray. To help solve the emission problem, de-select “export with shading engine” on the SG shader node.

  4. Thanks again for this great article,

    I made it work once, but since then, every time I try, the light seems to come from somewhere else than the ‘light’ object itself. I really don’t understand what I am doing wrong. I tried pretty much everything (I could think of). When I plug a mental ray shader in the area light, everything goes black, is that normal ?

  5. Hi David,
    seems that if you have an object named pSphere# in your scene in maya this takes precedence over the actual geometry attached to the light and the light emits from this Sphere instead. This could be why jack is seeing errors. Change the name of the sphere and it behaves as expected. Took me a while to figure this out… hope it helps

    • Ok I tested some more and it seems to be related to the alphabetical name of the object that is emitting the light. If you have 2 object lights in your scene emitting from 2 separate objects( plane1,sphere1) the light is only emitted from one of those objects but at the sum of the intensity of the 2 lights. The object that emits the light is determined by whether its name is alphabetically last (sphere1). Change the name of the other object to something like zplane1 and it will now emit all the light.

  6. Awesomest post ever… if I could get it to work. I’m following this post step by step but cannot get light to emit from the object. I’m getting a solid color from the shape, but no light. Anyone else have this issue? (Maya 2014, MR, Win 8)

    • To clarify, the .mi file works correctly, the builtin_object_light node seems to work fine, hooks up to the mesh and light without any issues, everything seems to work just fine, but no emitted light.

      • I made a goof in the post I need to fix, make sure you’re connecting the transform, not the shape node. Mayatomr usually catches that but can be a problem later. Also, what is your scene scale? Sometimes it’s very faint with quadratic cutoff and some light shaders will make the source dim as well based on distance from viewer (unintuitive in this case) so it might look like it’s not on.

        The source of the instability is being researched. In all honesty, if Autodesk would just re-integrate the standard object light method, the workaround wouldn’t be necessary.

  7. Thanks David that seems to have fixed it and i’m getting some pretty good results although I can’t wait till they fix those random crashes. Cheers for your help.

  8. is it normal i get “Warning: … Couldn’t find shader library: builtin_object_light.dylib” at maya start? Seems to work fine though.

  9. does the just released maya 2014 service pack address the crashing problems?

  10. Just tried with 2 objects with 2 different shaders, works well at first but very unstable. If I try to hide/show lights it could just go black and never work again, unless I reload Maya

    • (can’t modify the previous message ^^; )
      I get this error “fatal 041052: accessing unknown tag 0x8”
      In the end of the day i find all these lego stuff kinda annoying, makes me want to go back to V-ray…

      • As mentioned, this feature wasn’t integrated into Maya correctly, so it’s experimental. The bug has since been fixed but it hasn’t been released with Maya yet. The first section above in the post should explain that some more.

  11. Hello David,
    As Nico and Jack, I’ve experienced some weird light effects and trouble having more than one object light. The difference between “No decay and Quadratic” and none having a special setting for the intensity… is quite disturbing. It will be nice to have a proper new object “light” with everything included !!! So, for the moment I use a Mia material + a Mia Light Surface.

  12. Hi, i created a object, and paste text to Mentalray text. I Saved as .mi in the include folder. I follow workflow , after connect the arealight1.message to light of object light, the area light still appear in the scene and the object have little bit of lighting. Help me, what i’ve did wrong. Sorry about my english. i hope you understand.

    • So you’re saying that right now both the area light and the object light are emitting light into the scene? Make sure you are turning on the mental ray section of the area light.

  13. Hi, great post. I have this working but am running into the same issue as Jack, having multiple instances(copies not instanced) of the light mesh only one renders as emitting light and if I turn that one off the next one works, and so on. Has there been a fix found for this problem? Thanks again.

  14. things are working great now, no crashes. i’m setting the shape to rectangular and using the physical_light. It works the same if i suppress maya shaders (on the light and/or on the shading group) or not, so that doesn’t seem to matter anymore.
    i’ve tried it with light is and is precomp, seems to be fine.
    i do get this warning:
    // Warning: (Mayatomr.Custom) : builtin_object_light1: connection to light shape areaLightShape1 detected, linking first instance areaLight1 instead //
    not sure what that’s about

    • It wants the transform, not the shape node.

      • that did it! now to sort out the mib_continue thing. thanks

      • enabling or disabling ‘visible’ on the light’s shape, using a physical_light as the light shader, has no effect. Not sure what i’m doing wrong.
        When you say we can control the look using the object light’s ‘surface’ control do you mean we would use something like the mib_blackbody in the color gain slot of the file node’s ‘color balance’ section? That seems to work but i’m not sure that’s what you mean
        i notice that disabling double sided on the object shape or running the mib_continue through a mib_twosided will keep light from coming out the back, is one way better than the other?
        the alphabetical thing still happens but i’m sure i can find a simple workaround for that

      • Use visibilty flags on the shape node, not the light. And disable export with shading engine on the shading group node of the object light shader.

      • i have some really nice hdr lights, esp. now with the alpha they looking great. but the light they’re sending out looks like crap, even with brute force, total crap. i don’t see how they can replace the ibl_rect or light surface or portal as card. maybe you can give more detail on their usage

      • ok, i’ve just been at it too long at this point. i will pick it up again tomorrow. everything will be fine. didn’t mean to freak out

      • Depending on the HDRI and shape used, object lights will create noise initially. This is part of why they have been left out of Maya for so long. (This is true regardless of renderer)

        Have you tried using the new light importance string options to improve this?

      • Also, give lights more than just 1 sample. For importance sampling you need a few for mental ray to evaluate it properly. This is why we also suggested more than one sample in the Area lights 101 post.

      • with light IS there is a redistribution of noise but that’s all, no noticeable improvement in quality. It also increases render time by about 30%, but i think my tests, a nurbs torus with an hdr texture as the object light inside a large nurbs globe, similar to the tests above, may be too simple to be a viable indicator of performance.
        increasing samples increases render time but has no noticeable effect on quality.
        I’m going back to the old way for now. Maybe the upcoming ui will make it clearer how to get good results.

  15. just wanted to add that i am testing this with maya2015 and mr3.12

  16. what is the correct way to set the ‘shape intensity’? it would be nice to be able to keyframe that setting, or drive it with an expression, in response to changes in the light’s relative position and variations in the light’s ‘intensity’


    • I usually set it manually although if the area light is marked as “visible” it will use the light shader itself and if you’ve keyframed it it will carry over theoretically.

      • after some testing it seems that the correct value for the ‘shape intensity’ is 2pi when the light’s ‘intensity’ is set to 1 with the light 1cm away from the object.

        using that, i wrote an expression that keeps ‘shape intensity’ at the correct level based on the lights ‘intensity’ and its distance the from the object:


        this works great, but it’s correct for only one distance.

        i’m ok with it working this way, it should not be a problem to find a compromise in most cases, but is it possible to have the reflections be accurate at more than one distance using the ‘visible’ option?

      • I usually manipulate that setting to be more artistic for what I want to see. The physical light should have a fix for energy based on the light scale and distance, are you using that?

      • i’m using the maya area light set to mental ray area with quadratic decay and the light shader slot left empty, like we discussed on the forum. if i plug the physical_light with ‘visible’ enabled, the highlights appear no longer respect the hdr plugged in to the light’s color slot – it looks fake

        thing is, if i disable ‘visible’, and use the builtin_object_light’s surface information, the light reflections no longer look correct to me – they look too dim. that could be that i’m doing something wrong or that i’ve been looking at the ‘visible’ highlights for so long that they have started to look correct.

        i guess for now i will use it like it is, with the expression, and just set the shape intensity falloff distance to be correct at the place where i expect people to look


      • i realized i needed to plug my hdri into the color slot of the physical_light (obviously). but when i do that, the reflections, not of the ibl surface, but the surfaces (standard mila materials) very close to that surface, reflects differently than they do when the light shader slot is left empty – so i’m still not sure which one to use

        the solution i’m looking for is to have reflections to be physically accurate, but also allow for artistic/optimization tweaks to be applied on top of that. is that currently possible?

      • MILA obeys reciprocity unlike MIA materials. For now this physical approach will lead the way towards MDL and automatic lighting. This means your lights visibility and color need to match. Otherwise the materials don’t know what to evaluate. This will also make MIS unpredictable when included in mr 3.13 if you try that. When it samples the light or the reflection it will get two very different results. This essentially breaks MIS.

  17. real world scales will make the light just dim. is there a way to make it work like a real area light.

    • Real world energies are actually very very high. The problem is in VFX we’re interested in the look only. And high energies might create fireflies. I have a scene now where the spotlight is using an HDRI from a set spotlight where the realistic energy is about 260,000 RGB

      You can override the visible look of the light by using the surface parameter instead of the light shader control.

  18. mental ray also supports geometric area light sources for point lights, specified by the object keyword. Its first argument must be the instance of a single-group object that defines the geometry of the area light source. All points on the surface of the object will emit light uniformly. It is generally a good idea to keep the triangle count of the object as low as possible for maximum performance. The sampling rates usually have to be set much higher for object lights.


    I’d like to understand what is meant by the above quoted that is posted in this blog ?

    It appears to me that in Mental Ray there are still a bit of headaches with regards to setting up Object Lights, as there appears to be doubts from some of the replies to this post. As well I don’t understand what is meant by this;

    Since it is “builtin” you just need the .mi declaration saved in the include folder for the mental ray plug-in ?

    In Mental Ray must you save you scene as a .ma file instead of an mb file ?

    • mental ray can use object lights or what others might call mesh lights. The builtin include file allows you to use the native builtin object lights in mental ray. Improved Light Importance Sampling (light IS) can be used with these lights making them much more efficient. Since this material is not assigned an ID by the integration, it’s safest to save the file as .ma to avoid conflicts with “unknown nodes”. You might find that this workflow will improve later since it’s a very much in-demand feature.

  19. Hi,
    It must be a stupide question, but how do I assign the builtin light object to the mesh ?

    • It’s a material shader, builtin_object_light. Assigned like any shader. But needs to be connected to an area light transform too so it know how to light the scene.

  20. Florian Schwab

    Hello David,

    thank you for the detailed explanation, this looks wonderful.
    But I’m struggling with the same issue that Jack’s facing, I cannot assign the builtin_object_light as a material to the mesh I’d like to act as a light source. When middle mouse dragging over the node in hypershade, I only get the option to “Graph network”. Also, the node appears under MentalRay Lights, not Materials.

    I’m using Maya 2015, SvP5.

    • This has since been simplified. If you can use Maya 2016 (just released) it’s now a simple conversion selection in the “Create” menu.

      • Florian Schwab

        I see.
        What if one’s stuck with 2015, is it necessary to perform said conversion manually?
        And if so, how is this done?

        Best, flo

  21. For christ sake someone tell me how to change intensity of the object light ?
    I followed it works but can’t change intensity

  1. Pingback: Creating Object Lights in Mental Ray Using the Built In Object Light Shader

  2. Pingback: Maya 2014 – mental ray changes | elemental ray

  3. Pingback: Maya 2015 – mental ray changes | elemental ray

  4. Pingback: New GI Prototype Quick Start | elemental ray

  5. Pingback: Maya 2016, new features and integration | elemental ray

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: