From 7f7686d7f2b7c6d780354ca544386476a04c17c4 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 5 Aug 2016 05:11:02 -0700 Subject: [PATCH] Change log for August 5, 2016 Vulkan 1.0.23 spec update: * Bump API patch number and header version number to 23 for this update. Github Issues: * Add explicit valid value attributes to pname:sType members in vk.xml (public issue 34). * Clarify usage of flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr (public issue 225). * Fix a copy-and-paste error in the description of pname:pSwapchainImageCount saying that it was the count of ``format pairs'' instead of ``swapchain images'' (public issue 292). * flink:vkCmdExecuteCommandBuffers requires all command buffers to be allocated from command pools created for the same queue family (public issue 296). * Remove bogus +optional+ attribute for flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml (public issue 301). * Clean up the <> reference and contents. Use full enumerant names. Refer to pname:layerCount in the ``view parameters'' column instead of pname:arrayLayers. Require N >= 1 for the cube array subview row, not just arrayLayers >= 6 N (public issue 304). * Modify description of <> to be consistent with the description of <> (public issue 307). Internal Issues: * Describe remaining +vk_platform.h+ macros in the <> appendix (internal issue 6). * Clarify <> feature behavior; what memory can be accessed, how bounds checking is performed, and allowing for vectorization (internal issue 332). * Document markup for automatic extraction of reference pages from the spec sources in the style guide (internal issue 395). * Allow flink:vkCreateDisplayModeKHR to return ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode parameters that the specified display does not support (internal issue 411). * Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and more clearly remove the subroutine keyword alongside it (internal issue 421). * Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets not contained in the layout (internal issue 427). Other Commits: * Change the order in which members of sname:VkAttachmentDescription and sname:VkPipelineInputAssemblyStateCreateInfo are described to match their order in the structures. --- doc/specs/misc/GL_KHR_vulkan_glsl.txt | 81 +++++---- doc/specs/vulkan/Makefile | 2 +- .../vulkan/api/defines/VK_HEADER_VERSION.txt | 2 +- doc/specs/vulkan/appendices/boilerplate.txt | 87 ++++++++++ doc/specs/vulkan/appendices/extensions.txt | 2 +- doc/specs/vulkan/appendices/glossary.txt | 4 +- doc/specs/vulkan/appendices/spirvenv.txt | 2 +- doc/specs/vulkan/chapters/cmdbuffers.txt | 2 +- doc/specs/vulkan/chapters/copies.txt | 2 +- doc/specs/vulkan/chapters/descriptorsets.txt | 4 +- doc/specs/vulkan/chapters/drawing.txt | 4 +- doc/specs/vulkan/chapters/extensions.txt | 2 +- doc/specs/vulkan/chapters/features.txt | 63 ++++++- doc/specs/vulkan/chapters/initialization.txt | 76 +++++---- doc/specs/vulkan/chapters/renderpass.txt | 14 +- doc/specs/vulkan/chapters/resources.txt | 68 ++++---- doc/specs/vulkan/chapters/synchronization.txt | 2 +- doc/specs/vulkan/genRef.py | 47 +++++- doc/specs/vulkan/man/PFN_vkVoidFunction.txt | 4 +- .../vulkan/man/VkAttachmentDescription.txt | 14 +- doc/specs/vulkan/man/VkBufferImageCopy.txt | 2 +- .../man/VkDescriptorSetLayoutBinding.txt | 2 +- .../vulkan/man/VkImageViewCreateInfo.txt | 63 +++---- .../vulkan/man/VkPhysicalDeviceFeatures.txt | 63 ++++++- ...VkPipelineInputAssemblyStateCreateInfo.txt | 4 +- .../vulkan/man/vkAllocateDescriptorSets.txt | 2 +- doc/specs/vulkan/man/vkCreateCommandPool.txt | 2 +- doc/specs/vulkan/man/vkGetDeviceProcAddr.txt | 31 ++-- .../vulkan/man/vkGetInstanceProcAddr.txt | 43 +++-- doc/specs/vulkan/style/writing.txt | 130 +++++++++++---- doc/specs/vulkan/styleguide.txt | 2 + .../protos/vkCmdBindDescriptorSets.txt | 1 + .../validity/protos/vkCmdExecuteCommands.txt | 1 + .../validity/protos/vkGetInstanceProcAddr.txt | 2 - .../structs/VkImageViewCreateInfo.txt | 2 +- src/spec/README | 41 ++--- src/spec/registry.rnc | 4 + src/spec/registry.txt | 3 + src/spec/validitygenerator.py | 89 +++++----- src/spec/vk.xml | 154 +++++++++--------- src/vulkan/vulkan.h | 2 +- 41 files changed, 749 insertions(+), 376 deletions(-) diff --git a/doc/specs/misc/GL_KHR_vulkan_glsl.txt b/doc/specs/misc/GL_KHR_vulkan_glsl.txt index d6b5ef0c12..835d4ac2c6 100644 --- a/doc/specs/misc/GL_KHR_vulkan_glsl.txt +++ b/doc/specs/misc/GL_KHR_vulkan_glsl.txt @@ -33,8 +33,8 @@ Status Version - Last Modified Date: 20-Jul-2016 - Revision: 31 + Last Modified Date: 1-Aug-2016 + Revision: 32 Number @@ -62,7 +62,7 @@ Overview The following features are removed: * default uniforms (uniform variables not inside a uniform block), except for opaque types - * atomic-counter bindings: atomic counters form a one-dimensional space + * atomic-counters (those based on atomic_uint) * subroutines * shared and packed block layouts * the already deprecated texturing functions (e.g., texture2D()) @@ -219,7 +219,7 @@ Overview The constant_id can only be applied to a scalar *int*, a scalar *float* or a scalar *bool*. - + Only basic operators and constructors can be applied to a specialization constant and still result in a specialization constant: @@ -324,7 +324,7 @@ Overview in / out variable -> Input/Output, possibly with block (below) in / out block... -> Input/Output, with Block decoration buffer blockN { ... } ...; -> Uniform, with BufferBlock decoration - ... uniform atomic_uint ... -> AtomicCounter + N/A -> AtomicCounter shared -> Workgroup -> Private @@ -417,7 +417,7 @@ Overview Mapping of layouts std140/std430 -> explicit offsets/strides on struct - shared/packed -> not allowed + shared/packed -> not allowed -> not shared, but std140 or std430 max_vertices -> OutputVertices @@ -426,13 +426,13 @@ Overview % -> OpUMod/OpSMod mod() -> OpFMod - NA -> OpSRem/OpFRem + N/A -> OpSRem/OpFRem atomicExchange() -> OpAtomicExchange imageAtomicExchange() -> OpAtomicExchange atomicCompSwap() -> OpAtomicCompareExchange imageAtomicCompSwap() -> OpAtomicCompareExchange - NA -> OpAtomicCompareExchangeWeak + N/A -> OpAtomicCompareExchangeWeak Changes to Chapter 1 of the OpenGL Shading Language Specification @@ -442,7 +442,7 @@ Changes to Chapter 1 of the OpenGL Shading Language Specification Add a paragraph: "The Vulkan API will specify the Vulkan entry points used to manipulate SPIR-V shaders. Independent offline tool chains will compile - GLSL down to the SPIR-V intermediate language. Vulkan use is not enabled + GLSL down to the SPIR-V intermediate language. Vulkan use is not enabled with a #extension, #version, or a profile. Instead, use of GLSL for Vulkan is determined by offline tool-chain use. See the documentation of such tools to see how to request generation of SPIR-V for Vulkan." @@ -480,7 +480,7 @@ Changes to Chapter 3 of the OpenGL Shading Language Specification textureCube texture2DRect texture1DArray texture2DArray textureBuffer texture2DMS texture2DMSArray textureCubeArray - + itexture1D itexture2D itexture3D itextureCube itexture2DRect itexture1DArray itexture2DArray itextureBuffer @@ -497,10 +497,17 @@ Changes to Chapter 3 of the OpenGL Shading Language Specification subpassInput isubpassInput usubpassInput subpassInputMS isubpassInputMS usubpassInputMS + Move the following keywords in section 3.6 Keywords to the reserved + section: + + atomic_uint + subroutine + Changes to Chapter 4 of the OpenGL Shading Language Specification - Add into the tables in section 4.1, interleaved with the existing types, - using the existing descriptions (when not supplied below): + Add into the tables in section 4.1 Basic Types, interleaved with the + existing types, using the existing descriptions (when not supplied + below): Floating-Point Opaque Types @@ -555,6 +562,10 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification usubpassInputMS | a handle for accessing a multi-sampled unsigned | integer subpass input + Remove the entry from the table in section 4.1 Basic Types: + + atomic_uint + Add a new category in this section "Sampler Opaque Types @@ -590,7 +601,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification and unsigned integer data types. Textures can be combined with a variable of type *sampler* or *samplerShadow* to create a sampler type (e.g., sampler2D, or sampler2DShadow). This is done with a constructor, - e.g., sampler2D(texture2D, sampler) or + e.g., sampler2D(texture2D, sampler) or sampler2DShadow(texture2D, samplerShadow), and is described in more detail in section 5.4 "Constructors"." @@ -608,11 +619,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification "Subpass input types are only available in fragment shaders. It is a compile-time error to use them in any other stage." - Add to section 4.1.7.3 Atomic Counters: - - "It is an error to declare an atomic type with a different precision or - to specify the default precision for an atomic type to be lowp or - mediump." + Remove the section 4.1.7.3 Atomic Counters Change section 4.3.3 Constant Expressions: @@ -723,14 +730,14 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification returned for the lowerleft-most pixel in a window. The origin can be changed by redeclaring gl_FragCoord with the origin_upper_left identifier." - + To "The gl_FragCoord built-in variable assumes an upper-left origin for window coordinates ... For example, the (x, y) location (0.5, 0.5) is returned for the upper-left-most pixel in a window. The origin can be explicitly set by redeclaring gl_FragCoord with the origin_upper_left - identifier. It is a compile-time error to change it to + identifier. It is a compile-time error to change it to origin_lower_left." Add to the end of section 4.4.3 Uniform Variable Layout Qualifiers: @@ -765,6 +772,9 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification "It is a compile-time error for either the /set/ or /binding/ value to exceed a front-end-configuration supplied maximum value." + Remove mention of subroutine throughout section 4.4 Layout Qualifiers, + including removal of section 4.4.4 Subroutine Function Layout Qualifiers. + Change section 4.4.6 Opaque-Uniform Layout Qualifiers: Change @@ -779,6 +789,8 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification takes just the provided binding number. The next consecutive binding number is available for a different object." + Remove section 4.4.6.1 Atomic Counter Layout Qualifiers + Add a new subsection at the end of section 4.4: "4.4.x Specialization-Constant Qualifier @@ -809,22 +821,22 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification "The built-in constant vector gl_WorkGroupSize can be specialized using the local_size_{xyz}_id qualifiers, to individually give the components an id. For example: - + layout(local_size_x_id = 18, local_size_z_id = 19) in; "This leaves gl_WorkGroupSize.y as a non-specialization constant, with gl_WorkGroupSize being a partially specialized vector. Its x and z components can be later specialized using the ids 18 and 19. These ids are declared independently from declaring the work-group size: - + layout(local_size_x = 32, local_size_y = 32) in; // size is (32,32,1) layout(local_size_x_id = 18) in; // constant_id for x layout(local_size_z_id = 19) in; // constant_id for z - + "Existing rules for declaring local_size_x, local_size_y, and local_size_z are not changed by this extension. For the local-size ids, it is a compile-time error to provide different id values for the same - local-size id, or to provide them after any use. Otherwise, order, + local-size id, or to provide them after any use. Otherwise, order, placement, number of statements, and replication do not cause errors. "Two arrays sized with specialization constants are the same type only if @@ -871,7 +883,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification in the implicit input_attachment_index consumed by array declarations. "It is a compile-time error if the value assigned to an - input_attachment_index is greater than or equal to + input_attachment_index is greater than or equal to gl_MaxInputAttachments." Remove all mention of the 'shared' and 'packed' layout qualifiers. @@ -1023,6 +1035,11 @@ Changes to Chapter 5 of the OpenGL Shading Language Specification * logical operations ( && , || , ^^ ) * comparison ( == , != ) +Changes to Chapter 6 of the OpenGL Shading Language Specification + + Remove mention of subroutine throughout, including removal of + section 6.1.2 Subroutines. + Changes to Chapter 7 of the OpenGL Shading Language Specification Changes to section 7.1 Built-In Language Variables @@ -1100,11 +1117,10 @@ Changes to Chapter 8 of the OpenGL Shading Language Specification - For prototypes that do specify a resulting precision qualifier, the specified precision qualifier is the precision qualification of - the result." + the result." Add precision qualifiers to the following in desktop versions: - genIType floatBitsToInt (highp genFType value) genUType floatBitsToUint(highp genFType value) genFType intBitsToFloat (highp genIType value) @@ -1134,6 +1150,8 @@ Changes to Chapter 8 of the OpenGL Shading Language Specification void imulExtended(highp genIType x, highp genIType y, out highp genIType msb, out highp genIType lsb) + Remove section 8.10 Atomic-Counter Functions + Add a section "8.X Subpass Functions @@ -1161,7 +1179,7 @@ Changes to the grammar | LEFT_BRACKET constant_expression RIGHT_BRACKET - to + to | LEFT_BRACKET conditional_expression RIGHT_BRACKET @@ -1169,10 +1187,14 @@ Changes to the grammar | array_specifier LEFT_BRACKET constant_expression RIGHT_BRACKET - to + to | array_specifier LEFT_BRACKET conditional_expression RIGHT_BRACKET + Remove the ATOMIC_UINT type_specifier_nonarray. + + Remove all instances of the SUBROUTINE keyword. + Issues 1. Can we have specialization sizes in an array in a block? That prevents @@ -1286,6 +1308,7 @@ Revision History Rev. Date Author Changes ---- ----------- ------- -------------------------------------------- + 32 1-Aug-2016 JohnK Remove atomic_uint and more fully subroutine 31 20-Jul-2016 JohnK Have desktop versions respect mediump/lowp 30 12-Apr-2016 JohnK Restrict spec-const operations to non-float 29 5-Apr-2016 JohnK Clarify disallowance of spec-const arrays in diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index f042b8ba2b..e8f9e6bc88 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -134,7 +134,7 @@ GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker COMMONDOCS = $(CHAPTERS) $(GENINCLUDE) $(GENDEPENDS) # A generated included file with the spec version, date, and git commit SPECVERSION = specversion.txt -SPECREVISION = 1.0.22 +SPECREVISION = 1.0.23 SPECREMARK = # Spec targets diff --git a/doc/specs/vulkan/api/defines/VK_HEADER_VERSION.txt b/doc/specs/vulkan/api/defines/VK_HEADER_VERSION.txt index 37a8f59feb..0a1c0e4f08 100644 --- a/doc/specs/vulkan/api/defines/VK_HEADER_VERSION.txt +++ b/doc/specs/vulkan/api/defines/VK_HEADER_VERSION.txt @@ -8,6 +8,6 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] ------------------------------------------------------------------------------ // Version of this file -#define VK_HEADER_VERSION 22 +#define VK_HEADER_VERSION 23 ------------------------------------------------------------------------------ diff --git a/doc/specs/vulkan/appendices/boilerplate.txt b/doc/specs/vulkan/appendices/boilerplate.txt index 87e837a551..786eb9daae 100644 --- a/doc/specs/vulkan/appendices/boilerplate.txt +++ b/doc/specs/vulkan/appendices/boilerplate.txt @@ -225,3 +225,90 @@ handle. It may be passed to and returned from Vulkan commands only when include::../api/defines/VK_NULL_HANDLE.txt[] // refEnd VK_NULL_HANDLE + + +[[boilerplate-platform-macros]] +== Platform-Specific Macro Definitions in +vk_platform.h+ + +In addition to the macros described for +vulkan.h+, platform-specific macros +specified and used in the included +vk_platform.h+ file are described in +this section. These macros are specifically used to control +platform-dependent behavior and their exact definitions are under the +control of specific platforms and Vulkan implementations. + + +=== Platform-Specific Calling Conventions + +// @refBegin VKAPI_ATTR - Vulkan function attributes + +dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API +function declarations. If not empty, the interpretation of this macro +depends on the platform and compiler in use, but normally controls calling +conventions for C++11 and GCC/Clang-style compilers. + +// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR + +// @refBegin VKAPI_CALL - Vulkan function calling conventions + +dname:VKAPI_CALL is a macro placed after the return type in Vulkan API +function declarations. If not empty, the interpretation of this macro +depends on the platform and compiler in use, but normally controls calling +conventions for MSVC-style compilers. + +// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR + +// @refBegin VKAPI_PTR - Vulkan function pointer calling conventions + +dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API +function pointer declarations. If not empty, the interpretation of this +macro depends on the platform and compiler in use, and normally controls +calling conventions. dname:VKAPI_PTR typically has the same definition as +dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the compiler. + +// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL + + +=== Platform-Specific Header Control + +// @refBegin VK_NO_STDINT_H - control definition of ++ types + +If the +VK_NO_STDINT_H+ macro is defined at compile time, it indicates that +the system ++ does not define some required integer types, and ++vk_platform.h+ will declare fallback definitions of those types. This is +included for backwards compatibility with very old compilers, such as +Microsoft Visual Studio version 2008 or before. + +// @refEnd VK_NO_STDINT_H + + +=== Window System-Specific Header Control + +// @refBegin WSIheaders - control inclusion of window system interface extensions + +When using different window systems with Khronos extensions, header files +for those window systems must: be included at compile time in order for the +corresponding extension definitions to compile. The Vulkan header files +cannot determine whether or not an external header is available at compile +time, so applications must: include macros enabling those headers. If this is +not done, the corresponding extension interfaces will not be defined and +they will be unusable. + +The extensions, required compile-time symbols to enable them, and window +systems they correspond to are defined in the +<>. + + +[[boilerplate-wsi-header-table]] +.Window System Extensions and Required Compile-Time Symbol Definitions +[options="header"] +|==== +| Extension Name | Required Compile-Time Symbol | Window System Name +| +VK_KHR_xlib_surface+ | +VK_USE_PLATFORM_XLIB_KHR+ | X11 Xlib library +| +VK_KHR_xcb_surface+ | +VK_USE_PLATFORM_XCB_KHR+ | X11 Xcb library +| +VK_KHR_wayland_surface+ | +VK_USE_PLATFORM_WAYLAND_KHR+ | Wayland +| +VK_KHR_mir_surface+ | +VK_USE_PLATFORM_MIR_KHR+ | Mir +| +VK_KHR_android_surface+ | +VK_USE_PLATFORM_ANDROID_KHR+ | Android Native +| +VK_KHR_win32_surface+ | +VK_USE_PLATFORM_WIN32_KHR+ | Windows Win32 +|==== + +// @refEnd WSIheaders diff --git a/doc/specs/vulkan/appendices/extensions.txt b/doc/specs/vulkan/appendices/extensions.txt index 4aee597c95..a303cd2969 100644 --- a/doc/specs/vulkan/appendices/extensions.txt +++ b/doc/specs/vulkan/appendices/extensions.txt @@ -22,5 +22,5 @@ specific Vulkan extensions and layers, but rather specifies the processes by which extensions and layers are created. As of version 1.0.21 of the Vulkan Specification, this content has been migrated to the <> -document. Authors creating extensions and layers must follow the mandatory +document. Authors creating extensions and layers must: follow the mandatory procedures in that document. diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt index 01d393eeb5..6d47f896e5 100644 --- a/doc/specs/vulkan/appendices/glossary.txt +++ b/doc/specs/vulkan/appendices/glossary.txt @@ -471,7 +471,7 @@ Memory Dependency:: A sequence of operations that makes writes available, performs an execution dependency between the writes and subsequent accesses, and makes available writes visible to later accesses. In order for the - effects of a write to be coherent with later accesses, it must be made + effects of a write to be coherent with later accesses, it must: be made available from the old access type and then made visible to the new access type. @@ -484,7 +484,7 @@ Memory Type:: Mip Tail Region:: The set of mipmap levels of a sparse residency texture that are too - small to fill a sparse block, and that must all be bound to memory + small to fill a sparse block, and that must: all be bound to memory collectively and opaquely. Non-Dispatchable Handle:: diff --git a/doc/specs/vulkan/appendices/spirvenv.txt b/doc/specs/vulkan/appendices/spirvenv.txt index 068e916730..af137af340 100644 --- a/doc/specs/vulkan/appendices/spirvenv.txt +++ b/doc/specs/vulkan/appendices/spirvenv.txt @@ -92,7 +92,7 @@ A SPIR-V module passed to flink:vkCreateShaderModule must: conform to the following rules: * Every entry point must: have no return value and accept no arguments. - * Recursion: The static function-call graph for an entry point must not contain cycles. + * Recursion: The static function-call graph for an entry point mustnot: contain cycles. * The *Logical* addressing model must: be selected. * *Scope* for execution must: be limited to: ** *Workgroup* diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt index 96e8533e0f..00e6aab5b5 100644 --- a/doc/specs/vulkan/chapters/cmdbuffers.txt +++ b/doc/specs/vulkan/chapters/cmdbuffers.txt @@ -100,7 +100,7 @@ include::../api/protos/vkCreateCommandPool.txt[] * pname:pCreateInfo contains information used to create the command pool. * pname:pAllocator controls host memory allocation as described in the <> chapter. - * pname:pCommandPool points to an sname:VkCommandPool handle in which the + * pname:pCommandPool points to a sname:VkCommandPool handle in which the created pool is returned. include::../validity/protos/vkCreateCommandPool.txt[] diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index c2d9fcac8d..d9cafdefad 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -282,7 +282,7 @@ include::../api/structs/VkBufferImageCopy.txt[] in buffer memory. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the pname:imageExtent. - * pname:imageSubresource is an slink:VkImageSubresourceLayers used to + * pname:imageSubresource is a slink:VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. * pname:imageOffset selects the initial x, y, z offsets in texels of the diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt index 1ef8c0d4fd..c0c37a7385 100644 --- a/doc/specs/vulkan/chapters/descriptorsets.txt +++ b/doc/specs/vulkan/chapters/descriptorsets.txt @@ -598,7 +598,7 @@ include::../api/structs/VkDescriptorSetLayoutBinding.txt[] * pname:binding is the binding number of this entry and corresponds to a resource of the same binding number in the shader stages. - * pname:descriptorType is an elink:VkDescriptorType specifying which type + * pname:descriptorType is a elink:VkDescriptorType specifying which type of resource descriptors are used for this binding. * pname:descriptorCount is the number of descriptors contained in the binding, accessed in a shader as an array. If pname:descriptorCount is @@ -1228,7 +1228,7 @@ behavior. This means applications need not populate unused entries with dummy descriptors. If an allocation fails due to fragmentation, an indeterminate error is -returned with an unspecified error code. Any returned error other than +returned with an unspecified error code. Any returned error other than ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: applications should: assume that the allocation failed due to fragmentation, and create a new descriptor pool. diff --git a/doc/specs/vulkan/chapters/drawing.txt b/doc/specs/vulkan/chapters/drawing.txt index edc80a948d..60b7544671 100644 --- a/doc/specs/vulkan/chapters/drawing.txt +++ b/doc/specs/vulkan/chapters/drawing.txt @@ -24,6 +24,8 @@ include::../api/structs/VkPipelineInputAssemblyStateCreateInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is reserved for future use. + * pname:topology is a elink:VkPrimitiveTopology defining the primitive + topology, as described below. * pname:primitiveRestartEnable controls whether a special vertex index value is treated as restarting the assembly of primitives. This enable only applies to indexed draws (flink:vkCmdDrawIndexed and @@ -32,8 +34,6 @@ include::../api/structs/VkPipelineInputAssemblyStateCreateInfo.txt[] fname:vkCmdBindIndexBuffer is equal to ename:VK_INDEX_TYPE_UINT32, or 0xFFFF when pname:indexType is equal to ename:VK_INDEX_TYPE_UINT16. Primitive restart is not allowed for ``list'' topologies. - * pname:topology is a elink:VkPrimitiveTopology defining the primitive - topology, as described below. Restarting the assembly of primitives discards the most recent index values if those elements formed an incomplete primitive, and restarts the primitive diff --git a/doc/specs/vulkan/chapters/extensions.txt b/doc/specs/vulkan/chapters/extensions.txt index 94df199ebf..4d5c8d5c0b 100644 --- a/doc/specs/vulkan/chapters/extensions.txt +++ b/doc/specs/vulkan/chapters/extensions.txt @@ -14,7 +14,7 @@ or any of its child objects. Extensions can operate at either the instance or device scope. Enabled instance extensions are able to affect the operation of the instance and any of its child objects, while device extensions may: only be available on a subset of -physical devices, must be individually enabled per-device, and only affect the +physical devices, must: be individually enabled per-device, and only affect the operation of the devices where they are enabled. Examples of these might be: diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt index 5012368661..60b107ea19 100644 --- a/doc/specs/vulkan/chapters/features.txt +++ b/doc/specs/vulkan/chapters/features.txt @@ -89,21 +89,66 @@ The members of the sname:VkPhysicalDeviceFeatures structure describe the following features: * [[features-features-robustBufferAccess]] pname:robustBufferAccess - indicates that out of bounds accesses to buffers via shader operations - are well-defined. - ** When enabled, out-of-bounds buffer reads will return any of the - following values: - *** Values from anywhere within the buffer object. + indicates that accesses to buffers are bounds-checked against the range of + the buffer descriptor (as determined by + sname:VkDescriptorBufferInfo::pname:range, + sname:VkBufferViewCreateInfo::pname:range, or the size of the buffer). Out + of bounds accesses mustnot: cause application termination, and the effects + of shader loads, stores, and atomics must: conform to an + implementation-dependent behavior as described below. + ** A buffer access is considered to be out of bounds if any of the following + are true: + *** The pointer was formed by code:OpImageTexelPointer and the coordinate is + less than zero or greater than or equal to the number of whole elements + in the bound range. + *** The pointer was not formed by code:OpImageTexelPointer and the object + pointed to is not wholly contained within the bound range. ++ +-- +[NOTE] +.Note +==== +If a SPIR-V code:OpLoad instruction loads a structure and the tail end of the +structure is out of bounds, then all members of the structure are considered +out of bounds even if the members at the end are not statically used. +==== +-- ++ + *** If any buffer access in a given SPIR-V block is determined to be + out of bounds, then any other access of the same type (load, store, or + atomic) in the same SPIR-V block that accesses an address less + than 16 bytes away from the out of bounds address may: also be + considered out of bounds. + ** Out-of-bounds buffer loads will return any of the following values: + *** Values from anywhere within the memory range(s) bound to the buffer + (possibly including bytes of memory past the end of the buffer, up to + the end of the bound range). *** Zero values, or (0,0,0,x) vectors for vector reads where x is a valid value represented in the type of the vector components and may: be any of: **** 0, 1, or the maximum representable positive integer value, for signed or unsigned integer components **** 0.0 or 1.0, for floating-point components - ** When enabled, out-of-bounds writes may: modify values within the buffer - object or be ignored. - ** If not enabled, out of bounds accesses may: cause undefined behaviour - up-to and including process termination. + ** Out-of-bounds writes may: modify values within the memory range(s) bound + to the buffer, but mustnot: modify any other memory. + ** Out-of-bounds atomics may: modify values within the memory range(s) bound + to the buffer, but mustnot: modify any other memory, and return an + undefined value. + ** Vertex input attributes are considered out of bounds if the address of the + attribute plus the size of the attribute is greater than the size of the + bound buffer. Further, if any vertex input attribute using a specific + vertex input binding is out of bounds, then all vertex input attributes + using that vertex input binding for that vertex shader invocation are + considered out of bounds. + *** If a vertex input attribute is out of bounds, it will be assigned one + of the following values: + **** Values from anywhere within the memory range(s) bound to the buffer, + converted according to the format of the attribute. + **** Zero values, format converted according to the format of the attribute. + **** Zero values, or (0,0,0,x) vectors, as described above. + ** If pname:robustBufferAccess is not enabled, out of bounds accesses may: + corrupt any memory within the process and cause undefined behaviour up + to and including application termination. * [[features-features-fullDrawIndexUint32]] pname:fullDrawIndexUint32 indicates the full 32-bit range of indices is supported for indexed draw calls when using a elink:VkIndexType of ename:VK_INDEX_TYPE_UINT32. diff --git a/doc/specs/vulkan/chapters/initialization.txt b/doc/specs/vulkan/chapters/initialization.txt index 84a5e72cc7..ee38ab1b0c 100644 --- a/doc/specs/vulkan/chapters/initialization.txt +++ b/doc/specs/vulkan/chapters/initialization.txt @@ -19,7 +19,7 @@ command: include::../api/protos/vkGetInstanceProcAddr.txt[] * pname:instance is the instance that the function pointer will be - compatible with. + compatible with, or `NULL` for commands not dependent on any instance. * pname:pName is the name of the command to obtain. fname:vkGetInstanceProcAddr itself is obtained in a platform- and loader- @@ -30,25 +30,36 @@ Loaders are encouraged to export function symbols for all other core Vulkan commands as well; if this is done, then applications that use only the core Vulkan commands have no need to use fname:vkGetInstanceProcAddr. -Function pointers to commands that do not operate on a specific instance can: -be obtained by using this command with pname:instance equal to `NULL`. The -following commands can: be accessed this way: - - * flink:vkEnumerateInstanceExtensionProperties - * flink:vkEnumerateInstanceLayerProperties - * flink:vkCreateInstance +The table below defines the various use cases for fname:vkGetInstanceProcAddr +and expected return value ("fp" is function pointer) for each case. The returned function pointer is of type tlink:PFN_vkVoidFunction, and must be cast to the type of the command being queried. -If pname:instance is a valid sname:VkInstance, function pointers to any -commands that operate on pname:instance or a child of pname:instance can: be -obtained. The returned function pointer must: only be called with a -dispatchable object (the first parameter) that is a child of pname:instance. - -If pname:pName is not the name of a core Vulkan command, or is an -extension command for any extension not supported by any available layer or -implementation, then fname:vkGetInstanceProcAddr will return `NULL`. +.vkGetInstanceProcAddr behavior +[width="80%",options="header",align="center"] +|===== +| pname:instance | pname:pName | return value +| * | NULL | undefined +| invalid instance | * | undefined +| NULL | flink:vkEnumerateInstanceExtensionProperties | fp +| NULL | flink:vkEnumerateInstanceLayerProperties | fp +| NULL | flink:vkCreateInstance | fp +| NULL | * (any pname:pName not covered above) | NULL +| instance | core Vulkan command | fp^1^ +| instance | enabled instance extension commands for pname:instance | fp^1^ +| instance | available device extension commands for pname:instance | fp^1,2^ +| instance | * (any pname:pName not covered above) | NULL +|===== + +1:: +The returned function pointer must: only be called with a dispatchable object +(the first parameter) that is a child of pname:instance. + e.g. sname:VkInstance, sname:VkPhysicalDevice, sname:VkDevice, sname:VkQueue, or + sname:VkCommandBuffer. + +2:: +available extension is an extension function supported by any of the loader, ICD or layer. ifdef::editing-notes[] [NOTE] @@ -87,29 +98,36 @@ command: include::../api/protos/vkGetDeviceProcAddr.txt[] - * pname:device is the logical device that provides the function pointer. - * pname:pName is the name of any Vulkan command whose first parameter - is one of - ** sname:VkDevice - ** sname:VkQueue - ** sname:VkCommandBuffer +The table below defines the various use cases for fname:vkGetDeviceProcAddr +and expected return value for each case. The returned function pointer is of type tlink:PFN_vkVoidFunction, and must be cast to the type of the command being queried. -If pname:pName is not the name of one of these Vulkan commands, and is -not the name of an extension command belonging to an extension enabled for -pname:device, then fname:vkGetDeviceProcAddr will return `NULL`. +.vkGetDeviceProcAddr behavior +[width="80%",options="header",align="center"] +|===== +| pname:device | pname:pName | return value +| NULL | * | undefined +| invalid device | * | undefined +| device | NULL | undefined +| device | core Vulkan command^1^ | fp +| device | enabled device extension commands for pname:device | fp +| device | * (any pname:pName not covered above) | NULL +|===== + +1:: +pname:pName is the name of any Vulkan command whose first parameter + is sname:VkDevice or any of its dispatchable children (e.g. sname:VkQueue, + sname:vkCommandBuffer). include::../validity/protos/vkGetDeviceProcAddr.txt[] -// refEnd vkGetInstanceProcAddr PFN_vkVoidFunction +// refEnd vkGetDeviceProcAddr PFN_vkVoidFunction // refBegin PFN_vkVoidFunction Dummy function pointer type returned by queries -The function pointer type returned from the flink:vkGetInstanceProcAddr and -flink:vkGetDeviceProcAddr is a dummy type not corresponding to any actual -Vulkan function: +The definition of tlink:PFN_vkVoidFunction is: include::../api/funcpointers/PFN_vkVoidFunction.txt[] diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index 8564481b9e..9a1e5fbaaa 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -145,6 +145,13 @@ The sname:VkAttachmentDescription structure is defined as: include::../api/structs/VkAttachmentDescription.txt[] + * pname:flags is a bitmask describing additional properties of the + attachment. Bits which can: be set include: ++ +-- +// refBegin VkAttachmentDescriptionFlagBits - Bitmask specifying additional properties of an attachment +include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] +-- * pname:format is a elink:VkFormat value specifying the format of the image that will be used for the attachment. * pname:samples is the number of samples of the image as defined @@ -196,13 +203,6 @@ include::../api/enums/VkAttachmentStoreOp.txt[] transitioned to when a render pass instance ends. During a render pass instance, an attachment can: use a different layout in each subpass, if desired. - * pname:flags is a bitmask describing additional properties of the - attachment. Bits which can: be set include: -+ --- -// refBegin VkAttachmentDescriptionFlagBits - Bitmask specifying additional properties of an attachment -include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] --- If the attachment uses a color format, then pname:loadOp and pname:storeOp are used, and pname:stencilLoadOp and pname:stencilStoreOp are ignored. If diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index d371040061..9d2d753d36 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -743,7 +743,8 @@ include::../api/structs/VkImageViewCreateInfo.txt[] * pname:components specifies a remapping of color components (or of depth or stencil components after they have been converted into color components). See slink:VkComponentMapping. - * pname:subresourceRange selects the set of mipmap levels and array layers + * pname:subresourceRange is a slink:VkImageSubresourceRange + selecting the set of mipmap levels and array layers to be accessible to the view. If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT @@ -758,101 +759,101 @@ Classes>> section. |======================================== | Dim, Arrayed, MS | Image parameters | View parameters | 1D, 0, 0 | -imageType = IMAGE_TYPE_1D + +imageType = ename:VK_IMAGE_TYPE_1D + width >= 1 + height = 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_1D + +viewType = ename:VK_VIEW_TYPE_1D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 1D, 1, 0 | -imageType = IMAGE_TYPE_1D + +imageType = ename:VK_IMAGE_TYPE_1D + width >= 1 + height = 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_1D_ARRAY + +viewType = ename:VK_VIEW_TYPE_1D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | 2D, 0, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_2D + +viewType = ename:VK_VIEW_TYPE_2D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 2D, 1, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_2D_ARRAY + +viewType = ename:VK_VIEW_TYPE_2D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | 2D, 0, 1 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples > 1 | -viewType = VIEW_TYPE_2D + +viewType = ename:VK_VIEW_TYPE_2D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 2D, 1, 1 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples > 1 | -viewType = VIEW_TYPE_2D_ARRAY + +viewType = ename:VK_VIEW_TYPE_2D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | CUBE, 0, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height = width + depth = 1 + arrayLayers >= 6 + samples = 1 + flags include ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -viewType = VIEW_TYPE_CUBE + +viewType = ename:VK_VIEW_TYPE_CUBE + baseArrayLayer >= 0 + -arrayLayers = 6 +layerCount = 6 | CUBE, 1, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height = width + depth = 1 + -arrayLayers >= 6×N + +N >= 1 + +arrayLayers >= latexmath:[$6 \times N$] + samples = 1 + flags include ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -viewType = VIEW_TYPE_CUBE_ARRAY + +viewType = ename:VK_VIEW_TYPE_CUBE_ARRAY + baseArrayLayer >= 0 + -arrayLayers = 6×N +N >= 1 + +layerCount = latexmath:[$6 \times N$] | 3D, 0, 0 | -imageType = IMAGE_TYPE_3D + +imageType = ename:VK_IMAGE_TYPE_3D + width >= 1 + height >= 1 + depth >= 1 + arrayLayers = 1 + samples = 1 | -viewType = VIEW_TYPE_3D + +viewType = ename:VK_VIEW_TYPE_3D + baseArrayLayer = 0 + -arrayLayers = 1 +layerCount = 1 |======================================== -The pname:subresourceRange member is of type slink:VkImageSubresourceRange. - include::../validity/structs/VkImageViewCreateInfo.txt[] // refBegin VkImageSubresourceRange - Structure specifying a image subresource range @@ -1284,9 +1285,10 @@ multiple resources simultaneously, via flink:vkBindImageMemory, flink:vkBindBufferMemory, or via <>. A memory range aliased between two images or two buffers is defined to be the intersection of the memory ranges bound to the two -resources. A memory range aliased between an image and a buffer is defined +resources. A memory range aliased between two resources where one is a +buffer or a linear image, and the other is an optimal image, is defined to be the intersection of the memory ranges bound to the two resources, -where each range is first bloated to be aligned to the +where each range is first padded to be aligned to the pname:bufferImageGranularity. Applications can: alias memory, but use of multiple aliases is subject to several constraints. diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt index 1bbaa78d6c..4731c886f5 100644 --- a/doc/specs/vulkan/chapters/synchronization.txt +++ b/doc/specs/vulkan/chapters/synchronization.txt @@ -334,7 +334,7 @@ operation. For example, a sname:VkImageMemoryBarrier could use: * pname:oldLayout = etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR * pname:newLayout = ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL -Alternativeely, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if +Alternatively, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if the image's contents need not be preserved. This barrier accomplishes a dependency chain between previous presentation diff --git a/doc/specs/vulkan/genRef.py b/doc/specs/vulkan/genRef.py index 510259de6a..1a07502fb5 100755 --- a/doc/specs/vulkan/genRef.py +++ b/doc/specs/vulkan/genRef.py @@ -89,6 +89,33 @@ def seeAlsoList(apiName, explicitRefs = None): else: return None +# Remap include directives in a list of lines so they can be extracted to a +# different directory. Returns remapped lines. +# +# lines - text to remap +# baseDir - target directory +# specDir - source directory +def remapIncludes(lines, baseDir, specDir): + # This should be compiled only once + includePat = re.compile('^include::(?P.*)\[\]') + + newLines = [] + for line in lines: + matches = includePat.search(line) + if (matches != None): + path = matches.group('path') + + # Relative path to include file from here + incPath = specDir + '/' + path + # Remap to be relative to baseDir + newPath = os.path.relpath(incPath, baseDir) + newLine = 'include::' + newPath + '[]\n' + logDiag('remapIncludes: remapping from:\n\t', line, 'to:\n\t', newLine) + newLines.append(newLine) + else: + newLines.append(line) + return newLines + # Generate header of a reference page # pageName - string name of the page # pageDesc - string short description of the page @@ -180,11 +207,12 @@ def refPageTail(pageName, seeAlso, fp, auto = False): printCopyrightBlock(fp, comment=False) -# Emit a single reference page in baseDir +# Extract a single reference page into baseDir # baseDir - base directory to emit page into +# specDir - directory extracted page source came from # pi - pageInfo for this page relative to file # file - list of strings making up the file, indexed by pi -def emitPage(baseDir, pi, file): +def emitPage(baseDir, specDir, pi, file): pageName = baseDir + '/' + pi.name + '.txt' fp = open(pageName, 'w') @@ -198,7 +226,8 @@ def emitPage(baseDir, pi, file): pi.desc = '(no short description available)' # Specification text - specText = ''.join(file[pi.begin:pi.include+1]) + lines = remapIncludes(file[pi.begin:pi.include+1], baseDir, specDir) + specText = ''.join(lines) # Member/parameter list, if there is one field = None @@ -211,10 +240,12 @@ def emitPage(baseDir, pi, file): else: logWarn('PyOutputGenerator::emitPage: unknown field type:', pi.type, 'for', pi.name) - fieldText = ''.join(file[pi.param:pi.body]) + lines = remapIncludes(file[pi.param:pi.body], baseDir, specDir) + fieldText = ''.join(lines) # Description text - descText = ''.join(file[pi.body:pi.end+1]) + lines = remapIncludes(file[pi.body:pi.end+1], baseDir, specDir) + descText = ''.join(lines) refPageHead(pi.name, pi.desc, @@ -350,6 +381,10 @@ def genRef(specFile, baseDir): file = loadFile(specFile) if (file == None): return + + # Save the path to this file for later use in rewriting relative includes + specDir = os.path.dirname(os.path.abspath(specFile)) + pageMap = findRefs(file) logDiag(specFile + ': found', len(pageMap.keys()), 'potential pages') @@ -369,7 +404,7 @@ def genRef(specFile, baseDir): logDiag('genRef:', pi.name + ':', pi.Warning) if (pi.extractPage): - emitPage(baseDir, pi, file) + emitPage(baseDir, specDir, pi, file) elif (pi.type == 'enums'): autoGenEnumsPage(baseDir, pi, file) elif (pi.type == 'flags'): diff --git a/doc/specs/vulkan/man/PFN_vkVoidFunction.txt b/doc/specs/vulkan/man/PFN_vkVoidFunction.txt index b3aa8ed53e..95cec3ac3b 100644 --- a/doc/specs/vulkan/man/PFN_vkVoidFunction.txt +++ b/doc/specs/vulkan/man/PFN_vkVoidFunction.txt @@ -14,9 +14,7 @@ C Specification // refBegin PFN_vkVoidFunction Dummy function pointer type returned by queries -The function pointer type returned from the flink:vkGetInstanceProcAddr and -flink:vkGetDeviceProcAddr is a dummy type not corresponding to any actual -Vulkan function: +The definition of tlink:PFN_vkVoidFunction is: include::../api/funcpointers/PFN_vkVoidFunction.txt[] diff --git a/doc/specs/vulkan/man/VkAttachmentDescription.txt b/doc/specs/vulkan/man/VkAttachmentDescription.txt index e129aa4b5e..b0c2c8e4f9 100644 --- a/doc/specs/vulkan/man/VkAttachmentDescription.txt +++ b/doc/specs/vulkan/man/VkAttachmentDescription.txt @@ -22,6 +22,13 @@ include::../api/structs/VkAttachmentDescription.txt[] Members ------- + * pname:flags is a bitmask describing additional properties of the + attachment. Bits which can: be set include: ++ +-- +// refBegin VkAttachmentDescriptionFlagBits - Bitmask specifying additional properties of an attachment +include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] +-- * pname:format is a elink:VkFormat value specifying the format of the image that will be used for the attachment. * pname:samples is the number of samples of the image as defined @@ -73,13 +80,6 @@ include::../api/enums/VkAttachmentStoreOp.txt[] transitioned to when a render pass instance ends. During a render pass instance, an attachment can: use a different layout in each subpass, if desired. - * pname:flags is a bitmask describing additional properties of the - attachment. Bits which can: be set include: -+ --- -// refBegin VkAttachmentDescriptionFlagBits - Bitmask specifying additional properties of an attachment -include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] --- Description diff --git a/doc/specs/vulkan/man/VkBufferImageCopy.txt b/doc/specs/vulkan/man/VkBufferImageCopy.txt index 880ebdc24c..0e3ece1403 100644 --- a/doc/specs/vulkan/man/VkBufferImageCopy.txt +++ b/doc/specs/vulkan/man/VkBufferImageCopy.txt @@ -31,7 +31,7 @@ Members in buffer memory. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the pname:imageExtent. - * pname:imageSubresource is an slink:VkImageSubresourceLayers used to + * pname:imageSubresource is a slink:VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data. * pname:imageOffset selects the initial x, y, z offsets in texels of the diff --git a/doc/specs/vulkan/man/VkDescriptorSetLayoutBinding.txt b/doc/specs/vulkan/man/VkDescriptorSetLayoutBinding.txt index c19c213f6e..45c8340485 100644 --- a/doc/specs/vulkan/man/VkDescriptorSetLayoutBinding.txt +++ b/doc/specs/vulkan/man/VkDescriptorSetLayoutBinding.txt @@ -24,7 +24,7 @@ Members * pname:binding is the binding number of this entry and corresponds to a resource of the same binding number in the shader stages. - * pname:descriptorType is an elink:VkDescriptorType specifying which type + * pname:descriptorType is a elink:VkDescriptorType specifying which type of resource descriptors are used for this binding. * pname:descriptorCount is the number of descriptors contained in the binding, accessed in a shader as an array. If pname:descriptorCount is diff --git a/doc/specs/vulkan/man/VkImageViewCreateInfo.txt b/doc/specs/vulkan/man/VkImageViewCreateInfo.txt index c0a90fabe9..633f54507f 100644 --- a/doc/specs/vulkan/man/VkImageViewCreateInfo.txt +++ b/doc/specs/vulkan/man/VkImageViewCreateInfo.txt @@ -32,7 +32,8 @@ Members * pname:components specifies a remapping of color components (or of depth or stencil components after they have been converted into color components). See slink:VkComponentMapping. - * pname:subresourceRange selects the set of mipmap levels and array layers + * pname:subresourceRange is a slink:VkImageSubresourceRange + selecting the set of mipmap levels and array layers to be accessible to the view. @@ -51,101 +52,101 @@ Classes>> section. |======================================== | Dim, Arrayed, MS | Image parameters | View parameters | 1D, 0, 0 | -imageType = IMAGE_TYPE_1D + +imageType = ename:VK_IMAGE_TYPE_1D + width >= 1 + height = 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_1D + +viewType = ename:VK_VIEW_TYPE_1D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 1D, 1, 0 | -imageType = IMAGE_TYPE_1D + +imageType = ename:VK_IMAGE_TYPE_1D + width >= 1 + height = 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_1D_ARRAY + +viewType = ename:VK_VIEW_TYPE_1D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | 2D, 0, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_2D + +viewType = ename:VK_VIEW_TYPE_2D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 2D, 1, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples = 1 | -viewType = VIEW_TYPE_2D_ARRAY + +viewType = ename:VK_VIEW_TYPE_2D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | 2D, 0, 1 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples > 1 | -viewType = VIEW_TYPE_2D + +viewType = ename:VK_VIEW_TYPE_2D + baseArrayLayer >= 0 + -arrayLayers = 1 +layerCount = 1 | 2D, 1, 1 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height >= 1 + depth = 1 + arrayLayers >= 1 + samples > 1 | -viewType = VIEW_TYPE_2D_ARRAY + +viewType = ename:VK_VIEW_TYPE_2D_ARRAY + baseArrayLayer >= 0 + -arrayLayers >= 1 +layerCount >= 1 | CUBE, 0, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height = width + depth = 1 + arrayLayers >= 6 + samples = 1 + flags include ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -viewType = VIEW_TYPE_CUBE + +viewType = ename:VK_VIEW_TYPE_CUBE + baseArrayLayer >= 0 + -arrayLayers = 6 +layerCount = 6 | CUBE, 1, 0 | -imageType = IMAGE_TYPE_2D + +imageType = ename:VK_IMAGE_TYPE_2D + width >= 1 + height = width + depth = 1 + -arrayLayers >= 6×N + +N >= 1 + +arrayLayers >= latexmath:[$6 \times N$] + samples = 1 + flags include ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | -viewType = VIEW_TYPE_CUBE_ARRAY + +viewType = ename:VK_VIEW_TYPE_CUBE_ARRAY + baseArrayLayer >= 0 + -arrayLayers = 6×N +N >= 1 + +layerCount = latexmath:[$6 \times N$] | 3D, 0, 0 | -imageType = IMAGE_TYPE_3D + +imageType = ename:VK_IMAGE_TYPE_3D + width >= 1 + height >= 1 + depth >= 1 + arrayLayers = 1 + samples = 1 | -viewType = VIEW_TYPE_3D + +viewType = ename:VK_VIEW_TYPE_3D + baseArrayLayer = 0 + -arrayLayers = 1 +layerCount = 1 |======================================== -The pname:subresourceRange member is of type slink:VkImageSubresourceRange. - include::../validity/structs/VkImageViewCreateInfo.txt[] diff --git a/doc/specs/vulkan/man/VkPhysicalDeviceFeatures.txt b/doc/specs/vulkan/man/VkPhysicalDeviceFeatures.txt index 80eb598f92..1f393038c2 100644 --- a/doc/specs/vulkan/man/VkPhysicalDeviceFeatures.txt +++ b/doc/specs/vulkan/man/VkPhysicalDeviceFeatures.txt @@ -30,21 +30,66 @@ Description ----------- * [[features-features-robustBufferAccess]] pname:robustBufferAccess - indicates that out of bounds accesses to buffers via shader operations - are well-defined. - ** When enabled, out-of-bounds buffer reads will return any of the - following values: - *** Values from anywhere within the buffer object. + indicates that accesses to buffers are bounds-checked against the range of + the buffer descriptor (as determined by + sname:VkDescriptorBufferInfo::pname:range, + sname:VkBufferViewCreateInfo::pname:range, or the size of the buffer). Out + of bounds accesses mustnot: cause application termination, and the effects + of shader loads, stores, and atomics must: conform to an + implementation-dependent behavior as described below. + ** A buffer access is considered to be out of bounds if any of the following + are true: + *** The pointer was formed by code:OpImageTexelPointer and the coordinate is + less than zero or greater than or equal to the number of whole elements + in the bound range. + *** The pointer was not formed by code:OpImageTexelPointer and the object + pointed to is not wholly contained within the bound range. ++ +-- +[NOTE] +.Note +==== +If a SPIR-V code:OpLoad instruction loads a structure and the tail end of the +structure is out of bounds, then all members of the structure are considered +out of bounds even if the members at the end are not statically used. +==== +-- ++ + *** If any buffer access in a given SPIR-V block is determined to be + out of bounds, then any other access of the same type (load, store, or + atomic) in the same SPIR-V block that accesses an address less + than 16 bytes away from the out of bounds address may: also be + considered out of bounds. + ** Out-of-bounds buffer loads will return any of the following values: + *** Values from anywhere within the memory range(s) bound to the buffer + (possibly including bytes of memory past the end of the buffer, up to + the end of the bound range). *** Zero values, or (0,0,0,x) vectors for vector reads where x is a valid value represented in the type of the vector components and may: be any of: **** 0, 1, or the maximum representable positive integer value, for signed or unsigned integer components **** 0.0 or 1.0, for floating-point components - ** When enabled, out-of-bounds writes may: modify values within the buffer - object or be ignored. - ** If not enabled, out of bounds accesses may: cause undefined behaviour - up-to and including process termination. + ** Out-of-bounds writes may: modify values within the memory range(s) bound + to the buffer, but mustnot: modify any other memory. + ** Out-of-bounds atomics may: modify values within the memory range(s) bound + to the buffer, but mustnot: modify any other memory, and return an + undefined value. + ** Vertex input attributes are considered out of bounds if the address of the + attribute plus the size of the attribute is greater than the size of the + bound buffer. Further, if any vertex input attribute using a specific + vertex input binding is out of bounds, then all vertex input attributes + using that vertex input binding for that vertex shader invocation are + considered out of bounds. + *** If a vertex input attribute is out of bounds, it will be assigned one + of the following values: + **** Values from anywhere within the memory range(s) bound to the buffer, + converted according to the format of the attribute. + **** Zero values, format converted according to the format of the attribute. + **** Zero values, or (0,0,0,x) vectors, as described above. + ** If pname:robustBufferAccess is not enabled, out of bounds accesses may: + corrupt any memory within the process and cause undefined behaviour up + to and including application termination. * [[features-features-fullDrawIndexUint32]] pname:fullDrawIndexUint32 indicates the full 32-bit range of indices is supported for indexed draw calls when using a elink:VkIndexType of ename:VK_INDEX_TYPE_UINT32. diff --git a/doc/specs/vulkan/man/VkPipelineInputAssemblyStateCreateInfo.txt b/doc/specs/vulkan/man/VkPipelineInputAssemblyStateCreateInfo.txt index 0777554f97..8b91dacef6 100644 --- a/doc/specs/vulkan/man/VkPipelineInputAssemblyStateCreateInfo.txt +++ b/doc/specs/vulkan/man/VkPipelineInputAssemblyStateCreateInfo.txt @@ -29,6 +29,8 @@ Members * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is reserved for future use. + * pname:topology is a elink:VkPrimitiveTopology defining the primitive + topology, as described below. * pname:primitiveRestartEnable controls whether a special vertex index value is treated as restarting the assembly of primitives. This enable only applies to indexed draws (flink:vkCmdDrawIndexed and @@ -37,8 +39,6 @@ Members fname:vkCmdBindIndexBuffer is equal to ename:VK_INDEX_TYPE_UINT32, or 0xFFFF when pname:indexType is equal to ename:VK_INDEX_TYPE_UINT16. Primitive restart is not allowed for ``list'' topologies. - * pname:topology is a elink:VkPrimitiveTopology defining the primitive - topology, as described below. Description diff --git a/doc/specs/vulkan/man/vkAllocateDescriptorSets.txt b/doc/specs/vulkan/man/vkAllocateDescriptorSets.txt index 0fe4d39007..2d91c23199 100644 --- a/doc/specs/vulkan/man/vkAllocateDescriptorSets.txt +++ b/doc/specs/vulkan/man/vkAllocateDescriptorSets.txt @@ -50,7 +50,7 @@ behavior. This means applications need not populate unused entries with dummy descriptors. If an allocation fails due to fragmentation, an indeterminate error is -returned with an unspecified error code. Any returned error other than +returned with an unspecified error code. Any returned error other than ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: applications should: assume that the allocation failed due to fragmentation, and create a new descriptor pool. diff --git a/doc/specs/vulkan/man/vkCreateCommandPool.txt b/doc/specs/vulkan/man/vkCreateCommandPool.txt index e82c7a164d..050f41d0aa 100644 --- a/doc/specs/vulkan/man/vkCreateCommandPool.txt +++ b/doc/specs/vulkan/man/vkCreateCommandPool.txt @@ -26,7 +26,7 @@ Parameters * pname:pCreateInfo contains information used to create the command pool. * pname:pAllocator controls host memory allocation as described in the <> chapter. - * pname:pCommandPool points to an sname:VkCommandPool handle in which the + * pname:pCommandPool points to a sname:VkCommandPool handle in which the created pool is returned. diff --git a/doc/specs/vulkan/man/vkGetDeviceProcAddr.txt b/doc/specs/vulkan/man/vkGetDeviceProcAddr.txt index c0c903c9fd..f3ff6f1b01 100644 --- a/doc/specs/vulkan/man/vkGetDeviceProcAddr.txt +++ b/doc/specs/vulkan/man/vkGetDeviceProcAddr.txt @@ -30,12 +30,8 @@ include::../api/protos/vkGetDeviceProcAddr.txt[] Parameters ---------- - * pname:device is the logical device that provides the function pointer. - * pname:pName is the name of any Vulkan command whose first parameter - is one of - ** sname:VkDevice - ** sname:VkQueue - ** sname:VkCommandBuffer +The table below defines the various use cases for fname:vkGetDeviceProcAddr +and expected return value for each case. Description @@ -44,17 +40,32 @@ Description The returned function pointer is of type tlink:PFN_vkVoidFunction, and must be cast to the type of the command being queried. -If pname:pName is not the name of one of these Vulkan commands, and is -not the name of an extension command belonging to an extension enabled for -pname:device, then fname:vkGetDeviceProcAddr will return `NULL`. +.vkGetDeviceProcAddr behavior +[width="80%",options="header",align="center"] +|===== +| pname:device | pname:pName | return value +| NULL | * | undefined +| invalid device | * | undefined +| device | NULL | undefined +| device | core Vulkan command^1^ | fp +| device | enabled device extension commands for pname:device | fp +| device | * (any pname:pName not covered above) | NULL +|===== + +1:: +pname:pName is the name of any Vulkan command whose first parameter + is sname:VkDevice or any of its dispatchable children (e.g. sname:VkQueue, + sname:vkCommandBuffer). include::../validity/protos/vkGetDeviceProcAddr.txt[] +// refEnd vkGetDeviceProcAddr PFN_vkVoidFunction + See Also -------- -slink:VkDevice +tlink:PFN_vkVoidFunction, slink:VkDevice Document Notes diff --git a/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt b/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt index f07ad82d8a..dd812abeb1 100644 --- a/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt +++ b/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt @@ -25,7 +25,7 @@ Parameters ---------- * pname:instance is the instance that the function pointer will be - compatible with. + compatible with, or `NULL` for commands not dependent on any instance. * pname:pName is the name of the command to obtain. @@ -40,25 +40,36 @@ Loaders are encouraged to export function symbols for all other core Vulkan commands as well; if this is done, then applications that use only the core Vulkan commands have no need to use fname:vkGetInstanceProcAddr. -Function pointers to commands that do not operate on a specific instance can: -be obtained by using this command with pname:instance equal to `NULL`. The -following commands can: be accessed this way: - - * flink:vkEnumerateInstanceExtensionProperties - * flink:vkEnumerateInstanceLayerProperties - * flink:vkCreateInstance +The table below defines the various use cases for fname:vkGetInstanceProcAddr +and expected return value ("fp" is function pointer) for each case. The returned function pointer is of type tlink:PFN_vkVoidFunction, and must be cast to the type of the command being queried. -If pname:instance is a valid sname:VkInstance, function pointers to any -commands that operate on pname:instance or a child of pname:instance can: be -obtained. The returned function pointer must: only be called with a -dispatchable object (the first parameter) that is a child of pname:instance. - -If pname:pName is not the name of a core Vulkan command, or is an -extension command for any extension not supported by any available layer or -implementation, then fname:vkGetInstanceProcAddr will return `NULL`. +.vkGetInstanceProcAddr behavior +[width="80%",options="header",align="center"] +|===== +| pname:instance | pname:pName | return value +| * | NULL | undefined +| invalid instance | * | undefined +| NULL | flink:vkEnumerateInstanceExtensionProperties | fp +| NULL | flink:vkEnumerateInstanceLayerProperties | fp +| NULL | flink:vkCreateInstance | fp +| NULL | * (any pname:pName not covered above) | NULL +| instance | core Vulkan command | fp^1^ +| instance | enabled instance extension commands for pname:instance | fp^1^ +| instance | available device extension commands for pname:instance | fp^1,2^ +| instance | * (any pname:pName not covered above) | NULL +|===== + +1:: +The returned function pointer must: only be called with a dispatchable object +(the first parameter) that is a child of pname:instance. + e.g. sname:VkInstance, sname:VkPhysicalDevice, sname:VkDevice, sname:VkQueue, or + sname:VkCommandBuffer. + +2:: +available extension is an extension function supported by any of the loader, ICD or layer. ifdef::editing-notes[] [NOTE] diff --git a/doc/specs/vulkan/style/writing.txt b/doc/specs/vulkan/style/writing.txt index 6a360c0634..7da78e2f51 100644 --- a/doc/specs/vulkan/style/writing.txt +++ b/doc/specs/vulkan/style/writing.txt @@ -187,23 +187,28 @@ looks as it does. [[sample-command]] == Sample Command Description: Creating Command Pools +// refBegin vkCreateCommandPool Create a new command pool object. + To create a command pool, call: +include::../api/protos/vkCreateCommandPool.txt[] + [NOTE] .Guideline ==== +Begin the command description with a comment delimiting the language for +<>. + Use a short, active sentence when describing what commands do, instead of more passive phrasing like ``A command pool is created by calling:'' or ``The application may create a command pool by calling:''. -==== -include::../api/protos/vkCreateCommandPool.txt[] +After the description, include the autogenerated prototype for the +command from the `../protos/` directory: -[NOTE] -.Guideline -==== -After the description, include the autogenerated prototype for the command -from the `../protos/` directory: + // refBegin vkCreateCommandPool Create a new command pool object. + + To create a command pool, call: include::../api/protos/vkCreateCommandPool.txt[] @@ -254,8 +259,13 @@ Parameter and member validation language for commands and structures is also autogenerated from vk.xml, and included from the `../validity/` directories: include::../validity/protos/vkCreateCommandPool.txt[] + +Structures and enumerations first used as parameters of a command are +described next. ==== +// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool + The sname:VkCommandPoolCreateInfo structure is defined as: include::../api/structs/VkCommandPoolCreateInfo.txt[] @@ -263,9 +273,18 @@ include::../api/structs/VkCommandPoolCreateInfo.txt[] [NOTE] .Guideline ==== -Structures and enumerations first used as parameters of a command are -described next, by including the autogenerated interface file for that -structure or enumeration: +Begin the structure description with a comment delimiting the language for +<>. + +Use a short, active paragraph to introduce the structure, usually just +``The sname:VkStructureName structure is defined as:''. + +After the description, include the autogenerated definition for the +structure from the `../structs/` directory: + + // refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool + + The sname:VkCommandPoolCreateInfo structure is defined as: include::../api/structs/VkCommandPoolCreateInfo.txt[] ==== @@ -277,13 +296,14 @@ structure or enumeration: include: + -- +// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool include::../api/enums/VkCommandPoolCreateFlagBits.txt[] - -** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers - allocated from the pool will be short-lived. -** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether - command buffers allocated from the pool can: be individually reset. -- ++ + ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers + allocated from the pool will be short-lived. + ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether + command buffers allocated from the pool can: be individually reset. * pname:queueFamilyIndex designates a queue family. Command buffers in this command pool must: be submitted on queues from the same family. @@ -297,8 +317,7 @@ specific to the structure. ---- * pname:sType is the type of this structure. - * pname:pNext is `NULL` or a pointer to an - extension-specific structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. ---- In some cases, such as when the type of a member is itself a new type, the @@ -308,20 +327,20 @@ asciidoc parser. It is usually best to append a block following the first paragraph of such a list item: ---- - * pname:flags is a combination of bitmask flags - indicating usage behavior for the pool and - command buffers allocated from it. Possible - values include: + * pname:flags is a bitmask indicating usage behavior for the pool and + command buffers allocated from it. Bits which can: be set include: + -- -\include::../api/enums/VkCommandPoolCreateFlagBits.txt[] - -** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT - indicates that command buffers allocated - from the pool will be short-lived. -** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT - controls whether command buffers allocated from - the pool can: be individually reset. +// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool +include::../api/enums/VkCommandPoolCreateFlagBits.txt[] +-- ++ + ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT + indicates that command buffers allocated + from the pool will be short-lived. + ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT + controls whether command buffers allocated from + the pool can: be individually reset. -- ---- ==== @@ -336,3 +355,56 @@ for this structure: include::../validity/structs/VkCommandPoolCreateInfo.txt[] ==== + + +[[writing-refpages]] +== Markup For Automatic Reference Page Extraction + +The Vulkan reference pages are (mostly) being extracted from +corresponding sections of the API Specification. This requires that the +markup and writing conventions described above be adhered to rigidly. + +The extraction scripts for a given page rely on the existence of the +asciidoc +include+ of the autogenerated definition of that command, +structure, or other API interface element. Various heuristics are used +to determine which text to extract for that page; the general model is: + + * Optional (but usually specified) comment line specifying the + interface name and the short description used in the title of the + corresponding ref page: ++ +---- + // refBegin name - description +---- ++ + * A paragraph of text introducing the definition of the interface. If + the +refBegin+ comment does not exist, this paragraph must be + present. + * The +include+ line for the interface, which must be consistent + with the interface name in the comment line. + * A bullet list describing function parameters, structure members, + enumerants in an enumerated type, etc. This list should contain no + empty lines, as the extraction script classifies the uninterrupted + block of text following the +include+ directive as the +Parameters+ + or +Members+ section of the ref page. + * Optional paragraphs of text making up the +Description+ section of + the ref page. + * The +include+ line for the validity statement of commands and + structures. Other interfaces such as enumerated types do not have + validity statements. + * Comment line specifying the end of the extracted text for the + reference page and optional page names to link to in the +See Also+ + section of the page. If the validity +include+ is not present, this + line must be present: ++ +---- + // refEnd name [seeAlsoNames]* +---- + +All elements specifying an interface name (+refBegin+ and +refEnd+ +comments, interface +include+ line, and validity +include+ line) must +use the same interface name, if present. Otherwise the extraction script +is either unable to extract that page, or will extract the wrong text. +The extraction process is somewhat fragile, so care should be taken and +the results of reference page extraction verified after making changes +to that portion of the specification source. diff --git a/doc/specs/vulkan/styleguide.txt b/doc/specs/vulkan/styleguide.txt index fa4f859a1a..c745c08632 100644 --- a/doc/specs/vulkan/styleguide.txt +++ b/doc/specs/vulkan/styleguide.txt @@ -153,6 +153,8 @@ include::style/writing.txt[] = Revision History +* July 26, 2016 - Add section describing <>. * July 18, 2016 - Add examples of function-parameter and structure-member markup (based on public issue 286). * July 11, 2016 - Change the document title. diff --git a/doc/specs/vulkan/validity/protos/vkCmdBindDescriptorSets.txt b/doc/specs/vulkan/validity/protos/vkCmdBindDescriptorSets.txt index 06fd188c8f..e5e847bb39 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdBindDescriptorSets.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdBindDescriptorSets.txt @@ -18,6 +18,7 @@ endif::doctype-manpage[] * Each of pname:commandBuffer, pname:layout, and the elements of pname:pDescriptorSets must: have been created, allocated, or retrieved from the same sname:VkDevice * Any given element of pname:pDescriptorSets must: have been created with a sname:VkDescriptorSetLayout that matches (is the same as, or defined identically to) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, where _n_ is the sum of pname:firstSet and the index into pname:pDescriptorSets * pname:dynamicOffsetCount must: be equal to the total number of dynamic descriptors in pname:pDescriptorSets +* The sum of pname:firstSet and pname:descriptorSetCount must: be less than or equal to sname:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when pname:layout was created * pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family * Any given element of pname:pDynamicOffsets must: satisfy the required alignment for the corresponding descriptor binding's descriptor type ifndef::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt b/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt index c923f91020..5d6eafeafe 100644 --- a/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt +++ b/doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt @@ -19,6 +19,7 @@ endif::doctype-manpage[] * Any given element of pname:pCommandBuffers mustnot: be already pending execution in pname:commandBuffer, or appear twice in pname:pCommandBuffers, unless it was created with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag * Any given element of pname:pCommandBuffers mustnot: be already pending execution in any other sname:VkCommandBuffer, unless it was created with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag * Any given element of pname:pCommandBuffers must: be in the executable state +* Any given element of pname:pCommandBuffers must: have been allocated from a sname:VkCommandPool that was created for the same queue family as the sname:VkCommandPool from which pname:commandBuffer was allocated * If fname:vkCmdExecuteCommands is being called within a render pass instance, that render pass instance must: have been begun with the pname:contents parameter of fname:vkCmdBeginRenderPass set to ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the index of the subpass which the given command buffer will be executed in diff --git a/doc/specs/vulkan/validity/protos/vkGetInstanceProcAddr.txt b/doc/specs/vulkan/validity/protos/vkGetInstanceProcAddr.txt index e79f38418b..5a451190ad 100644 --- a/doc/specs/vulkan/validity/protos/vkGetInstanceProcAddr.txt +++ b/doc/specs/vulkan/validity/protos/vkGetInstanceProcAddr.txt @@ -9,8 +9,6 @@ Valid Usage endif::doctype-manpage[] * If pname:instance is not `NULL`, pname:instance must: be a valid sname:VkInstance handle * pname:pName must: be a null-terminated string -* If pname:instance is `NULL`, pname:pName must: be "vkEnumerateInstanceExtensionProperties", "vkEnumerateInstanceLayerProperties", or "vkCreateInstance" -* If pname:instance is not `NULL`, pname:pName mustnot: be "vkEnumerateInstanceExtensionProperties", "vkEnumerateInstanceLayerProperties", or "vkCreateInstance" ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/doc/specs/vulkan/validity/structs/VkImageViewCreateInfo.txt b/doc/specs/vulkan/validity/structs/VkImageViewCreateInfo.txt index 9f84d9e241..cba998ede0 100644 --- a/doc/specs/vulkan/validity/structs/VkImageViewCreateInfo.txt +++ b/doc/specs/vulkan/validity/structs/VkImageViewCreateInfo.txt @@ -33,7 +33,7 @@ endif::doctype-manpage[] * pname:subresourceRange must: be a valid image subresource range for pname:image (see <>) * If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be compatible with the pname:format used to create pname:image, as defined in <> * If pname:image was not created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be identical to the pname:format used to create pname:image -* pname:subResourceRange and pname:viewType must: be compatible with the image, as described in the <> +* pname:subResourceRange and pname:viewType must: be compatible with the image, as described in the <> ifndef::doctype-manpage[] ******************************************************************************** endif::doctype-manpage[] diff --git a/src/spec/README b/src/spec/README index 3afd5b9eb8..b6966ba877 100644 --- a/src/spec/README +++ b/src/spec/README @@ -19,14 +19,16 @@ When patches to the header or the includes are needed, follow this workflow: - Edit vk.xml - make ; make test (this just generates ../vulkan/vulkan.h) - - make full_install - (this generates all targets) + - make install doc_install + (this generates header and registry documentation) + - (cd ../../doc/specs/vulkan && make generated) + (this generates asciidoc includes) - Repeat until the header and/or includes are correct - Commit your changes to your local git branch - Push the branch to the git server and create a merge request against the specification branch ("1.0") or other appropriate target. -See 'readme.pdf' for a detailed description of the schema, and some examples +See 'readme.txt' for a detailed description of the schema, and some examples of how to make simple changes in the API via the XML. The generator scripts are written in Python 3, using the etree package for @@ -40,14 +42,16 @@ FILES Makefile - generates header and JSON from XML (see below) vk.xml - XML API description genvk.py - Python script to generate vulkan.h and other targets. - readme.tex - Source for detailed description of the XML schema - readme.pdf - Generated document describing the XML schema and giving - some examples of making simple changes to add API features + readme.txt - Source for detailed description of the XML schema registry.rnc - RelaxNG compact schema for validating XML against the schema reg.py - Python tools to read XML file and convert it into C headers - generator.py - output generator for C. Others are possible, although - vk.xml contains C-isms which would have to be factored out. + generator.py - output generator base class. + cgenerator.py - C output generator for vulkan.h + docgenerator.py - Asciidoc interface language include generator + hostsyncgenerator.py - Asciidoc host sync table generator + pygenerator.py - Generates python encoding of the API description + validitygenerator.py - Asciidoc validity language generator ../vulkan/vulkan.h - Generated header MAKEFILE TARGETS @@ -55,21 +59,14 @@ MAKEFILE TARGETS install or ../vulkan/vulkan.h (default target) - regenerate vulkan.h in ../vulkan . - vulkan-docs - regenerate spec/ref page API include .txt files and - install under ../../doc/specs/vulkan/*/ . In general, this should be - left until a branch is merged to master. - full_install - combination of 'install' and 'vulkan-docs' targets. - Again, in general this should be left until a branch is merged to - master. - readme.pdf - detailed description of the XML schema. Normally this need - not be rebuilt unless you are changing the schema and updating - readme.tex. + doc_install - generates detailed description of the XML schema from + registry.txt in $(OUTDIR)/registry.html . In general this should be + left until a branch is merged to 1.0. test - make sure ../vulkan/vulkan.h compiles. Important! validate - validate vk.xml against the schema. Requires 'jing' tool installed. - clobber - remove generated and cache files, including the API include - files. Usually done while merging to master via 'make clobber ; make - full_install' + clobber - remove generated files. Usually done when to merging to 1.0 + via 'make clobber ; make install doc_install'. If you have trouble running the Makefile on your platorm, try using the command line: @@ -173,3 +170,7 @@ CHANGE LOG 2016/05/31 Remove dependency on lxml. + +2016/07/27 + + Update documentation for changes to schema and generator scripts. diff --git a/src/spec/registry.rnc b/src/spec/registry.rnc index af354a9c06..7419a953f2 100644 --- a/src/spec/registry.rnc +++ b/src/spec/registry.rnc @@ -106,6 +106,8 @@ Types = element types { # optional - whether this value can be omitted by providing NULL (for # pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values) # noautovalidity - tag stating that no automatic validity language should be generated +# validextensionstructs - comma-separate list of legal structure types in pNext chain +# values - comma-separated list of legal values, usually used only for sType enums # # *** There's a problem here: I'm not sure how to represent the # syntax where it may contain arbitrarily interleaved text, , and @@ -141,6 +143,8 @@ Type = element type { attribute externsync { text } ? , attribute optional { text } ? , attribute noautovalidity { text } ? , + attribute validextensionstructs { text } ? , + attribute values { text } ? , mixed { element type { TypeName } ? , element name { text }, diff --git a/src/spec/registry.txt b/src/spec/registry.txt index 5d50be0dbd..eabe7d38d8 100644 --- a/src/spec/registry.txt +++ b/src/spec/registry.txt @@ -366,6 +366,9 @@ member. * attr:validextensionstructs - only valid on the +pNext+ member of a struct. This is a comma-separated list of structures that may be accepted by +pNext+ instead of +NULL+ + * attr:values - only valid on the +sType+ member of a struct. This is a + comma-separated list of enumerant values that are valid for the + structure type; usually there is only a single value. * attr:len - if the member is an array, len may be one or more of the following things, separated by commas (one for each array indirection): another member of that struct; +"null-terminated"+ for diff --git a/src/spec/validitygenerator.py b/src/spec/validitygenerator.py index 7607fea552..ceef6b2d8c 100644 --- a/src/spec/validitygenerator.py +++ b/src/spec/validitygenerator.py @@ -203,7 +203,7 @@ def staticArrayLength(self, param): # Check if the parameter passed in is a pointer to an array def paramIsArray(self, param): return param.attrib.get('len') is not None - + # # Get the parent of a handle object def getHandleParent(self, typename): @@ -224,7 +224,7 @@ def getHandleAncestors(self, typename): if current is None: return ancestors ancestors.append(current) - + # # Get the ancestors of a handle object def getHandleDispatchableAncestors(self, typename): @@ -236,7 +236,7 @@ def getHandleDispatchableAncestors(self, typename): return ancestors if self.isHandleTypeDispatchable(current): ancestors.append(current) - + # # Check if a parent object is dispatchable or not def isHandleTypeDispatchable(self, handlename): @@ -585,70 +585,70 @@ def makeAsciiDocHandleParent(self, param, params): asciidoc += '\n' return asciidoc - + # # Make an asciidoc validity entry for a common ancestors between handles def makeAsciiDocHandlesCommonAncestor(self, handles, params): asciidoc = '' - + if len(handles) > 1: ancestormap = {} anyoptional = False - + # Find all the ancestors for param in handles: paramname = param.find('name') paramtype = param.find('type') - + ancestors = self.getHandleDispatchableAncestors(paramtype.text) - - ancestormap[param] = ancestors - + + ancestormap[param] = ancestors + anyoptional |= self.isHandleOptional(param, params) # Remove redundant ancestor lists for param in handles: paramname = param.find('name') paramtype = param.find('type') - + removals = [] for ancestors in ancestormap.items(): if paramtype.text in ancestors[1]: removals.append(ancestors[0]) - + if removals != []: for removal in removals: del(ancestormap[removal]) # Intersect - + if len(ancestormap.values()) > 1: current = list(ancestormap.values())[0] for ancestors in list(ancestormap.values())[1:]: current = [val for val in current if val in ancestors] - + if len(current) > 1: commonancestor = current[0] - + if len(ancestormap.keys()) > 1: - + asciidoc += '* ' - + parametertexts = [] for param in ancestormap.keys(): - paramname = param.find('name') - parametertext = self.makeParameterName(paramname.text) + paramname = param.find('name') + parametertext = self.makeParameterName(paramname.text) if self.paramIsArray(param): parametertext = 'the elements of ' + parametertext parametertexts.append(parametertext) parametertexts.sort() - + if len(parametertexts) > 2: asciidoc += 'Each of ' else: asciidoc += 'Both of ' - + asciidoc += ", ".join(parametertexts[:-1]) asciidoc += ', and ' asciidoc += parametertexts[-1] @@ -657,9 +657,9 @@ def makeAsciiDocHandlesCommonAncestor(self, handles, params): asciidoc += ' must: have been created, allocated, or retrieved from the same ' asciidoc += self.makeStructName(commonancestor) asciidoc += '\n' - + return asciidoc - + # # Generate an asciidoc validity line for the sType value of a struct def makeStructureType(self, blockname, param): @@ -670,15 +670,28 @@ def makeStructureType(self, blockname, param): asciidoc += self.makeParameterName(paramname.text) asciidoc += ' must: be ' - structuretype = '' - for elem in re.findall(r'(([A-Z][a-z]+)|([A-Z][A-Z]+))', blockname): - if elem[0] == 'Vk': - structuretype += 'VK_STRUCTURE_TYPE_' - else: - structuretype += elem[0].upper() - structuretype += '_' + values = param.attrib.get('values') + if values: + # Extract each enumerant value. They could be validated in the + # same fashion as validextensionstructs in + # makeStructureExtensionPointer, although that's not relevant in + # the current extension struct model. + valuelist = [ self.makeEnumerantName(v) for v in values.split(',') ] + else: + structuretype = '' + for elem in re.findall(r'(([A-Z][a-z]+)|([A-Z][A-Z]+))', blockname): + if elem[0] == 'Vk': + structuretype += 'VK_STRUCTURE_TYPE_' + else: + structuretype += elem[0].upper() + structuretype += '_' + valuelist = [ self.makeEnumerantName(structuretype[:-1]) ] - asciidoc += self.makeEnumerantName(structuretype[:-1]) + if len(valuelist) > 0: + if len(valuelist) == 1: + asciidoc += valuelist[0] + else: + asciidoc += (', ').join(valuelist[:-1]) + ', or ' + valuelist[-1] asciidoc += '\n' return asciidoc @@ -860,21 +873,21 @@ def makeValidUsageStatements(self, cmd, blockname, params, usages): asciidoc += self.makeParameterName(arraylength) asciidoc += ' must: be greater than `0`' asciidoc += '\n' - + # Find the parents of all objects referenced in this command - for param in handles: - paramtype = param.find('type') + for param in handles: + paramtype = param.find('type') # Don't detect a parent for return values! if not self.paramIsPointer(param) or (param.text is not None and 'const' in param.text): - + parent = self.getHandleParent(paramtype.text) - + if parent is not None: asciidoc += self.makeAsciiDocHandleParent(param, params) - + # Find the common ancestor of all objects referenced in this command asciidoc += self.makeAsciiDocHandlesCommonAncestor(handles, params) - + # Add in any plain-text validation language that should be added for usage in usages: asciidoc += '* ' diff --git a/src/spec/vk.xml b/src/spec/vk.xml index f644c7ed01..852d63ab9b 100644 --- a/src/spec/vk.xml +++ b/src/spec/vk.xml @@ -101,7 +101,7 @@ maintained in the master branch of the Khronos Vulkan Github project. // Vulkan 1.0 version number #define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0) // Version of this file -#define VK_HEADER_VERSION 22 +#define VK_HEADER_VERSION 23 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -455,7 +455,7 @@ maintained in the master branch of the Khronos Vulkan Github project. char description[VK_MAX_DESCRIPTION_SIZE] - VkStructureType sType + VkStructureType sType const void* pNext const char* pApplicationName uint32_t applicationVersion @@ -481,7 +481,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDeviceQueueCreateFlags flags uint32_t queueFamilyIndex @@ -494,7 +494,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDeviceCreateFlags flags uint32_t queueCreateInfoCount @@ -509,7 +509,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkInstanceCreateFlags flags const VkApplicationInfo* pApplicationInfo @@ -533,7 +533,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkMemoryHeap memoryHeaps[VK_MAX_MEMORY_HEAPS] - VkStructureType sType + VkStructureType sType const void* pNext VkDeviceSize allocationSize uint32_t memoryTypeIndex @@ -568,7 +568,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkMemoryHeapFlags flags - VkStructureType sType + VkStructureType sType const void* pNext VkDeviceMemory memory VkDeviceSize offset @@ -609,7 +609,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkImageLayout imageLayout - VkStructureType sType + VkStructureType sType const void* pNext VkDescriptorSet dstSet uint32_t dstBinding @@ -640,7 +640,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDescriptorSet srcSet uint32_t srcBinding @@ -658,7 +658,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkBufferCreateFlags flags VkDeviceSize size @@ -677,7 +677,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkBufferViewCreateFlagsflags VkBuffer buffer @@ -730,13 +730,13 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkAccessFlags srcAccessMask VkAccessFlags dstAccessMask - VkStructureType sType + VkStructureType sType const void* pNext VkAccessFlags srcAccessMask VkAccessFlags dstAccessMask @@ -755,7 +755,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkAccessFlags srcAccessMask VkAccessFlags dstAccessMask @@ -782,7 +782,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkImageCreateFlags flags VkImageType imageType @@ -850,7 +850,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkDeviceSize depthPitch - VkStructureType sType + VkStructureType sType const void* pNext VkImageViewCreateFlags flags VkImage image @@ -877,7 +877,7 @@ maintained in the master branch of the Khronos Vulkan Github project. pname:subresourceRange must: be a valid image subresource range for pname:image (see <<resources-image-views>>) If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be compatible with the pname:format used to create pname:image, as defined in <<features-formats-compatibility-classes,Format Compatibility Classes>> If pname:image was not created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be identical to the pname:format used to create pname:image - pname:subResourceRange and pname:viewType must: be compatible with the image, as described in the <<resources-image-views-compatibility,table below>> + pname:subResourceRange and pname:viewType must: be compatible with the image, as described in the <<resources-image-views-compatibility,compatibility table>> @@ -939,7 +939,7 @@ maintained in the master branch of the Khronos Vulkan Github project. const VkSparseImageMemoryBind* pBinds - VkStructureType sType + VkStructureType sType const void* pNext uint32_t waitSemaphoreCount const VkSemaphore* pWaitSemaphores @@ -1045,7 +1045,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkShaderModuleCreateFlags flags size_t codeSize @@ -1072,7 +1072,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDescriptorSetLayoutCreateFlags flags uint32_t bindingCount @@ -1086,7 +1086,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDescriptorPoolCreateFlags flags uint32_t maxSets @@ -1097,7 +1097,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDescriptorPool descriptorPool uint32_t descriptorSetCount @@ -1126,7 +1126,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineShaderStageCreateFlags flags VkShaderStageFlagBits stage @@ -1153,7 +1153,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineCreateFlags flags VkPipelineShaderStageCreateInfo stage @@ -1193,7 +1193,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineVertexInputStateCreateFlags flags uint32_t vertexBindingDescriptionCount @@ -1210,7 +1210,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineInputAssemblyStateCreateFlags flags VkPrimitiveTopology topology @@ -1222,7 +1222,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineTessellationStateCreateFlags flags uint32_t patchControlPoints @@ -1231,7 +1231,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineViewportStateCreateFlags flags uint32_t viewportCount @@ -1247,7 +1247,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineRasterizationStateCreateFlags flags VkBool32 depthClampEnable @@ -1266,7 +1266,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineMultisampleStateCreateFlags flags VkSampleCountFlagBits rasterizationSamples @@ -1298,7 +1298,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineColorBlendStateCreateFlags flags VkBool32 logicOpEnable @@ -1313,7 +1313,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineDynamicStateCreateFlags flags uint32_t dynamicStateCount @@ -1329,7 +1329,7 @@ maintained in the master branch of the Khronos Vulkan Github project. uint32_t reference - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineDepthStencilStateCreateFlags flags VkBool32 depthTestEnable @@ -1346,7 +1346,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineCreateFlags flags uint32_t stageCount @@ -1408,7 +1408,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineCacheCreateFlags flags size_t initialDataSize @@ -1430,7 +1430,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkPipelineLayoutCreateFlags flags uint32_t setLayoutCount @@ -1447,7 +1447,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkSamplerCreateFlags flags VkFilter magFilter @@ -1481,7 +1481,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkCommandPoolCreateFlags flags uint32_t queueFamilyIndex @@ -1490,7 +1490,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkCommandPool commandPool VkCommandBufferLevel level @@ -1500,7 +1500,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkRenderPass renderPass uint32_t subpass @@ -1515,7 +1515,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkCommandBufferUsageFlags flags const VkCommandBufferInheritanceInfo* pInheritanceInfo @@ -1526,7 +1526,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkRenderPass renderPass VkFramebuffer framebuffer @@ -1626,7 +1626,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkRenderPassCreateFlags flags uint32_t attachmentCount @@ -1643,12 +1643,12 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkEventCreateFlags flags - VkStructureType sType + VkStructureType sType const void* pNext VkFenceCreateFlags flags @@ -1850,12 +1850,12 @@ maintained in the master branch of the Khronos Vulkan Github project. VkDeviceSize nonCoherentAtomSize - VkStructureType sType + VkStructureType sType const void* pNext VkSemaphoreCreateFlags flags - VkStructureType sType + VkStructureType sType const void* pNext VkQueryPoolCreateFlags flags VkQueryType queryType @@ -1867,7 +1867,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkFramebufferCreateFlags flags VkRenderPass renderPass @@ -1924,7 +1924,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext uint32_t waitSemaphoreCount const VkSemaphore* pWaitSemaphores @@ -1971,7 +1971,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkDisplayModeParametersKHR parameters - VkStructureType sType + VkStructureType sType const void* pNext VkDisplayModeCreateFlagsKHR flags VkDisplayModeParametersKHR parameters @@ -1992,7 +1992,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkExtent2D maxDstExtent - VkStructureType sType + VkStructureType sType const void* pNext VkDisplaySurfaceCreateFlagsKHR flags VkDisplayModeKHR displayMode @@ -2011,7 +2011,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkRect2D srcRect VkRect2D dstRect @@ -2035,7 +2035,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkImageUsageFlags supportedUsageFlags - VkStructureType sType + VkStructureType sType const void* pNext VkAndroidSurfaceCreateFlagsKHR flags ANativeWindow* window @@ -2044,35 +2044,35 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkMirSurfaceCreateFlagsKHR flags MirConnection* connection MirSurface* mirSurface - VkStructureType sType + VkStructureType sType const void* pNext VkWaylandSurfaceCreateFlagsKHR flags struct wl_display* display struct wl_surface* surface - VkStructureType sType + VkStructureType sType const void* pNext VkWin32SurfaceCreateFlagsKHR flags HINSTANCE hinstance HWND hwnd - VkStructureType sType + VkStructureType sType const void* pNext VkXlibSurfaceCreateFlagsKHR flags Display* dpy Window window - VkStructureType sType + VkStructureType sType const void* pNext VkXcbSurfaceCreateFlagsKHR flags xcb_connection_t* connection @@ -2083,7 +2083,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkColorSpaceKHR colorSpace - VkStructureType sType + VkStructureType sType const void* pNext VkSwapchainCreateFlagsKHR flags VkSurfaceKHR surface @@ -2118,7 +2118,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext uint32_t waitSemaphoreCount const VkSemaphore* pWaitSemaphores @@ -2132,26 +2132,26 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkDebugReportFlagsEXT flags PFN_vkDebugReportCallbackEXT pfnCallback void* pUserData - VkStructureType sType + VkStructureType sType const void* pNext VkRasterizationOrderAMD rasterizationOrder - VkStructureType sType + VkStructureType sType const void* pNext VkDebugReportObjectTypeEXT objectType uint64_t object const char* pObjectName - VkStructureType sType + VkStructureType sType const void* pNext VkDebugReportObjectTypeEXT objectType uint64_t object @@ -2160,13 +2160,13 @@ maintained in the master branch of the Khronos Vulkan Github project. const void* pTag - VkStructureType sType + VkStructureType sType const void* pNext const char* pMarkerName float color[4] - VkStructureType sType + VkStructureType sType const void* pNext VkBool32 dedicatedAllocation @@ -2174,7 +2174,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkBool32 dedicatedAllocation @@ -2182,7 +2182,7 @@ maintained in the master branch of the Khronos Vulkan Github project. - VkStructureType sType + VkStructureType sType const void* pNext VkImage image VkBuffer buffer @@ -3032,17 +3032,11 @@ maintained in the master branch of the Khronos Vulkan Github project. PFN_vkVoidFunction vkGetDeviceProcAddr VkDevice device const char* pName - - PFN_vkVoidFunction vkGetInstanceProcAddr VkInstance instance const char* pName - - If pname:instance is `NULL`, pname:pName must: be "vkEnumerateInstanceExtensionProperties", "vkEnumerateInstanceLayerProperties", or "vkCreateInstance" - If pname:instance is not `NULL`, pname:pName mustnot: be "vkEnumerateInstanceExtensionProperties", "vkEnumerateInstanceLayerProperties", or "vkCreateInstance" - void vkGetPhysicalDeviceProperties @@ -3114,7 +3108,7 @@ maintained in the master branch of the Khronos Vulkan Github project. VkResult vkEnumerateDeviceLayerProperties - VkPhysicalDevice physicalDevice + VkPhysicalDevice physicalDevice uint32_t* pPropertyCount VkLayerProperties* pProperties @@ -3953,6 +3947,7 @@ maintained in the master branch of the Khronos Vulkan Github project. Any given element of pname:pDescriptorSets must: have been created with a sname:VkDescriptorSetLayout that matches (is the same as, or defined identically to) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, where _n_ is the sum of pname:firstSet and the index into pname:pDescriptorSets pname:dynamicOffsetCount must: be equal to the total number of dynamic descriptors in pname:pDescriptorSets + The sum of pname:firstSet and pname:descriptorSetCount must: be less than or equal to sname:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when pname:layout was created pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family Any given element of pname:pDynamicOffsets must: satisfy the required alignment for the corresponding descriptor binding's descriptor type @@ -4547,6 +4542,7 @@ maintained in the master branch of the Khronos Vulkan Github project. Any given element of pname:pCommandBuffers mustnot: be already pending execution in pname:commandBuffer, or appear twice in pname:pCommandBuffers, unless it was created with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag Any given element of pname:pCommandBuffers mustnot: be already pending execution in any other sname:VkCommandBuffer, unless it was created with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT flag Any given element of pname:pCommandBuffers must: be in the executable state + Any given element of pname:pCommandBuffers must: have been allocated from a sname:VkCommandPool that was created for the same queue family as the sname:VkCommandPool from which pname:commandBuffer was allocated If fname:vkCmdExecuteCommands is being called within a render pass instance, that render pass instance must: have been begun with the pname:contents parameter of fname:vkCmdBeginRenderPass set to ename:VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the index of the subpass which the given command buffer will be executed in @@ -4595,7 +4591,7 @@ maintained in the master branch of the Khronos Vulkan Github project. uint32_t* pPropertyCount VkDisplayModePropertiesKHR* pProperties - + VkResult vkCreateDisplayModeKHR VkPhysicalDevice physicalDevice VkDisplayKHR display @@ -5540,5 +5536,11 @@ maintained in the master branch of the Khronos Vulkan Github project. + + + + + + diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h index ddbb311f83..0c547a5cfb 100644 --- a/src/vulkan/vulkan.h +++ b/src/vulkan/vulkan.h @@ -43,7 +43,7 @@ extern "C" { #define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff) #define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff) // Version of this file -#define VK_HEADER_VERSION 22 +#define VK_HEADER_VERSION 23 #define VK_NULL_HANDLE 0