Improve parameters and documentation of Light

[libs/gl.git] / source / light.h

diff --git a/source/light.h b/source/light.h
index ee62ce35634213f2e6af365f5169e2d2cf0e59c7..b775a71188c690ce17d9c78aac0d9d6ac7dce933 100644 (file)
--- a/source/light.h
+++ b/source/light.h
@@ -12,7 +12,15 @@ class Matrix;
 class ProgramData;
 
 /**
-Stores properties of a single light source.
+Stores properties of a single light source.  Lights can be directional, point
+lights or spotlights.  No explicit type parameter is provided; rather the
+other parameters determine what kind of light it is.  If the fourth component
+of position is zero, it's a directional light.  Otherwise, if the spot cutoff
+is not 180 degrees, it's a spotlight.  Otherwise it's an omnidirectional point
+light.
+
+Lights are usually grouped with a Lighting object, which can be used in a
+Pipeline::Pass.
 
 Lights do not cast shadows by themselves.  See ShadowMap for that.
 */
@@ -35,7 +43,7 @@ private:
        Vector4 position;
        Vector3 spot_dir;
        float spot_exp;
-       float spot_cutoff;
+       Geometry::Angle<float> spot_cutoff;
        float attenuation[3];
 
 public:
@@ -51,7 +59,7 @@ public:
        void set_diffuse(const Color &c);
 
        /** Sets the specular (direction-dependent) color of the Light.  Provided to
-       shaders with the name light_sources[i].diffuse. */
+       shaders with the name light_sources[i].specular. */
        void set_specular(const Color &c);
 
        const Color &get_diffuse() const { return diffuse; }
@@ -63,12 +71,28 @@ public:
 
        const Vector4 &get_position() const { return position; }
 
+       /** Sets the direction of a spotlight.  Has no effect if spotlight cutoff is
+       not set. */
        void set_spot_direction(const Vector3 &);
+
+       /** Sets the angular falloff exponent of the spotlight.  Must be >= 0. */
        void set_spot_exponent(float);
+
+       /// Deprecated.
        void set_spot_cutoff(float);
+
+       /** Sets the cutoff angle of a spotlight.  Beyond this angle from its axis
+       the spotlight provides no illumination.  Must be between 0 and 90 degrees,
+       or exactly 180 degrees to indicate a non-spotlight. */
+       void set_spot_cutoff(const Geometry::Angle<float> &);
+
+       /** Disables spotlight, reverting to an omnidirectional point light.
+       Equivalent to setting the spot cutoff to 180 degrees. */
+       void disable_spot_cutoff();
+
        const Vector3 &get_spot_direction() const { return spot_dir; }
        float get_spot_exponent() const { return spot_exp; }
-       float get_spot_cutoff() const { return spot_cutoff; }
+       const Geometry::Angle<float> &get_spot_cutoff() const { return spot_cutoff; }
        void set_attenuation(float, float, float);
        const float *get_attenuation() const { return attenuation; }