######
Lights
######

Introduction
============

The :ref:`addlight() <api_ref/viewing/classes/Communicator.View:addlight>` function accepts a :doc:`Light </api_ref/viewing/classes/Communicator.Light>` object and adds a light to the scene.

The :ref:`removeLight() <api_ref/viewing/classes/Communicator.View:removelight>` function accepts a :ref:`LightKey <api_ref/viewing/modules/Communicator:lightkey>` object removes the associated light from the scene.

The :ref:`updateLight() <api_ref/viewing/classes/Communicator.View:updatelight>` function accepts a ``LightKey`` and a ``Light`` and updates the light associated with the key to have the properties of the light object that was passed.

The :ref:`clearLights() <api_ref/viewing/classes/Communicator.View:clearlights>` removes all lights from the scene. When there are no lights, material colors are drawn at full intensity.

The ``Light`` object is used to define the properties of the light: type, space, position, and color.


**LightType**

All lights in |HCNOW| currently have a directional light type. Directional lights approximate a distant light source like the sun. The light's position is interpreted as a vector pointing toward the light rather than a point inside the scene. Light will hit every point in the scene from that direction.


**LightSpace**

Lights can either be placed in world space or camera space. Specifying a light position in camera space will cause it to follow the camera.


**Position**

The position of the light in the scene. Note: for directional lights, the position defines the light direction and is not interpreted as a point in the scene.


**Color**

The light's color.


Lighting examples
=================

.. image:: images/lights_no_color.png

The following code adds a red world space light to the scene:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_lights.ts
   :start-after: //! [add_light_world_space]
   :end-before: //! [add_light_world_space]
   
.. image:: images/lights_red_color.png

The following code adds a green camera space light to the scene:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_lights.ts
   :start-after: //! [add_light_camera_space]
   :end-before: //! [add_light_camera_space]

.. image:: images/lights_green_color.png

The following code adds a red and green camera space light to the scene. Then removes the red light:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_lights.ts
   :start-after: //! [remove_light]
   :end-before: //! [remove_light]
   
.. image:: images/lights_remove.png

The following code adds a red and green camera space light to the scene. Then changes the red light to be yellow:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_lights.ts
   :start-after: //! [update_light]
   :end-before: //! [update_light]

.. image:: images/lights_update_color.png
