Move ResourceArray to its own header

 - Add docs.

Author: karnkaul

lib/scene/CMakeLists.txt

@@ -43,6 +43,7 @@ target_sources(${PROJECT_NAME} PRIVATE
   include/${target_prefix}/scene/mesh.hpp
   include/${target_prefix}/scene/node_data.hpp
   include/${target_prefix}/scene/node.hpp
+  include/${target_prefix}/scene/resource_array.hpp
   include/${target_prefix}/scene/scene_resources.hpp
   include/${target_prefix}/scene/scene.hpp
 

lib/scene/include/facade/scene/material.hpp

@@ -39,12 +39,12 @@ struct TextureStore {
 };
 
 ///
-/// \brief Base Material: stores render parameters for a mesh.
+/// \brief Base class for concrete materials.
 ///
 class MaterialBase {
   public:
 	///
-	/// \brief The alpha blend mode.
+	/// \brief Alpha blend mode.
 	///
 	enum class AlphaMode : std::uint32_t { eOpaque = 0, eBlend, eMask };
 
@@ -64,9 +64,15 @@ class MaterialBase {
 	///
 	virtual void write_sets(Pipeline& pipeline, TextureStore const& store) const = 0;
 
+	///
+	/// \brief Name of this instance.
+	///
 	std::string name{"(Unnamed)"};
 };
 
+///
+/// \brief Value-semantic strategy wrapper for concrete materials.
+///
 class Material {
   public:
 	using AlphaMode = MaterialBase::AlphaMode;

lib/scene/include/facade/scene/resource_array.hpp

@@ -0,0 +1,82 @@
+#pragma once
+#include <facade/scene/id.hpp>
+#include <facade/util/ptr.hpp>
+#include <span>
+#include <utility>
+#include <vector>
+
+namespace facade {
+///
+/// \brief Wrapper over an array of resources, each identified by the index as its Id.
+///
+/// Only Scene has access to the underlying vector (via friend). Other types can operate
+/// on const / non-const spans, but cannot modify the array itself.
+///
+template <typename T>
+class ResourceArray {
+  public:
+	///
+	/// \brief Obtain an immutable view into the underlying array.
+	/// \returns Immutable span
+	///
+	std::span<T const> view() const { return m_array; }
+	///
+	/// \brief Obtain a mutable view into the underlying array.
+	/// \returns Mutable span
+	///
+	std::span<T> view() { return m_array; }
+
+	///
+	/// \brief Obtain an immutable pointer to the element at index id.
+	/// \param id Id (index) of element
+	/// \returns nullptr if id is out of bounds
+	///
+	Ptr<T const> find(Id<T> id) const {
+		if (id >= m_array.size()) { return {}; }
+		return &m_array[id];
+	}
+
+	///
+	/// \brief Obtain a mutable pointer to the element at index id.
+	/// \param id Id (index) of element
+	/// \returns nullptr if id is out of bounds
+	///
+	Ptr<T> find(Id<T> index) { return const_cast<Ptr<T>>(std::as_const(*this).find(index)); }
+
+	///
+	/// \brief Obtain an immutable reference to the element at index id.
+	/// \param id Id (index) of element
+	/// \returns const reference to element
+	///
+	/// id must be valid / in range
+	///
+	T const& operator[](Id<T> id) const {
+		auto ret = find(id);
+		assert(ret);
+		return *ret;
+	}
+
+	///
+	/// \brief Obtain an immutable reference to the element at index id.
+	/// \param id Id (index) of element
+	/// \returns const reference to element
+	///
+	/// id must be valid / in range
+	///
+	T& operator[](Id<T> index) { return const_cast<T&>(std::as_const(*this).operator[](index)); }
+
+	///
+	/// \brief Obtain the size of the underlying array.
+	///
+	constexpr std::size_t size() const { return m_array.size(); }
+	///
+	/// \brief Check if the underlying array is empty.
+	///
+	constexpr bool empty() const { return m_array.empty(); }
+
+  private:
+	std::vector<T> m_array{};
+
+	friend class Scene;
+};
+} // namespace facade

lib/scene/include/facade/scene/scene_resources.hpp

@@ -2,42 +2,14 @@
 #include <facade/scene/camera.hpp>
 #include <facade/scene/material.hpp>
 #include <facade/scene/mesh.hpp>
-#include <facade/util/ptr.hpp>
+#include <facade/scene/resource_array.hpp>
 #include <facade/vk/static_mesh.hpp>
 #include <facade/vk/texture.hpp>
-#include <span>
 
 namespace facade {
-template <typename T>
-class ResourceArray {
-  public:
-	std::span<T> view() { return m_array; }
-	std::span<T const> view() const { return m_array; }
-
-	Ptr<T const> find(Id<T> index) const {
-		if (index >= m_array.size()) { return {}; }
-		return &m_array[index];
-	}
-
-	Ptr<T> find(Id<T> index) { return const_cast<Ptr<T>>(std::as_const(*this).find(index)); }
-
-	T const& operator[](Id<T> index) const {
-		auto ret = find(index);
-		assert(ret);
-		return *ret;
-	}
-
-	T& operator[](Id<T> index) { return const_cast<T&>(std::as_const(*this).operator[](index)); }
-
-	constexpr std::size_t size() const { return m_array.size(); }
-	constexpr bool empty() const { return m_array.empty(); }
-
-  private:
-	std::vector<T> m_array{};
-
-	friend class Scene;
-};
-
+///
+/// \brief Collection of all ResourceArray instances used by Scene.
+///
 struct SceneResources {
 	ResourceArray<Camera> cameras{};
 	ResourceArray<Sampler> samplers{};