Specifying viewports and scissors to graphics pipeline creation

Also added functions to get extent from swapchains, in both
core (TL) and Vulkan (TLVK) contexts.

README.md

@@ -1,5 +1,5 @@
 <p align=center>
-    <img align=left src="res/img/render.png" height=110>
+    <img align=left src="res/logo/render.png" height=110>
 </p>
 
 

docs/pages/api/core/_core.rst

@@ -8,9 +8,10 @@ Objects and functions defined within the core Thallium library, exposed by ``tha
     :caption: Contents
 
     context
+    data
     debuggers
     pipelines
-    primitive_data
     renderers
     swapchains
+    viewports
     wsi

docs/pages/api/core/data.rst

@@ -0,0 +1,18 @@
+General Datatypes
+=================
+
+This section includes primitive struct definitions for general, standard data representation.
+
+
+*****
+
+
+Types
+-----
+
+
+Structs
+^^^^^^^
+
+.. doxygenstruct:: TL_Version_t
+    :members:

docs/pages/api/core/viewports.rst

@@ -0,0 +1,27 @@
+Viewport and Scissor Geometry
+=============================
+
+This section specifies primitive struct definitions to represent viewport and scissor properties.
+
+
+*****
+
+
+Types
+-----
+
+
+Structs
+^^^^^^^
+
+.. doxygenstruct:: TL_Viewport_t
+    :members:
+
+.. doxygenstruct:: TL_Extent2D_t
+    :members:
+
+.. doxygenstruct:: TL_Offset2D_t
+    :members:
+
+.. doxygenstruct:: TL_Rect2D_t
+    :members:

include/thallium.h

@@ -22,6 +22,7 @@
 #include "thallium/core/renderer.h"
 #include "thallium/core/swapchain.h"
 #include "thallium/core/version.h"
+#include "thallium/core/viewport.h"
 
 #include "thallium/core/wsi/window_surface.h"
 #if defined(_THALLIUM_WSI_COCOA)

include/thallium/core/pipeline.h

@@ -91,6 +91,20 @@ typedef struct TL_PipelineDescriptor_t {
     /// @brief A [descriptor](@ref TL_PipelineDepthTestDescriptor_t) of the depth-testing stage of the pipeline.
     /// This value is ignored in compute and ray tracing pipelines.
     TL_PipelineDepthTestDescriptor_t depth_test;
+
+    /// @brief The amount of viewports in the `viewports` array; ignored if `viewports` is NULL.
+    /// This value is ignored in compute and ray tracing pipelines.
+    uint32_t viewport_count;
+    /// @brief NULL or an array of viewports - if NULL, any viewports must be set dynamically instead.
+    /// This value is ignored in compute and ray tracing pipelines.
+    TL_Viewport_t *viewports;
+
+    /// @brief The amount of viewports in the `viewports` array; ignored if `viewports` is NULL.
+    /// This value is ignored in compute and ray tracing pipelines.
+    uint32_t scissor_count;
+    /// @brief NULL or an array of scissor rectangles - if NULL, any scissors must be set dynamically instead.
+    /// This value is ignored in compute and ray tracing pipelines.
+    TL_Rect2D_t *scissors;
 } TL_PipelineDescriptor_t;
 
 /**

include/thallium/core/swapchain.h

@@ -15,7 +15,7 @@
 #include "thallium_decl/fwd.h"
 #include "thallium/platform.h"
 
-#include "thallium/core/extent.h"
+#include "thallium/core/viewport.h"
 
 /**
  * @brief A structure to represent a graphical swapchain.
@@ -75,6 +75,18 @@ void TL_SwapchainDestroy(
     TL_Swapchain_t *const swapchain
 );
 
+/**
+ * @brief Retrieve the extent of the given swapchain.
+ *
+ * This function returns the extent of the specified swapchain object.
+ *
+ * @param swapchain Swapchain pointer
+ * @return Swapchain extent
+ */
+TL_Extent2D_t TL_SwapchainGetExtent(
+    TL_Swapchain_t *const swapchain
+);
+
 #ifdef __cplusplus
     }
 #endif // __cplusplus

include/thallium/core/viewport.h

