From dfe9b1abe92e90f88b0aec1d8735893b24078e4d Mon Sep 17 00:00:00 2001 From: Jorijn van der Graaf Date: Sat, 14 Jun 2025 14:58:02 +0200 Subject: [PATCH] improved docs --- Doxyfile | 2 +- src/module/Crafter.Graphics-Camera.cppm | 5 ++- .../Crafter.Graphics-DescriptorSet.cppm | 34 +++++++------- src/module/Crafter.Graphics-Mesh.cppm | 22 +++++---- src/module/Crafter.Graphics-MeshShader.cppm | 26 +++++++++++ .../Crafter.Graphics-TextureShader.cppm | 15 ++++++- src/module/Crafter.Graphics-UiElement.cppm | 6 ++- src/module/Crafter.Graphics-VulkanBuffer.cppm | 27 ++++++++++- src/module/Crafter.Graphics-VulkanDevice.cppm | 20 +++++++++ .../Crafter.Graphics-VulkanPipeline.cppm | 19 +++++++- src/module/Crafter.Graphics-VulkanShader.cppm | 24 ++++++++-- .../Crafter.Graphics-VulkanTexture.cppm | 44 ++++++++++++++++-- src/module/Crafter.Graphics-Window.cppm | 19 ++++++++ .../Crafter.Graphics-WindowWayland.cppm | 18 +++++++- .../Crafter.Graphics-WindowWaylandVulkan.cppm | 45 +++++++++++++++++++ ...Crafter.Graphics-WindowWaylandWayland.cppm | 29 ++++++++++++ 16 files changed, 315 insertions(+), 40 deletions(-) diff --git a/Doxyfile b/Doxyfile index 92db932..2d26b8c 100644 --- a/Doxyfile +++ b/Doxyfile @@ -607,7 +607,7 @@ HIDE_UNDOC_MEMBERS = NO # if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_UNDOC_NAMESPACES tag is set to YES, Doxygen will hide all # undocumented namespaces that are normally visible in the namespace hierarchy. diff --git a/src/module/Crafter.Graphics-Camera.cppm b/src/module/Crafter.Graphics-Camera.cppm index c6dc144..b3fdc57 100644 --- a/src/module/Crafter.Graphics-Camera.cppm +++ b/src/module/Crafter.Graphics-Camera.cppm @@ -28,6 +28,9 @@ import Crafter.Math; import Crafter.Event; namespace Crafter { + /** + * @brief Camera with projection and view matrices. + */ export class Camera { public: MatrixRowMajor projection; @@ -45,7 +48,7 @@ namespace Crafter { Camera(float fov, float aspectRatio, float near, float far); /** - * @brief calculates the projectionView matrix by multiplying the projection and view matricies. + * @brief Calculates the projectionView matrix by multiplying the projection and view matricies. */ void Update(); diff --git a/src/module/Crafter.Graphics-DescriptorSet.cppm b/src/module/Crafter.Graphics-DescriptorSet.cppm index abb25c1..bf570fd 100644 --- a/src/module/Crafter.Graphics-DescriptorSet.cppm +++ b/src/module/Crafter.Graphics-DescriptorSet.cppm @@ -35,22 +35,31 @@ import :WindowWaylandVulkan; import :VulkanPipeline; namespace Crafter { - export struct DescriptorEntry { + struct DescriptorEntry { VkDescriptorType type; bool occured = true; }; /** - * @brief A holder for descriptor sets. + * @brief Holder for VkDescriptorSet. + * + * This class stores 2 VkDescriptorSet one for the first stage and one for the second stage, + * This class has static members to effeciently use a VkDescriptorPool. + * @tparam MeshShader the VulkanShader to use for the first stage. + * @tparam FragmentShader the VulkanShader to use for the second stage. */ export template class DescriptorSet { public: + /** + * @brief [0] refers to the first stage, [1] refers to the second stage. + */ VkDescriptorSet set[2]; /** * @brief This event is triggered when a descriptor is aded to this static set which invalidates all previous descriptors, subscribe to this event to renew them. */ inline static Event onDescriptorRefresh; + private: inline static std::vector sets; inline static VkDescriptorPool descriptorPool = VK_NULL_HANDLE; @@ -131,7 +140,11 @@ namespace Crafter { return types; } - + + public: + /** + * @brief Allocates 2 VkDescriptorSet from the pool, all descriptors previously allocated become invalid. + */ DescriptorSet() { sets.push_back(this); @@ -153,20 +166,11 @@ namespace Crafter { onDescriptorRefresh.Invoke(); } + /** + * @brief Deallocates 2 VkDescriptorSet from the pool. + */ ~DescriptorSet() { sets.erase(find(sets.begin(), sets.end(), this)); } - - // void Write(VkWriteDescriptorSet* descriptors, std::uint32_t count) { - // vkUpdateDescriptorSets(VulkanDevice::device, count, descriptors, 0, nullptr); - // } - // void Write(std::uint32_t stage, VkDescriptorType type, std::uint32_t binding, VkDescriptorBufferInfo* buffer) { - // VkWriteDescriptorSet write = vks::initializers::writeDescriptorSet(set[stage], type, binding, buffer); - // vkUpdateDescriptorSets(VulkanDevice::device, 1, &write, 0, nullptr); - // } - // void Write(std::uint32_t stage, VkDescriptorType type, std::uint32_t binding, VkDescriptorImageInfo* buffer) { - // VkWriteDescriptorSet write = vks::initializers::writeDescriptorSet(set[stage], type, binding, buffer); - // vkUpdateDescriptorSets(VulkanDevice::device, 1, &write, 0, nullptr); - // } }; } \ No newline at end of file diff --git a/src/module/Crafter.Graphics-Mesh.cppm b/src/module/Crafter.Graphics-Mesh.cppm index dcf385f..d0b98ba 100644 --- a/src/module/Crafter.Graphics-Mesh.cppm +++ b/src/module/Crafter.Graphics-Mesh.cppm @@ -31,6 +31,10 @@ import :VulkanBuffer; import :Types; namespace Crafter { + /** + * @brief Holder for a indexed mesh. + * @tparam VertexType The vertex type to use that is internally stored, this must match the type the glsl shader expects. + */ export template class Mesh { public: @@ -49,8 +53,8 @@ namespace Crafter { } /** - * @brief Constructs Mesh from an in memory char buffer - * @param asset pointer to the char buffer + * @brief Constructs Mesh from an in memory char buffer. + * @param asset pointer to the char buffer. */ Mesh(const char* asset) requires(std::same_as) : vertexCount(reinterpret_cast(asset)[0]), indexCount(((reinterpret_cast(asset)[1]) + 63) & ~63), verticies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, vertexCount), indicies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, indexCount) { uint32_t indexCountNoPadding = reinterpret_cast(asset)[1]; @@ -73,8 +77,8 @@ namespace Crafter { /** - * @brief Constructs UV Mesh from an in memory char buffer - * @param asset pointer to the char buffer + * @brief Constructs UV Mesh from an in memory char buffer. + * @param asset pointer to the char buffer. */ Mesh(const char* asset) requires(std::same_as) : vertexCount(reinterpret_cast(asset)[0]), indexCount(((reinterpret_cast(asset)[1]) + 63) & ~63), verticies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, vertexCount), indicies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, indexCount) { uint32_t indexCountNoPadding = reinterpret_cast(asset)[1]; @@ -96,11 +100,11 @@ namespace Crafter { } /** - * @brief Constructs heightmap Mesh from an in memory char buffer - * @param heights pointer to heights - * @param sizeX size in the X dimension - * @param sizeZ size in the Y dimension - * @param spacing spacing between the points + * @brief Constructs heightmap Mesh from an in memory char buffer. + * @param heights pointer to heights. + * @param sizeX size in the X dimension. + * @param sizeZ size in the Y dimension. + * @param spacing spacing between the points . */ Mesh(float* heights, uint32_t sizeX, uint32_t sizeZ, float spacing) : vertexCount(sizeX*sizeZ), indexCount(((((sizeX-1)*(sizeZ-1))*6)+ 63) & ~63), verticies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, vertexCount), indicies(VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, indexCount) { uint32_t indexCountNoPadding = ((sizeX-1)*(sizeZ-1))*6; diff --git a/src/module/Crafter.Graphics-MeshShader.cppm b/src/module/Crafter.Graphics-MeshShader.cppm index be54d53..511cf20 100644 --- a/src/module/Crafter.Graphics-MeshShader.cppm +++ b/src/module/Crafter.Graphics-MeshShader.cppm @@ -35,6 +35,10 @@ import :DescriptorSet; import Crafter.Math; namespace Crafter { + /** + * @brief Shader for rendering indexed meshes + * @tparam VertexType The vertex type to use that is internally stored, this must match the type the glsl shader expects. + */ export template class MeshShader { public: @@ -43,18 +47,40 @@ namespace Crafter { Camera* camera; Buffer> mvp; std::uint32_t threadCount; + private: EventListener cameraUpdate; + public: + /** + * @brief Constructs the MeshShader with a mesh. + * The Model-View-Projection (MVP) matrix and the transform matrix are initialized to the identity matrix. + * + * @param mesh Pointer to the mesh to use. The mesh must remain valid for the lifetime of this object. + */ MeshShader(Mesh* mesh) : threadCount(std::ceil(static_cast(mesh->indexCount)/64/3)), mvp(VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT), mesh(mesh), camera(nullptr) { transform = MatrixRowMajor::Identity(); *mvp.value = MatrixRowMajor::Identity(); } + /** + * @brief Constructs the MeshShader with a mesh. + * The transform is initialized to identity, the transform is initialized to identity and the mvp to the camera's projectionView. + * + * @param mesh Pointer to the mesh to use. The mesh must remain valid for the lifetime of this object. + * @param mesh Pointer to the camera to use. The camera must remain valid for the lifetime of this object. + */ MeshShader(Mesh* mesh, Camera* camera) : threadCount(std::ceil(static_cast(mesh->indexCount)/64/3)), mvp(VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT), mesh(mesh), camera(camera), cameraUpdate( &camera->onUpdate, [this](){ Update(); } ) { transform = MatrixRowMajor::Identity(); + *mvp.value = camera->projectionView; } + /** + * @brief Writes this class's 3 descriptors to the set, this method must be called before rendering with this shader. + * Slot 0 mvp: VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER. + * Slot 1 vertex: VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER. + * Slot 2 index: VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER. + */ void WriteDescriptors(VkDescriptorSet set) { VkWriteDescriptorSet write[3] = { vks::initializers::writeDescriptorSet(set, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 0, &mvp.descriptor), diff --git a/src/module/Crafter.Graphics-TextureShader.cppm b/src/module/Crafter.Graphics-TextureShader.cppm index 212c731..c39938c 100644 --- a/src/module/Crafter.Graphics-TextureShader.cppm +++ b/src/module/Crafter.Graphics-TextureShader.cppm @@ -32,12 +32,21 @@ import :VulkanPipeline; import :DescriptorSet; namespace Crafter { + /** + * @brief Creates a sampler for a provided VulkanTexture. + * @tparam PixelType The pixeltype to use. + */ export template class TextureShader { - public: + private: VkSampler textureSampler; VkDescriptorImageInfo imageInfo; VulkanTexture* texture; + public: + /** + * @brief Creates a sampler for a texture. + * @param texture A pointer to the texture to create the sampler for, the texture must remain valid for the lifetime of this object. + */ TextureShader(VulkanTexture* texture) : texture(texture) { VkSamplerCreateInfo samplerInfo{}; samplerInfo.sType = VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO; @@ -62,6 +71,10 @@ namespace Crafter { imageInfo.imageView = texture->imageView; imageInfo.sampler = textureSampler; } + /** + * @brief Writes this class's 1 descriptor to the set, this method must be called before rendering with this shader. + * Slot 0: VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER. + */ void WriteDescriptors(VkDescriptorSet set) { VkWriteDescriptorSet write = vks::initializers::writeDescriptorSet(set, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 0, &imageInfo); vkUpdateDescriptorSets(VulkanDevice::device, 1, &write, 0, nullptr); diff --git a/src/module/Crafter.Graphics-UiElement.cppm b/src/module/Crafter.Graphics-UiElement.cppm index 4720194..a701c52 100644 --- a/src/module/Crafter.Graphics-UiElement.cppm +++ b/src/module/Crafter.Graphics-UiElement.cppm @@ -28,7 +28,11 @@ import Crafter.Event; import :Types; namespace Crafter { - export class UiElement { + /** + * @brief General use UiElement for handeling input events. + * Add to a window's elements member to start recieving events. + */ + export class UiElement { public: Event onMouseMove; Event onMouseEnter; diff --git a/src/module/Crafter.Graphics-VulkanBuffer.cppm b/src/module/Crafter.Graphics-VulkanBuffer.cppm index 05334f1..12c88ba 100644 --- a/src/module/Crafter.Graphics-VulkanBuffer.cppm +++ b/src/module/Crafter.Graphics-VulkanBuffer.cppm @@ -28,13 +28,31 @@ export module Crafter.Graphics:VulkanBuffer; import :VulkanDevice; namespace Crafter { + /** + * @brief VkBuffer holder. + * Stores a value and handles buffer mapping and lifetime management. + * @tparam T The value to store. + */ export template class Buffer { public: T* value; VkDescriptorBufferInfo descriptor; - VkBuffer buffer = VK_NULL_HANDLE; - VkDeviceMemory memory = VK_NULL_HANDLE; + public: + /** + * @brief Creates and initializes a Vulkan buffer with the specified usage and memory properties. + * + * This constructor allocates a buffer capable of holding `count` elements of type T. + * The buffer usage and memory property flags control how the buffer will be used + * and how its memory is managed. + * + * @param usageFlags Vulkan buffer usage flags that define allowed operations on the buffer + * (e.g., vertex buffer, index buffer, uniform buffer). + * @param memoryPropertyFlags Vulkan memory property flags specifying the desired memory + * properties (e.g., device local, host visible). + * @param count Number of elements to allocate space for in the buffer. The total buffer size + * will be `count * sizeof(T)`. Must be above 0. + */ Buffer(VkBufferUsageFlags usageFlags, VkMemoryPropertyFlags memoryPropertyFlags, std::uint32_t count = 1) { VkBufferCreateInfo bufferCreateInfo = vks::initializers::bufferCreateInfo(usageFlags, sizeof(T)*count); VulkanDevice::CHECK_VK_RESULT(vkCreateBuffer(VulkanDevice::device, &bufferCreateInfo, nullptr, &buffer)); @@ -66,6 +84,9 @@ namespace Crafter { VulkanDevice::CHECK_VK_RESULT(vkBindBufferMemory(VulkanDevice::device, buffer, memory, 0)); VulkanDevice::CHECK_VK_RESULT(vkMapMemory(VulkanDevice::device, memory, 0, sizeof(T)*count, 0, reinterpret_cast(&value))); } + /** + * @brief Frees all resources assosiacted with the buffer. + */ ~Buffer() { vkUnmapMemory(VulkanDevice::device, memory); vkDestroyBuffer(VulkanDevice::device, buffer, nullptr); @@ -75,5 +96,7 @@ namespace Crafter { VkDeviceSize alignment = 0; VkMemoryPropertyFlags memoryPropertyFlags; VkBufferUsageFlags usageFlags; + VkBuffer buffer = VK_NULL_HANDLE; + VkDeviceMemory memory = VK_NULL_HANDLE; }; } diff --git a/src/module/Crafter.Graphics-VulkanDevice.cppm b/src/module/Crafter.Graphics-VulkanDevice.cppm index 1762e92..a3a3b77 100644 --- a/src/module/Crafter.Graphics-VulkanDevice.cppm +++ b/src/module/Crafter.Graphics-VulkanDevice.cppm @@ -46,7 +46,27 @@ export namespace Crafter { * @brief Creates the vulkan device, this must be called before any use of vulkan. */ static void CreateDevice(); + /** + * @brief Checks if result is VK_SUCCESS. + * @param result The VkResult to check. + * @throws std::runtime_error If result != VK_SUCCESS. + */ static void CHECK_VK_RESULT(VkResult result); + /** + * @brief Finds a suitable memory type index for the device based on required properties. + * + * This function searches through the memory types supported by the physical device to find + * a memory type index that matches the specified bitmask and has the requested property flags. + * + * @param typeBits A bitmask representing the memory types that are suitable. Each bit corresponds + * to a memory type index; if the bit is set, that memory type is considered. + * @param properties A bitmask of VkMemoryPropertyFlags specifying the desired memory properties, + * such as device local, host visible, etc. + * + * @return The index of a suitable memory type that fulfills the requirements. + * + * @throws std::runtime_error If no suitable memory type is found matching the criteria. + */ static std::uint32_t GetMemoryType(std::uint32_t typeBits, VkMemoryPropertyFlags properties); }; } \ No newline at end of file diff --git a/src/module/Crafter.Graphics-VulkanPipeline.cppm b/src/module/Crafter.Graphics-VulkanPipeline.cppm index 7fb55a9..16fdf28 100644 --- a/src/module/Crafter.Graphics-VulkanPipeline.cppm +++ b/src/module/Crafter.Graphics-VulkanPipeline.cppm @@ -32,9 +32,25 @@ import :VulkanShader; import :WindowWaylandVulkan; namespace Crafter { + export template class DescriptorSet; + /** + * @brief A generic Vulkan graphics pipeline wrapper using template-based shaders. + * + * This class encapsulates the creation and management of a Vulkan graphics pipeline + * with a specified mesh shader and fragment shader. It provides static members for + * the pipeline, pipeline layout, and descriptor set layouts, which are shared across + * all instances of this template specialization. + * + * @tparam MeshShader The mesh shader type used in the pipeline. + * @tparam FragmentShader The fragment shader type used in the pipeline. + * + * @note Before using this pipeline, the CreatePipeline() function must be called, + * and all shader modules specified by the template parameters must be created. + */ export template class VulkanPipeline { private: + friend class DescriptorSet; template consteval static std::array GetDescriptorSet() { std::array set; @@ -45,11 +61,10 @@ namespace Crafter { return set; } + inline static VkDescriptorSetLayout descriptorSetLayout[2]; public: inline static VkPipeline pipeline; inline static VkPipelineLayout pipelineLayout; - inline static VkDescriptorSetLayout descriptorSetLayout[2]; - /** * @brief Creates the vulkan pipeline, this must be called before any use of this pipeline and all shaders must be created before this pipeline is created. diff --git a/src/module/Crafter.Graphics-VulkanShader.cppm b/src/module/Crafter.Graphics-VulkanShader.cppm index 06c6ecd..b2090fc 100644 --- a/src/module/Crafter.Graphics-VulkanShader.cppm +++ b/src/module/Crafter.Graphics-VulkanShader.cppm @@ -46,6 +46,22 @@ namespace Crafter { std::uint32_t slot; }; + /** + * @brief Represents a Vulkan shader module with specified configuration. + * + * This class template encapsulates a Vulkan shader, parametrized by the shader's + * source path, entry point, shader stage, and its descriptor bindings. + * + * @tparam path A compile-time string literal specifying the file path to the shader source or binary. + * @tparam entrypoint A compile-time string literal specifying the entry point function name within the shader. + * @tparam stage The Vulkan shader stage flag indicating the shader type (e.g., vertex, fragment). + * @tparam DescriptorCount The number of descriptor bindings used by the shader. + * @tparam Descriptors An array of descriptor binding configurations used by the shader. + * + * This class facilitates compile-time specification of shader resources and metadata, + * allowing for type-safe shader management and potentially more efficient shader pipeline creation. + * CreateShader must be called before using this shader in a pipeline. + */ export template < StringLiteral path, StringLiteral entrypoint, @@ -55,11 +71,11 @@ namespace Crafter { > class VulkanShader { public: - inline static VkShaderModule shader; - constexpr static std::uint32_t descriptorCount = DescriptorCount; - constexpr static std::array descriptors = Descriptors; - constexpr static StringLiteral _entrypoint = entrypoint; constexpr static VkShaderStageFlagBits _stage = stage; + constexpr static std::array descriptors = Descriptors; + constexpr static std::uint32_t descriptorCount = DescriptorCount; + constexpr static StringLiteral _entrypoint = entrypoint; + inline static VkShaderModule shader; /** * @brief Creates the vulkan shader, this must be called before any use of this shader. */ diff --git a/src/module/Crafter.Graphics-VulkanTexture.cppm b/src/module/Crafter.Graphics-VulkanTexture.cppm index 9717865..96fcc03 100644 --- a/src/module/Crafter.Graphics-VulkanTexture.cppm +++ b/src/module/Crafter.Graphics-VulkanTexture.cppm @@ -31,15 +31,37 @@ import :VulkanBuffer; namespace Crafter { + /** + * @brief Represents a Vulkan texture with pixel data of a specified type. + * + * This class manages a Vulkan image resource along with its associated memory, + * buffer, and image view. It provides functionality to create textures either + * by specifying dimensions or loading from an asset, and to update the texture + * data on the GPU using command buffers. + * + * @tparam PixelType The type of the pixel data stored in the texture. + */ export template class VulkanTexture { public: uint32_t width; uint32_t height; + private: VkImage image; VkDeviceMemory imageMemory; Buffer buffer; VkImageView imageView; + public: + /** + * @brief Constructs a VulkanTexture with the given dimensions. + * + * Creates a Vulkan texture image with the specified width and height, + * initializing necessary resources. + * + * @param width The width of the texture. + * @param height The height of the texture. + * @param cmd Vulkan command buffer used for resource initialization. + */ VulkanTexture(std::uint32_t width, std::uint32_t height, VkCommandBuffer cmd) : width(width), height(height), buffer(VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, width*height) { VkImageCreateInfo imageInfo{}; imageInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO; @@ -84,11 +106,27 @@ namespace Crafter { TransitionImageLayout(cmd, buffer, image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL); } - + /** + * @brief Constructs a VulkanTexture by loading from an in memory asset. + * + * Loads texture pixel data from the specified asset and initializes + * the Vulkan image resource accordingly. + * + * @param asset Pointer to the in memory asset. + * @param cmd Vulkan command buffer used for resource initialization. + */ VulkanTexture(const char* asset, VkCommandBuffer cmd) : VulkanTexture(reinterpret_cast(asset)[0], reinterpret_cast(asset)[1], cmd) { Update(reinterpret_cast(reinterpret_cast(asset)+2), cmd); } - + /** + * @brief Updates the texture with new pixel data. + * + * Copies the given pixel data into the texture's buffer and issues Vulkan + * commands to upload the data to the GPU image. + * + * @param bufferdata Pointer to the new pixel data. + * @param cmd Vulkan command buffer used for the update operation. + */ void Update(const PixelType* bufferdata, VkCommandBuffer cmd) { memcpy(buffer.value, bufferdata, height*width*sizeof(PixelType)); TransitionImageLayout(cmd, buffer, image, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL); @@ -173,4 +211,4 @@ namespace Crafter { ); } }; -} +} \ No newline at end of file diff --git a/src/module/Crafter.Graphics-Window.cppm b/src/module/Crafter.Graphics-Window.cppm index 1c3f32b..6ecf3a8 100644 --- a/src/module/Crafter.Graphics-Window.cppm +++ b/src/module/Crafter.Graphics-Window.cppm @@ -37,6 +37,13 @@ export namespace Crafter { int32_t height; }; + /** + * @brief Represents a GUI window handling input events, mouse states, keyboard states, and UI elements. + * + * The Window class encapsulates event handling for mouse and keyboard interactions, + * manages the state of the mouse and keyboard, and stores UI elements contained within the window. + * It also holds window-specific properties such as name, dimensions, and scaling factor. + */ class Window { public: Event onMouseRightClick; @@ -68,7 +75,19 @@ export namespace Crafter { std::uint32_t height; float scale = 1; bool open = true; + /** + * @brief Constructs a Window with a given name and dimensions. + * @param name The title of the window. + * @param width The width of the window in pixels. + * @param height The height of the window in pixels. + */ Window(std::string name, std::uint32_t width, std::uint32_t height); + /** + * @brief Calculates the real position and size of an UiElement + * + * @param element The UI element to get the position from. + * @return The actual position and size of the element after scaling. + */ ScaleData ScaleElement(const UiElement& element); }; } \ No newline at end of file diff --git a/src/module/Crafter.Graphics-WindowWayland.cppm b/src/module/Crafter.Graphics-WindowWayland.cppm index 21d0622..4f81b7f 100644 --- a/src/module/Crafter.Graphics-WindowWayland.cppm +++ b/src/module/Crafter.Graphics-WindowWayland.cppm @@ -33,10 +33,26 @@ import :Types; import :Window; export namespace Crafter { + /** + * @class WindowWayland + * @brief A window using the Wayland display server protocol. + * + * This class inherits from the base Window class and provides + * functionality specific to Wayland for creating and managing + * windows. + */ class WindowWayland : public Window { public: - Pixel_BU8_GU8_RU8_AU8* framebuffer = NULL; + /** + * @brief Constructs a Wayland window with a given name and size. + * @param name The title for the window. + * @param width The width of the window in pixels. + * @param height The height of the window in pixels. + */ WindowWayland(std::string name, std::uint32_t width, std::uint32_t height); + /** + * @brief Destructor cleans up Wayland-specific window resources. + */ ~WindowWayland(); protected: bool configured = false; diff --git a/src/module/Crafter.Graphics-WindowWaylandVulkan.cppm b/src/module/Crafter.Graphics-WindowWaylandVulkan.cppm index efbbd85..3c44f11 100644 --- a/src/module/Crafter.Graphics-WindowWaylandVulkan.cppm +++ b/src/module/Crafter.Graphics-WindowWaylandVulkan.cppm @@ -45,14 +45,59 @@ namespace Crafter { VkSemaphore renderComplete; }; + /** + * @class WindowWaylandVulkan + * @brief A Wayland window specialized for Vulkan rendering. + * + * This class extends the WindowWayland base class to support Vulkan graphics + * integration within a Wayland environment. It provides methods for initializing + * Vulkan command buffers and managing drawing operations either synchronously or asynchronously. + * + * The class exposes an event `onDraw` which is called for every frame. + * @pre VulkanDevice::CreateDevice() must be called before creating or using this class. + */ export class WindowWaylandVulkan : public WindowWayland { public: Event onDraw; + /** + * @brief Constructs a WindowWaylandVulkan instance. + * + * @param name The title of the window. + * @param width The width of the window in pixels. + * @param height The height of the window in pixels. + */ WindowWaylandVulkan(std::string name, std::uint32_t width, std::uint32_t height); + /** + * @brief Destructor for the WindowWaylandVulkan. + * + * Cleans up Vulkan and Wayland resources associated with this window. + */ ~WindowWaylandVulkan(); + /** + * @brief Starts Vulkan initialization and returns a command buffer. + * + * This command buffer can be used to record Vulkan setup commands. + * + * @return VkCommandBuffer A Vulkan command buffer for recording initialization commands. + */ VkCommandBuffer StartInit(); + /** + * @brief Completes Vulkan initialization. + * + * Finalizes any remaining setup required after recording commands returned by StartInit(). + */ void FinishInit(); + /** + * @brief Starts the event loop asynchronously. + * + * This method triggers rendering without blocking the caller. + */ void StartAsync(); + /** + * @brief Starts the event loop synchronously. + * + * This method blocks the caller until the event loop stops. + */ void StartSync(); private: void CreateSwapchain(); diff --git a/src/module/Crafter.Graphics-WindowWaylandWayland.cppm b/src/module/Crafter.Graphics-WindowWaylandWayland.cppm index 23e4e76..77f4a42 100644 --- a/src/module/Crafter.Graphics-WindowWaylandWayland.cppm +++ b/src/module/Crafter.Graphics-WindowWaylandWayland.cppm @@ -29,11 +29,40 @@ import Crafter.Event; import :WindowWayland; export namespace Crafter { + /** + * @brief A specialized Wayland window implementation for direct drawing. + * + * This class inherits from `WindowWayland` and provides a framebuffer using the pixel format `Pixel_BU8_GU8_RU8_AU8`. + */ class WindowWaylandWayland : public WindowWayland { public: + /** + * @brief Framebuffer for the window using the BGRA 8-bit unsigned pixel format, use this for direct drawing to the window. + */ + Pixel_BU8_GU8_RU8_AU8* framebuffer = NULL; + /** + * @brief Constructs a new WindowWaylandWayland object. + * + * @param name The title of the window. + * @param width The width of the window in pixels. + * @param height The height of the window in pixels. + */ WindowWaylandWayland(std::string name, std::uint32_t width, std::uint32_t height); + /** + * @brief Destructor cleans up Wayland-specific window resources and framebuffer. + */ ~WindowWaylandWayland(); + /** + * @brief Starts the event loop asynchronously. + * + * This method triggers rendering without blocking the caller. + */ void StartAsync(); + /** + * @brief Starts the event loop synchronously. + * + * This method blocks the caller until the event loop stops. + */ void StartSync(); private: std::thread thread;