Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.ILight

The ILight graph node interface.

This interface represents a light source in world space. The light's position and direction cannot be specified directly; instead, a separate ILightTransform node must be used that references the ILight node it is supposed to move/rotate.

To enable colored light, the SetColor() method of the Graph::IColored base interface can be used.

By default, the light source's direction runs along the negative Z axis, i.e. parallel to the default camera viewing direction. The default position is (0/0/0). Depending on the actual type of this light source, either the light's position, direction, or both are used for lighting calculations:

  • DIRECTIONAL: Only direction is used. The light's position is ignored, resulting in parallel light rays, like a light source inifinitely far away.
  • POINT: Only position is used, with light rays emitted in all directions from that point.
  • SPOT: Light rays are emitted from the given point, in the given direction.

See sceneGraphStatesSlotsUnits for an overview of state handling during scene graph traversal.
See Graph::ILightTransform for setting a light's position and orientation.
See Graph::ILightState for activating lights for rendering.


Table members

Inherited


Murl.Graph.IColored
Murl.Graph.IStateUnit

Methods


GetNodeInterface()

Get the constant INode interface. This method returns a constant pointer to the node's INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant INode interface, or null if not available.

GetSubjectInterface()

Get the constant ISubject interface. This method returns a constant pointer to the node's ISubject interface, to be able to query subject properties such as world transform, viewing matrix, projection matrix etc.

Murl.Graph.ISubject GetSubjectInterface()

Returns
Murl.Graph.ISubject The mutable ISubject interface, or null if not available

GetSubLightNodeTarget()

Get the constant container holding the optional child lights. This method returns a constant pointer to the node's Graph::ILightNodeTarget sub container, which is used to store multiple sub-lights.

Murl.Graph.IGenericNodeTarget.GraphILight GetSubLightNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphILight The constant Graph::ILightNodeTarget container, or null if not available.

GetTextureNodeTarget()

Get the constant Graph::ITextureNodeTarget container. This method returns a constant pointer to the node's Graph::ITextureNodeTarget container, which allows to query an optional texture to project onto the geometry affected by the light.

Murl.Graph.IGenericNodeTarget.GraphITexture GetTextureNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITexture The mutable Graph::ITextureNodeTarget container, or null if not available.

SetType(type)

Set the light type. This method sets the type of light, either directional, point or spot light.

Boolean SetType(Murl.IEnums.LightType type)

Parameters
typeThe light type to set.
Returns
Boolean true if successful.

GetType()

Get the light type.

Murl.IEnums.LightType GetType()

Returns
Murl.IEnums.LightType The light type.

SetShape(shape)

Set the light shape. This method sets the shape of the light's projection. This is only useful when a projected light texture is used.

Boolean SetShape(Murl.IEnums.LightShape shape)

Parameters
shapeThe light shape to set.
Returns
Boolean true if successful.

GetShape()

Get the light shape.

Murl.IEnums.LightShape GetShape()

Returns
Murl.IEnums.LightShape The light shape.

SetIntensity(intensity)

Set the light intensity. The light intensity can be queried in a shader via the uLightSpotN.z uniform variable, with N being the light unit where the light is currently bound. By default, the intensity is set to 1.0.

Boolean SetIntensity(Number intensity)

Parameters
intensityThe light intensity to set.
Returns
Boolean true if successful.

GetIntensity()

Get the light intensity.

Number GetIntensity()

Returns
Number The light intensity.

SetAttenuation(constant, linear, quadratic)

Set the light attenuation parameters. This method sets all three light attenuation parameters (constant, linear and quadratic), given as individual values.

Boolean SetAttenuation(Number constant, Number linear, Number quadratic)

Parameters
constantThe constant light attenuation value.
linearThe linear light attenuation value.
quadraticThe quadratic light attenuation value.
Returns
Boolean true if successful.

SetAttenuation(values)

Set the light attenuation parameters. This method sets all three light attenuation parameters (constant, linear and quadratic), packed into a given vector's X, Y and Z components, respectively.

Boolean SetAttenuation(Murl.Math.Vector values)

Parameters
valuesA vector holding the light attenuation parameters.
Returns
Boolean true if successful.

SetConstantAttenuation(value)

Set the constant light attenuation parameter.

Boolean SetConstantAttenuation(Number value)

Parameters
valueThe constant light attenuation value.
Returns
Boolean true if successful.

SetLinearAttenuation(value)

Set the linear light attenuation parameter.

Boolean SetLinearAttenuation(Number value)

Parameters
valueThe linear light attenuation value.
Returns
Boolean true if successful.

SetQuadraticAttenuation(value)

Set the quadratic light attenuation parameter.

Boolean SetQuadraticAttenuation(Number value)

Parameters
valueThe quadratic light attenuation value.
Returns
Boolean true if successful.

GetAttenuation()

Get the light attenuation parameters.

Murl.Math.Vector GetAttenuation()

Returns
Murl.Math.Vector A vector holding the light attenuation parameters, packed into its X, Y and Z components.

GetConstantAttenuation()

Get the constant light attenuation parameter.

Number GetConstantAttenuation()

Returns
Number The constant light attenuation value.

GetLinearAttenuation()

Get the linear light attenuation parameter.

Number GetLinearAttenuation()

Returns
Number The linear light attenuation value.

GetQuadraticAttenuation()

Get the quadratic light attenuation parameter.

Number GetQuadraticAttenuation()

Returns
Number The quadratic light attenuation value.

