Refactor|Materials: Continued cleanup refactorings

doomsday/engine/include/resource/materials.h

@@ -40,6 +40,17 @@ namespace de {
 
     /**
      * Specialized resource collection for a set of materials.
+     *
+     * - Pointers to Material are @em eternal, they are always valid and continue
+     *   to reference the same logical material data even after engine reset.
+     *
+     * - Public material identifiers (materialid_t) are similarly eternal.
+     *
+     * - Material name bindings are semi-independant from the materials. There
+     *   may be multiple name bindings for a given material (aliases). The only
+     *   requirement is that their symbolic names must be unique among those in
+     *   the same scheme.
+     *
      * @ingroup resource
      */
     class Materials
@@ -79,8 +90,19 @@ namespace de {
         /// Register the console commands, variables, etc..., of this module.
         static void consoleRegister();
 
-        /// @return  Total number of unique materials in the collection.
-        uint size();
+        /**
+         * Returns the total number of unique materials in the collection.
+         */
+        uint size() const;
+
+        /**
+         * Returns the total number of unique materials in the collection.
+         *
+         * Same as size()
+         */
+        inline uint count() const {
+            return size();
+        }
 
         /// Process all outstanding tasks in the cache queue.
         void processCacheQueue();
@@ -171,18 +193,18 @@ namespace de {
          * @param material  Material to be updated.
          * @param def  Material definition to update using.
          */
-        void rebuild(material_t *material, ded_material_t *def);
+        void rebuild(material_t &material, ded_material_t *def = 0);
 
         void updateTextureLinks(MaterialBind &bind);
 
         /// @return  (Particle) Generator definition associated with @a material else @c NULL.
-        ded_ptcgen_t const *ptcGenDef(material_t *material);
+        ded_ptcgen_t const *ptcGenDef(material_t &material);
 
         /// @return  Decoration defintion associated with @a material else @c NULL.
-        ded_decor_t const *decorationDef(material_t *material);
+        ded_decor_t const *decorationDef(material_t &material);
 
         /// @return  @c true if one or more light decorations are defined for this material.
-        bool hasDecorations(material_t *material);
+        bool hasDecorations(material_t &material);
 
         /**
          * Create a new Material unless an existing Material is found at the path
@@ -194,10 +216,10 @@ namespace de {
          * @param def  Material definition to construct from.
          * @return  The newly-created/existing material; otherwise @c NULL.
          */
-        material_t *newFromDef(ded_material_t *def);
+        material_t *newFromDef(ded_material_t &def);
 
         MaterialBind &newBind(MaterialScheme &scheme, Path const &path,
-                              material_t *material);
+                              material_t *material = 0);
 
         /**
          * Prepare a MaterialVariantSpecification according to a usage context. If
@@ -316,10 +338,10 @@ namespace de {
          * @param tics          Base duration of the new frame in tics.
          * @param randomTics    Extra frame duration in tics (randomized on each cycle).
          */
-        void addAnimGroupFrame(int animGroupNum, material_t *material, int tics, int randomTics);
+        void addAnimGroupFrame(int animGroupNum, material_t &material, int tics, int randomTics);
 
         /// @return  @c true iff @a material is linked to the identified @a animGroupNum.
-        bool isMaterialInAnimGroup(material_t *material, int animGroupNum);
+        bool isMaterialInAnimGroup(material_t &material, int animGroupNum);
 
         /// @todo Refactor; does not fit the current design.
         /// @return  @c true iff @a animGroupNum is a special precache group.

doomsday/engine/include/resource/materialvariant.h

@@ -40,9 +40,56 @@ typedef enum materialcontext_e {
 
 struct texturevariantspecification_s;
 
+/**
+ * @ingroup resource
+ */
 typedef struct materialvariantspecification_s {
+    /// Usage context identifier.
     enum materialcontext_e context;
+
+    /// Specification for the primary texture.
     struct texturevariantspecification_s *primarySpec;
+
+#ifdef __cplusplus
+    /**
+     * Construct a default MaterialVariantSpecification instance.
+     */
+    materialvariantspecification_s() : context(MC_UNKNOWN), primarySpec(0)
+    {}
+
+    /**
+     * Construct a MaterialVariantSpecification instance by duplicating @a other.
+     */
+    materialvariantspecification_s(materialvariantspecification_s const &other)
+        : context(other.context), primarySpec(other.primarySpec)
+    {}
+
+    /**
+     * Determines whether specification @a other is equal to this specifcation.
+     *
+     * @param other  The other specification.
+     * @return  @c true if specifications are equal; otherwise @c false.
+     *
+     * Same as operator ==
+     */
+    bool compare(struct materialvariantspecification_s const &other) const;
+
+    /**
+     * Determines whether specification @a other is equal to this specifcation.
+     * @see compare()
+     */
+    bool operator == (struct materialvariantspecification_s const &other) const {
+        return compare(other);
+    }
+
+    /**
+     * Determines whether specification @a other is NOT equal to this specifcation.
+     * @see compare()
+     */
+    bool operator != (struct materialvariantspecification_s const &other) const {
+        return !(*this == other);
+    }
+#endif
 } materialvariantspecification_t;
 
 #ifdef __cplusplus
@@ -109,7 +156,7 @@ class MaterialVariant
     materialvariantspecification_t const &spec() const;
 
     /**
-     * Retrieve a handle for a staged animation layer form this variant.
+     * Retrieve a handle for a staged animation layer for this variant.
      * @param layer  Index of the layer to retrieve.
      * @return  MaterialVariantLayer for the specified layer index.
      */
@@ -126,7 +173,7 @@ class MaterialVariant
      */
     MaterialSnapshot *detachSnapshot();
 
-    /// @return  MaterialSnapshot data associated with this.
+    /// @return  MaterialSnapshot data associated with this; otherwise @c 0.
     MaterialSnapshot *snapshot() const;
 
     /// @return  Frame count when the snapshot was last prepared/updated.

doomsday/engine/src/def_main.cpp

@@ -579,8 +579,8 @@ ded_ptcgen_t* Def_GetGenerator(material_t *mat, boolean hasExternal, boolean isC
                         if(App_Materials()->isPrecacheAnimGroup(g))
                             continue; // Precache groups don't apply.
 
-                        if(App_Materials()->isMaterialInAnimGroup(defMat, g) &&
-                           App_Materials()->isMaterialInAnimGroup(mat, g))
+                        if(App_Materials()->isMaterialInAnimGroup(*defMat, g) &&
+                           App_Materials()->isMaterialInAnimGroup(*mat, g))
                         {
                             // Both are in this group! This def will do.
                             return def;
@@ -1204,13 +1204,13 @@ void Def_Read()
             if(material_t *mat = bind.material())
             {
                 // Update existing.
-                App_Materials()->rebuild(mat, def);
+                App_Materials()->rebuild(*mat, def);
             }
         }
         catch(Materials::NotFoundError const &)
         {
             // A new Material.
-            App_Materials()->newFromDef(def);
+            App_Materials()->newFromDef(*def);
         }
     }
 
@@ -1441,7 +1441,7 @@ static void initAnimGroup(ded_group_t *def)
                 groupNumber = App_Materials()->newAnimGroup(def->flags);
             }
 
-            App_Materials()->addAnimGroupFrame(groupNumber, mat, gm->tics, gm->randomTics);
+            App_Materials()->addAnimGroupFrame(groupNumber, *mat, gm->tics, gm->randomTics);
         }
         catch(Materials::NotFoundError const &er)
         {

doomsday/engine/src/map/r_world.cpp

@@ -1279,8 +1279,15 @@ static void addToSurfaceLists(Surface *suf, material_t *mat)
 {
     if(!suf || !mat) return;
 
-    if(Material_HasGlow(mat))         R_SurfaceListAdd(GameMap_GlowingSurfaces(theMap),   suf);
-    if(App_Materials()->hasDecorations(mat)) R_SurfaceListAdd(GameMap_DecoratedSurfaces(theMap), suf);
+    if(Material_HasGlow(mat))
+    {
+        R_SurfaceListAdd(GameMap_GlowingSurfaces(theMap),   suf);
+    }
+
+    if(App_Materials()->hasDecorations(*mat))
+    {
+        R_SurfaceListAdd(GameMap_DecoratedSurfaces(theMap), suf);
+    }
 }
 
 void R_MapInitSurfaceLists()

doomsday/engine/src/map/surface.cpp

@@ -82,14 +82,14 @@ boolean Surface_SetMaterial(Surface *suf, material_t *mat)
                         R_SurfaceListAdd(GameMap_GlowingSurfaces(map), suf);
                     }
 
-                    if(App_Materials()->hasDecorations(mat))
+                    if(App_Materials()->hasDecorations(*mat))
                     {
                         R_SurfaceListAdd(GameMap_DecoratedSurfaces(map), suf);
                     }
 
                     if(DMU_GetType(suf->owner) == DMU_PLANE)
                     {
-                        ded_ptcgen_t const *def = App_Materials()->ptcGenDef(mat);
+                        ded_ptcgen_t const *def = App_Materials()->ptcGenDef(*mat);
                         P_SpawnPlaneParticleGen(def, (Plane *)suf->owner);
                     }
                 }

doomsday/engine/src/render/rend_decor.cpp

@@ -473,7 +473,7 @@ static void updateSurfaceDecorations2(Surface *suf, float offsetS, float offsetT
     {
         materialvariantspecification_t const *spec = Rend_MapSurfaceDiffuseMaterialSpec();
         material_t *mat = &App_Materials()->chooseVariant(*suf->material, *spec, true, true)->generalCase();
-        ded_decor_t const *def = App_Materials()->decorationDef(mat);
+        ded_decor_t const *def = App_Materials()->decorationDef(*mat);
         if(def)
         {
             int const axis = V3f_MajorAxis(suf->normal);