@@ -0,0 +1,76 @@
+/*
+ *   Copyright (c) 2023 Jack Bennett.
+ *   All Rights Reserved.
+ *
+ *   See the LICENCE file for more information.
+ */
+
+#pragma once
+#ifndef __TL__core__viewport_h__
+#define __TL__core__viewport_h__
+#ifdef __cplusplus
+    extern "C" {
+#endif // __cplusplus
+
+#include "thallium/platform.h"
+
+/**
+ * @brief A structure defining a viewport
+ *
+ * This structure contains floating-point data for viewport position (of the top-left corner), size, and depth range.
+ */
+typedef struct TL_Viewport_t {
+    /// @brief X position of the viewport's top-left corner
+    float x;
+    /// @brief Y position of the viewport's top-left corner
+    float y;
+    /// @brief Width of the viewport
+    float width;
+    /// @brief Height of the viewport
+    float height;
+    /// @brief Minimum depth of the viewport
+    float min_depth;
+    /// @brief Maximum depth of the viewport
+    float max_depth;
+} TL_Viewport_t;
+
+/**
+ * @brief 2-dimensional extent structure
+ *
+ * This 2-dimensional extent struct is used for unsigned integral 2D extents.
+ */
+typedef struct TL_Extent2D_t {
+    /// @brief Extent width
+    uint32_t width;
+    /// @brief Extent height
+    uint32_t height;
+} TL_Extent2D_t;
+
+/**
+ * @brief 2-dimensional offset (position) structure
+ *
+ * This 2-dimensional offset struct contains signed integral 2D position values.
+ */
+typedef struct TL_Offset2D_t {
+    /// @brief X offset
+    int32_t x;
+    /// @brief Y offset
+    int32_t y;
+} TL_Offset2D_t;
+
+/**
+ * @brief 2-dimensional structure with unsigned extent and signed offset data.
+ *
+ * This 2-dimensional struct contains an unsigned extent and a signed offset.
+ */
+typedef struct TL_Rect2D_t {
+    /// @brief Offset (position)
+    TL_Offset2D_t offset;
+    /// @brief Extent (size)
+    TL_Extent2D_t extent;
+} TL_Rect2D_t;
+
+#ifdef __cplusplus
+    }
+#endif // __cplusplus
+#endif

include/thallium/vulkan/vk_swapchain_system.h

