OpenHarmony/third_party_mesa3d
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/vulkan: use hawkmoth instead of doxygen

Browse Source 
Use the hawkmoth c:auto* directives to incorporate vulkan documentation.

Convert @param style parameter descriptions to rst info field lists.
Add static stubs for generated headers. Fix a lot of references, in
particular the symbols are now in the Sphinx C domain, not C++
domain. Tweak syntax here and there.

Based on the earlier work by Erik Faye-Lund <kusmabite@gmail.com>

Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>
This commit is contained in:
Jani Nikula
2023-08-20 20:41:21 +03:00
committed by Marge Bot
parent 91587326ae
commit 082e7d23e7
19 changed files with 348 additions and 259 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/header-stubs/vk_cmd_queue.h Normal file
View File

@@ -0,0 +1 @@
struct vk_cmd_queue {};

1
docs/header-stubs/vk_dispatch_table.h Normal file
View File

@@ -0,0 +1 @@
struct vk_instance_dispatch_table {};

2
docs/header-stubs/vk_extensions.h Normal file
View File

@@ -0,0 +1,2 @@
struct vk_instance_extension_table {};
struct vk_instance_entrypoint_table {};

4
docs/header-stubs/vk_physical_device_features.h Normal file
View File

@@ -0,0 +1,4 @@
struct vk_device_dispatch_table {};
struct vk_device_extension_table {};
struct vk_features {};
struct vk_physical_device_dispatch_table {};

1
docs/header-stubs/vk_physical_device_properties.h Normal file
View File

@@ -0,0 +1 @@
struct vk_properties {};

80
docs/vulkan/base-objs.rst
View File

@@ -10,27 +10,27 @@ which form the core of the Vulkan runtime code:
.. contents::
:local:
As one might expect, :cpp:struct:`vk_instance` is the required base struct
for implementing ``VkInstance``, :cpp:struct:`vk_physical_device` is
required for ``VkPhysicalDevice``, and :cpp:struct:`vk_device` for
As one might expect, :c:struct:`vk_instance` is the required base struct
for implementing ``VkInstance``, :c:struct:`vk_physical_device` is
required for ``VkPhysicalDevice``, and :c:struct:`vk_device` for
``VkDevice``. Everything else must derive from
:cpp:struct:`vk_object_base` or from some struct that derives from
:cpp:struct:`vk_object_base`.
:c:struct:`vk_object_base` or from some struct that derives from
:c:struct:`vk_object_base`.
vk_object_base
--------------
The root base struct for all Vulkan objects is
:cpp:struct:`vk_object_base`. Every object exposed to the client through
the Vulkan API *must* inherit from :cpp:struct:`vk_object_base` by having a
:cpp:struct:`vk_object_base` or some struct that inherits from
:cpp:struct:`vk_object_base` as the driver struct's first member. Even
:c:struct:`vk_object_base`. Every object exposed to the client through
the Vulkan API *must* inherit from :c:struct:`vk_object_base` by having a
:c:struct:`vk_object_base` or some struct that inherits from
:c:struct:`vk_object_base` as the driver struct's first member. Even
though we have ``container_of()`` and use it liberally, the
:cpp:struct:`vk_object_base` should be the first member as there are a few
:c:struct:`vk_object_base` should be the first member as there are a few
places, particularly in the logging framework, where we use void pointers
to avoid casting and this only works if the address of the driver struct is
the same as the address of the :cpp:struct:`vk_object_base`.
the same as the address of the :c:struct:`vk_object_base`.
The standard pattern for defining a Vulkan object inside a driver looks
something like this:
@@ -66,40 +66,44 @@ Then, to the object in a Vulkan entrypoint,
vk_object_free(&device->vk, pAllocator, sampler);
}
The :cpp:any:`VK_DEFINE_NONDISP_HANDLE_CASTS()` macro defines a set of
The :c:macro:`VK_DEFINE_NONDISP_HANDLE_CASTS()` macro defines a set of
type-safe cast functions called ``drv_sampler_from_handle()`` and
``drv_sampler_to_handle()`` which cast a :cpp:type:`VkSampler` to and from a
``drv_sampler_to_handle()`` which cast a :c:type:`VkSampler` to and from a
``struct drv_sampler *``. Because compile-time type checking with Vulkan
handle types doesn't always work in C, the ``_from_handle()`` helper uses the
provided :cpp:type:`VkObjectType` to assert at runtime that the provided
provided :c:type:`VkObjectType` to assert at runtime that the provided
handle is the correct type of object. Both cast helpers properly handle
``NULL`` and ``VK_NULL_HANDLE`` as inputs. The :cpp:any:`VK_FROM_HANDLE()`
``NULL`` and ``VK_NULL_HANDLE`` as inputs. The :c:macro:`VK_FROM_HANDLE()`
macro provides a convenient way to declare a ``drv_foo`` pointer and
initialize it from a ``VkFoo`` handle in one smooth motion.
.. doxygenstruct:: vk_object_base
.. c:autostruct:: vk_object_base
:file: src/vulkan/runtime/vk_object.h
:members:
.. doxygenfunction:: vk_object_base_init
.. doxygenfunction:: vk_object_base_finish
.. c:autofunction:: vk_object_base_init
.. doxygendefine:: VK_DEFINE_HANDLE_CASTS
.. c:autofunction:: vk_object_base_finish
.. doxygendefine:: VK_DEFINE_NONDISP_HANDLE_CASTS
.. c:automacro:: VK_DEFINE_HANDLE_CASTS
.. doxygendefine:: VK_FROM_HANDLE
.. c:automacro:: VK_DEFINE_NONDISP_HANDLE_CASTS
.. c:automacro:: VK_FROM_HANDLE
vk_instance
-----------
.. doxygenstruct:: vk_instance
.. c:autostruct:: vk_instance
:file: src/vulkan/runtime/vk_instance.h
:members:
.. doxygenfunction:: vk_instance_init
.. doxygenfunction:: vk_instance_finish
.. c:autofunction:: vk_instance_init
Once a driver has a :cpp:struct:`vk_instance`, implementing all the various
.. c:autofunction:: vk_instance_finish
Once a driver has a :c:struct:`vk_instance`, implementing all the various
instance-level ``vkGet*ProcAddr()`` entrypoints is trivial:
.. code-block:: c
@@ -142,9 +146,11 @@ actually defined in the Vulkan headers and you need the prototype somewhere
to get the C compiler to not complain. These are all implemented by
wrapping one of the provided ``vk_instance_get*_proc_addr()`` functions.
.. doxygenfunction:: vk_instance_get_proc_addr
.. doxygenfunction:: vk_instance_get_proc_addr_unchecked
.. doxygenfunction:: vk_instance_get_physical_device_proc_addr
.. c:autofunction:: vk_instance_get_proc_addr
.. c:autofunction:: vk_instance_get_proc_addr_unchecked
.. c:autofunction:: vk_instance_get_physical_device_proc_addr
We also provide an implementation of
``vkEnumerateInstanceExtensionProperties()`` which can be used similarly:
@@ -163,22 +169,26 @@ We also provide an implementation of
&instance_extensions, pPropertyCount, pProperties);
}
.. doxygenfunction:: vk_enumerate_instance_extension_properties
.. c:autofunction:: vk_enumerate_instance_extension_properties
vk_physical_device
------------------
.. doxygenstruct:: vk_physical_device
.. c:autostruct:: vk_physical_device
:file: src/vulkan/runtime/vk_physical_device.h
:members:
.. doxygenfunction:: vk_physical_device_init
.. doxygenfunction:: vk_physical_device_finish
.. c:autofunction:: vk_physical_device_init
.. c:autofunction:: vk_physical_device_finish
vk_device
------------------
.. doxygenstruct:: vk_device
.. c:autostruct:: vk_device
:file: src/vulkan/runtime/vk_device.h
:members:
.. doxygenfunction:: vk_device_init
.. doxygenfunction:: vk_device_finish
.. c:autofunction:: vk_device_init
.. c:autofunction:: vk_device_finish

