diff --git a/ChangeLog.adoc b/ChangeLog.adoc index d4361f3dee..e3027fae5e 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,49 @@ appears frequently in the change log. ----------------------------------------------------- +Change log for March 31, 2023 Vulkan 1.3.246 spec update: + +Github Issues: + + * Remove redundant "`input attachment`" wording in descriptions of + ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT and + ename:VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT (public issue + 2083). + * Add a NOTE describing state of buffers passed in + flink:vkBindBufferMemory2::pname:pBindInfos if the command fails (public + issue 2086). + +Internal Issues + + * Add new <> + restricting code:OpTypeImage multisampling to be consistent the + slink:VkImageCreateInfo::pname:samples its bound image was created with + (internal issue 2426). + * Clarify that <> enables + sample shading (internal issue 2872). + * Add <> for + multiple code:OpVariable for one code:Location, and use code:Location + and code:Component terminology consistently in related parts of the + specification, rather than informal equivalent terms (internal MR 5630). + * Add a new <> + preventing code:InputAttachmentIndex overlaps (internal MR 5759). + * Move apiext:VK_NV_displacement_micromap interfaces to the provisional + `vulkan_beta.h` header (internal MR 5812). + * Remove redundant common validity VU 07977 for buffer alignment in buffer + <-> image copies (internal MR 5814). + * Remove redundant slink:VkWriteDescriptorSet VU 07729 (internal MR 5815). + * Describe multi-planar aspect masks consistently in VU statements + (internal MR 5816). + * Fix ptext:width -> pname:height typo in slink:VkRenderingInfo VU 07816 + (internal MR 5817). + +New Extensions: + + * apiext:VK_EXT_shader_object + * apiext:VK_EXT_shader_tile_image + +----------------------------------------------------- + Change log for March 24, 2023 Vulkan 1.3.245 spec update: Github Issues: diff --git a/Makefile b/Makefile index 14ac63306f..7ea26eb94b 100644 --- a/Makefile +++ b/Makefile @@ -104,7 +104,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 245 +PATCHVERSION = 246 ifneq (,$(findstring VK_VERSION_1_3,$(VERSIONS))) SPECMINOR = 3 diff --git a/appendices/VK_EXT_shader_object.adoc b/appendices/VK_EXT_shader_object.adoc new file mode 100644 index 0000000000..33502ecfe4 --- /dev/null +++ b/appendices/VK_EXT_shader_object.adoc @@ -0,0 +1,340 @@ +// Copyright 2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_shader_object.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-03-30 +*Interactions and External Dependencies*:: + - Interacts with `apiext:VK_EXT_extended_dynamic_state` + - Interacts with `apiext:VK_EXT_extended_dynamic_state2` + - Interacts with `apiext:VK_EXT_extended_dynamic_state3` + - Interacts with `apiext:VK_EXT_vertex_input_dynamic_state` +*IP Status*:: + No known IP claims. +*Contributors*:: + - Piers Daniell, NVIDIA + - Sandy Jamieson, Nintendo + - Žiga Markuš, LunarG + - Tobias Hector, AMD + - Alex Walters, Imagination + - Shahbaz Youssefi, Google + - Ralph Potter, Samsung + - Jan-Harald Fredriksen, ARM + - Connor Abott, Valve + - Arseny Kapoulkine, Roblox + - Patrick Doane, Activision + - Jeff Leger, Qualcomm + - Stu Smith, AMD + - Chris Glover, Google + - Ricardo Garcia, Igalia + - Faith Ekstrand, Collabora + - Timur Kristóf, Valve + - Constantine Shablya, Collabora + - Daniel Koch, NVIDIA + - Alyssa Rosenzweig, Collabora + - Mike Blumenkrantz, Valve + - Samuel Pitoiset, Valve + - Qun Lin, AMD + - Spencer Fricke, LunarG + - Soroush Faghihi Kashani, Imagination + +=== Description + +This extension introduces a new sname:VkShaderEXT object type which +represents a single compiled shader stage. +Shader objects can be used as a more flexible but comparably performant +alternative to sname:VkPipeline objects. + +include::{generated}/interfaces/VK_EXT_shader_object.adoc[] + +=== Examples + +*Example 1* + +Create linked pair of vertex and fragment shaders. + +[source,c++] +-------------------------------------- +// Logical device created with the shaderObject feature enabled +VkDevice device; + +// SPIR-V shader code for a vertex shader, along with its size in bytes +void* pVertexSpirv; +size_t vertexSpirvSize; + +// SPIR-V shader code for a fragment shader, along with its size in bytes +void* pFragmentSpirv; +size_t fragmentSpirvSize; + +// Descriptor set layout compatible with the shaders +VkDescriptorSetLayout descriptorSetLayout; + +VkShaderCreateInfoEXT shaderCreateInfos[2] = +{ + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + .nextStage = VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexSpirvSize, + .pCode = pVertexSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentSpirvSize, + .pCode = pFragmentSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + } +}; + +VkResult result; +VkShaderEXT shaders[2]; + +result = vkCmdCreateShadersEXT(device, 2, &shaderCreateInfos, NULL, shaders); +if (result != VK_SUCCESS) +{ + // Handle error +} +-------------------------------------- + +Later, during command buffer recording, bind the linked shaders and draw. + +[source,c++] +-------------------------------------- +// Command buffer in the recording state +VkCommandBuffer commandBuffer; + +// Vertex and fragment shader objects created above +VkShaderEXT shaders[2]; + +// Assume vertex buffers, descriptor sets, etc. have been bound, and existing +// state setting commands have been called to set all required state + +const VkShaderStageFlagBits stages[2] = +{ + VK_SHADER_STAGE_VERTEX_BIT, + VK_SHADER_STAGE_FRAGMENT_BIT +}; + +// Bind linked shaders +vkCmdBindShadersEXT(commandBuffer, 2, stages, shaders); + +// Equivalent to the previous line. Linked shaders can be bound one at a time, +// in any order: +vkCmdBindShadersEXT(commandBuffer, 1, &stages[1], &shaders[1]); +vkCmdBindShadersEXT(commandBuffer, 1, &stages[0], &shaders[0]); + +// The above is sufficient to draw if the device was created with the +// tessellationShader and geometryShader features disabled. Otherwise, since +// those stages should not execute, vkCmdBindShadersEXT() must be called at +// least once with each of their stages in pStages before drawing: + +const VkShaderStageFlagBits unusedStages[3] = +{ + VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + VK_SHADER_STAGE_GEOMETRY_BIT +}; + +// NULL pShaders is equivalent to an array of stageCount VK_NULL_HANDLE values, +// meaning no shaders are bound to those stages, and that any previously bound +// shaders are unbound +vkCmdBindShadersEXT(commandBuffer, 3, unusedStages, NULL); + +// Draw a triangle +vkCmdDraw(commandBuffer, 3, 1, 0, 0); +-------------------------------------- + +*Example 2* + +Create unlinked vertex, geometry, and fragment shaders. + +[source,c++] +-------------------------------------- +// Logical device created with the shaderObject feature enabled +VkDevice device; + +// SPIR-V shader code for vertex shaders, along with their sizes in bytes +void* pVertexSpirv[2]; +size_t vertexSpirvSize[2]; + +// SPIR-V shader code for a geometry shader, along with its size in bytes +void pGeometrySpirv; +size_t geometrySpirvSize; + +// SPIR-V shader code for fragment shaders, along with their sizes in bytes +void* pFragmentSpirv[2]; +size_t fragmentSpirvSize[2]; + +// Descriptor set layout compatible with the shaders +VkDescriptorSetLayout descriptorSetLayout; + +VkShaderCreateInfoEXT shaderCreateInfos[5] = +{ + // Stage order does not matter + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_GEOMETRY_BIT, + .nextStage = VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = pGeometrySpirv, + .pCode = geometrySpirvSize, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + .nextStage = VK_SHADER_STAGE_GEOMETRY_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexSpirvSize[0], + .pCode = pVertexSpirv[0], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentSpirvSize[0], + .pCode = pFragmentSpirv[0], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentSpirvSize[1], + .pCode = pFragmentSpirv[1], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + // Suppose we want this vertex shader to be able to be followed by + // either a geometry shader or fragment shader: + .nextStage = VK_SHADER_STAGE_GEOMETRY_BIT | VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexSpirvSize[1], + .pCode = pVertexSpirv[1], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout; + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + } +}; + +VkResult result; +VkShaderEXT shaders[5]; + +result = vkCmdCreateShadersEXT(device, 5, &shaderCreateInfos, NULL, shaders); +if (result != VK_SUCCESS) +{ + // Handle error +} +-------------------------------------- + +Later, during command buffer recording, bind the linked shaders in different +combinations and draw. + +[source,c++] +-------------------------------------- +// Command buffer in the recording state +VkCommandBuffer commandBuffer; + +// Vertex, geometry, and fragment shader objects created above +VkShaderEXT shaders[5]; + +// Assume vertex buffers, descriptor sets, etc. have been bound, and existing +// state setting commands have been called to set all required state + +const VkShaderStageFlagBits vertexStage = VK_SHADER_STAGE_VERTEX_BIT; +const VkShaderStageFlagBits geometryStage = VK_SHADER_STAGE_VERTEX_BIT; +const VkShaderStageFlagBits fragmentStage = VK_SHADER_STAGE_VERTEX_BIT; + +// Bind unlinked vertex shader +vkCmdBindShadersEXT(commandBuffer, 1, &vertexStage, &shaders[0]); + +// Bind unlinked fragment shader +vkCmdBindShadersEXT(commandBuffer, 1, &fragmentStage, &shaders[3]); + +// Bind unlinked geometry shader +vkCmdBindShadersEXT(commandBuffer, 1, &geometryStage, &shaders[2]); + +// Assume the tessellationShader feature is disabled, so vkCmdBindShadersEXT() +// need not have been called with either tessellation stage + +// Draw a triangle +vkCmdDraw(commandBuffer, 3, 1, 0, 0); + +// Bind a different unlinked fragment shader +vkCmdBindShadersEXT(commandBuffer, 1, &fragmentStage, &shaders[4]); + +// Draw another triangle +vkCmdDraw(commandBuffer, 3, 1, 0, 0); + +// Bind a different unlinked vertex shader +vkCmdBindShadersEXT(commandBuffer, 1, &vertexStage, &shaders[1]); + +// Draw another triangle +vkCmdDraw(commandBuffer, 3, 1, 0, 0); +-------------------------------------- + +=== Version History + + * Revision 1, 2023-03-30 (Daniel Story) + ** Initial draft diff --git a/appendices/VK_EXT_shader_tile_image.adoc b/appendices/VK_EXT_shader_tile_image.adoc new file mode 100644 index 0000000000..9dc5b1e7d3 --- /dev/null +++ b/appendices/VK_EXT_shader_tile_image.adoc @@ -0,0 +1,81 @@ +// Copyright (c) 2022-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_EXT_shader_tile_image.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-03-23 +*IP Status*:: + No known IP claims. +*Interactions and External Dependencies*:: + - This extension requires + {spirv}/EXT/SPV_EXT_shader_tile_image.html[`SPV_EXT_shader_tile_image`] + - This extension provides API support for + https://raw.githubusercontent.com/KhronosGroup/GLSL/master/extensions/ext/GL_EXT_shader_tile_image.txt[`GL_EXT_shader_tile_image`] + +*Contributors*:: + - Sandeep Kakarlapudi, Arm + - Jan-Harald Fredriksen, Arm + - James Fitzpatrick, Imagination + - Andrew Garrard, Imagination + - Jeff Leger, Qualcomm + - Huilong Wang, Huawei + - Graeme Leese, Broadcom + - Hans-Kristian Arntzen, Valve + - Tobias Hector, AMD + - Jeff Bolz, NVIDIA + - Shahbaz Youssefi, Google + +=== Description + +This extension allows fragment shader invocations to read color, depth and +stencil values at their pixel location in rasterization order. +The functionality is only available when using dynamic render passes +introduced by VK_KHR_dynamic_rendering. +Example use cases are programmable blending and deferred shading. + +See <> for +more information. + +include::{generated}/interfaces/VK_EXT_shader_tile_image.adoc[] + +=== Issues + +None. + +=== Examples + +Color read example. +[source,c] +---- +layout( location = 0 /* aliased to color attachment 0 */ ) tileImageEXT highp attachmentEXT color0; +layout( location = 1 /* aliased to color attachment 1 */ ) tileImageEXT highp attachmentEXT color1; + +layout( location = 0 ) out vec4 fragColor; + +void main() +{ + vec4 value = colorAttachmentReadEXT(color0) + colorAttachmentReadEXT(color1); + fragColor = value; +} +---- + +Depth & Stencil read example. +[source,c] +---- +void main() +{ + // read sample 0: works for non-MSAA or MSAA targets + highp float last_depth = depthAttachmentReadEXT(); + lowp uint last_stencil = stencilAttachmentReadEXT(); + + //.. +} +---- +=== Version History + + * Revision 1, 2023-03-23 (Sandeep Kakarlapudi) + ** Initial version diff --git a/appendices/glossary.adoc b/appendices/glossary.adoc index f134a1a482..9f2ed00197 100644 --- a/appendices/glossary.adoc +++ b/appendices/glossary.adoc @@ -681,6 +681,14 @@ Frame (Video):: multi-dimensional array of chroma samples. endif::VK_KHR_video_queue[] +ifdef::VK_EXT_shader_tile_image[] +[[glossary-fragment-tile-image-interface]] +Fragment Tile Image Interface:: + A fragment shader entry point's variables with code:TileImageEXT storage + class and a decoration of code:Location, which are used to read values + from color attachments. +endif::VK_EXT_shader_tile_image[] + Framebuffer:: A collection of image views and a set of dimensions that, in conjunction with a render pass, define the inputs and outputs used by drawing @@ -1729,6 +1737,15 @@ Texel Coordinate System:: defining how texel coordinates are interpreted in an image or a specific mipmap level of an image. +ifdef::VK_EXT_shader_tile_image[] +[[glossary-tile-image]] +Tile Image:: + A per-tile view of a framebuffer attachment. + If the `apiext:VK_EXT_shader_tile_image` extension is enabled, the + framebuffer is considered to be divided into tiles. + +endif::VK_EXT_shader_tile_image[] + ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] Timeline Semaphore:: A semaphore with a strictly increasing 64-bit unsigned integer payload diff --git a/appendices/spirvenv.adoc b/appendices/spirvenv.adoc index f25c674979..d09cfc214e 100644 --- a/appendices/spirvenv.adoc +++ b/appendices/spirvenv.adoc @@ -176,7 +176,7 @@ or knowledge of runtime information, such as enabled features. *Uniform*, *Output*, *Workgroup*, *Private*, *Function*, *PushConstant*, *Image*, *StorageBuffer*, *RayPayloadKHR*, *IncomingRayPayloadKHR*, *HitAttributeKHR*, *CallableDataKHR*, *IncomingCallableDataKHR*, - *ShaderRecordBufferKHR*, or *PhysicalStorageBuffer* + *ShaderRecordBufferKHR*, *PhysicalStorageBuffer*, or *TileImageEXT* * [[VUID-{refpage}-None-04644]] If the *Storage Class* is *Output*, then it must: not be used in the *GlCompute*, *RayGenerationKHR*, *IntersectionKHR*, *AnyHitKHR*, @@ -184,6 +184,9 @@ or knowledge of runtime information, such as enabled features. * [[VUID-{refpage}-None-04645]] If the *Storage Class* is *Workgroup*, then it must: only be used in the task, mesh, or compute execution models + * [[VUID-{refpage}-None-08720]] + If the *Storage Class* is *TileImageEXT*, then it must: only be used in + the fragment execution model * [[VUID-{refpage}-OpAtomicStore-04730]] code:OpAtomicStore must: not use *Acquire*, *AcquireRelease*, or *SequentiallyConsistent* memory semantics @@ -548,6 +551,14 @@ or knowledge of runtime information, such as enabled features. * [[VUID-{refpage}-OpEntryPoint-06674]] Each code:OpEntryPoint must: not statically use more than one code:OpVariable in the code:PushConstant storage class + * [[VUID-{refpage}-OpEntryPoint-08721]] + Each code:OpEntryPoint must: not have more than one code:Input variable + assigned the same code:Component word inside a code:Location slot, + either explicitly or implicitly + * [[VUID-{refpage}-OpEntryPoint-08722]] + Each code:OpEntryPoint must: not have more than one code:Output variable + assigned the same code:Component word inside a code:Location slot, + either explicitly or implicitly * [[VUID-{refpage}-Result-04780]] The code:Result code:Type operand of any code:OpImageRead or code:OpImageSparseRead instruction must: be a vector of four components @@ -620,6 +631,14 @@ or knowledge of runtime information, such as enabled features. * [[VUID-{refpage}-Input-07290]] Variables with a storage class of code:Input or code:Output and a type of code:OpTypeBool must: be decorated with the code:BuiltIn decoration + * [[VUID-{refpage}-TileImageEXT-08723]] + The tile image variable declarations must: obey the constraints on the + code:TileImageEXT storage class and the code:Location decoration + described in <> + * [[VUID-{refpage}-None-08724]] + The *TileImageEXT* storage class must: only be used for declaring tile + image variables. **** -- @@ -983,7 +1002,7 @@ ifdef::VK_EXT_transform_feedback[] The code:Offset plus size of the type of each variable, in the output interface of the entry point being compiled, decorated with code:XfbBuffer must: not be greater than - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataSize + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataSize * [[VUID-{refpage}-XfbBuffer-06309]] For any given code:XfbBuffer value, define the buffer data size to be smallest number of bytes such that, for all outputs decorated with the @@ -991,21 +1010,21 @@ ifdef::VK_EXT_transform_feedback[] plus the code:Offset is less than or equal to the buffer data size. For a given code:Stream, the sum of all the buffer data sizes for all buffers writing to that stream the must: not exceed - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreamDataSize + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreamDataSize * [[VUID-{refpage}-OpEmitStreamVertex-06310]] The Stream value to code:OpEmitStreamVertex and code:OpEndStreamPrimitive must: be less than - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams * [[VUID-{refpage}-transformFeedbackStreamsLinesTriangles-06311]] If the geometry shader emits to more than one vertex stream and - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackStreamsLinesTriangles + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:transformFeedbackStreamsLinesTriangles is ename:VK_FALSE, then execution mode must: be code:OutputPoints * [[VUID-{refpage}-Stream-06312]] The stream number value to code:Stream must: be less than - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackStreams * [[VUID-{refpage}-XfbStride-06313]] The XFB Stride value to code:XfbStride must: be less than or equal to - sname:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataStride + slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT::pname:maxTransformFeedbackBufferDataStride endif::VK_EXT_transform_feedback[] ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] * [[VUID-{refpage}-PhysicalStorageBuffer64-06314]] @@ -1072,18 +1091,18 @@ ifdef::VK_NV_mesh_shader[] * [[VUID-{refpage}-MeshNV-07113]] For mesh shaders using the code:MeshNV {ExecutionModel} the code:OutputVertices code:OpExecutionMode must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices + slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices * [[VUID-{refpage}-MeshNV-07114]] For mesh shaders using the code:MeshNV {ExecutionModel} the code:OutputPrimitivesNV code:OpExecutionMode must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives + slink:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives endif::VK_NV_mesh_shader[] ifdef::VK_EXT_mesh_shader[] * [[VUID-{refpage}-MeshEXT-07115]] For mesh shaders using the code:MeshEXT {ExecutionModel} the code:OutputVertices code:OpExecutionMode must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputVertices * [[VUID-{refpage}-MeshEXT-07332]] For mesh shaders using the code:MeshEXT {ExecutionModel} the "`Vertex Count`" operand of code:OpSetMeshOutputsEXT must: be less than or equal @@ -1092,7 +1111,7 @@ ifdef::VK_EXT_mesh_shader[] For mesh shaders using the code:MeshEXT {ExecutionModel} the code:OutputPrimitivesEXT code:OpExecutionMode must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshOutputPrimitives * [[VUID-{refpage}-MeshEXT-07333]] For mesh shaders using the code:MeshEXT {ExecutionModel} the "`Primitive Count`" operand of code:OpSetMeshOutputsEXT must: be less than or equal @@ -1108,60 +1127,60 @@ ifdef::VK_EXT_mesh_shader[] * [[VUID-{refpage}-TaskEXT-07291]] In task shaders using the code:TaskEXT {ExecutionModel} the pname:x size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[0] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[0] * [[VUID-{refpage}-TaskEXT-07292]] In task shaders using the code:TaskEXT {ExecutionModel} the pname:y size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[1] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[1] * [[VUID-{refpage}-TaskEXT-07293]] In task shaders using the code:TaskEXT {ExecutionModel} the pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[2] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupSize[2] * [[VUID-{refpage}-TaskEXT-07294]] In task shaders using the code:TaskEXT {ExecutionModel} the product of pname:x size, pname:y size, and pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupInvocations + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxTaskWorkGroupInvocations * [[VUID-{refpage}-MeshEXT-07295]] For mesh shaders using the code:MeshEXT {ExecutionModel} the pname:x size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[0] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[0] * [[VUID-{refpage}-MeshEXT-07296]] For mesh shaders using the code:MeshEXT {ExecutionModel} the pname:y size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[1] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[1] * [[VUID-{refpage}-MeshEXT-07297]] For mesh shaders using the code:MeshEXT {ExecutionModel} the pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[2] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupSize[2] * [[VUID-{refpage}-MeshEXT-07298]] For mesh shaders using the code:MeshEXT {ExecutionModel} the product of pname:x size, pname:y size, and pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupInvocations + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupInvocations * [[VUID-{refpage}-TaskEXT-07299]] In task shaders using the code:TaskEXT {ExecutionModel} the value of the "`Group Count X`" operand of code:OpEmitMeshTasksEXT must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[0] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[0] * [[VUID-{refpage}-TaskEXT-07300]] In task shaders using the code:TaskEXT {ExecutionModel} the value of the "`Group Count Y`" operand of code:OpEmitMeshTasksEXT must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[1] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[1] * [[VUID-{refpage}-TaskEXT-07301]] In task shaders using the code:TaskEXT {ExecutionModel} the value of the "`Group Count Z`" operand of code:OpEmitMeshTasksEXT must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[2] + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupCount[2] * [[VUID-{refpage}-TaskEXT-07302]] In task shaders using the code:TaskEXT {ExecutionModel} the product of the "`Group Count`" operands of code:OpEmitMeshTasksEXT must: be less than or equal to - sname:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupTotalCount + slink:VkPhysicalDeviceMeshShaderPropertiesEXT::pname:maxMeshWorkGroupTotalCount endif::VK_EXT_mesh_shader[] ifdef::VK_KHR_portability_subset[] * [[VUID-{refpage}-shaderSampleRateInterpolationFunctions-06325]] @@ -1533,19 +1552,19 @@ endif::VK_NV_ray_tracing_invocation_reorder[] * [[VUID-{refpage}-x-06429]] The pname:x size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[0] + slink:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[0] * [[VUID-{refpage}-y-06430]] The pname:y size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[1] + slink:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[1] * [[VUID-{refpage}-z-06431]] The pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[2] + slink:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupSize[2] * [[VUID-{refpage}-x-06432]] The product of pname:x size, pname:y size, and pname:z size in code:LocalSize or code:LocalSizeId must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupInvocations + slink:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupInvocations ifndef::VK_VERSION_1_3,VK_KHR_maintenance4[] * [[VUID-{refpage}-LocalSizeId-06433]] The execution mode code:LocalSizeId must: not be used @@ -1604,6 +1623,14 @@ endif::VK_VERSION_1_3,VK_KHR_zero_initialize_workgroup_memory[] If an code:OpImageSample* or code:OpImageFetch* operation has an image operand of code:ConstOffset then the offset value must: be less than or equal to <> + * [[VUID-{refpage}-samples-08725]] + If an code:OpTypeImage has an code:MS operand 0, its bound image must: + have been created with slink:VkImageCreateInfo::pname:samples as + ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-{refpage}-samples-08726]] + If an code:OpTypeImage has an code:MS operand 1, its bound image must: + not have been created with slink:VkImageCreateInfo::pname:samples as + ename:VK_SAMPLE_COUNT_1_BIT ifdef::VK_QCOM_render_pass_shader_resolve[] * [[VUID-{refpage}-SampleRateShading-06378]] If the subpass description contains @@ -1716,6 +1743,37 @@ ifdef::VK_QCOM_image_processing[] code:Texture code:Image and code:Box code:Size parameters must: be _dynamically uniform_ endif::VK_QCOM_image_processing[] + * [[VUID-{refpage}-OpEntryPoint-08727]] + Each code:OpEntryPoint must: not have more than one variable decorated + with code:InputAttachmentIndex per image aspect of the attachment image + bound to it, either explicitly or implicitly as described by + <> +ifdef::VK_EXT_shader_tile_image[] + * [[VUID-{refpage}-shaderTileImageColorReadAccess-08728]] + If <> is not enabled, + code:OpColorAttachmentReadEXT operation must: not be used + * [[VUID-{refpage}-shaderTileImageDepthReadAccess-08729]] + If <> is not enabled, + code:OpDepthAttachmentReadEXT operation must: not be used + * [[VUID-{refpage}-shaderTileImageStencilReadAccess-08730]] + If <> is not enabled, + code:OpStencilAttachmentReadEXT operation must: not be used + * [[VUID-{refpage}-minSampleShading-08731]] + If <> is enabled and + pname:minSampleShading is 1.0, the code:sample operand of any + code:OpColorAttachmentReadEXT, code:OpDepthAttachmentReadEXT, or + code:OpStencilAttachmentReadEXT operation must: evaluate to the value of + the <> for any + given fragment invocation + * [[VUID-{refpage}-minSampleShading-08732]] + If <> is enabled and any of the + code:OpColorAttachmentReadEXT, code:OpDepthAttachmentReadEXT, or + code:OpStencilAttachmentReadEXT operations are used, then + pname:minSampleShading must: be 1.0 +endif::VK_EXT_shader_tile_image[] **** -- diff --git a/chapters/VK_EXT_blend_operation_advanced/advanced_blend.adoc b/chapters/VK_EXT_blend_operation_advanced/advanced_blend.adoc index 1da037fd7e..d492ff4ac1 100644 --- a/chapters/VK_EXT_blend_operation_advanced/advanced_blend.adoc +++ b/chapters/VK_EXT_blend_operation_advanced/advanced_blend.adoc @@ -58,7 +58,7 @@ ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT. include::{generated}/validity/structs/VkPipelineColorBlendAdvancedStateCreateInfoEXT.adoc[] -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetColorBlendAdvancedEXT',desc='Specify the advanced color blend state dynamically for a command buffer',type='protos'] -- To <> the advanced blend state, @@ -77,9 +77,16 @@ include::{generated}/api/protos/vkCmdSetColorBlendAdvancedEXT.adoc[] corresponding attachments. This command sets the advanced blend operation parameters of the specified -attachments for subsequent drawing commands when the graphics pipeline is -created with ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set in +attachments for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_COLOR_BLEND_ADVANCED_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:srcPremultiplied, slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:dstPremultiplied, @@ -88,9 +95,25 @@ values used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendAdvancedEXT-None-08592]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendAdvancedEXT-None-08593]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetColorBlendAdvancedEXT-extendedDynamicState3ColorBlendAdvanced-07504]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetColorBlendAdvancedEXT.adoc[] @@ -132,7 +155,7 @@ include::{generated}/api/structs/VkColorBlendAdvancedEXT.adoc[] include::{generated}/validity/structs/VkColorBlendAdvancedEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] When using one of the operations in table <> diff --git a/chapters/VK_EXT_opacity_micromap/micromaps.adoc b/chapters/VK_EXT_opacity_micromap/micromaps.adoc index eec346bca9..9698f095d3 100644 --- a/chapters/VK_EXT_opacity_micromap/micromaps.adoc +++ b/chapters/VK_EXT_opacity_micromap/micromaps.adoc @@ -273,10 +273,12 @@ endif::VK_NV_displacement_micromap[] pname:format member of slink:VkMicromapTriangleEXT must: be a valid value from ename:VkOpacityMicromapFormatEXT ifdef::VK_NV_displacement_micromap[] - * [[VUID-VkMicromapBuildInfoEXT-type-08704]] If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the + * [[VUID-VkMicromapBuildInfoEXT-type-08704]] + If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the pname:format member of slink:VkMicromapUsageEXT must: be a valid value from ename:VkDisplacementMicromapFormatNV - * [[VUID-VkMicromapBuildInfoEXT-type-08705]] If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the + * [[VUID-VkMicromapBuildInfoEXT-type-08705]] + If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the pname:format member of slink:VkMicromapTriangleEXT must: be a valid value from ename:VkDisplacementMicromapFormatNV endif::VK_NV_displacement_micromap[] @@ -329,12 +331,14 @@ include::{generated}/api/structs/VkMicromapUsageEXT.adoc[] must: be less than or equal to slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity4StateSubdivisionLevel ifdef::VK_NV_displacement_micromap[] - * [[VUID-VkMicromapUsageEXT-format-08706]] If the elink:VkMicromapTypeEXT of the micromap is + * [[VUID-VkMicromapUsageEXT-format-08706]] + If the elink:VkMicromapTypeEXT of the micromap is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:format must: be ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV - * [[VUID-VkMicromapUsageEXT-subdivisionLevel-08707]] If the elink:VkMicromapTypeEXT of the micromap is + * [[VUID-VkMicromapUsageEXT-subdivisionLevel-08707]] + If the elink:VkMicromapTypeEXT of the micromap is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:subdivisionLevel must: be less than or equal to slink:VkPhysicalDeviceDisplacementMicromapPropertiesNV::pname:maxDisplacementMicromapSubdivisionLevel @@ -381,12 +385,14 @@ include::{generated}/api/structs/VkMicromapTriangleEXT.adoc[] must: be less than or equal to slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity4StateSubdivisionLevel ifdef::VK_NV_displacement_micromap[] - * [[VUID-VkMicromapTriangleEXT-format-08708]] If the elink:VkMicromapTypeEXT of the micromap is + * [[VUID-VkMicromapTriangleEXT-format-08708]] + If the elink:VkMicromapTypeEXT of the micromap is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:format must: be ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV - * [[VUID-VkMicromapTriangleEXT-subdivisionLevel-08709]] If the elink:VkMicromapTypeEXT of the micromap is + * [[VUID-VkMicromapTriangleEXT-subdivisionLevel-08709]] + If the elink:VkMicromapTypeEXT of the micromap is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:subdivisionLevel must: be less than or equal to slink:VkPhysicalDeviceDisplacementMicromapPropertiesNV::pname:maxDisplacementMicromapSubdivisionLevel diff --git a/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.adoc b/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.adoc index bedf8a4ba0..7cb4c4d805 100644 --- a/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.adoc +++ b/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.adoc @@ -39,7 +39,7 @@ this structure to the pname:pNext chain of a sname:VkPipelineViewportStateCreateInfo structure and setting the graphics pipeline state with flink:vkCreateGraphicsPipelines. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetViewportWScalingEnableNV',desc='Specify the viewport W scaling enable state dynamically for a command buffer',type='protos'] -- @@ -54,25 +54,48 @@ include::{generated}/api/protos/vkCmdSetViewportWScalingEnableNV.adoc[] state. This command sets the pname:viewportWScalingEnable state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportWScalingEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetViewportWScalingEnableNV-None-08594]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetViewportWScalingEnableNV-None-08595]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetViewportWScalingEnableNV-extendedDynamicState3ViewportWScalingEnable-07580]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetViewportWScalingEnableNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetViewportWScalingNV',desc='Set the viewport W scaling dynamically for a command buffer',type='protos'] -- @@ -96,6 +119,7 @@ pname:pViewportWScalings replace the current state for the viewport index pname:viewportCount)#. This command sets the viewport *W* scaling for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. diff --git a/chapters/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc b/chapters/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc index 15fe46dd61..0cb8b9c1fb 100644 --- a/chapters/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc +++ b/chapters/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc @@ -13,14 +13,14 @@ ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-{refpage}-{imageparam}-07974]] If pname:{imageparam} does not have a depth/stencil format, then for each element of pname:pRegions, pname:bufferOffset must: be a multiple - of the format's texel block size + of the format's <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-{refpage}-{imageparam}-07975]] If pname:{imageparam} does not have either a depth/stencil or a <>, then for each element of pname:pRegions, pname:bufferOffset must: be a - multiple of the format's texel block size + multiple of the <> * [[VUID-{refpage}-{imageparam}-07976]] If pname:{imageparam} has a <>, then @@ -29,10 +29,6 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] the pname:aspectMask of the pname:imageSubresource as defined in <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] - * [[VUID-{refpage}-{imageparam}-07977]] - For each element of pname:pRegions, pname:bufferOffset must: be a - multiple of the <> of - the elink:VkFormat of pname:{imageparam} * [[VUID-{refpage}-{imageparam}-07978]] If pname:{imageparam} has a depth/stencil format, the pname:bufferOffset member of any element of pname:pRegions must: be a multiple of `4` diff --git a/chapters/commonvalidity/copy_image_common.adoc b/chapters/commonvalidity/copy_image_common.adoc index d57594a85a..8aa7433ed6 100644 --- a/chapters/commonvalidity/copy_image_common.adoc +++ b/chapters/commonvalidity/copy_image_common.adoc @@ -90,28 +90,16 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] format>> then for each element of pname:pRegions, pname:srcSubresource.aspectMask and pname:dstSubresource.aspectMask must: match - * [[VUID-{refpage}-srcImage-01552]] - If pname:srcImage has a elink:VkFormat with - <> then for each - element of pname:pRegions, pname:srcSubresource.aspectMask must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT - * [[VUID-{refpage}-srcImage-01553]] - If pname:srcImage has a elink:VkFormat with - <> then for - each element of pname:pRegions, pname:srcSubresource.aspectMask must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT - * [[VUID-{refpage}-dstImage-01554]] - If pname:dstImage has a elink:VkFormat with - <> then for each - element of pname:pRegions, pname:dstSubresource.aspectMask must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT - * [[VUID-{refpage}-dstImage-01555]] - If pname:dstImage has a elink:VkFormat with - <> then for - each element of pname:pRegions, pname:dstSubresource.aspectMask must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT + * [[VUID-{refpage}-srcImage-08713]] + If pname:srcImage has a <>, then for each element of pname:pRegions, + pname:srcSubresource.aspectMask must: be a single valid + <> + * [[VUID-{refpage}-dstImage-08714]] + If pname:dstImage has a <>, then for each element of pname:pRegions, + pname:dstSubresource.aspectMask must: be a single valid + <> * [[VUID-{refpage}-srcImage-01556]] If pname:srcImage has a <> diff --git a/chapters/commonvalidity/draw_common.adoc b/chapters/commonvalidity/draw_common.adoc index 36593d6587..bd641f7b00 100644 --- a/chapters/commonvalidity/draw_common.adoc +++ b/chapters/commonvalidity/draw_common.adoc @@ -70,36 +70,114 @@ include::{chapters}/commonvalidity/draw_dispatch_common.adoc[] ename:VK_DYNAMIC_STATE_LINE_WIDTH dynamic state enabled then flink:vkCmdSetLineWidth must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08617]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetPolygonModeEXT in the current command buffer set + pname:polygonMode to ename:VK_POLYGON_MODE_LINE, flink:vkCmdSetLineWidth + must: have been called in the current command buffer prior to this + drawing command + * [[VUID-{refpage}-None-08618]] + If a shader object is bound to the ename:VK_SHADER_STAGE_VERTEX_BIT + stage, and the most recent call to flink:vkCmdSetPrimitiveTopology in + the current command buffer set pname:primitiveTopology to any line + topology, flink:vkCmdSetLineWidth must: have been called in the current + command buffer prior to this drawing command + * [[VUID-{refpage}-None-08619]] + If a shader object that outputs line primitives is bound to the + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or + ename:VK_SHADER_STAGE_GEOMETRY_BIT stage, flink:vkCmdSetLineWidth must: + have been called in the current command buffer prior to this drawing + command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07834]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled then flink:vkCmdSetDepthBias must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08620]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetDepthBiasEnable in the current command buffer set + pname:depthBiasEnable to ename:VK_TRUE, flink:vkCmdSetDepthBias must: + have been called in the current command buffer prior to this drawing + command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07835]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled then flink:vkCmdSetBlendConstants must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08621]] + If a shader object is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT + stage, and the most recent call to flink:vkCmdSetRasterizerDiscardEnable + in the current command buffer set pname:rasterizerDiscardEnable to + ename:VK_FALSE, and the most recent call to + flink:vkCmdSetColorBlendEnableEXT in the current command buffer set any + element of pname:pColorBlendEnables to ename:VK_TRUE, and the most + recent call to flink:vkCmdSetColorBlendEquationEXT in the current + command buffer set the same element of pname:pColorBlendEquations to an + sname:VkColorBlendEquationEXT structure with any elink:VkBlendFactor + member with a value of ename:VK_BLEND_FACTOR_CONSTANT_COLOR, + ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR, + ename:VK_BLEND_FACTOR_CONSTANT_ALPHA, or + ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA, + flink:vkCmdSetBlendConstants must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07836]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled then flink:vkCmdSetDepthBounds must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08622]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetDepthBoundsTestEnable in the current command + buffer set pname:depthBoundsTestEnable to ename:VK_TRUE, + flink:vkCmdSetDepthBounds must: have been called in the current command + buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07837]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled then flink:vkCmdSetStencilCompareMask must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08623]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetStencilTestEnable in the current command buffer + set pname:stencilTestEnable to ename:VK_TRUE, + flink:vkCmdSetStencilCompareMask must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07838]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled then flink:vkCmdSetStencilWriteMask must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08624]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetStencilTestEnable in the current command buffer + set pname:stencilTestEnable to ename:VK_TRUE, + flink:vkCmdSetStencilWriteMask must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07839]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled then flink:vkCmdSetStencilReference must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08625]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetStencilTestEnable in the current command buffer + set pname:stencilTestEnable to ename:VK_TRUE, + flink:vkCmdSetStencilReference must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_1,VK_KHR_multiview[] * [[VUID-{refpage}-maxMultiviewInstanceIndex-02688]] If the draw is recorded in a render pass instance with multiview @@ -118,6 +196,14 @@ ifdef::VK_EXT_sample_locations[] ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT dynamic state enabled then flink:vkCmdSetSampleLocationsEXT must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08626]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetSampleLocationsEnableEXT in the current command + buffer set pname:sampleLocationsEnable to ename:VK_TRUE, + flink:vkCmdSetSampleLocationsEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-sampleLocationsPerPixel-07934]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT state enabled, then the @@ -133,41 +219,98 @@ ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] ename:VK_DYNAMIC_STATE_CULL_MODE dynamic state enabled then flink:vkCmdSetCullMode must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08627]] + If a shader object is bound to any graphics stage, + flink:vkCmdSetCullMode must: have been called in the current command + buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07841]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_FRONT_FACE dynamic state enabled then flink:vkCmdSetFrontFace must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08628]] + If a shader object is bound to any graphics stage, + flink:vkCmdSetFrontFace must: have been called in the current command + buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07843]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE dynamic state enabled then flink:vkCmdSetDepthTestEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08629]] + If a shader object is bound to any graphics stage, + flink:vkCmdSetDepthTestEnable must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07844]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE dynamic state enabled then flink:vkCmdSetDepthWriteEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08630]] + If a shader object is bound to any graphics stage, + flink:vkCmdSetDepthWriteEnable must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07845]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP dynamic state enabled then flink:vkCmdSetDepthCompareOp must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08631]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetDepthTestEnable in the current command buffer set + pname:depthTestEnable to ename:VK_TRUE, flink:vkCmdSetDepthCompareOp + must: have been called in the current command buffer prior to this + drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07846]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE dynamic state enabled then flink:vkCmdSetDepthBoundsTestEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08632]] + If a shader object is bound to any graphics stage, and the + <> feature is enabled, the + flink:vkCmdSetDepthBoundsTestEnable must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07847]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE dynamic state enabled then flink:vkCmdSetStencilTestEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08633]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetStencilTestEnable must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07848]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_STENCIL_OP dynamic state enabled then flink:vkCmdSetStencilOp must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08634]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and the most + recent call to flink:vkCmdSetStencilTestEnable in the current command + buffer set pname:stencilTestEnable to ename:VK_TRUE, then + flink:vkCmdSetStencilOp must: have been called in the current command + buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-viewportCount-03417]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT dynamic state enabled, but @@ -195,6 +338,15 @@ ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] drawing command, and the pname:viewportCount parameter of fname:vkCmdSetViewportWithCount must: match the pname:scissorCount parameter of fname:vkCmdSetScissorWithCount +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08635]] + If a shader object is bound to any graphics stage, then both + flink:vkCmdSetViewportWithCount and flink:vkCmdSetScissorWithCount must: + have been called in the current command buffer prior to this drawing + command, and the pname:viewportCount parameter of + fname:vkCmdSetViewportWithCount must: match the pname:scissorCount + parameter of fname:vkCmdSetScissorWithCount +endif::VK_EXT_shader_object[] ifdef::VK_NV_clip_space_w_scaling[] * [[VUID-{refpage}-viewportCount-04137]] If the bound graphics pipeline state was created with the @@ -212,6 +364,15 @@ ifdef::VK_NV_clip_space_w_scaling[] flink:vkCmdSetViewportWScalingNV must: be greater than or equal to the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWithCount +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08636]] + If a shader object is bound to any graphics stage, and the + `apiext:VK_NV_clip_space_w_scaling` extension is enabled on the device, + then the pname:viewportCount parameter in the last call to + flink:vkCmdSetViewportWScalingNV must: be greater than or equal to the + pname:viewportCount parameter in the last call to + flink:vkCmdSetViewportWithCount +endif::VK_EXT_shader_object[] endif::VK_NV_clip_space_w_scaling[] ifdef::VK_NV_shading_rate_image[] * [[VUID-{refpage}-viewportCount-04139]] @@ -231,6 +392,15 @@ ifdef::VK_NV_shading_rate_image[] flink:vkCmdSetViewportShadingRatePaletteNV must: be greater than or equal to the pname:viewportCount parameter in the last call to flink:vkCmdSetViewportWithCount +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08637]] + If a shader object is bound to any graphics stage, and the + <> feature is enabled on + the device, then the pname:viewportCount parameter in the last call to + flink:vkCmdSetViewportShadingRatePaletteNV must: be greater than or + equal to the pname:viewportCount parameter in the last call to + flink:vkCmdSetViewportWithCount +endif::VK_EXT_shader_object[] endif::VK_NV_shading_rate_image[] ifdef::VK_NV_viewport_swizzle[] * [[VUID-{refpage}-VkPipelineVieportCreateInfo-04141]] @@ -258,11 +428,21 @@ ifdef::VK_NV_scissor_exclusive[] ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV dynamic state enabled then flink:vkCmdSetExclusiveScissorEnableNV must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07879]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state enabled then flink:vkCmdSetExclusiveScissorNV must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08638]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetExclusiveScissorEnableNV in the current command + buffer set any element of pname:pExclusiveScissorEnables to + ename:VK_TRUE, then flink:vkCmdSetExclusiveScissorNV must: have been + called in the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_scissor_exclusive[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] @@ -271,11 +451,25 @@ ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE dynamic state enabled then flink:vkCmdSetRasterizerDiscardEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08639]] + If a shader object is bound to any graphics stage, then + flink:vkCmdSetRasterizerDiscardEnable must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-04877]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE dynamic state enabled then flink:vkCmdSetDepthBiasEnable must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08640]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetDepthBiasEnable must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state2[] * [[VUID-{refpage}-logicOp-04878]] If the bound graphics pipeline state was created with the @@ -283,6 +477,16 @@ ifdef::VK_EXT_extended_dynamic_state2[] flink:vkCmdSetLogicOpEXT must: have been called in the current command buffer prior to this drawing command and the pname:logicOp must: be a valid elink:VkLogicOp value +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08641]] + If a shader object is bound to any graphics stage, and the + <> feature is enabled on the device, and the + most recent call to flink:vkCmdSetRasterizerDiscardEnable in the current + command buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetLogicOpEXT must: have been called in the current command + buffer prior to this drawing command and the pname:logicOp must: be a + valid elink:VkLogicOp value +endif::VK_EXT_shader_object[] endif::VK_EXT_extended_dynamic_state2[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] ifdef::VK_KHR_fragment_shading_rate[] @@ -298,6 +502,17 @@ ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] command buffer prior to this drawing command, and the pname:viewportCount parameter of fname:vkCmdSetViewportWithCount must: be `1` +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-primitiveFragmentShadingRateWithMultipleViewports-08642]] + If the <> limit is not + supported, and any shader object bound to a graphics stage writes to the + code:PrimitiveShadingRateKHR built-in, then + flink:vkCmdSetViewportWithCount must: have been called in the current + command buffer prior to this drawing command, and the + pname:viewportCount parameter of fname:vkCmdSetViewportWithCount must: + be `1` +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] endif::VK_KHR_fragment_shading_rate[] * [[VUID-{refpage}-blendEnable-04727]] @@ -308,6 +523,18 @@ endif::VK_KHR_fragment_shading_rate[] pname:blendEnable member of the corresponding element of the pname:pAttachments member of pname:pColorBlendState must: be ename:VK_FALSE +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08643]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then for + each color attachment in the render pass, if the corresponding image + view's <> do not + contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the + corresponding member of pname:pColorBlendEnables in the most recent call + to fname:vkCmdSetColorBlendEnableEXT in the current command buffer that + affected that attachment index must: have been ename:VK_FALSE +endif::VK_EXT_shader_object[] ifdef::VK_EXT_multisampled_render_to_single_sampled[] * [[VUID-{refpage}-multisampledRenderToSingleSampled-07284]] If rasterization is not disabled in the bound graphics pipeline, and @@ -318,6 +545,20 @@ ifdef::VK_EXT_multisampled_render_to_single_sampled[] pname:rasterizationSamples for the currently bound graphics pipeline must: be the same as the current subpass color and/or depth/stencil attachments +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08644]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and none of + the `apiext:VK_AMD_mixed_attachment_samples` extension, the + `apiext:VK_NV_framebuffer_mixed_samples` extension, or the + <> feature is enabled, then the + most recent call to flink:vkCmdSetRasterizationSamplesEXT in the current + command buffer must: have set pname:rasterizationSamples to be the same + as the number of samples for the current render pass color and/or + depth/stencil attachments +endif::VK_EXT_shader_object[] endif::VK_EXT_multisampled_render_to_single_sampled[] ifndef::VK_EXT_multisampled_render_to_single_sampled[] * [[VUID-{refpage}-rasterizationSamples-04740]] @@ -327,6 +568,18 @@ ifndef::VK_EXT_multisampled_render_to_single_sampled[] pname:rasterizationSamples for the currently bound graphics pipeline must: be the same as the current subpass color and/or depth/stencil attachments +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08645]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and neither + the `apiext:VK_AMD_mixed_attachment_samples` nor the + `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, then + the most recent call to flink:vkCmdSetRasterizationSamplesEXT in the + current command buffer must: have set pname:rasterizationSamples to be + the same as the number of samples for the current render pass color + and/or depth/stencil attachments +endif::VK_EXT_shader_object[] endif::VK_EXT_multisampled_render_to_single_sampled[] ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] * [[VUID-{refpage}-imageView-06172]] @@ -412,6 +665,15 @@ ifdef::VK_EXT_color_write_enable[] ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT dynamic state enabled then flink:vkCmdSetColorWriteEnableEXT must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08646]] + If the <> feature is + enabled on the device, and a shader object is bound to the fragment + stage, and the most recent call to flink:vkCmdSetRasterizerDiscardEnable + in the current command buffer set pname:rasterizerDiscardEnable to + ename:VK_FALSE, then flink:vkCmdSetColorWriteEnableEXT must: have been + called in the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-attachmentCount-07750]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT dynamic state enabled then @@ -419,6 +681,17 @@ ifdef::VK_EXT_color_write_enable[] must: be greater than or equal to the sname:VkPipelineColorBlendStateCreateInfo::pname:attachmentCount of the currently bound graphics pipeline +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08647]] + If the <> feature is + enabled on the device, and a shader object is bound to the fragment + stage, and the most recent call to flink:vkCmdSetRasterizerDiscardEnable + in the current command buffer set pname:rasterizerDiscardEnable to + ename:VK_FALSE, then the pname:attachmentCount parameter of most recent + call to fname:vkCmdSetColorWriteEnableEXT in the current command buffer + must: be greater than or equal to the number of color attachments in the + current render pass instance +endif::VK_EXT_shader_object[] endif::VK_EXT_color_write_enable[] ifdef::VK_EXT_discard_rectangles[] * [[VUID-{refpage}-None-07751]] @@ -433,11 +706,31 @@ ifdef::VK_EXT_discard_rectangles[] ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT dynamic state enabled then flink:vkCmdSetDiscardRectangleEnableEXT must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08648]] + If the `apiext:VK_EXT_discard_rectangles` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetDiscardRectangleEnableEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07881]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic state enabled then flink:vkCmdSetDiscardRectangleModeEXT must: have been called in the current command buffer prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08649]] + If the `apiext:VK_EXT_discard_rectangles` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, and the most recent + call to flink:vkCmdSetDiscardRectangleEnableEXT in the current command + buffer set pname:discardRectangleEnable to ename:VK_TRUE, then + flink:vkCmdSetDiscardRectangleModeEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_discard_rectangles[] * [[VUID-{refpage}-pDepthAttachment-06181]] If the current render pass instance was begun with @@ -633,95 +926,249 @@ ifdef::VK_EXT_transform_feedback[] sname:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream endif::VK_EXT_transform_feedback[] endif::VK_EXT_primitives_generated_query[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07619]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT dynamic state enabled then flink:vkCmdSetTessellationDomainOriginEXT must: have been called in the current command buffer prior to this drawing command - * [[VUID-{refpage}-None-07620]] - If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT dynamic state enabled then +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08650]] + If the <> feature is enabled, and + a shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, then flink:vkCmdSetDepthClampEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07621]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_POLYGON_MODE_EXT dynamic state enabled then flink:vkCmdSetPolygonModeEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08651]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetPolygonModeEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07622]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT dynamic state enabled then flink:vkCmdSetRasterizationSamplesEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08652]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetRasterizationSamplesEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07623]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT dynamic state enabled then flink:vkCmdSetSampleMaskEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08653]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetSampleMaskEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07624]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic state enabled then flink:vkCmdSetAlphaToCoverageEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08654]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetAlphaToCoverageEnableEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07625]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT dynamic state enabled then flink:vkCmdSetAlphaToOneEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08655]] + If the <> feature is enabled, and + a shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetAlphaToOneEnableEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07626]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT dynamic state enabled then flink:vkCmdSetLogicOpEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08656]] + If the <> feature is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetLogicOpEnableEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07627]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT dynamic state enabled then flink:vkCmdSetColorBlendEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08657]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetColorBlendEnableEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07628]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT dynamic state enabled then flink:vkCmdSetColorBlendEquationEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08658]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and the most + recent call to flink:vkCmdSetColorBlendEnableEXT for any attachment set + that attachment's value in pname:pColorBlendEnables to ename:VK_TRUE, + then flink:vkCmdSetColorBlendEquationEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07629]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT dynamic state enabled then flink:vkCmdSetColorWriteMaskEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08659]] + If a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetColorWriteMaskEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] ifdef::VK_EXT_transform_feedback[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07630]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT dynamic state enabled then flink:vkCmdSetRasterizationStreamEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08660]] + If the <> feature is + enabled, and a shader object is bound to the geometry stage, then + flink:vkCmdSetRasterizationStreamEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_transform_feedback[] ifdef::VK_EXT_conservative_rasterization[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07631]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT dynamic state enabled then flink:vkCmdSetConservativeRasterizationModeEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08661]] + If the `apiext:VK_EXT_conservative_rasterization` extension is enabled, + and a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetConservativeRasterizationModeEXT must: have been called in + the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07632]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT dynamic state enabled then flink:vkCmdSetExtraPrimitiveOverestimationSizeEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08662]] + If the `apiext:VK_EXT_conservative_rasterization` extension is enabled, + and a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetRasterizerDiscardEnable in the current command + buffer set pname:rasterizerDiscardEnable to ename:VK_FALSE, and the most + recent call to flink:vkCmdSetConservativeRasterizationModeEXT in the + current command buffer set pname:conservativeRasterizationMode to + ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT, then + flink:vkCmdSetExtraPrimitiveOverestimationSizeEXT must: have been called + in the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_conservative_rasterization[] ifdef::VK_EXT_depth_clip_enable[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07633]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT dynamic state enabled then flink:vkCmdSetDepthClipEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08663]] + If the <> feature is + enabled, and a shader object is bound to any graphics stage, then + flink:vkCmdSetDepthClipEnableEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_depth_clip_enable[] ifdef::VK_EXT_sample_locations[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07634]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT dynamic state enabled then flink:vkCmdSetSampleLocationsEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08664]] + If the `apiext:VK_EXT_sample_locations` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetRasterizerDiscardEnable in the current command buffer + set pname:rasterizerDiscardEnable to ename:VK_FALSE, then + flink:vkCmdSetSampleLocationsEnableEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_sample_locations[] ifdef::VK_EXT_blend_operation_advanced[] * [[VUID-{refpage}-None-07635]] @@ -731,100 +1178,272 @@ ifdef::VK_EXT_blend_operation_advanced[] current command buffer prior to this drawing command endif::VK_EXT_blend_operation_advanced[] ifdef::VK_EXT_provoking_vertex[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07636]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT dynamic state enabled then flink:vkCmdSetProvokingVertexModeEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08665]] + If the `apiext:VK_EXT_provoking_vertex` extension is enabled, and a + shader object is bound to the vertex stage, then + flink:vkCmdSetProvokingVertexModeEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_provoking_vertex[] ifdef::VK_EXT_line_rasterization[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07637]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT dynamic state enabled then flink:vkCmdSetLineRasterizationModeEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08666]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetPolygonModeEXT in the current command buffer set + pname:polygonMode to ename:VK_POLYGON_MODE_LINE, then + flink:vkCmdSetLineRasterizationModeEXT must: have been called in the + current command buffer prior to this drawing command + * [[VUID-{refpage}-None-08667]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object is bound to the vertex stage, and the most recent call to + flink:vkCmdSetPrimitiveTopology in the current command buffer set + pname:primitiveTopology to any line topology, then + flink:vkCmdSetLineRasterizationModeEXT must: have been called in the + current command buffer prior to this drawing command + * [[VUID-{refpage}-None-08668]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object that outputs line primitives is bound to the tessellation + evaluation or geometry stage, then + flink:vkCmdSetLineRasterizationModeEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07638]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT dynamic state enabled then flink:vkCmdSetLineStippleEnableEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08669]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetPolygonModeEXT in the current command buffer set + pname:polygonMode to ename:VK_POLYGON_MODE_LINE, then + flink:vkCmdSetLineStippleEnableEXT must: have been called in the current + command buffer prior to this drawing command + * [[VUID-{refpage}-None-08670]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object is bound to the vertex stage, and the most recent call to + flink:vkCmdSetPrimitiveTopology in the current command buffer set + pname:primitiveTopology to any line topology, then + flink:vkCmdSetLineStippleEnableEXT must: have been called in the current + command buffer prior to this drawing command + * [[VUID-{refpage}-None-08671]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object that outputs line primitives is bound to the tessellation + evaluation or geometry stage, then flink:vkCmdSetLineStippleEnableEXT + must: have been called in the current command buffer prior to this + drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07849]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT dynamic state enabled then flink:vkCmdSetLineStippleEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08672]] + If the `apiext:VK_EXT_line_rasterization` extension is enabled, and a + shader object is bound to any graphics stage, and the most recent call + to flink:vkCmdSetLineStippleEnableEXT in the current command buffer set + pname:stippledLineEnable to ename:VK_TRUE, then + flink:vkCmdSetLineStippleEXT must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_line_rasterization[] ifdef::VK_EXT_depth_clip_control[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07639]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT dynamic state enabled then flink:vkCmdSetDepthClipNegativeOneToOneEXT must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08673]] + If the <> feature is + enabled, and a shader object is bound to any graphics stage, then + flink:vkCmdSetDepthClipNegativeOneToOneEXT must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_EXT_depth_clip_control[] ifdef::VK_NV_clip_space_w_scaling[] +ifdef::VK_EXT_extended_dynamic_state3 * [[VUID-{refpage}-None-07640]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_ENABLE_NV dynamic state enabled then flink:vkCmdSetViewportWScalingEnableNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3 +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08674]] + If the `apiext:VK_NV_clip_space_w_scaling` extension is enabled, and a + shader object is bound to any graphics stage, then + flink:vkCmdSetViewportWScalingEnableNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_clip_space_w_scaling[] ifdef::VK_NV_viewport_swizzle[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07641]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV dynamic state enabled then flink:vkCmdSetViewportSwizzleNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08675]] + If the `apiext:VK_NV_viewport_swizzle` extension is enabled, and a + shader object is bound to any graphics stage, then + flink:vkCmdSetViewportSwizzleNV must: have been called in the current + command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_viewport_swizzle[] ifdef::VK_NV_fragment_coverage_to_color[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07642]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV dynamic state enabled then flink:vkCmdSetCoverageToColorEnableNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08676]] + If the `apiext:VK_NV_fragment_coverage_to_color` extension is enabled, + and a shader object is bound to any graphics stage, then + flink:vkCmdSetCoverageToColorEnableNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07643]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV dynamic state enabled then flink:vkCmdSetCoverageToColorLocationNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08677]] + If the `apiext:VK_NV_fragment_coverage_to_color` extension is enabled, + and a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetCoverageToColorEnableNV in the current command + buffer set pname:coverageToColorEnable to ename:VK_TRUE, then + flink:vkCmdSetCoverageToColorLocationNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_fragment_coverage_to_color[] ifdef::VK_NV_framebuffer_mixed_samples[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07644]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV dynamic state enabled then flink:vkCmdSetCoverageModulationModeNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08678]] + If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, + and a shader object is bound to any graphics stage, then + flink:vkCmdSetCoverageModulationModeNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07645]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV dynamic state enabled then flink:vkCmdSetCoverageModulationTableEnableNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08679]] + If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, + and a shader object is bound to any graphics stage, then + flink:vkCmdSetCoverageModulationTableEnableNV must: have been called in + the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07646]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV dynamic state enabled then flink:vkCmdSetCoverageModulationTableNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08680]] + If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, + and a shader object is bound to any graphics stage, and the most recent + call to flink:vkCmdSetCoverageModulationTableEnableNV in the current + command buffer set pname:coverageModulationTableEnable to ename:VK_TRUE, + then flink:vkCmdSetCoverageModulationTableNV must: have been called in + the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_framebuffer_mixed_samples[] ifdef::VK_NV_shading_rate_image[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07647]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV dynamic state enabled then flink:vkCmdSetShadingRateImageEnableNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08681]] + If the <> feature is + enabled, and a shader object is bound to any graphics stage, then + flink:vkCmdSetShadingRateImageEnableNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_shading_rate_image[] ifdef::VK_NV_representative_fragment_test[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07648]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV dynamic state enabled then flink:vkCmdSetRepresentativeFragmentTestEnableNV must have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08682]] + If the <> feature is enabled, and a shader + object is bound to any graphics stage, then + flink:vkCmdSetRepresentativeFragmentTestEnableNV must: have been called + in the current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_representative_fragment_test[] ifdef::VK_NV_coverage_reduction_mode[] +ifdef::VK_EXT_extended_dynamic_state3[] * [[VUID-{refpage}-None-07649]] If the bound graphics pipeline state was created with the ename:VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV dynamic state enabled then flink:vkCmdSetCoverageReductionModeNV must: have been called in the current command buffer prior to this drawing command +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08683]] + If the <> + feature is enabled, and a shader object is bound to any graphics stage, + then flink:vkCmdSetCoverageReductionModeNV must: have been called in the + current command buffer prior to this drawing command +endif::VK_EXT_shader_object[] endif::VK_NV_coverage_reduction_mode[] * [[VUID-{refpage}-pColorBlendEnables-07470]] If the bound graphics pipeline state was created with the @@ -1147,7 +1766,7 @@ ifdef::VK_EXT_conservative_rasterization[] set by the last call to flink:vkCmdSetConservativeRasterizationModeEXT must: be ename:VK_CONSERVATIVE_RASTERIZATION_MODE_DISABLED_EXT endif::VK_EXT_conservative_rasterization[] -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] ifdef::VK_EXT_mesh_shader[] * [[VUID-{refpage}-stage-07073]] If the currently bound pipeline was created with the @@ -1165,4 +1784,122 @@ ifdef::VK_NV_inherited_viewport_scissor[] slink:VkCommandBufferInheritanceViewportScissorInfoNV, it must: be set in the current command buffer prior to this drawing command endif::VK_NV_inherited_viewport_scissor[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08684]] + If there is no bound graphics pipeline, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_VERTEX_BIT + * [[VUID-{refpage}-None-08685]] + If there is no bound graphics pipeline, and the + <> feature is + enabled, fname:vkCmdBindShadersEXT must: have been called on the current + command buffer with pname:pStages with an element of + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT + * [[VUID-{refpage}-None-08686]] + If there is no bound graphics pipeline, and the + <> feature is + enabled, fname:vkCmdBindShadersEXT must: have been called on the current + command buffer with pname:pStages with an element of + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT + * [[VUID-{refpage}-None-08687]] + If there is no bound graphics pipeline, and the + <> feature is enabled, + fname:vkCmdBindShadersEXT must: have been called on the current command + buffer with pname:pStages with an element of + ename:VK_SHADER_STAGE_GEOMETRY_BIT + * [[VUID-{refpage}-None-08688]] + If there is no bound graphics pipeline, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_FRAGMENT_BIT +ifdef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-None-08689]] + If there is no bound graphics pipeline, and the <> feature is enabled, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_TASK_BIT_EXT + * [[VUID-{refpage}-None-08690]] + If there is no bound graphics pipeline, and the <> feature is enabled, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-{refpage}-None-08691]] + If there is no bound graphics pipeline, and the <> feature is enabled, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_TASK_BIT_NV + * [[VUID-{refpage}-None-08692]] + If there is no bound graphics pipeline, and the <> feature is enabled, fname:vkCmdBindShadersEXT must: + have been called on the current command buffer with pname:pStages with + an element of ename:VK_SHADER_STAGE_MESH_BIT_NV +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-None-08693]] + If there is no bound graphics pipeline, and at least one of the + <> and <> features is enabled, one of the + ename:VK_SHADER_STAGE_VERTEX_BIT or ename:VK_SHADER_STAGE_MESH_BIT_EXT + stages must have a valid sname:VkShaderEXT bound, and the other must + have no sname:VkShaderEXT bound + * [[VUID-{refpage}-None-08694]] + If there is no bound graphics pipeline, and both the + <> and <> features are enabled, and a valid sname:VkShaderEXT + is bound the to the ename:VK_SHADER_STAGE_MESH_BIT_EXT stage, and that + sname:VkShaderEXT was created without the + ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT flag, a valid + sname:VkShaderEXT must: be bound to the + ename:VK_SHADER_STAGE_TASK_BIT_EXT stage + * [[VUID-{refpage}-None-08695]] + If there is no bound graphics pipeline, and both the + <> and <> features are enabled, and a valid sname:VkShaderEXT + is bound the to the ename:VK_SHADER_STAGE_MESH_BIT_EXT stage, and that + sname:VkShaderEXT was created with the + ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT flag, there must: be no + sname:VkShaderEXT bound to the ename:VK_SHADER_STAGE_TASK_BIT_EXT stage + * [[VUID-{refpage}-None-08696]] + If there is no bound graphics pipeline, and a valid sname:VkShaderEXT is + bound to the ename:VK_SHADER_STAGE_VERTEX_BIT stage, there must: be no + sname:VkShaderEXT bound to either the ename:VK_SHADER_STAGE_TASK_BIT_EXT + stage or the ename:VK_SHADER_STAGE_MESH_BIT_EXT stage +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-None-08697]] + If there is no bound graphics pipeline, a sname:VkShaderEXT must: be + bound to the ename:VK_SHADER_STAGE_VERTEX_BIT stage +endif::VK_EXT_mesh_shader[] + * [[VUID-{refpage}-None-08698]] + If any graphics shader is bound which was created with the + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT flag, then all shaders created + with the ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT flag in the same + flink:vkCreateShadersEXT call must: also be bound + * [[VUID-{refpage}-None-08699]] + If any graphics shader is bound which was created with the + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT flag, any stages in between + stages whose shaders which did not create a shader with the + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT flag as part of the same + flink:vkCreateShadersEXT call must: not have any sname:VkShaderEXT bound +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_tile_image[] + * [[VUID-{refpage}-pDynamicStates-08715]] + If the bound graphics pipeline state includes a fragment shader stage, + was created with ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in + slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and the + fragment shader declares the code:EarlyFragmentTests execution mode and + uses code:OpDepthAttachmentReadEXT, the pname:depthWriteEnable parameter + in the last call to flink:vkCmdSetDepthWriteEnable must: be + ename:VK_FALSE + * [[VUID-{refpage}-pDynamicStates-08716]] + If the bound graphics pipeline state includes a fragment shader stage, + was created with ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in + slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and the + fragment shader declares the code:EarlyFragmentTests execution mode and + uses code:OpStencilAttachmentReadEXT, the pname:writeMask parameter in + the last call to flink:vkCmdSetStencilWriteMask must: be `0` +endif::VK_EXT_shader_tile_image[] // Common Valid Usage diff --git a/chapters/commonvalidity/draw_dispatch_common.adoc b/chapters/commonvalidity/draw_dispatch_common.adoc index 7c7059c177..01cd8ce726 100644 --- a/chapters/commonvalidity/draw_dispatch_common.adoc +++ b/chapters/commonvalidity/draw_dispatch_common.adoc @@ -103,6 +103,7 @@ ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] view's <> must: contain ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-None-02697]] For each set _n_ that is statically used by the slink:VkPipeline bound to the pipeline bind point used by this command, a descriptor set must: @@ -110,7 +111,6 @@ endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] slink:VkPipelineLayout that is compatible for set _n_, with the slink:VkPipelineLayout used to create the current slink:VkPipeline, as described in <> -ifndef::VK_VERSION_1_3,VK_KHR_maintenance4[] * [[VUID-{refpage}-None-02698]] For each push constant that is statically used by the slink:VkPipeline bound to the pipeline bind point used by this command, a push constant @@ -118,8 +118,33 @@ ifndef::VK_VERSION_1_3,VK_KHR_maintenance4[] slink:VkPipelineLayout that is compatible for push constants, with the slink:VkPipelineLayout used to create the current slink:VkPipeline, as described in <> +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08600]] + For each set _n_ that is statically used by the slink:VkPipeline bound + to the pipeline bind point used by this command, or by any of the + slink:VkShaderEXT objects bound to stages corresponding to the pipeline + bind point used by this command, a descriptor set must: have been bound + to _n_ at the same pipeline bind point, with a slink:VkPipelineLayout + that is compatible for set _n_, with the slink:VkPipelineLayout or + slink:VkDescriptorSetLayout array that was used to create the current + slink:VkPipeline or slink:VkShaderEXT, as described in + <> + * [[VUID-{refpage}-None-08601]] + For each push constant that is statically used by the slink:VkPipeline + bound to the pipeline bind point used by this command, or by any of the + slink:VkShaderEXT objects bound to stages corresponding to the pipeline + bind point used by this command, a push constant value must: have been + set for the same pipeline bind point, with a slink:VkPipelineLayout that + is compatible for push constants, with the slink:VkPipelineLayout or + slink:VkDescriptorSetLayout and slink:VkPushConstantRange arrays used to + create the current slink:VkPipeline or slink:VkShaderEXT, as described + in <> +endif::VK_EXT_shader_object[] +ifndef::VK_VERSION_1_3,VK_KHR_maintenance4[] endif::VK_VERSION_1_3,VK_KHR_maintenance4[] ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-maintenance4-06425]] If the <> feature is not enabled, then for each push constant that is statically used by the @@ -128,14 +153,40 @@ ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] point, with a slink:VkPipelineLayout that is compatible for push constants, with the slink:VkPipelineLayout used to create the current slink:VkPipeline, as described in <> +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-maintenance4-08602]] + If the <> feature is not + enabled, then for each push constant that is statically used by the + slink:VkPipeline bound to the pipeline bind point used by this command, + or by any of the slink:VkShaderEXT objects bound to stages corresponding + to the pipeline bind point used by this command, a push constant value + must: have been set for the same pipeline bind point, with a + slink:VkPipelineLayout that is compatible for push constants, with the + slink:VkPipelineLayout or slink:VkDescriptorSetLayout and + slink:VkPushConstantRange arrays used to create the current + slink:VkPipeline or slink:VkShaderEXT, as described in + <> +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_3,VK_KHR_maintenance4[] ifndef::VK_EXT_descriptor_buffer[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-None-02699]] Descriptors in each bound descriptor set, specified via flink:vkCmdBindDescriptorSets, must: be valid as described by <> if they are statically used by the slink:VkPipeline bound to the pipeline bind point used by this command +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08603]] + Descriptors in each bound descriptor set, specified via + flink:vkCmdBindDescriptorSets, must: be valid as described by + <> if they are statically used + by the slink:VkPipeline bound to the pipeline bind point used by this + command, or by any of the slink:VkShaderEXT objects bound to stages + corresponding to the pipeline bind point used by this command +endif::VK_EXT_shader_object[] endif::VK_EXT_descriptor_buffer[] ifdef::VK_EXT_descriptor_buffer[] * [[VUID-{refpage}-None-08114]] @@ -155,6 +206,13 @@ ifdef::VK_EXT_descriptor_buffer[] dynamically used by the slink:VkPipeline bound to the pipeline bind point used by this command and the bound slink:VkPipeline was created with ename:VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08604]] + Descriptors in bound descriptor buffers, specified via + flink:vkCmdSetDescriptorBufferOffsetsEXT, must: be valid if they are + dynamically used by any slink:VkShaderEXT bound to a stage corresponding + to the pipeline bind point used by this command +endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-08117]] If the descriptors used by the slink:VkPipeline bound to the pipeline bind point were specified via flink:vkCmdSetDescriptorBufferOffsetsEXT, @@ -164,7 +222,15 @@ ifdef::VK_EXT_descriptor_buffer[] If a descriptor is dynamically used with a slink:VkPipeline created with ename:VK_PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the descriptor memory must: be resident +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08605]] + If a descriptor is dynamically used with a slink:VkShaderEXT created + with a sname:VkDescriptorSetLayout that was created with + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, the + descriptor memory must: be resident +endif::VK_EXT_shader_object[] endif::VK_EXT_descriptor_buffer[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-None-02700]] A valid pipeline must: be bound to the pipeline bind point used by this command @@ -194,6 +260,50 @@ endif::VK_EXT_descriptor_buffer[] coordinates, that sampler must: not be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a LOD bias or any offset values, in any shader stage +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08606]] + If the <> feature is not + enabled, a valid pipeline must: be bound to the pipeline bind point used + by this command + * [[VUID-{refpage}-None-08607]] + If the <> is enabled, either + a valid pipeline must: be bound to the pipeline bind point used by this + command, or a valid combination of valid and dlink:VK_NULL_HANDLE shader + objects must: be bound to every supported shader stage corresponding to + the pipeline bind point used by this command + * [[VUID-{refpage}-None-08608]] + If a pipeline is bound to the pipeline bind point used by this command, + there must: not have been any calls to dynamic state setting commands + for any state not specified as dynamic in the slink:VkPipeline object + bound to the pipeline bind point used by this command, since that + pipeline was bound + * [[VUID-{refpage}-None-08609]] + If the slink:VkPipeline object bound to the pipeline bind point used by + this command or any slink:VkShaderEXT bound to a stage corresponding to + the pipeline bind point used by this command accesses a slink:VkSampler + object that uses unnormalized coordinates, that sampler must: not be + used to sample from any slink:VkImage with a slink:VkImageView of the + type ename:VK_IMAGE_VIEW_TYPE_3D, ename:VK_IMAGE_VIEW_TYPE_CUBE, + ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY or + ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage + * [[VUID-{refpage}-None-08610]] + If the slink:VkPipeline object bound to the pipeline bind point used by + this command or any slink:VkShaderEXT bound to a stage corresponding to + the pipeline bind point used by this command accesses a slink:VkSampler + object that uses unnormalized coordinates, that sampler must: not be + used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` + instructions with code:ImplicitLod, code:Dref or code:Proj in their + name, in any shader stage + * [[VUID-{refpage}-None-08611]] + If the slink:VkPipeline object bound to the pipeline bind point used by + this command or any slink:VkShaderEXT bound to a stage corresponding to + the pipeline bind point used by this command accesses a slink:VkSampler + object that uses unnormalized coordinates, that sampler must: not be + used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` + instructions that includes a LOD bias or any offset values, in any + shader stage +endif::VK_EXT_shader_object[] ifndef::VK_EXT_pipeline_robustness[] * [[VUID-{refpage}-None-02705]] If the <> feature @@ -214,6 +324,14 @@ ifdef::VK_EXT_pipeline_robustness[] access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point endif::VK_EXT_pipeline_robustness[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08612]] + If the <> feature + is not enabled, and any slink:VkShaderEXT bound to a stage corresponding + to the pipeline bind point used by this command accesses a uniform + buffer, it must: not access values outside of the range of the buffer as + specified in the descriptor set bound to the same pipeline bind point +endif::VK_EXT_shader_object[] ifndef::VK_EXT_pipeline_robustness[] * [[VUID-{refpage}-None-02706]] If the <> feature @@ -234,15 +352,35 @@ ifdef::VK_EXT_pipeline_robustness[] access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point endif::VK_EXT_pipeline_robustness[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08613]] + If the <> feature + is not enabled, and any slink:VkShaderEXT bound to a stage corresponding + to the pipeline bind point used by this command accesses a storage + buffer, it must: not access values outside of the range of the buffer as + specified in the descriptor set bound to the same pipeline bind point +endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_1[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-commandBuffer-02707]] If pname:commandBuffer is an unprotected command buffer and <> is not supported, any resource accessed by the slink:VkPipeline object bound to the pipeline bind point used by this command must: not be a protected resource +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-commandBuffer-08614]] + If pname:commandBuffer is an unprotected command buffer and + <> is not supported, + any resource accessed by the slink:VkPipeline object bound to the + pipeline bind point used by this command or any slink:VkShaderEXT object + bound to a stage corresponding to the pipeline bind point used by this + command must: not be a protected resource +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +ifndef::VK_EXT_shader_object[] * [[VUID-{refpage}-None-06550]] If the slink:VkPipeline object bound to the pipeline bind point used by this command accesses a slink:VkSampler or slink:VkImageView object that @@ -254,6 +392,24 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] this command accesses a slink:VkSampler or slink:VkImageView object that enables <>, that object must: not use the code:ConstOffset and code:Offset operands +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-08615]] + If the slink:VkPipeline object bound to the pipeline bind point used by + this command or any slink:VkShaderEXT bound to a stage corresponding to + the pipeline bind point used by this command accesses a slink:VkSampler + or slink:VkImageView object that enables + <>, that object + must: only be used with `OpImageSample*` or `OpImageSparseSample*` + instructions + * [[VUID-{refpage}-ConstOffset-08616]] + If the slink:VkPipeline object bound to the pipeline bind point used by + this command or any slink:VkShaderEXT bound to a stage corresponding to + the pipeline bind point used by this command accesses a slink:VkSampler + or slink:VkImageView object that enables + <>, that object + must: not use the code:ConstOffset and code:Offset operands +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-{refpage}-viewType-07752]] If a slink:VkImageView is accessed as a result of this command, then the diff --git a/chapters/commonvalidity/get_image_subresource_layout_common.adoc b/chapters/commonvalidity/get_image_subresource_layout_common.adoc index bb646f5a01..617d0822b9 100644 --- a/chapters/commonvalidity/get_image_subresource_layout_common.adoc +++ b/chapters/commonvalidity/get_image_subresource_layout_common.adoc @@ -29,19 +29,12 @@ pname:aspectMask member of pname:pSubresource must: not contain ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] - * [[VUID-{refpage}-format-01581]] + * [[VUID-{refpage}-tiling-08717]] If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR - and its pname:format is a - <> with - two planes, the pname:aspectMask member of pname:pSubresource must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT - * [[VUID-{refpage}-format-01582]] - If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR - and its pname:format is a - <> with - three planes, the pname:aspectMask member of pname:pSubresource must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT + and has a <>, then the pname:aspectMask member of pname:pSubresource + must: be a single valid <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-{refpage}-image-01895]] diff --git a/chapters/commonvalidity/image_layout_transition_common.adoc b/chapters/commonvalidity/image_layout_transition_common.adoc index 16cca0a1e7..e463759194 100644 --- a/chapters/commonvalidity/image_layout_transition_common.adoc +++ b/chapters/commonvalidity/image_layout_transition_common.adoc @@ -42,14 +42,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-{refpage}-image-01672]] If pname:image has a multi-planar format and the image is _disjoint_, then the pname:aspectMask member of pname:subresourceRange must: include - either at least one of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, - ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and - ename:VK_IMAGE_ASPECT_PLANE_2_BIT; or must: include + at least one <> or ename:VK_IMAGE_ASPECT_COLOR_BIT - * [[VUID-{refpage}-image-01673]] - If pname:image has a multi-planar format with only two planes, then the - pname:aspectMask member of pname:subresourceRange must: not include - ename:VK_IMAGE_ASPECT_PLANE_2_BIT endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifndef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] * [[VUID-{refpage}-image-01207]] @@ -72,11 +66,13 @@ ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] pname:separateDepthStencilLayouts>> feature is not enabled, then the pname:aspectMask member of pname:subresourceRange must: include both ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT - * [[VUID-{refpage}-aspectMask-08702]] If the pname:aspectMask member of pname:subresourceRange includes + * [[VUID-{refpage}-aspectMask-08702]] + If the pname:aspectMask member of pname:subresourceRange includes ename:VK_IMAGE_ASPECT_DEPTH_BIT, pname:oldLayout and pname:newLayout must: not be one of ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL - * [[VUID-{refpage}-aspectMask-08703]] If the pname:aspectMask member of pname:subresourceRange includes + * [[VUID-{refpage}-aspectMask-08703]] + If the pname:aspectMask member of pname:subresourceRange includes ename:VK_IMAGE_ASPECT_STENCIL_BIT, pname:oldLayout and pname:newLayout must: not be one of ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL diff --git a/chapters/commonvalidity/pipeline_barrier_common.adoc b/chapters/commonvalidity/pipeline_barrier_common.adoc index 6da7c9cac2..ff7f0dbab6 100644 --- a/chapters/commonvalidity/pipeline_barrier_common.adoc +++ b/chapters/commonvalidity/pipeline_barrier_common.adoc @@ -70,8 +70,26 @@ ifdef::VK_VERSION_1_1,VK_KHR_multiview[] include ename:VK_DEPENDENCY_VIEW_LOCAL_BIT endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] +ifdef::VK_EXT_shader_tile_image[] + * [[VUID-{refpage}-shaderTileImageColorReadAccess-08718]] + If fname:{refpage} is called within a render pass instance and none of + the <>, + <>, + <> features are enabled, the + render pass must: not have been started with flink:vkCmdBeginRendering + * [[VUID-{refpage}-None-08719]] + If fname:{refpage} is called within a render pass instance started with + flink:vkCmdBeginRendering, it must: adhere to the restrictions in + <> +endif::VK_EXT_shader_tile_image[] +ifndef::VK_EXT_shader_tile_image[] * [[VUID-{refpage}-None-06191]] If fname:{refpage} is called within a render pass instance, the render pass must: not have been started with flink:vkCmdBeginRendering +endif::VK_EXT_shader_tile_image[] endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] // Common Valid Usage diff --git a/chapters/descriptorsets.adoc b/chapters/descriptorsets.adoc index 3370a85f7d..bd19ce2eda 100644 --- a/chapters/descriptorsets.adoc +++ b/chapters/descriptorsets.adoc @@ -2199,7 +2199,7 @@ exists in the corresponding descriptor set layout and is of an appropriate descriptor type and includes the set of shader stages it is used by in pname:stageFlags. The pipeline layout can: include entries that are not used by a particular -pipeline, or that are dead-code eliminated from any of the shaders. +pipeline. The pipeline layout allows the application to provide a consistent set of bindings across multiple pipeline compiles, which enables those pipelines to be compiled in a way that the implementation may: cheaply switch pipelines @@ -2210,8 +2210,7 @@ must: only place variables at offsets that are each included in a push constant range with pname:stageFlags including the bit corresponding to the shader stage that uses it. The pipeline layout can: include ranges or portions of ranges that are not -used by a particular pipeline, or for which the variables have been -dead-code eliminated from any of the shaders. +used by a particular pipeline. There is a limit on the total number of resources of each type that can: be included in bindings in all descriptor set layouts in a pipeline layout as @@ -3572,10 +3571,6 @@ endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of each element of pname:pImageInfo must: have been created with the identity swizzle - * [[VUID-VkWriteDescriptorSet-descriptorType-07729]] - If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, - the pname:imageView member of each element of pname:pImageInfo must: - have been created with exactly one aspect * [[VUID-VkWriteDescriptorSet-descriptorType-00337]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageView @@ -3891,9 +3886,8 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] <>, the image must: have been created with ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the pname:aspectMask of - the pname:imageView must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, - ename:VK_IMAGE_ASPECT_PLANE_1_BIT or (for three-plane formats only) - ename:VK_IMAGE_ASPECT_PLANE_2_BIT + the pname:imageView must: be a valid + <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_KHR_portability_subset[] * [[VUID-VkDescriptorImageInfo-mutableComparisonSamplers-04450]] diff --git a/chapters/devsandqueues.adoc b/chapters/devsandqueues.adoc index d137e7adb9..59746e7a04 100644 --- a/chapters/devsandqueues.adoc +++ b/chapters/devsandqueues.adoc @@ -1000,6 +1000,36 @@ include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingPropertiesQ -- endif::VK_QCOM_image_processing[] +ifdef::VK_EXT_shader_tile_image[] +[open,refpage='VkPhysicalDeviceShaderTileImagePropertiesEXT',desc='Structure containing information about tile image support for a physical device',type='structs'] +-- +The sname:VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined +as: + +include::{generated}/api/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:shaderTileImageCoherentReadAccelerated is a boolean that will be + ename:VK_TRUE if coherent reads of tile image data is accelerated. + * pname:shaderTileImageReadSampleFromPixelRateInvocation is a boolean that + will be ename:VK_TRUE if reading from samples from a pixel rate fragment + invocation is supported when + slink:VkPipelineMultisampleStateCreateInfo::rasterizationSamples > 1. + * pname:shaderTileImageReadFromHelperInvocation is a boolean that will be + ename:VK_TRUE if reads of tile image data from helper fragment + invocations result in valid values. + +:refpage: VkPhysicalDeviceShaderTileImagePropertiesEXT +include::{chapters}/limits.adoc[tag=limits_desc] + +These are properties of the tile image information of a physical device. + +include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] +-- +endif::VK_EXT_shader_tile_image[] + [open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] -- To query properties of queues available on a physical device, call: diff --git a/chapters/drawing.adoc b/chapters/drawing.adoc index 9615591f2e..16c018f040 100644 --- a/chapters/drawing.adoc +++ b/chapters/drawing.adoc @@ -9,9 +9,17 @@ _Drawing commands_ (commands with ftext:Draw in the name) provoke work in a graphics pipeline. Drawing commands are recorded into a command buffer and when executed by a queue, will produce work which executes according to the bound graphics -pipeline. -A graphics pipeline must: be bound to a command buffer before any drawing -commands are recorded in that command buffer. +ifndef::VK_EXT_shader_object[pipeline.] +ifdef::VK_EXT_shader_object[] +pipeline, or if the <> feature is +enabled, any <> bound to graphics stages. +endif::VK_EXT_shader_object[] +A graphics pipeline +ifdef::VK_EXT_shader_object[] +or a combination of one or more graphics shader objects +endif::VK_EXT_shader_object[] +must: be bound to a command buffer before any drawing commands are recorded +in that command buffer. [open,refpage='VkPipelineInputAssemblyStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline input assembly state',type='structs'] -- @@ -131,7 +139,7 @@ tname:VkPipelineInputAssemblyStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use. -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [open,refpage='vkCmdSetPrimitiveRestartEnable',desc='Set primitive assembly restart state dynamically for a command buffer',type='protos',alias='vkCmdSetPrimitiveRestartEnableEXT'] -- To <> whether a special vertex @@ -139,13 +147,13 @@ index value is treated as restarting the assembly of primitives, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetPrimitiveRestartEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state2[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state2[] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetPrimitiveRestartEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -155,9 +163,16 @@ endif::VK_EXT_extended_dynamic_state2[] sname:VkPipelineInputAssemblyStateCreateInfo::pname:primitiveRestartEnable This command sets the primitive restart enable for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] Otherwise, this state is specified by the slink:VkPipelineInputAssemblyStateCreateInfo::pname:primitiveRestartEnable value used to create the currently active pipeline. @@ -165,15 +180,30 @@ value used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetPrimitiveRestartEnable-None-08500]] + Either the <> feature or the <> feature or both must: be enabled +endif::VK_EXT_extended_dynamic_state2[] +ifndef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetPrimitiveRestartEnable-None-08501]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetPrimitiveRestartEnable-None-04866]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetPrimitiveRestartEnable.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [[drawing-primitive-topologies]] @@ -278,20 +308,20 @@ first primitive in the set of primitives defined by the vertices and topology. -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetPrimitiveTopology',desc='Set primitive topology state dynamically for a command buffer',type='protos',alias='vkCmdSetPrimitiveTopologyEXT'] -- To <> primitive topology, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetPrimitiveTopology.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetPrimitiveTopologyEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -299,9 +329,15 @@ endif::VK_EXT_extended_dynamic_state[] drawing. This command sets the primitive topology for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineInputAssemblyStateCreateInfo::pname:topology value used to create the currently active pipeline. @@ -309,9 +345,24 @@ create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetPrimitiveTopology-None-08502]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetPrimitiveTopology-None-08503]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetPrimitiveTopology-None-03347]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] @@ -341,7 +392,7 @@ The primitive topologies are grouped into the following topology classes: ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_WITH_ADJACENCY | Patch | ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST |=== -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [[drawing-point-lists]] diff --git a/chapters/features.adoc b/chapters/features.adoc index 00fe47b38e..29ca4a690d 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -6003,6 +6003,37 @@ include::{chapters}/features.adoc[tag=features] include::{generated}/validity/structs/VkPhysicalDeviceDepthClampZeroOneFeaturesEXT.adoc[] -- endif::VK_EXT_depth_clamp_zero_one[] +ifdef::VK_EXT_shader_tile_image[] +[open,refpage='VkPhysicalDeviceShaderTileImageFeaturesEXT',desc='Structure describing tile image features supported by the implementation',type='structs'] +-- +The sname:VkPhysicalDeviceShaderTileImageFeaturesEXT structure is defined +as: + +include::{generated}/api/structs/VkPhysicalDeviceShaderTileImageFeaturesEXT.adoc[] + +The members of the sname:VkPhysicalDeviceShaderTileImageFeaturesEXT +structure describe the following features: + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-shaderTileImageColorReadAccess]] + pname:shaderTileImageColorReadAccess indicates that the implementation + supports the code:TileImageColorReadAccessEXT SPIR-V capability. + * [[features-shaderTileImageDepthReadAccess]] + pname:shaderTileImageDepthReadAccess indicates that the implementation + supports the code:TileImageDepthReadAccessEXT SPIR-V capability. + * [[features-shaderTileImageStencilReadAccess]] + pname:shaderTileImageStencilReadAccess indicates that the implementation + supports the code:TileImageStencilReadAccessEXT SPIR-V capability. + +:refpage: VkPhysicalDeviceShaderTileImageFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImageFeaturesEXT.adoc[] +-- +endif::VK_EXT_shader_tile_image[] + ifdef::VK_EXT_device_address_binding_report[] [open,refpage='VkPhysicalDeviceAddressBindingReportFeaturesEXT',desc='Structure describing the virtual allocation reporting feature supported by an implementation',type='structs'] @@ -6098,6 +6129,25 @@ include::{generated}/validity/structs/VkPhysicalDevicePipelineLibraryGroupHandle -- endif::VK_EXT_pipeline_library_group_handles[] +ifdef::VK_EXT_shader_object[] +[open,refpage='VkPhysicalDeviceShaderObjectFeaturesEXT',desc='Structure describing whether shader objects can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceShaderObjectFeaturesEXT structure is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceShaderObjectFeaturesEXT.adoc[] + +This structure describes the following feature: + + * [[features-shaderObject]] pname:shaderObject indicates whether the + implementation supports <>. + +:refpage: VkPhysicalDeviceShaderObjectFeaturesEXT +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceShaderObjectFeaturesEXT.adoc[] +-- +endif::VK_EXT_shader_object[] + ifdef::VK_ARM_shader_core_builtins[] [open,refpage='VkPhysicalDeviceShaderCoreBuiltinsFeaturesARM',desc='Structure describing the shader core builtins features that can be supported by an implementation',type='structs'] -- @@ -6948,6 +6998,15 @@ ifdef::VK_QCOM_multiview_per_view_viewports[] pname:multiviewPerViewViewports>>, if the `apiext:VK_QCOM_multiview_per_view_viewports` extension is supported. endif::VK_QCOM_multiview_per_view_viewports[] +ifdef::VK_EXT_shader_object[] + * <>, if the + `apiext:VK_EXT_shader_object` extension is supported. +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_shader_tile_image[] + * <shaderTileImageColorReadAccess>, if + the `apiext:VK_EXT_shader_tile_image` extension is supported. +endif::VK_EXT_shader_tile_image[] All other features defined in the Specification are optional:. diff --git a/chapters/formats.adoc b/chapters/formats.adoc index ce4cec49a6..0ef1f73f5d 100644 --- a/chapters/formats.adoc +++ b/chapters/formats.adoc @@ -1315,6 +1315,19 @@ include::{generated}/formats/planeformat.adoc[] |==== endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +[[formats-planes-image-aspect]] +=== Multi-planar format image aspect + +When using elink:VkImageAspectFlagBits to select a plane of a multi-planar +format, the following are the valid options: + +* Two planes +** ename:VK_IMAGE_ASPECT_PLANE_0_BIT +** ename:VK_IMAGE_ASPECT_PLANE_1_BIT +* Three planes +** ename:VK_IMAGE_ASPECT_PLANE_0_BIT +** ename:VK_IMAGE_ASPECT_PLANE_1_BIT +** ename:VK_IMAGE_ASPECT_PLANE_2_BIT [[formats-packed]] === Packed Formats @@ -1808,7 +1821,7 @@ flink:vkGetPhysicalDeviceFormatProperties::pname:format: attachment. * ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT specifies that an image view can: be used as a framebuffer color attachment that supports - blending and as an input attachment. + blending. * ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that an image view can: be used as a framebuffer depth/stencil attachment and as an input attachment. @@ -2347,7 +2360,7 @@ flink:vkGetPhysicalDeviceFormatProperties2::pname:format: attachment. * ename:VK_FORMAT_FEATURE_2_COLOR_ATTACHMENT_BLEND_BIT specifies that an image view can: be used as a framebuffer color attachment that supports - blending and as an input attachment. + blending. * ename:VK_FORMAT_FEATURE_2_DEPTH_STENCIL_ATTACHMENT_BIT specifies that an image view can: be used as a framebuffer depth/stencil attachment and as an input attachment. diff --git a/chapters/fragops.adoc b/chapters/fragops.adoc index 412a9252c8..31fb4f9c86 100644 --- a/chapters/fragops.adoc +++ b/chapters/fragops.adoc @@ -22,6 +22,9 @@ endif::VK_NV_scissor_exclusive[] . <> . Certain <> operations: ** <> +ifdef::VK_EXT_shader_tile_image[] + ** <> +endif::VK_EXT_shader_tile_image[] ** <> ifdef::VK_EXT_shader_stencil_export[] ** <> @@ -279,6 +282,7 @@ replace the current state for the discard rectangle at index pname:discardRectangleCount)#. This command sets the discard rectangles for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -328,7 +332,9 @@ include::{generated}/api/protos/vkCmdSetDiscardRectangleEnableEXT.adoc[] enabled or not. This command sets the discard rectangle enable for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is implied by the @@ -361,6 +367,7 @@ include::{generated}/api/protos/vkCmdSetDiscardRectangleModeEXT.adoc[] discard rectangles, either inclusive or exclusive. This command sets the discard rectangle mode for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -431,6 +438,7 @@ the current state for the scissor index [eq]#pname:firstScissor {plus} i#, for [eq]#i# in [eq]#[0, pname:scissorCount)#. This command sets the scissor rectangles for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SCISSOR set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -559,7 +567,9 @@ pname:pExclusiveScissors replace the current state for the scissor index pname:exclusiveScissorCount)#. This command sets the exclusive scissor rectangles for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -620,7 +630,9 @@ index [eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, pname:exclusiveScissorCount)#. This command sets the exclusive scissor enable for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is implied by the @@ -650,7 +662,7 @@ The sample mask test compares the <> for a fragment with the _sample mask_ defined by slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetSampleMaskEXT',desc='Specify the sample mask dynamically for a command buffer',type='protos'] -- @@ -665,24 +677,47 @@ include::{generated}/api/protos/vkCmdSetSampleMaskEXT.adoc[] * pname:pSampleMask is a pointer to an array of VkSampleMask values, where the array size is based on the pname:samples parameter. -This command sets the sample mask for subsequent drawing commands when the -graphics pipeline is created with ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT set -in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +This command sets the sample mask for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT set in +slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetSampleMaskEXT-None-08504]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetSampleMaskEXT-None-08505]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetSampleMaskEXT-extendedDynamicState3SampleMask-07342]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetSampleMaskEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] Each bit of the coverage mask is associated with a sample index as described in the <>. @@ -778,6 +813,151 @@ code:SampleMask>> built-in in the code:Output storage class will be used by the <> operation, with the same encoding as the input built-in. +ifdef::VK_EXT_shader_tile_image[] +[[fragops-shader-tileimage-reads]] +=== Fragment Shader Tile Image Reads +If the `apiext:VK_EXT_shader_tile_image` extension is enabled, +implementations divide the framebuffer into a grid of tiles. +A <> is a view of a framebuffer attachment +tile for fragments with locations within the tile. + +Within a render pass instance initiated by flink:vkCmdBeginRenderingKHR, +fragment shader invocations can: read the framebuffer color, depth, and +stencil values at the fragment location via tile images. + +[NOTE] +.Note +==== +Even though fragment shader invocation can only read from the corresponding +fragment location, the abstraction of a tile image is introduced for the +following reasons: + + * Tile dimensions will be exposed in a future extension + * Future functionality such as executing compute dispatches within render + passes via tile shaders can leverage tile images. +==== + +Enabling <>, <>, +<> enables fragment shader invocations to +read from color, depth, and stencil, respectively. + +Color values are read from tile image variables with +code:OpColorAttachmentReadEXT. +Tile image variables are linked to specific color attachments using +code:Location decoration. +See <> for more +details. + +Depth values are read with code:OpDepthAttachmentReadEXT. + +Stencil values are read with code:OpStencilAttachmentReadEXT. + +The sample to read is specified by a +<> value specified as +the code:Sample operand to code:OpColorAttachmentReadEXT, +code:OpDepthAttachmentReadEXT, or code:OpStencilAttachmentReadEXT. + +If <> is disabled, a fragment +invocation can: read from all sample locations associated with the fragment +regardless of the fragment's coverage. +This functionality is supported for +slink:VkPipelineMultisampleStateCreateInfo::rasterizationSamples > 1 when +slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::shaderTileImageReadSampleFromPixelRateInvocation +is ename:VK_TRUE. + +If <> is enabled, and +pname:minSampleShading is 1.0, a fragment invocation must: only read from +the <> sample. +Tile image access must: not be used if the value of pname:minSampleShading +is not 1.0. + +If the <> declares the +code:EarlyFragmentTests execution mode, depth reads are allowed only if +depth writes are disabled and stencil reads are allowed only if stencil +writes are disabled. + +If +slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::shaderTileImageReadFromHelperInvocation +is ename:VK_FALSE, values read from helper invocations are undefined: +otherwise the values read are subject to the coherency guarantees described +below. + +code:OpDepthAttachmentReadEXT returns an undefined: value if no depth +attachment is present. +code:OpStencilAttachmentReadEXT returns an undefined: value if no stencil +attachment is present. + +Tile image reads from color, depth and stencil attachments are said to be +coherent when the accesses happen in raster order and without +<> with respect to accesses to the +attachments from framebuffer-space pipeline stages. +The samples which qualify for coherent access and the enabling conditions +are described below. + + * Let [eq]#Rc# be the set of components being read from an attachment + [eq]#A# in a draw call + * Let [eq]#Wc# be the set of components being written to [eq]#A# by the + draw call + +The samples which qualify for coherent tile image reads from an attachment +[eq]#A# are: + + * All samples in a pixel when [eq]#Rc# is disjoint with [eq]#Wc#. + * The samples with coverage in a fragment when [eq]#Rc# is not disjoint + with [eq]#Wc#. + The samples with coverage are determined by the coverage mask for the + fragment as calculated by fragment operations that executed prior to + fragment shading, including early fragment tests if enabled for the draw + call. + +A fragment shader can: declare code:NonCoherentColorAttachmentReadEXT, +code:NonCoherentDepthAttachmentReadEXT, or +code:NonCoherentStencilAttachmentReadEXT execution modes to enable +non-coherent tile image reads which requires +<> for the writes to an attachment to be made +visible via tile image reads. + +When +slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageCoherentReadAccelerated +is ename:VK_TRUE, the implementation prefers that coherent tile image reads +are used, otherwise the implementation prefers that non-coherent tile image +reads are used. + +[NOTE] +.Note +==== +In practice, the most common tile image reads usage patterns fall under one +of the following: + + * Programmable blending - each fragment reads from a single sample + (SampleID) at its location. + Per-sample shading is typically enabled when multisampled rendertargets + are used. + * G-buffer generation and shading in one renderpass - in the shading phase + a fragment reads from a single sample at its location. + * Programmable resolve - a fragment reads from all samples at its location + (per-sample shading is disabled). + This requires the use of a "full-screen triangle" instead of a rectangle + composed of two triangles in order to avoid data races along the shared + edge of the triangles. + * 1:1 texturing with LOD - in use cases such a deferred screen space + decals a fragment reads a single sample (SampleID) from depth buffer, + but requires being able to read from helper threads to derive the + texture LOD. + This use case is supported as long as the attachment components being + read are not overwritten by color, depth, or stencil attachment writes. + +All of the above use cases are supported by coherent tile image reads, but +only the latter three are supported when non-coherent reads are used as +there is no mechanism to synchronize non-coherent reads with writes within a +draw call. +==== + +endif::VK_EXT_shader_tile_image[] [[fragops-shader-depthreplacement]] === Depth Replacement @@ -889,7 +1069,7 @@ endif::VK_EXT_line_rasterization[] pname:alphaToCoverageEnable and pname:alphaToOneEnable members of the slink:VkPipelineMultisampleStateCreateInfo structure. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetAlphaToCoverageEnableEXT',desc='Specify the alpha to coverage enable state dynamically for a command buffer',type='protos'] -- @@ -904,19 +1084,42 @@ include::{generated}/api/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] state. This command sets the pname:alphaToCoverageEnable state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToCoverageEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetAlphaToCoverageEnableEXT-None-08506]] + Either the > feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetAlphaToCoverageEnableEXT-None-08507]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetAlphaToCoverageEnableEXT-extendedDynamicState3AlphaToCoverageEnable-07343]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] @@ -934,18 +1137,41 @@ include::{generated}/api/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] * pname:alphaToOneEnable specifies the pname:alphaToOneEnable state. This command sets the pname:alphaToOneEnable state for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToOneEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetAlphaToOneEnableEXT-None-08508]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetAlphaToOneEnableEXT-None-08509]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetAlphaToOneEnableEXT-extendedDynamicState3AlphaToOneEnable-07345]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetAlphaToOneEnableEXT-alphaToOne-07607]] If the <> feature is not enabled, pname:alphaToOneEnable must: be ename:VK_FALSE @@ -954,7 +1180,7 @@ used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] All alpha values in this section refer only to the alpha component of the fragment shader output that has a code:Location and code:Index decoration of @@ -1125,9 +1351,9 @@ value. These values are either set by the slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or dynamically by -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthBoundsTestEnable and -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthBounds. A given sample is considered within the depth bounds if [eq]#z~a~# is in the @@ -1138,7 +1364,7 @@ their coverage set to `0`. If the depth bounds test is disabled, or if there is no depth attachment, the coverage mask is unmodified by this operation. -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthBoundsTestEnable',desc='Set depth bounds test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBoundsTestEnableEXT'] -- To <> the depth @@ -1146,13 +1372,13 @@ bounds test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -1160,9 +1386,15 @@ endif::VK_EXT_extended_dynamic_state[] enabled. This command sets the depth bounds enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable value used to create the currently active pipeline. @@ -1170,15 +1402,30 @@ value used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthBoundsTestEnable-None-08510]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthBoundsTestEnable-None-08511]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthBoundsTestEnable-None-03349]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnable.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthBounds',desc='Set depth bounds range dynamically for a command buffer',type='protos'] -- @@ -1193,6 +1440,7 @@ include::{generated}/api/protos/vkCmdSetDepthBounds.adoc[] * pname:maxDepthBounds is the maximum depth bound. This command sets the depth bounds range for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -1304,7 +1552,7 @@ and slink:VkPipelineDepthStencilStateCreateInfo::pname:back as: {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetStencilTestEnable',desc='Set stencil test enable dynamically for a command buffer',type='protos',alias='vkCmdSetStencilTestEnableEXT'] -- To <> the stencil @@ -1312,22 +1560,28 @@ test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetStencilTestEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:stencilTestEnable specifies if the stencil test is enabled. This command sets the stencil test enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value used to create the currently active pipeline. @@ -1335,9 +1589,24 @@ used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetStencilTestEnable-None-08512]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetStencilTestEnable-None-08513]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetStencilTestEnable-None-03350]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] @@ -1350,13 +1619,13 @@ To <> the stencil operation, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetStencilOp.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetStencilOpEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -1372,8 +1641,14 @@ endif::VK_EXT_extended_dynamic_state[] operator used in the stencil test. This command sets the stencil operation for subsequent drawing commands when -the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP set -in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP +set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the corresponding sname:VkPipelineDepthStencilStateCreateInfo::pname:failOp, pname:passOp, pname:depthFailOp, and pname:compareOp values used to create the currently @@ -1382,15 +1657,30 @@ active pipeline, for both front and back faces. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetStencilOp-None-08514]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetStencilOp-None-08515]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetStencilOp-None-03351]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetStencilOp.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] -- @@ -1430,6 +1720,7 @@ include::{generated}/api/protos/vkCmdSetStencilCompareMask.adoc[] * pname:compareMask is the new value to use as the stencil compare mask. This command sets the stencil compare mask for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -1478,6 +1769,7 @@ include::{generated}/api/protos/vkCmdSetStencilWriteMask.adoc[] * pname:writeMask is the new value to use as the stencil write mask. This command sets the stencil write mask for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -1504,7 +1796,9 @@ include::{generated}/api/protos/vkCmdSetStencilReference.adoc[] * pname:reference is the new value to use as the stencil reference value. This command sets the stencil reference value for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -1603,17 +1897,17 @@ endif::VK_EXT_depth_range_unrestricted[] === Depth Comparison If the depth test is not enabled, as specified by -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthTestEnable or -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then this step is skipped. The comparison operation performed is determined by the elink:VkCompareOp value set by -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthCompareOp, or by -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during pipeline creation. [eq]#z~f~# and [eq]#z~a~# are used as the _reference_ and _test_ values, @@ -1627,15 +1921,15 @@ If the comparison evaluates to false, the coverage for the sample is set to === Depth Attachment Writes If depth writes are enabled, as specified by -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthWriteEnable or -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable, and the comparison evaluated to true, the depth attachment value [eq]#z~a~# is set to the sample's depth value [eq]#z~f~#. If there is no depth attachment, no value is written. -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthTestEnable',desc='Set depth test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthTestEnableEXT'] -- To <> the depth @@ -1643,22 +1937,28 @@ test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthTestEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthTestEnable specifies if the depth test is enabled. -This command sets the depth test enable for subsequent drawing commands when -the graphics pipeline is created with +This command sets the depth test enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value used to create the currently active pipeline. @@ -1666,9 +1966,24 @@ used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthTestEnable-None-08516]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthTestEnable-None-08517]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthTestEnable-None-03352]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] @@ -1682,13 +1997,13 @@ call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthCompareOp.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -1697,9 +2012,16 @@ endif::VK_EXT_extended_dynamic_state[] Comparison>> step of the <>. This command sets the depth comparison operator for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used to create the currently active pipeline. @@ -1707,9 +2029,24 @@ to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthCompareOp-None-08518]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthCompareOp-None-08519]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthCompareOp-None-03353]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] @@ -1723,22 +2060,28 @@ call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthWriteEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthWriteEnable specifies if depth writes are enabled. This command sets the depth write enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value used to create the currently active pipeline. @@ -1746,15 +2089,30 @@ used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthWriteEnable-None-08520]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetDepthWriteEnable-None-08521]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthWriteEnable-None-03354]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetDepthWriteEnable.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] ifdef::VK_NV_representative_fragment_test[] @@ -1804,7 +2162,7 @@ if enabled. include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetRepresentativeFragmentTestEnableNV',desc='Specify the representative fragment test enable dynamically for a command buffer',type='protos'] -- @@ -1819,25 +2177,49 @@ include::{generated}/api/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[ pname:representativeFragmentTestEnable state. This command sets the pname:representativeFragmentTestEnable state for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRepresentativeFragmentTestStateCreateInfoNV::pname:representativeFragmentTestEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRepresentativeFragmentTestEnableNV-None-08522]] + Either the + <> feature or + the <> feature or both must: + be enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRepresentativeFragmentTestEnableNV-None-08523]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetRepresentativeFragmentTestEnableNV-extendedDynamicState3RepresentativeFragmentTestEnable-07346]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_representative_fragment_test[] @@ -1924,7 +2306,7 @@ tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageToColorEnableNV',desc='Specify the coverage to color enable state dynamically for a command buffer',type='protos'] -- @@ -1939,19 +2321,42 @@ include::{generated}/api/protos/vkCmdSetCoverageToColorEnableNV.adoc[] state. This command sets the pname:coverageToColorEnable state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageToColorEnableNV-None-08524]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageToColorEnableNV-None-08525]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageToColorEnableNV-extendedDynamicState3CoverageToColorEnable-07347]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageToColorEnableNV.adoc[] @@ -1970,25 +2375,48 @@ include::{generated}/api/protos/vkCmdSetCoverageToColorLocationNV.adoc[] pname:coverageToColorLocation state. This command sets the pname:coverageToColorLocation state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorLocation value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageToColorLocationNV-None-08526]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageToColorLocationNV-None-08527]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageToColorLocationNV-extendedDynamicState3CoverageToColorLocation-07348]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageToColorLocationNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_fragment_coverage_to_color[] @@ -2148,7 +2576,7 @@ include::{generated}/api/enums/VkCoverageReductionModeNV.adoc[] covered; other pixel coverage samples are discarded. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageReductionModeNV',desc='Specify the coverage reduction mode dynamically for a command buffer',type='protos'] -- @@ -2163,25 +2591,48 @@ include::{generated}/api/protos/vkCmdSetCoverageReductionModeNV.adoc[] state. This command sets the pname:coverageReductionMode state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageReductionModeNV-None-08528]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageReductionModeNV-None-08529]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageReductionModeNV-extendedDynamicState3CoverageReductionMode-07349]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageReductionModeNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV',desc='Query supported sample count combinations',type='protos'] -- @@ -2355,7 +2806,7 @@ include::{generated}/api/enums/VkCoverageModulationModeNV.adoc[] are multiplied by the modulation factor. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageModulationModeNV',desc='Specify the coverage modulation mode dynamically for a command buffer',type='protos'] -- @@ -2370,19 +2821,42 @@ include::{generated}/api/protos/vkCmdSetCoverageModulationModeNV.adoc[] state. This command sets the pname:coverageModulationMode state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationModeNV-None-08530]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationModeNV-None-08531]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageModulationModeNV-extendedDynamicState3CoverageModulationMode-07350]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationModeNV.adoc[] @@ -2401,19 +2875,43 @@ include::{generated}/api/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] pname:coverageModulationTableEnable state. This command sets the pname:coverageModulationTableEnable state for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationTableEnableNV-None-08532]] + Either the + <> feature or + the <> feature or both must: + be enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationTableEnableNV-None-08533]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageModulationTableEnableNV-extendedDynamicState3CoverageModulationTableEnable-07351]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] @@ -2434,9 +2932,16 @@ include::{generated}/api/protos/vkCmdSetCoverageModulationTableNV.adoc[] containing a value for each number of covered samples. This command sets the table of modulation factors for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableCount, and @@ -2445,15 +2950,31 @@ values used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationTableNV-None-08534]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetCoverageModulationTableNV-None-08535]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCoverageModulationTableNV-extendedDynamicState3CoverageModulationTable-07352]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationTableNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_framebuffer_mixed_samples[] diff --git a/chapters/framebuffer.adoc b/chapters/framebuffer.adoc index 0fba38552e..c31a99a03d 100644 --- a/chapters/framebuffer.adoc +++ b/chapters/framebuffer.adoc @@ -278,7 +278,7 @@ endif::VK_KHR_portability_subset[] include::{generated}/validity/structs/VkPipelineColorBlendAttachmentState.adoc[] -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetColorBlendEnableEXT',desc='Specify the pname:blendEnable for each attachment dynamically for a command buffer',type='protos'] -- @@ -296,18 +296,41 @@ include::{generated}/api/protos/vkCmdSetColorBlendEnableEXT.adoc[] blending is enabled for the corresponding attachment. This command sets the color blending enable of the specified color -attachments for subsequent drawing commands when the graphics pipeline is -created with ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT set in +attachments for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineColorBlendAttachmentState::pname:blendEnable values used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendEnableEXT-None-08536]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendEnableEXT-None-08537]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetColorBlendEnableEXT-extendedDynamicState3ColorBlendEnable-07355]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetColorBlendEnableEXT.adoc[] @@ -331,9 +354,16 @@ include::{generated}/api/protos/vkCmdSetColorBlendEquationEXT.adoc[] corresponding attachments. This command sets the color blending factors and operations of the specified -attachments for subsequent drawing commands when the graphics pipeline is -created with ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT set in +attachments for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_COLOR_BLEND_EQUATION_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineColorBlendAttachmentState::pname:srcColorBlendFactor, slink:VkPipelineColorBlendAttachmentState::pname:dstColorBlendFactor, @@ -345,9 +375,25 @@ create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendEquationEXT-None-08538]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorBlendEquationEXT-None-08539]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetColorBlendEquationEXT-extendedDynamicState3ColorBlendEquation-07356]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetColorBlendEquationEXT.adoc[] @@ -465,24 +511,47 @@ include::{generated}/api/protos/vkCmdSetColorWriteMaskEXT.adoc[] that specify the color write masks of the corresponding attachments. This command sets the color write masks of the specified attachments for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COLOR_WRITE_MASK_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask values used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorWriteMaskEXT-None-08540]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetColorWriteMaskEXT-None-08541]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetColorWriteMaskEXT-extendedDynamicState3ColorWriteMask-07364]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetColorWriteMaskEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [[framebuffer-blendfactors]] @@ -554,9 +623,10 @@ include::{generated}/api/protos/vkCmdSetBlendConstants.adoc[] <>. [[framebuffer-blendconstants]] -This command sets blend constants for subsequent drawing commands when the -graphics pipeline is created with ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS set -in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +This command sets blend constants for subsequent drawing commands when +ifdef::VK_EXT_shader_object[when drawing using <>, or] +the graphics pipeline is created with ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS +set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineColorBlendStateCreateInfo::pname:blendConstants values used to create the currently active pipeline. @@ -790,7 +860,7 @@ as controlled by the component write mask, described in <>. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetLogicOpEnableEXT',desc='Specify dynamically whether logical operations are enabled for a command buffer',type='protos'] -- To <> whether logical operations @@ -803,18 +873,41 @@ include::{generated}/api/protos/vkCmdSetLogicOpEnableEXT.adoc[] * pname:logicOpEnable specifies whether logical operations are enabled. This command sets whether logical operations are enabled for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LOGIC_OP_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineColorBlendStateCreateInfo::pname:logicOpEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLogicOpEnableEXT-None-08542]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLogicOpEnableEXT-None-08543]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetLogicOpEnableEXT-extendedDynamicState3LogicOpEnable-07365]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetLogicOpEnableEXT-logicOp-07366]] If the <> feature is not enabled, pname:logicOpEnable must: be ename:VK_FALSE @@ -822,9 +915,9 @@ create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetLogicOpEnableEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] -ifdef::VK_EXT_extended_dynamic_state2[] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [open,refpage='vkCmdSetLogicOpEXT',desc='Select which logical operation to apply for blend state dynamically for a command buffer',type='protos'] -- To <> the logical operation to @@ -837,23 +930,46 @@ include::{generated}/api/protos/vkCmdSetLogicOpEXT.adoc[] * pname:logicOp specifies the logical operation to apply for blend state. This command sets the logical operation for blend state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state2[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state2[] Otherwise, this state is specified by the slink:VkPipelineColorBlendStateCreateInfo::pname:logicOp value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetLogicOpEXT-None-08544]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +ifndef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetLogicOpEXT-None-08545]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetLogicOpEXT-None-04867]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetLogicOpEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [[framebuffer-color-write-mask]] @@ -989,6 +1105,7 @@ include::{generated}/api/protos/vkCmdSetColorWriteEnableEXT.adoc[] for the given attachment. This command sets the color write enables for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. diff --git a/chapters/fundamentals.adoc b/chapters/fundamentals.adoc index 9198bc2f5a..d50c562b56 100644 --- a/chapters/fundamentals.adoc +++ b/chapters/fundamentals.adoc @@ -1356,6 +1356,10 @@ ifdef::VK_KHR_video_encode_queue[] not adhere to the capabilities of the video compression standard or the implementation. endif::VK_KHR_video_encode_queue[] +ifdef::VK_EXT_shader_object[] + * ename:VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT The provided binary shader + code is not compatible with this device. +endif::VK_EXT_shader_object[] * ename:VK_ERROR_UNKNOWN An unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred. diff --git a/chapters/fxvertex.adoc b/chapters/fxvertex.adoc index 8e6febebf5..42eb6316e6 100644 --- a/chapters/fxvertex.adoc +++ b/chapters/fxvertex.adoc @@ -35,7 +35,7 @@ attributes. In GLSL, vertex shaders associate input variables with a vertex input attribute number using the code:location layout qualifier. -The code:component layout qualifier associates components of a vertex shader +The code:Component layout qualifier associates components of a vertex shader input variable with components of a vertex input attribute. .GLSL example @@ -88,27 +88,18 @@ code:OpDecorate instruction. [[fxvertex-attrib-location]] === Attribute Location and Component Assignment -Vertex shaders allow code:Location and code:Component decorations on input -variable declarations. The code:Location decoration specifies which vertex input attribute is used to read and interpret the data that a variable will consume. -The code:Component decoration allows the location to be more finely -specified for scalars and vectors, down to the individual components within -a location that are consumed. -The components within a location are 0, 1, 2, and 3. -A variable starting at component N will consume components N, N+1, N+2, ... -up through its size. -For single precision types, it is invalid if the sequence of components gets -larger than 3. When a vertex shader input variable declared using a 16- or 32-bit scalar or -vector data type is assigned a location, its value(s) are taken from the -components of the input attribute specified with the corresponding +vector data type is assigned a code:Location, its value(s) are taken from +the components of the input attribute specified with the corresponding sname:VkVertexInputAttributeDescription::pname:location. The components used depend on the type of variable and the code:Component decoration specified in the variable declaration, as identified in <>. -Any 16-bit or 32-bit scalar or vector input will consume a single location. +Any 16-bit or 32-bit scalar or vector input will consume a single +code:Location. For 16-bit and 32-bit data types, missing components are filled in with default values as described <>. @@ -135,7 +126,7 @@ with the corresponding component from the input format (if present), or the default value. When a vertex shader input variable declared using a 32-bit floating point -matrix type is assigned a location _i_, its values are taken from +matrix type is assigned a code:Location _i_, its values are taken from consecutive input attributes starting with the corresponding sname:VkVertexInputAttributeDescription::pname:location. Such matrices are treated as an array of column vectors with values taken @@ -167,31 +158,15 @@ with the corresponding component from the input (if present), or the default value. When a vertex shader input variable declared using a scalar or vector 64-bit -data type is assigned a location _i_, its values are taken from consecutive -input attributes starting with the corresponding +data type is assigned a code:Location _i_, its values are taken from +consecutive input attributes starting with the corresponding sname:VkVertexInputAttributeDescription::pname:location. -The locations and components used depend on the type of variable and the -code:Component decoration specified in the variable declaration, as -identified in <>. +The code:Location slots and code:Component words used depend on the type of +variable and the code:Component decoration specified in the variable +declaration, as identified in <>. For 64-bit data types, no default attribute values are provided. Input variables must: not use more components than provided by the attribute. -Input attributes which have one- or two-component 64-bit formats will -consume a single location. -Input attributes which have three- or four-component 64-bit formats will -consume two consecutive locations. -A 64-bit scalar data type will consume two components, and a 64-bit -two-component vector data type will consume all four components available -within a location. -A three- or four-component 64-bit data type must: not specify a component. -A three-component 64-bit data type will consume all four components of the -first location and components 0 and 1 of the second location. -This leaves components 2 and 3 available for other component-qualified -declarations. -A four-component 64-bit data type will consume all four components of the -first location and all four components of the second location. -It is invalid for a scalar or two-component 64-bit data type to specify a -component of 1 or 3. [[fxvertex-attrib-double]] .Input attribute locations and components accessed by 64-bit input variables @@ -229,12 +204,12 @@ are no default values provided for 64-bit data types, and there is no data provided by the input format. When a vertex shader input variable declared using a 64-bit floating-point -matrix type is assigned a location _i_, its values are taken from +matrix type is assigned a code:Location _i_, its values are taken from consecutive input attribute locations. Such matrices are treated as an array of column vectors with values taken from the input attributes as shown in <>. -Each column vector starts at the location immediately following the last -location of the previous column vector. +Each column vector starts at the code:Location immediately following the +last code:Location of the previous column vector. The number of attributes and components assigned to each matrix is determined by the matrix dimensions and ranges from two to eight locations. @@ -251,15 +226,11 @@ but all at the same specified component within each location. Only input variables declared with the data types and component decorations as specified above are supported. -_Location aliasing_ is causing two variables to have the same location -number. -_Component aliasing_ is assigning the same (or overlapping) component number -for two location aliases. -Location aliasing is allowed only if it does not cause component aliasing. -Further, when location aliasing, the aliases sharing the location must: all -have the same SPIR-V floating-point component type or all have the same -width integer-type components. - +Two variables are allowed to share the same code:Location slot only if their +code:Component words do not overlap. +If multiple variables share the same code:Location slot, they must: all have +the same SPIR-V floating-point component type or all have the same width +scalar type components. [[fxvertex-input]] == Vertex Input Description @@ -416,7 +387,7 @@ endif::VK_KHR_portability_subset[] include::{generated}/validity/structs/VkVertexInputAttributeDescription.adoc[] -- -ifdef::VK_EXT_vertex_input_dynamic_state[] +ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetVertexInputEXT',desc='Set the vertex input state dynamically for a command buffer',type='protos'] -- To <> the vertex input attribute @@ -436,25 +407,54 @@ include::{generated}/api/protos/vkCmdSetVertexInputEXT.adoc[] sname:VkVertexInputAttributeDescription2EXT structures. This command sets the vertex input attribute and vertex input binding -descriptions state for subsequent drawing commands when the graphics -pipeline is created with ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT set in +descriptions state for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_vertex_input_dynamic_state[when drawing using <>, or] +ifndef::VK_EXT_vertex_input_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_vertex_input_dynamic_state[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_vertex_input_dynamic_state[] Otherwise, this state is specified by the slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState values used to create the currently active pipeline. +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] +If +ifdef::VK_EXT_shader_object[] +drawing using <>, +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[or if] +endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] -If the bound pipeline state object was also created with the +the bound pipeline state object was also created with the ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE dynamic state enabled, +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] then flink:vkCmdBindVertexBuffers2 can be used instead of fname:vkCmdSetVertexInputEXT to dynamically set the stride. -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_vertex_input_dynamic_state[] + * [[VUID-vkCmdSetVertexInputEXT-None-08546]] + Either the <> feature or the <> feature or both must: be enabled +endif::VK_EXT_vertex_input_dynamic_state[] +ifndef::VK_EXT_vertex_input_dynamic_state[] + * [[VUID-vkCmdSetVertexInputEXT-None-08547]] + The <> feature must: be + enabled +endif::VK_EXT_vertex_input_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetVertexInputEXT-None-04790]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetVertexInputEXT-vertexBindingDescriptionCount-04791]] pname:vertexBindingDescriptionCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxVertexInputBindings @@ -585,7 +585,7 @@ endif::VK_KHR_portability_subset[] include::{generated}/validity/structs/VkVertexInputAttributeDescription2EXT.adoc[] -- -endif::VK_EXT_vertex_input_dynamic_state[] +endif::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdBindVertexBuffers',desc='Bind vertex buffers to a command buffer',type='protos'] -- @@ -653,7 +653,7 @@ endif::VK_EXT_robustness2[] include::{generated}/validity/protos/vkCmdBindVertexBuffers.adoc[] -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdBindVertexBuffers2',desc='Bind vertex buffers to a command buffer and dynamically set strides',type='protos',alias='vkCmdBindVertexBuffers2EXT'] -- Alternatively, to bind vertex buffers, along with their sizes and strides, @@ -661,13 +661,13 @@ to a command buffer for use in subsequent drawing commands, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdBindVertexBuffers2.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdBindVertexBuffers2EXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command is recorded. @@ -705,29 +705,41 @@ endif::VK_EXT_robustness2[] This command also <> the byte strides between consecutive elements within buffer pname:pBuffers[i] to the -corresponding pname:pStrides[i] value when the graphics pipeline is created -with ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE set in +corresponding pname:pStrides[i] value +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, strides are specified by the sname:VkVertexInputBindingDescription::pname:stride values used to create the currently active pipeline. +ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] +If +ifdef::VK_EXT_shader_object[drawing using <>] ifdef::VK_EXT_vertex_input_dynamic_state[] -If the bound pipeline state object was also created with the -ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled then -flink:vkCmdSetVertexInputEXT can: be used instead of -fname:vkCmdBindVertexBuffers2 to set the stride. +ifdef::VK_EXT_shader_object[or if] +the bound pipeline state object was also created with the +ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state enabled endif::VK_EXT_vertex_input_dynamic_state[] +then flink:vkCmdSetVertexInputEXT can: be used instead of +fname:vkCmdBindVertexBuffers2 to set the stride. +endif::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] [NOTE] .Note ==== Unlike the static state to set the same, pname:pStrides must be between 0 and the maximum extent of the attributes in the binding. -ifdef::VK_EXT_vertex_input_dynamic_state[] +ifdef::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetVertexInputEXT does not have this restriction so can be used if other stride values are desired. -endif::VK_EXT_vertex_input_dynamic_state[] +endif::VK_EXT_vertex_input_dynamic_state,VK_EXT_shader_object[] ==== .Valid Usage @@ -775,7 +787,7 @@ endif::VK_EXT_robustness2[] include::{generated}/validity/protos/vkCmdBindVertexBuffers2.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] ifdef::VK_EXT_vertex_attribute_divisor[] diff --git a/chapters/interfaces.adoc b/chapters/interfaces.adoc index b921e6f8fd..51bd661eaa 100644 --- a/chapters/interfaces.adoc +++ b/chapters/interfaces.adoc @@ -12,6 +12,9 @@ a number of different interfaces. * <> * <> * <> +ifdef::VK_EXT_shader_tile_image[] + * <> +endif::VK_EXT_shader_tile_image[] * <> ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] * <> @@ -178,19 +181,18 @@ write to a matching output variable, as described above. [[interfaces-iointerfaces-locations]] === Location Assignment -This section describes location assignments for user-defined variables and -how many locations are consumed by a given user-variable type. +This section describes code:Location assignments for user-defined variables +and how many code:Location slots are consumed by a given user-variable type. <>, some inputs and outputs have an additional level of arrayness relative to other shader inputs and outputs. This outer array level is removed from the type before considering how many -locations the type consumes. +code:Location slots the type consumes. The code:Location value specifies an interface slot comprised of a 32-bit four-component vector conveyed between stages. -The code:Component specifies -<> within these vector -locations. +The code:Component specifies <> within these vector code:Location slots. Only types with widths of ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 16, @@ -198,7 +200,7 @@ endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] 32 or 64 are supported in shader interfaces. Inputs and outputs of the following types consume a single interface -location: +code:Location: ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] * 16-bit scalar and vector types, and @@ -206,20 +208,21 @@ endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] * 32-bit scalar and vector types, and * 64-bit scalar and 2-component vector types. -64-bit three- and four-component vectors consume two consecutive locations. +64-bit three- and four-component vectors consume two consecutive +code:Location slots. If a declared input or output is an array of size _n_ and each element takes -_m_ locations, it will be assigned _m_ {times} _n_ consecutive locations -starting with the location specified. +_m_ code:Location slots, it will be assigned _m_ {times} _n_ consecutive +code:Location slots starting with the specified code:Location. If the declared input or output is an _n_ {times} _m_ ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] 16-, endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] -32- or 64-bit matrix, it will be assigned multiple locations starting with -the location specified. -The number of locations assigned for each matrix will be the same as for an -_n_-element array of _m_-component vectors. +32- or 64-bit matrix, it will be assigned multiple code:Location slots +starting with the specified code:Location. +The number of code:Location slots assigned for each matrix will be the same +as for an _n_-element array of _m_-component vectors. An code:OpVariable with a structure type that is not a block must: be decorated with a code:Location. @@ -227,9 +230,9 @@ decorated with a code:Location. When an code:OpVariable with a structure type (either block or non-block) is decorated with a code:Location, the members in the structure type must: not be decorated with a code:Location. -The code:OpVariable's members are assigned consecutive locations in -declaration order, starting from the first member, which is assigned the -location decoration from the code:OpVariable. +The code:OpVariable's members are assigned consecutive code:Location slots +in declaration order, starting from the first member, which is assigned the +code:Location decoration from the code:OpVariable. When a block-type code:OpVariable is declared without a code:Location decoration, each member in its structure type must: be decorated with a @@ -237,25 +240,27 @@ code:Location. Types nested deeper than the top-level members must: not have code:Location decorations. -The locations consumed by block and structure members are determined by -applying the rules above in a depth-first traversal of the instantiated -members as though the structure or block member were declared as an input or -output variable of the same type. +The code:Location slots consumed by block and structure members are +determined by applying the rules above in a depth-first traversal of the +instantiated members as though the structure or block member were declared +as an input or output variable of the same type. Any two inputs listed as operands on the same code:OpEntryPoint must: not be -assigned the same location, either explicitly or implicitly. +assigned the same code:Location slot and code:Component word, either +explicitly or implicitly. Any two outputs listed as operands on the same code:OpEntryPoint must: not -be assigned the same location, either explicitly or implicitly. +be assigned the same code:Location slot and code:Component word, either +explicitly or implicitly. -The number of input and output locations available for a shader input or -output interface are limited, and dependent on the shader stage as described -in <>. +The number of input and output code:Location slots available for a shader +input or output interface is limited, and dependent on the shader stage as +described in <>. All variables in both the <> and the <> count against these limits. Each effective code:Location must: have a value less than the number of -locations available for the given interface, as specified in the "`Locations -Available`" column in <>. +code:Location slots available for the given interface, as specified in the +"`Locations Available`" column in <>. [[interfaces-iointerfaces-limits]] @@ -292,11 +297,11 @@ endif::VK_HUAWEI_cluster_culling_shader[] === Component Assignment The code:Component decoration allows the code:Location to be more finely -specified for scalars and vectors, down to the individual components within -a location that are consumed. -The components within a location are 0, 1, 2, and 3. -A variable or block member starting at component N will consume components -N, N+1, N+2, ... +specified for scalars and vectors, down to the individual code:Component +word within a code:Location slot that are consumed. +The code:Component word within a code:Location are 0, 1, 2, and 3. +A variable or block member starting at code:Component N will consume +code:Component words N, N+1, N+2, ... up through its size. ifdef::VK_VERSION_1_1,VK_KHR_16bit_storage[] For 16-, and 32-bit types, @@ -304,15 +309,16 @@ endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] ifndef::VK_VERSION_1_1,VK_KHR_16bit_storage[] For single precision types, endif::VK_VERSION_1_1,VK_KHR_16bit_storage[] -it is invalid if this sequence of components gets larger than 3. -A scalar 64-bit type will consume two of these components in sequence, and a -two-component 64-bit vector type will consume all four components available -within a location. -A three- or four-component 64-bit vector type must: not specify a +it is invalid if this sequence of code:Component words gets larger than 3. +A scalar 64-bit type will consume two of these code:Component words in +sequence, and a two-component 64-bit vector type will consume all four +code:Component words available within a code:Location. +A three- or four-component 64-bit vector type must: not specify a non-zero code:Component decoration. -A three-component 64-bit vector type will consume all four components of the -first location and components 0 and 1 of the second location. -This leaves components 2 and 3 available for other component-qualified +A three-component 64-bit vector type will consume all four code:Component +words of the first code:Location and code:Component 0 and 1 of the second +code:Location. +This leaves code:Component 2 and 3 available for other component-qualified declarations. A scalar or two-component 64-bit data type must: not specify a @@ -320,6 +326,9 @@ code:Component decoration of 1 or 3. A code:Component decoration must: not be specified for any type that is not a scalar or vector. +A four-component 64-bit data type will consume all four code:Component words +of the first code:Location and all four code:Component words of the second +code:Location. [[interfaces-vertexinput]] == Vertex Input Interface @@ -339,7 +348,7 @@ also be identified with a code:Component decoration. For the purposes of interface matching: variables declared without a code:Component decoration are considered to have a code:Component decoration of zero. -The number of available vertex input locations is given by the +The number of available vertex input code:Location slots is given by the pname:maxVertexInputAttributes member of the sname:VkPhysicalDeviceLimits structure. @@ -380,19 +389,19 @@ Values are written to those attachments after passing through the blending unit as described in <>, if enabled. Locations are consumed as described in <>. -The number of available fragment output locations is given by the +The number of available fragment output code:Location slots is given by the pname:maxFragmentOutputAttachments member of the sname:VkPhysicalDeviceLimits structure. Components of the output variables are assigned as described in <>. -Output components identified as 0, 1, 2, and 3 will be directed to the R, G, -B, and A inputs to the blending unit, respectively, or to the output -attachment if blending is disabled. -If two variables are placed within the same location, they must: have the -same underlying type (floating-point or integer). +Output code:Component words identified as 0, 1, 2, and 3 will be directed to +the R, G, B, and A inputs to the blending unit, respectively, or to the +output attachment if blending is disabled. +If two variables are placed within the same code:Location, they must: have +the same underlying type (floating-point or integer). The input values to blending or color attachment writes are undefined: for -components which do not correspond to a fragment shader output. +code:Component words which do not correspond to a fragment shader output. Fragment outputs identified with an code:Index of zero are directed to the first input of the blending unit associated with the corresponding @@ -400,9 +409,9 @@ code:Location. Outputs identified with an code:Index of one are directed to the second input of the corresponding blending unit. -No _component aliasing_ of output variables is allowed, that is there must: -not be two output variables which have the same location, component, and -index, either explicitly declared or implied. +There must: be no output variable which has the same code:Location, +code:Component, and code:Index as any other, either explicitly declared or +implied. Output values written by a fragment shader must: be declared with either code:OpTypeFloat or code:OpTypeInt, and a code:Width of 32. @@ -456,6 +465,43 @@ the vendor's OpenGL implementation, if any. ==== endif::VK_EXT_legacy_dithering[] +ifdef::VK_EXT_shader_tile_image[] +[[interfaces-fragmenttileimage]] +== Fragment Tile Image Interface + +When a fragment stage is present in a pipeline, the fragment shader tile +image variables decorated with code:Location form an interface with the +color attachments defined by the render pass instance. +The fragment shader tile image variables are matched by code:Location +decorations to the color attachments specified in the +pname:pColorAttachments array of the slink:VkRenderingInfoKHR structure +describing the render pass instance the fragment shader is executed in. + +The fragment shader variables listed by code:OpEntryPoint with the +code:TileImageEXT storage class and a decoration of code:Location form the +_fragment tile image interface_. +These variables must: be declared with a type of code:OpTypeImage, and a +code:Dim operand of code:TileImageDataEXT. +The code:Component decoration is not supported for these variables. + +Reading from a tile image variable with a code:Location decoration of _i_ +reads from the color attachment identified by the element of +slink:VkRenderingInfoKHR::pname:pColorAttachments with a pname:location +equal to _i_. +If the tile image variable is declared as an array of size N, it consumes N +consecutive tile image locations, starting with the index specified. +There must: not be more than one tile image variable with the same +code:Location whether explicitly declared or implied by an array +declaration. +The number of available tile image locations is the same as the number of +available fragment output locations as given by the +pname:maxFragmentOutputAttachments member of the +sname:VkPhysicalDeviceLimits structure. + +The basic data type (floating-point, integer, unsigned integer) of the tile +image variable must: match the basic format of the corresponding color +attachment, or the values read from the tile image variables are undefined:. +endif::VK_EXT_shader_tile_image[] [[interfaces-inputattachment]] == Fragment Input Attachment Interface @@ -490,7 +536,9 @@ If the subpass input variable is declared as an array of size N, it consumes N consecutive input attachments, starting with the index specified. There must: not be more than one input variable with the same code:InputAttachmentIndex whether explicitly declared or implied by an array -declaration. +declaration per image aspect. +A multi-aspect image (e.g. a depth/stencil format) can: use the same input +variable. The number of available input attachment indices is given by the pname:maxPerStageDescriptorInputAttachments member of the sname:VkPhysicalDeviceLimits structure. diff --git a/chapters/limits.adoc b/chapters/limits.adoc index 8095ca917b..64abbd1063 100644 --- a/chapters/limits.adoc +++ b/chapters/limits.adoc @@ -4049,6 +4049,34 @@ include::{generated}/validity/structs/VkPhysicalDeviceShaderCorePropertiesARM.ad -- endif::VK_ARM_shader_core_properties[] +ifdef::VK_EXT_shader_object[] +[open,refpage='VkPhysicalDeviceShaderObjectPropertiesEXT',desc='Structure describing shader object properties supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceShaderObjectPropertiesEXT structure is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceShaderObjectPropertiesEXT.adoc[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[limits-shaderBinaryUUID]] pname:shaderBinaryUUID is an array of + ename:VK_UUID_SIZE code:uint8_t values representing a universally unique + identifier for one or more implementations whose shader binaries are + guaranteed to be compatible with each other. + * [[limits-shaderBinaryVersion]] pname:shaderBinaryVersion is an unsigned + integer incremented to represent backwards compatible differences + between implementations with the same pname:shaderBinaryUUID. + +The purpose and usage of the values of this structure are described in +greater detail in <>. + +:refpage: VkPhysicalDeviceShaderObjectPropertiesEXT +include::{chapters}/limits.adoc[tag=limits_desc] + +include::{generated}/validity/structs/VkPhysicalDeviceShaderObjectPropertiesEXT.adoc[] +-- +endif::VK_EXT_shader_object[] [[limits-minmax]] == Limit Requirements diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index ced5498334..79c27b5943 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -719,6 +719,12 @@ or the equivalent include::{generated}/api/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.adoc[] endif::VK_EXT_subgroup_size_control[] +ifdef::VK_EXT_shader_object[] +or the equiavlent + +include::{generated}/api/structs/VkShaderRequiredSubgroupSizeCreateInfoEXT.adoc[] +endif::VK_EXT_shader_object[] + * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. @@ -731,6 +737,12 @@ included in the pname:pNext chain of slink:VkPipelineShaderStageCreateInfo, it specifies that the pipeline shader stage being compiled has a required subgroup size. +ifdef::VK_EXT_shader_object[] +If a sname:VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included +in the pname:pNext chain of slink:VkShaderCreateInfoEXT, it specifies that +the shader being compiled has a required subgroup size. +endif::VK_EXT_shader_object[] + .Valid Usage **** * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfo-requiredSubgroupSize-02760]] @@ -2732,6 +2744,15 @@ endif::VK_EXT_mesh_shader[] <> and pname:renderPass is dlink:VK_NULL_HANDLE, fragment shaders in pname:pStages must: not include the code:InputAttachment capability +ifdef::VK_EXT_shader_tile_image[] + * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-08710]] + If the pipeline is being created with + <> + and pname:renderPass is not dlink:VK_NULL_HANDLE, fragment shaders in + pname:pStages must: not include any of the + code:TileImageColorReadAccessEXT, code:TileImageDepthReadAccessEXT, or + code:TileImageStencilReadAccessEXT capabilities +endif::VK_EXT_shader_tile_image[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06062]] If the pipeline is being created with <>, and no element of the pname:pDynamicStates member of pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR or ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT, and if - <> is enabled, then the index of the most - significant bit in each element of - slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks must: be less than - pname:pViewportState::pname:scissorCount + <> is + enabled, then the index of the most significant bit in each element of + slink:VkRenderPassMultiviewCreateInfo::pname:pViewMasks must: be less + than pname:pViewportState::pname:scissorCount endif::VK_QCOM_multiview_per_view_viewports[] - +ifdef::VK_EXT_shader_tile_image[] + * [[VUID-VkGraphicsPipelineCreateInfo-pStages-08711]] + If pname:pStages includes a fragment shader stage, + ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE is not set in + slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and the + fragment shader declares the code:EarlyFragmentTests execution mode and + uses code:OpDepthAttachmentReadEXT, the pname:depthWriteEnable member of + slink:VkPipelineDepthStencilStateCreateInfo must: be ename:VK_FALSE + * [[VUID-VkGraphicsPipelineCreateInfo-pStages-08712]] + If pname:pStages includes a fragment shader stage, + ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK is not set in + slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and the + fragment shader declares the code:EarlyFragmentTests execution mode and + uses code:OpStencilAttachmentReadEXT, the value of + slink::VkStencilOpState::pname:writeMask for both pname:front and + pname:back in slink:VkPipelineDepthStencilStateCreateInfo must: be `0` +endif::VK_EXT_shader_tile_image[] **** include::{generated}/validity/structs/VkGraphicsPipelineCreateInfo.adoc[] @@ -5113,7 +5149,8 @@ endif::VK_KHR_pipeline_library[] * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-07999]] If pname:pLibraryInfo is `NULL` or its pname:libraryCount is `0`, pname:stageCount must: not be `0` - * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-08700]] If pname:flags does not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR + * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-08700]] + If pname:flags does not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and either pname:pLibraryInfo is `NULL` or its pname:libraryCount is `0`, pname:groupCount must: not be `0` * [[VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602]] @@ -5142,7 +5179,8 @@ ifdef::VK_EXT_opacity_micromap[] set endif::VK_EXT_opacity_micromap[] ifdef::VK_NV_displacement_micromap[] - * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-08701]] If pname:flags includes + * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-08701]] + If pname:flags includes ename:VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV, each element of pname:pLibraryInfo->pLibraries must: have been created with the ename:VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV @@ -6440,7 +6478,15 @@ include::{generated}/api/protos/vkCmdBindPipeline.adoc[] [[pipelines-bindpoint-commands]] Once bound, a pipeline binding affects subsequent commands that interact with the given pipeline type in the command buffer until a different -pipeline of the same type is bound to the bind point. +pipeline of the same type is bound to the bind +ifdef::VK_EXT_shader_object[] +point, or until the pipeline bind point is disturbed by binding a +<> as described in +<>. +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] +point. +endif::VK_EXT_shader_object[] Commands that do not interact with the given pipeline type must: not be affected by the pipeline state. @@ -6655,6 +6701,16 @@ include::{generated}/validity/protos/vkCmdBindPipelineShaderGroupNV.adoc[] -- endif::VK_NV_device_generated_commands[] +ifdef::VK_EXT_shader_object[] +[[pipelines-shader-object-interaction]] +=== Interaction with Shader Objects + +If the <> feature is enabled, +applications can: use both pipelines and <> +at the same time. +The interaction between pipelines and shader objects is described in +<>. +endif::VK_EXT_shader_object[] [[pipelines-dynamic-state]] == Dynamic State diff --git a/chapters/primsrast.adoc b/chapters/primsrast.adoc index e80995a4a4..8c916a9139 100644 --- a/chapters/primsrast.adoc +++ b/chapters/primsrast.adoc @@ -269,7 +269,7 @@ slink:VkPipelineRasterizationStateCreateInfo is enabled. When enabled, primitives are discarded after they are processed by the last active shader stage in the pipeline before rasterization. -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [open,refpage='vkCmdSetRasterizerDiscardEnable',desc='Control whether primitives are discarded before the rasterization stage dynamically for a command buffer',type='protos',alias='vkCmdSetRasterizerDiscardEnableEXT'] -- To <> whether primitives are @@ -277,23 +277,29 @@ discarded before the rasterization stage, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state2[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state2[] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetRasterizerDiscardEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:rasterizerDiscardEnable controls whether primitives are discarded immediately before the rasterization stage. -This command sets the discard enable for subsequent drawing commands when -the graphics pipeline is created with +This command sets the discard enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable value used to create the currently active pipeline. @@ -301,15 +307,30 @@ value used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetRasterizerDiscardEnable-None-08548]] + Either the <> feature or the <> feature or both must: be enabled +endif::VK_EXT_extended_dynamic_state2[] +ifndef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetRasterizerDiscardEnable-None-08549]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetRasterizerDiscardEnable-None-04871]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetRasterizerDiscardEnable.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] ifdef::VK_EXT_transform_feedback[] @@ -409,7 +430,7 @@ tname:VkPipelineRasterizationStateStreamCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetRasterizationStreamEXT',desc='Specify the rasterization stream dynamically for a command buffer',type='protos'] -- To <> the @@ -422,19 +443,42 @@ include::{generated}/api/protos/vkCmdSetRasterizationStreamEXT.adoc[] * pname:rasterizationStream specifies the pname:rasterizationStream state. This command sets the pname:rasterizationStream state for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_RASTERIZATION_STREAM_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRasterizationStreamEXT-None-08550]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRasterizationStreamEXT-None-08551]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetRasterizationStreamEXT-extendedDynamicState3RasterizationStream-07410]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetRasterizationStreamEXT-transformFeedback-07411]] The <> feature must: be enabled @@ -449,7 +493,7 @@ value used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetRasterizationStreamEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_EXT_transform_feedback[] @@ -595,7 +639,7 @@ slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples. Each sample in a set is assigned a unique _sample index_ [eq]#i# in the range [eq]#[0, pname:rasterizationSamples)#. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetRasterizationSamplesEXT',desc='Specify the rasterization samples dynamically for a command buffer',type='protos'] -- To <> the @@ -608,25 +652,49 @@ include::{generated}/api/protos/vkCmdSetRasterizationSamplesEXT.adoc[] * pname:rasterizationSamples specifies pname:rasterizationSamples. This command sets the pname:rasterizationSamples for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRasterizationSamplesEXT-None-08552]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetRasterizationSamplesEXT-None-08553]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetRasterizationSamplesEXT-extendedDynamicState3RasterizationSamples-07414]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetRasterizationSamplesEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] +[[primsrast-multisampling-coverageindex]] Each sample in a fragment is also assigned a unique _coverage index_ [eq]#j# in the range [eq]#[0, n {times} pname:rasterizationSamples)#, where [eq]#n# is the number of sets in the fragment. @@ -889,7 +957,7 @@ slink:VkPhysicalDeviceSampleLocationsPropertiesEXT. include::{generated}/validity/structs/VkSampleLocationEXT.adoc[] -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetSampleLocationsEnableEXT',desc='Specify the samples locations enable state dynamically for a command buffer',type='protos'] -- @@ -904,25 +972,48 @@ include::{generated}/api/protos/vkCmdSetSampleLocationsEnableEXT.adoc[] state. This command sets the pname:sampleLocationsEnable state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetSampleLocationsEnableEXT-None-08554]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetSampleLocationsEnableEXT-None-08555]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetSampleLocationsEnableEXT-extendedDynamicState3SampleLocationsEnable-07415]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetSampleLocationsEnableEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetSampleLocationsEXT',desc='Set sample locations dynamically for a command buffer',type='protos'] -- @@ -936,7 +1027,9 @@ include::{generated}/api/protos/vkCmdSetSampleLocationsEXT.adoc[] * pname:pSampleLocationsInfo is the sample locations state to set. This command sets the custom sample locations for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates, and when the slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable @@ -1159,7 +1252,9 @@ include::{generated}/api/protos/vkCmdSetFragmentShadingRateKHR.adoc[] generated by subsequent drawing commands. This command sets the pipeline fragment shading rate and combiner operation -for subsequent drawing commands when the graphics pipeline is created with +for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -1338,6 +1433,11 @@ ifdef::VK_EXT_sample_locations[] slink:VkPipelineSampleLocationsStateCreateInfoEXT::pname:sampleLocationsEnable is ename:VK_TRUE. endif::VK_EXT_sample_locations[] +ifdef::VK_EXT_shader_tile_image[] + * The fragment shader declares any of the + code:TileImageColorReadAccessEXT, code:TileImageDepthReadAccessEXT, or + code:TileImageStencilReadAccessEXT capabilities. +endif::VK_EXT_shader_tile_image[] Otherwise, each of the specified shading rates are combined and then used to derive the value of [eq]#C~xy~'#. @@ -1582,7 +1682,9 @@ include::{generated}/api/protos/vkCmdSetFragmentShadingRateEnumNV.adoc[] generated by subsequent drawing commands. This command sets the pipeline fragment shading rate and combiner operation -for subsequent drawing commands when the graphics pipeline is created with +for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -1838,7 +1940,7 @@ The number of entries in each palette is given by the implementation-dependent <>. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetShadingRateImageEnableNV',desc='Specify the shading rate image enable state dynamically for a command buffer',type='protos'] -- To <> the @@ -1852,24 +1954,47 @@ include::{generated}/api/protos/vkCmdSetShadingRateImageEnableNV.adoc[] state. This command sets the pname:shadingRateImageEnable state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SHADING_RATE_IMAGE_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineViewportShadingRateImageStateCreateInfoNV::pname:shadingRateImageEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetShadingRateImageEnableNV-None-08556]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetShadingRateImageEnableNV-None-08557]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetShadingRateImageEnableNV-extendedDynamicState3ShadingRateImageEnable-07416]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetShadingRateImageEnableNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetViewportShadingRatePaletteNV',desc='Set shading rate image palettes dynamically for a command buffer',type='protos'] -- @@ -1889,7 +2014,9 @@ include::{generated}/api/protos/vkCmdSetViewportShadingRatePaletteNV.adoc[] viewport. This command sets the per-viewport shading rate image palettes for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -2267,7 +2394,9 @@ sample count not enumerated in pname:pCustomSampleOrders will be identical to that used for ename:VK_COARSE_SAMPLE_ORDER_TYPE_DEFAULT_NV. This command sets the order of coverage samples for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the @@ -2323,28 +2452,43 @@ shader at least [eq]#max({lceil} slink:VkPipelineMultisampleStateCreateInfo::pname:minSampleShading {times} slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples {rceil}, 1)# times per fragment. -If a fragment shader entry point's interface includes an input variable -decorated with a code:BuiltIn of code:SampleId or code:SamplePosition, a -value of `1.0` is used instead of pname:minSampleShading. +If slink:VkPipelineMultisampleStateCreateInfo::pname:sampleShadingEnable is +set to ename:VK_TRUE, sample shading is enabled. + +If a fragment shader entry point <> an +input variable decorated with a code:BuiltIn of code:SampleId or +code:SamplePosition, sample shading is enabled and a value of `1.0` is used +instead of pname:minSampleShading. +If a fragment shader entry point <> an +input variable decorated with code:Sample, sample shading may: be enabled +and a value of `1.0` will be used instead of pname:minSampleShading if it +is. ifdef::VK_AMD_mixed_attachment_samples[] If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled and the subpass uses color attachments, the pname:samples value used to create each color attachment is used instead of pname:rasterizationSamples. endif::VK_AMD_mixed_attachment_samples[] -Sample shading is enabled if at least one of the following conditions is -true: - - * slink:VkPipelineMultisampleStateCreateInfo::pname:sampleShadingEnable is - set to ename:VK_TRUE, or - * the fragment shader's entry point interface includes input variables - decorated with a code:BuiltIn of code:SampleId or code:SamplePosition - built-ins. +[NOTE] +.Note +==== +If a shader decorates an input variable with code:Sample and that value +meaningfully impacts the output of a shader, sample shading will be enabled +to ensure that the input is in fact interpolated per-sample. +This is inherent to the specification and not spelled out here - if an +application simply declares such a variable it is implementation-defined +whether sample shading is enabled or not. +It is possible to see the effects of this by using atomics in the shader or +using a pipeline statistics query to query the number of fragment +invocations, even if the shader itself does not use any per-sample +variables. +==== -If there are fewer invocations than <>, +If there are fewer fragment invocations than <>, implementations may: include those samples in fragment shader invocations in -any manner as long as covered samples are all shaded at least once. - +any manner as long as covered samples are all shaded at least once, and each +invocation that is not a <> +covers at least one sample. ifdef::VK_NV_fragment_shader_barycentric,VK_KHR_fragment_shader_barycentric[] [[primsrast-barycentric]] @@ -2646,7 +2790,7 @@ include::{generated}/api/enums/VkLineRasterizationModeEXT.adoc[] falloff, as defined in <>. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetLineRasterizationModeEXT',desc='Specify the line rasterization mode dynamically for a command buffer',type='protos'] -- @@ -2661,19 +2805,42 @@ include::{generated}/api/protos/vkCmdSetLineRasterizationModeEXT.adoc[] state. This command sets the pname:lineRasterizationMode state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_RASTERIZATION_MODE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:lineRasterizationMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLineRasterizationModeEXT-None-08558]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLineRasterizationModeEXT-None-08559]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetLineRasterizationModeEXT-extendedDynamicState3LineRasterizationMode-07417]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetLineRasterizationModeEXT-lineRasterizationMode-07418]] If pname:lineRasterizationMode is ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_EXT, then the @@ -2705,24 +2872,47 @@ include::{generated}/api/protos/vkCmdSetLineStippleEnableEXT.adoc[] * pname:stippledLineEnable specifies the pname:stippledLineEnable state. This command sets the pname:stippledLineEnable state for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_STIPPLE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationLineStateCreateInfoEXT::pname:stippledLineEnable value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLineStippleEnableEXT-None-08560]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetLineStippleEnableEXT-None-08561]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetLineStippleEnableEXT-extendedDynamicState3LineStippleEnable-07421]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetLineStippleEnableEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_EXT_line_rasterization[] @@ -2736,9 +2926,10 @@ include::{generated}/api/protos/vkCmdSetLineWidth.adoc[] recorded. * pname:lineWidth is the width of rasterized line segments. -This command sets the line width for subsequent drawing commands when the -graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_WIDTH set in -slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +This command sets the line width for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_WIDTH +set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:lineWidth value used to create the currently active pipeline. @@ -3098,6 +3289,7 @@ include::{generated}/api/protos/vkCmdSetLineStippleEXT.adoc[] rasterization. This command sets the line stipple state for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. @@ -3194,7 +3386,7 @@ Any triangle which is not front-facing is back-facing, including zero-area triangles. -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetFrontFace',desc='Set front face orientation dynamically for a command buffer',type='protos',alias='vkCmdSetFrontFaceEXT'] -- To <> the front face orientation, @@ -3202,13 +3394,13 @@ call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetFrontFace.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetFrontFaceEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -3216,8 +3408,14 @@ endif::VK_EXT_extended_dynamic_state[] triangle orientation to be used for culling. This command sets the front face orientation for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_FRONT_FACE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:frontFace value used to create the currently active pipeline. @@ -3225,15 +3423,30 @@ create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetFrontFace-None-08562]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetFrontFace-None-08563]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetFrontFace-None-03383]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetFrontFace.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='VkCullModeFlagBits',desc='Bitmask controlling triangle culling',type='enums'] @@ -3265,28 +3478,34 @@ tname:VkCullModeFlags is a bitmask type for setting a mask of zero or more elink:VkCullModeFlagBits. -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetCullMode',desc='Set cull mode dynamically for a command buffer',type='protos',alias='vkCmdSetCullModeEXT'] -- To <> the cull mode, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetCullMode.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetCullModeEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:cullMode specifies the cull mode property to use for drawing. -This command sets the cull mode for subsequent drawing commands when the -graphics pipeline is created with ename:VK_DYNAMIC_STATE_CULL_MODE set in -slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +This command sets the cull mode for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_CULL_MODE +set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode value used to create the currently active pipeline. @@ -3294,15 +3513,30 @@ create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetCullMode-None-08564]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetCullMode-None-08565]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetCullMode-None-03384]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetCullMode.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] The rule for determining which fragments are produced by polygon rasterization is called _point sampling_. @@ -3458,7 +3692,7 @@ a polygon's vertices are shaded and the polygon is clipped and possibly culled before these modes are applied. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetPolygonModeEXT',desc='Specify polygon mode dynamically for a command buffer',type='protos'] -- @@ -3470,18 +3704,41 @@ include::{generated}/api/protos/vkCmdSetPolygonModeEXT.adoc[] recorded. * pname:polygonMode specifies polygon mode. -This command sets the polygon mode for subsequent drawing commands when the -graphics pipeline is created with ename:VK_DYNAMIC_STATE_POLYGON_MODE_EXT -set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +This command sets the polygon mode for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with +ename:VK_DYNAMIC_STATE_POLYGON_MODE_EXT set in +slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetPolygonModeEXT-None-08566]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetPolygonModeEXT-None-08567]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetPolygonModeEXT-extendedDynamicState3PolygonMode-07422]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] ifndef::VK_NV_fill_rectangle[] * [[VUID-vkCmdSetPolygonModeEXT-fillModeNonSolid-07423]] If the <> feature is @@ -3501,7 +3758,7 @@ endif::VK_NV_fill_rectangle[] include::{generated}/validity/protos/vkCmdSetPolygonModeEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [[primsrast-depthbias]] @@ -3528,7 +3785,7 @@ used to create the currently active pipeline. If the depth bias enable is ename:VK_FALSE, no bias is applied and the fragment's depth values are unchanged. -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthBiasEnable',desc='Control whether to bias fragment depth values dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBiasEnableEXT'] -- To <> whether to bias fragment @@ -3536,22 +3793,28 @@ depth values, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthBiasEnable.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state2[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state2[] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthBiasEnableEXT.adoc[] -endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthBiasEnable controls whether to bias fragment depth values. -This command sets the depth bias enable for subsequent drawing commands when -the graphics pipeline is created with +This command sets the depth bias enable for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:depthBiasEnable value used to create the currently active pipeline. @@ -3559,15 +3822,30 @@ used to create the currently active pipeline. ifndef::VK_VERSION_1_3[] .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetDepthBiasEnable-None-08568]] + Either the <> feature or the <> feature or both must: be enabled +endif::VK_EXT_extended_dynamic_state2[] +ifndef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetDepthBiasEnable-None-08569]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthBiasEnable-None-04872]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** endif::VK_VERSION_1_3[] include::{generated}/validity/protos/vkCmdSetDepthBiasEnable.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] [[primsrast-depthbias-computation]] @@ -3681,6 +3959,7 @@ include::{generated}/api/protos/vkCmdSetDepthBias.adoc[] slope in depth bias calculations. This command sets the depth bias parameters for subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BIAS set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the corresponding @@ -3785,7 +4064,7 @@ include::{generated}/api/enums/VkConservativeRasterizationModeEXT.adoc[] that conservative rasterization is enabled in underestimation mode. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetConservativeRasterizationModeEXT',desc='Specify the conservative rasterization mode dynamically for a command buffer',type='protos'] -- @@ -3800,19 +4079,43 @@ include::{generated}/api/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[] pname:conservativeRasterizationMode state. This command sets the pname:conservativeRasterizationMode state for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_CONSERVATIVE_RASTERIZATION_MODE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:conservativeRasterizationMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetConservativeRasterizationModeEXT-None-08570]] + Either the + <> feature or + the <> feature or both must: + be enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetConservativeRasterizationModeEXT-None-08571]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetConservativeRasterizationModeEXT-extendedDynamicState3ConservativeRasterizationMode-07426]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetConservativeRasterizationModeEXT.adoc[] @@ -3831,19 +4134,43 @@ include::{generated}/api/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc pname:extraPrimitiveOverestimationSize. This command sets the pname:extraPrimitiveOverestimationSize for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_EXTRA_PRIMITIVE_OVERESTIMATION_SIZE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationConservativeStateCreateInfoEXT::pname:extraPrimitiveOverestimationSize value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-None-08572]] + Either the + <> feature or + the <> feature or both must: + be enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-None-08573]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extendedDynamicState3ExtraPrimitiveOverestimationSize-07427]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetExtraPrimitiveOverestimationSizeEXT-extraPrimitiveOverestimationSize-07428]] pname:extraPrimitiveOverestimationSize must: be in the range of `0.0` to sname:VkPhysicalDeviceConservativeRasterizationPropertiesEXT::pname:maxExtraPrimitiveOverestimationSize @@ -3853,7 +4180,7 @@ value used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetExtraPrimitiveOverestimationSizeEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] When overestimate conservative rasterization is enabled, rather than evaluating coverage at individual sample locations, a determination is made diff --git a/chapters/renderpass.adoc b/chapters/renderpass.adoc index 45b7cdaaf6..fc706db838 100644 --- a/chapters/renderpass.adoc +++ b/chapters/renderpass.adoc @@ -195,7 +195,7 @@ ifdef::VK_VERSION_1_1,VK_KHR_device_group[] If the pname:pNext chain does not contain slink:VkDeviceGroupRenderPassBeginInfo or its pname:deviceRenderAreaCount member is equal to 0, the sum of - pname:renderArea.extent.width and pname:renderArea.offset.y must: be + pname:renderArea.extent.height and pname:renderArea.offset.y must: be less than or equal to <> * [[VUID-VkRenderingInfo-pNext-06079]] @@ -2992,7 +2992,6 @@ conditions: ==== endif::VK_EXT_attachment_feedback_loop_layout[] - ifdef::VK_VERSION_1_2,VK_KHR_create_renderpass2[] A more extensible version of render pass creation is also defined below. diff --git a/chapters/resources.adoc b/chapters/resources.adoc index 6b190ee110..029477835c 100644 --- a/chapters/resources.adoc +++ b/chapters/resources.adoc @@ -4265,17 +4265,15 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the pname:format of the pname:image is a <> format, and - if pname:subresourceRange.aspectMask is one of - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT, then pname:format must: be compatible - with the elink:VkFormat for the plane of the pname:image pname:format - indicated by pname:subresourceRange.aspectMask, as defined in + if pname:subresourceRange.aspectMask is one of the + <>, then + pname:format must: be compatible with the elink:VkFormat for the plane + of the pname:image pname:format indicated by + pname:subresourceRange.aspectMask, as defined in <> * [[VUID-VkImageViewCreateInfo-subresourceRange-07818]] - If pname:subresourceRange.aspectMask contains any of - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT, then it must: only have a single bit - set + pname:subresourceRange.aspectMask must: only have at most 1 valid + <> endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] // The VU below comes in an alternate version when the extension is @@ -7603,12 +7601,8 @@ endif::VK_ANDROID_external_memory_android_hardware_buffer[] If pname:pCreateInfo::pname:flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT set and if the pname:pCreateInfo::pname:tiling is ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_OPTIMAL, then - pname:planeAspect must: be a single valid _format plane_ for the image - (that is, for a two-plane image pname:planeAspect must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT, - and for a three-plane image pname:planeAspect must: be - ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT) + pname:planeAspect must: be a single valid + <> ifdef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06420]] If pname:pCreateInfo::pname:tiling is @@ -7653,11 +7647,7 @@ endif::VK_KHR_sampler_ycbcr_conversion[] * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02281]] If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single - valid _format plane_ for the image (that is, for a two-plane image - pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or - ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image - pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, - ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) + valid <> ifdef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02282]] If the image's pname:tiling is @@ -7837,6 +7827,15 @@ endif::VK_KHR_bind_memory2[] On some implementations, it may: be more efficient to batch memory bindings into a single command. +[NOTE] +.Note +==== +If fname:vkBindBufferMemory2 fails, and pname:bindInfoCount was greater than +one, then the buffers referenced by pname:pBindInfos will be in an +indeterminate state, and must not be used. +Applications should destroy these buffers. +==== + include::{generated}/validity/protos/vkBindBufferMemory2.adoc[] -- @@ -8029,6 +8028,15 @@ endif::VK_KHR_bind_memory2[] On some implementations, it may: be more efficient to batch memory bindings into a single command. +[NOTE] +.Note +==== +If fname:vkBindImageMemory2 fails, and pname:bindInfoCount was greater than +one, then the images referenced by pname:pBindInfos will be in an +indeterminate state, and must not be used. +Applications should destroy these images. +==== + .Valid Usage **** ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -8395,11 +8403,7 @@ endif::VK_KHR_sampler_ycbcr_conversion[] * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02283]] If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single - valid _format plane_ for the image (that is, for a two-plane image - pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or - ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image - pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, - ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) + valid <> ifdef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02284]] If the image's pname:tiling is diff --git a/chapters/shaders.adoc b/chapters/shaders.adoc index 11aeec28a9..15bc2a337c 100644 --- a/chapters/shaders.adoc +++ b/chapters/shaders.adoc @@ -37,6 +37,1214 @@ The available decorations for each stage are documented in the following subsections. +ifdef::VK_EXT_shader_object[] +[[shaders-objects]] +== Shader Objects + +Shaders may: be compiled and linked into monolithic pipeline objects as +described in <> chapter, or if the +<> feature is enabled they may: +be compiled into individual per-stage _shader objects_ which can: be bound +on a command buffer independently from one another. +Unlike pipelines, shader objects are not intrinsically tied to any specific +set of state. +Instead, state is specified dynamically on the command buffer. + +Each shader object represents a single compiled shader stage, which may: +optionally: be linked with one or more other stages. + +[open,refpage='VkShaderEXT',desc='Opaque handle to a shader object',type='handles'] +-- +Shader objects are represented by sname:VkShaderEXT handles: + +include::{generated}/api/handles/VkShaderEXT.adoc[] +-- + +[[shaders-objects-creation]] +=== Shader Object Creation + +Shader objects may: be created from shader code provided as SPIR-V, or in an +opaque, implementation-defined binary format specific to the physical +device. + +[open,refpage='vkCreateShadersEXT',desc='Create one or more new shaders',type='protos'] +-- +To create one or more shader objects, call: + +include::{generated}/api/protos/vkCreateShadersEXT.adoc[] + + * pname:device is the logical device that creates the shader objects. + * pname:createInfoCount is the length of the pname:pCreateInfos and + pname:pShaders arrays. + * pname:pCreateInfos is a pointer to an array of + slink:VkShaderCreateInfoEXT structures. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + * pname:pShaders is a pointer to an array of slink:VkShaderEXT handles in + which the resulting shader objects are returned. + +When this function returns, whether or not it succeeds, it is guaranteed +that every element of pname:pShaders will have been overwritten by either +dlink:VK_NULL_HANDLE or a valid sname:VkShaderEXT handle. + +This means that whenever shader creation fails, the application can: +determine which shader the returned error pertains to by locating the first +dlink:VK_NULL_HANDLE element in pname:pShaders. +It also means that an application can: always clean up from a failed call by +iterating over the pname:pShaders array and destroying every element that is +not dlink:VK_NULL_HANDLE. + +.Valid Usage +**** + * [[VUID-vkCreateShadersEXT-None-08400]] + The <> feature must: be + enabled + * [[VUID-vkCreateShadersEXT-pCreateInfos-08401]] + If pname:createInfoCount is 1, there must: be no element of + pname:pCreateInfos whose pname:flags member includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08402]] + If the pname:flags member of any element of pname:pCreateInfos includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:flags member of all + other elements of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + ename:VK_SHADER_STAGE_GEOMETRY_BIT, or + ename:VK_SHADER_STAGE_FRAGMENT_BIT must: also include + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT +ifdef::VK_EXT_mesh_shader[] + * [[VUID-vkCreateShadersEXT-pCreateInfos-08403]] + If the pname:flags member of any element of pname:pCreateInfos includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:flags member of all + other elements of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_TASK_BIT_EXT or ename:VK_SHADER_STAGE_MESH_BIT_EXT + must: also include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08404]] + If the pname:flags member of any element of pname:pCreateInfos whose + pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_EXT or + ename:VK_SHADER_STAGE_MESH_BIT_EXT includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, there must: be no member of + pname:pCreateInfos whose pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT + and whose pname:flags member includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08405]] + If there is any element of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_MESH_BIT_EXT and whose pname:flags member includes + both ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT and + ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT, there must: be no element + of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_TASK_BIT_EXT and whose pname:flags member includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-vkCreateShadersEXT-pCreateInfos-08406]] + If the pname:flags member of any element of pname:pCreateInfos includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:flags member of all + other elements of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV + must: also include ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08407]] + If the pname:flags member of any element of pname:pCreateInfos whose + pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_NV or + ename:VK_SHADER_STAGE_MESH_BIT_NV includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, there must: be no member of + pname:pCreateInfos whose pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT + and whose pname:flags member includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08408]] + If there is any element of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_MESH_BIT_NV and whose pname:flags includes both + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT and + ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT, there must: be no element + of pname:pCreateInfos whose pname:stage is + ename:VK_SHADER_STAGE_TASK_BIT_NV and whose pname:flags includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] + * [[VUID-vkCreateShadersEXT-pCreateInfos-08409]] + For each element of pname:pCreateInfos whose pname:flags member includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, if there is any other element + of pname:pCreateInfos whose pname:stage is logically later than the + pname:stage of the former and whose pname:flags member also includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the pname:nextStage of the + former must: be equal to the pname:stage of the element with the + logically earliest pname:stage following the pname:stage of the former + whose pname:flags member also includes + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + * [[VUID-vkCreateShadersEXT-pCreateInfos-08410]] + The pname:stage member of each element of pname:pCreateInfos whose + pname:flags member includes ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + must: be unique + * [[VUID-vkCreateShadersEXT-pCreateInfos-08411]] + The pname:codeType member of all elements of pname:pCreateInfos whose + pname:flags member includes ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT + must: be the same +**** + +include::{generated}/validity/protos/vkCreateShadersEXT.adoc[] +-- + +[open,refpage='VkShaderCreateInfoEXT',desc='Structure specifying parameters of a newly created shader',type='structs'] +-- +The sname:VkShaderCreateInfoEXT structure is defined as: + +include::{generated}/api/structs/VkShaderCreateInfoEXT.adoc[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of tlink:VkShaderCreateFlagsEXT describing + additional parameters of the shader. + * pname:stage is a elink:VkShaderStageFlagBits value specifying a single + shader stage. + * pname:nextStage is a bitmask of tlink:VkShaderStageFlags specifying zero + or more logically later stages which may: be used as a logically next + bound stage when drawing with the shader bound. + * pname:codeType is a elink:VkShaderCodeTypeEXT value specifying the type + of the shader code pointed to be pname:pCode. + * pname:codeSize is the size in bytes of the shader code pointed to be + pname:pCode. + * pname:pCode is a pointer to the shader code to use to create the shader. + * pname:pName is a pointer to a null-terminated UTF-8 string specifying + the entry point name of the shader for this stage. + * pname:setLayoutCount is the number of descriptor set layouts pointed to + by pname:pSetLayouts. + * pname:pSetLayouts is a pointer to an array of + slink:VkDescriptorSetLayout objects used by the shader stage. + * pname:pushConstantRangeCount is the number of push constant ranges + pointed to by pname:pPushConstantRanges. + * pname:pPushConstantRanges is a pointer to an array of + slink:VkPushConstantRange structures used by the shader stage. + * pname:pSpecializationInfo is a pointer to a slink:VkSpecializationInfo + structure, as described in + <>, or + `NULL`. + +.Valid Usage +**** + * [[VUID-VkShaderCreateInfoEXT-flags-08412]] + If pname:stage is not ename:VK_SHADER_STAGE_TASK_BIT_EXT, + ename:VK_SHADER_STAGE_MESH_BIT_EXT, ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + ename:VK_SHADER_STAGE_GEOMETRY_BIT, or + ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags must: not include + ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkShaderCreateInfoEXT-flags-08486]] + If pname:stage is not ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags + must: not include + ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT + * [[VUID-VkShaderCreateInfoEXT-flags-08487]] + If the <> feature is not enabled, + pname:flags must: not include + ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT +endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_EXT_fragment_density_map[] + * [[VUID-VkShaderCreateInfoEXT-flags-08488]] + If pname:stage is not ename:VK_SHADER_STAGE_FRAGMENT_BIT, pname:flags + must: not include + VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT + * [[VUID-VkShaderCreateInfoEXT-flags-08489]] + If the <> feature + is not enabled, pname:flags must: not include + ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT +endif::VK_EXT_fragment_density_map[] + * [[VUID-VkShaderCreateInfoEXT-flags-08413]] + If pname:stage is not ename:VK_SHADER_STAGE_COMPUTE_BIT, pname:flags + must: not include + ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT or + ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT +ifdef::VK_VERSION_1_1,VK_KHR_device_group[] + * [[VUID-VkShaderCreateInfoEXT-flags-08485]] + If pname:stage is not ename:VK_SHADER_STAGE_COMPUTE_BIT, pname:flags + must: not include ename:VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT +endif::VK_VERSION_1_1,VK_KHR_device_group[] +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-flags-08414]] + If pname:stage is not ename:VK_SHADER_STAGE_MESH_BIT_EXT, pname:flags + must: not include ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-flags-08415]] + If pname:stage is not ename:VK_SHADER_STAGE_MESH_BIT_NV, pname:flags + must: not include ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-flags-08416]] + If pname:flags includes both + ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and + ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT, the local + workgroup size in the X dimension of the shader must: be a multiple of + <> + * [[VUID-VkShaderCreateInfoEXT-flags-08417]] + If pname:flags includes + ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT but not + ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and no + slink:VkShaderRequiredSubgroupSizeCreateInfoEXT structure is included in + the pname:pNext chain, the local workgroup size in the X dimension of + the shader must: be a multiple of + <> + * [[VUID-VkShaderCreateInfoEXT-stage-08418]] + pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS or + ename:VK_SHADER_STAGE_ALL + * [[VUID-VkShaderCreateInfoEXT-stage-08419]] + If the <> feature + is not enabled, pname:stage must: not be + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT + * [[VUID-VkShaderCreateInfoEXT-stage-08420]] + If the <> feature is not + enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-stage-08421]] + If the <> feature is not enabled, + pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_EXT + * [[VUID-VkShaderCreateInfoEXT-stage-08422]] + If the <> feature is not enabled, + pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-stage-08423]] + If the <> feature is not enabled, + pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_NV + * [[VUID-VkShaderCreateInfoEXT-stage-08424]] + If the <> feature is not enabled, + pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] +ifdef::VK_HUAWEI_subpass_shading[] + * [[VUID-VkShaderCreateInfoEXT-stage-08425]] + pname:stage must: not be + ename:VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI +endif::VK_HUAWEI_subpass_shading[] +ifdef::VK_HUAWEI_cluster_culling_shader[] + * [[VUID-VkShaderCreateInfoEXT-stage-08426]] + pname:stage must: not be + ename:VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI +endif::VK_HUAWEI_cluster_culling_shader[] + * [[VUID-VkShaderCreateInfoEXT-nextStage-08427]] + If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, pname:nextStage + must: not include any bits other than + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_GEOMETRY_BIT, and + ename:VK_SHADER_STAGE_FRAGMENT_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08428]] + If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT and the + <> feature is not + enabled, pname:nextStage must: not include + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08429]] + If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT and the + <> feature is not + enabled, pname:nextStage must: not include + ename:VK_SHADER_STAGE_GEOMETRY_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08430]] + If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + pname:nextStage must: not include any bits other than + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08431]] + If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + pname:nextStage must: not include any bits other than + ename:VK_SHADER_STAGE_GEOMETRY_BIT and + ename:VK_SHADER_STAGE_FRAGMENT_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08432]] + If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT and + the <> feature is not + enabled, pname:nextStage must: not include + ename:VK_SHADER_STAGE_GEOMETRY_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08433]] + If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, pname:nextStage + must: not include any bits other than ename:VK_SHADER_STAGE_FRAGMENT_BIT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08434]] + If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT or + ename:VK_SHADER_STAGE_COMPUTE_BIT, pname:nextStage must: be 0 +ifdef::VK_EXT_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-nextStage-08435]] + If pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_EXT, pname:nextStage + must: not include any bits other than ename:VK_SHADER_STAGE_MESH_BIT_EXT + * [[VUID-VkShaderCreateInfoEXT-nextStage-08436]] + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_EXT, pname:nextStage + must: not include any bits other than ename:VK_SHADER_STAGE_FRAGMENT_BIT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-nextStage-08437]] + If pname:stage is ename:VK_SHADER_STAGE_TASK_BIT_NV, pname:nextStage + must: not include any bits other than ename:VK_SHADER_STAGE_MESH_BIT_NV + * [[VUID-VkShaderCreateInfoEXT-nextStage-08438]] + If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, pname:nextStage + must: not include any bits other than ename:VK_SHADER_STAGE_FRAGMENT_BIT +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] + * [[VUID-VkShaderCreateInfoEXT-codeSize-08439]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:codeSize + must: be a multiple of 4 + * [[VUID-VkShaderCreateInfoEXT-pName-08440]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pName + must: be the name of an code:OpEntryPoint in pname:pCode with an + execution model that matches pname:stage + * [[VUID-VkShaderCreateInfoEXT-pCode-08441]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode + must: point to valid SPIR-V code, formatted and packed as described by + the <> + * [[VUID-VkShaderCreateInfoEXT-pCode-08442]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode + must: adhere to the validation rules described by the + <> section + of the <> appendix + * [[VUID-VkShaderCreateInfoEXT-pCode-08443]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode + must: declare the code:Shader capability for SPIR-V code + * [[VUID-VkShaderCreateInfoEXT-pCode-08444]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode + must: not declare any capability that is not supported by the API, as + described by the <> section of + the <> appendix + * [[VUID-VkShaderCreateInfoEXT-pCode-08445]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:pCode declares any of the capabilities listed in the + <> appendix, one of the + corresponding requirements must: be satisfied + * [[VUID-VkShaderCreateInfoEXT-pCode-08446]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, pname:pCode + must: not declare any SPIR-V extension that is not supported by the API, + as described by the <> section of the + <> appendix + * [[VUID-VkShaderCreateInfoEXT-pCode-08447]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:pCode declares any of the SPIR-V extensions listed in the + <> appendix, one of the + corresponding requirements must: be satisfied + * [[VUID-VkShaderCreateInfoEXT-pCode-08448]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the + identified entry point includes any variable in its interface that is + declared with the code:ClipDistance code:BuiltIn decoration, that + variable must: not have an array size greater than + sname:VkPhysicalDeviceLimits::pname:maxClipDistances + * [[VUID-VkShaderCreateInfoEXT-pCode-08449]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the + identified entry point includes any variable in its interface that is + declared with the code:CullDistance code:BuiltIn decoration, that + variable must: not have an array size greater than + sname:VkPhysicalDeviceLimits::pname:maxCullDistances + * [[VUID-VkShaderCreateInfoEXT-pCode-08450]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the + identified entry point includes any variables in its interface that are + declared with the code:ClipDistance or code:CullDistance code:BuiltIn + decoration, those variables must: not have array sizes which sum to more + than sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances + * [[VUID-VkShaderCreateInfoEXT-pCode-08451]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and the + identified entry point includes any variable in its interface that is + declared with the code:SampleMask code:BuiltIn decoration, that variable + must: not have an array size greater than + sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords + * [[VUID-VkShaderCreateInfoEXT-pCode-08452]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry + point must: not include any input variable in its interface that is + decorated with code:CullDistance + * [[VUID-VkShaderCreateInfoEXT-pCode-08453]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified + entry point has an code:OpExecutionMode instruction specifying a patch + size with code:OutputVertices, the patch size must: be greater than `0` + and less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize + * [[VUID-VkShaderCreateInfoEXT-pCode-08454]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry + point must: have an code:OpExecutionMode instruction specifying a + maximum output vertex count that is greater than `0` and less than or + equal to sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices + * [[VUID-VkShaderCreateInfoEXT-pCode-08455]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified entry + point must: have an code:OpExecutionMode instruction specifying an + invocation count that is greater than `0` and less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations + * [[VUID-VkShaderCreateInfoEXT-pCode-08456]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is a + <>, and the identified entry point writes to code:Layer for any + primitive, it must: write the same value to code:Layer for all vertices + of a given primitive + * [[VUID-VkShaderCreateInfoEXT-pCode-08457]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is a + <>, and the identified entry point writes to code:ViewportIndex for + any primitive, it must: write the same value to code:ViewportIndex for + all vertices of a given primitive + * [[VUID-VkShaderCreateInfoEXT-pCode-08458]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified entry + point must: not include any output variables in its interface decorated + with code:CullDistance + * [[VUID-VkShaderCreateInfoEXT-pCode-08459]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, and + pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified + entry point writes to code:FragDepth in any execution path, all + execution paths that are not exclusive to helper invocations must: + either discard the fragment, or write or initialize the value of + code:FragDepth + * [[VUID-VkShaderCreateInfoEXT-pCode-08460]] + If pname:codeType is ename:VK_SHADER_CODE_TYPE_SPIRV_EXT, the shader + code in pname:pCode must: be valid as described by the + <> after applying the + specializations provided in pname:pSpecializationInfo, if any, and then + converting all specialization constants into fixed constants +**** + +include::{generated}/validity/structs/VkShaderCreateInfoEXT.adoc[] +-- + +[open,refpage='VkShaderCreateFlagsEXT',desc='Bitmask of VkShaderCreateFlagBitsEXT',type='flags'] +-- +include::{generated}/api/flags/VkShaderCreateFlagsEXT.adoc[] + +tname:VkShaderCreateFlagsEXT is a bitmask type for setting a mask of zero or +more elink:VkShaderCreateFlagBitsEXT. +-- + +[open,refpage='VkShaderCreateFlagBitsEXT',desc='Bitmask controlling how a shader object is created',type='enums'] +-- +Possible values of the pname:flags member of slink:VkShaderCreateInfoEXT +specifying how a shader object is created, are: + +include::{generated}/api/enums/VkShaderCreateFlagBitsEXT.adoc[] + + * ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT specifies that this stage is + linked to all other stages being created in the same + flink:vkCreateShadersEXT call whose slink:VkShaderCreateInfoEXT + structures have the ename:VK_SHADER_CREATE_LINK_STAGE_BIT_EXT flag set + in pname:flags. + * ename:VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT specifies + that the <> may: + vary in the shader stage. + * ename:VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT specifies that the + subgroup sizes must: be launched with all invocations active in the + compute stage. + * ename:VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT specifies that the mesh + shader being created must: only be used without a task shader. + Otherwise, the mesh shader being created must: only be used with a task + shader. +ifdef::VK_VERSION_1_1,VK_KHR_device_group[] + * ename:VK_SHADER_CREATE_DISPATCH_BASE_BIT_EXT specifies that a compute + shader can: be used with flink:vkCmdDispatchBase with a non-zero base + workgroup. +endif::VK_VERSION_1_1,VK_KHR_device_group[] +ifdef::VK_KHR_fragment_shading_rate[] + * ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT + specifies that the fragment shader can: be used with a fragment shading + rate attachment. +endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_EXT_fragment_density_map[] + * ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies + that the fragment shader can: be used with a fragment density map + attachment. +endif::VK_EXT_fragment_density_map[] +-- + +[NOTE] +.Note +==== +The behavior of +ifdef::VK_KHR_fragment_shading_rate[] +ename:VK_SHADER_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_EXT +endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[and] +ifdef::VK_EXT_fragment_density_map[] +ename:VK_SHADER_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT +endif::VK_EXT_fragment_density_map[] +differs subtly from the behavior of +ifdef::VK_KHR_fragment_shading_rate[] +ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR +endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[and] +ifdef::VK_EXT_fragment_density_map[] +ename:VK_PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT +endif::VK_EXT_fragment_density_map[] +in that the shader bit allows, but does not require the shader to be used +with that type of attachment. +This means that the application need not create multiple shaders when it +does not know in advance whether the shader will be used with or without the +attachment type, or when it needs the same shader to be compatible with +usage both with and without. +This may: come at some performance cost on some implementations, so +applications should: still only set bits that are actually necessary. +==== + +[open,refpage='VkShaderCodeTypeEXT',desc='Indicate a shader code type',type='enums'] +-- +Shader objects can: be created using different types of shader code. +Possible values of slink:VkShaderCreateInfoEXT::pname:codeType, are: + +include::{generated}/api/enums/VkShaderCodeTypeEXT.adoc[] + + * ename:VK_SHADER_CODE_TYPE_BINARY_EXT specifies shader code in an opaque, + implementation-defined binary format specific to the physical device. + * ename:VK_SHADER_CODE_TYPE_SPIRV_EXT specifies shader code in SPIR-V + format. +-- + +[[shaders-objects-binary-code]] +=== Binary Shader Code + +[open,refpage='vkGetShaderBinaryDataEXT',desc='Get the binary shader code from a shader object',type='protos'] +-- +Binary shader code can: be retrieved from a shader object using the command: + +include::{generated}/api/protos/vkGetShaderBinaryDataEXT.adoc[] + + * pname:device is the logical device that shader object was created from. + * pname:shader is the shader object to retrieve binary shader code from. + * pname:pDataSize is a pointer to a code:size_t value related to the size + of the binary shader code, as described below. + * pname:pData is either `NULL` or a pointer to a buffer. + +If pname:pData is `NULL`, then the size of the binary shader code of the +shader object, in bytes, is returned in pname:pDataSize. +Otherwise, pname:pDataSize must: point to a variable set by the user to the +size of the buffer, in bytes, pointed to by pname:pData, and on return the +variable is overwritten with the amount of data actually written to +pname:pData. +If pname:pDataSize is less than the size of the binary shader code, nothing +is written to pname:pData, and ename:VK_INCOMPLETE will be returned instead +of ename:VK_SUCCESS. + +[NOTE] +.Note +==== +The behavior of this command when pname:pDataSize is too small differs from +how some other getter-type commands work in Vulkan. +Because shader binary data is only usable in its entirety, it would never be +useful for the implementation to return partial data. +Because of this, nothing is written to pname:pData unless pname:pDataSize is +large enough to fit the data it its entirety. +==== + +Binary shader code retrieved using fname:vkGetShaderBinaryDataEXT can: be +passed to a subsequent call to fname:vkCreateShadersEXT on a compatible +physical device by specifying ename:VK_SHADER_CODE_TYPE_BINARY_EXT in the +pname:codeType member of sname:VkShaderCreateInfoEXT. + +The shader code returned by repeated calls to this function with the same +sname:VkShaderEXT is guaranteed to be invariant for the lifetime of the +sname:VkShaderEXT object. + +.Valid Usage +**** + * [[VUID-vkGetShaderBinaryDataEXT-None-08461]] + The <> feature must: be + enabled +**** + +include::{generated}/validity/protos/vkGetShaderBinaryDataEXT.adoc[] +-- + +[[shaders-objects-binary-compatibility]] +=== Binary Shader Compatibility + +Binary shader compatibility means that binary shader code returned from a +call to fname:vkGetShaderBinaryDataEXT can: be passed to a later call to +fname:vkCreateShadersEXT, potentially on a different logical and/or physical +device, and that this will result in the successful creation of a shader +object functionally equivalent to the shader object that the code was +originally queried from. + +Binary shader code queried from fname:vkGetShaderBinaryDataEXT is not +guaranteed to be compatible across all devices, but implementations are +required to provide some compatibility guarantees. +Applications may: determine binary shader compatibility using either (or +both) of two mechanisms. + +Guaranteed compatibility of shader binaries is expressed through a +combination of the pname:shaderBinaryUUID and pname:shaderBinaryVersion +members of the slink:VkPhysicalDeviceShaderObjectPropertiesEXT structure +queried from a physical device. +Binary shaders retrieved from a physical device with a certain +pname:shaderBinaryUUID are guaranteed to be compatible with all other +physical devices reporting the same pname:shaderBinaryUUID and the same or +higher pname:shaderBinaryVersion. + +Whenever a new version of an implementation incorporates any changes that +affect the output of fname:vkGetShaderBinaryDataEXT, the implementation +should: either increment pname:shaderBinaryVersion if binary shader code +retrieved from older versions remains compatible with the new +implementation, or else replace pname:shaderBinaryUUID with a new value if +backward compatibility has been broken. +Binary shader code queried from a device with a matching +pname:shaderBinaryUUID and lower pname:shaderBinaryVersion relative to the +device on which fname:vkCreateShadersEXT is being called may: be suboptimal +for the new device in ways that do not change shader functionality, but it +is still guaranteed to be usable to successfully create the shader +object(s). + +[NOTE] +.Note +==== +Implementations are encouraged to share pname:shaderBinaryUUID between +devices and driver versions to the maximum extent their hardware naturally +allows, and are *strongly* discouraged from ever changing the +pname:shaderBinaryUUID for the same hardware except unless absolutely +necessary. +==== + +In addition to the shader compatibility guarantees described above, it is +valid for an application to call fname:vkCreateShadersEXT with binary shader +code created on a device with a different or unknown pname:shaderBinaryUUID +and/or higher pname:shaderBinaryVersion. +In this case, the implementation may: use any unspecified means of its +choosing to determine whether the provided binary shader code is usable. +If it is, the fname:vkCreateShadersEXT call must: return ename:VK_SUCCESS, +and the created shader object is guaranteed to be valid. +Otherwise, in the absence of some other error, the fname:vkCreateShadersEXT +call must: return ename:VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT to indicate +that the provided binary shader code is not compatible with the device. + +[[shaders-objects-binding]] +=== Binding Shader Objects + +[open,refpage='vkCmdBindShadersEXT',desc='Bind shader objects to a command buffer',type='protos'] +-- +Once shader objects have been created, they can: be bound to the command +buffer using the command: + +include::{generated}/api/protos/vkCmdBindShadersEXT.adoc[] + + * pname:commandBuffer is the command buffer that the shader object will be + bound to. + * pname:stageCount is the length of the pname:pStages and pname:pShaders + arrays. + * pname:pStages is an array of elink:VkShaderStageFlagBits values + specifying one stage per array index that is affected by the + corresponding value in the pname:pShaders array. + * pname:pShaders is an array of sname:VkShaderEXT handles and/or + dlink:VK_NULL_HANDLE values describing the shader binding operations to + be performed on each stage in pname:pStages. + +When binding linked shaders, an application may: bind them in any +combination of one or more calls to fname:vkCmdBindShadersEXT (i.e., shaders +that were created linked together do not need to be bound in the same +fname:vkCmdBindShadersEXT call). + +Any shader object bound to a particular stage may: be unbound by setting its +value in pname:pShaders to dlink:VK_NULL_HANDLE. +If pname:pShaders is `NULL`, fname:vkCmdBindShadersEXT behaves as if +pname:pShaders was an array of pname:stageCount dlink:VK_NULL_HANDLE values +(i.e., any shaders bound to the stages specified in pname:pStages are +unbound). + +.Valid Usage +**** + * [[VUID-vkCmdBindShadersEXT-None-08462]] + The <> feature must: be + enabled + * [[VUID-vkCmdBindShadersEXT-pStages-08463]] + Every element of pname:pStages must: be unique + * [[VUID-vkCmdBindShadersEXT-pStages-08464]] + pname:pStages must: not contain ename:VK_SHADER_STAGE_ALL_GRAPHICS or + ename:VK_SHADER_STAGE_ALL +ifdef::VK_KHR_ray_tracing_pipeline[] + * [[VUID-vkCmdBindShadersEXT-pStages-08465]] + pname:pStages must: not contain ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, + ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR, + ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR, + ename:VK_SHADER_STAGE_MISS_BIT_KHR, + ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR, or + ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR +endif::VK_KHR_ray_tracing_pipeline[] +ifndef::VK_KHR_ray_tracing_pipeline[] +ifdef::VK_NV_ray_tracing[] + * [[VUID-vkCmdBindShadersEXT-pStages-08466]] + pname:pStages must: not contain ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, + ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV, + ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV, + ename:VK_SHADER_STAGE_MISS_BIT_NV, + ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV, or + ename:VK_SHADER_STAGE_CALLABLE_BIT_NV +endif::VK_NV_ray_tracing[] +endif::VK_KHR_ray_tracing_pipeline[] +ifdef::VK_HUAWEI_subpass_shading[] + * [[VUID-vkCmdBindShadersEXT-pStages-08467]] + pname:pStages must: not contain + ename:VK_SHADER_STAGE_SUBPASS_SHADING_BIT_HUAWEI +endif::VK_HUAWEI_subpass_shading[] +ifdef::VK_HUAWEI_cluster_culling_shader[] + * [[VUID-vkCmdBindShadersEXT-pStages-08468]] + pname:pStages must: not contain + ename:VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI +endif::VK_HUAWEI_cluster_culling_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08469]] + For each element of pname:pStages, if pname:pShaders is not `NULL`, and + the element of the pname:pShaders array with the same index is not + dlink:VK_NULL_HANDLE, it must: have been created with a pname:stage + equal to the corresponding element of pname:pStages +ifdef::VK_EXT_mesh_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08470]] + If pname:pStages contains both ename:VK_SHADER_STAGE_TASK_BIT_EXT and + ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and + the same index in pname:pShaders as ename:VK_SHADER_STAGE_TASK_BIT_EXT + in pname:pStages is not dlink:VK_NULL_HANDLE, the same index in + pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages + must: be dlink:VK_NULL_HANDLE + * [[VUID-vkCmdBindShadersEXT-pShaders-08471]] + If pname:pStages contains both ename:VK_SHADER_STAGE_MESH_BIT_EXT and + ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and + the same index in pname:pShaders as ename:VK_SHADER_STAGE_MESH_BIT_EXT + in pname:pStages is not dlink:VK_NULL_HANDLE, the same index in + pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages + must: be dlink:VK_NULL_HANDLE +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08472]] + If pname:pStages contains both ename:VK_SHADER_STAGE_TASK_BIT_NV and + ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and + the same index in pname:pShaders as ename:VK_SHADER_STAGE_TASK_BIT_NV in + pname:pStages is not dlink:VK_NULL_HANDLE, the same index in + pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages + must: be dlink:VK_NULL_HANDLE + * [[VUID-vkCmdBindShadersEXT-pShaders-08473]] + If pname:pStages contains both ename:VK_SHADER_STAGE_MESH_BIT_NV and + ename:VK_SHADER_STAGE_VERTEX_BIT, and pname:pShaders is not `NULL`, and + the same index in pname:pShaders as ename:VK_SHADER_STAGE_MESH_BIT_NV in + pname:pStages is not dlink:VK_NULL_HANDLE, the same index in + pname:pShaders as ename:VK_SHADER_STAGE_VERTEX_BIT in pname:pStages + must: be dlink:VK_NULL_HANDLE +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08474]] + If the <> feature + is not enabled, and pname:pStages contains + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and pname:pShaders is + not `NULL`, the same index or indices in pname:pShaders must: be + dlink:VK_NULL_HANDLE + * [[VUID-vkCmdBindShadersEXT-pShaders-08475]] + If the <> feature is not + enabled, and pname:pStages contains ename:VK_SHADER_STAGE_GEOMETRY_BIT, + and pname:pShaders is not `NULL`, the same index in pname:pShaders must: + be dlink:VK_NULL_HANDLE + * [[VUID-vkCmdBindShadersEXT-pShaders-08476]] + If pname:pStages contains ename:VK_SHADER_STAGE_COMPUTE_BIT, the + sname:VkCommandPool that pname:commandBuffer was allocated from must: + support compute operations + * [[VUID-vkCmdBindShadersEXT-pShaders-08477]] + If pname:pStages contains ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + ename:VK_SHADER_STAGE_GEOMETRY_BIT, or + ename:VK_SHADER_STAGE_FRAGMENT_BIT, the sname:VkCommandPool that + pname:commandBuffer was allocated from must: support graphics operations +ifdef::VK_EXT_mesh_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08478]] + If pname:pStages contains ename:VK_SHADER_STAGE_MESH_BIT_EXT or + ename:VK_SHADER_STAGE_TASK_BIT_EXT, the sname:VkCommandPool that + pname:commandBuffer was allocated from must: support graphics operations +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * [[VUID-vkCmdBindShadersEXT-pShaders-08480]] + If pname:pStages contains ename:VK_SHADER_STAGE_MESH_BIT_NV or + ename:VK_SHADER_STAGE_TASK_BIT_NV, the sname:VkCommandPool that + pname:commandBuffer was allocated from must: support graphics operations +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] +**** + +include::{generated}/validity/protos/vkCmdBindShadersEXT.adoc[] +-- + +[[shaders-objects-state]] +=== Setting State + +Whenever shader objects are used to issue drawing commands, the appropriate +<> setting commands must: have been +called to set the relevant state on the command buffer prior to drawing: + + * flink:vkCmdSetViewportWithCount + * flink:vkCmdSetScissorWithCount + +If a shader is bound to the ename:VK_SHADER_STAGE_VERTEX_BIT stage, the +following commands must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetVertexInputEXT + * flink:vkCmdSetPrimitiveTopology + * flink:vkCmdSetPatchControlPointsEXT, if pname:primitiveTopology is + ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST + * flink:vkCmdSetPrimitiveRestartEnable + +If a shader is bound to the +ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage, the following +command must: have been called on the command buffer prior to drawing: + + * flink:vkCmdSetTessellationDomainOriginEXT + +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, the +following command must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetRasterizerDiscardEnable + +If pname:rasterizerDiscardEnable is ename:VK_FALSE, the following commands +must: have been called on the command buffer prior to drawing: + + * flink:vkCmdSetRasterizationSamplesEXT + * flink:vkCmdSetSampleMaskEXT + * flink:vkCmdSetAlphaToCoverageEnableEXT + * flink:vkCmdSetAlphaToOneEnableEXT, if the <> feature is enabled on the device + * flink:vkCmdSetPolygonModeEXT + * flink:vkCmdSetLineWidth, if pname:polygonMode is + ename:VK_POLYGON_MODE_LINE, or if a shader is bound to the + ename:VK_SHADER_STAGE_VERTEX_BIT stage and pname:primitiveTopology is a + line topology, or if a shader which outputs line primitives is bound to + the ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or + ename:VK_SHADER_STAGE_GEOMETRY_BIT stage + * flink:vkCmdSetCullMode + * flink:vkCmdSetFrontFace, if pname:cullMode is not + ename:VK_CULL_MODE_NONE, or if pname:stencilTestEnable is ename:VK_TRUE, + or if the fragment shader uses a variable decorated with + code:FrontFacing + * flink:vkCmdSetDepthTestEnable + * flink:vkCmdSetDepthWriteEnable + * flink:vkCmdSetDepthCompareOp, if pname:depthTestEnable is ename:VK_TRUE + * flink:vkCmdSetDepthBoundsTestEnable, if the <> feature is enabled on the device + * flink:vkCmdSetDepthBounds, if pname:depthBoundsTestEnable is + ename:VK_TRUE + * flink:vkCmdSetDepthBiasEnable + * flink:vkCmdSetDepthBias, pname:depthBiasEnable is ename:VK_TRUE + * flink:vkCmdSetDepthClampEnableEXT, if the <> feature is enabled on the device + * flink:vkCmdSetStencilTestEnable + * flink:vkCmdSetStencilOp, if pname:stencilTestEnable is ename:VK_TRUE + +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, the following commands +must: have been called on the command buffer prior to drawing: + + * flink:vkCmdSetLogicOpEnableEXT, if the <> + feature is enabled on the device + * flink:vkCmdSetLogicOpEXT, if pname:logicOpEnable is ename:VK_TRUE + * flink:vkCmdSetColorBlendEnableEXT, with values set for every color + attachment in the render pass instance active at draw time +ifdef::VK_EXT_blend_operation_advanced[] + * flink:vkCmdSetColorBlendEquationEXT or + flink:vkCmdSetColorBlendAdvancedEXT, +endif::VK_EXT_blend_operation_advanced[] +ifndef::VK_EXT_blend_operation_advanced[] + * flink:vkCmdSetColorBlendEquationEXT, +endif::VK_EXT_blend_operation_advanced[] + for every attachment whose index in pname:pColorBlendEnables points to a + value of ename:VK_TRUE + * flink:vkCmdSetBlendConstants, if any index in pname:pColorBlendEnables + is ename:VK_TRUE, and the same index in pname:pColorBlendEquations is a + sname:VkColorBlendEquationEXT structure with any elink:VkBlendFactor + member with a value of ename:VK_BLEND_FACTOR_CONSTANT_COLOR, + ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR, + ename:VK_BLEND_FACTOR_CONSTANT_ALPHA, or + ename:VK_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA + * flink:vkCmdSetColorWriteMaskEXT + +ifdef::VK_KHR_fragment_shading_rate[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and one or more of the +<>, +<>, or +<> features are enabled on the device, +the following command must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetFragmentShadingRateKHR +endif::VK_KHR_fragment_shading_rate[] + +ifdef::VK_EXT_transform_feedback[] +If a shader is bound to the ename:VK_SHADER_STAGE_GEOMETRY_BIT stage, and +the <> feature is enabled +on the device, the following command must: have been called on the command +buffer prior to drawing: + + * flink:vkCmdSetRasterizationStreamEXT +endif::VK_EXT_transform_feedback[] + +ifdef::VK_EXT_discard_rectangles[] +If the `apiext:VK_EXT_discard_rectangles` extension is enabled on the +device, the following commands must: have been called on the command buffer +prior to drawing: + + * flink:vkCmdSetDiscardRectangleEnableEXT + * flink:vkCmdSetDiscardRectangleModeEXT, if `discardRectangleEnable` is + ename:VK_TRUE + * flink:vkCmdSetDiscardRectangleEXT, if `discardRectangleEnable` is + ename:VK_TRUE +endif::VK_EXT_discard_rectangles[] + +ifdef::VK_EXT_conservative_rasterization[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +`apiext:VK_EXT_conservative_rasterization` extension is enabled on the +device, the following commands must: have been called on the command buffer +prior to drawing: + + * flink:vkCmdSetConservativeRasterizationModeEXT + * flink:vkCmdSetExtraPrimitiveOverestimationSizeEXT, if + pname:conservativeRasterizationMode is + ename:VK_CONSERVATIVE_RASTERIZATION_MODE_OVERESTIMATE_EXT +endif::VK_EXT_conservative_rasterization[] + +ifdef::VK_EXT_depth_clip_enable[] +If the <> feature is +enabled on the device, the following command must: have been called on the +command buffer prior to drawing: + + * flink:vkCmdSetDepthClipEnableEXT +endif::VK_EXT_depth_clip_enable[] + +ifdef::VK_EXT_sample_locations[] +If the `apiext:VK_EXT_sample_locations` extension is enabled on the device, +the following commands must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetSampleLocationsEnableEXT + * flink:vkCmdSetSampleLocationsEXT, if pname:sampleLocationsEnable is + ename:VK_TRUE +endif::VK_EXT_sample_locations[] + +ifdef::VK_EXT_provoking_vertex[] +If the `apiext:VK_EXT_provoking_vertex` extension is enabled on the device, +the following command must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetProvokingVertexModeEXT +endif::VK_EXT_provoking_vertex[] + +ifdef::VK_EXT_line_rasterization[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +`apiext:VK_EXT_line_rasterization` extension is enabled on the device, and +if pname:polygonMode is ename:VK_POLYGON_MODE_LINE or a shader is bound to +the ename:VK_SHADER_STAGE_VERTEX_BIT stage and pname:primitiveTopology is a +line topology or a shader which outputs line primitives is bound to the +ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT or +ename:VK_SHADER_STAGE_GEOMETRY_BIT stage, the following commands must: have +been called on the command buffer prior to drawing: + + * flink:vkCmdSetLineRasterizationModeEXT + * flink:vkCmdSetLineStippleEnableEXT + * flink:vkCmdSetLineStippleEXT, if pname:stippledLineEnable is + ename:VK_TRUE +endif::VK_EXT_line_rasterization[] + +ifdef::VK_EXT_depth_clip_control[] +If the <> feature is +enabled on the device, the following command must: have been called on the +command buffer prior to drawing: + + * flink:vkCmdSetDepthClipNegativeOneToOneEXT +endif::VK_EXT_depth_clip_control[] + +ifdef::VK_EXT_color_write_enable[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +<> feature is enabled on +the device, the following command must: have been called on the command +buffer prior to drawing: + + * flink:vkCmdSetColorWriteEnableEXT, with values set for every color + attachment in the render pass instance active at draw time +endif::VK_EXT_color_write_enable[] + +ifdef::VK_NV_clip_space_w_scaling[] +If the `apiext:VK_NV_clip_space_w_scaling` extension is enabled on the +device, the following commands must: have been called on the command buffer +prior to drawing: + + * flink:vkCmdSetViewportWScalingEnableNV + * flink:vkCmdSetViewportWScalingNV, if pname:viewportWScalingEnable is + ename:VK_TRUE +endif::VK_NV_clip_space_w_scaling[] + +ifdef::VK_NV_viewport_swizzle[] +If the `apiext:VK_NV_viewport_swizzle` extension is enabled on the device, +the following command must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetViewportSwizzleNV +endif::VK_NV_viewport_swizzle[] + +ifdef::VK_NV_fragment_coverage_to_color[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +`apiext:VK_NV_fragment_coverage_to_color` extension is enabled on the +device, the following commands must: have been called on the command buffer +prior to drawing: + + * flink:vkCmdSetCoverageToColorEnableNV + * flink:vkCmdSetCoverageToColorLocationNV, if pname:coverageToColorEnable + is ename:VK_TRUE +endif::VK_NV_fragment_coverage_to_color[] + +ifdef::VK_NV_framebuffer_mixed_samples[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +`apiext:VK_NV_framebuffer_mixed_samples` extension is enabled on the device, +the following commands must: have been called on the command buffer prior to +drawing: + + * flink:vkCmdSetCoverageModulationModeNV + * flink:vkCmdSetCoverageModulationTableEnableNV, if + pname:coverageModulationMode is not + ename:VK_COVERAGE_MODULATION_MODE_NONE_NV + * flink:vkCmdSetCoverageModulationTableNV, if + pname:coverageModulationTableEnable is ename:VK_TRUE +endif::VK_NV_framebuffer_mixed_samples[] + +ifdef::VK_NV_coverage_reduction_mode[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +<> feature is +enabled on the device, the following command must: have been called on the +command buffer prior to drawing: + + * flink:vkCmdSetCoverageReductionModeNV +endif::VK_NV_coverage_reduction_mode[] + +ifdef::VK_NV_representative_fragment_test[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +<> +feature is enabled on the device, the following command must: have been +called on the command buffer prior to drawing: + + * flink:vkCmdSetRepresentativeFragmentTestEnableNV +endif::VK_NV_representative_fragment_test[] + +ifdef::VK_NV_shading_rate_image[] +If a shader is bound to the ename:VK_SHADER_STAGE_FRAGMENT_BIT stage, and +pname:rasterizerDiscardEnable is ename:VK_FALSE, and the +<> feature is enabled on +the device, the following commands must: have been called on the command +buffer prior to drawing: + + * flink:vkCmdSetCoarseSampleOrderNV + * flink:vkCmdSetShadingRateImageEnableNV + * flink:vkCmdSetViewportShadingRatePaletteNV, if + pname:shadingRateImageEnable is ename:VK_TRUE +endif::VK_NV_shading_rate_image[] + +ifdef::VK_NV_scissor_exclusive[] +If the <> feature is +enabled on the device, the following commands must: have been called on the +command buffer prior to drawing: + + * flink:vkCmdSetExclusiveScissorEnableNV + * flink:vkCmdSetExclusiveScissorNV, if any value in + pname:pExclusiveScissorEnables is ename:VK_TRUE +endif::VK_NV_scissor_exclusive[] + +State can: be set either at any time before or after shader objects are +bound, but all required state must: be set prior to issuing drawing +commands. + +[[shaders-objects-pipeline-interaction]] +=== Interaction with Pipelines + +Calling fname:vkCmdBindShadersEXT causes the pipeline bind points +corresponding to each stage in pname:pStages to be disturbed, meaning that +any <> that had previously been bound to those +pipeline bind points are no longer bound. + +The following table describes the relationship between shader stages and +pipeline bind points: + +[cols="1,1"] +|==== +|Shader stage |Pipeline bind point + +a| * ename:VK_SHADER_STAGE_VERTEX_BIT + * ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT + * ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT + * ename:VK_SHADER_STAGE_GEOMETRY_BIT + * ename:VK_SHADER_STAGE_FRAGMENT_BIT +ifdef::VK_EXT_mesh_shader[] + * ename:VK_SHADER_STAGE_TASK_BIT_EXT + * ename:VK_SHADER_STAGE_MESH_BIT_EXT +endif::VK_EXT_mesh_shader[] +ifndef::VK_EXT_mesh_shader[] +ifdef::VK_NV_mesh_shader[] + * ename:VK_SHADER_STAGE_TASK_BIT_NV + * ename:VK_SHADER_STAGE_MESH_BIT_NV +endif::VK_NV_mesh_shader[] +endif::VK_EXT_mesh_shader[] +| ename:VK_PIPELINE_BIND_POINT_GRAPHICS + +a| * ename:VK_SHADER_STAGE_COMPUTE_BIT +| ename:VK_PIPELINE_BIND_POINT_COMPUTE +|==== + +If ename:VK_PIPELINE_BIND_POINT_GRAPHICS is disturbed (i.e., if +pname:pStages contains any graphics stage), any graphics pipeline state that +the previously bound pipeline did not specify as <> becomes undefined:, and must: be set on the command buffer before +issuing drawing commands using shader objects. + +Calls to fname:vkCmdBindPipeline likewise disturb the shader stage(s) +corresponding to pname:pipelineBindPoint, meaning that any shaders that had +previously been bound to any of those stages are no longer bound, even if +the pipeline was created without shaders for some of those stages. + +[[shaders-objects-destruction]] +=== Shader Object Destruction + +[open,refpage='vkDestroyShaderEXT',desc='Destroy a shader object',type='protos'] +-- +To destroy a shader object, call: + +include::{generated}/api/protos/vkDestroyShaderEXT.adoc[] + + * pname:device is the logical device that destroys the shader object. + * pname:shader is the handle of the shader object to destroy. + * pname:pAllocator controls host memory allocation as described in the + <> chapter. + +Destroying a shader object used by one or more command buffers in the +<> causes those +command buffers to move into the _invalid state_. + +.Valid Usage +**** + * [[VUID-vkDestroyShaderEXT-None-08481]] + The <> feature must: be enabled + * [[VUID-vkDestroyShaderEXT-shader-08482]] + All submitted commands that refer to pname:shader must: have completed + execution + * [[VUID-vkDestroyShaderEXT-pAllocator-08483]] + If sname:VkAllocationCallbacks were provided when pname:shader was + created, a compatible set of callbacks must: be provided here + * [[VUID-vkDestroyShaderEXT-pAllocator-08484]] + If no sname:VkAllocationCallbacks were provided when pname:shader was + created, pname:pAllocator must: be `NULL` +**** + +include::{generated}/validity/protos/vkDestroyShaderEXT.adoc[] +-- + +endif::VK_EXT_shader_object[] + [[shader-modules]] == Shader Modules @@ -729,7 +1937,7 @@ and its associated data, and can: also output additional per-patch data. The input patch is sized according to the pname:patchControlPoints member of slink:VkPipelineTessellationStateCreateInfo, as part of input assembly. -ifdef::VK_EXT_extended_dynamic_state2[] +ifdef::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] The input patch can also be dynamically sized with pname:patchControlPoints parameter of flink:vkCmdSetPatchControlPointsEXT. @@ -746,18 +1954,41 @@ include::{generated}/api/protos/vkCmdSetPatchControlPointsEXT.adoc[] patch. This command sets the number of control points per patch for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state2[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state2[] Otherwise, this state is specified by the slink:VkPipelineTessellationStateCreateInfo::pname:patchControlPoints value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetPatchControlPointsEXT-None-08574]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +ifndef::VK_EXT_extended_dynamic_state2[] + * [[VUID-vkCmdSetPatchControlPointsEXT-None-08575]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetPatchControlPointsEXT-None-04873]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetPatchControlPointsEXT-patchControlPoints-04874]] pname:patchControlPoints must: be greater than zero and less than or equal to sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize @@ -765,7 +1996,7 @@ used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetPatchControlPointsEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state2[] +endif::VK_EXT_extended_dynamic_state2,VK_EXT_shader_object[] The size of the output patch is controlled by the code:OpExecutionMode code:OutputVertices specified in the tessellation control or tessellation @@ -1097,11 +2328,8 @@ instruction, which results in a pointer code:x to that object. A specific entry point in a SPIR-V module is said to _statically use_ that object if that entry point's call tree contains a function containing a instruction with code:x as an code:id operand. - -Static use is not used to control the behavior of variables with code:Input -and code:Output storage. -The effects of those variables are applied based only on whether they are -present in a shader entry point's interface. +A shader entry point also _statically uses_ any variables explicitly +declared in its interface. [[shaders-scope]] diff --git a/chapters/synchronization.adoc b/chapters/synchronization.adoc index 7a1c1df191..3f9bc5dccb 100644 --- a/chapters/synchronization.adoc +++ b/chapters/synchronization.adoc @@ -1177,8 +1177,14 @@ ifdef::VK_EXT_blend_operation_advanced[] <> (other than <>), endif::VK_EXT_blend_operation_advanced[] - <>, or certain + <>, or via certain +ifndef::VK_EXT_shader_tile_image[] <>. +endif::VK_EXT_shader_tile_image[] +ifdef::VK_EXT_shader_tile_image[] + <> or + <>. +endif::VK_EXT_shader_tile_image[] Such access occurs in the ename:VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage. * ename:VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a @@ -1200,6 +1206,19 @@ endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT or ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT pipeline stages. * ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT specifies write + <> in the + ename:VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT_KHR or + ename:VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT_KHR pipeline stages or + via certain +ifndef::VK_EXT_shader_tile_image[] + <> +endif::VK_EXT_shader_tile_image[] +ifdef::VK_EXT_shader_tile_image[] + <> or + <> +endif::VK_EXT_shader_tile_image[] + in the ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR pipeline stage. + * ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT_KHR specifies write access to a <>, via <> or certain <>. @@ -5612,8 +5631,14 @@ that occurred later in <>. If fname:vkCmdPipelineBarrier2 is recorded within a render pass instance, -the synchronization scopes are limited to operations within the same -subpass. +the synchronization scopes are limited to operations within the same subpass +ifdef::VK_EXT_shader_tile_image[] +, or must: follow the restrictions for +<> if the render pass instance was started with +flink:vkCmdBeginRendering +endif::VK_EXT_shader_tile_image[] +. .Valid Usage **** @@ -5796,6 +5821,48 @@ elink:VkDependencyFlagBits. -- +ifdef::VK_EXT_shader_tile_image[] +[[synchronization-pipeline-barriers-explicit-renderpass-tileimage]] +=== Explicit Render Pass Tile Image Access Synchronization + +A fragment shader can: declare code:NonCoherentColorAttachmentReadEXT, +code:NonCoherentDepthAttachmentReadEXT, or +code:NonCoherentStencilAttachmentReadEXT execution modes to enable +non-coherent tile image reads for color, depth, or stencil, respectively. +When non-coherent tile image reads are enabled, writes via color, depth and +stencil attachments are not automatically made visible to the corresponding +attachment reads via tile images. +For the writes to be made visible, an explicit memory dependency must: be +inserted between when the attachment is written to and when it is read from +by later fragments. +Such memory dependencies must: be inserted every time a fragment will read +values at a particular sample (x, y, layer, sample) coordinate, if those +values have been written since the most recent pipeline barrier; or since +the start of the render pass instance, if there have been no pipeline +barriers since the start of the render pass instance. +When such memory dependencies are used the values at all sample locations +inside the fragment area are made visible, regardless of coverage. + +To insert a memory dependency for explicit renderpass tile image +synchronization, call flink:vkCmdPipelineBarrier2 inside a render pass +instance started with flink:vkCmdBeginRendering. +The following restrictions apply for such pipeline barriers: + + * pname:dependencyFlags must: include ename:VK_DEPENDENCY_BY_REGION_BIT. + * The pipeline barriers can: only include memory barriers. + That is, buffer memory barriers and image memory barriers must: not be + used. + * The stages in slink:VkMemoryBarrier2::srcStageMask and + slink:VkMemoryBarrier2::dstStageMask are restricted to framebuffer space + stages. + * The access types in slink:VkMemoryBarrier2::srcAccessMask and + slink:VkMemoryBarrier2::dstAccessMask are restricted to the following + types: ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, + ename:VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, + ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT, and + ename:VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. +endif::VK_EXT_shader_tile_image[] + [[synchronization-memory-barriers]] == Memory Barriers diff --git a/chapters/tessellation.adoc b/chapters/tessellation.adoc index cbfa12556a..b3494c3d67 100644 --- a/chapters/tessellation.adoc +++ b/chapters/tessellation.adoc @@ -33,19 +33,44 @@ If no tessellation shaders are present in the pipeline, the tessellator is disabled and incoming primitives are passed through without modification. The type of subdivision performed by the tessellator is specified by an -code:OpExecutionMode instruction in the tessellation evaluation or -tessellation control shader using one of execution modes code:Triangles, -code:Quads, and code:IsoLines. -Other tessellation-related execution modes can: also be specified in either -the tessellation control or tessellation evaluation shaders, and if they are -specified in both then the modes must: be the same. +code:OpExecutionMode instruction using one of the code:Triangles, +code:Quads, or code:IsoLines execution modes. +ifdef::VK_EXT_shader_object[] +When using <>, this instruction must: be +specified in the tessellation evaluation shader, and may: also be specified +in the tessellation control shader. +When using pipelines, this +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[This] +instruction may: be specified in either the tessellation evaluation or +tessellation control shader. +ifdef::VK_EXT_shader_object[] +When using shader objects, tessellation-related modes that are required: +must: be specified in the tessellation evaluation shader, and may: also be +specified in the tessellation control shader. +Other tessellation-related modes may: be specified in the tessellation +evaluation shader. +When using pipelines, other +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[Other] +tessellation-related execution modes can: also be specified in either the +tessellation control or tessellation evaluation shaders. + +Any tessellation-related modes specified in both the tessellation control +and tessellation evaluation shaders must: be the same. Tessellation execution modes include: * code:Triangles, code:Quads, and code:IsoLines. These control the type of subdivision and topology of the output primitives. - One mode must: be set in at least one of the tessellation shader stages. +ifdef::VK_EXT_shader_object[] + When using <>, one mode must: be set in + at least the tessellation evaluation stage. + When using pipelines, one +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[One] + mode must: be set in at least one of the tessellation shader stages. ifdef::VK_KHR_portability_subset[] If the `apiext:VK_KHR_portability_subset` extension is enabled, and slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:tessellationIsolines @@ -55,11 +80,22 @@ ifdef::VK_KHR_portability_subset[] endif::VK_KHR_portability_subset[] * code:VertexOrderCw and code:VertexOrderCcw. These control the orientation of triangles generated by the tessellator. - One mode must: be set in at least one of the tessellation shader stages. +ifdef::VK_EXT_shader_object[] + When using <>, one mode must: be set in + at least the tessellation evaluation stage. + When using pipelines, one +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[One] + mode must: be set in at least one of the tessellation shader stages. * code:PointMode. Controls generation of points rather than triangles or lines. This functionality defaults to disabled, and is enabled if either shader stage includes the execution mode. +ifdef::VK_EXT_shader_object[] + When using <>, if code:PointMode is set + in the tessellation control stage, it must: be identically set in the + tesselation evaluation stage. +endif::VK_EXT_shader_object[] ifdef::VK_KHR_portability_subset[] If the `apiext:VK_KHR_portability_subset` extension is enabled, and slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:tessellationPointMode @@ -70,12 +106,23 @@ endif::VK_KHR_portability_subset[] * code:SpacingEqual, code:SpacingFractionalEven, and code:SpacingFractionalOdd. Controls the spacing of segments on the edges of tessellated primitives. - One mode must: be set in at least one of the tessellation shader stages. +ifdef::VK_EXT_shader_object[] + When using <>, one mode must: be set in + at least the tessellation evaluation stage. + When using pipelines, one +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[One] + mode must: be set in at least one of the tessellation shader stages. * code:OutputVertices. Controls the size of the output patch of the tessellation control shader. - One value must: be set in at least one of the tessellation shader - stages. +ifdef::VK_EXT_shader_object[] + When using <>, one value must: be set + in at least the tessellation evaluation stage. + When using pipelines, one +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[One] + value must: be set in at least one of the tessellation shader stages. For triangles, the tessellator subdivides a triangle primitive into smaller triangles. @@ -629,7 +676,7 @@ relative to the orientation of the domain. -- endif::VK_VERSION_1_1,VK_KHR_maintenance2[] -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetTessellationDomainOriginEXT',desc='Specify the origin of the tessellation domain space dynamically for a command buffer',type='protos'] -- @@ -644,22 +691,45 @@ include::{generated}/api/protos/vkCmdSetTessellationDomainOriginEXT.adoc[] space. This command sets the origin of the tessellation domain space for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_TESSELLATION_DOMAIN_ORIGIN_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineTessellationDomainOriginStateCreateInfo::pname:domainOrigin value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetTessellationDomainOriginEXT-None-08576]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetTessellationDomainOriginEXT-None-08577]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetTessellationDomainOriginEXT-extendedDynamicState3TessellationDomainOrigin-07444]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetTessellationDomainOriginEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] diff --git a/chapters/vertexpostproc.adoc b/chapters/vertexpostproc.adoc index 3ec07c6614..3ef8964661 100644 --- a/chapters/vertexpostproc.adoc +++ b/chapters/vertexpostproc.adoc @@ -480,7 +480,7 @@ this structure to the pname:pNext chain of a sname:VkPipelineViewportStateCreateInfo structure and setting the graphics pipeline state with flink:vkCreateGraphicsPipelines. -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetViewportSwizzleNV',desc='Specify the viewport swizzle state dynamically for a command buffer',type='protos'] -- @@ -499,9 +499,15 @@ include::{generated}/api/protos/vkCmdSetViewportSwizzleNV.adoc[] slink:VkViewportSwizzleNV structures specifying viewport swizzles. This command sets the viewport swizzle state for subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_SWIZZLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineViewportSwizzleStateCreateInfoNV::pname:viewportCount, and slink:VkPipelineViewportSwizzleStateCreateInfoNV::pname:pViewportSwizzles @@ -509,15 +515,31 @@ values used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetViewportSwizzleNV-None-08578]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetViewportSwizzleNV-None-08579]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetViewportSwizzleNV-extendedDynamicState3ViewportSwizzle-07445]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] **** include::{generated}/validity/protos/vkCmdSetViewportSwizzleNV.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] Each viewport specified from 0 to pname:viewportCount - 1 has its x,y,z,w swizzle state set to the corresponding pname:x, pname:y, pname:z and pname:w @@ -692,7 +714,7 @@ These modes are described more precisely in <>. -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetProvokingVertexModeEXT',desc='Specify the provoking vertex mode dynamically for a command buffer',type='protos'] -- @@ -706,19 +728,42 @@ include::{generated}/api/protos/vkCmdSetProvokingVertexModeEXT.adoc[] * pname:provokingVertexMode specifies the pname:provokingVertexMode state. This command sets the pname:provokingVertexMode state for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_PROVOKING_VERTEX_MODE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetProvokingVertexModeEXT-None-08580]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetProvokingVertexModeEXT-None-08581]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetProvokingVertexModeEXT-extendedDynamicState3ProvokingVertexMode-07446]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetProvokingVertexModeEXT-provokingVertexMode-07447]] If pname:provokingVertexMode is ename:VK_PROVOKING_VERTEX_MODE_LAST_VERTEX_EXT, then the @@ -729,7 +774,7 @@ value used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetProvokingVertexModeEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_EXT_provoking_vertex[] @@ -816,7 +861,7 @@ of the slink:VkPipelineRasterizationStateCreateInfo structure. Depth clipping is disabled when pname:depthClampEnable is ename:VK_TRUE. endif::VK_EXT_depth_clip_enable[] -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthClampEnableEXT',desc='Specify dynamically whether depth clamping is enabled in the command buffer',type='protos'] -- @@ -830,9 +875,16 @@ include::{generated}/api/protos/vkCmdSetDepthClampEnableEXT.adoc[] * pname:depthClampEnable specifies whether depth clamping is enabled. This command sets whether depth clamping is enabled or disabled for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_CLAMP_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable value used to create the currently active pipeline. @@ -843,9 +895,25 @@ depth clipping is enabled when depth clamping is disabled and vice versa. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClampEnableEXT-None-08582]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClampEnableEXT-None-08583]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClampEnableEXT-extendedDynamicState3DepthClampEnable-07448]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClampEnableEXT-depthClamp-07449]] If the <> feature is not enabled, pname:depthClampEnable must be ename:VK_FALSE @@ -867,9 +935,16 @@ include::{generated}/api/protos/vkCmdSetDepthClipEnableEXT.adoc[] * pname:depthClipEnable specifies whether depth clipping is enabled. This command sets whether depth clipping is enabled or disabled for -subsequent drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_CLIP_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRasterizationDepthClipStateCreateInfoEXT::pname:depthClipEnable value used to create the currently active pipeline, or is set to the inverse @@ -878,9 +953,25 @@ sname:VkPipelineRasterizationDepthClipStateCreateInfoEXT is not specified. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClipEnableEXT-None-08584]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClipEnableEXT-None-08585]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClipEnableEXT-extendedDynamicState3DepthClipEnable-07450]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClipEnableEXT-depthClipEnable-07451]] The <> feature must: be enabled @@ -890,7 +981,7 @@ include::{generated}/validity/protos/vkCmdSetDepthClipEnableEXT.adoc[] -- endif::VK_EXT_depth_clip_enable[] -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] When depth clipping is disabled, the plane equation @@ -997,7 +1088,7 @@ include::{generated}/api/structs/VkPipelineViewportDepthClipControlCreateInfoEXT include::{generated}/validity/structs/VkPipelineViewportDepthClipControlCreateInfoEXT.adoc[] -- -ifdef::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthClipNegativeOneToOneEXT',desc='Specify the negative one to one depth clip mode dynamically for a command buffer',type='protos'] -- To <> pname:negativeOneToOne, @@ -1010,19 +1101,42 @@ include::{generated}/api/protos/vkCmdSetDepthClipNegativeOneToOneEXT.adoc[] * pname:negativeOneToOne specifies the pname:negativeOneToOne state. This command sets the pname:negativeOneToOne state for subsequent drawing -commands when the graphics pipeline is created with +commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] +ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_CLIP_NEGATIVE_ONE_TO_ONE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineViewportDepthClipControlCreateInfoEXT::pname:negativeOneToOne value used to create the currently active pipeline. .Valid Usage **** +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClipNegativeOneToOneEXT-None-08586]] + Either the <> feature or the + <> feature or both must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-vkCmdSetDepthClipNegativeOneToOneEXT-None-08587]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClipNegativeOneToOneEXT-extendedDynamicState3DepthClipNegativeOneToOne-07452]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] * [[VUID-vkCmdSetDepthClipNegativeOneToOneEXT-depthClipControl-07453]] The <> feature must: be enabled @@ -1030,7 +1144,7 @@ value used to create the currently active pipeline. include::{generated}/validity/protos/vkCmdSetDepthClipNegativeOneToOneEXT.adoc[] -- -endif::VK_EXT_extended_dynamic_state3[] +endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_EXT_depth_clip_control[] @@ -1346,7 +1460,7 @@ endif::VK_NV_clip_space_w_scaling[] include::{generated}/validity/structs/VkPipelineViewportStateCreateInfo.adoc[] -- -ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetViewportWithCount',desc='Set the viewport count and viewports dynamically for a command buffer',type='protos',alias='vkCmdSetViewportWithCountEXT'] -- To <> the viewport count and @@ -1354,13 +1468,13 @@ viewports, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetViewportWithCount.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetViewportWithCountEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -1368,9 +1482,16 @@ endif::VK_EXT_extended_dynamic_state[] * pname:pViewports specifies the viewports to use for drawing. This command sets the viewport count and viewports state for subsequent -drawing commands when the graphics pipeline is created with +drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the corresponding slink:VkPipelineViewportStateCreateInfo::pname:viewportCount and pname:pViewports values used to create the currently active pipeline. @@ -1378,9 +1499,24 @@ pname:pViewports values used to create the currently active pipeline. .Valid Usage **** ifndef::VK_VERSION_1_3[] +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetViewportWithCount-None-08588]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetViewportWithCount-None-08589]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetViewportWithCount-None-03393]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_3[] * [[VUID-vkCmdSetViewportWithCount-viewportCount-03394]] pname:viewportCount must: be between `1` and @@ -1406,13 +1542,13 @@ scissor rectangular bounds, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetScissorWithCount.adoc[] -endif::VK_VERSION_1_3[] -ifdef::VK_VERSION_1_3+VK_EXT_extended_dynamic_state[or the equivalent command] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] +endif::VK_VERSION_1_3[] -ifdef::VK_EXT_extended_dynamic_state[] +ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetScissorWithCountEXT.adoc[] -endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. @@ -1420,9 +1556,16 @@ endif::VK_EXT_extended_dynamic_state[] * pname:pScissors specifies the scissors to use for drawing. This command sets the scissor count and scissor rectangular bounds state for -subsequence drawing commands when the graphics pipeline is created with +subsequent drawing commands +ifdef::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] +ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] +endif::VK_EXT_shader_object[] +ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the corresponding slink:VkPipelineViewportStateCreateInfo::pname:scissorCount and pname:pScissors values used to create the currently active pipeline. @@ -1430,9 +1573,24 @@ pname:pScissors values used to create the currently active pipeline. .Valid Usage **** ifndef::VK_VERSION_1_3[] +ifdef::VK_EXT_shader_object[] +ifdef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetScissorWithCount-None-08590]] + Either the <> + feature or the <> feature or + both must: be enabled +endif::VK_EXT_extended_dynamic_state[] +ifndef::VK_EXT_extended_dynamic_state[] + * [[VUID-vkCmdSetScissorWithCount-None-08591]] + The <> feature must: be + enabled +endif::VK_EXT_extended_dynamic_state[] +endif::VK_EXT_shader_object[] +ifndef::VK_EXT_shader_object[] * [[VUID-vkCmdSetScissorWithCount-None-03396]] The <> feature must: be enabled +endif::VK_EXT_shader_object[] endif::VK_VERSION_1_3[] * [[VUID-vkCmdSetScissorWithCount-scissorCount-03397]] pname:scissorCount must: be between `1` and @@ -1461,7 +1619,7 @@ endif::VK_NV_inherited_viewport_scissor[] include::{generated}/validity/protos/vkCmdSetScissorWithCount.adoc[] -- -endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] +endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='VkPipelineViewportStateCreateFlags',desc='Reserved for future use',type='flags'] -- @@ -1554,9 +1712,10 @@ include::{generated}/api/protos/vkCmdSetViewport.adoc[] specifying viewport parameters. This command sets the viewport transformation parameters state for -subsequent drawing commands when the graphics pipeline is created with -ename:VK_DYNAMIC_STATE_VIEWPORT set in -slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. +subsequent drawing commands +ifdef::VK_EXT_shader_object[when drawing using <>, or] +when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_VIEWPORT +set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the sname:VkPipelineViewportStateCreateInfo::pname:pViewports values used to create the currently active pipeline. diff --git a/config/makeSubmit.py b/config/makeSubmit.py index 9dae43f0e7..54273a0ad1 100755 --- a/config/makeSubmit.py +++ b/config/makeSubmit.py @@ -14,34 +14,33 @@ import argparse, copy, io, os, pdb, re, string, subprocess, sys -def enQuote(str): - return '"' + str + '"' - # Make a single submission target. Several are needed per document. # # outDir - where to generate intermediate and final documents -# extensionList - list of extensions to include +# extensions - list of extensions to include # submitName - base name of final HTML file # title - document title # target - default 'html' -def makeTarget(outDir, extensionList, submitName, title, target): +def makeTarget(outDir, extensions, submitName, title, target): + ws = ' ' + print('make clean_generated') - print('make OUTDIR=' + outDir, + print('make', + f'OUTDIR="{outDir}"', 'IMAGEOPTS=', - 'EXTENSIONS="' + ' '.join(extensionList) + '"', - 'APITITLE="' + title + '"', target) + f'EXTENSIONS="{ws.join(sorted(extensions))}"', + f'APITITLE="{title}"', + target) # Rename into submission directory - outFile = outDir + '/html/' + submitName + '.html' - outFile = outFile.replace(' ', '_') - print('mv', outDir + '/html/vkspec.html', enQuote(outFile)) - # No longer needed - # print('mv -n', outDir + '/katex', 'out/submit/') + outFile = f'{outDir}/html/{submitName}.html'.replace(' ', '_') + print('mv', f'"{outDir}/html/vkspec.html"', f'"{outFile}"') return outFile # Make submission for a list of required extension names -def makeSubmit(submitName, required, apideps, target='html'): - """submitName - the base document title, usually the name of the +def makeSubmit(outDir, submitName, required, apideps, target='html'): + """outDir - path to output directory for generated specs. + submitName - the base document title, usually the name of the extension being submitted unless there is more than one of them. required - a list of one or more extension names comprising the submission. @@ -63,7 +62,6 @@ def makeSubmit(submitName, required, apideps, target='html'): print('') # Generate shell commands to build the specs - outDir = 'submit' print('mkdir -p', outDir) # Generate spec with required extensions + dependencies @@ -79,10 +77,10 @@ def makeSubmit(submitName, required, apideps, target='html'): print('') print('cd scripts/htmldiff') print('./htmldiff', - enQuote('../../' + baseSpec), - enQuote('../../' + newSpec), + f'"{baseSpec}"', + f'"{newSpec}"', '>', - enQuote('../../submit/html/diff-' + submitName + '.html')) + f'"{outDir}/html/diff-{submitName}.html"') print('cd ../../') if __name__ == '__main__': @@ -94,7 +92,9 @@ def makeSubmit(submitName, required, apideps, target='html'): parser.add_argument('-title', action='store', default='vkspec-tmp', help='Set the document title') - + parser.add_argument('-outdir', action='store', + default='submit', + help='Path to generated specs') parser.add_argument('-registry', action='store', default=None, help='Path to API XML registry file specifying version and extension dependencies') @@ -112,4 +112,5 @@ def makeSubmit(submitName, required, apideps, target='html'): apideps = ApiDependencies(results.registry, results.apiname) - makeSubmit(results.title, results.extension, apideps) + results.outdir = os.path.abspath(results.outdir) + makeSubmit(results.outdir, results.title, results.extension, apideps) diff --git a/images/tile_image.svg b/images/tile_image.svg new file mode 100644 index 0000000000..9ae9fc0b75 --- /dev/null +++ b/images/tile_image.svg @@ -0,0 +1,11051 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Framebuffer + Tile Image + Pixel + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/proposals/VK_EXT_shader_object.adoc b/proposals/VK_EXT_shader_object.adoc new file mode 100644 index 0000000000..91cd2498bf --- /dev/null +++ b/proposals/VK_EXT_shader_object.adoc @@ -0,0 +1,699 @@ +// Copyright 2023 The Khronos Group, Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_EXT_shader_object +:toc: left +:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/ +:sectnums: + +This document describes the proposed design for a new extension which aims to comprehensively address problems the pipeline abstraction has created for both applications and implementations. + +== Problem Statement + +When Vulkan 1.0 and its precursor Mantle were originally developed the then-existing shader and state binding models of earlier APIs were beginning to show worrying limitations, both in terms of draw call scaling and driver complexity needed to support them. Application developers were being artificially constrained from accessing the full capabilities of GPUs, and many IHVs were forced to maintain rat's nests of driver code full of heavy-handed draw time state validation and hacky shader patching, all in the service of simplicity at the API level. IHVs were understandably highly motivated to move away from such API designs. + +Enter the new low-level APIs like Mantle and ultimately Vulkan. These APIs set out to reduce driver overhead by exposing lower-level abstractions that would hopefully avoid the need for the draw time state validation and shader patching that was so problematic for IHVs, and so detrimental to performance for applications. + +One of the most significant changes to this end was the new concept of pipelines, which promised to shift the burden of the shader state combinatorics out of drivers and into applications, ideally avoiding the need for driver-side draw time state validation and shader patching entirely. The thinking went that application developers would design or redesign their renderers with pipelines in mind, and in so doing they would naturally learn to accomplish their goals with fewer combinations of state. + +Implicit in such a design was an assumption that applications would be able to know and provide nearly all of this state upfront. A very limited set of dynamic states was specified for the few pieces of state that had effectively unbounded ranges of values, but otherwise even state that could have been fully dynamic on all implementations was required to be baked into the static pipeline objects. This, the thinking went, would benefit even those implementations where the state was internally dynamic by enabling new possibilities for optimization during shader compilation. + +Also implicit in the design of pipelines was an assumption that the driver overhead of the pipeline abstraction would either be negligible, or that it would at least always be outweighed by the performance savings at draw time when compared to earlier APIs. The possibility that either setting dozens of individual pieces of state each time a pipeline is bound or tracking which of those dozens of pieces of state had changed since the previous pipeline bind might cause some implementations to exhibit problematically high overhead at pipeline bind time does not seem to have been a central consideration. + +Many of these assumptions have since proven to be unrealistic. + +On the application side, many developers considering or implementing Vulkan and similar APIs found them unable to efficiently support important use cases which were easily supportable in earlier APIs. This has not been simply a matter of developers being stuck in an old way of thinking or unwilling to "rein in" an unnecessarily large number of state combinations, but a reflection of the reality that the natural design patterns of the most demanding class of applications which use graphics APIs -- video games -- are inherently and deeply dependent on the very "dynamism" that pipelines set out to constrain. + +As a result, renderers with a choice of API have largely chosen to avoid Vulkan and its "pipelined" contemporaries, while those without a choice have largely just devised workarounds to make these new APIs behave like the old ones -- usually in the form of the now nearly ubiquitous hash-n-cache pattern. These applications set various pieces of "pipeline" state independently, then hash it all at draw time and use the hash as a key into an application-managed pipeline cache, reusing an existing pipeline if it exists or creating and caching a new one if it does not. In effect, the messy and inefficient parts of GL drivers that pipelines sought to eliminate have simply moved into applications, except without the benefits of implementation specific knowledge which might have reduced their complexity or improved their performance. + +This is not just a problem of "legacy" application code where it might be viable for the API to wait it out until application codebases are rewritten or replaced. Applications need the features they need, and are unlikely to remove features they need just to satisfy what they know to be artificial limitations imposed by a graphics API's made-up abstraction. This is especially true for developers working on platforms where the pipeline API does not offer substantial performance benefits over other APIs that do not share the same limitations. + +On the driver side, pipelines have provided some of their desired benefits for some implementations, but for others they have largely just shifted draw time overhead to pipeline bind time (while in some cases still not entirely eliminating the draw time overhead in the first place). Implementations where nearly all "pipeline" state is internally dynamic are forced to either redundantly re-bind all of this state each time a pipeline is bound, or to track what state has changed from pipeline to pipeline -- either of which creates considerable overhead on CPU-constrained platforms. + +For certain implementations, the pipeline abstraction has also locked away a significant amount of the flexibility supported by their hardware, thereby paradoxically leaving many of their capabilities inaccessible in the newer and ostensibly "low level" API, though still accessible through older, high level ones. In effect, this is a return to the old problem of the graphics API artificially constraining applications from accessing the full capabilities of the GPU, only on a different axis. + +Finally, on fixed hardware platforms like game consoles and embedded systems pipelines have created some additional and unique challenges. These platforms tend to have limited CPU performance, memory, and storage capacity all at the same time. Because of this it is generally not desirable for applications on these platforms to waste storage space shipping both uncompiled SPIR-V and precompiled pipeline caches, however it is also not desirable to compile the same shaders from scratch on each system (even if they could be cached for subsequent runs). Also, the hardware and even driver versions on these systems are typically known in advance, and drivers might only ever change in tandem with applications. Vulkan applications on these systems are forced to waste precious storage space on not only shipping both SPIR-V and pipeline cached versions of their shaders, but on their pipeline caches containing potentially large numbers of slightly differently optimized permutations of the same shader code, with only minor differences in pipeline state (arguably this last point is a compression problem, but opaque pipeline caches mostly leave applications at the mercy of the driver to solve it for them). + +Fortunately, some of these problems have been acknowledged and various efforts have already begun to address several of them. + +These existing efforts have mainly chosen to tackle problems through the lens of existing hash-n-cache type application architectures, and have focused on those problems which are most acute at pipeline compile time. Their goals have included things like reducing pipeline counts, improving the usability and efficiency of pipeline caches, and introducing more granularity to the pipeline compilation and caching process. The extensions they have produced have preferred a targeted, piecemeal, and minimally invasive "band-aid" approach over a more holistic "rip off the band-aid" redesign. + +Such efforts have undoubtedly produced valuable improvements, but they have left the class of problems which manifest at bind time largely unaddressed. It might be possible to continue the existing piecemeal approach with a refocus onto bind time, but the solution space afforded by this kind of approach would necessarily remain constrained by the design decisions of the past. + +== Solution Space + +Several approaches are immediately apparent: + + . Extend the existing graphics pipeline library concept somehow, perhaps by adding optional new, more granular library types and/or making pipeline binaries directly bindable without needing to be explicitly linked into a pipeline object + . Continue to expose more (maybe optional) dynamic state to minimize the number of pipeline objects needed + . Abandon pipelines entirely and introduce new functionality to compile and bind shaders directly + +Option 1 is a natural extension of recent efforts and requires relatively few API changes, but it adds even more complexity to the already very complex pipeline concept, while also failing to adequately address significant parts of the problem. While directly bindable pipeline libraries do reduce the dimensionality of pipeline combinatorics, they do not provide any meaningful absolute CPU performance improvement at pipeline bind time. The total overhead of binding N different pipeline libraries is still roughly on par with the overhead of binding a single (monolithic or linked) pipeline. + +Option 2 also requires relatively few API changes and would do more to address bind time CPU performance than option 1, but this option is limited in both the class of issues it can address and its portability across implementations. Much of the universally supportable "low hanging fruit" dynamic state has already been exposed by the existing extended dynamic state extensions, and the remaining state is mostly not universally dynamic. Exposing states A and B as dynamic on one implementation and states B and C on another is still valuable, but it limits this approach's benefits for simplifying application architectures. Even though this option is not a complete solution, it can and should be pursued in parallel with other efforts -- both for its own sake and as a potential foundation for more a comprehensive solution. + +Option 3 is more radical, but brings the API design more in line with developer expectations. The pipeline abstraction has been a consistent problem for many developers trying to use Vulkan since its inception, and this option can produce a cleaner, more user-friendly abstraction that bypasses the complexity of pipelines. With the benefit of years of hindsight and broader Working Group knowledge about the constraints of each others' implementations, it can aim to achieve a design which better balances API simplicity with adherence to the explicit design ethos of Vulkan. + +This proposal focuses on option 3, for the reasons outlined above. + +== Proposal + +=== Shaders + +This extension introduces a new object type `VkShaderEXT` which represents a single compiled shader stage. `VkShaderEXT` objects may be created either independently or linked with other `VkShaderEXT` objects created at the same time. To create `VkShaderEXT` objects, applications call `vkCreateShadersEXT()`: + +[source,c] +---- +VkResult vkCreateShadersEXT( + VkDevice device, + uint32_t createInfoCount, + VkShaderCreateInfoEXT* pCreateInfos, + VkAllocationCallbacks* pAllocator, + VkShaderEXT* pShaders); +---- + +This function compiles the source code for one or more shader stages into `VkShaderEXT` objects. Whenever `createInfoCount` is greater than one, the shaders being created may optionally be linked together. Linking allows the implementation to perform cross-stage optimizations based on a promise by the application that the linked shaders will always be used together. + +Though a set of linked shaders may perform anywhere between the same to substantially better than equivalent unlinked shaders, this tradeoff is left to the application and linking is never mandatory. + +[source,c] +---- +typedef enum VkShaderCreateFlagBitsEXT { + VK_SHADER_CREATE_LINK_STAGE_BIT_EXT = 0x00000001, + VK_SHADER_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT = 0x00000002, + VK_SHADER_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT = 0x00000004, + VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT = 0x00000008 +} VkShaderCreateFlagBitsEXT; +typedef VkFlags VkShaderCreateFlagsEXT; + +typedef enum VkShaderCodeTypeEXT { + VK_SHADER_CODE_TYPE_BINARY_EXT = 0, + VK_SHADER_CODE_TYPE_SPIRV_EXT = 1 +} VkShaderCodeTypeEXT; + +typedef struct VkShaderCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkShaderCreateFlagsEXT flags; + VkShaderStageFlagBits stage; + VkShaderStageFlags nextStage; + VkShaderCodeTypeEXT codeType; + size_t codeSize; + const void* pCode; + const char* pName; + uint32_t setLayoutCount; + const VkDescriptorSetLayout* pSetLayouts; + uint32_t pushConstantRangeCount; + const VkPushConstantRange* pPushConstantRanges; + const VkSpecializationInfo* pSpecializationInfo; +} VkShaderCreateInfoEXT; +---- + +To specify that shaders should be linked, include the `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` flag in each of the `VkShaderCreateInfoEXT` structures passed to `vkCreateShadersEXT()`. The presence or absence of `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` must match across all `VkShaderCreateInfoEXT` structures passed to a single `vkCreateShadersEXT()` call: i.e., if any member of `pCreateInfos` includes `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` then all other members must include it too. `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` is ignored if `createInfoCount` is one, and a shader created this way is considered unlinked. + +The stage of the shader being compiled is specified by `stage`. Applications must also specify which stage types will be allowed to immediately follow the shader being created. For example, a vertex shader might specify a `nextStage` value of `VK_SHADER_STAGE_FRAGMENT_BIT` to indicate that the vertex shader being created will always be followed by a fragment shader (and never a geometry or tessellation shader). Applications that do not know this information at shader creation time or need the same shader to be compatible with multiple subsequent stages can specify a mask that includes as many valid next stages as they wish. For example, a vertex shader can specify a `nextStage` mask of `VK_SHADER_STAGE_GEOMETRY_BIT | VK_SHADER_STAGE_FRAGMENT_BIT` to indicate that the next stage could be either a geometry shader or fragment shader (but not a tessellation shader). + +[NOTE] +==== +Certain implementations may incur a compile time and/or memory usage penalty whenever more than one stage bit is set in `nextStage`, so applications should strive to set the minimum number of bits they are able to. However, applications should *not* interpret this advice to mean that they should create multiple `VkShaderEXT` objects that differ only by the value of `nextStage`, as this will incur unnecessarily overhead on implementations where `nextStage` is ignored. +==== + +The shader code is pointed to by `pCode` and may be provided as SPIR-V, or in an opaque implementation defined binary form specific to the physical device. The format of the shader code is specified by `codeType`. + +The `codeType` of all `VkShaderCreateInfoEXT` structures passed to a `vkCreateShadersEXT()` call must match. This also means that only shaders created with the same `codeType` may be linked together. + +Descriptor set layouts and push constant ranges used by each shader are specified directly (not via a `VkPipelineLayout`), though multiple stages can of course point to the same structures. + +Any time after a `VkShaderEXT` object has been created, its binary shader code can be queried using `vkGetShaderBinaryDataEXT()`: + +[source,c] +---- +VkResult vkGetShaderBinaryDataEXT( + VkDevice device, + VkShaderEXT shader, + size_t* size, + void* pData); +---- + +When `pData` is `NULL`, `size` is filled with the number of bytes needed to store the shader’s binary code and `VK_SUCCESS` is returned. + +When `pData` is non-`NULL`, `size` points to the application-provided size of `pData`. If the provided size is large enough then the location pointed to by `pData` is filled with the shader’s binary code and `VK_SUCCESS` is returned, otherwise nothing is written to `pData` and `VK_INCOMPLETE` is returned. + +The binary shader code returned in `pData` can be saved by the application and used in a future `vkCreateShadersEXT()` call (including on a different `VkInstance` and/or `VkDevice`) with a compatible physical device by setting `codeType` to `VK_SHADER_CODE_TYPE_BINARY_EXT`. This means that on fixed platforms like game consoles and embedded systems applications need not ship SPIR-V shader code at all. If the binary shader code in any `VkShaderCreateInfoEXT` passed to `vkCreateShadersEXT()` is not compatible with the physical device then the `vkCreateShadersEXT()` call returns `VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT`. + +Applications must pass the same values of `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` to a `vkCreateShadersEXT()` call with a `codeType` of `VK_SHADER_CODE_TYPE_BINARY_EXT` as were passed when those shaders were originally compiled from SPIR-V. + +`VkShaderEXT` objects can be bound on a command buffer using `vkCmdBindShadersEXT()`: + +[source,c] +---- +void vkCmdBindShadersEXT( + VkCommandBuffer commandBuffer, + uint32_t stageCount, + const VkShaderStageFlagBits* pStages, + const VkShaderEXT* pShaders); +---- + +It is possible to unbind shaders for a particular stage by calling `vkCmdBindShadersEXT()` with elements of `pShaders` set to `VK_NULL_HANDLE`. For example, an application may want to arbitrarily bind and unbind a known compatible passthrough geometry shader without knowing or caring what specific vertex and fragment shaders are bound at that time. + +Regardless of whether the shaders were created with `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` the interfaces of all stages bound at `vkCmdDraw*()` time must be compatible. This means that the union of descriptor set layouts and push constant ranges across all bound shaders must not conflict, and that the inputs of each stage are compatible with the outputs of the previous stage. It is the application's responsibility to ensure that this is the case, and the implementation will not do any draw time state validation to guard against this kind of invalid usage. + +If any of the shaders bound at `vkCmdDraw*()` time were created with `VK_SHADER_CREATE_LINK_STAGE_BIT_EXT` then all shaders that were linked to that shader must also be bound. It is the application's responsibility to ensure that this is the case, and the implementation will not do any draw time state validation to guard against this kind of invalid usage. + +When drawing with shaders bound with `vkCmdBindShadersEXT()` most state must be set dynamically. Specifically, the following existing commands must be used to set the corresponding state: + + * `vkCmdSetViewportWithCount()` + * `vkCmdSetScissorWithCount()` + * `vkCmdSetLineWidth()` + * `vkCmdSetDepthBias()` + * `vkCmdSetBlendConstants()` + * `vkCmdSetDepthBounds()` + * `vkCmdSetStencilCompareMask()` + * `vkCmdSetStencilWriteMask()` + * `vkCmdSetStencilReference()` + * `vkCmdBindVertexBuffers2()` + * `vkCmdSetCullMode()` + * `vkCmdSetDepthBoundsTestEnable()` + * `vkCmdSetDepthCompareOp()` + * `vkCmdSetDepthTestEnable()` + * `vkCmdSetDepthWriteEnable()` + * `vkCmdSetFrontFace()` + * `vkCmdSetPrimitiveTopology()` + * `vkCmdSetStencilOp()` + * `vkCmdSetStencilTestEnable()` + * `vkCmdSetDepthBiasEnable()` + * `vkCmdSetPrimitiveRestartEnable()` + * `vkCmdSetRasterizerDiscardEnable()` + * `vkCmdSetVertexInputEXT()` + * `vkCmdSetLogicOpEXT()` + * `vkCmdSetPatchControlPointsEXT()` + * `vkCmdSetTessellationDomainOriginEXT()` + * `vkCmdSetDepthClampEnableEXT()` + * `vkCmdSetPolygonModeEXT()` + * `vkCmdSetRasterizationSamplesEXT()` + * `vkCmdSetSampleMaskEXT()` + * `vkCmdSetAlphaToCoverageEnableEXT()` + * `vkCmdSetAlphaToOneEnableEXT()` + * `vkCmdSetLogicOpEnableEXT()` + * `vkCmdSetColorBlendEnableEXT()` + * `vkCmdSetColorBlendEquationEXT()` + * `vkCmdSetColorWriteMaskEXT()` + +If link:{refpage}VK_KHR_fragment_shading_rate.html[VK_KHR_fragment_shading_rate] is supported and enabled: + + * `vkCmdSetFragmentShadingRateKHR()` + +If link:{refpage}VK_EXT_transform_feedback.html[VK_EXT_transform_feedback] is supported and enabled: + + * `vkCmdSetRasterizationStreamEXT()` + +If link:{refpage}VK_EXT_discard_rectangle.html[VK_EXT_discard_rectangle] is supported and enabled: + + * `vkCmdSetDiscardRectangleEnableEXT()` + * `vkCmdSetDiscardRectangleModeEXT()` + * `vkCmdSetDiscardRectangleEXT()` + +If link:{refpage}VK_EXT_conservative_rasterization.html[VK_EXT_conservative_rasterization] is supported and enabled: + + * `vkCmdSetConservativeRasterizationModeEXT()` + * `vkCmdSetExtraPrimitiveOverestimationSizeEXT()` + +If link:{refpage}VK_EXT_depth_clip_enable.html[VK_EXT_depth_clip_enable] is supported and enabled: + + * `vkCmdSetDepthClipEnableEXT()` + +If link:{refpage}VK_EXT_sample_locations.html[VK_EXT_sample_locations] is supported and enabled: + + * `vkCmdSetSampleLocationsEnableEXT()` + * `vkCmdSetSampleLocationsEXT()` + +If link:{refpage}VK_EXT_blend_operation_advanced.html[VK_EXT_blend_operation_advanced] is supported and enabled: + + * `vkCmdSetColorBlendAdvancedEXT()` + +If link:{refpage}VK_EXT_provoking_vertex.html[VK_EXT_provoking_vertex] is supported and enabled: + + * `vkCmdSetProvokingVertexModeEXT()` + +If link:{refpage}VK_EXT_line_rasterization.html[VK_EXT_line_rasterization] is supported and enabled: + + * `vkCmdSetLineRasterizationModeEXT()` + * `vkCmdSetLineStippleEnableEXT()` + * `vkCmdSetLineStippleEXT()` + +If link:{refpage}VK_EXT_depth_clip_control.html[VK_EXT_depth_clip_control] is supported and enabled: + + * `vkCmdSetDepthClipNegativeOneToOneEXT()` + +If link:{refpage}VK_EXT_color_write_enable.html[VK_EXT_color_write_enable] is supported and enabled: + + * `vkCmdSetColorWriteEnableEXT()` + +If link:{refpage}VK_NV_clip_space_w_scaling.html[VK_NV_clip_space_w_scaling] is supported and enabled: + + * `vkCmdSetViewportWScalingEnableNV()` + * `vkCmdSetViewportWScalingNV()` + +If link:{refpage}VK_NV_viewport_swizzle.html[VK_NV_viewport_swizzle] is supported and enabled: + + * `vkCmdSetViewportSwizzleNV()` + +If link:{refpage}VK_NV_fragment_coverage_to_color.html[VK_NV_fragment_coverage_to_color] is supported and enabled: + + * `vkCmdSetCoverageToColorEnableNV()` + * `vkCmdSetCoverageToColorLocationNV()` + +If link:{refpage}VK_NV_framebuffer_mixed_samples.html[VK_NV_framebuffer_mixed_samples] is supported and enabled: + + * `vkCmdSetCoverageModulationModeNV()` + * `vkCmdSetCoverageModulationTableEnableNV()` + * `vkCmdSetCoverageModulationTableNV()` + +If link:{refpage}VK_NV_coverage_reduction_mode.html[VK_NV_coverage_reduction_mode] is supported and enabled: + + * `vkCmdSetCoverageReductionModeNV()` + +If link:{refpage}VK_NV_representative_fragment_test.html[VK_NV_representative_fragment_test] is supported and enabled: + + * `vkCmdSetRepresentativeFragmentTestEnableNV()` + +If link:{refpage}VK_NV_shading_rate_image.html[VK_NV_shading_rate_image] is supported and enabled: + + * `vkCmdSetCoarseSampleOrderNV()` + * `vkCmdSetShadingRateImageEnableNV()` + * `vkCmdSetViewportShadingRatePaletteNV()` + +If link:{refpage}VK_NV_scissor_exclusive.html[VK_NV_scissor_exclusive] is supported and enabled: + + * `vkCmdSetExclusiveScissorEnableNV()` + * `vkCmdSetExclusiveScissorNV()` + +If link:{refpage}VK_NV_fragment_shading_rate_enums.html[VK_NV_fragment_shading_rate_enums] is supported and enabled: + + * `vkCmdSetFragmentShadingRateEnumNV()` + +Certain dynamic state setting commands have modified behavior from their original versions: + + * `vkCmdSetPrimitiveTopology()` does not have any constraints on the topology class (i.e., it behaves as if the `dynamicPrimitiveTopologyUnrestricted` property is `VK_TRUE` even when the actual property is `VK_FALSE`). + * `vkCmdSetLogicOpEXT()` may be used on any implementation regardless of its support for the `extendedDynamicState2LogicOp` feature. + * `vkCmdSetPatchControlPointsEXT()` may be used on any implementation regardless of its support for the `extendedDynamicState2PatchControlPoints` feature. + +Any `VkShaderEXT` can be destroyed using `vkDestroyShaderEXT()`: + +[source,c] +---- +void vkDestroyShaderEXT( + VkDevice device, + VkShaderEXT shader, + VkAllocationCallbacks* pAllocator); +---- + +Destroying a `VkShaderEXT` object used by action commands in one or more command buffers in the _recording_ or _executable_ states causes those command buffers to enter the _invalid_ state. A `VkShaderEXT` object must not be destroyed as long as any command buffer that issues any action command that uses it is in the _pending_ state. + +== Examples + +=== Graphics + +Consider an application which always treats sets of shader stages as complete programs. + +At startup time, the application compiles and links the shaders for each complete program: + +[source,c] +---- +VkShaderCreateInfoEXT shaderInfo[2] = { + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + .nextStage = VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexShaderSpirvSize, + .pCode = pVertexShaderSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentShaderSpirvSize, + .pCode = pFragmentShaderSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + } +}; + +VkShaderEXT shaders[2]; + +vkCreateShadersEXT(device, 2, shaderInfo, NULL, shaders); +---- + +Later at draw time, the application binds the linked vertex and fragment shaders forming a complete program: + +[source,c] +---- +VkShaderStageFlagBits stages[2] = { + VK_SHADER_STAGE_VERTEX_BIT, + VK_SHADER_STAGE_FRAGMENT_BIT +}; +vkCmdBindShadersEXT(commandBuffer, 2, stages, shaders); +---- + +Alternatively, the same result could be achieved by: + +[source,c] +---- +{ + VkShaderStageFlagBits stage = VK_SHADER_STAGE_VERTEX_BIT; + vkCmdBindShadersEXT(commandBuffer, 1, &stage, &shaders[0]); +} + +{ + VkShaderStageFlagBits stage = VK_SHADER_STAGE_FRAGMENT_BIT; + vkCmdBindShadersEXT(commandBuffer, 1, &stage, &shaders[1]); +} +---- + +If the `tessellationShader` or `geometryShader` features are enabled on the device, the application sets the corresponding shader types to VK_NULL_HANDLE: + +[source,c] +---- +VkShaderStageFlagBits unusedStages[3] = { + VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + VK_SHADER_STAGE_GEOMETRY_BIT +}; +VkShaderEXT unusedShaders[3] = { /* VK_NULL_HANDLE, ... */ }; +vkCmdBindShadersEXT(commandBuffer, 3, unusedStages, unusedShaders); +---- + +Alternatively, the same result could be achieved by: + +[source,c] +---- +VkShaderStageFlagBits unusedStages[3] = { + VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + VK_SHADER_STAGE_GEOMETRY_BIT +}; +// Setting pShaders to NULL is equivalent to specifying an array of stageCount VK_NULL_HANDLE values +vkCmdBindShadersEXT(commandBuffer, 3, unusedStages, NULL); +---- + +Finally, the application issues a draw call: + +[source,c] +---- +vkCmdDrawIndexed(commandBuffer, ...); +---- + +Now consider a different application which needs to mix and match vertex and fragment shaders in arbitrary combinations that are not predictable at shader compile time. + +At startup time, the application compiles unlinked vertex and fragment shaders: + +[source,c] +---- +VkShaderCreateInfoEXT shaderInfo[3] = { + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + .nextStage = VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexShaderSpirvSize, + .pCode = pVertexShaderSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentShaderSpirvSize[0], + .pCode = pFragmentShaderSpirv[0], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }, + { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentShaderSpirvSize[1], + .pCode = pFragmentShaderSpirv[1], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + } +}; + +VkShaderEXT shaders[3]; + +vkCreateShadersEXT(device, 3, shaderInfo, NULL, shaders); +---- + +Alternatively, the same result could be achieved by: + +[source,c] +---- +VkShaderEXT shaders[3]; + +{ + VkShaderCreateInfoEXT shaderInfo = { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_VERTEX_BIT, + .nextStage = VK_SHADER_STAGE_FRAGMENT_BIT, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = vertexShaderSpirvSize, + .pCode = pVertexShaderSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }; + + vkCreateShadersEXT(device, 1, &shaderInfo, NULL, &shaders[0]); +} + +{ + VkShaderCreateInfoEXT shaderInfo = { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentShaderSpirvSize[0], + .pCode = pFragmentShaderSpirv[0], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }; + + vkCreateShadersEXT(device, 1, &shaderInfo, NULL, &shaders[1]); +} + +{ + VkShaderCreateInfoEXT shaderInfo = { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_FRAGMENT_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = fragmentShaderSpirvSize[1], + .pCode = pFragmentShaderSpirv[1], + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL + }; + + vkCreateShadersEXT(device, 1, &shaderInfo, NULL, &shaders[2]); +} +---- + +Later at draw time, the application binds independent vertex and fragment shaders forming a complete program: + +[source,c] +---- +VkShaderStageFlagBits stages[2] = { + VK_SHADER_STAGE_VERTEX_BIT, + VK_SHADER_STAGE_FRAGMENT_BIT +}; +vkCmdBindShadersEXT(commandBuffer, 2, stages, shaders); +---- + +If the `tessellationShader` or `geometryShader` features are enabled on the device, the application sets the corresponding shader types to VK_NULL_HANDLE: + +[source,c] +---- +VkShaderStageFlagBits unusedStages[3] = { + VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + VK_SHADER_STAGE_GEOMETRY_BIT +}; +// Setting pShaders to NULL is equivalent to specifying an array of stageCount VK_NULL_HANDLE values +vkCmdBindShadersEXT(commandBuffer, 3, unusedStages, NULL); +---- + +Then, the application issues a draw call: + +[source,c] +---- +vkCmdDrawIndexed(commandBuffer, ...); +---- + +Later, the application binds a different fragment shader without disturbing any other stages: + +[source,c] +---- +VkShaderStageFlagBits stage = VK_SHADER_STAGE_FRAGMENT_BIT; +vkCmdBindShadersEXT(commandBuffer, 1, &stage, &shaders[2]); +---- + +Finally, the application issues another draw call: + +[source,c] +---- +vkCmdDrawIndexed(commandBuffer, ...); +---- + +=== Compute + +At startup time, the application compiles a compute shader: + +[source,c] +---- +VkShaderCreateInfoEXT shaderInfo = { + .sType = VK_STRUCTURE_TYPE_SHADER_CREATE_INFO_EXT, + .pNext = NULL, + .flags = 0, + .stage = VK_SHADER_STAGE_COMPUTE_BIT, + .nextStage = 0, + .codeType = VK_SHADER_CODE_TYPE_SPIRV_EXT, + .codeSize = computeShaderSpirvSize, + .pCode = pComputeShaderSpirv, + .pName = "main", + .setLayoutCount = 1, + .pSetLayouts = &descriptorSetLayout, + .pushConstantRangeCount = 0, + .pPushConstantRanges = NULL, + .pSpecializationInfo = NULL +}; + +VkShaderEXT shader; + +vkCreateShadersEXT(device, 1, &shaderInfo, NULL, &shader); +---- + +Later, the application binds the compute shader: + +[source,c] +---- +VkShaderStageFlagBits stage = VK_SHADER_STAGE_COMPUTE_BIT; +vkCmdBindShadersEXT(commandBuffer, 1, &stage, &shader); +---- + +Finally, the application dispatches the compute: + +[source,c] +---- +vkCmdDispatch(commandBuffer, ...); +---- + +== Issues + +=== RESOLVED: How should implementations which absolutely must link shader stages implement this extension? + +The purpose of this extension is to expose the flexibility of those implementations which allow arbitrary combinations of unlinked but compatible shader stages and state to be bound independently. Attempting to modify this extension to support implementations which do not have this flexibility would defeat the entire purpose of the extension. For this reason, implementations which do not have the required flexibility should not implement this extension. + +IHVs whose implementations have such limitations today are encouraged to consider incorporating changes which could remove these limitations into their future hardware roadmaps. + +=== RESOLVED: Should this extension try to reuse pipeline objects and concepts? + +No - the pipeline abstraction was never designed with such a radically different design in mind. + +Avoiding the introduction of a new object type and a handful of new entry points is not a compelling reason to continue to pile less and less pipeline-like functionality into pipelines. Doing so would needlessly constrict or even undermine the design and future extensibility of both models. + +=== RESOLVED: Should binary shader support be exposed in some way similar to existing pipeline caches or pipeline binaries? + +No - fixed platforms like game consoles and embedded systems have constraints which make shipping both SPIR-V and binary copies of the same shader code undesirable. + +=== RESOLVED: Should there be some kind of shader program object to represent a set of linked shaders? + +No - the compiled code for each shader stage is represented by a single `VkShaderEXT` object whether it is linked to other stages or not. + +Introducing a shader program object would overly complicate the API and impose a new and unnecessary object lifetime management burden on applications. Vulkan is a low level API, and it should be the application's responsibility to ensure that it keeps any promises it chooses to make about binding the correct stages together. + +[NOTE] +==== +Whenever shaders are created linked together, the rules for binding them give implementations the freedom to (for example) internally store the compiled code for multiple linked stages in a single stage's `VkShaderEXT` object and to leave the other stages' `VkShaderEXT` objects internally unused, though this is *strongly* discouraged. +==== + +=== RESOLVED: Should there be some mechanism for applications to provide static state that is known at compile time? + +Not as part of this extension - it is possible to imagine some kind of "shader optimization hint" functionality to let applications provide implementations with "static state" similar to the existing static state in pipelines, but on an opt-in rather than opt-out basis. By providing a given piece of state in an optimization hint at shader creation time, an application could promise that the equivalent piece of dynamic state would always be set to some specific value whenever that shader is used, thereby allowing implementations to perform compile time optimizations similar to those they can make with pipelines today. + +For already pipeline-friendly applications with lots of static state this could serve as a "gentler" version of pipelines that might provide the best of both worlds, but it is unclear that the benefits of such a scheme for the (pipeline-unfriendly) majority of applications which actually need this extension would outweigh the costs of the added complexity to the API. + +If such functionality turns out to be important, it can be noninvasively layered on top of this extension in the form of another extension. Until then, applications wanting something that behaves like pipelines should just use pipelines. + +=== RESOLVED: Should this extension expose some abstraction for setting groups of related state? + +No - an earlier version of this proposal exposed a mechanism for applications to pre-create "interface shaders" which could then be bound on a command buffer to reduce draw time overhead. This added complexity to the API, and it was unclear that this solution would be able to deliver meaningful performance improvements over setting individual pieces of state on the command buffer. + +Such an abstraction may prove beneficial for certain implementations, but it should not be designed until those implementations have at least attempted to implement support for this extension in its existing form. + +=== RESOLVED: There is currently no dynamic state setting functionality for sample shading. How should this be handled? + +Sample shading is already implicitly enabled (with minSampleShading = 1.0) whenever a shader reads from the SampleId or SamplePosition builtins. The main functionality missing in the absence of dynamic sample shading is the ability to specify minSampleShading values other than 1.0. + +This could be addressed by introducing a new MinSampleShading shader builtin which can be either hard-coded or specialized at SPIR-V compile time using the existing specialization constant mechanism. However, since introducing this functionality is orthogonal to the objective of this extension this is left up to a different extension. + +Until such an extension is available, applications that need to specify a minSampleShading other than 1.0 should use pipelines. + +== Further Functionality + + * Shader optimization hints + * State grouping + * Ray tracing shader objects diff --git a/proposals/VK_EXT_shader_tile_image.adoc b/proposals/VK_EXT_shader_tile_image.adoc new file mode 100644 index 0000000000..5b8d110086 --- /dev/null +++ b/proposals/VK_EXT_shader_tile_image.adoc @@ -0,0 +1,499 @@ +// Copyright 2021-2023 The Khronos Group, Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_EXT_shader_tile_image +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +`VK_EXT_shader_tile_image` is a device extension that explicitly enables access to on-chip pixel data. For GPUs supporting this extension, it is a replacement for many use-cases for subpasses, which are not available when the `VK_KHR_dynamic_rendering` extension is used. + +== Problem Statement + +Some implementations, in particular tile-based GPUs, want to allow applications to effectively exploit local, e.g. on-chip, memory. +A classic example would be optimizing G-buffer based deferred shading techniques where the G-buffer is produced and consumed on-chip. + +Subpasses were designed to support such use-cases with an API mechanism that was portable across all implementations. In practice, that has led to some problems, including: + + * the high level abstraction is far removed from the mental model an application developer needs to have to be able to optimize for keeping data on-chip + * the subpass design affects other parts of the API and is seen as a 'tax' on applications that do not target implementations that benefit from on-chip storage + * developers wanting to optimize for a specific class of GPUs often need to make GPU specific optimization choices, so the abstraction does not add much + +These problems motivated `VK_KHR_dynamic_rendering`, which offers an alternative API without subpasses. But keeping data on-chip is still an important optimization for a class of GPUs. + +This proposal aims to provide the most essential functionality of subpasses, but in an explicit manner. +The abstractions in this proposal are a closer match to what the underlying GPU implementation does and should make it easier to communicate best practices and performance guarantees to developers. + +== Solution Space + +=== High-level choices + +The solution space can be split in two axes: scope and abstraction level. + +The abstraction level is a question of whether we want an API that is only targeted at tile-based GPUs or if we should have a higher-level API that would allow the feature to be supported on a wider range of GPUs. +The main argument for a higher abstraction level is application portability. +Arguments against additional abstractions include: + + * It would be hard for developers to reason about performance expectations, for the same reasons that it is hard to do this for subpasses + * "Framebuffer fetch" and "programmable blend" semantics are naturally expressed as direct reads from color attachments, and adding abstractions just obfuscate what (some) GPU hardware is doing + * GPUs that are not tile-based would not gain much from exposing this - at least not unless the scope is expanded - so the abstractions add little practical value + +There are two choices broadly based on what the functionality is for, and which GPUs are able to support it: + +1. An explicit API to allow certain tile-based GPUs to expose on-chip memory with fast raster order access. + * Provides framebuffer fetch and Pixel Local Storage functionality and forms the basis for Tile Shader like functionality. + * This is mainly targeted at GPUs which defer fragment shading into framebuffer tiles where each tile is typically processed just once. + * This addresses use cases such as keeping G-buffer data on-chip. + * No DRAM bandwidth paid for render targets which are cleared on load, consumed within the render pass, and content discarded at end of render pass. + * Raster order access (coherent access) to framebuffer data from fragment shader is efficient or even "free" - depending on the GPU. + * No descriptors needed for render target access. + +2. A slightly higher level API to enable broad GPU support for framebuffer fetch like functionality within draw calls in dynamic render passes. + * Provides framebuffer fetch like functionality. + * This is intended to be supported by a wide range of GPUs. The GPUs in general have optimised support for framebuffer fetch within a render pass. + * This addresses use cases such a programmable image composition, or programmable resolve. + * Attachment data is not guaranteed to be on-chip within a render pass and may spill to DRAM. Implementations may opportunistically cache data in their cache hierarchy. + * Raster order access to framebuffer data from fragment shader is not "free". Many implementations may prefer non-coherent access with explicit synchronization from applications. + * Descriptors need to be bound for render target access (at least for some implementations). + +This proposal targets the first choice. + +The options for scope include: + + * "Framebuffer fetch" equivalent, i.e. enable access to the previously written pixel in the local framebuffer region + * "Pixel local storage" equivalent, i.e. as above with the addition of pixel format reinterpretation + * "Tile shader" equivalent, i.e. enable access to a region larger than 1x1 pixels + +This proposal targets the first option, but adds building blocks to enable future enhancements. +The reasoning behind this choice is that: + + * It should be possible to support this extension on existing GPUs + * Many use-cases that benefit from subpasses could be implemented with this functionality + * Ease of integration; this option requires the least amount of changes to rendering engines + * Time to market; several IHVs would like at least the subpass equivalent functionality to be implemented alongside `VK_KHR_dynamic_rendering` + +=== Implementation choices + +It is useful to provide tile image access for all attachment types. +But implementations may manage depth/stencil differently than color, which could add constraints. +We will therefore expose separate feature bits for color, depth, and stencil access. + +Tile image variables currently have to 'alias' a color attachment location, and their format is implicitly specified to match the color attachment format. + +== Proposal + +=== Concept + +image::{images}/tile_image.svg[align="center",title="Tile Image",align="center",opts="{imageopts}"] + +Introduce the concept of a 'tile image'. When the extension is enabled, the framebuffer is logically divided into a grid of non-overlapping tiles called tile images. + +=== API changes + +Add a new feature struct `VkPhysicalDeviceShaderTileImageFeaturesEXT` containing: + + * shaderTileImageColorReadAccess + * shaderTileImageDepthReadAccess + * shaderTileImageStencilReadAccess + +shaderTileImageColorReadAccess is mandatory if this extension is supported. + +shaderTileImageColorReadAccess provides the ability to access current (rasterization order) color values from tile memory via tile images. +There is no support for the storage format to be redefined as part of this feature. +Output data is still written via Fragment Output variables. +Since the framebuffer format is not re-declared, fixed-function blending works as normal. + +Existing shaders do not to need to be modified to write to color attachments. + +Reading color values using the functionality in this extension guarantees that the access is in rasterization order. +See the spec (Fragment Shader Tile Image Reads) for details on which samples reads qualify for coherent read access. + +shaderTileImageDepthReadAccess and shaderTileImageStencilReadAccess provide similar ability to read the depth and stencil values of any sample location covered by the fragment. +Depth and stencil fetches use implicit tile images. +If no depth / stencil attachment is present then the values returned by fetches are undefined. +Early fragment tests are disallowed if depth or stencil fetch is used. + +Reading depth/stencil values have similar rasterization order and synchronization guarantees as color. + +=== SPIR-V changes + +This proposal leverages `OpTypeImage` and makes 'TileImageDataEXT' another `Dim` similar to `SubpassData`. + +Specifically: + + * `Dim` is extended with `TileImageDataEXT`. + * `OpTypeImage` gets the additional constraint that if `Dim` is `TileImageDataEXT`: + ** `Sampled` must: be `2` + ** `Image Format` must be `Unknown` as the format is implicitly specified by the color attachment + *** (We could relax this in a further extension if we wanted to support format reinterpretation in the shader.) + ** `Execution Model` must be `Fragment` + ** `Arrayed` must be `0` + ** Extend the use of `Location` such that it specifies the color attachment index + * Add `OpColorAttachmentReadEXT`, which is similar to `OpImageRead` but helps disambiguate between color/depth/stencil. + * Add `OpDepthAttachmentReadEXT` and `OpStencilAttachmentReadEXT` to read depth/stencil + ** These take an optional `Sample` parameter for MSAA use-cases + * Add a `TileImageEXT` Storage Class that is only supported for variables of `OpTypeImage` with `Dim` equal to `TileImageDataEXT` + +=== GLSL changes + +Main changes: + + * New type: `attachmentEXT` + * The `location` layout qualifier is used to specify the corresponding color attachment + * New storage qualifier (supported only in fragment shaders): `tileImageEXT` + * New functions: `colorAttachmentReadEXT`, `depthAttachmentReadEXT`, `stencilAttachmentReadEXT` + +Mapping to SPIR-V: + + * `attachmentEXT` maps to `OpTypeImage` with `Dim` equal to `TileImageDataEXT` + * `colorAttachmentReadEXT` maps to `OpColorAttachmentReadEXT` + * `depthAttachmentReadEXT` maps to `OpDepthAttachmentReadEXT` + * `stencilAttachmentReadEXT` maps to `OpStencilAttachmentReadEXT` + +Function signatures: +[source,c] +---- +// color +gvec4 colorAttachmentReadEXT(gattachment attachmentEXT); +gvec4 colorAttachmentReadEXT(gattachment attachmentEXT, int sample); + +// depth +highp float depthAttachmentReadEXT(); +highp float depthAttachmentReadEXT(int sample); + +// stencil +lowp uint stencilAttachmentReadEXT(); +lowp uint stencilAttachmentReadEXT(int sample); +---- + +=== HLSL Changes + +== Examples + +=== Color reads + +[source,c] +---- +// ------ Subpass Example -------- +layout( set = 0, binding = 0, input_attachment_index = 0 ) uniform highp subpassInput color0; +layout( set = 0, binding = 1, input_attachment_index = 1 ) uniform highp subpassInput color1; + +layout( location = 0 ) out vec4 fragColor; + +void main() +{ + vec4 value = subpassLoad(color0) + subpassLoad(color1); + fragColor = value; +} + +// ----- Equivalent Tile Image approach ------ + +// NOTES: +// 'tileImageEXT' is a storage qualifier. +// 'attachmentEXT' is an opaque type; similar to subpassInput +// 'aliased' means that the variable shares _tile image_ with the corresponding attachment; there is no in-memory aliasing + +layout( location = 0 /* aliased to color attachment 0 */ ) tileImageEXT highp attachmentEXT color0; +layout( location = 1 /* aliased to color attachment 1 */ ) tileImageEXT highp attachmentEXT color1; + +layout( location = 0 ) out vec4 fragColor; + +void main() +{ + vec4 value = colorAttachmentReadEXT(color0) + colorAttachmentReadEXT(color1); + fragColor = value; +} +---- + +==== Depth reads + +[source,c] +---- +void main() +{ + // read sample 0: works for non-MSAA or MSAA targets + highp float last_depth = depthAttachmentReadEXT(); +} +---- + +== Alternate Proposals + +The following proposals explore alternate ways to expose the functionality for reading from the tile memory for color data - reading depth and stencil and the API changes are kept unchanged from the main proposal. + +=== Proposal B: OpTypeTileImage + +==== SPIR-V Changes + +Add new type: `TileImage`. We have two options for defining `TileImage`: + +. `TileImage` variables which are instanced per-pixel (or per-sample in case of multisampled framebuffers) +. `TileImage` defines a 2D array of pixels similar to an image but in tile memory. +.. Note: Defining this as a 2D array fits well for future `Tile Shaders` functionality where tile shader invocations on a tile can access any location within a TileImage on the tile. + +Add new instruction: `OpTypeTileImage`. The instruction declares a `tile image`. `Tile image` is an opaque type. `OpTypeTileImage` has the following operands: + +* `Image Format`: the imageformat. This must be set to `Unknown` as the format is implicitly specified by the color attachment. +** (We could relax this in a further extension if we wanted to support format reinterpretation in the shader.) +* `MS` : indicates whether the content is multisampled. 0 - single-sampled. 1 - multisampled. + +`Tile image` variables must be decorated with `Location` which specifies the color attachment index. +`Execution Model` must be `Fragment`. + +Add `OpTileImageRead`, `OpDepthTileImageRead`, `OpStencilTileImageRead` to read from color, depth, stencil tile images. +Add `Tile` storage class. + +==== GLSL Changes + +GLSL changes remain the same as in the main proposal except the mapping changes to `OpTypeTileImage` instead of `OpTypeImage`: + + * `tileImage` maps to `OpTypeTileImage` + +=== Proposal C: Storage Class / PLS style + +==== SPIR-V Changes + +Introduce `TileImage` as a new storage class. + +* Variables declared with `TileImage` must have `Location` decoration specified - this specifies the attachment index to alias to. +* If image format reinterpretation is to be supported then a new `Imageformat` decoration is specified. +* `TileImage` storage class variables are multisampled with the sample count of the framebuffer if multisampling is enabled. +* Reading of TileImage variables is done via `OpTileImageRead`. +** `OpTileImageRead` which accepts a `sample` parameter for MSAA use cases. + +* If aggregate types are to be supported in `TileImage` storage class, we would need the following: +** `Location` and `Imageformat` must only be applied to non-structure type (that is, scalars or vectors or arrays of scalars or arrays of vectors). + +==== GLSL Changes + +* New storage class `tileImage`. +* Add support for grouping `tileImage` variable declarations into an interface block. +* layout `location` must be specified for the variables. +* Add new builtin function `tileImageRead`, which accepts an optional parameter `sample` +* If reinterpretation of formats is supported (within the same draw call), then we need `tileImageIn` and `tileImageOut` (or make `tileImage` an auxiliary storage specifier, similar to `patch` so we could use `tileImage in` and `tileImage out`). + +== Non-coherent access + +Some implementations have a penalty for support raster order access to tile image data. To support this functionality on such implementations we would add the following changes to the base proposal: + +=== API Changes + +* A property bit `shaderTileImagePreferCoherentReadAccess` indicating whether the implementation prefers coherent read accesses are used. + +* Support for specifying the barriers - three broad options (see next section) + +* Note: The gains from tile image feature with raster order access enabled are expected to match the gains from subpasses. + +=== Barrier Proposal A: MemoryBarrier via vkCmdPipelineBarrier2 + +`vkCmdPipelineBarrier2` would be allowed within dynamic render passes to specify a `VkMemoryBarrier2` with some restrictions. The enums `VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT` and `VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT` are reused for tileimage read accesses. + +This approach would allow synchronizing all color attachments, or depth stencil attachment, but does not support synchronizing individual color attachments. + +Example synchronizing two draw calls, where the first writes to color attachments and the second reads via the tileimage variables. + +[source,c] +---- +vkCmdDraw(...); + +VkMemoryBarrier2 memoryBarrier = { + ... + .srcStageMask = VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT, + .srcAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, + .dstStageMask = VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, + .dstAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT +}; + +VkDependencyInfo dependencyInfo { + ... + VK_DEPENDENCY_BY_REGION, //dependency flags + 1, //memory barrier count + &memoryBarrier, //memory barrier + ... +}; + +vkCmdPipelineBarrier2(commandBuffer, &dependencyInfo); + +vkCmdDraw(...); +---- + +=== Barrier Proposal B: ImageMemoryBarrier via vkCmdPipelineBarrier2 + +`vkCmdPipelineBarrier2` would be allowed within dynamic render passes to specify a `VkMemoryBarrier2` with some restrictions. The enums `VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT` and `VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT` are reused to express tileimage read accesses. + +This approach would allow synchronizing individual color attachments, or depth or stencil attachment. + +Example synchronizing two draw calls, where the first writes to color attachments and the second reads via the tileimage variables. + +[source,c] +---- +vkCmdDraw(...); + +VkImageMemoryBarrier2 imageMemoryBarrier = { + ... + .srcStageMask = VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT, + .srcAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, + .dstStageMask = VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT, + .dstAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT, + .oldLayout = ..., //layouts not allowed to be changed. + .newLayout ..., + .image = .., //image and subresource identifying the specific attachment. + .subresourceRange = .. +}; + +VkDependencyInfo dependencyInfo { + ... + VK_DEPENDENCY_BY_REGION, //dependency flags + ... + 1, //image memory barrier count + &imageMemoryBarrier, //memory barrier + ... +}; + +vkCmdPipelineBarrier2(commandBuffer, &dependencyInfo); + +vkCmdDraw(...); +---- + +=== Barrier Proposal C: New simple API for tile image barriers + +New API entry point `vkCmdTileBarrierEXT(..)` where the app can specify which attachments to synchronize. This can be easily extended to tile shader if an implementation desires explicit barriers - by specifying all of tile memory needs to be synchronized and explicitly specifying tile-wide synchronization. + +[source,c] +---- +//New Vulkan function and types +vkCmdTileBarrierEXT( + VkCommandBuffer commandBuffer, + VkDependencyFlags dependencyFlags, + VkTileMemoryTypeFlagsEXT tileMemoryMask); + +typedef enum VkTileMemoryTypeFlagsBitsEXT { + VK_TILE_IMAGE_COLOR_ATTACHMENTS_BIT = 0x00000001, + VK_TILE_IMAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000002, +} +---- + +Example synchronizing two draw calls, where the first writes to color attachments and the second reads via the tile image variables. + +[source,c] +---- +vkCmdDraw(...); + +vkCmdTileBarrierEXT(commandBuffer, + VK_DEPENDENCY_BY_REGION, + VK_TILE_IMAGE_COLOR_ATTACHMENTS_BIT); + +vkCmdDraw(...); +---- + + +=== SPIR-V and GLSL changes + +* Tile Image data variables can optionally be specified with "noncoherent" layout qualifier in GLSL. For Depth and Stencil we could use a special fragment shader layout qualifier (similar to early_fragment_tests) to indicate depth and stencil access is "noncoherent". +* Three new Execution modes in SPIR-V to specify that color, depth or stencil reads via the functionality in this extension are non-coherent (that is the reads are no longer guaranteed to be in raster order with respect to write operations from prior fragments). + +== Issues + +=== 1. RESOLVED: Should we allow early fragment tests? + +Early fragment tests are disallowed if reading frag depth / stencil. + +=== 2. RESOLVED: Should depth / stencil fetch be a separate extension? + +Access to depth / stencil is defined differently than color, but we suggest keeping them together - with separate feature bits. + +=== 3. RESOLVED: What should we name these variables? What should the extension be named? + +Other APIs have similar but not identical concepts, so a unique name is useful. + +We call these resources tile images. +On typical implementations supporting this extension, the framebuffer is divided into tiles and fragment processing is deferred such that each framebuffer tile is typically visited just once. +A tile image is a view of a framebuffer attachment, restricted to the tile being processed. + +Note that fragment shaders still can only color, depth, and stencil values from their fragment location and not the entire tile. + +The extension is called VK_EXT_shader_tile_image. + +=== 4. RESOLVED: Are there any non-obvious interactions with the suspend/resume functionality in `VK_KHR_dynamic_rendering`? + +Not at present. +If we were to allow non-aliased tile image variables, then implementations would have to be able to guarantee that those variables never have to 'spill' from tile image. + +=== 5. RESOLVED: Enable / Disable raster order access + +Some implementations pay a performance cost to guarantee raster order access. We need to give them a way to disable raster order access and add support for barriers to explicitly perform synchronization. + +Three proposals have been added to the Non-coherent access section in this document. The spec changes currently choose Barrier Proposal A: MemoryBarrier via vkCmdPipelineBarrier2. + +Vulkan barriers have been difficult for developers to use, so Barrier Proposal C might offer a simpler API. + +Consensus was to keep things consistent with existing barriers in Vulkan, so Barrier Proposal A was chosen. + +=== 7. RESOLVED: Should this extension reuse OpTypeImage, or introduce a new type for declaring tile images? + +OpTypeImage is reused with a special Dim for tile images, following what was done for subpass attachments. + +An alternative would have been to make tile images their own type, and introduce an OpTypeTileImage type. +That would require less special-casing of OpTypeImage, but comes with higher initial burden in tooling. + +=== 8. RESOLVED: Should Color, Depth, and Stencil reads use the same SPIR-V opcode? + +No. The extension introduces separate opcodes. + +Tile based GPUs which guarantee framebuffer residency in tile memory can offer efficient raster order access to color, depth, stencil data with relatively low overhead. +Some GPU implementations would have a significant performance penalty in raster order access if the implementation cannot determine from the SPIR-V shader whether a specific access is color, depth, or stencil. + +This design choice is in-line with other API extensions (GL framebuffer fetch and framebuffer fetch depth stencil) and other APIs where depth/stencil access is clearly disambiguated. + +=== 9. RESOLVED: Should Depth and Stencil read opcodes consume an image operand specifying the attachment, or should it be implicit? + +No operand is necessary as there is depth and stencil uniquely identify the attachments unlike with color. + +The other options considered were: + + A. Allow depth and stencil tile images to be declared as variables. Tile images are defined to map to the color attachment specified via the `Location` decoration - some equivalent needs to be defined for depth and stencil. Pixel Local Storage like functionality of supporting format reinterpretation is only supported for color attachments, and hence must be disallowed for depth and stencil. There is very little benefit to declaring the depth and stencil variables given these restrictions. + B. Depth and stencil tile images are exposed as built-in variables. + +Given the design choice made for issue 8, the alternate options do not add any value. + +=== 10. RESOLVED: Should this extension re-use the image Dim SubpassData or introduce a new Dim? + +The extension introduces a new Dim. + +This extension is intended to serve as foundation for further functionality - for example Pixel Local Storage like format reinterpretation, or to define the tile size and allow tile shaders to access any pixel within the tile. +In SPIR-V, input attachments use images with Dim of SubpassData. We use a new Dim so we can easily distinguish whether an image is an input attachment or a tile image. + +=== 11. RESOLVED: Should this extension require applications to create and bind descriptors for tile images? + +No. +Some GPUs internally require descriptors to be able to access framebuffer data. The input attachments in Vulkan subpasses help these GPU implementations. + +Other GPUs do not require apps to bind such descriptors. The intent with this extension is to provide functionality roughly in the lines of GL_EXT_shader_framebuffer_fetch, GL_EXT_shader_pixel_local_storage - which do not require apps to manage and bind descriptors. + +=== 12. RESOLVED: What does 'undefined value' mean for tile image reads? + +It simply means that the value has no well-defined meaning to an application. It does _not_ mean that the value is random nor that it could have been leaked from other contexts, processes, or memory other than the framebuffer attachments. + +== Further Functionality + +=== Fragment Shading Rate interactions + +With `VK_KHR_fragment_shading_rate` multi-pixel fragments read some implementation-defined pixel from the input attachments. We could define stronger requirements in this extension. + +=== Allow non-aliased Tile Image variables and/or image format redeclaration + +This would provide "Pixel local storage" equivalent functionality. + +A possible approach for that would be to specify the format as layout parameter - similar to image access: +[source,c] +---- +layout(r11f_g11f_b10f) tile readonly highp tileImage normal; +---- + +=== Tile Image size query + +If we were to allow non-aliased Tile Image variables, we would need to expose some limits on tile image size and tile dimensions so that applications can make performance trade-offs on tile size vs storage requirements. + +=== Memoryless attachments + +We have lazily allocated images in Vulkan, but they do not guarantee that memory is not allocated. diff --git a/scripts/genvk.py b/scripts/genvk.py index 5242036ed9..67cd8d08b5 100755 --- a/scripts/genvk.py +++ b/scripts/genvk.py @@ -364,10 +364,12 @@ def makeGenOpts(args): 'VK_KHR_video_encode_queue', 'VK_EXT_video_encode_h264', 'VK_EXT_video_encode_h265', + 'VK_NV_displacement_micromap', ] betaSuppressExtensions = [ - 'VK_KHR_video_queue' + 'VK_KHR_video_queue', + 'VK_EXT_opacity_micromap', ] platforms = [ diff --git a/xml/vk.xml b/xml/vk.xml index 7252b7ecdd..08b10a07ce 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -173,7 +173,7 @@ branch of the member gitlab server. #define VKSC_API_VERSION_1_0 VK_MAKE_API_VERSION(VKSC_API_VARIANT, 1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 245 +#define VK_HEADER_VERSION 246 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) // Version of this file @@ -474,6 +474,7 @@ typedef void* MTLSharedEvent_id; typedef VkFlags VkOpticalFlowExecuteFlagsNV; typedef VkFlags VkPresentScalingFlagsEXT; typedef VkFlags VkPresentGravityFlagsEXT; + typedef VkFlags VkShaderCreateFlagsEXT; Video Core extension typedef VkFlags VkVideoCodecOperationFlagsKHR; @@ -555,6 +556,7 @@ typedef void* MTLSharedEvent_id; VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkCuFunctionNVX) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkOpticalFlowSessionNV) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkMicromapEXT) + VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkShaderEXT) WSI extensions VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR) @@ -768,6 +770,8 @@ typedef void* MTLSharedEvent_id; + + WSI extensions @@ -5239,12 +5243,13 @@ typedef void* MTLSharedEvent_id; VkShaderStageFlags requiredSubgroupSizeStagesThe shader stages that support specifying a subgroup size - + VkStructureType sType void* pNext uint32_t requiredSubgroupSize + VkStructureType sType void* pNext @@ -7680,10 +7685,10 @@ typedef void* MTLSharedEvent_id; VkStructureType sType void* pNext - + VkFormat displacementBiasAndScaleFormat VkFormat displacementVectorFormat - + VkDeviceOrHostAddressConstKHR displacementBiasAndScaleBuffer VkDeviceSize displacementBiasAndScaleStride VkDeviceOrHostAddressConstKHR displacementVectorBuffer @@ -7693,13 +7698,13 @@ typedef void* MTLSharedEvent_id; VkIndexType indexType VkDeviceOrHostAddressConstKHR indexBuffer VkDeviceSize indexStride - + uint32_t baseTriangle - + uint32_t usageCountsCount const VkMicromapUsageEXT* pUsageCounts const VkMicromapUsageEXT* const* ppUsageCounts - + VkMicromapEXT micromap @@ -8126,6 +8131,47 @@ typedef void* MTLSharedEvent_id; VkMemoryUnmapFlagsKHR flags VkDeviceMemory memory + + VkStructureType sType + void* pNext + VkBool32 shaderObject + + + VkStructureType sType + void* pNext + uint8_t shaderBinaryUUID[VK_UUID_SIZE] + uint32_t shaderBinaryVersion + + + VkStructureType sType + const void* pNext + VkShaderCreateFlagsEXT flags + VkShaderStageFlagBits stage + VkShaderStageFlags nextStage + VkShaderCodeTypeEXT codeType + size_t codeSize + const void* pCode + const char* pName + uint32_t setLayoutCount + const VkDescriptorSetLayout* pSetLayouts + uint32_t pushConstantRangeCount + const VkPushConstantRange* pPushConstantRanges + const VkSpecializationInfo* pSpecializationInfo + + + VkStructureType sType + void* pNext + VkBool32 shaderTileImageColorReadAccess + VkBool32 shaderTileImageDepthReadAccess + VkBool32 shaderTileImageStencilReadAccess + + + VkStructureType sType + void* pNext + VkBool32 shaderTileImageCoherentReadAccelerated + VkBool32 shaderTileImageReadSampleFromPixelRateInvocation + VkBool32 shaderTileImageReadFromHelperInvocation + @@ -10156,6 +10202,19 @@ typedef void* MTLSharedEvent_id; + + + + + + + + + + + + + @@ -14000,6 +14059,34 @@ typedef void* MTLSharedEvent_id; VkDevice device const VkMemoryUnmapInfoKHR* pMemoryUnmapInfo + + VkResult vkCreateShadersEXT + VkDevice device + uint32_t createInfoCount + const VkShaderCreateInfoEXT* pCreateInfos + const VkAllocationCallbacks* pAllocator + VkShaderEXT* pShaders + + + void vkDestroyShaderEXT + VkDevice device + VkShaderEXT shader + const VkAllocationCallbacks* pAllocator + + + VkResult vkGetShaderBinaryDataEXT + VkDevice device + VkShaderEXT shader + size_t* pDataSize + void* pData + + + void vkCmdBindShadersEXT + VkCommandBuffer commandBuffer + uint32_t stageCount + const VkShaderStageFlagBits* pStages + const VkShaderEXT* pShaders + @@ -20756,10 +20843,14 @@ typedef void* MTLSharedEvent_id; - + - - + + + + + + @@ -21617,13 +21708,83 @@ typedef void* MTLSharedEvent_id; - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -23529,6 +23690,9 @@ typedef void* MTLSharedEvent_id; + + + @@ -24003,5 +24167,14 @@ typedef void* MTLSharedEvent_id; + + + + + + + + +