Working on comments (#49)

* More comments added. Still WIP.

* Minimize Gui interface; update docs

* Move util/ring_buffer to vk/rotator, document all util types

Also rename `RingBuffer` to `Rotator`.

* Move DeferQueue from util to vk

* Document scene, move Transform from scene to util

- Remove rect.hpp (unused).
- `Transform` was initially more complex: contained child transforms too. Since it is now a pure data component agnostic to the scene, it has been moved to util.

* Document glfw

* Document render

Co-authored-by: Karn Kaul <karnkaul@gmail.com>

Author: Rinzii

lib/engine/src/engine.cpp

@@ -129,15 +129,15 @@ struct DearImGui : Gui {
 		pool = init_imgui(info);
 	}
 
-	void new_frame() final {
+	void new_frame() {
 		if (state == State::eEndFrame) { end_frame(); }
 		ImGui_ImplVulkan_NewFrame();
 		ImGui_ImplGlfw_NewFrame();
 		ImGui::NewFrame();
 		state = State::eEndFrame;
 	}
 
-	void end_frame() final {
+	void end_frame() {
 		// ImGui::Render calls ImGui::EndFrame
 		ImGui::Render();
 		state = State::eNewFrame;
@@ -151,9 +151,9 @@ struct RenderWindow {
 	Vulkan vulkan;
 	Gfx gfx;
 	Renderer renderer;
-	std::unique_ptr<Gui> gui;
+	std::unique_ptr<DearImGui> gui;
 
-	RenderWindow(UniqueWin window, std::unique_ptr<Gui> gui, std::uint8_t msaa, bool validation)
+	RenderWindow(UniqueWin window, std::unique_ptr<DearImGui> gui, std::uint8_t msaa, bool validation)
 		: window(std::move(window)), vulkan(GlfwWsi{this->window}, validation), gfx(vulkan.gfx()),
 		  renderer(gfx, this->window, gui.get(), Renderer::CreateInfo{command_buffers_v, msaa}), gui(std::move(gui)) {}
 };

lib/glfw/include/facade/glfw/glfw.hpp

@@ -9,39 +9,106 @@
 #include <vector>
 
 namespace facade {
+///
+/// \brief Represents a GLFW instance.
+///
+/// GLFW is initialized and shutdown agnostic of any windows created.
+/// GLFW polls all windows for events simultaneously (ergo, they all share the same delta-time).
+/// The required Vulkan Device extensions are specific to a platform, independent of any windows in use.
+/// Glfw handles all these responsibilities.
+///
 struct Glfw {
 	struct Window;
 	struct Deleter;
 	struct State;
 
+	///
+	/// \brief Whether this instance is active.
+	///
+	/// Used for move semantics.
+	///
 	bool active{};
 
+	///
+	/// \brief Obtain the Vulkan Device extensions for this windowing platform.
+	///
 	std::vector<char const*> vk_extensions() const;
+	///
+	/// \brief Poll all windows for events.
+	///
 	void poll_events();
+	///
+	/// \brief Reset delta time.
+	///
 	void reset_dt();
 
 	bool operator==(Glfw const&) const = default;
 };
 
+///
+/// \brief RAII GLFW Window
+///
 using UniqueWin = Unique<Glfw::Window, Glfw::Deleter>;
 
+///
+/// \brief A snapshot of the current window / input state.
+///
 struct Glfw::State {
+	///
+	/// \brief Input state.
+	///
 	Input input{};
+	///
+	/// \brief Paths of files dropped on the window this frame.
+	///
+	/// All paths are supplied in generic form (/path/to/file).
+	///
 	std::vector<std::string> file_drops{};
+	///
+	/// \brief Delta-time between polls.
+	///
 	float dt{};
 
+	///
+	/// \brief Obtain the filename of a file drop path.
+	/// \param path Path to extract filename from
+	///
+	/// Passed path must be in generic form.
+	///
 	static std::string to_filename(std::string_view path);
 };
 
+///
+/// \brief Represents a GLFW Window.
+///
 struct Glfw::Window {
+	///
+	/// \brief Shared Glfw instance.
+	///
 	std::shared_ptr<Glfw> glfw{};
+	///
+	/// \brief GLFW window associated with this instance.
+	///
 	GLFWwindow* win{};
 
+	///
+	/// \brief Create a new window.
+	/// \returns RAII Glfw::Window
+	///
 	static UniqueWin make();
 
+	///
+	/// \brief Obtain the extent (size) of the window.
+	///
 	glm::uvec2 window_extent() const;
+	///
+	/// \brief Obtain the extent (size) of the framebuffer.
+	///
 	glm::uvec2 framebuffer_extent() const;
 
+	///
+	/// \brief Obtain the state since the last poll.
+	///
 	State const& state() const;
 
 	operator GLFWwindow*() const { return win; }

lib/glfw/include/facade/glfw/glfw_wsi.hpp

@@ -3,10 +3,16 @@
 #include <facade/vk/wsi.hpp>
 
 namespace facade {
+///
+/// \brief Concrete Wsi using GLFW.
+///
 struct GlfwWsi : Wsi {
+	///
+	/// \brief The window in use.
+	///
 	Glfw::Window window{};
 
-	GlfwWsi(Glfw::Window window) : window(window) {}
+	explicit GlfwWsi(Glfw::Window window) : window(window) {}
 
 	std::vector<char const*> extensions() const final;
 	vk::UniqueSurfaceKHR make_surface(vk::Instance instance) const final;

lib/glfw/include/facade/glfw/input.hpp

@@ -1,43 +1,71 @@
 #pragma once
+#include <facade/util/enum_array.hpp>
 #include <glm/vec2.hpp>
 #include <array>
 #include <string_view>
 
 struct GLFWwindow;
 
 namespace facade {
-enum class Action { eNone, ePress, eHeld, eRepeat, eRelease };
-
-inline constexpr std::string_view action_name(Action action) {
-	switch (action) {
-	default:
-	case Action::eNone: return "none";
-	case Action::ePress: return "press";
-	case Action::eHeld: return "held";
-	case Action::eRepeat: return "repeat";
-	case Action::eRelease: return "release";
-	}
-}
+///
+/// \brief Kinds of Key / Button actions.
+///
+enum class Action { eNone, ePress, eHeld, eRepeat, eRelease, eCOUNT_ };
+constexpr auto action_str = EnumArray<Action, std::string_view>{
+	"none", "press", "held", "repeat", "release",
+};
 
+///
+/// \brief Storage for Key (or Button) state.
+/// \param Capacity size of state array
+///
 template <int Capacity>
 class KeyState {
   public:
 	static constexpr int capacity_v{Capacity};
 
+	///
+	/// \brief Obtain the action corresponding to key
+	/// \param key GLFW key / button Id
+	/// \returns Action for key
+	///
 	Action action(int key) const {
 		if (key < 0 || key > capacity_v) { return Action::eNone; }
 		return m_key_actions[static_cast<std::size_t>(key)];
 	}
 
+	///
+	/// \brief Check if a key was pressed.
+	/// \param key GLFW key / button Id
+	/// \returns true If key was pressed
+	///
 	bool pressed(int key) const { return action(key) == Action::ePress; }
+	///
+	/// \brief Check if a key was released.
+	/// \param key GLFW key / button Id
+	/// \returns true If key was released
+	///
 	bool released(int key) const { return action(key) == Action::eRelease; }
+	///
+	/// \brief Check if a key was repeated.
+	/// \param key GLFW key / button Id
+	/// \returns true If key was repeated
+	///
 	bool repeated(int key) const { return action(key) == Action::eRepeat; }
 
+	///
+	/// \brief Check if a key is held.
+	/// \param key GLFW key / button Id
+	/// \returns true If key is held
+	///
 	bool held(int key) const {
 		auto const ret = action(key);
 		return ret == Action::ePress || ret == Action::eHeld || ret == Action::eRepeat;
 	}
 
+	///
+	/// \brief Update actions and swap states.
+	///
 	virtual void next_frame() {
 		auto prev = m_key_actions;
 		m_key_actions = {};
@@ -49,24 +77,61 @@ class KeyState {
 		}
 	}
 
+	///
+	/// \brief Associate action with key.
+	/// \param key GLFW key / button Id
+	/// \param action Action to associate
+	///
 	void on_key(int key, Action action) { m_key_actions[static_cast<std::size_t>(key)] = action; }
 
   private:
 	std::array<Action, static_cast<std::size_t>(capacity_v)> m_key_actions{};
 };
 
+///
+/// \brief Keyboard State
+///
 class Keyboard : public KeyState<512> {};
 
+///
+/// \brief Mouse State
+///
 class Mouse : public KeyState<8> {
   public:
+	///
+	/// \brief Wrapper for on_key.
+	///
 	void on_button(int button, Action action) { on_key(button, action); }
+	///
+	/// \brief Store cursor position.
+	/// \param position Cursor position.
+	///
 	void on_position(glm::vec2 position) { m_position = position; }
-	void on_scroll(glm::vec2 scroll) { m_scroll += scroll; }
-
+	///
+	/// \brief Add scroll delta.
+	/// \param delta Amount scrolled in xy directions
+	///
+	void on_scroll(glm::vec2 delta) { m_scroll += delta; }
+
+	///
+	/// \brief Obtain the cursor position.
+	/// \returns Cursor position
+	///
 	glm::vec2 position() const { return m_position; }
+	///
+	/// \brief Obtain the difference in cursor positions from last state.
+	/// \returns Difference in cursor positions.
+	///
 	glm::vec2 delta_pos() const { return m_position - m_prev_position; }
+	///
+	/// \brief Obtain the amount scrolled.
+	/// \returns Scroll amount
+	///
 	glm::vec2 scroll() const { return m_scroll; }
 
+	///
+	/// \brief Update and swap state.
+	///
 	void next_frame() override {
 		KeyState<8>::next_frame();
 		m_scroll = {};

lib/render/include/facade/render/gui.hpp

@@ -4,6 +4,9 @@
 #include <facade/vk/gfx.hpp>
 
 namespace facade {
+///
+/// \brief Abstract interface for GUI (concrete DearImGui authored and owned by Engine).
+///
 class Gui {
   public:
 	struct InitInfo {
@@ -17,9 +20,6 @@ class Gui {
 	virtual ~Gui() = default;
 
 	virtual void init(InitInfo const& info) = 0;
-
-	virtual void new_frame() = 0;
-	virtual void end_frame() = 0;
 	virtual void render(vk::CommandBuffer cb) = 0;
 };
 } // namespace facade