From 571772581cc28be38d8d85f02ed7633eb45b8bbd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 8 Feb 2021 14:15:04 +0100
Subject: [PATCH] Vk: rename PipelineStage::AllGraphics to AllRasterization.

Because that's what it is, after all. Also mention this naming
difference in the Vulkan wrapping overview.

I was wondering if I should rename QueueFlag::Graphics too, but since
graphics queues are used for (not really rasterization-specific) image
copies as well, and ray tracing is actually done on compute queues, I
don't think renaming to Rasterization is a good idea. Clarified the
comments at least.
---
 doc/vulkan-wrapping.dox               |  9 +++++++++
 src/Magnum/Vk/DeviceProperties.h      |  4 ++--
 src/Magnum/Vk/Pipeline.h              | 14 ++++++++------
 src/Magnum/Vk/Test/RenderPassTest.cpp |  4 ++--
 4 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/doc/vulkan-wrapping.dox b/doc/vulkan-wrapping.dox
index b64d5873f..b21ddaa1d 100644
--- a/doc/vulkan-wrapping.dox
+++ b/doc/vulkan-wrapping.dox
@@ -188,5 +188,14 @@ can be also passed to @ref Vk::DeviceCreateInfo to allow reuse:
 
 @snippet MagnumVk.cpp wrapping-optimizing-properties-device-move
 
+@section vulkan-wrapping-naming-differences Important differences in naming
+
+-   To emphasise the distinction between rasterization and raytracing
+    pipelines and prevent confusion, @ref Vk::RasterizationPipelineCreateInfo
+    is used for @type_vk{GraphicsPipelineCreateInfo}, and similarly for
+    related APIs, such as @ref Vk::DynamicRasterizationState containing a
+    rasterization-related subset of @type_vk{DynamicState} or
+    @ref Vk::PipelineStage::AllRasterization for @val_vk{PIPELINE_STAGE_ALL_GRAPHICS_BIT,PipelineStageFlagBits}.
+
 */
 }
diff --git a/src/Magnum/Vk/DeviceProperties.h b/src/Magnum/Vk/DeviceProperties.h
index 6fe6a3584..336a39aaf 100644
--- a/src/Magnum/Vk/DeviceProperties.h
+++ b/src/Magnum/Vk/DeviceProperties.h
@@ -161,10 +161,10 @@ Wraps a @type_vk_keyword{QueueFlagBits}.
 @m_enum_values_as_keywords
 */
 enum class QueueFlag: UnsignedInt {
-    /** Supports graphics operations */
+    /** Supports general graphics and rasterization operations. */
     Graphics = VK_QUEUE_GRAPHICS_BIT,
 
-    /** Supports compute operations */
+    /** Supports compute and ray tracing operations. */
     Compute = VK_QUEUE_COMPUTE_BIT,
 
     /** Supports transfer operations */
diff --git a/src/Magnum/Vk/Pipeline.h b/src/Magnum/Vk/Pipeline.h
index 1f0255e1e..694958db8 100644
--- a/src/Magnum/Vk/Pipeline.h
+++ b/src/Magnum/Vk/Pipeline.h
@@ -335,9 +335,9 @@ enum class PipelineStage: UnsignedInt {
     RayTracingShader = VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR,
 
     /**
-     * Execution of all graphics stages. While numerically a single bit, it's
-     * equivalent to the logical OR of a supported and enabled subset of the
-     * following:
+     * Execution of all rasterization stages. While numerically a single bit,
+     * it's equivalent to the logical OR of a supported and enabled subset of
+     * the following:
      *
      * -    @ref PipelineStage::DrawIndirect
      * -    @ref PipelineStage::VertexInput
@@ -350,10 +350,12 @@ enum class PipelineStage: UnsignedInt {
      * -    @ref PipelineStage::LateFragmentTests
      * -    @ref PipelineStage::ColorAttachmentOutput
      *
-     * Note that this *does not* include @ref PipelineStage::RayTracingShader
-     * or @ref PipelineStage::AccelerationStructureBuild.
+     * As the name suggests, this *does not* include
+     * @ref PipelineStage::RayTracingShader or
+     * @ref PipelineStage::AccelerationStructureBuild.
+     * @todo mention mesh / task shaders once exposed
      */
-    AllGraphics = VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT,
+    AllRasterization = VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT,
 
     /**
      * All commands.
diff --git a/src/Magnum/Vk/Test/RenderPassTest.cpp b/src/Magnum/Vk/Test/RenderPassTest.cpp
index e0f941668..c0cf0d448 100644
--- a/src/Magnum/Vk/Test/RenderPassTest.cpp
+++ b/src/Magnum/Vk/Test/RenderPassTest.cpp
@@ -776,7 +776,7 @@ void RenderPassTest::subpassDependencyConstruct() {
     SubpassDependency dependency{
         15, SubpassDependency::External,
         PipelineStage::ComputeShader|PipelineStage::Transfer,
-        PipelineStage::AllGraphics,
+        PipelineStage::AllRasterization,
         Access::TransferRead|Access::UniformRead,
         Access::MemoryWrite,
         DependencyFlag::ByRegion};
@@ -830,7 +830,7 @@ template<class T> void RenderPassTest::subpassDependencyConvertToVk() {
     SubpassDependency dependency{
         15, SubpassDependency::External,
         PipelineStage::ComputeShader|PipelineStage::Transfer,
-        PipelineStage::AllGraphics,
+        PipelineStage::AllRasterization,
         Access::TransferRead|Access::UniformRead,
         Access::MemoryWrite,
         DependencyFlag::ByRegion};