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

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

The :js:meth:`~wv.View.addLight` function accepts a :js:class:`~wv.Light` object and adds a light to the scene.

The :js:meth:`~wv.View.removeLight` function accepts a :js:data:`~wv.LightKey` object and removes the associated light from the scene.

The :js:meth:`~wv.View.updateLight` function accepts a :js:data:`~wv.LightKey` and a :js:class:`~wv.Light` and updates the light associated with the key to have the properties of the light object that was passed.

The :js:meth:`~wv.View.clearLights` removes all lights from the scene. When there are no lights, material colors are drawn at full intensity.

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


**LightType**

All lights in HOOPS Visualize Web 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
