Documentation|SurfaceDecoration: Improved apidoc for SurfaceDecorator…

…; minor cleanup
skyjake · Sep 13, 2013 · fee3c08 · fee3c08
1 parent cfb14fa
commit fee3c08
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 13 deletions.
diff --git a/doomsday/client/include/render/decoration.h b/doomsday/client/include/render/decoration.h
@@ -33,6 +33,7 @@ class Surface;
 #define MAX_DECOR_DISTANCE      (2048)
 
 /**
+ * World surface decoration.
  * @ingroup render
  */
 class Decoration : public de::MapObject

diff --git a/doomsday/client/include/render/lightdecoration.h b/doomsday/client/include/render/lightdecoration.h
@@ -24,6 +24,10 @@
 #include "Decoration"
 #include "render/lumobj.h"
 
+/**
+ * World surface light decoration.
+ * @ingroup render
+ */
 class LightDecoration : public Decoration, public Lumobj::Source
 {
 public:

diff --git a/doomsday/client/include/render/lumobj.h b/doomsday/client/include/render/lumobj.h
@@ -55,7 +55,7 @@ class Lumobj : public de::MapObject
          * return a value in the range [0..1], where @c 0 is fully occluded and
          * @c 1 is fully visible.
          *
-         * In the default implementation assumes the source is always visible.
+         * The default implementation assumes the source is always visible.
          *
          * @param eye  Position of the eye in map space.
          */

diff --git a/doomsday/client/include/render/surfacedecorator.h b/doomsday/client/include/render/surfacedecorator.h
@@ -47,19 +47,43 @@ class SurfaceDecorator
     SurfaceDecorator();
 
     /**
-     * Decorate @a surface.
+     * Perform one time decoration of a single @a surface. The surface will not
+     * be remembered and any resulting decorations will not be updated later.
      */
     void decorate(Surface &surface);
 
-    /// Note that existing decorations are retained.
+    /**
+     * Perform scheduled (re)decoration work.
+     */
+    void redecorate();
+
+    /**
+     * Forget all known surfaces and previous decorations.
+     */
+    void reset();
+
+    /**
+     * Add the specified @a surface to the decorator's job list. If the surface
+     * is already on this list then nothing will happen. If the surface lacks a
+     * material or no decorations are defined for this material, then nothing
+     * will happen.
+     *
+     * Any existing decorations are retained until the material next changes.
+     *
+     * @param surface  Surface to add to the job list.
+     */
     void add(Surface *surface);
 
-    /// Note that existing decorations are retained.
+    /**
+     * Remove the specified @a surface from the decorator's job list. If the
+     * surface is not on this list then nothing will happen.
+     *
+     * Any existing decorations are retained and will no longer be updated.
+     *
+     * @param surface  Surface to add to the job list.
+     */
     void remove(Surface *surface);
 
-    void reset();
-    void redecorate();
-
 private:
     DENG2_PRIVATE(d)
 };

diff --git a/doomsday/client/src/render/surfacedecorator.cpp b/doomsday/client/src/render/surfacedecorator.cpp
@@ -326,14 +326,21 @@ void SurfaceDecorator::redecorate()
     MaterialSurfaceMap::iterator i = d->decorated.begin();
     while(i != d->decorated.end())
     {
-        Material &material     = *i.key();
-        SurfaceSet &surfaceSet = i.value();
-
-        MaterialSnapshot const &materialSnapshot =
-            material.prepare(Rend_MapSurfaceMaterialSpec());
+        MaterialSnapshot const *materialSnapshot = 0;
 
+        SurfaceSet &surfaceSet = i.value();
         foreach(Surface *surface, surfaceSet)
         {
+            if(!surface->_needDecorationUpdate)
+                continue;
+
+            // Time to prepare the material?
+            if(!materialSnapshot)
+            {
+                Material &material = *i.key();
+                materialSnapshot = &material.prepare(Rend_MapSurfaceMaterialSpec());
+            }
+
             surface->_needDecorationUpdate = false;
             surface->clearDecorations();
 
@@ -342,7 +349,7 @@ void SurfaceDecorator::redecorate()
 
             if(prepareGeometry(*surface, topLeft, bottomRight, materialOrigin))
             {
-                d->updateDecorations(*surface, materialSnapshot, materialOrigin,
+                d->updateDecorations(*surface, *materialSnapshot, materialOrigin,
                                      topLeft, bottomRight, containingSector(*surface));
             }
         }