29
docs/vulkan/command-pools.rst
View File

@@ -4,10 +4,11 @@ Command Pools
The Vulkan runtime code provides a common ``VkCommandPool`` implementation
which makes managing the lifetimes of command buffers and recycling their
internal state easier. To use the common command pool a driver needs to
fill out a :cpp:struct:`vk_command_buffer_ops` struct and set the
``command_buffer_ops`` field of :cpp:struct:`vk_device`.
fill out a :c:struct:`vk_command_buffer_ops` struct and set the
``command_buffer_ops`` field of :c:struct:`vk_device`.
.. doxygenstruct:: vk_command_buffer_ops
.. c:autostruct:: vk_command_buffer_ops
:file: src/vulkan/runtime/vk_command_buffer.h
:members:
By reducing the entirety of command buffer lifetime management to these
@@ -21,7 +22,7 @@ Command Buffer Recycling
The common command pool provides automatic command buffer recycling as long
as the driver uses the common ``vkAllocateCommandBuffers()`` and
``vkFreeCommandBuffers()`` implementations. The driver must also provide the
``reset`` function pointer in :cpp:struct:`vk_command_buffer_ops`.
``reset`` function pointer in :c:struct:`vk_command_buffer_ops`.
With the common command buffer pool, when the client calls
``vkFreeCommandBuffers()``, the command buffers are not immediately freed.
@@ -39,7 +40,7 @@ Custom command pools
If a driver wishes to recycle at a finer granularity than whole command
buffers, they can do so by providing their own command pool implementation
which wraps :cpp:struct:`vk_command_pool`. The common use-case here is if
which wraps :c:struct:`vk_command_pool`. The common use-case here is if
the driver wants to pool command-buffer-internal objects at a finer
granularity than whole command buffers. The command pool provides a place
where things like GPU command buffers or upload buffers can be cached
@@ -53,7 +54,7 @@ entrypoints:
- ``vkTrimCommandPool()``
All of the other entrypoints will be handled by common code so long as the
driver's command pool derives from :cpp:struct:`vk_command_pool`.
driver's command pool derives from :c:struct:`vk_command_pool`.
The driver implementation of the command buffer ``recycle()`` function
should respect ``VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT`` and, when
@@ -64,15 +65,21 @@ come from the common command buffer code when a command buffer is recycled.
The driver's implementation of ``vkTrimCommandPool()`` should free any
resources that have been cached within the command pool back to the device
or back to the OS. It **must** also call :cpp:func:`vk_command_pool_trim`
or back to the OS. It **must** also call :c:func:`vk_command_pool_trim`
to allow the common code to free any recycled command buffers.
Reference
---------
.. doxygenstruct:: vk_command_pool
.. c:autostruct:: vk_command_pool
:file: src/vulkan/runtime/vk_command_pool.h
:members:
.. doxygenfunction:: vk_command_pool_init
.. doxygenfunction:: vk_command_pool_finish
.. doxygenfunction:: vk_command_pool_trim
.. c:autofunction:: vk_command_pool_init
:file: src/vulkan/runtime/vk_command_pool.h
.. c:autofunction:: vk_command_pool_finish
:file: src/vulkan/runtime/vk_command_pool.h
.. c:autofunction:: vk_command_pool_trim
:file: src/vulkan/runtime/vk_command_pool.h

2
docs/vulkan/dispatch.rst
View File

@@ -273,7 +273,7 @@ which wrap these functions because those have to be exposed as actual
symbols from the ``.so`` or ``.dll`` as part of the loader interface. It
also has to provide its own ``drv_GetInstanceProcAddr()`` because it needs
to pass the supported instance extension table to
:cpp:func:`vk_instance_get_proc_addr`. The runtime will provide
:c:func:`vk_instance_get_proc_addr`. The runtime will provide
``vk_common_GetDeviceProcAddr()`` implementations.

133
docs/vulkan/graphics-state.rst
View File

