From 368ed5a1a8066a08b59e93268c909b66c0163afb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diogo=20Mendon=C3=A7a?= Date: Thu, 12 Oct 2023 10:27:11 +0100 Subject: [PATCH] docs(engine): document Gizmos plugin --- engine/include/cubos/engine/gizmos/gizmos.hpp | 48 +++++++++++-- engine/src/cubos/engine/gizmos/gizmos.cpp | 72 ++++++++++--------- 2 files changed, 79 insertions(+), 41 deletions(-) diff --git a/engine/include/cubos/engine/gizmos/gizmos.hpp b/engine/include/cubos/engine/gizmos/gizmos.hpp index aec6b06c1f..a264530992 100644 --- a/engine/include/cubos/engine/gizmos/gizmos.hpp +++ b/engine/include/cubos/engine/gizmos/gizmos.hpp @@ -1,3 +1,7 @@ +/// @file +/// @brief Resource @ref cubos::engine::Gizmos. +/// @ingroup gizmos-plugin + #pragma once #include @@ -13,26 +17,56 @@ using cubos::engine::DeltaTime; namespace cubos::engine { + /// @brief Resource which draws gizmos. + /// + /// @ingroup gizmos-plugin class Gizmos final { public: + /// @brief Initiates the Gizmos resource. + /// @param renderDevice Active render device. void init(RenderDevice& renderDevice); + /// @brief Sets the color to be used when drawing any subsequent gizmos. + /// @param color Color to be used. void color(const glm::vec3& color); - void drawLine(std::string id, glm::vec3 from, glm::vec3 to, float lifespan = 0); - void drawBox(std::string id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan = 0); - void drawWireBox(std::string id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan = 0); + /// @brief Draws a line gizmo. + /// @param id Identifier of the gizmo. + /// @param from One of the ends of the line to be drawn. + /// @param to The other end of the line to be drawn. + /// @param lifespan How long the line will be on screen for, in seconds. Defaults to 0, which means a single + /// frame. + void drawLine(const std::string& id, glm::vec3 from, glm::vec3 to, float lifespan = 0); + + /// @brief Draws a filled box gizmo. + /// @param id Identifier of the gizmo. + /// @param corner One of the corners of the box to be drawn. + /// @param oppositeCorner The opposite corner of the box to be drawn. + /// @param lifespan How long the line will be on screen for, in seconds. Defaults to 0, which means a single + /// frame. + void drawBox(const std::string& id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan = 0); + + /// @brief Draws a wireframe box gizmo. + /// @param id Identifier of the gizmo. + /// @param corner One of the corners of the box to be drawn. + /// @param oppositeCorner The opposite corner of the box to be drawn. + /// @param lifespan How long the line will be on screen for, in seconds. Defaults to 0, which means a single + /// frame. + void drawWireBox(const std::string& id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan = 0); + + /// @brief Draws all the gizmos that were called to be drawn. + /// @param deltaTime Resource holding the time since the previous frame. void drawQueuedGizmos(DeltaTime deltaTime); private: - ShaderPipeline mPipeline; - RenderDevice* mRenderDevice; - glm::vec3 mColor; + ShaderPipeline mPipeline; ///< Shader pipeline to be used when drawing gizmos + RenderDevice* mRenderDevice; ///< Active render device + glm::vec3 mColor; ///< Currently set color class GizmoBase; class LineGizmo; class BoxGizmo; - std::vector> mGizmosVector; + std::vector> mGizmosVector; ///< Queued gizmos to be drawn. }; } // namespace cubos::engine diff --git a/engine/src/cubos/engine/gizmos/gizmos.cpp b/engine/src/cubos/engine/gizmos/gizmos.cpp index a5a24242bd..723a870477 100644 --- a/engine/src/cubos/engine/gizmos/gizmos.cpp +++ b/engine/src/cubos/engine/gizmos/gizmos.cpp @@ -18,15 +18,16 @@ using cubos::core::gl::VertexArrayDesc; using cubos::engine::DeltaTime; using cubos::engine::Gizmos; +/// @brief A gizmo to be drawn class Gizmos::GizmoBase { protected: const std::string& mId; glm::vec3 mColor; float mLifespan; - VertexArray va; - IndexBuffer ib; - VertexArrayDesc vaDesc; + VertexArray mVa; + IndexBuffer mIb; + VertexArrayDesc mVaDesc; public: GizmoBase(const std::string& id, glm::vec3 color, float lifespan) @@ -47,6 +48,7 @@ class Gizmos::GizmoBase virtual ~GizmoBase() = default; }; +/// @brief A line gizmo to be drawn class Gizmos::LineGizmo : public Gizmos::GizmoBase { public: @@ -56,19 +58,19 @@ class Gizmos::LineGizmo : public Gizmos::GizmoBase , mPointA(from) , mPointB(to) { - vaDesc.elementCount = 1; - vaDesc.elements[0].name = "position"; - vaDesc.elements[0].type = Type::Float; - vaDesc.elements[0].size = 3; - vaDesc.elements[0].buffer.index = 0; - vaDesc.elements[0].buffer.offset = 0; - vaDesc.elements[0].buffer.stride = 3 * sizeof(float); - vaDesc.shaderPipeline = shaderPipeline; + mVaDesc.elementCount = 1; + mVaDesc.elements[0].name = "position"; + mVaDesc.elements[0].type = Type::Float; + mVaDesc.elements[0].size = 3; + mVaDesc.elements[0].buffer.index = 0; + mVaDesc.elements[0].buffer.offset = 0; + mVaDesc.elements[0].buffer.stride = 3 * sizeof(float); + mVaDesc.shaderPipeline = shaderPipeline; float verts[] = {mPointA[0], mPointA[1], mPointA[2], mPointB[0], mPointB[1], mPointB[2]}; renderDevice.setShaderPipeline(shaderPipeline); - vaDesc.buffers[0] = renderDevice.createVertexBuffer(sizeof(verts), verts, Usage::Static); - va = renderDevice.createVertexArray(vaDesc); + mVaDesc.buffers[0] = renderDevice.createVertexBuffer(sizeof(verts), verts, Usage::Static); + mVa = renderDevice.createVertexArray(mVaDesc); } void draw(RenderDevice& renderDevice, const ShaderPipeline& shaderPipeline) override; @@ -76,6 +78,8 @@ class Gizmos::LineGizmo : public Gizmos::GizmoBase glm::vec3 mPointA; glm::vec3 mPointB; }; + +/// @brief A box gizmo to be drawn class Gizmos::BoxGizmo : public Gizmos::GizmoBase { public: @@ -85,22 +89,22 @@ class Gizmos::BoxGizmo : public Gizmos::GizmoBase , mPointA(corner) , mPointB(oppositeCorner) { - vaDesc.elementCount = 1; - vaDesc.elements[0].name = "position"; - vaDesc.elements[0].type = Type::Float; - vaDesc.elements[0].size = 3; - vaDesc.elements[0].buffer.index = 0; - vaDesc.elements[0].buffer.offset = 0; - vaDesc.elements[0].buffer.stride = 3 * sizeof(float); - vaDesc.shaderPipeline = shaderPipeline; + mVaDesc.elementCount = 1; + mVaDesc.elements[0].name = "position"; + mVaDesc.elements[0].type = Type::Float; + mVaDesc.elements[0].size = 3; + mVaDesc.elements[0].buffer.index = 0; + mVaDesc.elements[0].buffer.offset = 0; + mVaDesc.elements[0].buffer.stride = 3 * sizeof(float); + mVaDesc.shaderPipeline = shaderPipeline; float verts[] = {mPointA[0], mPointA[1], mPointA[2], mPointB[0], mPointA[1], mPointA[2], mPointB[0], mPointA[1], mPointB[2], mPointA[0], mPointA[1], mPointB[2], mPointA[0], mPointB[1], mPointB[2], mPointA[0], mPointB[1], mPointA[2], mPointB[0], mPointB[1], mPointA[2], mPointB[0], mPointB[1], mPointB[2]}; renderDevice.setShaderPipeline(shaderPipeline); - vaDesc.buffers[0] = renderDevice.createVertexBuffer(sizeof(verts), verts, Usage::Static); - va = renderDevice.createVertexArray(vaDesc); + mVaDesc.buffers[0] = renderDevice.createVertexBuffer(sizeof(verts), verts, Usage::Static); + mVa = renderDevice.createVertexArray(mVaDesc); unsigned int indices[] = {// front 0, 6, 1, 0, 5, 6, @@ -114,7 +118,7 @@ class Gizmos::BoxGizmo : public Gizmos::GizmoBase 3, 1, 2, 3, 0, 1, // top 5, 7, 6, 5, 4, 7}; - ib = renderDevice.createIndexBuffer(sizeof(indices), indices, IndexFormat::UInt, Usage::Static); + mIb = renderDevice.createIndexBuffer(sizeof(indices), indices, IndexFormat::UInt, Usage::Static); } void draw(RenderDevice& renderDevice, const ShaderPipeline& shaderPipeline) override; @@ -163,18 +167,18 @@ void Gizmos::color(const glm::vec3& color) mColor = color; } -void Gizmos::drawLine(std::string id, glm::vec3 from, glm::vec3 to, float lifespan) +void Gizmos::drawLine(const std::string& id, glm::vec3 from, glm::vec3 to, float lifespan) { mGizmosVector.push_back(std::make_shared(id, from, to, mColor, lifespan, *mRenderDevice, mPipeline)); } -void Gizmos::drawBox(std::string id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan) +void Gizmos::drawBox(const std::string& id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan) { mGizmosVector.push_back( std::make_shared(id, corner, oppositeCorner, mColor, lifespan, *mRenderDevice, mPipeline)); } -void Gizmos::drawWireBox(std::string id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan) +void Gizmos::drawWireBox(const std::string& id, glm::vec3 corner, glm::vec3 oppositeCorner, float lifespan) { // Front mGizmosVector.push_back(std::make_shared(id, corner, glm::vec3{oppositeCorner[0], corner[1], corner[2]}, @@ -238,10 +242,10 @@ void Gizmos::drawQueuedGizmos(DeltaTime deltaTime) void Gizmos::LineGizmo::draw(RenderDevice& renderDevice, const ShaderPipeline& shaderPipeline) { - renderDevice.setVertexArray(va); + renderDevice.setVertexArray(mVa); - auto v = glm::translate(glm::mat4(1.0f), glm::vec3(-1.0f, -1.0f, 0.0f)); - auto p = glm::ortho(-0.5f, 0.5f, -0.5f, 0.5f); + auto v = glm::translate(glm::mat4(1.0F), glm::vec3(-1.0F, -1.0F, 0.0F)); + auto p = glm::ortho(-0.5F, 0.5F, -0.5F, 0.5F); auto vp = v * p; auto mvpBuffer = renderDevice.createConstantBuffer(sizeof(glm::mat4), &vp, Usage::Static); shaderPipeline->getBindingPoint("MVP")->bind(mvpBuffer); @@ -253,11 +257,11 @@ void Gizmos::LineGizmo::draw(RenderDevice& renderDevice, const ShaderPipeline& s void Gizmos::BoxGizmo::draw(RenderDevice& renderDevice, const ShaderPipeline& shaderPipeline) { - renderDevice.setVertexArray(va); - renderDevice.setIndexBuffer(ib); + renderDevice.setVertexArray(mVa); + renderDevice.setIndexBuffer(mIb); - auto v = glm::translate(glm::mat4(1.0f), glm::vec3(-1.0f, -1.0f, 0.0f)); - auto p = glm::ortho(-0.5f, 0.5f, -0.5f, 0.5f); + auto v = glm::translate(glm::mat4(1.0F), glm::vec3(-1.0F, -1.0F, 0.0F)); + auto p = glm::ortho(-0.5F, 0.5F, -0.5F, 0.5F); auto vp = v * p; auto mvpBuffer = renderDevice.createConstantBuffer(sizeof(glm::mat4), &vp, Usage::Static); shaderPipeline->getBindingPoint("MVP")->bind(mvpBuffer);