DiskLight

Overview

DiskLight is a light-emitting flat disk of a specified radius. The disk lies in the local (x,y)-plane of the light’s coordinate system and can be oriented and placed using the node_xform attribute. Additionally, it supports all the common attributes for controling its brightness, color, etc.

Note that by default the light will be emitted from a single surface of the disk - the one corresponding to the positive direction of the light’s local z-axis. This behavior can be changed via the sidedness attribute.


Attribute Reference

Map attributes

contrast

Rgb
default: [ 1, 1, 1 ]

Per-channel contrast used in color-correcting the light's texture, if one is present. The operation mimics Nuke's ColorCorrect node's contrast function:
For input > 0, output = 0.18 * pow(inputCompnent/0.18, contrast).
For input <= 0, output = 0.18 * input * pow(1/0.18, contrast).

gain

Rgb
default: [ 1, 1, 1 ]

Per-channel gain used in tandem with a per-channel offset for color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = input * gain + offset

gamma

Rgb
default: [ 1, 1, 1 ]

Per-channel gamma used in color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
For input > 0, output = pow(input, gamma)
For input <= 0, output = input

offset

Rgb
default: [ 0, 0, 0 ]

Per-channel offset used in tandem with a per-channel gain for color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = input * gain + offset

saturation

Rgb
default: [ 1, 1, 1 ]

Per-channel saturation used in color-correcting the light's texture, if one is present. This is achieved by applying the following formula for each channel:
output = lerp(luminance(inputRGB), input, saturation).

temperature

Vec3f
default: [ 0, 0, 0 ]