@@ -11,32 +11,32 @@ Pipeline state
--------------
All (possibly dynamic) Vulkan graphics pipeline state is encapsulated into
a single :cpp:struct:`vk_graphics_pipeline_state` structure which contains
a single :c: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
Unlike :c:type:`VkGraphicsPipelineCreateInfo`, the pointers in
:c: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
:c: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.
:cpp:func:`vk_graphics_pipeline_state_fill()` automatically handles both
:c:func:`vk_graphics_pipeline_state_fill()` automatically handles both
the render pass and dynamic rendering. For drivers which use
:cpp:struct:`vk_render_pass`, the :cpp:struct:`vk_render_pass_state`
:c:struct:`vk_render_pass`, the :c:struct:`vk_render_pass_state`
structure will be populated as if for dynamic rendering, regardless of
which path is used. Drivers which use their own render pass structure
should parse the render pass, if available, and pass a
:cpp:struct:`vk_render_pass_state` to the `driver_rp` argument of
:cpp:func:`vk_graphics_pipeline_state_fill()` with the relevant information
:c:struct:`vk_render_pass_state` to the `driver_rp` argument of
:c:func:`vk_graphics_pipeline_state_fill()` with the relevant information
from the specified subpass. If a render pass is available,
:cpp:struct:`vk_render_pass_state` will be populated with the
the information from the :cpp:struct:`driver_rp`. If dynamic
:c:struct:`vk_render_pass_state` will be populated with the
the information from the :c:struct:`driver_rp`. If dynamic
rendering is used or the driver provides a `NULL`
:cpp:struct:`driver_rp`, the :cpp:struct:`vk_render_pass_state`
:c:struct:`driver_rp`, the :c:struct:`vk_render_pass_state`
structure will be populated for dynamic rendering, including color, depth,
and stencil attachment formats.
@@ -52,7 +52,7 @@ like this:
/* Emit stuff using the state in `state` */
The :cpp:struct:`vk_graphics_pipeline_all_state` structure exists to allow
The :c: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
@@ -78,8 +78,8 @@ library pipeline.
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
:c:func:`vk_graphics_pipeline_state_merge`.
:c: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:
@@ -96,9 +96,11 @@ together but store the final state on the stack for immediate consumption:
vk_graphics_pipeline_state_fill(&device->vk, &state, pCreateInfo,
NULL, &all, NULL, 0, NULL);
.. doxygenfunction:: vk_graphics_pipeline_state_fill
.. c:autofunction:: vk_graphics_pipeline_state_fill
:file: src/vulkan/runtime/vk_graphics_state.h
.. doxygenfunction:: vk_graphics_pipeline_state_merge
.. c:autofunction:: vk_graphics_pipeline_state_merge
:file: src/vulkan/runtime/vk_graphics_state.h
Dynamic state
@@ -106,32 +108,39 @@ Dynamic state
All dynamic states in Vulkan, regardless of which API version or extension
introduced them, are represented by the
:cpp:enum:`mesa_vk_dynamic_graphics_state` enum. This corresponds to the
:cpp:type:`VkDynamicState` enum in the Vulkan API only it's compact (has no
:c:enum:`mesa_vk_dynamic_graphics_state` enum. This corresponds to the
:c:type:`VkDynamicState` enum in the Vulkan API only it's compact (has no
holes due to extension namespacing) and a bit better organized. Each
enumerant is named with the name of the state group to which the dynamic
state belongs as well as the name of the dynamic state itself. The fact
that it's compact allows us to use to index bitsets.
.. doxygenfunction:: vk_get_dynamic_graphics_states
.. c:autofunction:: vk_get_dynamic_graphics_states
:file: src/vulkan/runtime/vk_graphics_state.h
We also provide a :cpp:struct:`vk_dynamic_graphics_state` structure which
We also provide a :c:struct:`vk_dynamic_graphics_state` structure which
contains all the dynamic graphics states, regardless of which API version
or extension introduced them. This structure can be populated from a
:cpp:struct:`vk_graphics_pipeline_state` via
:cpp:func:`vk_dynamic_graphics_state_init`.
:c:struct:`vk_graphics_pipeline_state` via
:c:func:`vk_dynamic_graphics_state_init`.
.. doxygenfunction:: vk_dynamic_graphics_state_init
.. doxygenfunction:: vk_dynamic_graphics_state_copy
.. c:autofunction:: vk_dynamic_graphics_state_init
:file: src/vulkan/runtime/vk_graphics_state.h
There is also a :cpp:struct:`vk_dynamic_graphics_state` embedded in
:cpp:struct:`vk_command_buffer`. Should you choose to use them, we provide
.. c:autofunction:: vk_dynamic_graphics_state_copy
:file: src/vulkan/runtime/vk_graphics_state.h
There is also a :c:struct:`vk_dynamic_graphics_state` embedded in
:c:struct:`vk_command_buffer`. Should you choose to use them, we provide
common implementations for all ``vkCmdSet*()`` functions. Two additional
functions are provided for the driver to call in ``CmdBindPipeline()`` and
``CmdBindVertexBuffers2()``:
.. doxygenfunction:: vk_cmd_set_dynamic_graphics_state
.. doxygenfunction:: vk_cmd_set_vertex_binding_strides
.. c:autofunction:: vk_cmd_set_dynamic_graphics_state
:file: src/vulkan/runtime/vk_graphics_state.h
.. c:autofunction:: vk_cmd_set_vertex_binding_strides
:file: src/vulkan/runtime/vk_graphics_state.h
To use the dynamic state framework, you will need the following in your
pipeline structure:
@@ -193,69 +202,93 @@ Any states used by the currently bound pipeline and attachments are always
valid in ``vk_command_buffer::dynamic_graphics_state`` so you can always
use a state even if it isn't dirty on this particular draw.
.. doxygenfunction:: vk_dynamic_graphics_state_dirty_all
.. doxygenfunction:: vk_dynamic_graphics_state_clear_dirty
.. doxygenfunction:: vk_dynamic_graphics_state_any_dirty
.. c:autofunction:: vk_dynamic_graphics_state_dirty_all
:file: src/vulkan/runtime/vk_graphics_state.h
.. c:autofunction:: vk_dynamic_graphics_state_clear_dirty
:file: src/vulkan/runtime/vk_graphics_state.h
.. c:autofunction:: vk_dynamic_graphics_state_any_dirty
:file: src/vulkan/runtime/vk_graphics_state.h
Depth stencil state optimization
--------------------------------
.. doxygenfunction:: vk_optimize_depth_stencil_state
.. c:autofunction:: vk_optimize_depth_stencil_state
:file: src/vulkan/runtime/vk_graphics_state.h
Reference
---------
.. doxygenstruct:: vk_graphics_pipeline_state
.. c:autostruct:: vk_graphics_pipeline_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_vertex_binding_state
.. c:autostruct:: vk_vertex_binding_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_vertex_attribute_state
.. c:autostruct:: vk_vertex_attribute_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_vertex_input_state
.. c:autostruct:: vk_vertex_input_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_input_assembly_state
.. c:autostruct:: vk_input_assembly_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_tessellation_state
.. c:autostruct:: vk_tessellation_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_viewport_state
.. c:autostruct:: vk_viewport_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_discard_rectangles_state
.. c:autostruct:: vk_discard_rectangles_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_rasterization_state
.. c:autostruct:: vk_rasterization_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_fragment_shading_rate_state
.. c:autostruct:: vk_fragment_shading_rate_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_sample_locations_state
.. c:autostruct:: vk_sample_locations_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_multisample_state
.. c:autostruct:: vk_multisample_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_stencil_test_face_state
.. c:autostruct:: vk_stencil_test_face_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_depth_stencil_state
.. c:autostruct:: vk_depth_stencil_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_color_blend_state
.. c:autostruct:: vk_color_blend_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenstruct:: vk_render_pass_state
.. c:autostruct:: vk_render_pass_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:
.. doxygenenum:: mesa_vk_dynamic_graphics_state
.. c:autoenum:: mesa_vk_dynamic_graphics_state
:file: src/vulkan/runtime/vk_graphics_state.h
.. doxygenstruct:: vk_dynamic_graphics_state
.. c:autostruct:: vk_dynamic_graphics_state
:file: src/vulkan/runtime/vk_graphics_state.h
:members:

64
docs/vulkan/renderpass.rst
View File