@@ -12,6 +12,8 @@
     extern "C" {
 #endif // __cplusplus
 
+#include "thallium/core/viewport.h"
+
 #include "thallium_decl/fwd.h"
 #include "thallium_decl/fwdvk.h"
 #include "thallium/platform.h"
@@ -37,6 +39,11 @@ typedef struct TLVK_SwapchainSystem_t TLVK_SwapchainSystem_t;
  * This descriptor structure provides options for the creation of Vulkan swapchains via Thallium Vulkan swapchain systems.
  */
 typedef struct TLVK_SwapchainSystemDescriptor_t {
+    /// @brief Resolution of images in the swapchain. Both values must be above 0 in this struct. If you are specifying this descriptor as an add-on
+    /// to a @ref TL_SwapchainDescriptor_t (i.e. calling @ref TL_SwapchainCreate()), then setting this will override the resolution specified to that
+    /// descriptor - keeping this zero-initialised will use the resolution specified to that descriptor.
+    TL_Extent2D_t resolution;
+
     /// @brief NULL or a Vulkan surface to use in swapchain creation.
     /// If this is NULL, a surface will be created based on the specified Thallium **window surface** (i.e. platform window handles). Otherwise, that
     /// window will be disregarded and this surface will be directly used instead.
@@ -65,7 +72,6 @@ typedef struct TLVK_SwapchainSystemDescriptor_t {
  * parameter **must** be a valid Thallium window surface object, in which case a new Vulkan surface will be created and stored by the swapchain.
  *
  * @param renderer_system a valid Thallium Vulkan renderer system object
- * @param resolution resolution of images in the swapchain
  * @param descriptor a Thallium Vulkan swapchain system descriptor
  * @param window_surface a Thallium window surface object <i>(can conditionally be NULL - see note above)</i>
  * @return The new swapchain system
@@ -76,7 +82,6 @@ typedef struct TLVK_SwapchainSystemDescriptor_t {
  */
 TLVK_SwapchainSystem_t *TLVK_SwapchainSystemCreate(
     const TLVK_RendererSystem_t *const renderer_system,
-    const TL_Extent2D_t resolution,
     const TLVK_SwapchainSystemDescriptor_t descriptor,
     const TL_WindowSurface_t *const window_surface
 );
@@ -95,6 +100,18 @@ void TLVK_SwapchainSystemDestroy(
     TLVK_SwapchainSystem_t *const swapchain_system
 );
 
+/**
+ * @brief Retrieve the extent of the given Vulkan swapchain system.
+ *
+ * This function returns the extent of the specified Vulkan swapchain system.
+ *
+ * @param swapchain_system Swapchain system pointer
+ * @return Swapchain system extent
+ */
+TL_Extent2D_t TLVK_SwapchainSystemGetExtent(
+    TLVK_SwapchainSystem_t *const swapchain_system
+);
+
 #ifdef __cplusplus
     }
 #endif // __cplusplus

include/thallium_decl/fwd.h

@@ -12,15 +12,15 @@
     extern "C" {
 #endif // __cplusplus
 
+typedef struct TL_WindowSurface_t TL_WindowSurface_t;
+
 typedef struct TL_Context_t TL_Context_t;
 typedef struct TL_ContextDescriptor_t TL_ContextDescriptor_t;
 
 typedef struct TL_Debugger_t TL_Debugger_t;
 typedef struct TL_DebuggerDescriptor_t TL_DebuggerDescriptor_t;
 typedef struct TL_DebuggerAttachmentDescriptor_t TL_DebuggerAttachmentDescriptor_t;
 
-typedef struct TL_Extent2D_t TL_Extent2D_t;
-
 typedef struct TL_Pipeline_t TL_Pipeline_t;
 typedef struct TL_PipelineDescriptor_t TL_PipelineDescriptor_t;
 typedef struct TL_PipelineDepthTestDescriptor_t TL_PipelineDepthTestDescriptor_t;
@@ -35,7 +35,10 @@ typedef struct TL_SwapchainDescriptor_t TL_SwapchainDescriptor_t;
 
 typedef struct TL_Version_t TL_Version_t;
 
-typedef struct TL_WindowSurface_t TL_WindowSurface_t;
+typedef struct TL_Viewport_t TL_Viewport_t;
+typedef struct TL_Extent2D_t TL_Extent2D_t;
+typedef struct TL_Offset2D_t TL_Offset2D_t;
+typedef struct TL_Rect2D_t TL_Rect2D_t;
 
 #ifdef __cplusplus
     }

src/lib/core/swapchain.c

@@ -52,9 +52,16 @@ TL_Swapchain_t *TL_SwapchainCreate(const TL_Renderer_t *const renderer, const TL
 
                 if (descriptor.swapchain_system_descriptor) {
                     ssdescr = *((TLVK_SwapchainSystemDescriptor_t *) descriptor.swapchain_system_descriptor);
+
+                    // fallback to descriptor.resolution
+                    if (ssdescr.resolution.width <= 0 || ssdescr.resolution.height <= 0) {
+                        ssdescr.resolution = descriptor.resolution;
+                    }
                 } else {
                     // default swapchain system descriptor configuration (used if no user-given descriptor was specified)...
 
+                    ssdescr.resolution = descriptor.resolution;
+
                     ssdescr.vk_surface = NULL; // create a surface for descriptor.window_surface (passed to TLVK_SwapchainSystemCreate call).
 
                     // automatically select properties
@@ -64,14 +71,14 @@ TL_Swapchain_t *TL_SwapchainCreate(const TL_Renderer_t *const renderer, const TL
 
                 void *renderersys = renderer->renderer_system;
 
-                TLVK_SwapchainSystem_t *swapchainsys = TLVK_SwapchainSystemCreate(renderersys, descriptor.resolution, ssdescr,
-                    descriptor.window_surface);
+                TLVK_SwapchainSystem_t *swapchainsys = TLVK_SwapchainSystemCreate(renderersys, ssdescr, descriptor.window_surface);
                 if (!swapchainsys) {
                     TL_Error(debugger, "Failed to create Vulkan swapchain system for new swapchain at %p", swapchain);
                     return NULL;
                 }
 
                 swapchain->swapchain_system = (void *) swapchainsys;
+                swapchain->extent = TLVK_SwapchainSystemGetExtent(swapchainsys);
 
 #           endif
             break;
@@ -109,3 +116,7 @@ void TL_SwapchainDestroy(TL_Swapchain_t *const swapchain) {
 
     free(swapchain);
 }
+
+TL_Extent2D_t TL_SwapchainGetExtent(TL_Swapchain_t *const swapchain) {
+    return swapchain->extent;
+}