/*=========================================================================

  Program:   Visualization Toolkit
  Module:    $RCSfile: vtkLightKit.h,v $
  Language:  C++
  Date:      $Date: 2002/12/13 21:10:10 $
  Version:   $Revision: 1.11 $

  Copyright (c) 1993-2002 Ken Martin, Will Schroeder, Bill Lorensen 
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

     This software is distributed WITHOUT ANY WARRANTY; without even 
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
// .NAME vtkLightKit - a simple but quality lighting kit
// .SECTION Description
// vtkLightKit is designed to make general purpose lighting of vtk
// scenes simple, flexible, and attractive (or at least not horribly
// ugly without significant effort).  Use a LightKit when you want
// more control over your lighting than you can get with the default
// vtk light, which is a headlight located at the camera. (Headlights
// are very simple to use, but they don't show the shape of objects very 
// well, don't give a good sense of "up" and "down", and don't evenly
// light the object.)
//
// A LightKit consists of three lights, a key light, a fill light, and
// a headlight.  The main light is the key light.  It is usually
// positioned so that it appears like an overhead light (like the sun,
// or a ceiling light).  It is generally positioned to shine down on the
// scene from about a 45 degree angle vertically and at least a little
// offset side to side.  The key light usually at least about twice as 
// bright as the total of all other lights in the scene to provide good
// modeling of object features.
// 
// The other lights in the kit (the fill light, headlight, and a pair of
// back lights) are weaker sources that provide extra
// illumination to fill in the spots that the key light misses.  The
// fill light is usually positioned across from or opposite from the
// key light (though still on the same side of the object as the
// camera) in order to simulate diffuse reflections from other objects
// in the scene.  The headlight, always located at the position of the
// camera, reduces the contrast between areas lit by the key and fill
// light. The two back lights, one on the left of the object as seen
// from the observer and one on the right, fill on the high-contrast
// areas behind the object.  To enforce the relationship between the
// different lights, the intensity of the fill, back and headlights
// are set as a ratio to the key light brightness.  Thus, the
// brightness of all the lights in the scene can be changed by
// changing the key light intensity.
//
// All lights are directional lights (infinitely far away with no
// falloff).  Lights move with the camera.
//
// For simplicity, the position of lights in the LightKit can only be
// specified using angles: the elevation (latitude) and azimuth
// (longitude) of each light with respect to the camera, expressed in
// degrees.  (Lights always shine on the camera's lookat point.) For
// example, a light at (elevation=0, azimuth=0) is located at the
// camera (a headlight).  A light at (elevation=90, azimuth=0) is
// above the lookat point, shining down.  Negative azimuth values move
// the lights clockwise as seen above, positive values
// counter-clockwise.  So, a light at (elevation=45, azimuth=-20) is
// above and in front of the object and shining slightly from the left
// side.
//
// vtkLightKit limits the colors that can be assigned to any light to
// those of incandescent sources such as light bulbs and sunlight.  It
// defines a special color spectrum called "warmth" from which light
// colors can be chosen, where 0 is cold blue, 0.5 is neutral white,
// and 1 is deep sunset red.  Colors close to 0.5 are "cool whites" and
// "warm whites," respectively. 
//
// Since colors far from white on the warmth scale appear less bright,
// key-to-fill and key-to-headlight ratios are skewed by 
// key, fill, and headlight colors.  If the flag MaintainLuminance
// is set, vtkLightKit will attempt to compensate for these perceptual
// differences by increasing the brightness of more saturated colors.
//
// A LightKit is not explicitly part of the vtk pipeline.  Rather, it
// is a composite object that controls the behavior of lights using a
// unified user interface.  Every time a parameter of vtkLightKit is
// adjusted, the properties of its lights are modified.
//
// .SECTION Credits
// vtkLightKit was originally written and contributed to vtk by
// Michael Halle (mhalle@bwh.harvard.edu) at the Surgical Planning
// Lab, Brigham and Women's Hospital.

#ifndef __vtkLightKit_h
#define __vtkLightKit_h

#include "vtkObject.h"
class vtkLight;
class vtkPiecewiseFunction;
class vtkRenderer;

class VTK_RENDERING_EXPORT vtkLightKit : public vtkObject
{
public:
  static vtkLightKit *New();
  vtkTypeRevisionMacro(vtkLightKit, vtkObject);
  void PrintSelf(ostream& os, vtkIndent indent);

  // Description:
  // Set/Get the intensity of the key light.  The key light is the
  // brightest light in the scene.  The intensities of the other two
  // lights are ratios of the key light's intensity.  
  vtkSetMacro(KeyLightIntensity, float);  
  vtkGetMacro(KeyLightIntensity, float);

  // Description: 
  // Set/Get the key-to-fill ratio.  This ratio controls
  // how bright the fill light is compared to the key light: larger
  // values correspond to a dimmer fill light.  The purpose of the
  // fill light is to light parts of the object not lit by the key
  // light, while still maintaining constrast.  This type of lighting
  // may correspond to indirect illumination from the key light, bounced
  // off a wall, floor, or other object.  The fill light should never
  // be brighter than the key light:  a good range for the key-to-fill
  // ratio is between 2 and 10.
  vtkSetClampMacro(KeyToFillRatio, float, 0.5, VTK_FLOAT_MAX);
  vtkGetMacro(KeyToFillRatio, float);

  // Description: 
  // Set/Get the key-to-headlight ratio.  Similar to the key-to-fill
  // ratio, this ratio controls how bright the headlight light is
  // compared to the key light: larger values correspond to a dimmer
  // headlight light.  The headlight is special kind of fill light,
  // lighting only the parts of the object that the camera can see.
  // As such, a headlight tends to reduce the contrast of a scene.  It
  // can be used to fill in "shadows" of the object missed by the key
  // and fill lights.  The headlight should always be significantly
  // dimmer than the key light:  ratios of 2 to 15 are typical.
  vtkSetClampMacro(KeyToHeadRatio, float, 0.5, VTK_FLOAT_MAX);
  vtkGetMacro(KeyToHeadRatio, float);

  // Description: 
  // Set/Get the key-to-back light ratio.  This ratio controls
  // how bright the back lights are compared to the key light: larger
  // values correspond to dimmer back lights.  The back lights fill
  // in the remaining high-contrast regions behind the object.
  // Values between 2 and 10 are good.
  vtkSetClampMacro(KeyToBackRatio, float, 0.5, VTK_FLOAT_MAX);
  vtkGetMacro(KeyToBackRatio, float);

  // Description: 
  // Set the warmth of each the lights.  Warmth is a parameter that
  // varies from 0 to 1, where 0 is "cold" (looks icy or lit by a very
  // blue sky), 1 is "warm" (the red of a very red sunset, or the
  // embers of a campfire), and 0.5 is a neutral white.  The warmth
  // scale is non-linear. Warmth values close to 0.5 are subtly
  // "warmer" or "cooler," much like a warmer tungsten incandescent
  // bulb, a cooler halogen, or daylight (cooler still).  Moving
  // further away from 0.5, colors become more quickly varying towards
  // blues and reds.  With regards to aesthetics, extremes of warmth
  // should be used sparingly.
  vtkSetMacro(KeyLightWarmth, float);
  vtkGetMacro(KeyLightWarmth, float);

  vtkSetMacro(FillLightWarmth, float);
  vtkGetMacro(FillLightWarmth, float);

  vtkSetMacro(HeadlightWarmth, float);
  vtkGetMacro(HeadlightWarmth, float);

  vtkSetMacro(BackLightWarmth, float);
  vtkGetMacro(BackLightWarmth, float);

  // Description:
  // Returns the floating-point RGB values of each of the light's color.
  vtkGetVectorMacro(KeyLightColor,  float, 3);
  vtkGetVectorMacro(FillLightColor, float, 3);
  vtkGetVectorMacro(HeadlightColor, float, 3);
  vtkGetVectorMacro(BackLightColor, float, 3);

  // Description:
  // If MaintainLuminance is set, the LightKit will attempt to maintain
  // the apparent intensity of lights based on their perceptual brightnesses.
  // By default, MaintainLuminance is off.
  vtkBooleanMacro(MaintainLuminance, int);
  vtkGetMacro(MaintainLuminance, int);
  vtkSetMacro(MaintainLuminance, int);

  // Description: 
  // Get/Set the position of the key, fill, and back lights
  // using angular methods.  Elevation corresponds to latitude,
  // azimuth to longitude.  It is recommended that the key light
  // always be on the viewer's side of the object and above the
  // object, while the fill light generally lights the part of the object
  // not lit by the fill light.  The headlight, which is always located
  // at the viewer, can then be used to reduce the contrast in the image.
  // There are a pair of back lights.  They are located at the same
  // elevation and at opposing azimuths (ie, one to the left, and one to
  // the right).  They are generally set at the equator (elevation = 0),
  // and at approximately 120 degrees (lighting from each side and behind).
  void SetKeyLightAngle(float elevation, float azimuth);
  void SetKeyLightAngle(float angle[2]) { 
    this->SetKeyLightAngle(angle[0], angle[1]); };

  void SetKeyLightElevation(float x) {
    this->SetKeyLightAngle(x, this->KeyLightAngle[1]); };

  void SetKeyLightAzimuth(float x) {
    this->SetKeyLightAngle(this->KeyLightAngle[0], x); };

  vtkGetVectorMacro(KeyLightAngle, float, 2);
  float GetKeyLightElevation() {
    float ang[2]; this->GetKeyLightAngle(ang); return ang[0]; };

  float GetKeyLightAzimuth() {
    float ang[2]; this->GetKeyLightAngle(ang); return ang[1]; };

  void SetFillLightAngle(float elevation, float azimuth);
  void SetFillLightAngle(float angle[2]) { 
    this->SetFillLightAngle(angle[0], angle[1]); };

  void SetFillLightElevation(float x) {
    this->SetFillLightAngle(x, this->FillLightAngle[1]); };

  void SetFillLightAzimuth(float x) {
    this->SetFillLightAngle(this->FillLightAngle[0], x); };

  vtkGetVectorMacro(FillLightAngle, float, 2);
  float GetFillLightElevation() {
    float ang[2]; this->GetFillLightAngle(ang); return ang[0]; };

  float GetFillLightAzimuth() {
    float ang[2]; this->GetFillLightAngle(ang); return ang[1]; };

  void SetBackLightAngle(float elevation, float azimuth);
  void SetBackLightAngle(float angle[2]) { 
    this->SetBackLightAngle(angle[0], angle[1]); };

  void SetBackLightElevation(float x) {
    this->SetBackLightAngle(x, this->BackLightAngle[1]); };

  void SetBackLightAzimuth(float x) {
    this->SetBackLightAngle(this->BackLightAngle[0], x); };

  vtkGetVectorMacro(BackLightAngle, float, 2);
  float GetBackLightElevation() {
    float ang[2]; this->GetBackLightAngle(ang); return ang[0]; };

  float GetBackLightAzimuth() {
    float ang[2]; this->GetBackLightAngle(ang); return ang[1]; };

  // Description:
  // Add lights to, or remove lights from, a renderer.  
  // Lights may be added to more than one renderer, if desired.
  void AddLightsToRenderer(vtkRenderer *renderer);
  void RemoveLightsFromRenderer(vtkRenderer *renderer);

  void DeepCopy(vtkLightKit *kit);

  void Modified();
  void Update();

protected:
  vtkLightKit();
  ~vtkLightKit();

  void WarmthToRGBI(float w, float rgb[3], float& i);
  void WarmthToRGB(float w, float rgb[3]);
  void InitializeWarmthFunctions();
  float WarmthToIntensity(float w);


  float KeyLightIntensity;
  float KeyToFillRatio;
  float KeyToHeadRatio;
  float KeyToBackRatio;
  
  vtkLight *KeyLight;
  float KeyLightWarmth;
  float KeyLightAngle[2];
  float KeyLightColor[3];

  vtkLight *FillLight;
  float FillLightWarmth;
  float FillLightAngle[2];
  float FillLightColor[3];

  float BackLightWarmth;
  float BackLightColor[3];

  vtkLight *BackLight0;
  vtkLight *BackLight1;

  float BackLightAngle[2];

  vtkLight *Headlight;
  float HeadlightWarmth;
  float HeadlightColor[3];

  int MaintainLuminance;

  vtkPiecewiseFunction *WarmthFunction[4]; // r, g, b, perceptual length
private:
  vtkLightKit(const vtkLightKit&);  // Not implemented.
  void operator=(const vtkLightKit&);  // Not implemented.
};

#endif