Color temperature using Nuke-style T/M/I settings (T = temperature, M = magenta/green, I = intensity). This is achieved as follows:
The 3-channel temperature is interpreted as the vector (T,M,I). The followiong scale values are then applied to the RGB components:
outputR = inputR * (pow(2,I) + M/3 - T/2)
outputG = inputG * (pow(2,I) - 2*M/3
outputB = inputB * (pow(2,I) + M/3 + T/2)

texture

String filename
default:

File name of the texture applied to the light. If set to the empty string, no texture is applied. Any file format supported by OpenImageIO can be used. The texture is used in 2 ways - for looking up the texture value at the intersection point when a ray hits the light, and for building a lookup-table-based auxilliary data structure used for distributing light samples over the texture.

texture_border_color

Rgb
default: [ 1, 1, 1 ]

RGB value used when a texture lookup occurs outside the texture.

texture_coverage

Vec2f
default: [ 1, 1 ]

Texture scales in the u and v-directions.

texture_mirror_u

Bool
default: False

Whether to mirror the texture in the u-direction. If set to false, the texture is repeated in the u-direction.

texture_mirror_v

Bool
default: False

Whether to mirror the texture in the v-direction. If set to false, the texture is repeated in the v-direction.

texture_reps_u

Float
default: 1.0

Number of times texture repeats in u over the scaled texture space.

texture_reps_v

Float
default: 1.0

Number of times texture repeats in v over the scaled texture space.

texture_rotation

Float
default: 0.0

Clockwise rotation angle in degrees.

texture_translation

Vec2f
default: [ 0, 0 ]

Translation of the texture in (u,v)-space, in units of the texture size. For example, a translation of (0.25, 0.5) will translate the texture one-quarter of its width in the u-direction and one-half of its height in the v-direction.

Properties attributes

apply_scene_scale

Bool
default: True

Whether to apply scene scale variable when normalized.

clear_radius

Float
default: 0.0

Shadows less than this distance from the light are ignored. Setting this value to 0.0 or less effectively disables this feature.

clear_radius_falloff_distance

Float
default: 0.0

Distance over which the shadows fall off. Shadows are fully visible at a distance clear_radius + clear_radius_falloff_distance from the light, and fully invisble at a distance clear_radius from the light.

clear_radius_interpolation_type

Int enum
  0 = “linear” (default)
  1 = “exponential_up”
  2 = “exponential_down”
  3 = “smoothstep”

Interpolation type to use for the clear radius shadow falloff.

color

Rgb
default: [ 1, 1, 1 ]

The light's RGB values.
These are combined multiplicatively with the intensity and other attributes in determining the light's 3-channel radiance.

exposure

Float
default: 0.0

The light's exposure value.
This value provides an alternative to the intensity value as a mechanism for controlling the light's overall brightness, and is inspired by the corresponding photographic term but is generalised to apply independently to each light. To calculate its effect, pow(2, exposure) is combined multiplicatively with the color and other attributes in determining the light's 3-channel radiance.

intensity

Float
default: 1.0

The light's intensity.
This is combined multiplicatively with the color and other attributes in determining the light's 3-channel radiance.

label

String
default:

Label used in light aov expressions.

max_shadow_distance

Float
default: 0.0

The distance from the light beyond which a light-receiving surface will no longer receive shadows cast from that light.
Note that the distance is thresholded for each occlusion ray cast for this light, it is possible for a receiving point to lie at an intermediate distance such that some parts of the light are closer than the threshold distance and other parts beyond it, in which case the point will appearto be in partial shadow.

mb

Bool
default: False

Whether motion-blur is active for this light. When set to true, the scene's illumination will correctly account for any blur() applied to the light's transformation matrix.

normalized

Bool
default: True

When set to true, the size of the light can be changed without altering the amount of total energy cast into the scene. This is achieved via scaling the light's radiance by the reciprocal of its surface area. When set to false, the radiance is used as-is, regardless of surface area.

on

Bool
default: True

Whether the light is switched on.

presence_shadows

Int enum
  0 = “force off”
  1 = “force on”
  2 = “use default” (default)

Switch this attribute on for shadows cast from this light to correctly respect presence values. When off, surfaces with a material with presence less than 1.0 will cast opaque shadows from this light. This is an optimization - when the attribute is off, occlusion rays (fast) are used for testing for shadows. When it is on, regular rays (slower) are used, and the material's presence is evaluated to determine how much shadowing should occur. When set to "use default" it reads from the value of SceneVariable enable_presence_shadows.

radius

Float
default: 1.0

The radius of the DiskLight.

ray_termination

Bool
default: False

Whether the light is used for ray termination color. Ray termination color is used for filling in falsely dark areas where ray paths have been terminated too early by the depth controls. Such a ray path immediately exits to any ray termination light(s) present in the light set being applied to the lobe, ignoring occlusion by scene geometry. Any light can either be a regular light or a ray termination light (but not both). Thus they can be freely assigned to light sets, which provides a mechanism for applying specific ray termination lights to specific materials, parts or objects. Ray termination color is only applied to non-hair transmission lobes.

sidedness

Int enum
  0 = “regular” (default)
  1 = “reverse”
  2 = “2-sided”

When set to 0 (regular), light is emitted from the front-facing surface of the disk. When set to 1 (reverse), light is emitted from the back-facing surface of the disk. When set to 2 (2-sided), light is emitted from both surfaces of the disk.

spread

Float
default: 1.0

The directionality of light emission. 1 is completely diffuse hemisphere. 0 is parallel to normal of light.

texture_filter

Int enum
  0 = “nearest neighbor” (default)
  1 = “bilinear”
  2 = “nearest neighbor with nearest mip”
  3 = “bilinear with nearest mip”

The filtering mode to apply to the texture. Nearest neighbor is the cheapest filtering mode but produces a blocky result. Switch linear filtering on for a smoother result. Additionally, mip-mapping can be switched on with either nearest neighbor or linear filtering.

visible_in_camera

Int enum
  0 = “force off”
  1 = “force on”
  2 = “use default” (default)

Whether the light is directly visible in the scene's active camera. When set to "use default" it reads from the value of SceneVariable lights_visible_in_camera.

Visibility Flags attributes

visible_diffuse_reflection

Bool
default: True

Whether the light is visible in diffuse reflection.

visible_diffuse_transmission

Bool
default: True

Whether the light is visible in diffuse transmission.

visible_glossy_reflection

Bool
default: True

Whether the light is visible in glossy reflection.

visible_glossy_transmission

Bool
default: True

Whether the light is visible in glossy transmission (refraction).

visible_mirror_reflection

Bool
default: True

Whether the light is visible in miror reflection.

visible_mirror_transmission

Bool
default: True

Whether the light is visible in miror transmission (refraction).

General attributes

light_filters

SceneObject Vector
default: {}

Vector of LightFilters associated with the light.

node_xform

Mat4d blurrable
default: [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]

The 4x4 matrix describing the transformation from local space to world space.


Examples

DiskLight("/lights/disk") {
    ["node_xform"] = Mat4(-0.70710678, 0, 0.70710678, 0, 0.70710678, 0, 0.70710678, 0, 0, 1, 0, 0, 1.0, 2.0, 3.0, 1),
    ["color"] = Rgb(1.0, 0.9, 0.6),
    ["intensity"] = 3.0,
    ["radius"] = 2.0,
}