SceneGraph

Home About XEngine Engine API SceneGraph Changelog Programming Guide

Index

| Scene Description Language | camera | directory | eventmessage | geometry | group | input | light | node | primitives | root | spinner | transformation | user |

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