More doc comments. (Part 3)

Move some graphics/ headers into graphics/detail/.

example/flappy/src/pipes.hpp

@@ -1,6 +1,6 @@
 #pragma once
 #include <bave/core/random.hpp>
-#include <bave/graphics/sprite.hpp>
+#include <bave/graphics/sprite_9slice.hpp>
 #include <src/config.hpp>
 
 class Pipes {

lib/include/bave/graphics/anim_timeline.hpp

@@ -4,10 +4,16 @@
 #include <vector>
 
 namespace bave {
+/// \brief Animation Timeline as a cycle of atlas tiles.
 struct AnimTimeline {
+	/// \brief IDS of tiles to cycle through.
 	std::vector<std::string> tiles{};
+	/// \brief Duration of timeline.
 	Seconds duration{1s};
 
+	/// \brief Obtain the tile ID at a given timestamp.
+	/// \param timestamp Timestamp to get tile ID for.
+	/// \return Tile ID corresponding to timestamp. Empty string if tiles is empty.
 	[[nodiscard]] auto get_tile_at(Seconds timestamp) const -> std::string_view;
 };
 } // namespace bave

lib/include/bave/graphics/bitmap.hpp

@@ -6,28 +6,41 @@
 #include <vector>
 
 namespace bave {
+/// \brief View of a 2D bitmap.
 struct BitmapView {
+	/// \brief Bytestream representing bitmap data.
 	std::span<std::byte const> bytes{};
+	/// \brief Size of bitmap.
 	glm::ivec2 extent{};
 };
 
+/// \brief Interface that produces a BitmapView.
 class IBitmapViewSource : public Polymorphic {
   public:
+	/// \brief Obtain a BitmapView.
+	/// \returns BitmapView of stored data.
 	[[nodiscard]] virtual auto get_bitmap_view() const -> BitmapView = 0;
 };
 
+/// \brief 2D Bitmap storage.
 class Bitmap : public IBitmapViewSource {
   public:
 	using View = BitmapView;
 
+	/// \brief Constructor.
+	/// \param bytes Bytestream representing bitmap data.
+	/// \param extent Size of bitmap.
 	explicit Bitmap(std::vector<std::byte> bytes, glm::ivec2 extent) : m_bytes(std::move(bytes)), m_extent(extent) {}
 
+	/// \brief Obtain a BitmapView.
+	/// \returns BitmapView of stored data.
 	[[nodiscard]] auto get_bitmap_view() const -> BitmapView final { return {.bytes = std::span<std::byte const>{m_bytes}, .extent = m_extent}; }
 
   private:
 	std::vector<std::byte> m_bytes{};
 	glm::ivec2 m_extent{};
 };
 
+/// \brief Check if an integer is a power of two.
 constexpr auto is_power_of_2(int const in) -> bool { return std::popcount(static_cast<std::uint32_t>(in)) == 1; }
 } // namespace bave

lib/include/bave/graphics/detail/pipeline_cache.hpp

@@ -1,7 +1,7 @@
 #pragma once
 #include <bave/graphics/detail/descriptor_cache.hpp>
+#include <bave/graphics/detail/set_layout.hpp>
 #include <bave/graphics/detail/shader_cache.hpp>
-#include <bave/graphics/set_layout.hpp>
 #include <span>
 
 namespace bave::detail {

lib/include/bave/graphics/render_target.hpp → lib/include/bave/graphics/detail/render_target.hpp

@@ -1,7 +1,7 @@
 #pragma once
 #include <vulkan/vulkan.hpp>
 
-namespace bave {
+namespace bave::detail {
 enum class ColourSpace : int { eSrgb, eLinear };
 
 struct RenderTarget {
@@ -10,4 +10,4 @@ struct RenderTarget {
 	vk::Extent2D extent{};
 	vk::Format format{};
 };
-} // namespace bave
+} // namespace bave::detail

lib/include/bave/graphics/set_layout.hpp → lib/include/bave/graphics/detail/set_layout.hpp

@@ -2,7 +2,7 @@
 #include <vulkan/vulkan.hpp>
 #include <cstdint>
 
-namespace bave {
+namespace bave::detail {
 template <std::size_t Count>
 constexpr auto make_bindings(vk::DescriptorType const type) -> std::array<vk::DescriptorType, Count> {
 	auto ret = std::array<vk::DescriptorType, Count>{};
@@ -36,4 +36,4 @@ struct SetLayout {
 };
 
 constexpr auto set_layout_v = SetLayout{};
-} // namespace bave
+} // namespace bave::detail

lib/include/bave/graphics/detail/swapchain.hpp

@@ -1,6 +1,6 @@
 #pragma once
+#include <bave/graphics/detail/render_target.hpp>
 #include <bave/graphics/gpu.hpp>
-#include <bave/graphics/render_target.hpp>
 #include <cstdint>
 #include <optional>
 #include <vector>

lib/include/bave/graphics/drawable.hpp

@@ -7,17 +7,28 @@
 #include <vector>
 
 namespace bave {
+/// \brief Base class for drawable objects.
 class Drawable : public Polymorphic {
   public:
+	/// \brief Draw this object using a given shader.
+	/// \param shader Shader instance to use.
 	void draw(Shader& shader) const;
 
+	/// \brief Get the bounding rectangle of this instance.
 	[[nodiscard]] auto get_bounds() const -> Rect<>;
+	/// \brief Get the Geometry of this instance.
 	[[nodiscard]] auto get_geometry() const -> Geometry const& { return m_geometry; }
 
+	/// \brief World transform of this instance.
 	Transform transform{};
-	Rgba tint{};
-	std::array<std::shared_ptr<Texture const>, SetLayout::max_textures_v> textures{};
-
+	/// \brief Tint to apply during draw.
+	Rgba tint{white_v};
+	/// \brief Textures to bind during draw.
+	std::array<std::shared_ptr<Texture const>, Shader::max_textures_v> textures{};
+
+	/// \brief Instanced rendering.
+	///
+	/// transform and tint are ignored if instances is not empty.
 	std::vector<RenderInstance> instances{};
 
   protected:

lib/include/bave/graphics/extent_scaler.hpp

@@ -2,41 +2,60 @@
 #include <bave/core/is_positive.hpp>
 
 namespace bave {
-///
 /// \brief Maintains source aspect ratio and scales positive extents.
-///
 struct ExtentScaler {
+	/// \brief Source extent.
 	glm::vec2 source{};
 
+	/// \brief Obtain the aspect ratio of a given 2D vector.
+	/// \param extent Size of input.
+	/// \returns Aspect ratio of input. Zero if extent is non-positive.
 	[[nodiscard]] static constexpr auto aspect_ratio(glm::vec2 const extent) -> float {
 		if (!is_positive(extent)) { return {}; }
 		return extent.x / extent.y;
 	}
 
+	/// \brief Obtain the aspect ratio of source.
+	/// \returns Aspect ratio of source.
 	[[nodiscard]] constexpr auto aspect_ratio() const -> float { return aspect_ratio(source); }
 
+	/// \brief Scale by matching width of input.
+	/// \param of Input to match width of.
+	/// \returns Scaled extent while maintaining aspect ratio.
 	[[nodiscard]] constexpr auto match_width(glm::vec2 const of) const -> glm::vec2 {
 		if (!is_positive(source) || !is_positive(of)) { return {}; }
 		auto const scale = of.x / source.x;
 		return scale * source;
 	}
 
+	/// \brief Scale by matching height of input.
+	/// \param of Input to match height of.
+	/// \returns Scaled extent while maintaining aspect ratio.
 	[[nodiscard]] constexpr auto match_height(glm::vec2 const of) const -> glm::vec2 {
 		if (!is_positive(source) || !is_positive(of)) { return {}; }
 		auto const scale = of.y / source.y;
 		return scale * source;
 	}
 
+	/// \brief Scale by matching smaller of width and height.
+	/// \param of Input to match dimension of.
+	/// \returns Scaled extent while maintaining aspect ratio.
 	[[nodiscard]] constexpr auto match_smaller(glm::vec2 const of) const -> glm::vec2 {
 		if (of.x < source.x) { return match_width(of); }
 		return match_height(of);
 	}
 
+	/// \brief Scale by matching larger of width and height.
+	/// \param of Input to match dimension of.
+	/// \returns Scaled extent while maintaining aspect ratio.
 	[[nodiscard]] constexpr auto match_larger(glm::vec2 const of) const -> glm::vec2 {
 		if (of.x > source.x) { return match_width(of); }
 		return match_height(of);
 	}
 
+	/// \brief Scale by fitting final rect within given space.
+	/// \param in Size limits.
+	/// \returns Scaled extent while maintaining aspect ratio.
 	[[nodiscard]] constexpr auto fit_space(glm::vec2 const in) const -> glm::vec2 {
 		auto const source_ar = aspect_ratio(source);
 		auto const dest_ar = aspect_ratio(in);

lib/include/bave/graphics/geometry.hpp

@@ -9,6 +9,7 @@
 #include <vector>
 
 namespace bave {
+/// \brief A single 2D vertex.
 struct Vertex {
 	glm::vec2 position{};
 	glm::vec2 uv{};
@@ -21,6 +22,7 @@ struct RoundedQuad;
 struct NineQuad;
 struct LineRect;
 
+/// \brief Collection of vertices and indices representing a graphics draw primitive.
 struct Geometry {
 	std::vector<Vertex> vertices{};
 	std::vector<std::uint32_t> indices{};
@@ -41,6 +43,7 @@ struct Geometry {
 	}
 };
 
+/// \brief Spec for an axis-aligned quad.
 struct Quad {
 	static constexpr auto size_v = glm::vec2{200.0f};
 
@@ -54,6 +57,7 @@ struct Quad {
 	auto operator==(Quad const&) const -> bool = default;
 };
 
+/// \brief Spec for a circle.
 struct Circle {
 	static constexpr int resolution_v{128};
 	static constexpr auto diameter_v{200.0f};
@@ -68,6 +72,7 @@ struct Circle {
 	auto operator==(Circle const&) const -> bool = default;
 };
 
+/// \brief Spec for a quad with rounded corners.
 struct RoundedQuad : Quad {
 	float corner_radius{0.25f * size_v.x};
 	int corner_resolution{8};
@@ -77,13 +82,15 @@ struct RoundedQuad : Quad {
 	auto operator==(RoundedQuad const&) const -> bool = default;
 };
 
+/// \brief Spec for a 9-slice.
 struct NineSlice {
 	glm::vec2 n_left_top{0.25f};
 	glm::vec2 n_right_bottom{0.75f};
 
 	auto operator==(NineSlice const&) const -> bool = default;
 };
 
+/// \brief Spec for a 9-sliced axis-aligned quad.
 struct NineQuad {
 	struct Size {
 		glm::vec2 reference{Quad::size_v};

lib/include/bave/graphics/image_file.hpp

@@ -3,10 +3,16 @@
 #include <memory>
 
 namespace bave {
+/// \brief Image file decompresser.
 class ImageFile : public IBitmapViewSource {
   public:
+	/// \brief Attempt to load a compressed image.
+	/// \param compressed Bytestream representing image data.
+	/// \returns true on success.
 	auto load_from_bytes(std::span<std::byte const> compressed) -> bool;
 
+	/// \brief Obtain a view into the decompressed bitmap.
+	/// \returns a BitmapView into the decompressed bitmap.
 	[[nodiscard]] auto get_bitmap_view() const -> BitmapView final;
 
 	[[nodiscard]] auto is_empty() const -> bool { return m_impl == nullptr; }

lib/include/bave/graphics/particle_emitter.hpp

@@ -5,6 +5,7 @@
 #include <bave/graphics/shape.hpp>
 
 namespace bave {
+/// \brief Configuration for a particle emitter.
 struct ParticleConfig {
 	struct {
 		InclusiveRange<glm::vec2> position{};
@@ -30,6 +31,7 @@ struct ParticleConfig {
 	bool respawn{true};
 };
 
+/// \brief Particle Emitter.
 class ParticleEmitter : public QuadShape {
   public:
 	struct Modifier {

lib/include/bave/graphics/pixmap.hpp

@@ -7,46 +7,73 @@
 #include <vector>
 
 namespace bave {
+/// \brief Writeable array of Rgba.
 class Pixmap {
   public:
 	struct Atlas;
 	class Builder;
 
-	explicit Pixmap(glm::ivec2 size = {1, 1}, Rgba background = black_v);
+	/// \brief Constructor.
+	/// \param extent Extent (size) of bitmap.
+	/// \param background initializer for all Rgba values.
+	explicit Pixmap(glm::ivec2 extent = {1, 1}, Rgba background = black_v);
 
-	[[nodiscard]] auto get_size() const -> glm::ivec2 { return m_size; }
+	[[nodiscard]] auto get_extent() const -> glm::ivec2 { return m_extent; }
 
+	/// \brief Overwrite image data.
+	/// \param source Source Pixmap to read from.
+	/// \param left_top Destination offset to start overwriting at.
+	/// \returns true on success.
 	auto overwrite(Pixmap const& source, Index2D left_top) -> bool;
 
+	/// \brief Obtain Rgba at given Index2D.
+	/// \returns Const reference to Rgba.
 	[[nodiscard]] auto at(Index2D index) const -> Rgba const&;
+	/// \brief Obtain Rgba at given Index2D.
+	/// \returns Mutable reference to Rgba.
 	[[nodiscard]] auto at(Index2D index) -> Rgba&;
 
+	/// \brief Create a byte bitmap from stored Rgba bitmap.
+	/// \returns Rgba Bitmap.
 	[[nodiscard]] auto make_bitmap() const -> Bitmap;
 
 	[[nodiscard]] auto is_empty() const -> bool { return m_pixels.empty(); }
 
   private:
-	glm::ivec2 m_size{};
+	glm::ivec2 m_extent{};
 	std::vector<Rgba> m_pixels{};
 };
 
+/// \brief Atlas of sub-images.
 struct Pixmap::Atlas {
 	using Id = std::uint32_t;
 
+	/// \brief Combined Pixmap.
 	Pixmap pixmap{};
+	/// \brief UV coordinates of each sub-image.
 	std::unordered_map<Id, UvRect> uvs{};
 };
 
+/// \brief Builder for Pixmap::Atlas.
 class Pixmap::Builder {
   public:
 	using Id = Atlas::Id;
 
 	static constexpr int min_width_v{16};
 
+	/// \brief Constructor.
+	/// \param max_width Maximum width of final pixmap.
+	/// \param pad Padding between each sub-image.
 	explicit Builder(int max_width, glm::ivec2 pad = {1, 1});
 
+	/// \brief Add a sub-image.
+	/// \param id Id to associate with.
+	/// \param pixmap Sub-image to add.
 	void add(Id id, Pixmap pixmap);
 
+	/// \brief Buld Atlas.
+	/// \param background Background Rgba.
+	/// \returns Built Atlas.
 	[[nodiscard]] auto build(Rgba background = black_v) const -> Atlas;
 
   private:

lib/include/bave/graphics/projector.hpp

@@ -2,13 +2,16 @@
 #include <bave/core/is_positive.hpp>
 
 namespace bave {
-///
 /// \brief Projects a point from source space to target space.
-///
 struct Projector {
+	/// \brief Source space.
 	glm::vec2 source{};
+	/// \brief Target space.
 	glm::vec2 target{};
 
+	/// \brief Project a point.
+	/// \param point Point in source space.
+	/// \returns Point in target space.
 	[[nodiscard]] constexpr auto project(glm::vec2 const point) const -> glm::vec2 {
 		if (!is_positive(source) || source == target) { return point; }
 		return point * target / source;