Merge branch 'master' of https://github.com/harrand/Topaz

.gitignore

@@ -1,6 +1,7 @@
 # Topaz Specific Ignores
 cpl/
 docs/*/
+!docs/images
 bin/
 extern/
 build/

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)

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
@@ -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
@@ -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
@@ -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
@@ -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

docs/DoxygenLayout.xml

@@ -2,14 +2,13 @@
   <!-- Generated by doxygen 1.9.3 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
-    <tab type="mainpage" visible="yes" title="Topaz Home"/>
+    <tab type="mainpage" visible="yes" title="Home"/>
     <tab type="user" visible="yes" title="API Reference" url="@ref tz"/>
-    <tab type="user" visible="yes" title="Wiki" url="https://github.com/harrand/Topaz/wiki"/ target="_blank">
   </navindex>
 
   <!-- Layout definition for a class page -->
   <class>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <includes visible="$SHOW_HEADERFILE"/>
     <inheritancegraph visible="$CLASS_GRAPH"/>
     <collaborationgraph visible="$COLLABORATION_GRAPH"/>
@@ -47,7 +46,6 @@
       <related title="" subtitle=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
@@ -68,7 +66,7 @@
 
   <!-- Layout definition for a namespace page -->
   <namespace>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <memberdecl>
       <nestednamespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
@@ -85,7 +83,6 @@
       <variables title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
@@ -100,16 +97,15 @@
 
   <!-- Layout definition for a concept page -->
   <concept>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <includes visible="$SHOW_HEADERFILE"/>
     <definition visible="yes" title=""/>
-    <detaileddescription title=""/>
     <authorsection visible="yes"/>
   </concept>
 
   <!-- Layout definition for a file page -->
   <file>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <includes visible="$SHOW_INCLUDE_FILES"/>
     <includegraph visible="$INCLUDE_GRAPH"/>
     <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
@@ -131,7 +127,6 @@
       <variables title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <defines title=""/>
@@ -147,43 +142,23 @@
 
   <!-- Layout definition for a group page -->
   <group>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <groupgraph visible="$GROUP_GRAPHS"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
-      <dirs visible="yes" title=""/>
-      <files visible="yes" title=""/>
-      <namespaces visible="yes" title=""/>
-      <concepts visible="yes" title=""/>
-      <classes visible="yes" title=""/>
-      <defines title=""/>
       <typedefs title=""/>
-      <sequences title=""/>
-      <dictionaries title=""/>
-      <enums title=""/>
-      <enumvalues title=""/>
-      <functions title=""/>
-      <variables title=""/>
-      <signals title=""/>
-      <publicslots title=""/>
-      <protectedslots title=""/>
-      <privateslots title=""/>
-      <events title=""/>
-      <properties title=""/>
-      <friends title=""/>
-      <membergroups visible="yes"/>
+      <classes visible="yes" title=""/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <pagedocs/>
+      <functions title=""/>
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
       <sequences title=""/>
       <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
-      <functions title=""/>
       <variables title=""/>
       <signals title=""/>
       <publicslots title=""/>
@@ -198,12 +173,11 @@
 
   <!-- Layout definition for a directory page -->
   <directory>
-    <briefdescription visible="yes"/>
+    <detaileddescription title="Description"/>
     <directorygraph visible="yes"/>
     <memberdecl>
       <dirs visible="yes"/>
       <files visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
   </directory>
 </doxygenlayout>

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;

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",

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.

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;
+		}
 	};
 
 	/**

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.
 	 *

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<const std::byte> 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<const std::byte> 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