SceneGraph

Index

Light

Derived from:	Node3D
Class name:	Light3D
Description:	It adds a light source to the scene. The light source can be manipulated like any other node, including activation/deactivation and transformations. The light sources are point lights such as spot lights and directional lights. Lights also have a range of effect (and a near range for defining the closest-to-light distance for the shadow map) as well as an RGB color value which can be set to any (un-normalized) value, i.e. greater than (1,1,1).

Function List

Name	XE_light_set_light_type
Arguments	int node_id, XE_LIGHT_TYPE light_type
Return Type	bool
Description	Sets the light type for this light node. Currently, the following point light types are supported: - Spotlights (point lights with position, intensity and directional variance by specifying a cut-off angle) Spotlights use standard shadow maps with PCF for the generation of shadows Spotlights, also support the generation of additional map which store normal and lighting information from the light's point of view (RSM) - Directional lights (point lights with direction and intensity), mainly used for approximating long distance light sources, such as the sun. Directional lights use CSM (Cascaded Shadow Maps) Parameters: - node_id, the node id of a light node - light_type, the light type based on the XE_LIGHT_TYPE enum. Returns true if the node id was found
Notes:	enum XE_LIGHT_TYPE { LT_POINT_PARALLEL, LT_POINT_SPOT, LT_NONE };

Name	XE_light_get_light_type
Arguments	int node_id, XE_LIGHT_TYPE& light_type
Return Type	bool
Description	Retrieves the light type Parameters: - node_id, the node id of an input node - light_type, the light type based on the XE_LIGHT_TYPE enum. Returns true if the node id was found
Notes:

Name	XE_light_set_color
Arguments	int node_id, float r, float g, float b
Return Type	bool
Description	Sets the light color Parameters: - node_id, the node's id - r, the R value of the light color (Default value is 1.0) - g, the G value of the light color (Default value is 1.0) - b, the B value of the light color (Default value is 1.0) Returns true if the node id was found
Notes:

Name	XE_light_get_color
Arguments	int node_id, float& r, float& g, float& b
Return Type	bool
Description	Retrieves the light color Parameters: - node_id, the node's id - r, the R value of the light color - g, the G value of the light color - b, the B value of the light color Returns true if the node id was found
Notes:

Name	XE_light_set_position
Arguments	int node_id, float x, float y, float z
Return Type	bool
Description	Sets the light position For Spotlights, it is being used to set the current light position in world coordinates For Directional lights, it is being used with the light target in order to generate the light's direction Parameters: - node_id, the node's id - x, the x value of the position vector in world coordinates (Default value is 0.0) - y, the y value of the position vector in world coordinates (Default value is 0.0) - z, the z value of the position vector in world coordinates (Default value is 0.0) Returns true if the node id was found
Notes:

Name	XE_light_get_position
Arguments	int node_id, float& x, float& y, float& z
Return Type	bool
Description	Retrieves the light position Parameters: - node_id, the node's id - x, the x value of the position vector in world coordinates - y, the y value of the position vector in world coordinates - z, the z value of the position vector in world coordinates Returns true if the node id was found
Notes:

Name	XE_light_set_target
Arguments	int node_id, float x, float y, float z
Return Type	bool
Description	Sets the light target point Parameters: - node_id, the node's id - x, the x value of the target vector in world coordinates (Default value is 0.0) - y, the y value of the target vector in world coordinates (Default value is 0.0) - z, the z value of the target vector in world coordinates (Default value is -1.0) Returns true if the node id was found
Notes:

Name	XE_light_get_target
Arguments	int node_id, float& x, float& y, float& z
Return Type	bool
Description	Retrieves the light target point Parameters: - node_id, the node's id - x, the x value of the target vector in world coordinates - y, the y value of the target vector in world coordinates - z, the z value of the target vector in world coordinates Returns true if the node id was found
Notes:

Name	XE_light_set_near_range
Arguments	int node_id, float near_range
Return Type	bool
Description	Sets the light near range Parameters: - node_id, the node's id - near_range, the light's near range (Default value is 10.0) Returns true if the node id was found
Notes:

