From 6635a81b5b9dea234faf967d54abf7241db371c9 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 24 May 2019 05:29:25 -0700 Subject: [PATCH] Change log for May 24, 2019 Vulkan 1.1.109 spec update: * Update release number to 109. Github Issues: * Require matching for physical devices to be in a device group in the <> section (public issue 695). * Fix typo in an equation in the <> section (public issue 954). * Fix styleguide links (public pull request 965). Internal Issues: * Allow <> with different resolve attachments (internal issue 1464). * Add some missing empty flags types to API spec so custom refpage generation doesn't break (internal issue 1607). * Add a "`SPIR-V Sampled Type`" column to the <> table, and clarify the requirement that the code:OpTypeImage sampled type match the bound image's numeric format for slink:VkClearColorValue and in the <> section (internal issue 1646). * Fix a typo in the <> section which should refer to rectangles, not triangles (internal issue 1667). * Clarify the definition of time domains in elink:VkTimeDomainEXT (internal merge request 3110). * Add R10X6 and R12X4 formats to the <> table (internal merge request 3137). * Don't require extern sync on wait/signal semaphores in `vk.xml` for flink:vkQueueSubmit and flink:vkQueueBindSparse (internal merge request 3116). * Improve phrasing of compute and mesh shader size related to code:LocalSize and code:WorkgroupSize in slink:VkPhysicalDeviceMeshShaderPropertiesNV and slink:VkPhysicalDeviceMaintenance3Properties (internal merge request 3156). * Make the flink:vkCmdBindShadingRateImageNV pname:imageView parameter optional in `vk.xml` (internal merge request 3157). New Extensions: * `<>` * `<>` --- ChangeLog.txt | 49 +++ Makefile | 4 +- appendices/VK_INTEL_performance_query.txt | 213 ++++++++++ .../VK_INTEL_shader_integer_functions2.txt | 10 +- appendices/VK_KHR_xlib_surface.txt | 2 +- .../VK_INTEL_performance_query/queries.txt | 365 ++++++++++++++++++ chapters/VK_KHR_display/display.txt | 16 + .../platformCreateSurface_win32.txt | 14 +- chapters/clears.txt | 5 +- chapters/debugging.txt | 3 + chapters/devsandqueues.txt | 15 + chapters/features.txt | 14 +- chapters/formats.txt | 30 +- chapters/fragmentdensitymapops.txt | 2 +- chapters/interfaces.txt | 6 +- chapters/limits.txt | 45 ++- chapters/memory.txt | 12 +- chapters/queries.txt | 19 +- chapters/renderpass.txt | 6 +- chapters/synchronization.txt | 43 ++- chapters/tessellation.txt | 2 +- scripts/genRef.py | 2 +- scripts/reflow_count.py | 2 +- style/extensions.txt | 8 +- style/naming.txt | 4 +- style/writing.txt | 5 +- styleguide.txt | 3 +- xml/vk.xml | 163 +++++++- 28 files changed, 975 insertions(+), 87 deletions(-) create mode 100644 appendices/VK_INTEL_performance_query.txt create mode 100644 chapters/VK_INTEL_performance_query/queries.txt diff --git a/ChangeLog.txt b/ChangeLog.txt index 4c8cd4d0..685e4e1d 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -8,6 +8,55 @@ public pull requests that have been accepted. ----------------------------------------------------- +Change log for May 24, 2019 Vulkan 1.1.109 spec update: + + * Update release number to 109. + +Github Issues: + + * Require matching for physical devices to be in a device group in the + <> section (public issue 695). + * Fix typo in an equation in the <> section (public issue 954). + * Fix styleguide links (public pull request 965). + +Internal Issues: + + * Allow <> with different resolve attachments (internal issue 1464). + * Add some missing empty flags types to API spec so custom refpage + generation doesn't break (internal issue 1607). + * Add a "`SPIR-V Sampled Type`" column to the <> table, and clarify the requirement + that the code:OpTypeImage sampled type match the bound image's numeric + format for slink:VkClearColorValue and in the + <> section + (internal issue 1646). + * Fix a typo in the <> + section which should refer to rectangles, not triangles (internal issue + 1667). + * Clarify the definition of time domains in elink:VkTimeDomainEXT + (internal merge request 3110). + * Add R10X6 and R12X4 formats to the <> + table (internal merge request 3137). + * Don't require extern sync on wait/signal semaphores in `vk.xml` for + flink:vkQueueSubmit and flink:vkQueueBindSparse (internal merge request + 3116). + * Improve phrasing of compute and mesh shader size related to + code:LocalSize and code:WorkgroupSize in + slink:VkPhysicalDeviceMeshShaderPropertiesNV and + slink:VkPhysicalDeviceMaintenance3Properties (internal merge request + 3156). + * Make the flink:vkCmdBindShadingRateImageNV pname:imageView parameter + optional in `vk.xml` (internal merge request 3157). + +New Extensions: + + * `<>` + * `<>` + +----------------------------------------------------- + Change log for May 13, 2019 Vulkan 1.1.108 spec update: * Update release number to 108. diff --git a/Makefile b/Makefile index 15f5a47f..bbd62553 100644 --- a/Makefile +++ b/Makefile @@ -121,7 +121,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 108 +PATCHVERSION = 109 ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS))) SPECREVISION = 1.1.$(PATCHVERSION) else @@ -367,7 +367,7 @@ MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt GENREF = $(SCRIPTS)/genRef.py LOGFILE = man/logfile man/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(SCRIPTS)/vkapi.py - $(PYTHON) $(GENREF) -log $(LOGFILE) $(SPECFILES) + $(PYTHON) $(GENREF) -log $(LOGFILE) $(EXTOPTIONS) $(SPECFILES) # These targets are HTML5 ref pages # diff --git a/appendices/VK_INTEL_performance_query.txt b/appendices/VK_INTEL_performance_query.txt new file mode 100644 index 00000000..3be9982c --- /dev/null +++ b/appendices/VK_INTEL_performance_query.txt @@ -0,0 +1,213 @@ +include::meta/VK_INTEL_performance_query.txt[] + +*Last Modified Date*:: + 2018-05-16 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Lionel Landwerlin, Intel + - Piotr Maciejewski, Intel + +This extension allows an application to capture performance data to be +interpreted by a external application or library. + +Such a library is available at : https://github.com/intel/metrics-discovery + +Performance analysis tools such as GPA +(https://software.intel.com/en-us/gpa) make use of this extension and the +metrics-discovery library to present the data in a human readable way. + +=== New Object Types + + * slink:VkPerformanceConfigurationINTEL + +=== New Enum Constants + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL + ** ename:VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL + ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_MARKER_INFO_INTEL + ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_STREAM_MARKER_INFO_INTEL + ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_OVERRIDE_INFO_INTEL + ** ename:VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL + ** ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL + + * Extending elink:VkQueryType: + ** ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL + +=== New Enums + + * elink:VkPerformanceConfigurationTypeINTEL + * elink:VkQueryPoolSamplingModeINTEL + * elink:VkPerformanceOverrideTypeINTEL + * elink:VkPerformanceParameterTypeINTEL + * elink:VkPerformanceValueTypeINTEL + +=== New Structures + + * slink:VkPerformanceValueINTEL + * slink:VkInitializePerformanceApiInfoINTEL + * slink:VkQueryPoolCreateInfoINTEL + * slink:VkPerformanceMarkerInfoINTEL + * slink:VkPerformanceStreamMarkerInfoINTEL + * slink:VkPerformanceOverrideInfoINTEL + * slink:VkPerformanceConfigurationAcquireInfoINTEL + +=== New Functions + + * flink:vkInitializePerformanceApiINTEL + * flink:vkUninitializePerformanceApiINTEL + * flink:vkCmdSetPerformanceMarkerINTEL + * flink:vkCmdSetPerformanceOverrideINTEL + * flink:vkCmdSetPerformanceStreamMarkerINTEL + * flink:vkAcquirePerformanceConfigurationINTEL + * flink:vkReleasePerformanceConfigurationINTEL + * flink:vkQueueSetPerformanceConfigurationINTEL + * flink:vkGetPerformanceParameterINTEL + +=== Issues + +None. + +=== Example Code + +[source,c] +--------------------------------------------------- + +// A previously created device +VkDevice device; + +// A queue from from device +VkQueue queue; + +VkInitializePerformanceApiInfoINTEL performanceApiInfoIntel = { + VK_STRUCTURE_TYPE_INITIALIZE_PERFORMANCE_API_INFO_INTEL, + NULL, + NULL +}; + +vkInitializePerformanceApiINTEL( + device, + &performanceApiInfoIntel); + +VkQueryPoolCreateInfoINTEL queryPoolIntel = { + VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO_INTEL, + NULL, + VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL, +}; + +VkQueryPoolCreateInfo queryPoolCreateInfo = { + VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO, + &queryPoolIntel, + 0, + VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL, + 1, + 0 +}; + +VkQueryPool queryPool; + +VkResult result = vkCreateQueryPool( + device, + &queryPoolCreateInfo, + NULL, + &queryPool); + +assert(VK_SUCCESS == result); + +// A command buffer we want to record counters on +VkCommandBuffer commandBuffer; + +VkCommandBufferBeginInfo commandBufferBeginInfo = { + VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, + NULL, + VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, + NULL +}; + +result = vkBeginCommandBuffer(commandBuffer, &commandBufferBeginInfo); + +assert(VK_SUCCESS == result); + +vkCmdResetQueryPool( + commandBuffer, + queryPool, + 0, + 1); + +vkCmdBeginQuery( + commandBuffer, + queryPool, + 0, + 0); + +// Perform the commands you want to get performance information on +// ... + +// Perform a barrier to ensure all previous commands were complete before +// ending the query +vkCmdPipelineBarrier(commandBuffer, + VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, + VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, + 0, + 0, + NULL, + 0, + NULL, + 0, + NULL); + +vkCmdEndQuery( + commandBuffer, + queryPool, + 0); + +result = vkEndCommandBuffer(commandBuffer); + +assert(VK_SUCCESS == result); + +VkPerformanceConfigurationAcquireInfoINTEL performanceConfigurationAcquireInfo = { + VK_STRUCTURE_TYPE_PERFORMANCE_CONFIGURATION_ACQUIRE_INFO_INTEL, + NULL, + VK_PERFORMANCE_CONFIGURATION_TYPE_COMMAND_QUEUE_METRICS_DISCOVERY_ACTIVATED_INTEL +}; + +VkPerformanceConfigurationINTEL performanceConfigurationIntel; + +result = vkAcquirePerformanceConfigurationINTEL( + device, + &performanceConfigurationAcquireInfo, + &performanceConfigurationIntel); + +vkQueueSetPerformanceConfigurationINTEL(queue, performanceConfigurationIntel); + +assert(VK_SUCCESS == result); + +// Submit the command buffer and wait for its completion +// ... + +result = vkReleasePerformanceConfigurationINTEL( + device, + performanceConfigurationIntel); + +assert(VK_SUCCESS == result); + +// Get the report size from metrics-discovery's QueryReportSize + +result = vkGetQueryPoolResults( + device, + queryPool, + 0, 1, QueryReportSize, + data, QueryReportSize, 0); + +assert(VK_SUCCESS == result); + +// The data can then be passed back to metrics-discovery from which +// human readable values can be queried. + +--------------------------------------------------- + +=== Version History + + * Revision 1, 2018-05-16 (Lionel Landwerlin) + - Initial revision diff --git a/appendices/VK_INTEL_shader_integer_functions2.txt b/appendices/VK_INTEL_shader_integer_functions2.txt index 3cb1cb4e..52546068 100644 --- a/appendices/VK_INTEL_shader_integer_functions2.txt +++ b/appendices/VK_INTEL_shader_integer_functions2.txt @@ -8,13 +8,15 @@ include::meta/VK_INTEL_shader_integer_functions2.txt[] - Ian Romanick, Intel - Ben Ashbaugh, Intel -This extension adds support for several new integer instructions in SPIR-V for -use in graphics shaders. Many of these instructions have pre-existing -counterparts in the Kernel environment. +This extension adds support for several new integer instructions in SPIR-V +for use in graphics shaders. +Many of these instructions have pre-existing counterparts in the Kernel +environment. The added integer functions are defined by the http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/INTEL/SPV_INTEL_shader_integer_functions2.html[+SPV_INTEL_shader_integer_functions+] -SPIR-V extension and can be used with the GL_INTEL_shader_integer_functions2 GLSL extension. +SPIR-V extension and can be used with the GL_INTEL_shader_integer_functions2 +GLSL extension. === New Object Types diff --git a/appendices/VK_KHR_xlib_surface.txt b/appendices/VK_KHR_xlib_surface.txt index 8a16f573..ff21c3c9 100644 --- a/appendices/VK_KHR_xlib_surface.txt +++ b/appendices/VK_KHR_xlib_surface.txt @@ -58,7 +58,7 @@ None 1) Does X11 need a way to query for compatibility between a particular physical device and a specific screen? This would be a more general query -than flink:vkGetPhysicalDeviceSurfaceSupportKHR : if it returned +than flink:vkGetPhysicalDeviceSurfaceSupportKHR; if it returned ename:VK_TRUE, then the physical device could be assumed to support presentation to any window on that screen. diff --git a/chapters/VK_INTEL_performance_query/queries.txt b/chapters/VK_INTEL_performance_query/queries.txt new file mode 100644 index 00000000..c1270bc7 --- /dev/null +++ b/chapters/VK_INTEL_performance_query/queries.txt @@ -0,0 +1,365 @@ +ifdef::VK_INTEL_performance_query[] + +[[queries-performance-intel]] +== Intel performance queries + +Intel performance queries allow an application to capture performance data +for a set of commands. +Performance queries are used in a similar way than other types of queries. +A main difference with existing queries is that the resulting data should be +handed over to a library capabable to produce human readable results rather +than being read directly by an application. + +[open,refpage='vkInitializePerformanceApiINTEL',desc='Initialize a device for performance queries',type='protos'] +-- +Prior to creating a performance query pool, initialize the device for +performance queries with the call: + +include::{generated}/api/protos/vkInitializePerformanceApiINTEL.txt[] + + * pname:device is the logical device used for the queries. + * pname:pInitializeInfo is a pointer to the initialization parameters. + +include::{generated}/validity/protos/vkInitializePerformanceApiINTEL.txt[] +-- + +[open,refpage='VkInitializePerformanceApiInfoINTEL',desc='Structure specifying parameters of initialize of the device',type='structs'] +-- +The sname:VkInitializePerformanceApiInfoINTEL structure is defined as : + +include::{generated}/api/structs/VkInitializePerformanceApiInfoINTEL.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:pUserData is a pointer for application data. + +include::{generated}/validity/structs/VkInitializePerformanceApiInfoINTEL.txt[] +-- + +[open,refpage='vkUninitializePerformanceApiINTEL',desc='Uninitialize a device for performance queries',type='protos'] +-- +Once performance query operations have completed, uninitalize the device for +performance queries with the call: + +include::{generated}/api/protos/vkUninitializePerformanceApiINTEL.txt[] + + * pname:device is the logical device used for the queries. + +include::{generated}/validity/protos/vkUninitializePerformanceApiINTEL.txt[] +-- + +[open,refpage='vkGetPerformanceParameterINTEL',desc='Query performance capabilities of the device',type='protos'] +-- +Some performance query features of a device can be discovered with the call: + +include::{generated}/api/protos/vkGetPerformanceParameterINTEL.txt[] + + * pname:device is the logical device to query. + * pname:parameter is the parameter to query. + * pname:pValue points to an instance of the slink:VkPerformanceValueINTEL + structure in which the type and value of the parameter are returned. + +include::{generated}/validity/protos/vkGetPerformanceParameterINTEL.txt[] +-- + +[open,refpage='VkPerformanceParameterTypeINTEL',desc='Parameters that can be queried',type='enums'] +-- +Possible values of flink:vkGetPerformanceParameterINTEL::pname:parameter, +specifying a performance query feature, are: + +include::{generated}/api/enums/VkPerformanceParameterTypeINTEL.txt[] + + * ename:VK_PERFORMANCE_PARAMETER_TYPE_HW_COUNTERS_SUPPORTED_INTEL has a + boolean result which tells whether hardware counters can be captured. + * ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL has a + 32 bits integer result which tells how many bits can be written into the + sname:VkStreamPerformanceMarkerInfoINTEL value. +-- + +[open,refpage='VkPerformanceValueINTEL',desc='Container for value and types of parameters that can be queried',type='structs'] +-- +The sname:VkPerformanceValueINTEL structure is defined as: + +include::{generated}/api/structs/VkPerformanceValueINTEL.txt[] + + * pname:type is an elink:VkPerformanceValueTypeINTEL value specifying the + type of the returned data. + * pname:data is an slink:VkPerformanceValueDataINTEL union specifying the + value of the returned data. + +include::{generated}/validity/structs/VkPerformanceValueINTEL.txt[] +-- + +[open,refpage='VkPerformanceValueTypeINTEL',desc='Type of the parameters that can be queried',type='enums'] +-- +Possible values of slink:VkPerformanceValueINTEL::pname:type, specifying the +type of the data returned in slink:VkPerformanceValueINTEL::pname:data, are: + + * ename:VK_PERFORMANCE_VALUE_TYPE_UINT32_INTEL specifies that unsigned + 32-bit integer data is returned in pname:data.value32. + * ename:VK_PERFORMANCE_VALUE_TYPE_UINT64_INTEL specifies that unsigned + 64-bit integer data is returned in pname:data.value64. + * ename:VK_PERFORMANCE_VALUE_TYPE_FLOAT_INTEL specifies that + floating-point data is returned in pname:data.valueFloat. + * ename:VK_PERFORMANCE_VALUE_TYPE_BOOL_INTEL specifies that + basetype:Bool32 data is returned in pname:data.valueBool. + * ename:VK_PERFORMANCE_VALUE_TYPE_STRING_INTEL specifies that a pointer to + a NULL-terminated string is returned in pname:data.valueString. + The pointer is valid for the lifetime of the pname:device parameter + passed to flink:vkGetPerformanceParameterINTEL. + +include::{generated}/api/enums/VkPerformanceValueTypeINTEL.txt[] +-- + +[open,refpage='VkPerformanceValueDataINTEL',desc='Values returned for the parameters',type='structs'] +-- +The sname:VkPerformanceValueDataINTEL union is defined as: + +include::{generated}/api/structs/VkPerformanceValueDataINTEL.txt[] + + * pname:data.value32 represents 32-bit integer data. + * pname:data.value64 represents 64-bit integer data. + * pname:data.valueFloat represents floating-point data. + * pname:data.valueBool represents basetype:Bool32 data. + * pname:data.valueString represents a pointer to a NULL-terminated string. + +The correct member of the union is determined by the associated +elink:VkPerformanceValueTypeINTEL value. + +include::{generated}/validity/structs/VkPerformanceValueDataINTEL.txt[] +-- + +[open,refpage='VkQueryPoolCreateInfoINTEL',desc='Structure specifying parameters to create a pool of performance queries',type='structs'] +-- +The sname:VkQueryPoolCreateInfoINTEL structure is defined as: + +include::{generated}/api/structs/VkQueryPoolCreateInfoINTEL.txt[] + +To create a pool for Intel performance queries, set +slink:VkQueryPoolCreateInfo::pname:queryType to +ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL and add a +sname:VkQueryPoolCreateInfoINTEL to the pname:pNext chain of the +slink:VkQueryPoolCreateInfo structure. + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:performanceCountersSampling describe how performance queries + should be captured. + +include::{generated}/validity/structs/VkQueryPoolCreateInfoINTEL.txt[] +-- + +[open,refpage='VkQueryPoolSamplingModeINTEL',desc='Enum specifying how performance queries should be captured',type='enums'] +-- +Possible values of +slink:VkQueryPoolCreateInfoINTEL::pname:performanceCountersSampling are: + +include::{generated}/api/enums/VkQueryPoolSamplingModeINTEL.txt[] + + * ename:VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL is the default mode in + which the application calls flink:vkCmdBeginQuery and + flink:vkCmdEndQuery to record performance data. +-- + +[open,refpage='vkCmdSetPerformanceMarkerINTEL',desc='Markers',type='protos'] +-- +To help associate query results with a particular point at which an +application emitted commands, markers can be set into the command buffers +with the call: + +include::{generated}/api/protos/vkCmdSetPerformanceMarkerINTEL.txt[] + +The last marker set onto a command buffer before the end of a query will be +part of the query result. + +include::{generated}/validity/protos/vkCmdSetPerformanceMarkerINTEL.txt[] +-- + +[open,refpage='VkPerformanceMarkerInfoINTEL',desc='Structure specifying performance markers',type='structs'] +-- +The sname:VkPerformanceMarkerInfoINTEL structure is defined as: + +include::{generated}/api/structs/VkPerformanceMarkerInfoINTEL.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:marker is the marker value that will be recorded into the opaque + query results. + +include::{generated}/validity/structs/VkPerformanceMarkerInfoINTEL.txt[] +-- + +[open,refpage='vkCmdSetPerformanceStreamMarkerINTEL',desc='Markers',type='protos'] +-- +When monitoring the behavior of an application wihtin the dataset generated +by the entire set of applications running on the system, it is useful to +identify draw calls within a potentially huge amount of performance data. +To do so, application can generate stream markers that will be used to trace +back a particular draw call with a particular performance data item. + +include::{generated}/api/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[] + +include::{generated}/validity/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[] +-- + +[open,refpage='VkPerformanceStreamMarkerInfoINTEL',desc='Structure specifying stream performance markers',type='structs'] +-- +The sname:VkPerformanceStreamMarkerInfoINTEL structure is defined as: + +include::{generated}/api/structs/VkPerformanceStreamMarkerInfoINTEL.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:marker is the marker value that will be recorded into the reports + consumed by an external application. + +.Valid Usage +**** + * [[VUID-VkPerformanceStreamMarkerInfoINTEL-marker-02735]] + The value written by the application into pname:marker must: only used + the valid bits as reported by flink:vkGetPerformanceParameterINTEL with + the ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL. +**** + +include::{generated}/validity/structs/VkPerformanceStreamMarkerInfoINTEL.txt[] +-- + +[open,refpage='vkCmdSetPerformanceOverrideINTEL',desc='Performance override settings',type='protos'] +-- +Some applications might want measure the effect of a set of commands with a +different settings. +It is possible to override a particular settings using : + +include::{generated}/api/protos/vkCmdSetPerformanceOverrideINTEL.txt[] + + * pname:commandBuffer is the command buffer where the override takes + place. + * pname:pOverrideInfo is a pointer to a + sname:VkPerformanceOverrideInfoINTEL selecting the parameter to + override. + +.Valid Usage +**** + * [[VUID-vkCmdSetPerformanceOverrideINTEL-pOverrideInfo-02736]] + pname:pOverrideInfo must: not be used with a + elink:VkPerformanceOverrideTypeINTEL that is not reported available by + fname:vkGetPerformanceParameterINTEL. +**** + +include::{generated}/validity/protos/vkCmdSetPerformanceOverrideINTEL.txt[] +-- + +[open,refpage='VkPerformanceOverrideInfoINTEL',desc='Performance override info',type='structs'] +-- +The sname:VkPerformanceOverrideInfoINTEL structure is defined as: + +include::{generated}/api/structs/VkPerformanceOverrideInfoINTEL.txt[] + + * pname:type is the particular elink:VkPerformanceOverrideTypeINTEL to + set. + * pname:enable defines whether the override is enabled. + * pname:parameter is a potential required parameter for the override. + +include::{generated}/validity/structs/VkPerformanceOverrideInfoINTEL.txt[] +-- + +[open,refpage='VkPerformanceOverrideTypeINTEL',desc='Performance override type',type='enums'] +-- +Possible values of slink:VkPerformanceOverrideInfoINTEL::pname:type, +specifying performance override types, are: + +include::{generated}/api/enums/VkPerformanceOverrideTypeINTEL.txt[] + + * ename:VK_PERFORMANCE_OVERRIDE_TYPE_NULL_HARDWARE_INTEL turns all + rendering operations into noop. + * ename:VK_PERFORMANCE_OVERRIDE_TYPE_FLUSH_GPU_CACHES_INTEL stalls the + stream of commands until all previously emitted commands have completed + and all caches been flushed and invalidated. +-- + +[open,refpage='VkPerformanceConfigurationINTEL',desc='Device configuration for performance queries',type='handles'] +-- +Before submitting command buffers containing performance queries commands to +a device queue, the application must acquire and set a performance query +configuration. +The configuration can be released once all command buffers containing +performance query commands are not in a pending state. + +include::{generated}/api/handles/VkPerformanceConfigurationINTEL.txt[] +-- + +[open,refpage='vkAcquirePerformanceConfigurationINTEL',desc='Acquire the performance query capability',type='protos'] +-- +To acquire a device performance configuration, call: + +include::{generated}/api/protos/vkAcquirePerformanceConfigurationINTEL.txt[] + + * pname:device is the logical device that the performance query commands + will be submitted to. + * pname:pAcquireInfo is a pointer to + slink:VkPerformanceConfigurationAcquireInfoINTEL. + * pname:pConfiguration is a pointer to a + sname:VkPerformanceConfigurationINTEL handle in which the resulting + configuration object is returned. + +include::{generated}/validity/protos/vkAcquirePerformanceConfigurationINTEL.txt[] +-- + +[open,refpage='VkPerformanceConfigurationAcquireInfoINTEL',desc='Acquire a configuration to capture performance data',type='structs'] +-- +The sname:VkPerformanceConfigurationAcquireInfoINTEL structure is defined +as: + +include::{generated}/api/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:type is one of the elink:VkPerformanceConfigurationTypeINTEL type + of performance configuration that will be acquired. + +include::{generated}/validity/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[] +-- + +[open,refpage='VkPerformanceConfigurationTypeINTEL',desc='Type of performance configuration',type='enums'] +-- +Possible values of +slink:VkPerformanceConfigurationAcquireInfoINTEL::pname:type, specifying +performance configuration types, are: + +include::{generated}/api/enums/VkPerformanceConfigurationTypeINTEL.txt[] +-- + +[open,refpage='vkQueueSetPerformanceConfigurationINTEL',desc='Set a performance query',type='protos'] +-- +To set a performance configuration, call: + +include::{generated}/api/protos/vkQueueSetPerformanceConfigurationINTEL.txt[] + + * pname:queue is the queue on which the configuration will be used. + * pname:configuration is the configuration to use. + +include::{generated}/validity/protos/vkQueueSetPerformanceConfigurationINTEL.txt[] +-- + +[open,refpage='vkReleasePerformanceConfigurationINTEL',desc='Release a configuration to capture performance data',type='protos'] +-- +To release a device performance configuration, call: + +include::{generated}/api/protos/vkReleasePerformanceConfigurationINTEL.txt[] + + * pname:device is the device associated to the configuration object to + release. + * pname:configuration is the configuration object to release. + +.Valid Usage +**** + * [[VUID-vkReleasePerformanceConfigurationINTEL-configuration-02737]] + pname:configuration must: not be released before all command buffers + submitted while the configuration was set are in + <>. +**** + +include::{generated}/validity/protos/vkReleasePerformanceConfigurationINTEL.txt[] +-- + +endif::VK_INTEL_performance_query[] diff --git a/chapters/VK_KHR_display/display.txt b/chapters/VK_KHR_display/display.txt index 74edb3d4..17202f6d 100644 --- a/chapters/VK_KHR_display/display.txt +++ b/chapters/VK_KHR_display/display.txt @@ -352,6 +352,14 @@ include::{generated}/api/structs/VkDisplayModePropertiesKHR.txt[] include::{generated}/validity/structs/VkDisplayModePropertiesKHR.txt[] -- +[open,refpage='VkDisplayModeCreateFlagsKHR',desc='Reserved for future use',type='flags'] +-- +include::{generated}/api/flags/VkDisplayModeCreateFlagsKHR.txt[] + +tname:VkDisplayModeCreateFlagsKHR is a bitmask type for setting a mask, but +is currently reserved for future use. +-- + ifdef::VK_KHR_get_display_properties2[] [open,refpage='vkGetDisplayModeProperties2KHR',desc='Query information about the available display modes.',type='protos'] @@ -724,6 +732,14 @@ to a display surface. include::{generated}/validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[] -- +[open,refpage='VkDisplaySurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags'] +-- +include::{generated}/api/flags/VkDisplaySurfaceCreateFlagsKHR.txt[] + +tname:VkDisplaySurfaceCreateFlagsKHR is a bitmask type for setting a mask, +but is currently reserved for future use. +-- + [open,refpage='VkDisplayPlaneAlphaFlagBitsKHR',desc='Alpha blending type',type='enums'] -- diff --git a/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt b/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt index 0ea05405..4e650456 100644 --- a/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt +++ b/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt @@ -36,8 +36,10 @@ include::{generated}/api/structs/VkWin32SurfaceCreateInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is reserved for future use. - * pname:hinstance and pname:hwnd are the Win32 code:HINSTANCE and - code:HWND for the window to associate the surface with. + * pname:hinstance is the Win32 code:HINSTANCE for the window to associate + the surface with. + * pname:hwnd is the Win32 code:HWND for the window to associate the + surface with. .Valid Usage **** @@ -67,3 +69,11 @@ The window size may: become [eq]#(0, 0)# on this platform (e.g. when the window is minimized), and so a swapchain cannot: be created until the size changes. ==== + +[open,refpage='VkWin32SurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags'] +-- +include::{generated}/api/flags/VkWin32SurfaceCreateFlagsKHR.txt[] + +tname:VkWin32SurfaceCreateFlagsKHR is a bitmask type for setting a mask, but +is currently reserved for future use. +-- diff --git a/chapters/clears.txt b/chapters/clears.txt index ae0125c5..6d84d3ca 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -416,9 +416,8 @@ The sname:VkClearColorValue structure is defined as: include::{generated}/api/structs/VkClearColorValue.txt[] * pname:float32 are the color clear values when the format of the image or - attachment is one of the formats in the <> table other than signed integer - (etext:SINT) or unsigned integer (etext:UINT). + attachment is one of the formats in the <> table + other than signed integer (etext:SINT) or unsigned integer (etext:UINT). Floating point values are automatically converted to the format of the image, with the clear value being treated as linear if the image is sRGB. diff --git a/chapters/debugging.txt b/chapters/debugging.txt index c5e9d1b2..fc127cb8 100644 --- a/chapters/debugging.txt +++ b/chapters/debugging.txt @@ -77,6 +77,9 @@ endif::VK_EXT_validation_cache[] ifdef::VK_NV_ray_tracing[] | ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV | slink:VkAccelerationStructureNV endif::VK_NV_ray_tracing[] +ifdef::VK_INTEL_performance_query[] +| ename:VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL | slink:VkPerformanceConfigurationINTEL +endif::VK_INTEL_performance_query[] |==== -- diff --git a/chapters/devsandqueues.txt b/chapters/devsandqueues.txt index 5c7fd9a9..6eba8ec6 100644 --- a/chapters/devsandqueues.txt +++ b/chapters/devsandqueues.txt @@ -757,6 +757,21 @@ Device groups are enumerated by calling flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from a subset of the physical devices in a device group by passing the physical devices through slink:VkDeviceGroupDeviceCreateInfo. +For two physical devices to be in the same device group, they must: support +identical extensions, features, and properties. + +[NOTE] +.Note +==== +Physical devices in the same device group must: be so similar because there +are no rules for how different features/properties would interact. +They must: return the same values for nearly every invariant +ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could +potentially differ for certain queries based on things like having a +different display connected, or different compositor, etc.. +The specification does not attempt to enumerate which state is in each +category, because such a list would quickly become out of date. +==== [open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] -- diff --git a/chapters/features.txt b/chapters/features.txt index abd6fcf7..b3a224e7 100644 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -2086,8 +2086,8 @@ ifdef::VK_INTEL_shader_integer_functions2[] [open,refpage='VkPhysicalDeviceShaderIntegerFunctions2INTEL',desc='Structure describing shader integer functions that can be supported by an implementation',type='structs'] -- -The sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL structure is -defined as: +The sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL structure is defined +as: include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerFunctions2INTEL.txt[] @@ -2098,11 +2098,11 @@ structure describe the following features: indicates that the implementation supports the code:ShaderIntegerFunctions2INTEL SPIR-V capability. -If the sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL structure -is included in the pname:pNext chain of slink:VkPhysicalDeviceFeatures2KHR, -it is filled with values indicating whether the feature is supported. -sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL can: also be used -in the pname:pNext chain of slink:VkDeviceCreateInfo to enable features. +If the sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL structure is +included in the pname:pNext chain of slink:VkPhysicalDeviceFeatures2KHR, it +is filled with values indicating whether the feature is supported. +sname:VkPhysicalDeviceShaderIntegerFunctions2INTEL can: also be used in the +pname:pNext chain of slink:VkDeviceCreateInfo to enable features. include::{generated}/validity/structs/VkPhysicalDeviceShaderIntegerFunctions2INTEL.txt[] -- diff --git a/chapters/formats.txt b/chapters/formats.txt index 92a498b8..b08b02a4 100644 --- a/chapters/formats.txt +++ b/chapters/formats.txt @@ -1289,18 +1289,18 @@ An X indicates a component that is unused, but may: be present for padding. [[formats-numericformat]] .Interpretation of Numeric Format -[width="95%",cols="2,10",options="header"] +[width="95%",cols="2,3,10",options="header"] |==== -| Numeric format | Description -| etext:UNORM | The components are unsigned normalized values in the range [eq]#[0,1]# -| etext:SNORM | The components are signed normalized values in the range [eq]#[-1,1]# -| etext:USCALED | The components are unsigned integer values that get converted to floating-point in the range [0,2^n^-1] -| etext:SSCALED | The components are signed integer values that get converted to floating-point in the range [-2^n-1^,2^n-1^-1] -| etext:UINT | The components are unsigned integer values in the range [0,2^n^-1] -| etext:SINT | The components are signed integer values in the range [-2^n-1^,2^n-1^-1] -| etext:UFLOAT | The components are unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats) -| etext:SFLOAT | The components are signed floating-point numbers -| etext:SRGB | The R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value +| Numeric format | SPIR-V _Sampled Type_ | Description +| etext:UNORM | OpTypeFloat | The components are unsigned normalized values in the range [eq]#[0,1]# +| etext:SNORM | OpTypeFloat | The components are signed normalized values in the range [eq]#[-1,1]# +| etext:USCALED | OpTypeFloat | The components are unsigned integer values that get converted to floating-point in the range [0,2^n^-1] +| etext:SSCALED | OpTypeFloat | The components are signed integer values that get converted to floating-point in the range [-2^n-1^,2^n-1^-1] +| etext:UINT | OpTypeInt unsigned | The components are unsigned integer values in the range [0,2^n^-1] +| etext:SINT | OpTypeInt signed | The components are signed integer values in the range [-2^n-1^,2^n-1^-1] +| etext:UFLOAT | OpTypeFloat | The components are unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats) +| etext:SFLOAT | OpTypeFloat | The components are signed floating-point numbers +| etext:SRGB | OpTypeFloat | The R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value |==== The suffix etext:_PACKnn indicates that the format is packed into an @@ -2650,7 +2650,7 @@ s| Format <<< [[formats-mandatory-features-10bit]] -.Mandatory format support: 10-bit channels +.Mandatory format support: 10- and 12-bit channels [width="100%",cols="12,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1,^1",options="unbreakable"] |==== 13+>| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT .14+^.^| {downarrow} @@ -2679,6 +2679,12 @@ s| Format | ename:VK_FORMAT_A2B10G10R10_SSCALED_PACK32 | | | | | | | | | | | | | | ename:VK_FORMAT_A2B10G10R10_UINT_PACK32 | {sym1} | {sym1} | | | | {sym1} | {sym1} | | | | {sym1} | | | ename:VK_FORMAT_A2B10G10R10_SINT_PACK32 | | | | | | | | | | | | | +ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +| ename:VK_FORMAT_R10X6_UNORM_PACK16 | | | | | | | | | | | | | +| ename:VK_FORMAT_R10X6G10X6_UNORM_2PACK16 | | | | | | | | | | | | | +| ename:VK_FORMAT_R12X4_UNORM_PACK16 | | | | | | | | | | | | | +| ename:VK_FORMAT_R12X4G12X4_UNORM_2PACK16 | | | | | | | | | | | | | +endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |==== <<< diff --git a/chapters/fragmentdensitymapops.txt b/chapters/fragmentdensitymapops.txt index 7e8ec2e2..0a55bfc9 100644 --- a/chapters/fragmentdensitymapops.txt +++ b/chapters/fragmentdensitymapops.txt @@ -45,7 +45,7 @@ sname:VkPhysicalDeviceFragmentDensityMapPropertiesEXT and therefore the final region size is clamped: :: latexmath:[fragmentDensityTexelSize_{width} = - \mathbin{clamp}(fragmentDensityTexelSize'_{width},minFragmentDensityTexelSize_{width},maxFragmentDensityTexelSize_{height})] + \mathbin{clamp}(fragmentDensityTexelSize'_{width},minFragmentDensityTexelSize_{width},maxFragmentDensityTexelSize_{width})] :: latexmath:[fragmentDensityTexelSize_{height} = \mathbin{clamp}(fragmentDensityTexelSize'_{height},minFragmentDensityTexelSize_{height},maxFragmentDensityTexelSize_{height})] diff --git a/chapters/interfaces.txt b/chapters/interfaces.txt index 9abe8285..485693d8 100644 --- a/chapters/interfaces.txt +++ b/chapters/interfaces.txt @@ -520,8 +520,10 @@ Such variables must: be typed as code:OpTypeImage, code:OpTypeSampler, code:OpTypeSampledImage, or an array of one of these types. The code:Sampled code:Type of an code:OpTypeImage declaration must: match -the same basic data type as the corresponding resource, or the values -obtained by reading or sampling from this image are undefined:. +the numeric format of the corresponding resource in type and signedness, as +shown in the _SPIR-V Sampled Type_ column of the <> +table, or the values obtained by reading or sampling from this image are +undefined:. The code:Image code:Format of an code:OpTypeImage declaration must: not be *Unknown*, for variables which are used for code:OpImageRead, diff --git a/chapters/limits.txt b/chapters/limits.txt index e33e49be..b8604b6c 100644 --- a/chapters/limits.txt +++ b/chapters/limits.txt @@ -461,17 +461,18 @@ endif::VK_EXT_descriptor_indexing[] * [[limits-maxComputeWorkGroupInvocations]] pname:maxComputeWorkGroupInvocations is the maximum total number of compute shader invocations in a single local workgroup. - The product of the X, Y, and Z sizes as specified by the code:LocalSize - execution mode in shader modules and by the object decorated by the - code:WorkgroupSize decoration must: be less than or equal to this limit. + The product of the X, Y, and Z sizes, as specified by the code:LocalSize + execution mode in shader modules or by the object decorated by the + code:WorkgroupSize decoration, must: be less than or equal to this + limit. * [[limits-maxComputeWorkGroupSize]] pname:maxComputeWorkGroupSize[3] is the maximum size of a local compute workgroup, per dimension. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. - The pname:x, pname:y, and pname:z sizes specified by the code:LocalSize - execution mode and by the object decorated by the code:WorkgroupSize - decoration in shader modules must: be less than or equal to the - corresponding limit. + The pname:x, pname:y, and pname:z sizes, as specified by the + code:LocalSize execution mode or by the object decorated by the + code:WorkgroupSize decoration in shader modules, must: be less than or + equal to the corresponding limit. * [[limits-subPixelPrecisionBits]] pname:subPixelPrecisionBits is the number of bits of subpixel precision in framebuffer coordinates [eq]#x~f~# and [eq]#y~f~#. @@ -1465,34 +1466,36 @@ describe the following implementation-dependent limits: See <>. * pname:maxTaskWorkGroupInvocations is the maximum total number of task shader invocations in a single local workgroup. - The product of the X, Y, and Z sizes as specified by the code:LocalSize - execution mode in shader modules and by the object decorated by the - code:WorkgroupSize decoration must: be less than or equal to this limit. + The product of the X, Y, and Z sizes, as specified by the code:LocalSize + execution mode in shader modules or by the object decorated by the + code:WorkgroupSize decoration, must: be less than or equal to this + limit. * pname:maxTaskWorkGroupSize[3] is the maximum size of a local task workgroup. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. - The pname:x, pname:y, and pname:z sizes specified by the code:LocalSize - execution mode and by the object decorated by the code:WorkgroupSize - decoration in shader modules must: be less than or equal to the - corresponding limit. + The pname:x, pname:y, and pname:z sizes, as specified by the + code:LocalSize execution mode or by the object decorated by the + code:WorkgroupSize decoration in shader modules, must: be less than or + equal to the corresponding limit. * pname:maxTaskTotalMemorySize is the maximum number of bytes that the task shader can use in total for shared and output memory combined. * pname:maxTaskOutputCount is the maximum number of output tasks a single task shader workgroup can emit. * pname:maxMeshWorkGroupInvocations is the maximum total number of mesh shader invocations in a single local workgroup. - The product of the X, Y, and Z sizes as specified by the code:LocalSize - execution mode in shader modules and by the object decorated by the - code:WorkgroupSize decoration must: be less than or equal to this limit. + The product of the X, Y, and Z sizes, as specified by the code:LocalSize + execution mode in shader modules or by the object decorated by the + code:WorkgroupSize decoration, must: be less than or equal to this + limit. * pname:maxMeshWorkGroupSize[3] is the maximum size of a local mesh workgroup. These three values represent the maximum local workgroup size in the X, Y, and Z dimensions, respectively. - The pname:x, pname:y, and pname:z sizes specified by the code:LocalSize - execution mode and by the object decorated by the code:WorkgroupSize - decoration in shader modules must: be less than or equal to the - corresponding limit. + The pname:x, pname:y, and pname:z sizes, as specified by the + code:LocalSize execution mode or by the object decorated by the + code:WorkgroupSize decoration in shader modules, must: be less than or + equal to the corresponding limit. * pname:maxMeshTotalMemorySize is the maximum number of bytes that the mesh shader can use in total for shared and output memory combined. * pname:maxMeshOutputVertices is the maximum number of vertices a mesh diff --git a/chapters/memory.txt b/chapters/memory.txt index 5bcd504d..a1d29d45 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -467,8 +467,8 @@ To query memory properties, call: include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties.txt[] * pname:physicalDevice is the handle to the device to query. - * pname:pMemoryProperties points to an instance of - sname:VkPhysicalDeviceMemoryProperties structure in which the properties + * pname:pMemoryProperties points to an instance of the + slink:VkPhysicalDeviceMemoryProperties structure in which the properties are returned. include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[] @@ -652,8 +652,8 @@ include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[] endif::VK_KHR_get_physical_device_properties2[] * pname:physicalDevice is the handle to the device to query. - * pname:pMemoryProperties points to an instance of - sname:VkPhysicalDeviceMemoryProperties2 structure in which the + * pname:pMemoryProperties points to an instance of the + slink:VkPhysicalDeviceMemoryProperties2 structure in which the properties are returned. fname:vkGetPhysicalDeviceMemoryProperties2 behaves similarly to @@ -2834,7 +2834,7 @@ Protected memory adds the following concepts: * Queue operations ** Unprotected queue operations ** Protected queue operations - + [[memory-protected-access-rules]] ==== Protected Memory Access Rules @@ -2848,7 +2848,7 @@ operations: transfer stage. * Perform a query within protected queue operations. * Execute an indirect command within protected queue operations. - + If slink:VkPhysicalDeviceProtectedMemoryProperties::pname:protectedNoFault is ename:VK_TRUE, these operations are valid, but reads will return undefined: values, and writes will either be dropped or store undefined: diff --git a/chapters/queries.txt b/chapters/queries.txt index d9215473..866d6eca 100644 --- a/chapters/queries.txt +++ b/chapters/queries.txt @@ -17,7 +17,10 @@ buffer object on the device. The supported query types are <>, <>, and <>. - +ifdef::VK_INTEL_performance_query[] +<> are also supported if the associated extension +is available. +endif::VK_INTEL_performance_query[] [[queries-pools]] == Query Pools @@ -144,6 +147,10 @@ ifdef::VK_EXT_transform_feedback[] * ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT specifies a <>. endif::VK_EXT_transform_feedback[] +ifdef::VK_INTEL_performance_query[] + * ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL specifies a + <>. +endif::VK_INTEL_performance_query[] -- @@ -924,6 +931,12 @@ before using the results. If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_TIMESTAMP, pname:flags must: not contain ename:VK_QUERY_RESULT_PARTIAL_BIT +ifdef::VK_INTEL_performance_query[] + * [[VUID-vkCmdCopyQueryPoolResults-queryType-02734]] + flink:vkCmdCopyQueryPoolResults must: not be called if the + pname:queryType used to create pname:queryPool was + ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL. +endif::VK_INTEL_performance_query[] **** include::{generated}/validity/protos/vkCmdCopyQueryPoolResults.txt[] @@ -1300,3 +1313,7 @@ fname:vkGetQueryPoolResults). endif::VK_EXT_transform_feedback[] + +ifdef::VK_INTEL_performance_query[] +include::VK_INTEL_performance_query/queries.txt[] +endif::VK_INTEL_performance_query[] diff --git a/chapters/renderpass.txt b/chapters/renderpass.txt index 5da8bcdc..6effe62a 100644 --- a/chapters/renderpass.txt +++ b/chapters/renderpass.txt @@ -2246,7 +2246,11 @@ are otherwise identical except for: As an additional special case, if two render passes have a single subpass, they are compatible even if they have different resolve attachment -references but satisfy the other compatibility conditions. +references +ifdef::VK_KHR_depth_stencil_resolve[] +or depth/stencil resolve modes +endif::VK_KHR_depth_stencil_resolve[] +but satisfy the other compatibility conditions. A framebuffer is compatible with a render pass if it was created using the same render pass or a compatible render pass. diff --git a/chapters/synchronization.txt b/chapters/synchronization.txt index fae5bd5c..c6f44db2 100644 --- a/chapters/synchronization.txt +++ b/chapters/synchronization.txt @@ -4628,16 +4628,51 @@ The set of supported time domains consists of: include::{generated}/api/enums/VkTimeDomainEXT.txt[] * ename:VK_TIME_DOMAIN_DEVICE_EXT specifies the device time domain. - Timestamp values in this time domain are comparable with device - timestamp values captured using flink:vkCmdWriteTimestamp and are - defined to be incrementing according to the - <> of the device. + Timestamp values in this time domain use the same units and are + comparable with device timestamp values captured using + flink:vkCmdWriteTimestamp and are defined to be incrementing according + to the <> of the device. + * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_EXT specifies the CLOCK_MONOTONIC time domain available on POSIX platforms. + Timestamp values in this time domain are in units of nanoseconds and are + comparable with platform timestamp values captured using the POSIX + clock_gettime API as computed by this example: + +[source,c] +---- +struct timespec tv; +clock_gettime(CLOCK_MONOTONIC, &tv); +return tv.tv_nsec + tv.tv_sec*1000000000ull; +---- + * ename:VK_TIME_DOMAIN_CLOCK_MONOTONIC_RAW_EXT specifies the CLOCK_MONOTONIC_RAW time domain available on POSIX platforms. + Timestamp values in this time domain are in units of nanoseconds and are + comparable with platform timestamp values captured using the POSIX + clock_gettime API as computed by this example: + +[source,c] +---- +struct timespec tv; +clock_gettime(CLOCK_MONOTONIC_RAW, &tv); +return tv.tv_nsec + tv.tv_sec*1000000000ull; +---- + * ename:VK_TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_EXT specifies the performance counter (QPC) time domain available on Windows. + Timestamp values in this time domain are in the same units as those + provided by the Windows QueryPerformanceCounter API and are comparable + with platform timestamp values captured using that API as computed by + this example: + +[source,c] +---- +LARGE_INTEGER counter; +QueryPerformanceCounter(&counter); +return counter.QuadPart; +---- + -- endif::VK_EXT_calibrated_timestamps[] diff --git a/chapters/tessellation.txt b/chapters/tessellation.txt index 9dab7abc..1705c034 100644 --- a/chapters/tessellation.txt +++ b/chapters/tessellation.txt @@ -430,7 +430,7 @@ The area between the outer and inner rectangles is completely filled by non-overlapping triangles. Two of the three vertices of each triangle are adjacent vertices on a subdivided edge of one rectangle; the third is one of the vertices on the -corresponding edge of the other triangle. +corresponding edge of the other rectangle. If either edge of the innermost rectangle is degenerate, the area near the corresponding outer edges is filled by connecting each vertex on the outer edge with the single vertex making up the _inner edge_. diff --git a/scripts/genRef.py b/scripts/genRef.py index fe8d7df8..9b371dbc 100755 --- a/scripts/genRef.py +++ b/scripts/genRef.py @@ -724,7 +724,7 @@ if __name__ == '__main__': for prefix in conventions.extension_index_prefixes: # Splits up into chunks, sorted within each chunk. filtered_extensions = sorted( - [name for name in ext_names + [name for name in desired_extensions if name.startswith(prefix) and name not in extensions]) for name in filtered_extensions: extensions[name] = None diff --git a/scripts/reflow_count.py b/scripts/reflow_count.py index 7480f10d..c15e8f3f 100644 --- a/scripts/reflow_count.py +++ b/scripts/reflow_count.py @@ -1,2 +1,2 @@ # The value to start tagging VU statements at, unless overridden by -nextvu -startVUID = 2734 +startVUID = 2738 diff --git a/style/extensions.txt b/style/extensions.txt index 22b160c8..ec812719 100644 --- a/style/extensions.txt +++ b/style/extensions.txt @@ -812,13 +812,13 @@ extensions must define two additional tokens. files and the revision supported by the Vulkan implementation (the pname:specVersion field of the sname:VkExtensionProperties structure corresponding to the extension and returned by one of the - link:html/vkspec.html#extendingvulkan-extensions[extension queries]) - may differ. + link:html/vkspec.html#extendingvulkan-extensions[extension queries]) may + differ. The revision value indicates a patch version of the extension specification, and differences in this version number maintain full compatibility, as defined in the - link:html/vkspec.html#_compatibility_guarantees_informative[Compatibility Guarantees] - section of the <>. + link:html/vkspec.html#_compatibility_guarantees_informative[Compatibility + Guarantees] section of the <>. [NOTE] .Note diff --git a/style/naming.txt b/style/naming.txt index 40019c57..13f4df04 100644 --- a/style/naming.txt +++ b/style/naming.txt @@ -276,8 +276,8 @@ application behavior. If the results are not invariant, the lifetime of the results should be clearly described in the command description. See -link:html/vkspec.html#fundamentals-commandsyntax-results-lifetime[Lifetime of Retrieved Results] -in the specification for more information. +link:html/vkspec.html#fundamentals-commandsyntax-results-lifetime[Lifetime +of Retrieved Results] in the specification for more information. These commands fall into two categories from a naming perspective: diff --git a/style/writing.txt b/style/writing.txt index 8a4ed3ca..9f865702 100644 --- a/style/writing.txt +++ b/style/writing.txt @@ -43,8 +43,9 @@ Never use ambigious formats such as "`09/12/16`". [[writing-misc-a-an]] === A/An and Markup Macros -Use "`a`" and "`an`" https://www.grammar.com/a-vs-an-when-to-use/[correctly], -based on the *sound* of the letter beginning the following word. +Use "`a`" and "`an`" +https://www.grammar.com/a-vs-an-when-to-use/[correctly], based on the +*sound* of the letter beginning the following word. It is easy to get this wrong when talking about Vulkan API names tagged with the <>. diff --git a/styleguide.txt b/styleguide.txt index 89b4f784..0e1ef310 100644 --- a/styleguide.txt +++ b/styleguide.txt @@ -113,8 +113,7 @@ which documentation authors must comply. [[iso-8601]] International Organization for Standardization, _Data elements and interchange formats -- Information interchange -- Representation of dates -and times_, https://www.iso.org/standard/40874.html, -2004-12-01. +and times_, https://www.iso.org/standard/40874.html, 2004-12-01. Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. [[vulkan-docs]] diff --git a/xml/vk.xml b/xml/vk.xml index 5dc306ef..380640be 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -89,6 +89,7 @@ server. + @@ -153,7 +154,7 @@ server. // Vulkan 1.1 version number #define VK_API_VERSION_1_1 VK_MAKE_VERSION(1, 1, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 108 +#define VK_HEADER_VERSION 109 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -366,6 +367,7 @@ typedef void CAMetalLayer; VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkValidationCacheEXT) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureNV) + VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkPerformanceConfigurationINTEL) WSI extensions VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR) @@ -499,6 +501,11 @@ typedef void CAMetalLayer; + + + + + WSI extensions @@ -3896,6 +3903,49 @@ typedef void CAMetalLayer; void* pNext VkBool32 shaderIntegerFunctions2 + + uint32_t value32 + uint64_t value64 + float valueFloat + VkBool32 valueBool + const char* valueString + + + VkPerformanceValueTypeINTEL type + VkPerformanceValueDataINTEL data + + + VkStructureType sType + const void* pNext + void* pUserData + + + VkStructureType sType + const void* pNext + VkQueryPoolSamplingModeINTEL performanceCountersSampling + + + VkStructureType sType + const void* pNext + uint64_t marker + + + VkStructureType sType + const void* pNext + uint32_t marker + + + VkStructureType sType + const void* pNext + VkPerformanceOverrideTypeINTEL type + VkBool32 enable + uint64_t parameter + + + VkStructureType sType + const void* pNext + VkPerformanceConfigurationTypeINTEL type + Vulkan enumerant (token) definitions @@ -5134,6 +5184,28 @@ typedef void CAMetalLayer; + + + + + + + + + + + + + + + + + + + + + + VkResult vkCreateInstance @@ -5250,7 +5322,7 @@ typedef void CAMetalLayer; VkResult vkQueueSubmit VkQueue queue uint32_t submitCount - const VkSubmitInfo* pSubmits + const VkSubmitInfo* pSubmits VkFence fence @@ -5357,7 +5429,7 @@ typedef void CAMetalLayer; VkResult vkQueueBindSparse VkQueue queue uint32_t bindInfoCount - const VkBindSparseInfo* pBindInfo + const VkBindSparseInfo* pBindInfo VkFence fence @@ -7177,7 +7249,7 @@ typedef void CAMetalLayer; void vkCmdBindShadingRateImageNV VkCommandBuffer commandBuffer - VkImageView imageView + VkImageView imageView VkImageLayout imageLayout @@ -7378,6 +7450,52 @@ typedef void CAMetalLayer; uint32_t* pCombinationCount VkFramebufferMixedSamplesCombinationNV* pCombinations + + VkResult vkInitializePerformanceApiINTEL + VkDevice device + const VkInitializePerformanceApiInfoINTEL* pInitializeInfo + + + void vkUninitializePerformanceApiINTEL + VkDevice device + + + VkResult vkCmdSetPerformanceMarkerINTEL + VkCommandBuffer commandBuffer + const VkPerformanceMarkerInfoINTEL* pMarkerInfo + + + VkResult vkCmdSetPerformanceStreamMarkerINTEL + VkCommandBuffer commandBuffer + const VkPerformanceStreamMarkerInfoINTEL* pMarkerInfo + + + VkResult vkCmdSetPerformanceOverrideINTEL + VkCommandBuffer commandBuffer + const VkPerformanceOverrideInfoINTEL* pOverrideInfo + + + VkResult vkAcquirePerformanceConfigurationINTEL + VkDevice device + const VkPerformanceConfigurationAcquireInfoINTEL* pAcquireInfo + VkPerformanceConfigurationINTEL* pConfiguration + + + VkResult vkReleasePerformanceConfigurationINTEL + VkDevice device + VkPerformanceConfigurationINTEL configuration + + + VkResult vkQueueSetPerformanceConfigurationINTEL + VkQueue queue + VkPerformanceConfigurationINTEL configuration + + + VkResult vkGetPerformanceParameterINTEL + VkDevice device + VkPerformanceParameterTypeINTEL parameter + VkPerformanceValueINTEL* pValue + @@ -10396,10 +10514,41 @@ typedef void CAMetalLayer; - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +