From 7b4b7563aed2424117877aa8d3275f5445caaeeb Mon Sep 17 00:00:00 2001 From: danij Date: Fri, 1 Mar 2013 02:05:58 +0000 Subject: [PATCH] Documentation: Minor apidoc improvements for Materials --- doomsday/client/include/resource/material.h | 2 +- doomsday/client/include/resource/materials.h | 44 ++++++++++++------- doomsday/client/src/dd_main.cpp | 3 +- doomsday/client/src/def_main.cpp | 2 +- doomsday/client/src/map/p_data.cpp | 2 +- doomsday/client/src/resource/materials.cpp | 2 +- .../client/src/resource/materialvariant.cpp | 4 +- 7 files changed, 34 insertions(+), 25 deletions(-) diff --git a/doomsday/client/include/resource/material.h b/doomsday/client/include/resource/material.h index badc01bb17..58f03d241d 100644 --- a/doomsday/client/include/resource/material.h +++ b/doomsday/client/include/resource/material.h @@ -512,7 +512,7 @@ class Material : public de::MapElement * Reset the staged animation point for the material. The animation * states of all layers and decorations will be rewound to the beginning. */ - void resetAnim(); + void restartAnimation(); /** * Returns the current state of the layer animation @a layerNum for diff --git a/doomsday/client/include/resource/materials.h b/doomsday/client/include/resource/materials.h index d8910844ba..8c3d737568 100644 --- a/doomsday/client/include/resource/materials.h +++ b/doomsday/client/include/resource/materials.h @@ -27,13 +27,11 @@ #ifdef __CLIENT__ # include "MaterialVariantSpec" #endif -#include "def_data.h" #include "uri.hh" #include -#include -#include #include #include +#include namespace de { @@ -118,10 +116,11 @@ class Materials * Construct a new material collection. */ Materials(); - virtual ~Materials(); - /// Register the console commands, variables, etc..., of this module. + /** + * Register the console commands, variables, etc..., of this module. + */ static void consoleRegister(); /** @@ -245,11 +244,16 @@ class Materials */ inline int groupCount() const { return allGroups().count(); } - /// - Manifest &newManifest(Uri const &uri); - - /// - void addMaterial(Material &material); + /** + * Declare a material in the collection, producing a manifest for a logical + * Material which will be defined later. If a manifest with the specified + * @a uri already exists the existing manifest will be returned. + * + * @param uri Uri representing a path to the material in the virtual hierarchy. + * + * @return Manifest for this URI. + */ + Manifest &declare(Uri const &uri); /** * Returns a list of all the unique material instances in the collection, @@ -258,18 +262,17 @@ class Materials All const &all() const; #ifdef __CLIENT__ - /** - * Reset all material instance animations back to their initial state. + * Rewind all material animations back to their initial/starting state. * - * @see all(), MaterialVariant::resetAnim() + * @see all(), MaterialVariant::restartAnimation() */ - inline void resetAllAnims() const + inline void restartAllAnimations() const { foreach(Material *material, all()) foreach(MaterialVariant *variant, material->variants()) { - variant->resetAnim(); + variant->restartAnimation(); } } @@ -310,14 +313,21 @@ class Materials */ void cache(Material &material, VariantSpec const &spec, bool cacheGroups = true); - /// Process all outstanding tasks in the cache queue. + /** + * Process all queued material cache tasks. + */ void processCacheQueue(); - /// Empty the Material cache queue, cancelling all outstanding tasks. + /** + * Cancel all queued material cache tasks. + */ void purgeCacheQueue(); #endif // __CLIENT__ + /// @todo Refactor away: + void addMaterial(Material &material); + private: DENG2_PRIVATE(d) }; diff --git a/doomsday/client/src/dd_main.cpp b/doomsday/client/src/dd_main.cpp index 48d3d685a6..70ec67914a 100644 --- a/doomsday/client/src/dd_main.cpp +++ b/doomsday/client/src/dd_main.cpp @@ -2308,8 +2308,7 @@ void DD_UpdateEngineState(void) gx.UpdateState(DD_POST); #ifdef __CLIENT__ - // Reset material animations. - App_Materials().resetAllAnims(); + App_Materials().restartAllAnimations(); #endif } diff --git a/doomsday/client/src/def_main.cpp b/doomsday/client/src/def_main.cpp index 6d15e87861..9f80204324 100644 --- a/doomsday/client/src/def_main.cpp +++ b/doomsday/client/src/def_main.cpp @@ -1150,7 +1150,7 @@ static void interpretMaterialDef(ded_material_t const &def) try { // Create/retrieve a manifest for the would-be material. - MaterialManifest *manifest = &App_Materials().newManifest(*reinterpret_cast(def.uri)); + MaterialManifest *manifest = &App_Materials().declare(*reinterpret_cast(def.uri)); // Update manifest classification: manifest->setFlags(MaterialManifest::AutoGenerated, CPP_BOOL(def.autoGenerated)); diff --git a/doomsday/client/src/map/p_data.cpp b/doomsday/client/src/map/p_data.cpp index b2f4b33656..59f067aa82 100644 --- a/doomsday/client/src/map/p_data.cpp +++ b/doomsday/client/src/map/p_data.cpp @@ -182,7 +182,7 @@ DENG_EXTERN_C boolean P_LoadMap(char const *uriCString) #ifdef __CLIENT__ // Material animations should begin from their first step. - App_Materials().resetAllAnims(); + App_Materials().restartAllAnimations(); R_InitObjlinkBlockmapForMap(); diff --git a/doomsday/client/src/resource/materials.cpp b/doomsday/client/src/resource/materials.cpp index 2d439a123b..914c5d3547 100644 --- a/doomsday/client/src/resource/materials.cpp +++ b/doomsday/client/src/resource/materials.cpp @@ -356,7 +356,7 @@ bool Materials::has(Uri const &path) const return false; } -MaterialManifest &Materials::newManifest(de::Uri const &uri) +MaterialManifest &Materials::declare(de::Uri const &uri) { LOG_AS("Materials::newManifest"); diff --git a/doomsday/client/src/resource/materialvariant.cpp b/doomsday/client/src/resource/materialvariant.cpp index 57670bf7ad..579bf05908 100644 --- a/doomsday/client/src/resource/materialvariant.cpp +++ b/doomsday/client/src/resource/materialvariant.cpp @@ -170,7 +170,7 @@ Material::Variant::Variant(Material &generalCase, Material::VariantSpec const &s : d(new Instance(this, generalCase, spec)) { // Initialize animation states. - resetAnim(); + restartAnimation(); } Material::Variant::~Variant() @@ -263,7 +263,7 @@ void Material::Variant::ticker(timespan_t /*ticLength*/) } } -void Material::Variant::resetAnim() +void Material::Variant::restartAnimation() { // Animation ceases once the material is no longer valid. if(!d->material->isValid()) return;