Name	XE_light_get_near_range
Arguments	int node_id, float& near_range
Return Type	bool
Description	Retrieves the light near range Parameters: - node_id, the node's id - near_range, the light's near range Returns true if the node id was found
Notes:

Name	XE_light_set_far_range
Arguments	int node_id, float far_range
Return Type	bool
Description	Sets the light far range Parameters: - node_id, the node's id - far_range, the light's far range (Default value is 1000.0) Returns true if the node id was found
Notes:

Name	XE_light_get_far_range
Arguments	int node_id, float& far_range
Return Type	bool
Description	Retrieves the light far range Parameters: - node_id, the node's id - far_range, the light's far range Returns true if the node id was found
Notes:

Name	XE_light_set_shadows_status
Arguments	int node_id, bool status
Return Type	bool
Description	Sets whether this light's shadow generation is enabled/disabled Parameters: - node_id, the node's id - status, a flag indicating whether shadow maps will be generated for this light (Default value is true) Returns true if the node id was found
Notes:

Name	XE_light_get_shadows_status
Arguments	int node_id, bool& status
Return Type	bool
Description	Retrieves the current shadow generation status Parameters: - node_id, the node's id - status, a flag indicating whether shadow maps will be generated for this light Returns true if the node id was found
Notes:

Name	XE_light_set_rsm_status
Arguments	int node_id, bool status
Return Type	bool
Description	Sets whether this light will generate RSM maps. Currently, directional lights do not support RSM maps so this function has no effect on this light type. Parameters: - node_id, the node's id - status, a flag indicating whether RSM's will be generated for this light (Default value is false) Returns true if the node id was found
Notes:

Name	XE_light_get_rsm_status
Arguments	int node_id, bool& status
Return Type	bool
Description	Retrieves the current RSM status Parameters: - node_id, the node's id - status, a flag indicating whether RSM's will be generated for this light Returns true if the node id was found
Notes:

Name	XE_light_set_attenuation_status
Arguments	int node_id, bool status
Return Type	bool
Description	Sets whether light attenuation is enabled for this light For directional lights this function has no effect, since they do not get attenuated with distance. Parameters: - node_id, the node's id - status, a flag indicating whether light attenuation is enabled/disabled (Default value is true) Returns true if the node id was found
Notes:

Name	XE_light_get_attenuation_status
Arguments	int node_id, bool& status
Return Type	bool
Description	Retrieves the light attenuation status Parameters: - node_id, the node's id - status, a flag indicating whether light attenuation is enabled/disabled Returns true if the node id was found
Notes:

Name	XE_light_set_conical_status
Arguments	int node_id, bool status
Return Type	bool
Description	Spotlights radiate within a cone. This function sets whether the cone angle will be used in the lighting calculations. For directional lights this function has no effect, since they do not use a cone angle for the lighting calculations. Parameters: - node_id, the node's id - status, a flag indicating whether this spotlight will radiate within a cone (Default value is true) Returns true if the node id was found
Notes:

Name	XE_light_get_conical_status
Arguments	int node_id, bool& status
Return Type	bool
Description	Retrieves the light's conical status Parameters: - node_id, the node's id - status, a flag indicating whether this spotlight will radiate within a cone Returns true if the node id was found
Notes:

Name	XE_light_set_cone_aperture
Arguments	int node_id, float cone_aperture
Return Type	bool
Description	Sets the cone angle (in degrees) which will be used in the lighting calculations for spotlights For directional lights, this function has no effect. Parameters: - node_id, the node's id - cone_aperture, the aperture of the light's cone (Default value is 90 degrees) Returns true if the node id was found
Notes:

Name	XE_light_get_cone_aperture
Arguments	int node_id, float& cone_aperture
Return Type	bool
Description	Retrieves the cone aperture Parameters: - node_id, the node's id - cone_aperture, the aperture of the light's cone Returns true if the node id was found
Notes:

Name	XE_light_set_shadow_resolution
Arguments	int node_id, unsigned int shadow_resolution
Return Type	bool
Description	Sets the shadow map resolution (the same resolution is used for the RSM maps) Parameters: - node_id, the node's id - shadow_resolution, the resolution of the shadow map buffers (Default value is 512) Returns true if the node id was found
Notes:

