Documentation|MaterialVariant: Improved apidoc for MaterialVariant

Plus further minor cleanup refactorings.

doomsday/engine/include/de_resource.h

@@ -29,7 +29,6 @@
 #include "resource/fonts.h"
 #include "resource/r_data.h"
 #include "resource/materials.h"
-#include "resource/materialvariant.h"
 #include "resource/models.h"
 #include "resource/compositetexture.h"
 #include "resource/rawtexture.h"
@@ -40,6 +39,7 @@
 #endif
 
 #ifdef __cplusplus
+#  include "resource/materialvariant.h"
 #  include "resource/materialsnapshot.h"
 #  include "resource/patch.h"
 #  include "resource/texturemanifest.h"

doomsday/engine/include/render/rend_main.h

@@ -35,8 +35,6 @@
 #endif
 #include "r_things.h"
 
-struct materialvariantspec_s;
-
 #define GLOW_HEIGHT_MAX                     (1024.f) /// Absolute maximum
 
 #define OMNILIGHT_SURFACE_LUMINOSITY_ATTRIBUTION_MIN (.05f)

doomsday/engine/include/render/sprite.h

@@ -22,7 +22,7 @@
 #ifndef LIBDENG_RENDER_SPRITE_H
 #define LIBDENG_RENDER_SPRITE_H
 
-#include "resource/materialvariant.h"
+#include "dd_types.h"
 
 /// @addtogroup render
 ///@{
@@ -32,7 +32,7 @@ typedef struct rendpspriteparams_s
     float pos[2]; // {X, Y} Screen-space position.
     float width, height;
 
-    struct material_s* mat;
+    struct material_s *mat;
     float texOffset[2];
     boolean texFlip[2]; // {X, Y} Flip along the specified axis.
 
@@ -49,6 +49,8 @@ DENG_EXTERN_C void Rend_SpriteRegister(void);
 #ifdef __CLIENT__
 #ifdef __cplusplus
 
