From 89a64888967518a9dbaf11682e15ea80cc0cfdb8 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 14:18:25 +0000 Subject: [PATCH 1/7] [error] renamed hardware_unsuitability to machine_unsuitability, as it also counts for invalid drivers etc --- include/tz/core/error.hpp | 6 +++--- src/tz/gpu/rhi_vulkan.cpp | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/include/tz/core/error.hpp b/include/tz/core/error.hpp index 523e0293d4..3db26637bc 100644 --- a/include/tz/core/error.hpp +++ b/include/tz/core/error.hpp @@ -19,8 +19,8 @@ namespace tz precondition_failure, /// An error has occurred because an illegal/incorrect value has been detected. invalid_value, - /// An error has occurred because the hardware currently being used is not suitable for the given task. - hardware_unsuitable, + /// An error has occurred because the currently running machine does not support the given operation. + machine_unsuitable, /// An error has occurred due to an engine-side logic error, and you should submit a bug report. engine_bug, /// An error has occurred due to a serious hazard relating to the driver/hardware. This most likely means a graphics driver crash/hardware-lost. @@ -44,7 +44,7 @@ namespace tz "partial success", "precondition failure error", "invalid value error", - "hardware unsuitability error", + "machine unsuitability error", "engine bug error", "driver hazard error", "unknown error", diff --git a/src/tz/gpu/rhi_vulkan.cpp b/src/tz/gpu/rhi_vulkan.cpp index c7a944a3e6..a1010107c0 100644 --- a/src/tz/gpu/rhi_vulkan.cpp +++ b/src/tz/gpu/rhi_vulkan.cpp @@ -465,7 +465,7 @@ namespace tz::gpu if(hw.caps != hardware_capabilities::graphics_compute) { // incompatible hardware. - return error_code::hardware_unsuitable; + RETERR(error_code::machine_unsuitable, "Graphics hardware {} is not suitable because it does not have a graphics-compute queue.", hw.name); } auto pdev = reinterpret_cast(static_cast(hw.internals.i0.peek())); @@ -532,7 +532,7 @@ namespace tz::gpu RETERR(tz::error_code::voom, "ran out of GPU memory while trying to create vulkan device"); break; case VK_ERROR_EXTENSION_NOT_PRESENT: - RETERR(tz::error_code::hardware_unsuitable, "the hardware requested for use is not suitable due to a missing vulkan extension"); + RETERR(tz::error_code::machine_unsuitable, "the hardware requested for use is not suitable due to a missing vulkan extension"); break; case VK_ERROR_FEATURE_NOT_PRESENT: switch(hw.features) @@ -541,7 +541,7 @@ namespace tz::gpu RETERR(tz::error_code::engine_bug, "vulkan driver says not all features were available for the device, even though the engine said it was suitable. please submit a bug report."); break; default: - RETERR(tz::error_code::hardware_unsuitable, "the hardware requested for use is not suitable due to a missing vulkan feature"); + RETERR(tz::error_code::machine_unsuitable, "the hardware requested for use is not suitable due to a missing vulkan feature"); break; } break; @@ -2007,7 +2007,7 @@ namespace tz::gpu return tz::error_code::precondition_failure; break; case VK_ERROR_INITIALIZATION_FAILED: - return tz::error_code::hardware_unsuitable; + return tz::error_code::machine_unsuitable; break; default: return tz::error_code::unknown_error; From 894735e9b2fff9a43932dfd7a94a9ed15f1f0dec Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 14:24:46 +0000 Subject: [PATCH 2/7] [gpu.resource] minor documentation pass --- include/tz/gpu/resource.hpp | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/tz/gpu/resource.hpp b/include/tz/gpu/resource.hpp index 1d8807dbca..9711b4f09c 100644 --- a/include/tz/gpu/resource.hpp +++ b/include/tz/gpu/resource.hpp @@ -207,8 +207,26 @@ namespace tz::gpu * - If the image was created with @ref image_type::depth or @ref image_type::floats, then each pixel should be 4 bytes - a single signed 32-bit float. */ tz::error_code resource_write(resource_handle res, std::span new_data, std::size_t offset = 0); + /** + * @ingroup tz_gpu_resource + * @brief Retrieve the size of a resource's data, in bytes. + */ std::size_t resource_size(resource_handle res); + /** + * @ingroup tz_gpu_resource + * @brief Retrieve the width of an image resource. + * + * - It is valid to pass @ref tz::gpu::window_resource, in which case the width of the window image will be returned. + * - If you do not pass a valid image resource (e.g a buffer resource, or the null handle), then 0 is returned. + */ unsigned int image_get_width(resource_handle res); + /** + * @ingroup tz_gpu_resource + * @brief Retrieve the height of an image resource. + * + * - It is valid to pass @ref tz::gpu::window_resource, in which case the height of the window image will be returned. + * - If you do not pass a valid image resource (e.g a buffer resource, or the null handle), then 0 is returned. + */ unsigned int image_get_height(resource_handle res); /** * @ingroup tz_gpu_resource @@ -217,7 +235,21 @@ namespace tz::gpu * You aren't allowed to read from @ref tz::gpu::window_resource. */ std::span resource_read(resource_handle res); + /** + * @ingroup tz_gpu_resource + * @brief Resize a buffer resource. + * + * - If the size of the buffer increases, the new memory at the end will be of unspecified value. + * - Any data within the buffer that you have previously written to will be preserved. + */ void buffer_resize(resource_handle bufh, std::size_t new_size_bytes); + /** + * @ingroup tz_gpu_resource + * @brief Resize an image resource. + * + * - If the size of the image increases, the new rows/columns of the image will be of unspecified value. + * - Any data within the image that you have previously written to will be preserved. + */ void image_resize(resource_handle imgh, unsigned int new_width, unsigned int new_height); /** * @ingroup tz_gpu_resource From 4897bbfe04619553327bb0c47b6edd8c22cb7cb1 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 14:52:51 +0000 Subject: [PATCH 3/7] [ren] major documentation pass for quad_renderer --- include/tz/gpu/graph.hpp | 4 ++ include/tz/ren/quad.hpp | 125 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 128 insertions(+), 1 deletion(-) diff --git a/include/tz/gpu/graph.hpp b/include/tz/gpu/graph.hpp index f532e73aca..141d7f1abd 100644 --- a/include/tz/gpu/graph.hpp +++ b/include/tz/gpu/graph.hpp @@ -11,6 +11,10 @@ namespace tz::gpu * @brief Documentation for render graphs - describes the execution of @ref tz_gpu_pass. */ + /** + * @ingroup tz_gpu_graph + * @brief Specifies optional, extra functionality for a graph. + */ enum graph_flag { /// After the graph has completed execution, present the system image to the window. diff --git a/include/tz/ren/quad.hpp b/include/tz/ren/quad.hpp index a340aaed54..fe015064ce 100644 --- a/include/tz/ren/quad.hpp +++ b/include/tz/ren/quad.hpp @@ -11,12 +11,39 @@ namespace tz::ren struct quad_t{}; struct quadren_t{}; } + /** + * @ingroup tz_ren + * @defgroup tz_ren_quad Quad Renderer + * @brief Efficiently render a large number of 2D quads. + * + * 1. Create a quad renderer via @ref create_quad_renderer. + * 2. Create a bunch of quads using repeated calls to @ref quad_renderer_create_quad. + * 3. Every frame, retrieve the graph via @ref quad_renderer_graph and pass that to @ref tz::gpu::execute to render all the quads. + */ + + /** + * @ingroup tz_ren_quad + * @brief Represents a single quad. Owned by a @ref quad_renderer_handle. + */ using quad_handle = tz::handle; + /** + * @ingroup tz_ren_quad + * @brief Represents a single quad renderer instance. + * + * You can have multiple quad renderers at the same time. Any @ref quad_handle retrieved from creating a quad will be owned solely by whichever quad renderer you used to create it. + */ using quad_renderer_handle = tz::handle; + /** + * @ingroup tz_ren_quad + * @brief Specifies optional, extra functionality for a quad renderer. + */ enum quad_renderer_flag { + /// If the alpha-component of any fragment in a quad (after texture sampling) is very low (<0.05f), then that fragment will be discarded. alpha_clipping = 0b0001, + /// Sets @ref tz::gpu::graph_flag::present_after on the graph representing the quad renderer. + graph_present_after = 0b0010, }; constexpr quad_renderer_flag operator|(quad_renderer_flag lhs, quad_renderer_flag rhs) @@ -29,41 +56,137 @@ namespace tz::ren return static_cast(lhs) & static_cast(rhs); } + /** + * @ingroup tz_ren_quad + * @brief Specifies creation flags for a quad renderer. + * + * See @ref create_quad_renderer for usage. + */ struct quad_renderer_info { + /// When the main pass is executed, the colour target will be cleared to this colour value. tz::v4f clear_colour = {0.0f, 0.0f, 0.0f, 1.0f}; - quad_renderer_flag flags = static_cast(0); + /// Specifies the colour target to render into. By default, this is the window resource (i.e the quad renderer will draw to the window unless you specify a different colour target). tz::gpu::resource_handle colour_target = tz::gpu::window_resource; + /// Any extra optional flags to specify? + quad_renderer_flag flags = static_cast(0); }; + /** + * @ingroup tz_ren_quad + * @brief Create a new quad renderer. + * @return On success: A @ref quad_renderer_handle corresponding to the newly-created quad renderer. + * @return On failure: Any error returned by the automatic call to @ref create_pass. + */ std::expected create_quad_renderer(quad_renderer_info info); + /** + * @ingroup tz_ren_quad + * @brief Manually destroy a quad renderer. + * @return On failure: Any error returned by the automatic calls to @ref destroy_resource. + */ tz::error_code destroy_quad_renderer(quad_renderer_handle renh); + /** + * @ingroup tz_ren_quad + * @brief Specifies initial data for a single quad. + */ struct quad_info { + /// Position of the quad, in world-space. You can change this later via @ref set_quad_position. tz::v2f position = tz::v2f::zero(); + /// Rotation of the quads, in radians. float rotation = 0.0f; + /// Scale factors of the quad, in both dimensions. You can change this later via @ref set_quad_scale. tz::v2f scale = tz::v2f::filled(1.0f); + /// Texture to display on the quad. Defaults to -1 (no texture). If no texture is used, then the quad will have a solid colour corresponding to @ref colour. You can change this later via @ref set_quad_texture. std::uint32_t texture_id = -1; + /// Colour of the quad. If the quad has no texture, this will be the exact colour of the whole quad. If the quad *does* have a texture, then the sampled texture colour will be multiplied by this value (in which case you will often want to provide {1, 1, 1}). You can change this later via @ref set_quad_colour. tz::v3f colour = tz::v3f::filled(1.0f); }; + + /** + * @ingroup tz_ren_quad + * @brief Create a new quad to be rendered by an existing quad renderer. + * @return On success, a handle corresponding to the newly created quad. + * @return @ref tz::error_code::invalid_value If you provide an invalid texture-id. + * + * Next time the quad renderer executes, this new quad will be visible with the info provided. + */ std::expected quad_renderer_create_quad(quad_renderer_handle renh, quad_info info); + /** + * @ingroup tz_ren_quad + * @brief Associate an existing image resource with the provided quad renderer, allowing quads to use it as a texture. + * @return On success, a integer representing the texture-id corresponding to the image. You can cause a quad to use this texture via @ref set_quad_texture. + * @return On failure: Any error returned by the automatic call to @ref pass_add_image_resource. + */ std::expected quad_renderer_add_texture(quad_renderer_handle renh, tz::gpu::resource_handle image); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the position of a quad, in world-space. + */ tz::v2f get_quad_position(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new position of a quad, in world-space. + */ void set_quad_position(quad_renderer_handle renh, quad_handle quad, tz::v2f position); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the scale factor of a quad, in both dimensions. + */ tz::v2f get_quad_scale(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new scale factor of a quad, in both dimensions. + */ void set_quad_scale(quad_renderer_handle renh, quad_handle quad, tz::v2f scale); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the colour of a quad. + * + * See @ref quad_info::colour for more details. + */ tz::v3f get_quad_colour(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new colour of a quad. + * + * See @ref quad_info::colour for more details. + */ void set_quad_colour(quad_renderer_handle renh, quad_handle quad, tz::v3f colour); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the texture-id currently being used by a quad. + * @return (-1) If the quad was not using a texture. + */ std::uint32_t get_quad_texture(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new texture-id to be used by a quad. + * + * Note: Passing -1 as the texture-id will cause the quad to no longer sample from a texture. + */ void set_quad_texture(quad_renderer_handle renh, quad_handle quad, std::uint32_t texture_id); + /** + * @ingroup tz_ren_quad + * @brief Retrieve a graph representing the quad renderer. + * + * To actually execute a quad renderer, you must retrieve it's graph and pass it to @ref tz::gpu::execute. See @ref tz_gpu_graph for more info. + */ tz::gpu::graph_handle quad_renderer_graph(quad_renderer_handle renh); + /** + * @ingroup tz_ren_quad + * @brief Update internal state for a quad renderer. + * + * - This does *not* render anything. + * - You should call this every frame, before rendering. + */ void quad_renderer_update(quad_renderer_handle renh); } From c6a7fafada4d78e696162301617ac04725149d10 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 16:26:22 +0000 Subject: [PATCH 4/7] [docs] improved doxygen layout and aesthetics --- README.md | 2 +- docs/Doxyfile | 22 +++++++++++----------- docs/DoxygenLayout.xml | 21 +++++++-------------- docs/tz.png | Bin 0 -> 3262 bytes include/tz/topaz.hpp | 2 +- 5 files changed, 20 insertions(+), 27 deletions(-) create mode 100644 docs/tz.png diff --git a/README.md b/README.md index bdee018cb2..5cb0371c49 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Topaz +# Topaz Engine [![OGL Debug](https://github.com/Harrand/Topaz/actions/workflows/codebuild_opengl_debug.yml/badge.svg)](https://github.com/Harrand/Topaz/actions/workflows/codebuild_opengl_debug.yml) [![OGL Release](https://github.com/Harrand/Topaz/actions/workflows/codebuild_opengl_release.yml/badge.svg)](https://github.com/Harrand/Topaz/actions/workflows/codebuild_opengl_release.yml) diff --git a/docs/Doxyfile b/docs/Doxyfile index f915be0447..9aad923522 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -60,13 +60,13 @@ PROJECT_BRIEF = "Topaz Game Engine" # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = "./tz.png # With the PROJECT_ICON tag one can specify an icon that is included in the tabs # when the HTML document is shown. Doxygen will copy the logo to the output # directory. -PROJECT_ICON = +PROJECT_ICON = "./tz.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -673,7 +673,7 @@ SHOW_GROUPED_MEMB_INC = NO # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. -FORCE_LOCAL_INCLUDES = NO +FORCE_LOCAL_INCLUDES = YES # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. @@ -686,7 +686,7 @@ INLINE_INFO = YES # name. If set to NO, the members will appear in declaration order. # The default value is: YES. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then Doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member @@ -739,19 +739,19 @@ STRICT_PROTO_MATCHING = NO # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. -GENERATE_TODOLIST = YES +GENERATE_TODOLIST = NO # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. # The default value is: YES. -GENERATE_TESTLIST = YES +GENERATE_TESTLIST = NO # The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. -GENERATE_BUGLIST = YES +GENERATE_BUGLIST = NO # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in @@ -782,21 +782,21 @@ MAX_INITIALIZER_LINES = 30 # list will mention the files that were used to generate the documentation. # The default value is: YES. -SHOW_USED_FILES = YES +SHOW_USED_FILES = NO # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This # will remove the Files entry from the Quick Index and from the Folder Tree View # (if specified). # The default value is: YES. -SHOW_FILES = YES +SHOW_FILES = NO # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. -SHOW_NAMESPACES = YES +SHOW_NAMESPACES = NO # The FILE_VERSION_FILTER tag can be used to specify a program or script that # Doxygen should invoke to get the current version for each file (typically from @@ -1444,7 +1444,7 @@ HTML_EXTRA_FILES = # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE = AUTO_LIGHT +HTML_COLORSTYLE = DARK # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index d209561d5f..bd97f59023 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -2,14 +2,13 @@ - + - - + @@ -47,7 +46,6 @@ - @@ -68,7 +66,7 @@ - + @@ -85,7 +83,6 @@ - @@ -100,16 +97,15 @@ - + - - + @@ -131,7 +127,6 @@ - @@ -147,7 +142,7 @@ - + @@ -173,7 +168,6 @@ - @@ -198,12 +192,11 @@ - + - \ No newline at end of file diff --git a/docs/tz.png b/docs/tz.png new file mode 100644 index 0000000000000000000000000000000000000000..714168fce9401f541d6d50247caa7fb8f889b5be GIT binary patch literal 3262 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 literal 0 HcmV?d00001 diff --git a/include/tz/topaz.hpp b/include/tz/topaz.hpp index 244ab243c3..fb8343e6fa 100644 --- a/include/tz/topaz.hpp +++ b/include/tz/topaz.hpp @@ -3,7 +3,7 @@ #include "textc/imported_text.hpp" /** - * @defgroup tz Topaz API Reference + * @defgroup tz API Reference **/ namespace tz { From cb92b964d97cafd4e29759e1e5b4996ff0bc672b Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 16:43:15 +0000 Subject: [PATCH 5/7] [docs] remove a bunch of unnecessary cruft, making the documentation more compact. im hoping i havent accidentally removed a section used by some groups but i absolutely might have missed it. --- docs/Doxyfile | 2 +- docs/DoxygenLayout.xml | 23 ++--------------------- include/tz/topaz.hpp | 1 + 3 files changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 9aad923522..be59169b83 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -162,7 +162,7 @@ ABBREVIATE_BRIEF = "The $name class" \ # description. # The default value is: NO. -ALWAYS_DETAILED_SEC = NO +ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, Doxygen will show all # inherited members of a class in the documentation of that class as if those diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index bd97f59023..1eba072daa 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -146,30 +146,12 @@ - - - - - - - - - - - - - - - - - - - - + + @@ -177,7 +159,6 @@ - diff --git a/include/tz/topaz.hpp b/include/tz/topaz.hpp index fb8343e6fa..bd7eb76d88 100644 --- a/include/tz/topaz.hpp +++ b/include/tz/topaz.hpp @@ -4,6 +4,7 @@ /** * @defgroup tz API Reference + * @brief C++ API for the Topaz Engine **/ namespace tz { From 5c88a3bb18345a8e8f3efc68187c3f818bfe2a78 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 19:04:00 +0000 Subject: [PATCH 6/7] [docs] remove unnecessarily massive horizontal margin, and add directory for images (currently empty) --- .gitignore | 1 + docs/Doxyfile | 2 +- docs/doxygen-awesome.css | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 1f47839276..7a7586981a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # Topaz Specific Ignores cpl/ docs/*/ +!docs/images bin/ extern/ build/ diff --git a/docs/Doxyfile b/docs/Doxyfile index be59169b83..d013fb934e 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1120,7 +1120,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = ./images # The INPUT_FILTER tag can be used to specify a program that Doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/docs/doxygen-awesome.css b/docs/doxygen-awesome.css index 99ead768b3..415de70758 100644 --- a/docs/doxygen-awesome.css +++ b/docs/doxygen-awesome.css @@ -73,7 +73,7 @@ html { /* content text properties. These only affect the page content, not the navigation or any other ui elements */ --content-line-height: 27px; /* The content is centered and constraint in it's width. To make the content fill the whole page, set the variable to auto.*/ - --content-maxwidth: 1050px; + --content-maxwidth: auto; --table-line-height: 24px; --toc-sticky-top: var(--spacing-medium); --toc-width: 200px; From 5d347e8245198839b7204f9c247247379b18a5f4 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 19:59:17 +0000 Subject: [PATCH 7/7] [gpu.hardware] emit an engine bug if the user tries to use 2 different pieces of hardware, which is not currently supported. --- include/tz/gpu/hardware.hpp | 10 ++++++++++ include/tz/gpu/pass.hpp | 1 + src/tz/gpu/rhi_vulkan.cpp | 23 ++++++++++++++++++++--- 3 files changed, 31 insertions(+), 3 deletions(-) diff --git a/include/tz/gpu/hardware.hpp b/include/tz/gpu/hardware.hpp index cfed810301..ba7efa9205 100644 --- a/include/tz/gpu/hardware.hpp +++ b/include/tz/gpu/hardware.hpp @@ -87,6 +87,16 @@ namespace tz::gpu hardware_handle i0; std::uint32_t i1; } internals; + + bool operator==(const hardware& rhs) const + { + return this->internals.i0 == rhs.internals.i0; + } + + bool operator!=(const hardware& rhs) const + { + return this->internals.i0 != rhs.internals.i0; + } }; /** diff --git a/include/tz/gpu/pass.hpp b/include/tz/gpu/pass.hpp index 02a871c47a..d10b03bde0 100644 --- a/include/tz/gpu/pass.hpp +++ b/include/tz/gpu/pass.hpp @@ -155,6 +155,7 @@ namespace tz::gpu * @return @ref tz::error_code::invalid_value For a graphics pass if you fail to provide at least one colour target. * @return @ref tz::error_code::invalid_value For a graphics pass if you provide a colour target that is invalid. A valid colour target is either a.) the window resource (and you have opened a window), b.) an image resource created with @ref tz::gpu::image_flag::colour_target * @return @ref tz::error_code::precondition_failure For a graphics pass if any colour target provided does not exactly match the dimensions of all other provided colour targets. All colour targets must be images with the same dimensions. This does mean that if you provide the window resource as a colour target, all other colour targets must have the same dimensions as the window. + * @return @ref tz::error_code::machine_unsuitable If the currently-used hardware does not support the pass you're attempting to create, for example if you attempt to create a graphics pass but your hardware has @ref hardware_capabilities::compute_only. * @return @ref tz::error_code::oom If CPU memory is exhausted while trying to create the pass. * @return @ref tz::error_code::voom If GPU memory is exhausted while trying to create the pass. * diff --git a/src/tz/gpu/rhi_vulkan.cpp b/src/tz/gpu/rhi_vulkan.cpp index a1010107c0..929f5df68a 100644 --- a/src/tz/gpu/rhi_vulkan.cpp +++ b/src/tz/gpu/rhi_vulkan.cpp @@ -45,7 +45,7 @@ namespace tz::gpu unsigned int swapchain_width = -1; unsigned int swapchain_height = -1; std::vector swapchain_images = {}; std::vector swapchain_views = {}; - hardware current_hardware; + hardware current_hardware = {}; #define VULKAN_API_VERSION_USED VK_API_VERSION_1_3 constexpr VkFormat swapchain_format = VK_FORMAT_B8G8R8A8_UNORM; VmaAllocator alloc = VK_NULL_HANDLE; @@ -462,10 +462,18 @@ namespace tz::gpu error_code use_hardware(hardware hw) { - if(hw.caps != hardware_capabilities::graphics_compute) + if(current_hardware == hw) + { + return tz::error_code::success; + } + if(current_hardware != hardware{}) + { + RETERR(tz::error_code::engine_bug, "I have not yet implemented the ability to select hardware twice for two different pieces of hardware. You previously selected \"{}\" but now want \"{}\"", current_hardware.name, hw.name); + } + if(hw.caps == hardware_capabilities::neither) { // incompatible hardware. - RETERR(error_code::machine_unsuitable, "Graphics hardware {} is not suitable because it does not have a graphics-compute queue.", hw.name); + RETERR(error_code::machine_unsuitable, "Graphics hardware {} is not suitable because it supports neither graphics nor compute operations.", hw.name); } auto pdev = reinterpret_cast(static_cast(hw.internals.i0.peek())); @@ -1192,6 +1200,10 @@ namespace tz::gpu if(shader1.ty == shader_type::compute) { + if(current_hardware.caps == hardware_capabilities::graphics_only || current_hardware.caps == hardware_capabilities::neither) + { + UNERR(tz::error_code::machine_unsuitable, "Attempt to create compute pass using hardware {} which does not support compute operations.", current_hardware.name); + } VkComputePipelineCreateInfo create { .sType = VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO, @@ -1222,6 +1234,11 @@ namespace tz::gpu } auto& shader2 = shaders[--bottom_part]; + if(current_hardware.caps == hardware_capabilities::compute_only || current_hardware.caps == hardware_capabilities::neither) + { + UNERR(tz::error_code::machine_unsuitable, "Attempt to create graphics pass using hardware {} which does not support graphics operations.", current_hardware.name); + } + std::array shader_creates { VkPipelineShaderStageCreateInfo