229 lines
8.8 KiB
Plaintext
229 lines
8.8 KiB
Plaintext
// This section is included inside the Debugging chapter (debugging.txt)
|
|
|
|
[[debugging-debug-markers]]
|
|
== Debug Markers
|
|
|
|
Debug markers provide a flexible way for debugging and validation layers to
|
|
receive annotation and debug information.
|
|
|
|
The <<debugging-object-annotation,Object Annotation>> section describes how
|
|
to associate a name or binary data with a Vulkan object.
|
|
|
|
The <<debugging-command-buffer-markers,Command Buffer Markers>> section
|
|
describes how to associate logical elements of the scene with commands in
|
|
the command buffer.
|
|
|
|
|
|
[[debugging-object-annotation]]
|
|
=== Object Annotation
|
|
|
|
The commands in this section allow application developers to associate
|
|
user-defined information with Vulkan objects at will.
|
|
|
|
[open,refpage='vkDebugMarkerSetObjectNameEXT',desc='Give a user-friendly name to an object',type='protos']
|
|
--
|
|
|
|
An object can be given a user-friendly name by calling:
|
|
|
|
include::{generated}/api/protos/vkDebugMarkerSetObjectNameEXT.txt[]
|
|
|
|
* pname:device is the device that created the object.
|
|
* pname:pNameInfo is a pointer to an instance of the
|
|
slink:VkDebugMarkerObjectNameInfoEXT structure specifying the parameters
|
|
of the name to set on the object.
|
|
|
|
include::{generated}/validity/protos/vkDebugMarkerSetObjectNameEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDebugMarkerObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs']
|
|
--
|
|
|
|
The sname:VkDebugMarkerObjectNameInfoEXT structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDebugMarkerObjectNameInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
|
|
type of the object to be named.
|
|
* pname:object is the object to be named.
|
|
* pname:pObjectName is a null-terminated UTF-8 string specifying the name
|
|
to apply to pname:object.
|
|
|
|
Applications may: change the name associated with an object simply by
|
|
calling fname:vkDebugMarkerSetObjectNameEXT again with a new string.
|
|
To remove a previously set name, pname:pObjectName should: be set to an
|
|
empty string.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDebugMarkerObjectNameInfoEXT-objectType-01490]]
|
|
pname:objectType must: not be
|
|
ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
|
|
* [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01491]]
|
|
pname:object must: not be dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01492]]
|
|
pname:object must: be a Vulkan object of the type associated with
|
|
pname:objectType as defined in <<debug-report-object-types>>.
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkDebugMarkerObjectNameInfoEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='vkDebugMarkerSetObjectTagEXT',desc='Attach arbitrary data to an object',type='protos']
|
|
--
|
|
|
|
In addition to setting a name for an object, debugging and validation layers
|
|
may have uses for additional binary data on a per-object basis that has no
|
|
other place in the Vulkan API.
|
|
For example, a sname:VkShaderModule could have additional debugging data
|
|
attached to it to aid in offline shader tracing.
|
|
To attach data to an object, call:
|
|
|
|
include::{generated}/api/protos/vkDebugMarkerSetObjectTagEXT.txt[]
|
|
|
|
* pname:device is the device that created the object.
|
|
* pname:pTagInfo is a pointer to an instance of the
|
|
slink:VkDebugMarkerObjectTagInfoEXT structure specifying the parameters
|
|
of the tag to attach to the object.
|
|
|
|
include::{generated}/validity/protos/vkDebugMarkerSetObjectTagEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDebugMarkerObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs']
|
|
--
|
|
|
|
The sname:VkDebugMarkerObjectTagInfoEXT structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDebugMarkerObjectTagInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
|
|
type of the object to be named.
|
|
* pname:object is the object to be tagged.
|
|
* pname:tagName is a numerical identifier of the tag.
|
|
* pname:tagSize is the number of bytes of data to attach to the object.
|
|
* pname:pTag is an array of pname:tagSize bytes containing the data to be
|
|
associated with the object.
|
|
|
|
The pname:tagName parameter gives a name or identifier to the type of data
|
|
being tagged.
|
|
This can be used by debugging layers to easily filter for only data that can
|
|
be used by that implementation.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDebugMarkerObjectTagInfoEXT-objectType-01493]]
|
|
pname:objectType must: not be
|
|
ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
|
|
* [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01494]]
|
|
pname:object must: not be dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01495]]
|
|
pname:object must: be a Vulkan object of the type associated with
|
|
pname:objectType as defined in <<debug-report-object-types>>.
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkDebugMarkerObjectTagInfoEXT.txt[]
|
|
--
|
|
|
|
[[debugging-command-buffer-markers]]
|
|
=== Command Buffer Markers
|
|
|
|
Typical Vulkan applications will submit many command buffers in each frame,
|
|
with each command buffer containing a large number of individual commands.
|
|
Being able to logically annotate regions of command buffers that belong
|
|
together as well as hierarchically subdivide the frame is important to a
|
|
developer's ability to navigate the commands viewed holistically.
|
|
|
|
The marker commands fname:vkCmdDebugMarkerBeginEXT and
|
|
fname:vkCmdDebugMarkerEndEXT define regions of a series of commands that are
|
|
grouped together, and they can be nested to create a hierarchy.
|
|
The fname:vkCmdDebugMarkerInsertEXT command allows insertion of a single
|
|
label within a command buffer.
|
|
|
|
[open,refpage='vkCmdDebugMarkerBeginEXT',desc='Open a command buffer marker region',type='protos']
|
|
--
|
|
|
|
A marker region can be opened by calling:
|
|
|
|
include::{generated}/api/protos/vkCmdDebugMarkerBeginEXT.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command is
|
|
recorded.
|
|
* pname:pMarkerInfo is a pointer to an instance of the
|
|
slink:VkDebugMarkerMarkerInfoEXT structure specifying the parameters of
|
|
the marker region to open.
|
|
|
|
include::{generated}/validity/protos/vkCmdDebugMarkerBeginEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDebugMarkerMarkerInfoEXT',desc='Specify parameters of a command buffer marker region',type='structs']
|
|
--
|
|
|
|
The sname:VkDebugMarkerMarkerInfoEXT structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkDebugMarkerMarkerInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:pMarkerName is a pointer to a null-terminated UTF-8 string that
|
|
contains the name of the marker.
|
|
* pname:color is an optional: RGBA color value that can be associated with
|
|
the marker.
|
|
A particular implementation may: choose to ignore this color value.
|
|
The values contain RGBA values in order, in the range 0.0 to 1.0.
|
|
If all elements in pname:color are set to 0.0 then it is ignored.
|
|
|
|
include::{generated}/validity/structs/VkDebugMarkerMarkerInfoEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdDebugMarkerEndEXT',desc='Close a command buffer marker region',type='protos']
|
|
--
|
|
|
|
A marker region can be closed by calling:
|
|
|
|
include::{generated}/api/protos/vkCmdDebugMarkerEndEXT.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command is
|
|
recorded.
|
|
|
|
An application may: open a marker region in one command buffer and close it
|
|
in another, or otherwise split marker regions across multiple command
|
|
buffers or multiple queue submissions.
|
|
When viewed from the linear series of submissions to a single queue, the
|
|
calls to fname:vkCmdDebugMarkerBeginEXT and fname:vkCmdDebugMarkerEndEXT
|
|
must: be matched and balanced.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01239]]
|
|
There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command
|
|
prior to the fname:vkCmdDebugMarkerEndEXT on the queue that
|
|
pname:commandBuffer is submitted to
|
|
* [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01240]]
|
|
If pname:commandBuffer is a secondary command buffer, there must: be an
|
|
outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to
|
|
pname:commandBuffer that has not previously been ended by a call to
|
|
flink:vkCmdDebugMarkerEndEXT.
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdDebugMarkerEndEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdDebugMarkerInsertEXT',desc='Insert a marker label into a command buffer',type='protos']
|
|
--
|
|
|
|
A single marker label can be inserted into a command buffer by calling:
|
|
|
|
include::{generated}/api/protos/vkCmdDebugMarkerInsertEXT.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer into which the command is
|
|
recorded.
|
|
* pname:pMarkerInfo is a pointer to an instance of the
|
|
slink:VkDebugMarkerMarkerInfoEXT structure specifying the parameters of
|
|
the marker to insert.
|
|
|
|
include::{generated}/validity/protos/vkCmdDebugMarkerInsertEXT.txt[]
|
|
--
|