Update and improve documentation

[libs/gl.git] / source / effects / shadowmap.h

diff --git a/source/effects/shadowmap.h b/source/effects/shadowmap.h
index 502480122fc68354e45c85adec5b8a3d22c328de..da76062833c745a487549df4a2a88e265f70cf2c 100644 (file)
--- a/source/effects/shadowmap.h
+++ b/source/effects/shadowmap.h
@@ -17,10 +17,17 @@ class Light;
 class PointLight;
 
 /**
-Creates shadows on a renderable through a shadow map texture.  In the setup
-phase, the scene is rendered to a depth texture from the point of view of the
-lightsource.  This texture is then used in the rendering phase together with
-texture coordinate generation to determine whether each fragment is lit.
+Creates a depth texture which can be used to add shadows to a renderable.
+
+In the setup phase, the scene is rendered from the point of view of the light
+source and the depth values are recorded.  This texture can be used by shaders
+to determine if the light can reach a particular position.
+
+A shadow map can be created as an atlas, containing multiple lights in the same
+depth texture.  Each light is automatically allocated a region of the texture
+and region information is added to the uniform values.
+
+The shader fragment shadow.glsl provides interfaces to access the shadow map.
 */
 class ShadowMap: public Effect
 {
@@ -115,30 +122,40 @@ private:
        std::string debug_name;
 
        ShadowMap(unsigned, unsigned, Renderable &, const Lighting *);
+
 public:
-       ShadowMap(unsigned, Renderable &, const DirectionalLight &, Renderable &);
-       ShadowMap(unsigned, unsigned, Renderable &, const Lighting &);
+       /** Creates a shadow map for a single light. */
+       ShadowMap(unsigned size, Renderable &content, const DirectionalLight &, Renderable &caster);
+
+       /** Creates a shadow map atlas, to which multiple lights can be added. */
+       ShadowMap(unsigned width, unsigned height, Renderable &, const Lighting &);
+
+       /** Adds a directional light.  The shadow map is rendered using an
+       orthogonal projection. */
+       void add_light(const DirectionalLight &, unsigned size, Renderable &caster);
 
-       void add_light(const DirectionalLight &, unsigned, Renderable &);
-       void add_light(const PointLight &, unsigned, Renderable &);
+       /** Adds a point light.  The shadow map is rendered using a perspective
+       projection, with four views in a tetrahedral arrangement.  The shader must
+       clip vertices appropriately.  Occluder_thsm.glsl can be used for this. */
+       void add_light(const PointLight &, unsigned size, Renderable &caster);
 private:
        void add_light(const Light &, unsigned, ShadowType, Renderable &);
 
 public:
-       /** Sets the ShadowMap target point and radius.  The transformation matrix is
-       computed so that a sphere with the specified parameters will be completely
-       covered by the ShadowMap. */
+       /** Sets the shadow volume parameters.  For directional lights the shadow
+       camera will be positioned so that the spherical shadow volume fits entirely
+       in the view volume.  For point lights the shadow volume's radius will be
+       used as the view distance. */
        void set_target(const Vector3 &, float);
 
        /** Sets the darkness of shadows.  Must be in the range between 0.0 and 1.0,
-       inclusive.  Only usable with shaders, and provided through the
-       shadow_darkness uniform. */
+       inclusive.  Values other than 1.0 are not physically correct. */
        void set_darkness(float);
 
-       /** Sets a distance beyond objects from which the shadow starts.  Expressed
-       in pixel-sized units.  Must be positive; values less than 1.0 are not
-       recommended.  Larger values produce less depth artifacts, but may prevent
-       thin objects from casting shadows on nearby sufraces. */
+       /** Sets an offset for depth values to avoid surfaces incorrectly shadowing
+       themselves.  Must be positive; values less than 1.0 are not recommended.
+       Larger values produce less artifacts, but may cause shadows to become
+       disconnected from the objects casting them. */
        void set_depth_bias(float);
 
        const Texture2D &get_depth_texture() const { return depth_buf; }