+#include "resource/materialvariant.h"
+
 de::MaterialVariantSpec const &Rend_SpriteMaterialSpec(int tclass = 0, int tmap = 0);
 
 extern "C" {

doomsday/engine/include/resource/material.h

@@ -318,11 +318,6 @@ int Material_SetProperty(material_t *material, setargs_t const *args);
 de::MaterialAnim &Material_AnimGroup(material_t *mat);
 #endif
 
-/**
- * Provides access to the list of variant instances for efficient traversal.
- */
-de::Material::Variants const &Material_Variants(material_t const *mat);
-
 /**
  * Choose/create a variant of the material which fulfills @a spec.
  *
@@ -336,6 +331,11 @@ de::Material::Variants const &Material_Variants(material_t const *mat);
 de::MaterialVariant *Material_ChooseVariant(material_t *mat,
     de::MaterialVariantSpec const &spec, bool smoothed = true, bool canCreate = false);
 
+/**
+ * Provides access to the list of variant instances for efficient traversal.
+ */
+de::Material::Variants const &Material_Variants(material_t const *mat);
+
 #endif
 
 #ifdef __cplusplus

doomsday/engine/include/resource/materialvariant.h

@@ -20,7 +20,14 @@
 #ifndef LIBDENG_RESOURCE_MATERIALVARIANT_H
 #define LIBDENG_RESOURCE_MATERIALVARIANT_H
 
-/// Material (Usage) Context identifiers.
+#include "def_data.h"
+#include "resource/materialsnapshot.h"
+#include "resource/material.h"
+#include "resource/texture.h"
+
+struct texturevariantspecification_s;
+
+/// Identifiers for material usage contexts.
 typedef enum {
     MC_UNKNOWN = -1,
     MATERIALCONTEXT_FIRST = 0,
@@ -38,30 +45,27 @@ typedef enum {
 /// @c true= val can be interpreted as a valid material context identifier.
 #define VALID_MATERIALCONTEXT(val) ((val) >= MATERIALCONTEXT_FIRST && (val) <= MATERIALCONTEXT_LAST)
 
-#ifdef __cplusplus
-
-#include "def_data.h"
-#include "resource/materialsnapshot.h"
-#include "resource/material.h"
-#include "resource/texture.h"
-
-struct texturevariantspecification_s;
-
 namespace de {
 
 /**
+ * Specialization specification for a variant material. Property values are
+ * public for user convenience.
+ *
+ * @see MaterialVariant, material_t
  * @ingroup resource
  */
 struct MaterialVariantSpec
 {
+public:
     /// Usage context identifier.
     materialcontext_t context;
 
     /// Specification for the primary texture.
     struct texturevariantspecification_s *primarySpec;
 
+public:
     /**
-     * Construct a default MaterialVariantSpec instance.
+     * Construct a zeroed MaterialVariantSpec instance.
      */
     MaterialVariantSpec() : context(MC_UNKNOWN), primarySpec(0)
     {}
@@ -101,6 +105,14 @@ struct MaterialVariantSpec
 };
 
 /**
+ * Context-specialized material variant. Encapsulates all context variant values
+ * and logics pertaining to a specialized version of a @em superior material.
+ *
+ * MaterialVariant instances are usually only created by the superior material
+ * when asked to prepare for render (@ref Material_ChooseVariant()) using a context
+ * specialization specification which it cannot fulfill/match.
+ *
+ * @see material_t, MaterialVariantSpec
  * @ingroup resource
  */
 class MaterialVariant
@@ -134,6 +146,9 @@ class MaterialVariant
     /// The requested layer does not exist. @ingroup errors
     DENG2_ERROR(InvalidLayerError);
 
+    /// Required snapshot data is missing. @ingroup errors
+    DENG2_ERROR(MissingSnapshotError);
+
 public:
     MaterialVariant(material_t &generalCase, MaterialVariantSpec const &spec);
     ~MaterialVariant();
@@ -151,7 +166,7 @@ class MaterialVariant
     /// @return  Superior material from which the variant was derived.
     material_t &generalCase() const;
 
-    /// @return  MaterialVariantSpec which the variant was specialised using.
+    /// @return  Material variant specification for the variant.
     MaterialVariantSpec const &spec() const;
 
     /**
@@ -162,43 +177,64 @@ class MaterialVariant
     bool isPaused() const;
 
     /**
-     * Process a system tick event.
-     * @param time  Length of the tick in seconds.
+     * Process a system tick event. If not currently paused and the material is
+     * valid; layer stages are animated and state property values are updated
+     * accordingly.
+     *
+     * @param ticLength  Length of the tick in seconds.
+     *
+     * @see isPaused()
      */
-    void ticker(timespan_t time);
+    void ticker(timespan_t ticLength);
 
     /**
      * Reset the staged animation point for this Material.
      */
     void resetAnim();
 
     /**
-     * Return the current state of @a layerNum for the variant.
+     * Returns the current state of @a layerNum for the variant.
      */
     LayerState const &layer(int layerNum);
 
     /**
-     * Attach MaterialSnapshot data. MaterialVariant is given ownership of @a materialSnapshot.
+     * Attach new MaterialSnapshot data to the variant. If an existing snapshot
+     * is already present it will be replaced. Ownership of @a materialSnapshot
+     * is given to the variant.
+     *
      * @return  Same as @a materialSnapshot for caller convenience.
+     *
+     * @see detachSnapshot(), snapshot()
      */
     MaterialSnapshot &attachSnapshot(MaterialSnapshot &snapshot);
 
     /**
-     * Detach MaterialSnapshot data. Ownership is relinquished to the caller.
+     * Detach the MaterialSnapshot data from the variant, relinquishing ownership
+     * to the caller.
+     *
+     * @see attachSnapshot(), detachSnapshot()
      */
     MaterialSnapshot *detachSnapshot();
 
-    /// @return  MaterialSnapshot data associated with the variant; otherwise @c 0.
+    /**
+     * Returns the MaterialSnapshot data from the variant or otherwise @c 0.
+     * Ownership is unaffected.
+     *
+     * @see attachSnapshot(), detachSnapshot()
+     */
     MaterialSnapshot *snapshot() const;
 
-    /// @return  Frame count when the snapshot was last prepared/updated.
+    /**
+     * Returns the frame number when the variant's associated snapshot was last
+     * prepared/updated.
+     */
     int snapshotPrepareFrame() const;
 
     /**
-     * Change the frame when the snapshot was last prepared/updated.
-     * @param frame  Frame to mark the snapshot with.
+     * Change the frame number when the variant's snapshot was last prepared/updated.
+     * @param frameNum  Frame number to mark the snapshot with.
      */
-    void setSnapshotPrepareFrame(int frame);
+    void setSnapshotPrepareFrame(int frameNum);
 
 #ifdef LIBDENG_OLD_MATERIAL_ANIM_METHOD
     /// @return  Translated 'next' (or target) MaterialVariant if set, else this.
@@ -232,8 +268,6 @@ class MaterialVariant
 
 } // namespace de
 
-#endif // __cplusplus
-
 struct materialvariant_s; // The materialvariant instance (opaque).
 
 #endif /* LIBDENG_RESOURCE_MATERIALVARIANT_H */

doomsday/engine/src/map/linedef.c

@@ -26,7 +26,6 @@
 #include "de_render.h"
 
 #include "m_misc.h"
-#include "resource/materialvariant.h"
 #include "resource/materials.h"
 #include "map/linedef.h"
 

doomsday/engine/src/resource/materialvariant.cpp

@@ -24,12 +24,12 @@
 
 #include "de_base.h"
 #ifdef __CLIENT__
-#  include "de_network.h" // playback /clientPaused
+#  include "de_network.h" // playback / clientPaused
 #endif
 
-#include "map/r_world.h"
-#include "gl/gl_texmanager.h"
-#include "render/r_main.h"
+#include "map/r_world.h" // R_UpdateMapSurfacesOnMaterialChange
+#include "gl/gl_texmanager.h" // GL_CompareTextureVariantSpecifications
+#include "render/r_main.h" // frameTimePos
 
 #include "resource/materialvariant.h"
 
@@ -44,7 +44,7 @@ bool MaterialVariantSpec::compare(MaterialVariantSpec const &other) const
 
 struct MaterialVariant::Instance
 {
-    /// Superior Material of which this is a derivative.
+    /// Superior material of which this is a derivative.
     material_t *material;
 
     /// Specification used to derive this variant.
@@ -118,7 +118,7 @@ bool MaterialVariant::isPaused() const
 #endif
 }
 
-void MaterialVariant::ticker(timespan_t /*time*/)
+void MaterialVariant::ticker(timespan_t /*ticLength*/)
 {
     // Animation ceases once the material is no longer valid.
     if(!Material_IsValid(d->material)) return;
@@ -196,23 +196,25 @@ void MaterialVariant::resetAnim()
     int const layerCount      = Material_LayerCount(d->material);
     for(int i = 0; i < layerCount; ++i)
     {
+        ded_material_layer_t const *layerDef = &def->layers[i];
         LayerState &l = d->layers[i];
+
         l.stage = 0;
-        l.tics  = def->layers[i].stages[0].tics;
+        l.tics  = layerDef->stages[0].tics;
         l.inter = 0;
-        l.texOrigin[0] = def->layers[i].stages[0].texOrigin[0];
-        l.texOrigin[1] = def->layers[i].stages[0].texOrigin[1];
-        l.glowStrength = def->layers[i].stages[0].glowStrength;
+        l.texOrigin[0] = layerDef->stages[0].texOrigin[0];
+        l.texOrigin[1] = layerDef->stages[0].texOrigin[1];
+        l.glowStrength = layerDef->stages[0].glowStrength;
     }
 }
 
-MaterialVariant::LayerState const &MaterialVariant::layer(int layer)
+MaterialVariant::LayerState const &MaterialVariant::layer(int layerNum)
 {
-    if(layer >= 0 && layer < Material_LayerCount(d->material))
-        return d->layers[layer];
+    if(layerNum >= 0 && layerNum < Material_LayerCount(d->material))
+        return d->layers[layerNum];
 
     /// @throw InvalidLayerError Invalid layer reference.
-    throw InvalidLayerError("MaterialVariant::layer", QString("Invalid material layer #%1").arg(layer));
+    throw InvalidLayerError("MaterialVariant::layer", QString("Invalid material layer #%1").arg(layerNum));
 }
 
 MaterialSnapshot &MaterialVariant::attachSnapshot(MaterialSnapshot &newSnapshot)
@@ -241,12 +243,20 @@ MaterialSnapshot *MaterialVariant::snapshot() const
 
 int MaterialVariant::snapshotPrepareFrame() const
 {
-    return d->snapshotPrepareFrame;
+    if(d->snapshot)
+    {
+        return d->snapshotPrepareFrame;
+    }
+    /// @throw MissingSnapshotError A snapshot is needed for this.
+    throw MissingSnapshotError("MaterialVariant::snapshotPrepareFrame", "Snapshot data is required");
 }
 
-void MaterialVariant::setSnapshotPrepareFrame(int frame)
+void MaterialVariant::setSnapshotPrepareFrame(int frameNum)
 {
-    d->snapshotPrepareFrame = frame;
+    if(d->snapshot)
+    {
+        d->snapshotPrepareFrame = frameNum;
+    }
 }
 
 #ifdef LIBDENG_OLD_MATERIAL_ANIM_METHOD