---
title: "PxrPortalLight"
canonical: "https://rmanwiki-25.pixar.com/space/REN25/20416358/PxrPortalLight"
format: markdown
---
Although a portal light is a rectangular shape, it is not interchangeable nor replaceable by a [PxrRectLight](https://renderman.atlassian.net/wiki/spaces/REN25/pages/20416382) because we get the illumination from the 3D environment using a [PxrDomeLight](https://renderman.atlassian.net/wiki/spaces/REN25/pages/20416370) .
PxrPortalLight is *one-sided*. That is, there is no illumination behind the portal. If we need to illuminate the back side, we can create another portal facing the reverse direction.
We can add light filters to a portal light like any other lights. In fact, a PxrBarnLightFilter works great with this type of light.
For more information you can consult the technical paper:
- Benedikt Bitterli, Jan Novák, Wojciech Jarosz. [Portal-Masked Environment Map Sampling](https://www.disneyresearch.com/publication/portal-masked-environment/). Eurographics Symposium on Rendering (EGSR), 2015
> ⚠️ Portal Lights do not work with the PxrEnvDayLight system. Use a PxrDomeLight with an appropriate HDRI or HDRI sequence.
> ⚠️
> ⚠️ All portal lights that are associated with the same parent dome light and the same portal name *must have the same rotation* . If you need to change a portal light's rotation, then you need to have a new portal name. However, different translation and scaling can share the same portal name.
**"Why do I use a portal light?"**
Since lighting interiors with little or no direct lighting is difficult for a renderer to resolve, portal lights help direct the renderers attention to the exterior source of light. RenderMan can make excellent use of the PxrPortalLight as shown below on the classic Classroom scene. Both images are rendered with the same 32 samples per pixel. But you can plainly see how much more effective the result is with portal lights on the right than without on the left.
### Parameters
#### Basic
**Intensity Multiplier**
Intensity adjustment relative to the parent dome light intensity. This gets multiplied by the parent dome light's intensity and power.
| | | |
| --- | --- | --- |
|  |  |  |
**Color Tint**
This parameter tints the color from the dome texture. Below each portal has a different color assigned for a nice rainbow effect.
**Map Gamma**
Gamma-correct the texture. Each channel (RGB) can be adjusted independently. If this map gamma is unchanged from its default, then it will inherit the map gamma from the parent dome light.
**Map Saturation**
Adjust the saturation of the texture. If this map saturation is unchanged from its default, then it will inherit the map saturation from the parent dome light.
**Enable Temperature**
Turns color temperature on or off.
| | | |
| --- | --- | --- |
|  |  |  |
**Color Temperature**
Allow the user to choose the color temperature of the light in Kelvins. Unlike the basic light color, this allows the user to easily pick plausible light colors based on standard temperature measurements.This control will act like a filter or gel (a tinted transparent surface) in front of your light. If your light is white, you will get the chosen color temperature. If your light is colored, the color temperature will make it cooler (over 6500K) or warmer (below 6500K).
> ℹ️ The effect will be less pronounced on fully saturated mono-chromatic lights. Defaults to 6500K, which should be very close to white on most monitors (D65 illuminant used by sRGB and Rec 709).
**Primary Visibility**
The light isn't directly visible to the camera by default. Turning this on makes it visible and can be written to an LPE using the emission token, 'O'
** **
---
#### Refine
**Specular Amount**
Amount of specular light that is emitted. This is a non-physical control. You could use a light with **Specular Amount** 0.0 to act purely as a source of diffuse light for your scene objects and avoid adding highlights. Note that the scene still collects indirect reflection off other objects in the room.
| | | |
| --- | --- | --- |
|  |  |  |
**Diffuse Amount**
Amount of diffuse light that is emitted. This is a non-physical control. You could use a light with **Diffuse Amount** 0.0 to act purely as a source of highlights for your scene objects.
| | | |
| --- | --- | --- |
|  |  |  |
---
#### Shadows
> ⚠️ All shadow parameters will be ignored if the light's **Trace Light Paths** is enabled in Advanced. The below options are all non-physical controls when used out of their default state. If **Trace Light Paths** is enabled then their physical nature is enforced.
**Enable Shadows**
Enable raytraced shadows. Below is on (default) and off.
**Shadow Color**
The color of the shadows cast by emitted light. Below there's Red, Green, and Blue from different portal lights.
.0 0.0 0.0
**Shadow Max Distance**
The maximum distance of the shadow starting from the position of the point being shaded. -1.0 is unset which will use the distance between the point being shaded and the point on the light. You may use this control to artificially reduce the distance shadows are cast. This may also increase render speed by not calculating shadows outside this distance. Notice the shadows of chair and table legs as they are cut off after a distance and the shadow on the wall at the front of the classroom.
| | | |
| --- | --- | --- |
|  |  |  |
**Shadow Falloff**
The distance from the light at which shadow falloff begins. -1.0 turns off shadow falloff. This is used along with **Shadow Max Distance** to create a false fade for shadows that are reduced or cut off by the **Shadow Max Distance** parameter. Below is an example with both parameters being used and the falloff is increased. Note this parameter may impact performance on complex lighting setups.
| | | |
| --- | --- | --- |
|  |  |  |
**Shadow Falloff Gamma**
The gamma of the shadow strength in the falloff zone. This requires the use of **Shadow Max Distance ** and ** Shadow Falloff** .
| | | |
| --- | --- | --- |
|  |  |  |
**Trace Subset**
Set of geometry to consider for traced shadow intersection. If this is not specified, all geometry are considered for traced shadow intersection.
**Don't Trace Subset**
Set of geometry to ignore for traced shadow intersection. If this is not specified, all geometry is used for traced shadow intersection.
---
#### Advanced
**Trace Light Paths**
Enable light and photon tracing from this light. This value enforces a physically-based light and as a side-effect disables the above **Shadows** controls. Users may use this feature to selectively decide which lights emit photons when using the PxrVCM or PxrUnified Integrators.
**Thin Shadow**
Enable thin shadow and disable refraction caustics for this light. This parameter will ignored if **Trace Light Paths** is enabled. This is a non-physical control that creates "fake" colored shadows for transmissive objects without needing to generate photons for caustics. Below we go from On (default) to Off (opaque shadowing). Notice we lose the colored shadows and interior colored reflection choosing Off, but we gain some render speed instead.
**Visible in Refraction**
Make a light visible through transmission effects like glass and windows by turning this on.
**Manifold Walk**
Used with the PxrUnified Integrator and enabling **Enable Manifold Walk** to create inexpensive caustics. Note: You must disable Thin Shadows
**Manifold Walk Exclude Group**
Used with the PxrUnified Integrator and enabling **Enable Manifold Walk, **this trace set is ignored during manifold exploration to avoid stopping or shadowing manifold exploration rays
**Light Samples**
Specifies an override of the number of light samples to be taken for this light source. If set to something other than zero, it will override the sampling performed by the integrator. You might find need for this if you have unsolvable noise from this light and need more samples.
**Light Group**
Specify the light group name used for light group LPEs. This is useful to generate per-light AOVs for later adjustment in compositing.
**Importance Multiplier**
Rather than setting explicit Light Samples, users can change the amount of samples the light will be assigned internally by changing this value. RenderMan creates a set of samples at render time for all lights in the scene and changing this value rebalances the samples across the lights. Note that increasing this value will cause *more* samples to be selected from this light while reducing it for others in the scene. Lower than the default will *decrease* the samples while providing more to others in the scene.
---
### Application Interface
The bridge application such as RenderMan for Maya or Katana provides a convenient interface to create and link a portal light to its parent dome light. It also automatically assigns unique portal names for the portal lights that do not have the same rotation as the parent dome light's. By default, the portal light inherits all the parameters from its parent dome light. If a parameter is modified in the portal light, then the local overridden parameter will be used instead. There are two exceptions: *intensity and color gets multiplied to the parent dome's intensity and color*.
The bridge product will emit all the modified parameters to the RIB for PxrPortalLight. Note that PxrDomeLight is not being emitted.