vulkan: Add data structures to store all graphics state

Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/17328>

2 files changed, 136 insertions, 0 deletions

diff --git a/docs/vulkan/graphics-state.rst b/docs/vulkan/graphics-state.rst
new file mode 100644
index 00000000000..b74857c7a1a
--- /dev/null
+++ b/docs/vulkan/graphics-state.rst
@@ -0,0 +1,135 @@
+Graphics state
+==============
+
+The Mesa Vulkan runtime provides helpers for managing the numerous pieces
+of graphics state associated with a ``VkPipeline`` or set dynamically on a
+command buffer.  No such helpers are provided for compute or ray-tracing
+because they have little or no state besides the shaders themselves.
+
+
+Pipeline state
+--------------
+
+All (possibly dynamic) Vulkan graphics pipeline state is encapsulated into
+a single :cpp:struct:`vk_graphics_pipeline_state` structure which contains
+pointers to sub-structures for each of the different state categories.
+Unlike :cpp:type:`VkGraphicsPipelineCreateInfo`, the pointers in
+:cpp:struct:`vk_graphics_pipeline_state` are guaranteed to be either be
+NULL or point to valid and properly populated memory.
+
+When creating a pipeline, the
+:cpp:func:`vk_graphics_pipeline_state_fill()` function can be used to
+gather all of the state from the core structures as well as various `pNext`
+chains into a single state structure.  Whenever an extension struct is
+missing, a reasonable default value is provided whenever possible.  The
+usual flow for creating a full graphics pipeline (not library) looks like
+this:
+
+.. code-block:: c
+
+   struct vk_graphics_pipeline_state state = { };
+   struct vk_graphics_pipeline_all_state all;
+   vk_graphics_pipeline_state_fill(&device->vk, &state, pCreateInfo,
+                                   NULL, &all, NULL, 0, NULL);
+
+   /* Emit stuff using the state in `state` */
+
+The :cpp:struct:`vk_graphics_pipeline_all_state` structure exists to allow
+the state to sit on the stack instead of requiring a heap allocation.  This
+is useful if you intend to use the state right away and don't need to store
+it.  For pipeline libraries, it's likely more useful to use the dynamically
+allocated version and store the dynamically allocated memory in the
+library pipeline.
+
+.. code-block:: c
+
+   /* Assuming we have a vk_graphics_pipeline_state in pipeline */
+   memset(&pipeline->state, 0, sizeof(pipeline->state));
+
+   for (uint32_t i = 0; i < lib_info->libraryCount; i++) {
+      VK_FROM_HANDLE(drv_graphics_pipeline_library, lib, lib_info->pLibraries[i]);
+      vk_graphics_pipeline_state_merge(&pipeline->state, &lib->state);
+   }
+
+   /* This assumes you have a void **state_mem in pipeline */
+   result = vk_graphics_pipeline_state_fill(&device->vk, &pipeline->state,
+                                            pCreateInfo, NULL, NULL, pAllocator,
+                                            VK_SYSTEM_ALLOCATION_SCOPE_OBJECT,
+                                            &pipeline->state_mem);
+   if (result != VK_SUCCESS)
+      return result;
+
+State from dependent libraries can be merged together using
+:cpp:func:`vk_graphics_pipeline_state_merge`.
+:cpp:func:`vk_graphics_pipeline_state_fill` will then only attempt to
+populate missing fields.  You can also merge dependent pipeline libraries
+together but store the final state on the stack for immediate consumption:
+
+.. code-block:: c
+
+   struct vk_graphics_pipeline_state state = { };
+
+   for (uint32_t i = 0; i < lib_info->libraryCount; i++) {
+      VK_FROM_HANDLE(drv_graphics_pipeline_library, lib, lib_info->pLibraries[i]);
+      vk_graphics_pipeline_state_merge(&state, &lib->state);
+   }
+
+   struct vk_graphics_pipeline_all_state all;
+   vk_graphics_pipeline_state_fill(&device->vk, &state, pCreateInfo,
+                                   NULL, &all, NULL, 0, NULL);
+
+.. doxygenfunction:: vk_graphics_pipeline_state_fill
+
+.. doxygenfunction:: vk_graphics_pipeline_state_merge
+
+Reference
+---------
+
+.. doxygenstruct:: vk_graphics_pipeline_state
+   :members:
+
+.. doxygenstruct:: vk_vertex_binding_state
+   :members:
+
+.. doxygenstruct:: vk_vertex_attribute_state
+   :members:
+
+.. doxygenstruct:: vk_vertex_input_state
+   :members:
+
+.. doxygenstruct:: vk_input_assembly_state
+   :members:
+
+.. doxygenstruct:: vk_tessellation_state
+   :members:
+
+.. doxygenstruct:: vk_viewport_state
+   :members:
+
+.. doxygenstruct:: vk_discard_rectangles_state
+   :members:
+
+.. doxygenstruct:: vk_rasterization_state
+   :members:
+
+.. doxygenstruct:: vk_fragment_shading_rate_state
+   :members:
+
+.. doxygenstruct:: vk_sample_locations_state
+   :members:
+
+.. doxygenstruct:: vk_multisample_state
+   :members:
+
+.. doxygenstruct:: vk_stencil_test_face_state
+   :members:
+
+.. doxygenstruct:: vk_depth_stencil_state
+   :members:
+
+.. doxygenstruct:: vk_color_blend_state
+   :members:
+
+.. doxygenstruct:: vk_render_pass_state
+   :members:
+
diff --git a/docs/vulkan/index.rst b/docs/vulkan/index.rst
index c4acd9e89bb..8562261135f 100644
--- a/docs/vulkan/index.rst
+++ b/docs/vulkan/index.rst
@@ -11,4 +11,5 @@ hardware-agnostic bits in common code.
 
    base-objs
    dispatch
+   graphics-state
    renderpass