Re-arrange functions in graphics::manager.

Rename manager_impl to manager_cache.
Add comments to graphics::manager.

graphics/include/game/graphics/manager.hpp

@@ -20,23 +20,63 @@ namespace graphics {
     manager();
     ~manager();
 
+    /**
+     * @brief Load a material - from either cache or by fetching data from the
+     * given arguments - and return its identifier.
+     * A material is a linkage of shader(s) and texture(s), that desribe the
+     * needed details to draw it on a page.
+     * @param program The shader program that should be used to paint this
+     * material.
+     * @param texture The path to an image file for this material
+     * @param uniform The name of the uniform to use as a fallback texture
+     */
     identity<material> get(identity<shader_program> program,
                            std::string const & texture,
                            std::string const & uniform) const;
+    /**
+     * @brief Load a shader - from either cache or by fetching data from the
+     * given arguments - and return its identifier.
+     * A shader is a type of program that is run on the GPU by a library like
+     * OpenGL.
+     * @param type A shader type describe what it draws...
+     * @param path The path to the shader's source code file.
+     */
     identity<shader> get(shaders::type type, std::string const & path) const;
+    /**
+     * @brief Load a shader_program - from either cache or by fetching data from
+     * the given arguments - and return its identifier.
+     * @param fragment The file path to the fragment shader code.
+     * @param vertex The file path to the vertex shader code.
+     */
     identity<shader_program> get(std::string const & fragment,
                                  std::string const & vertex) const;
+    /**
+     * @brief Load a texture - from either cache or by fetching data from the
+     * given arguments - and return its identifier.
+     * @param path The file path to an imagefile that contains one or more
+     * drawings of the object to be rendered.
+     */
     identity<texture> get(std::string const & path) const;
 
+    // TODO: This is kinda dumb...
     object create_object(identity<material> fromMaterial, math::vec2 atPosition,
                          math::vec2 frameWidth, float scale) const;
+
+    /**
+     * @brief Translate a material identity into an actual object.
+     * Used for internal linkage with the implementation code.
+     */
     material const & get(identity<material> identity) const;
+    /**
+     * @brief Translate a texture identity into an actual object.
+     * Used for internal linkage with the implementation code.
+     */
     texture const & get(identity<texture> identity) const;
 
   private:
     identity<texture> texture_or_uniform(std::string const & path,
                                          std::string const & uniform) const;
 
-    std::unique_ptr<struct manager_impl> pimpl_;
+    std::unique_ptr<struct manager_cache> pcache_;
   };
 }

graphics/src/manager.cxx

@@ -45,21 +45,21 @@ identity<T> cache<T>::emplace(key_t<T> const & key, T && value) {
   return values.emplace(key, std::forward<T>(value)).first->second;
 }
 
-struct graphics::manager_impl {
+struct graphics::manager_cache {
   cache<material> materials;
   cache<shader> shaders;
   cache<shader_program> programs;
   cache<texture> textures;
 };
 
-manager::manager() : pimpl_(new manager_impl) {}
+manager::manager() : pcache_(new manager_cache) {}
 manager::~manager() {}
 
 identity<material> manager::get(identity<shader_program> program,
                                 std::string const & texture,
                                 std::string const & uniform) const {
   auto key = std::make_tuple(program, texture, uniform);
-  auto & cache = pimpl_->materials;
+  auto & cache = pcache_->materials;
   auto found = cache.values.find(key);
   if (found != cache.values.end()) { return found->second; }
 
@@ -71,51 +71,19 @@ identity<material> manager::get(identity<shader_program> program,
   return cache.emplace(key, material(program, size, uniforms));
 }
 
-material const & manager::get(identity<material> identity) const {
-  auto & cache = pimpl_->materials;
-  return cache.values.find(cache.keys.find(identity)->second)->second;
-}
-
-texture const & manager::get(identity<texture> identity) const {
-  auto & cache = pimpl_->textures;
-  auto it = cache.keys.find(identity);
-  if (it == cache.keys.end()) { return texture::WHITE(); }
-  return cache.values.find(it->second)->second;
-}
-
 identity<shader> manager::get(shaders::type type,
                               std::string const & path) const {
   auto key = std::make_pair(type, path);
-  auto & cache = pimpl_->shaders;
+  auto & cache = pcache_->shaders;
   auto found = cache.values.find(key);
   if (found != cache.values.end()) { return found->second; }
   return cache.emplace(key, shader(type, path));
 }
 
-identity<texture>
-manager::texture_or_uniform(std::string const & path,
-                            std::string const & uniform) const {
-  if (!path.empty()) {
-    try {
-      return get(path);
-    } catch (std::exception const & e) {
-      // TODO: Logging
-    }
-  }
-  if (uniform == "u_normalMap") {
-    return texture::LIGHT_BLUE();
-  } else if (uniform == "u_specularMap") {
-    return texture::DARK_YELLOW();
-  } else if (uniform == "u_diffuseMap") {
-    return texture::WHITE();
-  }
-  throw;
-}
-
 identity<shader_program> manager::get(std::string const & fragment,
                                       std::string const & vertex) const {
   auto key = std::make_pair(fragment, vertex);
-  auto & cache = pimpl_->programs;
+  auto & cache = pcache_->programs;
   auto found = cache.values.find(key);
   if (found != cache.values.end()) { return found->second; }
   auto fragment_shader = get(shaders::type::FRAGMENT, fragment);
@@ -125,7 +93,7 @@ identity<shader_program> manager::get(std::string const & fragment,
 }
 
 identity<texture> manager::get(std::string const & path) const {
-  auto & cache = pimpl_->textures;
+  auto & cache = pcache_->textures;
   auto found = cache.values.find(path);
   if (found != cache.values.end()) { return found->second; }
   return cache.emplace(path, texture(path));
@@ -138,3 +106,35 @@ object manager::create_object(identity<material> fromMaterial,
                                                (scale ? scale : 1.f)};
   return {bounds, bounds, fromMaterial, {make_vector(0.f, 0.f), frameWidth}};
 }
+
+material const & manager::get(identity<material> identity) const {
+  auto & cache = pcache_->materials;
+  return cache.values.find(cache.keys.find(identity)->second)->second;
+}
+
+texture const & manager::get(identity<texture> identity) const {
+  auto & cache = pcache_->textures;
+  auto it = cache.keys.find(identity);
+  if (it == cache.keys.end()) { return texture::WHITE(); }
+  return cache.values.find(it->second)->second;
+}
+
+identity<texture>
+manager::texture_or_uniform(std::string const & path,
+                            std::string const & uniform) const {
+  if (!path.empty()) {
+    try {
+      return get(path);
+    } catch (std::exception const & e) {
+      // TODO: Logging
+    }
+  }
+  if (uniform == "u_normalMap") {
+    return texture::LIGHT_BLUE();
+  } else if (uniform == "u_specularMap") {
+    return texture::DARK_YELLOW();
+  } else if (uniform == "u_diffuseMap") {
+    return texture::WHITE();
+  }
+  throw;
+}