Name	XE_light_get_shadow_resolution
Arguments	int node_id, unsigned int& shadow_resolution
Return Type	bool
Description	Retrieves the current shadow generation status Parameters: - node_id, the node's id - shadow_resolution, the resolution of the shadow map buffers Returns true if the node id was found
Notes:

Name	XE_light_set_soft_shadow_size
Arguments	int node_id, bool status
Return Type	bool
Description	Sets a value to mimic an area light effect for point lights Parameters: - node_id, the node's id - soft_shadow_size, the size of the soft shadow (Default value is 1.0) Returns true if the node id was found
Notes:

Name	XE_light_get_soft_shadow_size
Arguments	int node_id, bool& status
Return Type	bool
Description	Retrieves the soft shadow value Parameters: - node_id, the node's id - soft_shadow_size, the size of the soft shadow Returns true if the node id was found
Notes:

Scene Description Language Declaration

XML node name

light

Placement:

Within any node

Special notes:

Inherited attributes:

name, active

New attributes:

attribute	type	description
type	OPTION [STRING] spotlight parallel	The type of light source.
color	VEC3	The color of the light source. RGB values can be greater than 1.0.
shadows	BOOLEAN	True if the light casts shadows. True by default.
rsm	BOOLEAN	True if the spotilight generates RSM maps. False by default.
attenuation	BOOLEAN	True if the spotlight is attenuated. False by default. Attenuation is linear and the light range is set by the range attribute (equal to the far shadow map clipping distance). Enabled by default. Not supported by directional lights.
conical	BOOLEAN	True if the spotlight radiates within a cone. True by default.
far_range	FLOAT	The shadow map and attenuation (far) range. Default value is 100.0.
near_range	FLOAT	The shadow map near clipping distance. Default value is 10.0.
position	VEC3	The position of the light source, relative to the local coordinate system. This point is subject to transformations. For directional lights, it is being used with the target to generate the light's direction vector.
target	VEC3	The "look-at" point of the light source, relative to the local coordinate system. It is used for the spotlight type of sources and for the calculation of the shadow map frustum. This point is subject to transformations. For directional lights, it is being used with the position to generate the light's direction vector.
resolution	INT	The resolution of the shadow map and the RSM buffers (resolution x resolution square buffer). Default value is 512.
aperture	FLOAT	The side-to-side aperture of the light cone in degrees. used by spotlights and shadow maps. Default value is 90.0 degrees.

Events:

event name	condition
-	-

Inherited events:

New messages:

attribute	value	description
follow	STRING	Follow the named node, if the name given is valid.
shadows	BOOLEAN	Change the light's shadow status
rsm	BOOLEAN	Change the spotlight's RSM status
conical	BOOLEAN	Change the spotlight's conical status
attenuation	BOOLEAN	Change the light's attenuation status
aperture	FLOAT	Change the aperture of the camera
color	VEC3	Change the light's color
position	VEC3	Change the light's position
target	VEC3	Change the light's target
near_range	FLOAT	Change the near clipping plane distance of the camera.
far_range	FLOAT	Change the far clipping plane distance of the camera.
size	FLOAT	Change the size of the soft shadows.

Inherited messages:

Redefined messages:

Obsolete messages:

visible, hide, show

Example

<world ambient="0.3 0.3 0.3" background="0.2 0.2 0.2">
  
    <camera name="first_person" aperture="50.0"
            near="2.0" far="1000" follow="Myself" primary="true">
    </camera>
    
    <light name="point2" shadows="on" color="0.0,0.0,0.0" active="true" type="spotlight" 
           rsm="true" attenuation="on" far_range="400" near_range="10" position="120,180,0"
           target="0,0,0" resolution="1024" conical="true" cone_aperture="50" soft_shadow_size="7">
    </light>
    
    <transformation name="environment" scale="1.0,1.0,1.0" translation="0,0,-10">
        
        <object name="geom2" file="arena.obj"></object>
    
    </transformation>
 
    <user name="Myself" control="navigate" speed="2.0" turn="0.5"
          position="0,10,100" lookat="0,10,0" input="MouseKeyboard">
    </user>

    <input name="MouseKeyboard" devicename="device0">
    </input>

</world>

Last updated: 3 Jun. 2013