Change default for vtkExternalLight

It adjusts light with OpenGL identifier GL_LIGHT0.
Some documentation changes.

Rendering/External/vtkExternalLight.cxx

@@ -15,14 +15,15 @@
 #include "vtkExternalLight.h"
 
 #include "vtkObjectFactory.h"
+#include "vtkOpenGL.h"
 
 //-----------------------------------------------------------------------------
 vtkStandardNewMacro(vtkExternalLight);
 
 //-----------------------------------------------------------------------------
 vtkExternalLight::vtkExternalLight()
 {
-  this->LightIndex = -1;
+  this->LightIndex = GL_LIGHT0;
   this->ReplaceMode = INDIVIDUAL_PARAMS;
 
   // By default, nothing is set by user

Rendering/External/vtkExternalLight.h

@@ -27,15 +27,16 @@
 // if the light is a positional light.
 //
 // By default, vtkExternalLight overrides specific light parameters as set by
-// the user. Setting the \em ReplaceMode to ALL_PARAMS, will set all
+// the user. Setting the #ReplaceMode to ALL_PARAMS, will set all
 // the light parameter values to the ones set in vtkExternalLight.
 //
 // .SECTION Caveats
 // Use the vtkExternalLight object to tweak parameters of lights created in the
-// external context. This class does not create new lights in the scene.
-// One must explicitly set the \em LightIndex to control the light of choice.
+// external context. This class does NOT create new lights in the scene.
 //
 // .SECTION Example
+// Usage example for vtkExternalLight in conjunction with
+// vtkExternalOpenGLRenderer and \ref ExternalVTKWidget
 // \code{.cpp}
 //    vtkNew<vtkExternalLight> exLight;
 //    exLight->SetLightIndex(GL_LIGHT0); // GL_LIGHT0 identifies the external light
@@ -46,7 +47,7 @@
 // \endcode
 //
 // .SECTION see also
-// vtkExternalOpenGLRenderer ExternalVTKWidget
+// vtkExternalOpenGLRenderer \ref ExternalVTKWidget
 
 #ifndef vtkExternalLight_h
 #define vtkExternalLight_h
@@ -61,7 +62,13 @@ class VTKRENDERINGEXTERNAL_EXPORT vtkExternalLight : public vtkLight
   void PrintSelf(ostream& os, vtkIndent indent);
 
   // Description:
-  // Create an external light object
+  // Create an external light object with the focal point at the origin and its
+  // position set to (0,0,1). The light is a Headlight, its color is white
+  // (black ambient, white diffuse, white specular),
+  // intensity=1, the light is turned on, positional lighting is off,
+  // ConeAngle=30, AttenuationValues=(1,0,0), Exponent=1 and the
+  // TransformMatrix is NULL. The light index is GL_LIGHT0, which means the
+  // existing light with index GL_LIGHT0 will be affected by this light.
   static vtkExternalLight *New();
 
   enum ReplaceModes
@@ -70,72 +77,105 @@ class VTKRENDERINGEXTERNAL_EXPORT vtkExternalLight : public vtkLight
     ALL_PARAMS          = 1
     };
 
-  // Set/Get OpenGL light index
+  // Description:
+  // Set/Get light index
   // This should be the OpenGL light identifier. (e.g.: GL_LIGHT0)
+  // (Default: GL_LIGHT0)
   vtkSetMacro(LightIndex, int);
   vtkGetMacro(LightIndex, int);
 
+  // Description:
   // Set/Get replace mode
+  // This determines how this ExternalLight will be used to tweak parameters on
+  // an existing light in the rendering context.
+  // (Default: INDIVIDUAL_PARAMS)
+  //
+  // \li \c vtkExternalLight::INDIVIDUAL_PARAMS : Replace parameters
+  // specifically set by the user by calling the parameter
+  // Set method. (e.g. SetDiffuseColor())
+  //
+  // \li \c vtkExternalLight::ALL_PARAMS : Replace all
+  // parameters of the light with the parameters in vtkExternalLight object.
   vtkSetMacro(ReplaceMode, int);
   vtkGetMacro(ReplaceMode, int);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetPosition(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetFocalPoint(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetAmbientColor(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetDiffuseColor(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetSpecularColor(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetIntensity(double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetConeAngle(double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetAttenuationValues(double, double, double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetExponent(double);
 
+  // Description:
   // Override Set method to keep a record of changed value
   void SetPositional(int);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(PositionSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(FocalPointSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(AmbientColorSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(DiffuseColorSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(SpecularColorSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(IntensitySet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(ConeAngleSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(AttenuationValuesSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(ExponentSet, bool);
 
+  // Description:
   // Check whether value set by user
   vtkGetMacro(PositionalSet, bool);