SetSpot(exponent, cutoffAngle)

Set the spot exponent and cutoff angle value.

Boolean SetSpot(Number exponent, Number cutoffAngle)

Parameters
exponentThe spot exponent value in the range [0, 128].
cutoffAngleThe spot cutoff angle in the range [0, PI/2] radians.
Returns
Boolean true if successful.

SetSpot(values)

Set the combined spot exponent and cutoff angle value.

Boolean SetSpot(Murl.Math.Vector values)

Parameters
valuesA vector containing the spot exponent value in the range [0, 128] in the X component, and the spot cutoff angle in the range [0, PI/2] radians in the Y component.
Returns
Boolean true if successful.

SetSpotExponent(exponent)

Set the spot exponent value.

Boolean SetSpotExponent(Number exponent)

Parameters
exponentThe spot exponent value in the range [0, 128].
Returns
Boolean true if successful.

SetSpotCutoffAngle(cutoffAngle)

Set the spot cutoff angle in degrees.

Boolean SetSpotCutoffAngle(Number cutoffAngle)

Parameters
cutoffAngleThe spot cutoff angle in the range [0, PI/2].
Returns
Boolean true if successful.

GetSpot()

Get the combined spot exponent and cutoff angle value.

Murl.Math.Vector GetSpot()

Returns
Murl.Math.Vector A constant reference to a vector containing the spot exponent value in the range [0, 128] in the X component, and the spot cutoff angle in the range [0, PI/2] radians in the Y component.

GetSpotExponent()

Get the spot exponent value.

Number GetSpotExponent()

Returns
Number The spot exponent value in the range [0, 128].

GetSpotCutoffAngle()

Get the spot cutoff angle in radians.

Number GetSpotCutoffAngle()

Returns
Number The spot cutoff angle in the range [0, PI/2].

SetAspectRatio(ratio)

Set the light's aspect ratio used for shadow maps. When using directional or point lights for rendering into a shadow map, this method (together with any of the SetFieldOfView methods below) can be used to define the actual volume considered for generating the shadow map.

Boolean SetAspectRatio(Number ratio)

Parameters
ratioThe X:Y aspect ratio.
Returns
Boolean true if successful.

GetAspectRatio()

Get the current aspect ratio.

Number GetAspectRatio()

Returns
Number The X:Y aspect ratio.

SetFieldOfView(fovX, fovY)

Set the field of view at the minimum distance. This method sets both the horizontal and vertical field of view values. See SetAspectRatio().

Boolean SetFieldOfView(Number fovX, Number fovY)

Parameters
fovXThe horizontal field of view.
fovYThe vertical field of view.
Returns
Boolean true if successful.

SetFieldOfViewX(fovX)

Set the horizontal field of view, at the minimum distance. See SetAspectRatio().

Boolean SetFieldOfViewX(Number fovX)

Parameters
fovXThe horizontal field of view.
Returns
Boolean true if successful.

SetFieldOfViewY(fovY)

Set the vertical field of view, at the minimum distance. See SetAspectRatio().

Boolean SetFieldOfViewY(Number fovY)

Parameters
fovYThe vertical field of view.
Returns
Boolean true if successful.

GetFieldOfViewX()

Get the horizontal field of view.

Number GetFieldOfViewX()

Returns
Number The horizontal field of view, or 0.0 if variable.

GetFieldOfViewY()

Get the vertical field of view.

Number GetFieldOfViewY()

Returns
Number The vertical field of view, or 0.0 if variable.

SetMinDistance(distance)

Set the light's minimum influence radius. The given value only has effect when rendering a projected light texture. In this case, it represents the near plane distance of the light projection matrix.

Boolean SetMinDistance(Number distance)

Parameters
distanceThe minimum distance.
Returns
Boolean true if successful.

SetMaxDistance(distance)

Set the light's maximum influence radius. This method sets the radius of the light's bounding sphere, which is used to determine the nearest light source within a group, for every geometry object for which the respective group is active. For rendering projected light textures, this also represents the far plane of the light projection matrix.

Boolean SetMaxDistance(Number distance)

Parameters
distanceThe radius of the bounding sphere.
Returns
Boolean true if successful.

GetNearestStages(boundingVolume, stageIndices, maxStages)

Get the stage indices of the N nearest sub-lights.

Integer, Murl.Array.UInt32 GetNearestStages(Murl.Graph.IBoundingVolume boundingVolume, Murl.Array.UInt32 stageIndices, Integer maxStages)

Parameters
boundingVolumeThe bounding volume to check the sub-lights against.
stageIndicesA reference to an array of stage indices to write to.
maxStagesThe size of the output array.
Returns
Integer The actual number of stage indices written.
Murl.Array.UInt32 stageIndices A reference to an array of stage indices to write to.

GetNumberOfStages()

Get the light's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.

GetBoundingVolume(stage)

Get the light's bounding volume for a given stage.

Murl.Graph.IBoundingVolume GetBoundingVolume(Integer stage)

Parameters
stageThe stage to query.
Returns
Murl.Graph.IBoundingVolume The bounding volume, or null if the light has infinite influence.

GetMinDistance(stage)

Get the light's minimum influence distance for a given stage.

Number GetMinDistance(Integer stage)

Parameters
stageThe stage to query.
Returns
Number The minimum distance.

GetMaxDistance(stage)

Get the light's maximum influence radius for a given stage.

Number GetMaxDistance(Integer stage)

Parameters
stageThe stage to query.
Returns
Number The maximum distance.