Light

Last revision: ver. 5.1 - 5 November 2013

module cyclops extends SceneNode wraps the cyclops::Light

Defines a light for the scene. After creation, lights are automatically attached to the scene root node. Lights need to be explicitly turned on using the setEnabled method. Cyclops supports point, spot and directional lights by default, but custom light functions can be added by the user.

Methods

Method(s)	Description
Light create() static	Creates a new light object
setColor(Color color)	Sets the diffuse color for this light. See Color.
setAmbient(Color color)	Sets the ambient color for this light. Ambient color will be considered only for the main scene light (see SceneManager.setMainLight). See Color.
bool isEnabled(), setEnabled(bool value)	Gets or sets the light enabled value
setAttenuation(float consant, float linear, float quadratic), Vector3 getAttenuation()	Sets or gets the light attenuation values. getAttenuation() returns the attenuation parameters as a Vector3 object.
setLightType(LightType type), LightType getLightType()	Sets or gets the light type.
setLightFunction(string), string getLightFunction()	Sets or gets the light function.
setLightDirection(value), string getLightDirection()	Sets or gets the light direction for Spot or Directional light types.
setSpotExponent(float value), float getSpotExponent()	Sets or gets the spot exponent for Spot lights.
setSpotCutoff(float value), float getSpotCutoff()	Sets or gets the spot cutoff for Spot lights.
Shadow Mapping
setShadow(ShadowMap shadow), ShadowMap getShadowMap()	Sets or gets the shadow map for this light. See ShadowMap.
setShadowRefreshMode(ShadowRefreshMode srm)	Sets the shadow refresh mode. Supported values are ShadowRefreshMode.OnFrame, ShadowRefreshMode.OnLightMove

Light Types

The setLightType() method accepts a value from the LightType enumeration. Supported values are:

• Point: for point lights
• Directional: for directional lights
• Spot: for spot lights
• Custom: for custom lights

Custom lights allow the user to specify a custom, per pixel light function:

	scene = getSceneManager()
	
	// Use the customFragmentFunctions macro to inject code into fragment shaders.
	scene.setShaderMacroToString('customFragmentFunctions', '''
		customLightFunction(SurfaceData sd, LightData ld)
		{
			// Trivial example: return a fixed color regardless of light or surface properties
			return vec4(1, 0, 0, 0);
		}
	'''
	)
	
	light = Light.create()
	light.setType(lightType.Custom)
	light.setLightFunction('customLightFunction')

Examples

Creating a headlight

Added: ver. 3.3 - 29 January 2013

In some applications you want to have a light attached to the main camera: when the camera moves and rotates the light should follow. This is very easy to implement, given that the Camera class derives from SceneNode, and it can have children attached to it:

	# Create a full white headlight
	headlight = Light.create()
	headlight.setColor(Color("white"))
	headlight.setEnabled(True)
	getDefaultCamera().addChild(headlight)

Remember the light will be attached by default at the camera origin: inside a VR system this does not correspond to the head position of the tracked user. If you want to take the head offset into account, you can make the light follow the head trackable object. Add the following line:

	headlight.followTrackable(headTrackableId)

Where headTrackableId is the integer Id of the head trackable (check your VR system config file or tracker configuration for this). Note that you need to attach the light to the camera AND to the head trackable to have a full headlight. Without attaching the light to the camera, the light will not move when navigating in the scene.