@@ -14,25 +14,25 @@ old Vulkan 1.0 entrypoints. If a driver does not implement them, the
following will be implemented in common code in terms of their
:ext:`VK_KHR_create_renderpass2` counterparts:
- :cpp:func:`vkCreateRenderPass`
- :cpp:func:`vkCmdBeginRenderPass`
- :cpp:func:`vkCmdNextSubpass`
- :cpp:func:`vkCmdEndRenderPass`
- :c:func:`vkCreateRenderPass`
- :c:func:`vkCmdBeginRenderPass`
- :c:func:`vkCmdNextSubpass`
- :c:func:`vkCmdEndRenderPass`
Common VkRenderPass implementation
----------------------------------
The Vulkan runtime code in Mesa provides a common implementation of
:cpp:type:`VkRenderPass` called :cpp:struct:`vk_render_pass` which drivers
:c:type:`VkRenderPass` called :c:struct:`vk_render_pass` which drivers
can optionally use. Unlike most Vulkan runtime structs, it's not really
designed to be used as a base for a driver-specific struct. It does,
however, contain all the information passed to
:cpp:func:`vkCreateRenderPass2` so it can be used in a driver so long as
:c:func:`vkCreateRenderPass2` so it can be used in a driver so long as
that driver doesn't need to do any additional compilation at
:cpp:func:`vkCreateRenderPass2` time. If a driver chooses to use
:cpp:struct:`vk_render_pass`, the Vulkan runtime provides implementations
of :cpp:func:`vkCreateRenderPass2` and :cpp:func:`vkDestroyRenderPass`.
:c:func:`vkCreateRenderPass2` time. If a driver chooses to use
:c:struct:`vk_render_pass`, the Vulkan runtime provides implementations
of :c:func:`vkCreateRenderPass2` and :c:func:`vkDestroyRenderPass`.
:ext:`VK_KHR_dynamic_rendering`
@@ -42,40 +42,43 @@ For drivers which don't need to do subpass combining, it is recommended
that they skip implementing render passes entirely and implement
:ext:`VK_KHR_dynamic_rendering` instead. If they choose to do so, the runtime
will provide the following, implemented in terms of
:cpp:func:`vkCmdBeginRendering` and :cpp:func:`vkCmdEndRendering`:
:c:func:`vkCmdBeginRendering` and :c:func:`vkCmdEndRendering`:
- :cpp:func:`vkCmdBeginRenderPass2`
- :cpp:func:`vkCmdNextSubpass2`
- :cpp:func:`vkCmdEndRenderPass2`
- :c:func:`vkCmdBeginRenderPass2`
- :c:func:`vkCmdNextSubpass2`
- :c:func:`vkCmdEndRenderPass2`
We also provide a no-op implementation of
:cpp:func:`vkGetRenderAreaGranularity` which returns a render area
:c:func:`vkGetRenderAreaGranularity` which returns a render area
granularity of 1x1.
Drivers which wish to use the common render pass implementation in this way
**must** also support a Mesa-specific pseudo-extension which optionally
provides an initial image layout for each attachment at
:cpp:func:`vkCmdBeginRendering` time. This is required for us to combine
:c:func:`vkCmdBeginRendering` time. This is required for us to combine
render pass clears with layout transitions, often from
:cpp:enum:`VK_IMAGE_LAYOUT_UNDEFINED`. On at least Intel and AMD,
:c:enum:`VK_IMAGE_LAYOUT_UNDEFINED`. On at least Intel and AMD,
combining these transitions with clears is important for performance.
.. doxygenstruct:: VkRenderingAttachmentInitialLayoutInfoMESA
.. c:autostruct:: VkRenderingAttachmentInitialLayoutInfoMESA
:file: src/vulkan/runtime/vk_render_pass.h
:members:
Because render passes and subpass indices are also passed into
:cpp:func:`vkCmdCreateGraphicsPipelines` and
:cpp:func:`vkCmdExecuteCommands` which we can't implement on the driver's
:c:func:`vkCmdCreateGraphicsPipelines` and
:c:func:`vkCmdExecuteCommands` which we can't implement on the driver's
behalf, we provide a couple of helpers for getting the render pass
information in terms of the relevant :ext:`VK_KHR_dynamic_rendering`:
.. doxygenfunction:: vk_get_pipeline_rendering_create_info
.. c:autofunction:: vk_get_pipeline_rendering_create_info
:file: src/vulkan/runtime/vk_render_pass.h
.. doxygenfunction:: vk_get_command_buffer_inheritance_rendering_info
.. c:autofunction:: vk_get_command_buffer_inheritance_rendering_info
:file: src/vulkan/runtime/vk_render_pass.h
Apart from handling layout transitions, the common render pass
implementation mostly ignores input attachments. It is expected that the
driver call :cpp:func:`nir_lower_input_attachments` to turn them into
driver call :c:func:`nir_lower_input_attachments` to turn them into
texturing operations. The driver **must** support texturing from an input
attachment at the same time as rendering to it in order to support Vulkan
subpass self-dependencies. ``VK_EXT_attachment_feedback_loop_layout`` provides
@@ -84,20 +87,25 @@ information on when these self dependencies are present.
vk_render_pass reference
------------------------
The following is a reference for the :cpp:struct:`vk_render_pass` structure
The following is a reference for the :c:struct:`vk_render_pass` structure
and its substructures.
.. doxygenstruct:: vk_render_pass
.. c:autostruct:: vk_render_pass
:file: src/vulkan/runtime/vk_render_pass.h
:members:
.. doxygenstruct:: vk_render_pass_attachment
.. c:autostruct:: vk_render_pass_attachment
:file: src/vulkan/runtime/vk_render_pass.h
:members:
.. doxygenstruct:: vk_subpass
.. c:autostruct:: vk_subpass
:file: src/vulkan/runtime/vk_render_pass.h
:members:
.. doxygenstruct:: vk_subpass_attachment
.. c:autostruct:: vk_subpass_attachment
:file: src/vulkan/runtime/vk_render_pass.h
:members:
.. doxygenstruct:: vk_subpass_dependency
.. c:autostruct:: vk_subpass_dependency
:file: src/vulkan/runtime/vk_render_pass.h
:members:

9
src/vulkan/runtime/vk_command_buffer.h
View File

@@ -60,6 +60,7 @@ struct vk_attachment_state {
VkClearValue clear_value;
};
/** Command buffer ops */
struct vk_command_buffer_ops {
/** Creates a command buffer
*
@@ -147,11 +148,11 @@ struct vk_command_buffer {
* call. This means that there can be no more than one such label at a
* time.
*
* \c labels contains all active labels at this point in order of submission
* \c region_begin denotes whether the most recent label opens a new region
* If \t labels is empty \t region_begin must be true.
* ``labels`` contains all active labels at this point in order of
* submission ``region_begin`` denotes whether the most recent label opens
* a new region If ``labels`` is empty ``region_begin`` must be true.
*
* Anytime we modify labels, we first check for \c region_begin. If it's
* Anytime we modify labels, we first check for ``region_begin``. If it's
* false, it means that the most recent label was submitted by
* `*InsertDebugUtilsLabel` and we need to remove it before doing anything
* else.

18
src/vulkan/runtime/vk_command_pool.h
View File

@@ -62,12 +62,12 @@ VK_DEFINE_NONDISP_HANDLE_CASTS(vk_command_pool, base, VkCommandPool,
/** Initialize a vk_command_pool
*
* @param[in] device The Vulkan device
* @param[out] pool The command pool to initialize
* @param[in] pCreateInfo VkCommandPoolCreateInfo pointer passed to
* `vkCreateCommandPool()`
* @param[in] pAllocator Allocation callbacks passed to
* `vkCreateCommandPool()`
* :param device: |in| The Vulkan device
* :param pool: |out| The command pool to initialize
* :param pCreateInfo: |in| VkCommandPoolCreateInfo pointer passed to
* `vkCreateCommandPool()`
* :param pAllocator: |in| Allocation callbacks passed to
* `vkCreateCommandPool()`
*/
VkResult MUST_CHECK
vk_command_pool_init(struct vk_device *device,
@@ -77,7 +77,7 @@ vk_command_pool_init(struct vk_device *device,
/** Tear down a vk_command_pool
*
* @param[inout] pool The command pool to tear down
* :param pool: |inout| The command pool to tear down
*/
void
vk_command_pool_finish(struct vk_command_pool *pool);
@@ -90,8 +90,8 @@ vk_command_pool_finish(struct vk_command_pool *pool);
* should be called before doing any driver-specific trimming in case it ends
* up returning driver-internal resources to the pool.
*
* @param[inout] pool The command pool to trim
* @param[in] flags Flags controling the trim operation
* :param pool: |inout| The command pool to trim
* :param flags: |in| Flags controling the trim operation
*/
void
vk_command_pool_trim(struct vk_command_pool *pool,

30
src/vulkan/runtime/vk_device.h
View File

@@ -44,8 +44,8 @@ enum vk_queue_submit_mode {
/** Submits happen immediately
*
* `vkQueueSubmit()` and `vkQueueBindSparse()` call
* `vk_queue::driver_submit` directly for all submits and the last call to
* `vk_queue::driver_submit` will have completed by the time
* ``vk_queue::driver_submit`` directly for all submits and the last call to
* ``vk_queue::driver_submit`` will have completed by the time
* `vkQueueSubmit()` or `vkQueueBindSparse()` return.
*/
VK_QUEUE_SUBMIT_MODE_IMMEDIATE,
@@ -73,7 +73,7 @@ enum vk_queue_submit_mode {
* semaphores after waiting on them.
*
* 3. All vk_sync types used as permanent payloads of semaphores support
* `vk_sync_type::move` so that it can move the pending signal into a
* ``vk_sync_type::move`` so that it can move the pending signal into a
* temporary vk_sync and reset the semaphore.
*
* This is requied for shared timeline semaphores where we need to handle
@@ -156,7 +156,7 @@ struct vk_device {
/** Checks the status of this device
*
* This is expected to return either VK_SUCCESS or VK_ERROR_DEVICE_LOST.
* It is called before vk_queue::driver_submit and after every non-trivial
* It is called before ``vk_queue::driver_submit`` and after every non-trivial
* wait operation to ensure the device is still around. This gives the
* driver a hook to ask the kernel if its device is still valid. If the
* kernel says the device has been lost, it MUST call vk_device_set_lost().
@@ -173,10 +173,10 @@ struct vk_device {
* anyway.
*
* If `signal_memory` is set, the resulting vk_sync will be used to signal
* the memory object from a queue via vk_queue_submit::signals. The common
* the memory object from a queue ``via vk_queue_submit::signals``. The common
* code guarantees that, by the time vkQueueSubmit() returns, the signal
* operation has been submitted to the kernel via the driver's
* vk_queue::driver_submit hook. This means that any vkQueueSubmit() call
* ``vk_queue::driver_submit`` hook. This means that any vkQueueSubmit() call
* which needs implicit synchronization may block.
*
* If `signal_memory` is not set, it can be assumed that memory object
@@ -269,20 +269,20 @@ VK_DEFINE_HANDLE_CASTS(vk_device, base, VkDevice,
*
* Along with initializing the data structures in `vk_device`, this function
* checks that every extension specified by
* `VkInstanceCreateInfo::ppEnabledExtensionNames` is actually supported by
* ``VkInstanceCreateInfo::ppEnabledExtensionNames`` is actually supported by
* the physical device and returns `VK_ERROR_EXTENSION_NOT_PRESENT` if an
* unsupported extension is requested. It also checks all the feature struct
* chained into the `pCreateInfo->pNext` chain against the features returned
* by `vkGetPhysicalDeviceFeatures2` and returns
* `VK_ERROR_FEATURE_NOT_PRESENT` if an unsupported feature is requested.
*
* @param[out] device The device to initialize
* @param[in] physical_device The physical device
* @param[in] dispatch_table Device-level dispatch table
* @param[in] pCreateInfo VkDeviceCreateInfo pointer passed to
* `vkCreateDevice()`
* @param[in] alloc Allocation callbacks passed to
* `vkCreateDevice()`
* :param device: |out| The device to initialize
* :param physical_device: |in| The physical device
* :param dispatch_table: |in| Device-level dispatch table
* :param pCreateInfo: |in| VkDeviceCreateInfo pointer passed to
* `vkCreateDevice()`
* :param alloc: |in| Allocation callbacks passed to
* `vkCreateDevice()`
*/
VkResult MUST_CHECK
vk_device_init(struct vk_device *device,
@@ -299,7 +299,7 @@ vk_device_set_drm_fd(struct vk_device *device, int drm_fd)
/** Tears down a vk_device
*
* @param[out] device The device to tear down
* :param device: |out| The device to tear down
*/
void
vk_device_finish(struct vk_device *device);

110
src/vulkan/runtime/vk_graphics_state.h
View File

@@ -113,13 +113,14 @@ enum mesa_vk_dynamic_graphics_state {
* This function maps a VkPipelineDynamicStateCreateInfo to a bitset indexed
* by mesa_vk_dynamic_graphics_state enumerants.
*
* @param[out] dynamic Bitset to populate
* @param[in] info VkPipelineDynamicStateCreateInfo or NULL
* :param dynamic: |out| Bitset to populate
* :param info: |in| VkPipelineDynamicStateCreateInfo or NULL
*/
void
vk_get_dynamic_graphics_states(BITSET_WORD *dynamic,
const VkPipelineDynamicStateCreateInfo *info);
/***/
struct vk_vertex_binding_state {
/** VkVertexInputBindingDescription::stride */
uint16_t stride;
@@ -131,6 +132,7 @@ struct vk_vertex_binding_state {
uint32_t divisor;
};
/***/
struct vk_vertex_attribute_state {
/** VkVertexInputAttributeDescription::binding */
uint32_t binding;
@@ -142,6 +144,7 @@ struct vk_vertex_attribute_state {
uint32_t offset;
};
/***/
struct vk_vertex_input_state {
/** Bitset of which bindings are valid, indexed by binding */
uint32_t bindings_valid;
@@ -152,6 +155,7 @@ struct vk_vertex_input_state {
struct vk_vertex_attribute_state attributes[MESA_VK_MAX_VERTEX_ATTRIBUTES];
};
/***/
struct vk_input_assembly_state {
/** VkPipelineInputAssemblyStateCreateInfo::topology
*
@@ -166,6 +170,7 @@ struct vk_input_assembly_state {
bool primitive_restart_enable;
};
/***/
struct vk_tessellation_state {
/** VkPipelineTessellationStateCreateInfo::patchControlPoints
*
@@ -180,6 +185,7 @@ struct vk_tessellation_state {
uint8_t domain_origin;
};
/***/
struct vk_viewport_state {
/** VkPipelineViewportDepthClipControlCreateInfoEXT::negativeOneToOne
*/
@@ -210,6 +216,7 @@ struct vk_viewport_state {
VkRect2D scissors[MESA_VK_MAX_SCISSORS];
};
/***/
struct vk_discard_rectangles_state {
/** VkPipelineDiscardRectangleStateCreateInfoEXT::discardRectangleMode */
VkDiscardRectangleModeEXT mode;
@@ -232,6 +239,7 @@ enum ENUM_PACKED vk_mesa_depth_clip_enable {
VK_MESA_DEPTH_CLIP_ENABLE_NOT_CLAMP,
};
/***/
struct vk_rasterization_state {
/** VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable
*
@@ -385,6 +393,7 @@ vk_rasterization_state_depth_clip_enable(const struct vk_rasterization_state *rs
unreachable("Invalid depth clip enable");
}
/***/
struct vk_fragment_shading_rate_state {
/** VkPipelineFragmentShadingRateStateCreateInfoKHR::fragmentSize
*
@@ -399,6 +408,7 @@ struct vk_fragment_shading_rate_state {
VkFragmentShadingRateCombinerOpKHR combiner_ops[2];
};
/***/
struct vk_sample_locations_state {
/** VkSampleLocationsInfoEXT::sampleLocationsPerPixel */
VkSampleCountFlagBits per_pixel;
@@ -410,6 +420,7 @@ struct vk_sample_locations_state {
VkSampleLocationEXT locations[MESA_VK_MAX_SAMPLE_LOCATIONS];
};
/***/
struct vk_multisample_state {
/** VkPipelineMultisampleStateCreateInfo::rasterizationSamples */
VkSampleCountFlagBits rasterization_samples;
@@ -480,6 +491,7 @@ struct vk_stencil_test_face_state {
uint8_t reference;
};
/***/
struct vk_depth_stencil_state {
struct {
/** VkPipelineDepthStencilStateCreateInfo::depthTestEnable
@@ -550,12 +562,12 @@ struct vk_depth_stencil_state {
* hit. This function attempts to optimize the depth stencil state and
* disable writes and sometimes even testing whenever possible.
*
* @param[inout] ds The depth stencil state to optimize
* @param[in] ds_aspects Which image aspects are present in the
* render pass.
* @param[in] consider_write_mask If true, the write mask will be taken
* into account when optimizing. If
* false, it will be ignored.
* :param ds: |inout| The depth stencil state to optimize
* :param ds_aspects: |in| Which image aspects are present in the
* render pass.
* :param consider_write_mask: |in| If true, the write mask will be taken
* into account when optimizing. If
* false, it will be ignored.
*/
void vk_optimize_depth_stencil_state(struct vk_depth_stencil_state *ds,
VkImageAspectFlags ds_aspects,
@@ -613,6 +625,7 @@ struct vk_color_blend_attachment_state {
VkBlendOp alpha_blend_op;
};
/***/
struct vk_color_blend_state {
/** VkPipelineColorBlendStateCreateInfo::logicOpEnable
*
@@ -650,6 +663,7 @@ struct vk_color_blend_state {
float blend_constants[4];
};
/***/
struct vk_render_pass_state {
/** Set of image aspects bound as color/depth/stencil attachments
*
@@ -827,6 +841,7 @@ struct vk_dynamic_graphics_state {
BITSET_DECLARE(dirty, MESA_VK_DYNAMIC_GRAPHICS_STATE_ENUM_MAX);
};
/***/
struct vk_graphics_pipeline_all_state {
struct vk_vertex_input_state vi;
struct vk_input_assembly_state ia;
@@ -842,6 +857,7 @@ struct vk_graphics_pipeline_all_state {
struct vk_render_pass_state rp;
};
/***/
struct vk_graphics_pipeline_state {
/** Bitset of which states are dynamic */
BITSET_DECLARE(dynamic, MESA_VK_DYNAMIC_GRAPHICS_STATE_ENUM_MAX);
@@ -905,24 +921,24 @@ struct vk_graphics_pipeline_state {
* to this new blob of memory is returned via `alloc_ptr_out` and must
* eventually be freed by the driver.
*
* @param[in] device The Vulkan device
* @param[out] state The graphics pipeline state to populate
* @param[in] info The pCreateInfo from vkCreateGraphicsPipelines
* @param[in] driver_rp Renderpass state if the driver implements render
* :param device: |in| The Vulkan device
* :param state: |out| The graphics pipeline state to populate
* :param info: |in| The pCreateInfo from vkCreateGraphicsPipelines
* :param driver_rp: |in| Renderpass state if the driver implements render
* passes itself. This should be NULL for drivers
* that use the common render pass infrastructure
* built on top of dynamic rendering.
* @param[in] all The vk_graphics_pipeline_all_state to use to
* :param all: |in| The vk_graphics_pipeline_all_state to use to
* back any newly needed states. If NULL, newly
* needed states will be dynamically allocated
* instead.
* @param[in] alloc Allocation callbacks for dynamically allocating
* :param alloc: |in| Allocation callbacks for dynamically allocating
* new state memory.
* @param[in] scope Allocation scope for dynamically allocating new
* :param scope: |in| Allocation scope for dynamically allocating new
* state memory.
* @param[out] alloc_ptr_out Will be populated with a pointer to any newly
* allocated state. The driver is responsible for
* freeing this pointer.
* :param alloc_ptr_out: |out| Will be populated with a pointer to any newly
* allocated state. The driver is responsible for
* freeing this pointer.
*/
VkResult
vk_graphics_pipeline_state_fill(const struct vk_device *device,
@@ -968,16 +984,16 @@ vk_graphics_pipeline_state_fill(const struct vk_device *device,
*
* In this case we will avoid allocating memory for `library->state.foo`.
*
* @param[in] device The Vulkan device
* @param[out] state The graphics pipeline state to populate
* @param[in] old_state The graphics pipeline state to copy from
* @param[in] alloc Allocation callbacks for dynamically allocating
* :param device: |in| The Vulkan device
* :param state: |out| The graphics pipeline state to populate
* :param old_state: |in| The graphics pipeline state to copy from
* :param alloc: |in| Allocation callbacks for dynamically allocating
* new state memory.
* @param[in] scope Allocation scope for dynamically allocating new
* :param scope: |in| Allocation scope for dynamically allocating new
* state memory.
* @param[out] alloc_ptr_out Will be populated with a pointer to any newly
* allocated state. The driver is responsible for
* freeing this pointer.
* :param alloc_ptr_out: |out| Will be populated with a pointer to any newly
* allocated state. The driver is responsible for
* freeing this pointer.
*/
VkResult
vk_graphics_pipeline_state_copy(const struct vk_device *device,
@@ -995,9 +1011,9 @@ vk_graphics_pipeline_state_copy(const struct vk_device *device,
* The only exception here is render pass state which may be only partially
* defined in which case the fully defined one (if any) is used.
*
* @param[out] dst The destination state. When the function returns, this
* will be the union of the original dst and src.
* @param[in] src The source state
* :param dst: |out| The destination state. When the function returns, this
* will be the union of the original dst and src.
* :param src: |in| The source state
*/
void
vk_graphics_pipeline_state_merge(struct vk_graphics_pipeline_state *dst,
@@ -1015,24 +1031,24 @@ extern const struct vk_dynamic_graphics_state vk_default_dynamic_graphics_state;
/** Initialize a vk_dynamic_graphics_state with defaults
*
* @param[out] dyn Dynamic graphics state to initizlie
* :param dyn: |out| Dynamic graphics state to initizlie
*/
void
vk_dynamic_graphics_state_init(struct vk_dynamic_graphics_state *dyn);
/** Clear a vk_dynamic_graphics_state to defaults
*
* @param[out] dyn Dynamic graphics state to initizlie
* :param dyn: |out| Dynamic graphics state to initizlie
*/
void
vk_dynamic_graphics_state_clear(struct vk_dynamic_graphics_state *dyn);
/** Initialize a vk_dynamic_graphics_state for a pipeline
*
* @param[out] dyn Dynamic graphics state to initizlie
* @param[in] supported Bitset of all dynamic state supported by the driver.
* @param[in] p The pipeline state from which to initialize the
* dynamic state.
* :param dyn: |out| Dynamic graphics state to initizlie
* :param supported: |in| Bitset of all dynamic state supported by the driver.
* :param p: |in| The pipeline state from which to initialize the
* dynamic state.
*/
void
vk_dynamic_graphics_state_fill(struct vk_dynamic_graphics_state *dyn,
@@ -1040,7 +1056,7 @@ vk_dynamic_graphics_state_fill(struct vk_dynamic_graphics_state *dyn,
/** Mark all states in the given vk_dynamic_graphics_state dirty
*
* @param[out] d Dynamic graphics state struct
* :param d: |out| Dynamic graphics state struct
*/
static inline void
vk_dynamic_graphics_state_dirty_all(struct vk_dynamic_graphics_state *d)
@@ -1050,7 +1066,7 @@ vk_dynamic_graphics_state_dirty_all(struct vk_dynamic_graphics_state *d)
/** Mark all states in the given vk_dynamic_graphics_state not dirty
*
* @param[out] d Dynamic graphics state struct
* :param d: |out| Dynamic graphics state struct
*/
static inline void
vk_dynamic_graphics_state_clear_dirty(struct vk_dynamic_graphics_state *d)
@@ -1060,8 +1076,8 @@ vk_dynamic_graphics_state_clear_dirty(struct vk_dynamic_graphics_state *d)
/** Test if any states in the given vk_dynamic_graphics_state are dirty
*
* @param[in] d Dynamic graphics state struct to test
* @returns true if any state is dirty
* :param d: |in| Dynamic graphics state struct to test
* :returns: true if any state is dirty
*/
static inline bool
vk_dynamic_graphics_state_any_dirty(const struct vk_dynamic_graphics_state *d)
@@ -1076,8 +1092,8 @@ vk_dynamic_graphics_state_any_dirty(const struct vk_dynamic_graphics_state *d)
* structs. Anything not set in src, as indicated by src->set, is ignored and
* those bits of dst are left untouched.
*
* @param[out] dst Copy destination
* @param[in] src Copy source
* :param dst: |out| Copy destination
* :param src: |in| Copy source
*/
void
vk_dynamic_graphics_state_copy(struct vk_dynamic_graphics_state *dst,
@@ -1088,8 +1104,8 @@ vk_dynamic_graphics_state_copy(struct vk_dynamic_graphics_state *dst,
* Anything not set, as indicated by src->set, is ignored and those states in
* the command buffer are left untouched.
*
* @param[inout] cmd Command buffer to update
* @param[in] src State to set
* :param cmd: |inout| Command buffer to update
* :param src: |in| State to set
*/
void
vk_cmd_set_dynamic_graphics_state(struct vk_command_buffer *cmd,
@@ -1099,10 +1115,10 @@ vk_cmd_set_dynamic_graphics_state(struct vk_command_buffer *cmd,
*
* This is the dynamic state part of vkCmdBindVertexBuffers2().
*
* @param[inout] cmd Command buffer to update
* @param[in] first_binding First binding to update
* @param[in] binding_count Number of bindings to update
* @param[in] strides binding_count many stride values to set
* :param cmd: |inout| Command buffer to update
* :param first_binding: |in| First binding to update
* :param binding_count: |in| Number of bindings to update
* :param strides: |in| binding_count many stride values to set
*/
void
vk_cmd_set_vertex_binding_strides(struct vk_command_buffer *cmd,

20
src/vulkan/runtime/vk_instance.h
View File

@@ -183,18 +183,18 @@ VK_DEFINE_HANDLE_CASTS(vk_instance, base, VkInstance,
* Along with initializing the data structures in `vk_instance`, this function
* validates the Vulkan version number provided by the client and checks that
* every extension specified by
* `VkInstanceCreateInfo::ppEnabledExtensionNames` is actually supported by
* ``VkInstanceCreateInfo::ppEnabledExtensionNames`` is actually supported by
* the implementation and returns `VK_ERROR_EXTENSION_NOT_PRESENT` if an
* unsupported extension is requested.
*
* @param[out] instance The instance to initialize
* @param[in] supported_extensions Table of all instance extensions supported
* by this instance
* @param[in] dispatch_table Instance-level dispatch table
* @param[in] pCreateInfo VkInstanceCreateInfo pointer passed to
* `vkCreateInstance()`
* @param[in] alloc Allocation callbacks used to create this
* instance; must not be `NULL`
* :param instance: |out| The instance to initialize
* :param supported_extensions: |in| Table of all instance extensions supported
* by this instance
* :param dispatch_table: |in| Instance-level dispatch table
* :param pCreateInfo: |in| VkInstanceCreateInfo pointer passed to
* `vkCreateInstance()`
* :param alloc: |in| Allocation callbacks used to create this
* instance; must not be `NULL`
*/
VkResult MUST_CHECK
vk_instance_init(struct vk_instance *instance,
@@ -205,7 +205,7 @@ vk_instance_init(struct vk_instance *instance,
/** Tears down a vk_instance
*
* @param[out] instance The instance to tear down
* :param instance: |out| The instance to tear down
*/
void
vk_instance_finish(struct vk_instance *instance);

50
src/vulkan/runtime/vk_object.h
View File

@@ -69,9 +69,9 @@ struct vk_object_base {
/** Initialize a vk_base_object
*
* @param[in] device The vk_device this object was created from or NULL
* @param[out] base The vk_object_base to initialize
* @param[in] obj_type The VkObjectType of the object being initialized
* :param device: |in| The vk_device this object was created from or NULL
* :param base: |out| The vk_object_base to initialize
* :param obj_type: |in| The VkObjectType of the object being initialized
*/
void vk_object_base_init(struct vk_device *device,
struct vk_object_base *base,
@@ -79,7 +79,7 @@ void vk_object_base_init(struct vk_device *device,
/** Tear down a vk_object_base
*
* @param[out] base The vk_object_base being torn down
* :param base: |out| The vk_object_base being torn down
*/
void vk_object_base_finish(struct vk_object_base *base);
@@ -90,7 +90,7 @@ void vk_object_base_finish(struct vk_object_base *base);
* long as it's called between when the client thinks the object was destroyed
* and when the client sees it again as a supposedly new object.
*
* @param[inout] base The vk_object_base being recycled
* :param base: |inout| The vk_object_base being recycled
*/
void vk_object_base_recycle(struct vk_object_base *base);
@@ -118,16 +118,16 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
* `VkObjectType` to assert that the object is of the correct type when
* running with a debug build.
*
* @param __driver_type The name of the driver struct; it is assumed this is
* the name of a struct type and `struct` will be
* prepended automatically
* :param __driver_type: The name of the driver struct; it is assumed this is
* the name of a struct type and ``struct`` will be
* prepended automatically
*
* @param __base The name of the vk_base_object member
* :param __base: The name of the vk_base_object member
*
* @param __VkType The Vulkan object type such as VkImage
* :param __VkType: The Vulkan object type such as VkImage
*
* @param __VK_TYPE The VkObjectType corresponding to __VkType, such as
* VK_OBJECT_TYPE_IMAGE
* :param __VK_TYPE: The VkObjectType corresponding to __VkType, such as
* VK_OBJECT_TYPE_IMAGE
*/
#define VK_DEFINE_HANDLE_CASTS(__driver_type, __base, __VkType, __VK_TYPE) \
static inline struct __driver_type * \
@@ -157,16 +157,16 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
* `VkObjectType` to assert that the object is of the correct type when
* running with a debug build.
*
* @param __driver_type The name of the driver struct; it is assumed this is
* the name of a struct type and `struct` will be
* prepended automatically
* :param __driver_type: The name of the driver struct; it is assumed this is
* the name of a struct type and ``struct`` will be
* prepended automatically
*
* @param __base The name of the vk_base_object member
* :param __base: The name of the vk_base_object member
*
* @param __VkType The Vulkan object type such as VkImage
* :param __VkType: The Vulkan object type such as VkImage
*
* @param __VK_TYPE The VkObjectType corresponding to __VkType, such as
* VK_OBJECT_TYPE_IMAGE
* :param __VK_TYPE: The VkObjectType corresponding to __VkType, such as
* VK_OBJECT_TYPE_IMAGE
*/
#define VK_DEFINE_NONDISP_HANDLE_CASTS(__driver_type, __base, __VkType, __VK_TYPE) \
UNUSED static inline struct __driver_type * \
@@ -190,14 +190,14 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
/** Declares a __driver_type pointer which represents __handle
*
* @param __driver_type The name of the driver struct; it is assumed this is
* the name of a struct type and `struct` will be
* prepended automatically
* :param __driver_type: The name of the driver struct; it is assumed this is
* the name of a struct type and ``struct`` will be
* prepended automatically
*
* @param __name The name of the declared pointer
* :param __name: The name of the declared pointer
*
* @param __handle The Vulkan object handle with which to initialize
* `__name`
* :param __handle: The Vulkan object handle with which to initialize
* `__name`
*/
#define VK_FROM_HANDLE(__driver_type, __name, __handle) \
struct __driver_type *__name = __driver_type ## _from_handle(__handle)

18
src/vulkan/runtime/vk_physical_device.h
View File

@@ -117,14 +117,14 @@ VK_DEFINE_HANDLE_CASTS(vk_physical_device, base, VkPhysicalDevice,
/** Initialize a vk_physical_device
*
* @param[out] physical_device The physical device to initialize
* @param[in] instance The instance which is the parent of this
* physical device
* @param[in] supported_extensions Table of all device extensions supported
* by this physical device
* @param[in] supported_features Table of all features supported by this
* physical device
* @param[in] dispatch_table Physical-device-level dispatch table
* :param physical_device: |out| The physical device to initialize
* :param instance: |in| The instance which is the parent of this
* physical device
* :param supported_extensions: |in| Table of all device extensions supported
* by this physical device
* :param supported_features: |in| Table of all features supported by this
* physical device
* :param dispatch_table: |in| Physical-device-level dispatch table
*/
VkResult MUST_CHECK
vk_physical_device_init(struct vk_physical_device *physical_device,
@@ -136,7 +136,7 @@ vk_physical_device_init(struct vk_physical_device *physical_device,
/** Tears down a vk_physical_device
*
* @param[out] physical_device The physical device to tear down
* :param physical_device: |out| The physical device to tear down
*/
void
vk_physical_device_finish(struct vk_physical_device *physical_device);

8
src/vulkan/runtime/vk_queue.h
View File

@@ -129,11 +129,11 @@ struct vk_queue {
* call. This means that there can be no more than one such label at a
* time.
*
* \c labels contains all active labels at this point in order of submission
* \c region_begin denotes whether the most recent label opens a new region
* If \t labels is empty \t region_begin must be true.
* ``labels`` contains all active labels at this point in order of
* submission ``region_begin`` denotes whether the most recent label opens
* a new region If ``labels`` is empty ``region_begin`` must be true.
*
* Anytime we modify labels, we first check for \c region_begin. If it's
* Anytime we modify labels, we first check for ``region_begin``. If it's
* false, it means that the most recent label was submitted by
* `*InsertDebugUtilsLabel` and we need to remove it before doing anything
* else.

27
src/vulkan/runtime/vk_render_pass.h
View File

@@ -60,6 +60,7 @@ typedef struct VkRenderingAttachmentInitialLayoutInfoMESA {
VkImageLayout initialLayout;
} VkRenderingAttachmentInitialLayoutInfoMESA;
/***/
struct vk_subpass_attachment {
/** VkAttachmentReference2::attachment */
uint32_t attachment;
@@ -101,6 +102,7 @@ struct vk_subpass_attachment {
struct vk_subpass_attachment *resolve;
};
/***/
struct vk_subpass {
/** Count of all attachments referenced by this subpass */
uint32_t attachment_count;
@@ -179,6 +181,7 @@ struct vk_subpass {
VkMultisampledRenderToSingleSampledInfoEXT mrtss;
};
/***/
struct vk_render_pass_attachment {
/** VkAttachmentDescription2::format */
VkFormat format;
@@ -230,6 +233,7 @@ struct vk_render_pass_attachment {
VkImageLayout final_stencil_layout;
};
/***/
struct vk_subpass_dependency {
/** VkSubpassDependency2::dependencyFlags */
VkDependencyFlags flags;
@@ -256,6 +260,7 @@ struct vk_subpass_dependency {
int32_t view_offset;
};
/***/
struct vk_render_pass {
struct vk_object_base base;
@@ -303,7 +308,7 @@ VK_DEFINE_NONDISP_HANDLE_CASTS(vk_render_pass, base, VkRenderPass,
* is VK_NULL_HANDLE and there is a VkPipelineRenderingCreateInfo in the pNext
* chain of VkGraphicsPipelineCreateInfo, it will return that.
*
* @param[in] info One of the pCreateInfos from vkCreateGraphicsPipelines
* :param info: |in| One of the pCreateInfos from vkCreateGraphicsPipelines
*/
const VkPipelineRenderingCreateInfo *
vk_get_pipeline_rendering_create_info(const VkGraphicsPipelineCreateInfo *info);
@@ -322,7 +327,7 @@ vk_get_pipeline_rendering_create_info(const VkGraphicsPipelineCreateInfo *info);
* If VkGraphicsPipelineCreateInfo::renderPass is VK_NULL_HANDLE, the relevant
* flags from VkGraphicsPipelineCreateInfo::flags will be returned.
*
* @param[in] info One of the pCreateInfos from vkCreateGraphicsPipelines
* :param info: |in| One of the pCreateInfos from vkCreateGraphicsPipelines
*/
VkPipelineCreateFlags
vk_get_pipeline_rendering_flags(const VkGraphicsPipelineCreateInfo *info);
@@ -337,7 +342,7 @@ vk_get_pipeline_rendering_flags(const VkGraphicsPipelineCreateInfo *info);
* is VK_NULL_HANDLE and there is a VkAttachmentSampleCountInfoAMD in the pNext
* chain of VkGraphicsPipelineCreateInfo, it will return that.
*
* @param[in] info One of the pCreateInfos from vkCreateGraphicsPipelines
* :param info: |in| One of the pCreateInfos from vkCreateGraphicsPipelines
*/
const VkAttachmentSampleCountInfoAMD *
vk_get_pipeline_sample_count_info_amd(const VkGraphicsPipelineCreateInfo *info);
@@ -355,8 +360,8 @@ vk_get_pipeline_sample_count_info_amd(const VkGraphicsPipelineCreateInfo *info);
* is a VkCommandBufferInheritanceRenderingInfo in the pNext chain of
* VkCommandBufferBeginInfo, it will return that.
*
* @param[in] level The nesting level of this command buffer
* @param[in] pBeginInfo The pBeginInfo from vkBeginCommandBuffer
* :param level: |in| The nesting level of this command buffer
* :param pBeginInfo: |in| The pBeginInfo from vkBeginCommandBuffer
*/
const VkCommandBufferInheritanceRenderingInfo *
vk_get_command_buffer_inheritance_rendering_info(
@@ -386,12 +391,12 @@ struct vk_gcbiarr_data {
* constructed due to a missing framebuffer or similar, NULL will be
* returned.
*
* @param[in] level The nesting level of this command buffer
* @param[in] pBeginInfo The pBeginInfo from vkBeginCommandBuffer
* @param[out] stack_data An opaque blob of data which will be overwritten by
* this function, passed in from the caller to avoid
* heap allocations. It must be at least
* VK_GCBIARR_DATA_SIZE(max_color_rts) bytes.
* :param level: |in| The nesting level of this command buffer
* :param pBeginInfo: |in| The pBeginInfo from vkBeginCommandBuffer
* :param stack_data: |out| An opaque blob of data which will be overwritten by
* this function, passed in from the caller to avoid
* heap allocations. It must be at least
* VK_GCBIARR_DATA_SIZE(max_color_rts) bytes.
*/
const VkRenderingInfo *
vk_get_command_buffer_inheritance_as_rendering_resume(