diff --git a/COPYING.md b/COPYING.md index ab44b3ca..23c84f25 100644 --- a/COPYING.md +++ b/COPYING.md @@ -3,19 +3,26 @@ project are under a mix of copyright and license statements. Refer to the individual files for specific information. As a general guideline: -* The Vulkan Specification asciidoc sources and generated output - documents are under a proprietary Khronos license. See - https://www.khronos.org/registry/speccopyright.html -* The Vulkan headers, spec build tools, and spec and registry - configuration files are for the most part under the Apache 2 license. - Some older files under BSD-like licenses which may eventually be - updated to Apache 2 as we have time. +* The Vulkan Specification asciidoc sources, as well as other documentation + which we expect people may wish to regenerate and distributed in other + formats - such as the reference pages generated from the Specification + source - are under a Creative Commons Attribution 4.0 license. +** The specification sources have only recently (as of June 2017) been + placed under this license. We will now be able to accept pull requests on + Github, but there is a related Contribution License Agreement which + people proposing PRs to the Vulkan-Docs repository must execute as part + of opening the PR. +* Generated output documents, including the official Vulkan Specification + PDF and HTML documents, are under a proprietary Khronos license. See + https://www.khronos.org/registry/speccopyright.html . Only Specification + documents posted in the Vulkan Registry are official. +* The Vulkan headers, spec build tools, and spec and registry configuration + files are, for the most part, under the Apache 2 license. Some older files + are under BSD-like licenses which may eventually be updated to Apache 2 as + we have time. * There may be some configuration files customized from material shipped with the asciidoc and dblatex distributions. Such files continue under their original copyrights. -* Documentation which we expect to be redistributed in different - formats, such as the reference pages generated from the Specification - source, are under a Creative Commons Attribution 4.0 license. * Some generated, transient files produced during the course of building the specification, headers, or other targets may not have copyrights. These are typically very short asciidoc fragments describing parts of diff --git a/ChangeLog.txt b/ChangeLog.txt index bc876dc6..d7fe0c62 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -1,5 +1,5 @@ -Update Log for the Vulkan-Docs repository on Github. Updates are in -reverse chronological order starting with the latest public release. +Update Log for the Vulkan-Docs repository on Github. Updates are in reverse +chronological order starting with the latest public release. This summarizes the periodic public updates, not individual commits. For the most part, commits on Github are done as single large patches at the release @@ -8,6 +8,88 @@ public issues. ----------------------------------------------------- +Change log for June 24, 2017 Vulkan 1.0.53 spec update: + + * Bump API patch number and header version number to 53 for this update. + +Github Issues: + +Internal Issues: + + * Clarify mappings of coordinates for mutable, compatible image views in + slink:VkImageViewCreateInfo (internal issue 815). + * Make ename:VK_BIND_SFR_BIT require a logical device with multiple + physical devices, so that standard sparse image block dimensions are + only required on systems that support multi-GPU (internal issue 835). + * Convert all files from use of // refBegin .. // refEnd comments to + delimit ref pages, to use of open blocks, and update style guide + accordingly (internal issue 839). + * Add valid usage for slink:VkWriteDescriptorSet when performing updates + to a ename:VK_STORAGE_IMAGE descriptor with layout + ename:VK_IMAGE_LAYOUT_GENERAL. + * Add a hack to the validity generator script to support an odd + interaction between flink:vkCmdFillBuffer and an extension (internal + issue 853). + * Remove redundant text describing slink:VkBufferCreateInfo::pname:usage, + which was already covered by implicit valid usage (internal issue 854). + * Update implicit validity generator script to properly handle the + pname:sType and pname:pNext members of "returnedonly" structures + (internal issue 874). + * Note that slink:VkApplicationInfo::pname:pApplicationName & + slink:VkApplicationInfo::pname:pEngineName are optional, and add missing + implicit valid usage statements for flink:vkDestroyInstance. + * Added missing valid usage for flink:vkCmdWriteTimestamp to require a + timestamp query pool. + * Simplify and/or split "`non-atomic`" valid usage statements. + +New Extensions: + + * `VK_AMD_gpu_shader_int16` + * `VK_EXT_blend_operation_advanced` + * `VK_EXT_sampler_filter_minmax` + * `VK_NV_framebuffer_mixed_samples` + +----------------------------------------------------- + +Change log for June 13, 2017 Vulkan 1.0.52 spec update: + + * Bump API patch number and header version number to 52 for this update. + +Github Issues: + +Internal Issues: + + * Clarify behavior when non-coherent memory has + <> (internal issue 819). + * Fix description of code:WorkgroupSize builtin to note it decorates an + object, not a variable (internal issue 836). + * Fix asciidoc attributes so that trailing '{plus}' symbols in [eq] style + equations are rendered properly (internal issue 845). + * Add language to the "`Extension Handles, Objects, Enums, and Typedefs`" + section of the Procedures and Conventions document stating that any new + handle type requires a corresponding entry in the elink:VkObjectType + enumerated type (internal issue 856). + * Update style guide to use slink macro for Vulkan handle type names, and + define narrow conditions under which to use the *name and *text macros + instead of *link (internal issue 886). + * Add a dependency of the <> + extension on VK_KHX_device_group_creation to +vk.xml+ and the extension + appendix. + * Change the copyright on Vulkan specification asciidoc *source* files to + CC-BY 4.0, and update the proprietary Khronos copyright applied to the + generated *output* formats (internal issue 327). This enables broader + re-use and modification of the Vulkan specification sources, while not + affecting the Reciprocal IP License between Vulkan Adopters and Working + Group Members. + +New Extensions: + + * `VK_NV_fill_rectangle` + * `VK_NV_fragment_coverage_to_color` + +----------------------------------------------------- + Change log for June 4, 2017 Vulkan 1.0.51 spec update: * Bump API patch number and header version number to 51 for this update. diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile index a0126319..1bbb1b4c 100644 --- a/doc/specs/vulkan/Makefile +++ b/doc/specs/vulkan/Makefile @@ -87,7 +87,7 @@ VERBOSE = # $(EXTENSIONS)) # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -SPECREVISION = 1.0.51 +SPECREVISION = 1.0.53 # Spell out RFC2822 format as not all date commands support -R SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`) @@ -124,7 +124,7 @@ ADOCHTMLEXTS = -r $(CURDIR)/config/katex_replace.rb KATEXDIR = katex ADOCHTMLOPTS = $(ADOCHTMLEXTS) -a katexpath=$(KATEXDIR) -ADOCPDFEXTS = -r asciidoctor-pdf -r asciidoctor-mathematical +ADOCPDFEXTS = -r asciidoctor-pdf -r asciidoctor-mathematical -r $(CURDIR)/config/asciidoctor-mathematical-ext.rb ADOCPDFOPTS = $(ADOCPDFEXTS) -a mathematical-format=svg \ -a imagesoutdir=$(PDFMATHDIR) @@ -239,7 +239,7 @@ clean_checks: clean_generated: $(QUIET)$(RMRF) api/* hostsynctable/* validity/* vkapi.py - $(QUIET)$(RM) man/apispec.txt man/[Vv][Kk]*.txt man/PFN*.txt + $(QUIET)$(RM) man/apispec.txt $(LOGFILE) man/[Vv][Kk]*.txt man/PFN*.txt $(QUIET)$(RMRF) $(PDFMATHDIR) clean_validusage: @@ -273,8 +273,10 @@ MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt # @@ Needs to pass in $(EXTOPTIONS) and use that to determine which # pages to generate. As it stands, all the extension ref pages are # also generated, though they are not useable at present. + +LOGFILE = man/logfile man/apispec.txt: $(SPECFILES) genRef.py reflib.py vkapi.py - $(PYTHON) genRef.py $(SPECFILES) + $(PYTHON) genRef.py -log $(LOGFILE) $(SPECFILES) # These dependencies don't take into account include directives diff --git a/doc/specs/vulkan/appendices/VK_AMD_gpu_shader_int16.txt b/doc/specs/vulkan/appendices/VK_AMD_gpu_shader_int16.txt new file mode 100644 index 00000000..fdac04de --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_AMD_gpu_shader_int16.txt @@ -0,0 +1,36 @@ +== VK_AMD_gpu_shader_int16 + +*Name String*:: + +VK_AMD_gpu_shader_int16+ +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 133 +*Last Modified Date*:: + 06/08/2017 +*Revision*:: 1 +*IP Status*:: + No known IP claims. +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - Requires the SPV_AMD_gpu_shader_int16 SPIR-V extension. + +*Contributors*:: + - Daniel Rakos, AMD + - Dominik Witczak, AMD + - Matthaeus G. + Chajdas, AMD + - Rex Xu, AMD + - Timothy Lottes, AMD + - Zhi Cai, AMD +*Contacts*:: + - Qun Lin, AMD (quentin.lin@amd.com) + +This extension adds support for the following SPIR-V extension in Vulkan: + + * SPV_AMD_gpu_shader_int16 + +=== Version History + + * Revision 1, 2017-06-18 (Dominik Witczak) + - First version. diff --git a/doc/specs/vulkan/appendices/VK_EXT_blend_operation_advanced.txt b/doc/specs/vulkan/appendices/VK_EXT_blend_operation_advanced.txt new file mode 100644 index 00000000..17f6f630 --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_EXT_blend_operation_advanced.txt @@ -0,0 +1,184 @@ +[[VK_EXT_blend_operation_advanced]] +== VK_EXT_blend_operation_advanced +*Name String*:: + VK_EXT_blend_operation_advanced +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 149 +*Status*:: + Complete +*Last Modified Data*:: + 2017-06-12 +*Revision*:: + 2 +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - This extension requires Vulkan 1.0. +*Contributors*:: + - Jeff Bolz, NVIDIA +*Contact*:: + - Jeff Bolz (jbolz 'at' nvidia.com) +*Overview*:: ++ +-- +This extension adds a number of "advanced" blending operations that can: be +used to perform new color blending operations, many of which are more +complex than the standard blend modes provided by unextended Vulkan. +This extension requires different styles of usage, depending on the level of +hardware support and the feature enable: + +- If + slink:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::pname:advancedBlendCoherentOperations + is ename:VK_FALSE, the new blending operations are supported, but a memory + dependency must: separate each advanced blend operation on a given sample. + ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT is used to + synchronize reads using advanced blend operations. + +- If + slink:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT::pname:advancedBlendCoherentOperations + is ename:VK_TRUE, advanced blend operations obey primitive order just like + basic blend operations. + +In unextended Vulkan, the set of blending operations is limited, and can: be +expressed very simply. +The ename:VK_BLEND_OP_MIN and ename:VK_BLEND_OP_MAX blend operations simply +compute component-wise minimums or maximums of source and destination color +components. +The ename:VK_BLEND_OP_ADD, ename:VK_BLEND_OP_SUBTRACT, and +ename:VK_BLEND_OP_REVERSE_SUBTRACT modes multiply the source and destination +colors by source and destination factors and either add the two products +together or subtract one from the other. +This limited set of operations supports many common blending operations but +precludes the use of more sophisticated transparency and blending operations +commonly available in many dedicated imaging APIs. + +This extension provides a number of new "advanced" blending operations. +Unlike traditional blending operations using ename:VK_BLEND_OP_ADD, these +blending equations do not use source and destination factors specified by +elink:VkBlendFactor. +Instead, each blend operation specifies a complete equation based on the +source and destination colors. +These new blend operations are used for both RGB and alpha components; they +must: not be used to perform separate RGB and alpha blending (via different +values of color and alpha elink:VkBlendOp). + +These blending operations are performed using premultiplied colors, where +RGB colors can: be considered premultiplied or non-premultiplied by alpha, +according to the pname:srcPremultiplied and pname:dstPremultiplied members +of slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT. +If a color is considered non-premultiplied, the (R,G,B) color components are +multiplied by the alpha component prior to blending. +For non-premultiplied color components in the range eq#[0,1]#, the +corresponding premultiplied color component would have values in the range +eq#[0 {times} A, 1 {times} A]#. + +Many of these advanced blending equations are formulated where the result of +blending source and destination colors with partial coverage have three +separate contributions: from the portions covered by both the source and the +destination, from the portion covered only by the source, and from the +portion covered only by the destination. +The blend parameter +slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:blendOverlap +can: be used to specify a correlation between source and destination pixel +coverage. +If set to ename:VK_BLEND_OVERLAP_CONJOINT_EXT, the source and destination +are considered to have maximal overlap, as would be the case if drawing two +objects on top of each other. +If set to ename:VK_BLEND_OVERLAP_DISJOINT_EXT, the source and destination +are considered to have minimal overlap, as would be the case when rendering +a complex polygon tessellated into individual non-intersecting triangles. +If set to ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT, the source and +destination coverage are assumed to have no spatial correlation within the +pixel. + +In addition to the coherency issues on implementations not supporting +pname:advancedBlendCoherentOperations, this extension has several +limitations worth noting. +First, the new blend operations have a limit on the number of color +attachments they can: be used with, as indicated by +slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendMaxColorAttachments. +Additionally, blending precision may: be limited to 16-bit floating-point, +which may: result in a loss of precision and dynamic range for framebuffer +formats with 32-bit floating-point components, and in a loss of precision +for formats with 12- and 16-bit signed or unsigned normalized integer +components. +-- + +=== New Object Types +None. + +=== New Enum Constants + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT + ** ename:VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT + + * Extending elink:VkAccessFlagBits: + ** ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT + + * Extending elink:VkBlendOp: + ** ename:VK_BLEND_OP_ZERO_EXT + ** ename:VK_BLEND_OP_SRC_EXT + ** ename:VK_BLEND_OP_DST_EXT + ** ename:VK_BLEND_OP_SRC_OVER_EXT + ** ename:VK_BLEND_OP_DST_OVER_EXT + ** ename:VK_BLEND_OP_SRC_IN_EXT + ** ename:VK_BLEND_OP_DST_IN_EXT + ** ename:VK_BLEND_OP_SRC_OUT_EXT + ** ename:VK_BLEND_OP_DST_OUT_EXT + ** ename:VK_BLEND_OP_SRC_ATOP_EXT + ** ename:VK_BLEND_OP_DST_ATOP_EXT + ** ename:VK_BLEND_OP_XOR_EXT + ** ename:VK_BLEND_OP_MULTIPLY_EXT + ** ename:VK_BLEND_OP_SCREEN_EXT + ** ename:VK_BLEND_OP_OVERLAY_EXT + ** ename:VK_BLEND_OP_DARKEN_EXT + ** ename:VK_BLEND_OP_LIGHTEN_EXT + ** ename:VK_BLEND_OP_COLORDODGE_EXT + ** ename:VK_BLEND_OP_COLORBURN_EXT + ** ename:VK_BLEND_OP_HARDLIGHT_EXT + ** ename:VK_BLEND_OP_SOFTLIGHT_EXT + ** ename:VK_BLEND_OP_DIFFERENCE_EXT + ** ename:VK_BLEND_OP_EXCLUSION_EXT + ** ename:VK_BLEND_OP_INVERT_EXT + ** ename:VK_BLEND_OP_INVERT_RGB_EXT + ** ename:VK_BLEND_OP_LINEARDODGE_EXT + ** ename:VK_BLEND_OP_LINEARBURN_EXT + ** ename:VK_BLEND_OP_VIVIDLIGHT_EXT + ** ename:VK_BLEND_OP_LINEARLIGHT_EXT + ** ename:VK_BLEND_OP_PINLIGHT_EXT + ** ename:VK_BLEND_OP_HARDMIX_EXT + ** ename:VK_BLEND_OP_HSL_HUE_EXT + ** ename:VK_BLEND_OP_HSL_SATURATION_EXT + ** ename:VK_BLEND_OP_HSL_COLOR_EXT + ** ename:VK_BLEND_OP_HSL_LUMINOSITY_EXT + ** ename:VK_BLEND_OP_PLUS_EXT + ** ename:VK_BLEND_OP_PLUS_CLAMPED_EXT + ** ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT + ** ename:VK_BLEND_OP_PLUS_DARKER_EXT + ** ename:VK_BLEND_OP_MINUS_EXT + ** ename:VK_BLEND_OP_MINUS_CLAMPED_EXT + ** ename:VK_BLEND_OP_CONTRAST_EXT + ** ename:VK_BLEND_OP_INVERT_OVG_EXT + ** ename:VK_BLEND_OP_RED_EXT + ** ename:VK_BLEND_OP_GREEN_EXT + ** ename:VK_BLEND_OP_BLUE_EXT + +=== New Enums + * elink:VkBlendOverlapEXT + +=== New Structures + * slink:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT + * slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT + * slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT + +=== New Functions +None. + +=== Issues +None. + +=== Version History + * Revisions 1-2, 2017-06-12 (Jeff Bolz) + - Internal revisions diff --git a/doc/specs/vulkan/appendices/VK_EXT_sampler_filter_minmax.txt b/doc/specs/vulkan/appendices/VK_EXT_sampler_filter_minmax.txt new file mode 100644 index 00000000..5bea45b0 --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_EXT_sampler_filter_minmax.txt @@ -0,0 +1,91 @@ +[[VK_EXT_sampler_filter_minmax]] +== VK_EXT_sampler_filter_minmax + +*Name String*:: + +VK_EXT_sampler_filter_minmax+ +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 131 +*Status*:: + Draft. +*Last Modified Date*:: + 2017-05-19 +*Revision*:: + 2 +*IP Status*:: + No known IP claims. +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - Requires +<>+. +*Contributors*:: + - Jeff Bolz, NVIDIA + - Piers Daniell, NVIDIA +*Contacts*:: + - Jeff Bolz (jbolz 'at' nvidia.com) +*Overview*:: ++ +-- +In unextended Vulkan, minification and magnification filters such as LINEAR +allow sampled image lookups to returned a filtered texel value produced by +computing an weighted average of a collection of texels in the neighborhood +of the texture coordinate provided. + +This extension provides a new sampler parameter which allows applications to +produce a filtered texel value by computing a component-wise minimum (MIN) +or maximum (MAX) of the texels that would normally be averaged. +The reduction mode is orthogonal to the minification and magnification +filter parameters. +The filter parameters are used to identify the set of texels used to produce +a final filtered value; the reduction mode identifies how these texels are +combined. +-- + +=== New Object Types + +None. + +=== New Enum Constants + + * Extending ename:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT + ** ename:VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT + + * Extending ename:VkFormatFeatureFlagBits + ** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT + +=== New Enums + + * elink:VkSamplerReductionModeEXT + +=== New Structures + + * slink:VkSamplerReductionModeCreateInfoEXT + * slink:VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT + +=== New Functions + +None. + +=== New Built-In Variables + +None. + +=== New SPIR-V Capabilities + +None. + +=== Issues + +None. + +=== Examples + +None. + +=== Version History + * Revision 2, 2017-05-19 (Piers Daniell) + - Renamed to EXT + + * Revision 1, 2017-03-25 (Jeff Bolz) + - Internal revisions diff --git a/doc/specs/vulkan/appendices/VK_GOOGLE_display_timing.txt b/doc/specs/vulkan/appendices/VK_GOOGLE_display_timing.txt index a5988a99..7b11df75 100644 --- a/doc/specs/vulkan/appendices/VK_GOOGLE_display_timing.txt +++ b/doc/specs/vulkan/appendices/VK_GOOGLE_display_timing.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2016 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_GOOGLE_display_timing]] == VK_GOOGLE_display_timing diff --git a/doc/specs/vulkan/appendices/VK_KHR_android_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_android_surface.txt index 568fd840..493ff115 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_android_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_android_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_android_surface]] == VK_KHR_android_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_descriptor_update_template.txt b/doc/specs/vulkan/appendices/VK_KHR_descriptor_update_template.txt index 6baf3440..a1ff4541 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_descriptor_update_template.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_descriptor_update_template.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_descriptor_update_template]] == VK_KHR_descriptor_update_template diff --git a/doc/specs/vulkan/appendices/VK_KHR_display.txt b/doc/specs/vulkan/appendices/VK_KHR_display.txt index cb52f8e5..ef2a2ed6 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_display.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_display.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_display]] == VK_KHR_display diff --git a/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt b/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt index 428fb660..c895f16a 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_display_swapchain]] == VK_KHR_display_swapchain diff --git a/doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt b/doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt index 34ed6c04..8f0af83f 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_get_physical_device_properties2]] == VK_KHR_get_physical_device_properties2 diff --git a/doc/specs/vulkan/appendices/VK_KHR_get_surface_capabilities2.txt b/doc/specs/vulkan/appendices/VK_KHR_get_surface_capabilities2.txt index 5aad9853..4f117f5b 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_get_surface_capabilities2.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_get_surface_capabilities2.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_get_surface_capabilities2]] == VK_KHR_get_surface_capabilities2 diff --git a/doc/specs/vulkan/appendices/VK_KHR_incremental_present.txt b/doc/specs/vulkan/appendices/VK_KHR_incremental_present.txt index b911fe30..1fa2edc1 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_incremental_present.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_incremental_present.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_incremental_present]] == VK_KHR_incremental_present diff --git a/doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt b/doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt index 3709026f..3fb4bd53 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_maintenance1.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_maintenance1]] == VK_KHR_maintenance1 diff --git a/doc/specs/vulkan/appendices/VK_KHR_mir_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_mir_surface.txt index 6f3fc5b7..e7916a88 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_mir_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_mir_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_mir_surface]] == VK_KHR_mir_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_push_descriptor.txt b/doc/specs/vulkan/appendices/VK_KHR_push_descriptor.txt index c7f2081f..6a3aa4f0 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_push_descriptor.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_push_descriptor.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_push_descriptor]] == VK_KHR_push_descriptor diff --git a/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt b/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt index 5def4100..f2e51260 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_sampler_mirror_clamp_to_edge]] == VK_KHR_sampler_mirror_clamp_to_edge diff --git a/doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt b/doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt index 70d1fa25..116c0536 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_shader_draw_parameters.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_shader_draw_parameters]] == VK_KHR_shader_draw_parameters diff --git a/doc/specs/vulkan/appendices/VK_KHR_shared_presentable_image.txt b/doc/specs/vulkan/appendices/VK_KHR_shared_presentable_image.txt index 4f4f7b6f..2e982cc8 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_shared_presentable_image.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_shared_presentable_image.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_shared_presentable_image]] == VK_KHR_shared_presentable_image diff --git a/doc/specs/vulkan/appendices/VK_KHR_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_surface.txt index 5149871d..c6b7a926 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_surface]] == VK_KHR_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt b/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt index 9c946747..bb6001b8 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_swapchain.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_swapchain]] == VK_KHR_swapchain diff --git a/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt index 86337d70..f301f37e 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_wayland_surface]] == VK_KHR_wayland_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_win32_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_win32_surface.txt index aab74739..df8bc276 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_win32_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_win32_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_win32_surface]] == VK_KHR_win32_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_xcb_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_xcb_surface.txt index b82ab95d..730a900b 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_xcb_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_xcb_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_xcb_surface]] == VK_KHR_xcb_surface diff --git a/doc/specs/vulkan/appendices/VK_KHR_xlib_surface.txt b/doc/specs/vulkan/appendices/VK_KHR_xlib_surface.txt index aab15c21..61a45c31 100644 --- a/doc/specs/vulkan/appendices/VK_KHR_xlib_surface.txt +++ b/doc/specs/vulkan/appendices/VK_KHR_xlib_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHR_xlib_surface]] == VK_KHR_xlib_surface diff --git a/doc/specs/vulkan/appendices/VK_KHX_device_group.txt b/doc/specs/vulkan/appendices/VK_KHX_device_group.txt index e1d2dc83..14a83a0d 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_device_group.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_device_group.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_device_group]] == VK_KHX_device_group @@ -21,6 +22,7 @@ *Dependencies*:: - This extension is written against version 1.0 of the Vulkan API. - Requires +VK_KHR_swapchain+ revision 68. + - Requires +VK_KHX_device_group_creation+ revision 1. *Contributors*:: - Jeff Bolz, NVIDIA *Contacts*:: diff --git a/doc/specs/vulkan/appendices/VK_KHX_device_group_creation.txt b/doc/specs/vulkan/appendices/VK_KHX_device_group_creation.txt index c8cf5504..b7480be0 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_device_group_creation.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_device_group_creation.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_device_group_creation]] == VK_KHX_device_group_creation diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory.txt index 64967589..c0a13a0d 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_memory]] == VK_KHX_external_memory diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory_capabilities.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory_capabilities.txt index 24f50ae7..9ffe6cb8 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory_capabilities.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory_capabilities.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_memory_capabilities]] == VK_KHX_external_memory_capabilities diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt index cf74d0ef..732998b4 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_memory_fd]] == VK_KHX_external_memory_fd diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt b/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt index 2c5141c5..75ee0b50 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_memory_win32]] == VK_KHX_external_memory_win32 diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore.txt index 54931b3f..18a8252f 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_semaphore]] == VK_KHX_external_semaphore diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_capabilities.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_capabilities.txt index 00273976..0ca047e0 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_capabilities.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_capabilities.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_semaphore_capabilities]] == VK_KHX_external_semaphore_capabilities diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt index 9e58e501..a54c7d8e 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_semaphore_fd]] == VK_KHX_external_semaphore_fd diff --git a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt index e3fb142a..d20e3643 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_external_semaphore_win32]] == VK_KHX_external_semaphore_win32 diff --git a/doc/specs/vulkan/appendices/VK_KHX_multiview.txt b/doc/specs/vulkan/appendices/VK_KHX_multiview.txt index 4c678413..c7d9b5d7 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_multiview.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_multiview.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_multiview]] == VK_KHX_multiview diff --git a/doc/specs/vulkan/appendices/VK_KHX_win32_keyed_mutex.txt b/doc/specs/vulkan/appendices/VK_KHX_win32_keyed_mutex.txt index 782720e3..320cab65 100644 --- a/doc/specs/vulkan/appendices/VK_KHX_win32_keyed_mutex.txt +++ b/doc/specs/vulkan/appendices/VK_KHX_win32_keyed_mutex.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_KHX_win32_keyed_mutex]] == VK_KHX_win32_keyed_mutex diff --git a/doc/specs/vulkan/appendices/VK_MVK_ios_surface.txt b/doc/specs/vulkan/appendices/VK_MVK_ios_surface.txt index ae8d62ab..7c6f0929 100644 --- a/doc/specs/vulkan/appendices/VK_MVK_ios_surface.txt +++ b/doc/specs/vulkan/appendices/VK_MVK_ios_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Brenwill Workshop Ltd. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 The Brenwill Workshop Ltd. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_MVK_ios_surface]] == VK_MVK_ios_surface diff --git a/doc/specs/vulkan/appendices/VK_MVK_macos_surface.txt b/doc/specs/vulkan/appendices/VK_MVK_macos_surface.txt index 4d6c249e..2e46cb72 100644 --- a/doc/specs/vulkan/appendices/VK_MVK_macos_surface.txt +++ b/doc/specs/vulkan/appendices/VK_MVK_macos_surface.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Brenwill Workshop Ltd. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 The Brenwill Workshop Ltd. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[VK_MVK_macos_surface]] == VK_MVK_macos_surface diff --git a/doc/specs/vulkan/appendices/VK_NV_fill_rectangle.txt b/doc/specs/vulkan/appendices/VK_NV_fill_rectangle.txt new file mode 100644 index 00000000..74390dd8 --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_NV_fill_rectangle.txt @@ -0,0 +1,56 @@ +[[VK_NV_fill_rectangle]] +== VK_NV_fill_rectangle +*Name String*:: + VK_NV_fill_rectangle +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 154 +*Status*:: + Complete +*Last Modified Data*:: + 2017-05-22 +*Revision*:: + 1 +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - This extension requires Vulkan 1.0. +*Contributors*:: + - Jeff Bolz, NVIDIA +*Contact*:: + - Jeff Bolz (jbolz 'at' nvidia.com) +*Overview*:: ++ +-- +This extension adds a new elink:VkPolygonMode enum where a triangle is +rasterized by computing and filling its axis-aligned screen-space bounding +box, disregarding the actual triangle edges. +This can be useful for drawing a rectangle without being split into two +triangles with an internal edge. +It is also useful to minimize the number of primitives that need to be +drawn, particularly for a user interface. +-- + +=== New Object Types +None. + +=== New Enum Constants + * Extending elink:VkPolygonMode + + ** ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV + +=== New Enums +None. + +=== New Structures +None. + +=== New Functions +None. + +=== Issues +None. + +=== Version History + * Revision 1, 2017-05-22 (Jeff Bolz) + - Internal revisions diff --git a/doc/specs/vulkan/appendices/VK_NV_fragment_coverage_to_color.txt b/doc/specs/vulkan/appendices/VK_NV_fragment_coverage_to_color.txt new file mode 100644 index 00000000..23b8fbb9 --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_NV_fragment_coverage_to_color.txt @@ -0,0 +1,61 @@ +[[VK_NV_fragment_coverage_to_color]] +== VK_NV_fragment_coverage_to_color +*Name String*:: + VK_NV_fragment_coverage_to_color +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 150 +*Status*:: + Complete +*Last Modified Data*:: + 2017-05-21 +*Revision*:: + 1 +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - This extension requires Vulkan 1.0. +*Contributors*:: + - Jeff Bolz, NVIDIA +*Contact*:: + - Jeff Bolz (jbolz 'at' nvidia.com) +*Overview*:: ++ +-- +This extension allows the fragment coverage value, represented as an integer +bitmask, to be substituted for a color output being written to a +single-component color attachment with integer components (e.g. +ename:VK_FORMAT_R8_UINT). +The functionality provided by this extension is different from simply +writing the code:SampleMask fragment shader output, in that the coverage +value written to the framebuffer is taken after stencil test and depth test, +as well as after fragment operations such as alpha-to-coverage. + +This functionality may be useful for deferred rendering algorithms, where +the second pass needs to know which samples belong to which original +fragments. +-- + +=== New Object Types +None. + +=== New Enum Constants + * Extending elink:VkStructureType: + + ** ename:VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV + +=== New Enums + * elink:VkPipelineCoverageToColorStateCreateFlagsNV + +=== New Structures + * slink:VkPipelineCoverageToColorStateCreateInfoNV + +=== New Functions +None. + +=== Issues +None. + +=== Version History + * Revision 1, 2017-05-21 (Jeff Bolz) + - Internal revisions diff --git a/doc/specs/vulkan/appendices/VK_NV_framebuffer_mixed_samples.txt b/doc/specs/vulkan/appendices/VK_NV_framebuffer_mixed_samples.txt new file mode 100644 index 00000000..d2a3a4cb --- /dev/null +++ b/doc/specs/vulkan/appendices/VK_NV_framebuffer_mixed_samples.txt @@ -0,0 +1,86 @@ +[[VK_NV_framebuffer_mixed_samples]] +== VK_NV_framebuffer_mixed_samples +*Name String*:: + VK_NV_framebuffer_mixed_samples +*Extension Type*:: + Device extension +*Registered Extension Number*:: + 153 +*Status*:: + Complete +*Last Modified Data*:: + 2017-06-04 +*Revision*:: + 1 +*Dependencies*:: + - This extension is written against version 1.0 of the Vulkan API. + - This extension requires Vulkan 1.0. +*Contributors*:: +*Contact*:: + - Jeff Bolz (jbolz 'at' nvidia.com) +*Overview*:: ++ +-- +This extension allows multisample rendering with a raster and depth/stencil +sample count that is larger than the color sample count. +Rasterization and the results of the depth and stencil tests together +determine the portion of a pixel that is "covered". +It can be useful to evaluate coverage at a higher frequency than color +samples are stored. +This coverage is then "reduced" to a collection of covered color samples, +each having an opacity value corresponding to the fraction of the color +sample covered. +The opacity can optionally be blended into individual color samples. + +Rendering with fewer color samples than depth/stencil samples greatly +reduces the amount of memory and bandwidth consumed by the color buffer. +However, converting the coverage values into opacity introduces artifacts +where triangles share edges and may: not be suitable for normal triangle +mesh rendering. + +One expected use case for this functionality is Stencil-then-Cover path +rendering (similar to the OpenGL GL_NV_path_rendering extension). +The stencil step determines the coverage (in the stencil buffer) for an +entire path at the higher sample frequency, and then the cover step draws +the path into the lower frequency color buffer using the coverage +information to antialias path edges. +With this two-step process, internal edges are fully covered when +antialiasing is applied and there is no corruption on these edges. + +The key features of this extension are: + + * It allows render pass and framebuffer objects to be created where the + number of samples in the depth/stencil attachment in a subpass is a + multiple of the number of samples in the color attachments in the + subpass. + + * A coverage reduction step is added to Fragment Operations which converts + a set of covered raster/depth/stencil samples to a set of color samples + that perform blending and color writes. + The coverage reduction step also includes an optional coverage modulation + step, multiplying color values by a fractional opacity corresponding to + the number of associated raster/depth/stencil samples covered. +-- + +=== New Object Types +None. + +=== New Enum Constants +None. + +=== New Enums + * elink:VkCoverageModulationModeNV + * elink:VkPipelineCoverageModulationStateCreateFlagsNV + +=== New Structures + * slink:VkPipelineCoverageModulationStateCreateInfoNV + +=== New Functions +None. + +=== Issues +None. + +=== Version History + * Revision 1, 2017-06-04 (Jeff Bolz) + - Internal revisions diff --git a/doc/specs/vulkan/appendices/boilerplate.txt b/doc/specs/vulkan/appendices/boilerplate.txt index 7b241034..ef1628e0 100644 --- a/doc/specs/vulkan/appendices/boilerplate.txt +++ b/doc/specs/vulkan/appendices/boilerplate.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] [[boilerplate]] @@ -13,7 +14,8 @@ elsewhere in the Specification. [[boilerplate-sType]] == Structure Types -// refBegin VkStructureType Vulkan structure types (pname:stype) +[open,refpage='VkStructureType',desc='Vulkan structure types (pname:stype)',type='enums'] +-- Vulkan structures containing pname:sType members must: have a value of pname:sType matching the type of the structure, as described more fully in @@ -22,7 +24,7 @@ Structure types supported by the Vulkan API include: include::../api/enums/VkStructureType.txt[] -// refEnd VkStructureType +-- [[boilerplate-flags]] @@ -86,6 +88,12 @@ include::../api/flags/VkPeerMemoryFeatureFlagsKHX.txt[] endif::VK_KHX_device_group[] include::../api/flags/VkPipelineCacheCreateFlags.txt[] include::../api/flags/VkPipelineColorBlendStateCreateFlags.txt[] +ifdef::VK_NV_fragment_coverage_to_color[] +include::../api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.txt[] +endif::VK_NV_fragment_coverage_to_color[] +ifdef::VK_NV_framebuffer_mixed_samples[] +include::../api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.txt[] +endif::VK_NV_framebuffer_mixed_samples[] include::../api/flags/VkPipelineCreateFlags.txt[] include::../api/flags/VkPipelineDepthStencilStateCreateFlags.txt[] include::../api/flags/VkPipelineDynamicStateCreateFlags.txt[] @@ -138,34 +146,38 @@ macros that are described below. <> are packed into integers. These macros manipulate version numbers in useful ways. -// refBegin VK_VERSION_MAJOR Extract API major version number +[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines'] +-- dname:VK_VERSION_MAJOR extracts the API major version number from a packed version number: include::../api/defines/VK_VERSION_MAJOR.txt[] -// refEnd VK_VERSION_MAJOR +-- -// refBegin VK_VERSION_MINOR Extract API minor version number +[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines'] +-- dname:VK_VERSION_MINOR extracts the API minor version number from a packed version number: include::../api/defines/VK_VERSION_MINOR.txt[] -// refEnd VK_VERSION_MINOR +-- -// refBegin VK_VERSION_PATCH Extract API patch version number +[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines'] +-- dname:VK_VERSION_PATCH extracts the API patch version number from a packed version number: include::../api/defines/VK_VERSION_PATCH.txt[] -// refEnd VK_VERSION_PATCH +-- -// refBegin VK_API_VERSION_1_0 Return API version number for Vulkan 1.0 +[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] +-- dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0. The patch version number in this macro will always be zero. @@ -174,17 +186,19 @@ flink:vkGetPhysicalDeviceProperties. include::../api/defines/VK_API_VERSION_1_0.txt[] -// refEnd VK_API_VERSION_1_0 vkCreateInstance vkGetPhysicalDeviceProperties +-- -// refBegin VK_API_VERSION Deprecated version number macro +[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines'] +-- dname:VK_API_VERSION is now commented out of +vulkan.h+ and cannot: be used. include::../api/defines/VK_API_VERSION.txt[] -// refEnd VK_API_VERSION +-- -// refBegin VK_MAKE_VERSION Construct an API version number +[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] +-- dname:VK_MAKE_VERSION constructs an API version number. @@ -198,12 +212,13 @@ This macro can: be used when constructing the slink:VkApplicationInfo::pname:apiVersion parameter passed to flink:vkCreateInstance. -// refEnd VK_MAKE_VERSION VkApplicationInfo vkCreateInstance +-- === Vulkan Header File Version Number -// refBegin VK_HEADER_VERSION Vulkan header file version number +[open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines'] +-- dname:VK_HEADER_VERSION is the version number of the +vulkan.h+ header. This value is currently kept synchronized with the release number of the @@ -213,12 +228,13 @@ Specification updates have no effect on +vulkan.h+. include::../api/defines/VK_HEADER_VERSION.txt[] -// refEnd VK_HEADER_VERSION +-- === Vulkan Handle Macros -// refBegin VK_DEFINE_HANDLE Declare a dispatchable object handle +[open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue'] +-- dname:VK_DEFINE_HANDLE defines a <> type. @@ -230,9 +246,10 @@ include::../api/defines/VK_DEFINE_HANDLE.txt[] The only dispatchable handle types are those related to device and instance management, such as slink:VkDevice. -// refEnd VK_DEFINE_HANDLE VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue +-- -// refBegin VK_DEFINE_NON_DISPATCHABLE_HANDLE Declare a non-dispatchable object handle +[open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer'] +-- dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a <> type. @@ -260,9 +277,10 @@ careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition. ================== -// refEnd VK_DEFINE_NON_DISPATCHABLE_HANDLE VkBuffer +-- -// refBegin VK_NULL_HANDLE Reserved non-valid object handle +[open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines'] +-- dname:VK_NULL_HANDLE is a reserved value representing a non-valid object handle. @@ -271,8 +289,7 @@ 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+ diff --git a/doc/specs/vulkan/appendices/compressedtex.txt b/doc/specs/vulkan/appendices/compressedtex.txt index ef35369d..2024fa13 100644 --- a/doc/specs/vulkan/appendices/compressedtex.txt +++ b/doc/specs/vulkan/appendices/compressedtex.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] = Compressed Image Formats diff --git a/doc/specs/vulkan/appendices/credits.txt b/doc/specs/vulkan/appendices/credits.txt index 28d5d111..2bf4049d 100644 --- a/doc/specs/vulkan/appendices/credits.txt +++ b/doc/specs/vulkan/appendices/credits.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] [[credits]] diff --git a/doc/specs/vulkan/appendices/extensions.txt b/doc/specs/vulkan/appendices/extensions.txt index 3ea3b498..17a9cb21 100644 --- a/doc/specs/vulkan/appendices/extensions.txt +++ b/doc/specs/vulkan/appendices/extensions.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] @@ -195,6 +196,10 @@ ifdef::VK_EXT_acquire_xlib_display[] include::VK_EXT_acquire_xlib_display.txt[] endif::VK_EXT_acquire_xlib_display[] +ifdef::VK_EXT_blend_operation_advanced[] +include::VK_EXT_blend_operation_advanced.txt[] +endif::VK_EXT_blend_operation_advanced[] + ifdef::VK_EXT_debug_marker[] include::VK_EXT_debug_marker.txt[] endif::VK_EXT_debug_marker[] @@ -223,6 +228,10 @@ ifdef::VK_EXT_hdr_metadata[] include::VK_EXT_hdr_metadata.txt[] endif::VK_EXT_hdr_metadata[] +ifdef::VK_EXT_sampler_filter_minmax[] +include::VK_EXT_sampler_filter_minmax.txt[] +endif::VK_EXT_sampler_filter_minmax[] + ifdef::VK_EXT_shader_subgroup_ballot[] include::VK_EXT_shader_subgroup_ballot.txt[] endif::VK_EXT_shader_subgroup_ballot[] @@ -258,6 +267,10 @@ ifdef::VK_AMD_gpu_shader_half_float[] include::VK_AMD_gpu_shader_half_float.txt[] endif::VK_AMD_gpu_shader_half_float[] +ifdef::VK_AMD_gpu_shader_int16[] +include::VK_AMD_gpu_shader_int16.txt[] +endif::VK_AMD_gpu_shader_int16[] + ifdef::VK_AMD_negative_viewport_height[] include::VK_AMD_negative_viewport_height.txt[] endif::VK_AMD_negative_viewport_height[] @@ -355,6 +368,18 @@ ifdef::VK_NV_external_memory_win32[] include::VK_NV_external_memory_win32.txt[] endif::VK_NV_external_memory_win32[] +ifdef::VK_NV_fill_rectangle[] +include::VK_NV_fill_rectangle.txt[] +endif::VK_NV_fill_rectangle[] + +ifdef::VK_NV_fragment_coverage_to_color[] +include::VK_NV_fragment_coverage_to_color.txt[] +endif::VK_NV_fragment_coverage_to_color[] + +ifdef::VK_NV_framebuffer_mixed_samples[] +include::VK_NV_framebuffer_mixed_samples.txt[] +endif::VK_NV_framebuffer_mixed_samples[] + ifdef::VK_NV_geometry_shader_passthrough[] include::VK_NV_geometry_shader_passthrough.txt[] endif::VK_NV_geometry_shader_passthrough[] diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt index bb4dbad2..6f99c218 100644 --- a/doc/specs/vulkan/appendices/glossary.txt +++ b/doc/specs/vulkan/appendices/glossary.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ // The asciidoc [glossary] template cannot contain subsections. // The abbreviations and prefixes probably belong in the upcoming @@ -25,6 +26,13 @@ Adjacent Vertex:: A vertex in an adjacency primitive topology that is not part of a given primitive, but is accessible in geometry shaders. +ifdef::VK_EXT_blend_operation_advanced[] +Advanced Blend Operation:: + Blending performed using one of the blend operation enums introduced by + the +VK_EXT_blend_operation_advanced+ extension. + See <>. +endif::VK_EXT_blend_operation_advanced[] + Aliased Range (Memory):: A range of a device memory allocation that is bound to multiple resources simultaneously. @@ -145,6 +153,13 @@ Color Renderable Format:: field of VkFormatProperties::optimalTilingFeatures returned by flink:vkGetPhysicalDeviceFormatProperties, depending on the tiling used. +Color Sample Mask:: + A bitfield associated with a fragment, with one bit for each sample in + the color attachment(s). + Samples are considered to be covered based on the result of the Coverage + Reduction stage. + Uncovered samples do not write to color attachments. + Combined Image Sampler:: A descriptor type that includes both a sampled image and a sampler. @@ -186,6 +201,14 @@ Compressed Texel Block:: these elements in units of texels, and a size in bytes of the encoding in memory. +Coverage:: + A bitfield associated with a fragment, where each bit is associated to a + rasterization sample. + Samples are initially considered to be covered based on the result of + rasterization, and then coverage can subsequently be turned on or off by + other fragment operations or the fragment shader. + Uncovered samples do not write to framebuffer attachments. + Cull Distance:: A built-in output from vertex processing stages that defines a cull half-space where the primitive is rejected if all vertices have a diff --git a/doc/specs/vulkan/appendices/invariance.txt b/doc/specs/vulkan/appendices/invariance.txt index 708c994f..4771cff2 100644 --- a/doc/specs/vulkan/appendices/invariance.txt +++ b/doc/specs/vulkan/appendices/invariance.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] [[invariance]] diff --git a/doc/specs/vulkan/appendices/spirvenv.txt b/doc/specs/vulkan/appendices/spirvenv.txt index 0ce42eb2..aafadd18 100644 --- a/doc/specs/vulkan/appendices/spirvenv.txt +++ b/doc/specs/vulkan/appendices/spirvenv.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [appendix] [[spirvenv]] @@ -134,6 +135,11 @@ The application can: pass a SPIR-V module to flink:vkCreateShaderModule that uses the +SPV_AMD_gpu_shader_half_float+ SPIR-V extension. endif::VK_AMD_gpu_shader_half_float[] +ifdef::VK_AMD_gpu_shader_int16[] +The application can: pass a SPIR-V module to flink:vkCreateShaderModule that +uses the +SPV_AMD_gpu_shader_int16+ SPIR-V extension. +endif::VK_AMD_gpu_shader_int16[] + ifdef::VK_AMD_shader_ballot[] The application can: pass a SPIR-V module to flink:vkCreateShaderModule that uses the +SPV_AMD_shader_ballot+ SPIR-V extension. diff --git a/doc/specs/vulkan/chapters/VK_EXT_acquire_xlib_display/acquire_xlib_display.txt b/doc/specs/vulkan/chapters/VK_EXT_acquire_xlib_display/acquire_xlib_display.txt index 5dfbb6ca..602a2e37 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_acquire_xlib_display/acquire_xlib_display.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_acquire_xlib_display/acquire_xlib_display.txt @@ -1,4 +1,5 @@ -// refBegin vkAcquireXlibDisplayEXT Acquire access to a VkDisplayKHR using Xlib +[open,refpage='vkAcquireXlibDisplayEXT',desc='Acquire access to a VkDisplayKHR using Xlib',type='protos'] +-- To acquire permission to directly access a display in Vulkan from an X11 server, call: @@ -30,8 +31,10 @@ ownership of its virtual terminal. ==== include::../../validity/protos/vkAcquireXlibDisplayEXT.txt[] +-- -// refBegin vkGetRandROutputDisplayEXT Query the VkDisplayKHR corresponding to an X11 RandR Output +[open,refpage='vkGetRandROutputDisplayEXT',desc='Query the VkDisplayKHR corresponding to an X11 RandR Output',type='protos'] +-- When acquiring displays from an X11 server, an application may also wish to enumerate and identify them using a native handle rather than a @@ -53,3 +56,4 @@ pname:physicalDevice, ename:VK_NULL_HANDLE must: be returned in pname:pDisplay. include::../../validity/protos/vkGetRandROutputDisplayEXT.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt b/doc/specs/vulkan/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt new file mode 100644 index 00000000..d885d872 --- /dev/null +++ b/doc/specs/vulkan/chapters/VK_EXT_blend_operation_advanced/advanced_blend.txt @@ -0,0 +1,805 @@ + +[[framebuffer-blend-advanced]] +=== Advanced Blend Operations + +The _advanced blend operations_ are those listed in tables +<>, +<>, and +<>. + +[open,refpage='VkPipelineColorBlendAdvancedStateCreateInfoEXT',desc='Structure specifying parameters that affect advanced blend operations',type='structs'] +-- + +If the pname:pNext list of slink:VkPipelineColorBlendStateCreateInfo +includes a sname:VkPipelineColorBlendAdvancedStateCreateInfoEXT structure, +then that structure includes parameters that affect advanced blend +operations. + +The sname:VkPipelineColorBlendAdvancedStateCreateInfoEXT structure is +defined as: + +include::../../api/structs/VkPipelineColorBlendAdvancedStateCreateInfoEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:srcPremultiplied specifies whether the source color of the blend + operation is treated as premultiplied. + * pname:dstPremultiplied specifies whether the destination color of the + blend operation is treated as premultiplied. + * pname:blendOverlap is a elink:VkBlendOverlapEXT value specifying how the + source and destination sample's coverage is correlated. + +If this structure is not present, pname:srcPremultiplied and +pname:dstPremultiplied are both considered to be ename:VK_TRUE, and +pname:blendOverlap is considered to be +ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT. + +.Valid Usage +**** + * [[VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-srcPremultiplied-01424]] + If the + <> property is not supported, pname:srcPremultiplied must: + be ename:VK_TRUE + * [[VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-dstPremultiplied-01425]] + If the + <> property is not supported, pname:dstPremultiplied + must: be ename:VK_TRUE + * [[VUID-VkPipelineColorBlendAdvancedStateCreateInfoEXT-blendOverlap-01426]] + If the <> property is not supported, pname:blendOverlap must: be + ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT +**** + +include::../../validity/structs/VkPipelineColorBlendAdvancedStateCreateInfoEXT.txt[] +-- + +When using one of the operations in table +<> +or <>, blending is performed according to the following +equations: + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + R & = & f(R_s',R_d')*p_0(A_s,A_d) & + & Y*R_s'*p_1(A_s,A_d) & + & Z*R_d'*p_2(A_s,A_d) \\ + G & = & f(G_s',G_d')*p_0(A_s,A_d) & + & Y*G_s'*p_1(A_s,A_d) & + & Z*G_d'*p_2(A_s,A_d) \\ + B & = & f(B_s',B_d')*p_0(A_s,A_d) & + & Y*B_s'*p_1(A_s,A_d) & + & Z*B_d'*p_2(A_s,A_d) \\ + A & = & X*p_0(A_s,A_d) & + & Y*p_1(A_s,A_d) & + & Z*p_2(A_s,A_d) +\end{aligned} ++++++++++++++++++++ + +where the function f and terms X, Y, and Z are specified in the table. +The R, G, and B components of the source color used for blending are derived +according to pname:srcPremultiplied. +If pname:srcPremultiplied is set to ename:VK_TRUE, the fragment color +components are considered to have been premultiplied by the A component +prior to blending. +The base source color [eq]#(R~s~',G~s~',B~s~')# is obtained by dividing +through by the A component: + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + (R_s', G_s', B_s') & = + \begin{cases} + (0, 0, 0) & A_s = 0 \\ + (\frac{R_s}{A_s}, \frac{G_s}{A_s}, \frac{B_s}{A_s}) & \text{otherwise} + \end{cases} +\end{aligned} ++++++++++++++++++++ + +If pname:srcPremultiplied is ename:VK_FALSE, the fragment color components +are used as the base color: + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + (R_s', G_s', B_s') & = (R_s, G_s, B_s) +\end{aligned} ++++++++++++++++++++ + +The R, G, and B components of the destination color used for blending are +derived according to pname:dstPremultiplied. +If pname:dstPremultiplied is set to ename:VK_TRUE, the destination +components are considered to have been premultiplied by the A component +prior to blending. +The base destination color [eq]#(R~d~',G~d~',B~d~')# is obtained by dividing +through by the A component: + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + (R_d', G_d', B_d') & = + \begin{cases} + (0, 0, 0) & A_d = 0 \\ + (\frac{R_d}{A_d}, \frac{G_d}{A_d}, \frac{B_d}{A_d}) & \text{otherwise} + \end{cases} +\end{aligned} ++++++++++++++++++++ + +If pname:dstPremultiplied is ename:VK_FALSE, the destination color +components are used as the base color: + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + (R_d', G_d', B_d') & = (R_d, G_d, B_d) +\end{aligned} ++++++++++++++++++++ + +[open,refpage='VkBlendOverlapEXT',desc='Enumerant specifying the blend overlap parameter',type='enums'] +-- + +When blending using advanced blend operations, we expect that the R, G, and +B components of premultiplied source and destination color inputs be stored +as the product of non-premultiplied R, G, and B component values and the A +component of the color. +If any R, G, or B component of a premultiplied input color is non-zero and +the A component is zero, the color is considered ill-formed, and the +corresponding component of the blend result is undefined. + +The weighting functions [eq]#p~0~#, [eq]#p~1~#, and [eq]#p~2~# are defined +in table <>. +In these functions, the A components of the source and destination colors +are taken to indicate the portion of the pixel covered by the fragment +(source) and the fragments previously accumulated in the pixel +(destination). +The functions [eq]#p~0~#, [eq]#p~1~#, and [eq]#p~2~# approximate the +relative portion of the pixel covered by the intersection of the source and +destination, covered only by the source, and covered only by the +destination, respectively. + +Possible values of +slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:blendOverlap, +specifying the blend overlap functions, are: + +include::../../api/enums/VkBlendOverlapEXT.txt[] + + * ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT specifies that there is no + correlation between the source and destination coverage. + * ename:VK_BLEND_OVERLAP_CONJOINT_EXT specifies that the source and + destination coverage are considered to have maximal overlap. + * ename:VK_BLEND_OVERLAP_DISJOINT_EXT specifies that the source and + destination coverage are considered to have minimal overlap. + +[[framebuffer-blend-advanced-overlap-modes]] +.Advanced Blend Overlap Modes +[width="80%",options="header"] +|==== +| Overlap Mode | Weighting Equations +| ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + p_0(A_s,A_d) & = A_sA_d \\ + p_1(A_s,A_d) & = A_s(1-A_d) \\ + p_2(A_s,A_d) & = A_d(1-A_s) \\ + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OVERLAP_CONJOINT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + p_0(A_s,A_d) & = min(A_s,A_d) \\ + p_1(A_s,A_d) & = max(A_s-A_d,0) \\ + p_2(A_s,A_d) & = max(A_d-A_s,0) \\ + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +| ename:VK_BLEND_OVERLAP_DISJOINT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + p_0(A_s,A_d) & = max(A_s+A_d-1,0) \\ + p_1(A_s,A_d) & = min(A_s,1-A_d) \\ + p_2(A_s,A_d) & = min(A_d,1-A_s) \\ + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +|==== +-- + +[[framebuffer-blend-advanced-fxyz-modes]] +.f/X/Y/Z Advanced Blend Operations +[width="80%",options="header"] +|==== +| Mode | Blend Coefficients +| ename:VK_BLEND_OP_ZERO_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (0,0,0) \\ + f(C_s,C_d) & = 0 + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +| ename:VK_BLEND_OP_SRC_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,0) \\ + f(C_s,C_d) & = C_s + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DST_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,1) \\ + f(C_s,C_d) & = C_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SRC_OVER_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = C_s + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DST_OVER_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = C_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SRC_IN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,0) \\ + f(C_s,C_d) & = C_s + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DST_IN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,0) \\ + f(C_s,C_d) & = C_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SRC_OUT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (0,1,0) \\ + f(C_s,C_d) & = 0 + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DST_OUT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (0,0,1) \\ + f(C_s,C_d) & = 0 + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SRC_ATOP_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,1) \\ + f(C_s,C_d) & = C_s + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DST_ATOP_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,0) \\ + f(C_s,C_d) & = C_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_XOR_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (0,1,1) \\ + f(C_s,C_d) & = 0 + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_MULTIPLY_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = C_sC_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SCREEN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = C_s+C_d-C_sC_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +| ename:VK_BLEND_OP_OVERLAY_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 2 C_sC_d & C_d \leq 0.5 \\ + 1-2 (1-C_s)(1-C_d) & \text{otherwise} + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DARKEN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = min(C_s,C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_LIGHTEN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = max(C_s,C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_COLORDODGE_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 0 & C_d \leq 0 \\ + min(1,\frac{C_d}{1-C_s}) & C_d \gt 0 \text{ and } C_s \lt 1 \\ + 1 & C_d \gt 0 \text{ and } C_s \geq 1 + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_COLORBURN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 1 & C_d \geq 1 \\ + 1 - min(1,\frac{1-C_d}{C_s}) & C_d \lt 1 \text{ and } C_s \gt 0 \\ + 0 & C_d \lt 1 \text{ and } C_s \leq 0 + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_HARDLIGHT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 2 C_sC_d & C_s \leq 0.5 \\ + 1-2 (1-C_s)(1-C_d) & \text{otherwise} + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_SOFTLIGHT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + C_d-(1-2 C_s)C_d(1-C_d) & C_s \leq 0.5 \\ + C_d+(2 C_s-1)C_d((16 C_d-12)C_d+3) & C_s \gt 0.5 \text{ and } C_d \leq 0.25 \\ + C_d+(2 C_s-1)(\sqrt{C_d}-C_d) & C_s \gt 0.5 \text{ and } C_d \gt 0.25 + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_DIFFERENCE_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = \lvert C_d-C_s \rvert + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_EXCLUSION_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = C_s+C_d-2C_sC_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_INVERT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,1) \\ + f(C_s,C_d) & = 1-C_d + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_INVERT_RGB_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,0,1) \\ + f(C_s,C_d) & = C_s(1-C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_LINEARDODGE_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + C_s+C_d & C_s+C_d \leq 1 \\ + 1 & \text{otherwise} + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_LINEARBURN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + C_s+C_d-1 & C_s+C_d \gt 1 \\ + 0 & \text{otherwise} + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_VIVIDLIGHT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 1-min(1,\frac{1-C_d}{2C_s}) & 0 \lt C_s \lt 0.5 \\ + 0 & C_s \leq 0 \\ + min(1,\frac{C_d}{2(1-C_s)}) & 0.5 \leq C_s \lt 1 \\ + 1 & C_s \geq 1 + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_LINEARLIGHT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 1 & 2C_s+C_d \gt 2 \\ + 2C_s+C_d-1 & 1 \lt 2C_s+C_d \leq 2 \\ + 0 & 2C_s+C_d \leq 1 + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_PINLIGHT_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 0 & 2C_s-1 \gt C_d \text{ and } C_s \lt 0.5 \\ + 2C_s-1 & 2C_s-1 \gt C_d \text{ and } C_s \geq 0.5 \\ + 2C_s & 2C_s-1 \leq C_d \text{ and } C_s \lt 0.5C_d \\ + C_d & 2C_s-1 \leq C_d \text{ and } C_s \geq 0.5C_d + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_HARDMIX_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = + \begin{cases} + 0 & C_s+C_d \lt 1 \\ + 1 & \text{otherwise} + \end{cases} + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +|==== + + +When using one of the HSL blend operations in table +<> as the blend operation, the RGB color components produced +by the function f are effectively obtained by converting both the +non-premultiplied source and destination colors to the HSL (hue, saturation, +luminosity) color space, generating a new HSL color by selecting H, S, and L +components from the source or destination according to the blend operation, +and then converting the result back to RGB. +In the equations below, a blended RGB color is produced according to the +following pseudocode: + +[source,c++] +---------------------------------------- + float minv3(vec3 c) { + return min(min(c.r, c.g), c.b); + } + float maxv3(vec3 c) { + return max(max(c.r, c.g), c.b); + } + float lumv3(vec3 c) { + return dot(c, vec3(0.30, 0.59, 0.11)); + } + float satv3(vec3 c) { + return maxv3(c) - minv3(c); + } + + // If any color components are outside [0,1], adjust the color to + // get the components in range. + vec3 ClipColor(vec3 color) { + float lum = lumv3(color); + float mincol = minv3(color); + float maxcol = maxv3(color); + if (mincol < 0.0) { + color = lum + ((color-lum)*lum) / (lum-mincol); + } + if (maxcol > 1.0) { + color = lum + ((color-lum)*lum) / (maxcol-lum); + } + return color; + } + + // Take the base RGB color and override its luminosity + // with that of the RGB color . + vec3 SetLum(vec3 cbase, vec3 clum) { + float lbase = lumv3(cbase); + float llum = lumv3(clum); + float ldiff = llum - lbase; + vec3 color = cbase + vec3(ldiff); + return ClipColor(color); + } + + // Take the base RGB color and override its saturation with + // that of the RGB color . The override the luminosity of the + // result with that of the RGB color . + vec3 SetLumSat(vec3 cbase, vec3 csat, vec3 clum) + { + float minbase = minv3(cbase); + float sbase = satv3(cbase); + float ssat = satv3(csat); + vec3 color; + if (sbase > 0) { + // Equivalent (modulo rounding errors) to setting the + // smallest (R,G,B) component to 0, the largest to , + // and interpolating the "middle" component based on its + // original value relative to the smallest/largest. + color = (cbase - minbase) * ssat / sbase; + } else { + color = vec3(0.0); + } + return SetLum(color, clum); + } +---------------------------------------- + +[[framebuffer-blend-advanced-hsl-modes]] +.Hue-Saturation-Luminosity Advanced Blend Operations +[width="80%",options="header"] +|==== +| Mode | Result +| ename:VK_BLEND_OP_HSL_HUE_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = SetLumSat(C_s,C_d,C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_HSL_SATURATION_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = SetLumSat(C_d,C_s,C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_HSL_COLOR_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = SetLum(C_s,C_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_HSL_LUMINOSITY_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (X,Y,Z) & = (1,1,1) \\ + f(C_s,C_d) & = SetLum(C_d,C_s) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +|==== + + +When using one of the operations in table +<> as the blend operation, the source and destination colors used +by these blending operations are interpreted according to +pname:srcPremultiplied and pname:dstPremultiplied. +The blending operations below are evaluated where the RGB source and +destination color components are both considered to have been premultiplied +by the corresponding A component. + +[latexmath] ++++++++++++++++++++ +\begin{aligned} + (R_s', G_s', B_s') & = + \begin{cases} + (R_s, G_s, B_s) & \text{if srcPremultiplied is VK\_TRUE} \\ + (R_sA_s, G_sA_s, B_sA_s) & \text{if srcPremultiplied is VK\_FALSE} + \end{cases} \\ + (R_d', G_d', B_d') & = + \begin{cases} + (R_d, G_d, B_d) & \text{if dstPremultiplied is VK\_TRUE} \\ + (R_dA_d, G_dA_d, B_dA_d) & \text{if dstPremultiplied is VK\_FALSE} + \end{cases} +\end{aligned} ++++++++++++++++++++ + +[[framebuffer-blend-advanced-additional-rgb]] +.Additional RGB Blend Operations +[width="80%",options="header"] +|==== +| Mode | Result +| ename:VK_BLEND_OP_PLUS_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & R_s'+R_d', \\ + & G_s'+G_d', \\ + & B_s'+B_d', \\ + & A_s+A_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_PLUS_CLAMPED_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & min(1,R_s'+R_d'), \\ + & min(1,G_s'+G_d'), \\ + & min(1,B_s'+B_d'), \\ + & min(1,A_s+A_d)) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & min(min(1,A_s+A_d),R_s'+R_d'), \\ + & min(min(1,A_s+A_d),G_s'+G_d'), \\ + & min(min(1,A_s+A_d),B_s'+B_d'), \\ + & min(1,A_s+A_d)) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_PLUS_DARKER_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & max(0,min(1,A_s+A_d)-((A_s-R_s')+(A_d-R_d'))), \\ + & max(0,min(1,A_s+A_d)-((A_s-G_s')+(A_d-G_d'))), \\ + & max(0,min(1,A_s+A_d)-((A_s-B_s')+(A_d-B_d'))), \\ + & min(1,A_s+A_d)) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_MINUS_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & R_d'-R_s', \\ + & G_d'-G_s', \\ + & B_d'-B_s', \\ + & A_d-A_s) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_MINUS_CLAMPED_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & max(0,R_d'-R_s'), \\ + & max(0,G_d'-G_s'), \\ + & max(0,B_d'-B_s'), \\ + & max(0,A_d-A_s)) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_CONTRAST_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & \frac{A_d}{2} + 2(R_d'-\frac{A_d}{2})(R_s'-\frac{A_s}{2}), \\ + & \frac{A_d}{2} + 2(G_d'-\frac{A_d}{2})(G_s'-\frac{A_s}{2}), \\ + & \frac{A_d}{2} + 2(B_d'-\frac{A_d}{2})(B_s'-\frac{A_s}{2}), \\ + & A_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_INVERT_OVG_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) = ( & A_s(1-R_d') + (1-A_s)R_d', \\ + & A_s(1-G_d') + (1-A_s)G_d', \\ + & A_s(1-B_d') + (1-A_s)B_d', \\ + & A_s+A_d-A_sA_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_RED_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) & = (R_s', G_d', B_d', A_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_GREEN_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) & = (R_d', G_s', B_d', A_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +| ename:VK_BLEND_OP_BLUE_EXT a| +[latexmath] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + \begin{aligned} + (R,G,B,A) & = (R_d', G_d', B_s', A_d) + \end{aligned} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +|==== diff --git a/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt b/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt index d31fa6aa..507921d9 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt @@ -20,7 +20,8 @@ the command buffer. The commands in this section allow application developers to associate user-defined information with Vulkan objects at will. -// refBegin vkDebugMarkerSetObjectNameEXT Give a user-friendly name to an object +[open,refpage='vkDebugMarkerSetObjectNameEXT',desc='Give a user-friendly name to an object',type='protos'] +-- An object can be given a user-friendly name by calling: @@ -38,8 +39,10 @@ include::../api/protos/vkDebugMarkerSetObjectNameEXT.txt[] **** include::../validity/protos/vkDebugMarkerSetObjectNameEXT.txt[] +-- -// refBegin VkDebugMarkerObjectNameInfoEXT Specify parameters of a name to give to an object +[open,refpage='VkDebugMarkerObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs'] +-- The sname:VkDebugMarkerObjectNameInfoEXT structure is defined as: @@ -59,8 +62,10 @@ To remove a previously set name, pname:pName should: be set to an empty string. include::../validity/structs/VkDebugMarkerObjectNameInfoEXT.txt[] +-- -// refBegin vkDebugMarkerSetObjectTagEXT Attach arbitrary data to an object +[open,refpage='vkDebugMarkerSetObjectTagEXT',desc='Attach arbitrary data to an object',type='protos'] +-- In addition to setting a name for an object, debugging and validation layers may have uses for additional binary data on a per-object basis that has no @@ -85,8 +90,10 @@ include::../api/protos/vkDebugMarkerSetObjectTagEXT.txt[] **** include::../validity/protos/vkDebugMarkerSetObjectTagEXT.txt[] +-- -// refBegin VkDebugMarkerObjectTagInfoEXT Specify parameters of a tag to attach to an object +[open,refpage='VkDebugMarkerObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs'] +-- The sname:VkDebugMarkerObjectTagInfoEXT structure is defined as: @@ -108,6 +115,7 @@ This can be used by debugging layers to easily filter for only data that can be used by that implementation. include::../validity/structs/VkDebugMarkerObjectTagInfoEXT.txt[] +-- [[debugging-command-buffer-markers]] === Command Buffer Markers @@ -124,7 +132,8 @@ grouped together, and they can be nested to create a hierarchy. The fname:vkCmdDebugMarkerInsertEXT command allows insertion of a single label within a command buffer. -// refBegin vkCmdDebugMarkerBeginEXT Open a command buffer marker region +[open,refpage='vkCmdDebugMarkerBeginEXT',desc='Open a command buffer marker region',type='protos'] +-- A marker region can be opened by calling: @@ -137,8 +146,10 @@ include::../api/protos/vkCmdDebugMarkerBeginEXT.txt[] the marker region to open. include::../validity/protos/vkCmdDebugMarkerBeginEXT.txt[] +-- -// refBegin VkDebugMarkerMarkerInfoEXT Specify parameters of a command buffer marker region +[open,refpage='VkDebugMarkerMarkerInfoEXT',desc='Specify parameters of a command buffer marker region',type='structs'] +-- The sname:VkDebugMarkerMarkerInfoEXT structure is defined as: @@ -155,8 +166,10 @@ include::../api/structs/VkDebugMarkerMarkerInfoEXT.txt[] If all elements in pname:color are set to 0.0 then it is ignored. include::../validity/structs/VkDebugMarkerMarkerInfoEXT.txt[] +-- -// refBegin vkCmdDebugMarkerEndEXT Close a command buffer marker region +[open,refpage='vkCmdDebugMarkerEndEXT',desc='Close a command buffer marker region',type='protos'] +-- A marker region can be closed by calling: @@ -186,8 +199,10 @@ must: be matched and balanced. **** include::../validity/protos/vkCmdDebugMarkerEndEXT.txt[] +-- -// refBegin vkCmdDebugMarkerInsertEXT Insert a marker label into a command buffer +[open,refpage='vkCmdDebugMarkerInsertEXT',desc='Insert a marker label into a command buffer',type='protos'] +-- A single marker label can be inserted into a command buffer by calling: @@ -200,3 +215,4 @@ include::../api/protos/vkCmdDebugMarkerInsertEXT.txt[] the marker to insert. include::../validity/protos/vkCmdDebugMarkerInsertEXT.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt b/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt index a9ebe12f..959121cc 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt @@ -3,16 +3,18 @@ [[debugging-debug-report-callbacks]] == Debug Report Callbacks -// refBegin VkDebugReportCallbackEXT Opaque handle to a debug report callback object +[open,refpage='VkDebugReportCallbackEXT',desc='Opaque handle to a debug report callback object',type='handles'] +-- Debug report callbacks are represented by sname:VkDebugReportCallbackEXT handles: include::../api/handles/VkDebugReportCallbackEXT.txt[] -// refEnd VkDebugReportCallbackEXT +-- -// refBegin vkCreateDebugReportCallbackEXT Create a debug report callback object +[open,refpage='vkCreateDebugReportCallbackEXT',desc='Create a debug report callback object',type='protos'] +-- Debug report callbacks give more detailed feedback on the application's use of Vulkan when events of interest occur. @@ -32,8 +34,10 @@ include::../api/protos/vkCreateDebugReportCallbackEXT.txt[] sname:VkDebugReportCallbackEXT object created. include::../validity/protos/vkCreateDebugReportCallbackEXT.txt[] +-- -// refBegin VkDebugReportCallbackCreateInfoEXT Structure specifying parameters of a newly created debug report callback +[open,refpage='VkDebugReportCallbackCreateInfoEXT',desc='Structure specifying parameters of a newly created debug report callback',type='structs'] +-- The definition of slink:VkDebugReportCallbackCreateInfoEXT is: @@ -72,8 +76,10 @@ application is making Vulkan calls from multiple threads). **** include::../validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[] +-- -// refBegin VkDebugReportFlagBitsEXT Bitmask specifying events which cause a debug report callback +[open,refpage='VkDebugReportFlagBitsEXT',desc='Bitmask specifying events which cause a debug report callback',type='enums'] +-- Bits which can: be set in slink:VkDebugReportCallbackCreateInfoEXT::pname:flags, specifying events @@ -102,9 +108,10 @@ include::../api/enums/VkDebugReportFlagBitsEXT.txt[] * ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies diagnostic information from the implementation and layers. -// refEnd VkDebugReportFlagBitsEXT +-- -// refBegin PFN_vkDebugReportCallbackEXT Application-defined debug report callback function +[open,refpage='PFN_vkDebugReportCallbackEXT',desc='Application-defined debug report callback function',type='funcpointers'] +-- The prototype for the slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback function @@ -148,9 +155,10 @@ If the application returns ename:VK_TRUE from its callback and the Vulkan call being aborted returns a elink:VkResult, the layer will return ename:VK_ERROR_VALIDATION_FAILED_EXT. -// refEnd PFN_vkDebugReportCallbackEXT +-- -// refBegin VkDebugReportObjectTypeEXT Specify the type of an object handle +[open,refpage='VkDebugReportObjectTypeEXT',desc='Specify the type of an object handle',type='enums'] +-- Possible values passed to the pname:objectType parameter of the callback function specified by @@ -233,9 +241,10 @@ It is not expected that an application would see this error code during normal use of the validation layers. ==== -// refEnd PFN_vkDebugReportCallbackEXT +-- -// refBegin vkDebugReportMessageEXT Inject a message into a debug stream +[open,refpage='vkDebugReportMessageEXT',desc='Inject a message into a debug stream',type='protos'] +-- To inject its own messages into the debug stream, call: @@ -270,8 +279,10 @@ registered. **** include::../validity/protos/vkDebugReportMessageEXT.txt[] +-- -// refBegin vkDestroyDebugReportCallbackEXT Destroy a debug report callback object +[open,refpage='vkDestroyDebugReportCallbackEXT',desc='Destroy a debug report callback object',type='protos'] +-- To destroy a sname:VkDebugReportCallbackEXT object, call: @@ -297,3 +308,4 @@ include::../api/protos/vkDestroyDebugReportCallbackEXT.txt[] **** include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_direct_mode_display/acquire_release_displays.txt b/doc/specs/vulkan/chapters/VK_EXT_direct_mode_display/acquire_release_displays.txt index 157fd732..ce2b6863 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_direct_mode_display/acquire_release_displays.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_direct_mode_display/acquire_release_displays.txt @@ -10,7 +10,8 @@ ifdef::VK_EXT_acquire_xlib_display[] include::../VK_EXT_acquire_xlib_display/acquire_xlib_display.txt[] endif::VK_EXT_acquire_xlib_display[] -// refBegin vkReleaseDisplayEXT Release access to an acquired VkDisplayKHR +[open,refpage='vkReleaseDisplayEXT',desc='Release access to an acquired VkDisplayKHR',type='protos'] +-- To release a previously acquired display, call: @@ -20,3 +21,4 @@ include::../../api/protos/vkReleaseDisplayEXT.txt[] * pname:display The display to release control of. include::../../validity/protos/vkReleaseDisplayEXT.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt b/doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt index 3a7ffc14..3dbd70ad 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt @@ -1,6 +1,7 @@ === Display Control -// refBegin vkDisplayPowerControlEXT Set the power state of a display +[open,refpage='vkDisplayPowerControlEXT',desc='Set the power state of a display',type='protos'] +-- To set the power state of a display, call: @@ -12,8 +13,10 @@ include::../../api/protos/vkDisplayPowerControlEXT.txt[] specifying the new power state of pname:display. include::../../validity/protos/vkDisplayPowerControlEXT.txt[] +-- -// refBegin VkDisplayPowerInfoEXT Describe the power state of a display +[open,refpage='VkDisplayPowerInfoEXT',desc='Describe the power state of a display',type='structs'] +-- The sname:VkDisplayPowerInfoEXT structure is defined as: @@ -25,8 +28,10 @@ include::../../api/structs/VkDisplayPowerInfoEXT.txt[] new power state of the display. include::../../validity/structs/VkDisplayPowerInfoEXT.txt[] +-- -// refBegin VkDisplayPowerStateEXT Possible power states for a display +[open,refpage='VkDisplayPowerStateEXT',desc='Possible power states for a display',type='enums'] +-- Possible values of slink:VkDisplayPowerInfoEXT::pname:powerState, specifying the new power state of a display, are: @@ -43,4 +48,4 @@ include::../../api/enums/VkDisplayPowerStateEXT.txt[] * ename:VK_DISPLAY_POWER_STATE_ON_EXT specifies that the display is powered on. -// refEnd VkDisplayPowerStateEXT +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt b/doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt index 58ceffc6..c400ba7a 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt @@ -4,7 +4,8 @@ Besides submitting a fence to a queue as part of a <> command, a fence may: also be signaled when a particular event occurs on a device or display. -// refBegin vkRegisterDeviceEventEXT Signal a fence when a device event occurs +[open,refpage='vkRegisterDeviceEventEXT',desc='Signal a fence when a device event occurs',type='protos'] +-- To create a fence that will be signaled when an event occurs on a device, call: @@ -21,8 +22,10 @@ include::../../api/protos/vkRegisterDeviceEventEXT.txt[] returned. include::../../validity/protos/vkRegisterDeviceEventEXT.txt[] +-- -// refBegin VkDeviceEventInfoEXT Describe a device event to create +[open,refpage='VkDeviceEventInfoEXT',desc='Describe a device event to create',type='structs'] +-- The sname:VkDeviceEventInfoEXT structure is defined as: @@ -34,8 +37,10 @@ include::../../api/structs/VkDeviceEventInfoEXT.txt[] fence will be signaled. include::../../validity/structs/VkDeviceEventInfoEXT.txt[] +-- -// refBegin VkDeviceEventTypeEXT Events that can occur on a device object +[open,refpage='VkDeviceEventTypeEXT',desc='Events that can occur on a device object',type='enums'] +-- Possible values of slink:VkDeviceEventInfoEXT::pname:device, specifying when a fence will be signaled, are: @@ -48,9 +53,10 @@ include::../../api/enums/VkDeviceEventTypeEXT.txt[] Applications can: use this notification to determine when they need to re-enumerate the available displays on a device. -// refEnd VkDeviceEventTypeEXT +-- -// refBegin vkRegisterDisplayEventEXT Signal a fence when a display event occurs +[open,refpage='vkRegisterDisplayEventEXT',desc='Signal a fence when a display event occurs',type='protos'] +-- To create a fence that will be signaled when an event occurs on a VkDisplayKHR object, call: @@ -68,8 +74,10 @@ include::../../api/protos/vkRegisterDisplayEventEXT.txt[] returned. include::../../validity/protos/vkRegisterDisplayEventEXT.txt[] +-- -// refBegin VkDisplayEventInfoEXT Describe a display event to create +[open,refpage='VkDisplayEventInfoEXT',desc='Describe a display event to create',type='structs'] +-- The sname:VkDisplayEventInfoEXT structure is defined as: @@ -81,8 +89,10 @@ include::../../api/structs/VkDisplayEventInfoEXT.txt[] fence will be signaled. include::../../validity/structs/VkDisplayEventInfoEXT.txt[] +-- -// refBegin VkDisplayEventTypeEXT Events that can occur on a display object +[open,refpage='VkDisplayEventTypeEXT',desc='Events that can occur on a display object',type='enums'] +-- Possible values of slink:VkDisplayEventInfoEXT::pname:displayEvent, specifying when a fence will be signaled, are: @@ -93,4 +103,4 @@ include::../../api/enums/VkDisplayEventTypeEXT.txt[] is signaled when the first pixel of the next display refresh cycle leaves the display engine for the display. -// refEnd VkDisplayEventTypeEXT +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_display_control/swapchain_counters.txt b/doc/specs/vulkan/chapters/VK_EXT_display_control/swapchain_counters.txt index 5c07dbc7..1d9608e8 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_display_control/swapchain_counters.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_display_control/swapchain_counters.txt @@ -1,4 +1,5 @@ -// refBegin VkSwapchainCounterCreateInfoEXT Specify the surface counters desired +[open,refpage='VkSwapchainCounterCreateInfoEXT',desc='Specify the surface counters desired',type='structs'] +-- To enable surface counters when creating a swapchain, add sname:VkSwapchainCounterCreateInfoEXT to the pname:pNext chain of @@ -21,8 +22,10 @@ include::../../api/structs/VkSwapchainCounterCreateInfoEXT.txt[] **** include::../../validity/structs/VkSwapchainCounterCreateInfoEXT.txt[] +-- -// refBegin vkGetSwapchainCounterEXT Query the current value of a surface counter +[open,refpage='vkGetSwapchainCounterEXT',desc='Query the current value of a surface counter',type='protos'] +-- The requested counters become active when the first presentation command for the associated swapchain is processed by the presentation engine. @@ -46,3 +49,4 @@ implementation may: return ename:VK_ERROR_OUT_OF_DATE_KHR. **** include::../../validity/protos/vkGetSwapchainCounterEXT.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt b/doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt index 5bcc09f3..2b60f8d7 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt @@ -1,4 +1,5 @@ -// refBegin vkGetPhysicalDeviceSurfaceCapabilities2EXT Query surface capabilities +[open,refpage='vkGetPhysicalDeviceSurfaceCapabilities2EXT',desc='Query surface capabilities',type='protos'] +-- To query the basic capabilities of a surface, needed in order to create a swapchain, call: @@ -19,8 +20,10 @@ extended information by adding extension structures to its pname:pNext chain. include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2EXT.txt[] +-- -// refBegin VkSurfaceCapabilities2EXT Structure describing capabilities of a surface +[open,refpage='VkSurfaceCapabilities2EXT',desc='Structure describing capabilities of a surface',type='structs'] +-- The sname:VkSurfaceCapabilities2EXT structure is defined as: @@ -45,8 +48,10 @@ The remaining members are: **** include::../../validity/structs/VkSurfaceCapabilities2EXT.txt[] +-- -// refBegin VkSurfaceCounterFlagBitsEXT Surface-relative counter types +[open,refpage='VkSurfaceCounterFlagBitsEXT',desc='Surface-relative counter types',type='enums'] +-- Bits which can: be set in slink:VkSurfaceCapabilities2EXT::pname:supportedSurfaceCounters, indicating @@ -58,4 +63,4 @@ include::../../api/enums/VkSurfaceCounterFlagBitsEXT.txt[] once every time a vertical blanking period occurs on the display associated with the surface. -// refEnd VkSurfaceCounterFlagBitsEXT +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_hdr_metadata.txt b/doc/specs/vulkan/chapters/VK_EXT_hdr_metadata.txt index 657454fc..1a38a5ff 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_hdr_metadata.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_hdr_metadata.txt @@ -17,7 +17,8 @@ The definitions below are from the associated SMPTE 2086, CTA 861.3 and CIE The definition of fname:vkSetHdrMetadataEXT is: -// refBegin vkSetHdrMetadataEXT function to set Hdr metadata +[open,refpage='vkSetHdrMetadataEXT',desc='function to set Hdr metadata',type='protos'] +-- include::../api/protos/vkSetHdrMetadataEXT.txt[] * pname:device is the logical device where the swapchain(s) were created. @@ -29,16 +30,19 @@ include::../api/protos/vkSetHdrMetadataEXT.txt[] sname:VkHdrMetadataEXT structures. include::../validity/protos/vkSetHdrMetadataEXT.txt[] +-- -// refBegin VkXYColorEXT structure to specify X,Y chromaticity coordinates +[open,refpage='VkXYColorEXT',desc='structure to specify X,Y chromaticity coordinates',type='structs'] +-- include::../api/structs/VkXYColorEXT.txt[] Chromaticity coordinates x and y are as specified in CIE 15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are limited to between 0 and 1 for real colors for the mastering display. -// refEnd VkXYColorEXT +-- -// refBegin VkHdrMetadataEXT structure to specify Hdr metadata +[open,refpage='VkHdrMetadataEXT',desc='structure to specify Hdr metadata',type='structs'] +-- include::../api/structs/VkHdrMetadataEXT.txt[] * pname:sType is the type of this structure. @@ -66,4 +70,4 @@ The validity and use of this data is outside the scope of Vulkan and thus no +Valid Usage+ is given. ==== -// refEnd VkHdrMetadataEXT +-- diff --git a/doc/specs/vulkan/chapters/VK_EXT_validation_flags.txt b/doc/specs/vulkan/chapters/VK_EXT_validation_flags.txt index ad957d18..cd6ad1e3 100644 --- a/doc/specs/vulkan/chapters/VK_EXT_validation_flags.txt +++ b/doc/specs/vulkan/chapters/VK_EXT_validation_flags.txt @@ -1,4 +1,5 @@ -// refBegin VkValidationFlagsEXT Specify validation checks to disable for a Vulkan instance +[open,refpage='VkValidationFlagsEXT',desc='Specify validation checks to disable for a Vulkan instance',type='structs'] +-- When creating a Vulkan instance for which you wish to disable validation checks, add a slink:VkValidationFlagsEXT structure to the pname:pNext chain @@ -15,8 +16,10 @@ include::../api/structs/VkValidationFlagsEXT.txt[] disabled. include::../validity/structs/VkValidationFlagsEXT.txt[] +-- -// refBegin VkValidationCheckEXT Specify validation checks to disable +[open,refpage='VkValidationCheckEXT',desc='Specify validation checks to disable',type='enums'] +-- Possible values of elements of the slink:VkValidationFlagsEXT::pname:pDisabledValidationChecks array, @@ -29,4 +32,4 @@ include::../api/enums/VkValidationCheckEXT.txt[] * ename:VK_VALIDATION_CHECK_SHADERS_EXT specifies that shader validation is disabled. -// refEnd VkValidationCheckEXT +-- diff --git a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt index 26dc7816..8af10139 100644 --- a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt +++ b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt @@ -1,5 +1,6 @@ -// refBegin VkPresentTimesInfoGOOGLE - The earliest time each image should be presented +[open,refpage='VkPresentTimesInfoGOOGLE',desc='The earliest time each image should be presented',type='structs'] +-- When the +VK_GOOGLE_display_timing+ extension is enabled, additional fields can: be specified that allow an application to specify the earliest time @@ -38,8 +39,10 @@ include::../../api/structs/VkPresentTimesInfoGOOGLE.txt[] **** include::../../validity/structs/VkPresentTimesInfoGOOGLE.txt[] +-- -// refBegin VkPresentTimeGOOGLE - The earliest time image should be presented +[open,refpage='VkPresentTimeGOOGLE',desc='The earliest time image should be presented',type='structs'] +-- The sname:VkPresentTimeGOOGLE structure is defined as: @@ -61,4 +64,4 @@ include::../../api/structs/VkPresentTimeGOOGLE.txt[] This is useful when the application desires to provide pname:presentID, but doesn't need a specific pname:desiredPresentTime. -// refEnd VkPresentTimeGOOGLE +-- diff --git a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt index d3080872..c921a4d8 100644 --- a/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt +++ b/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2016 Google Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2016-2017 Google Inc. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ == Display Timing Queries @@ -41,7 +42,8 @@ rate (VRR) display technology, where each refresh cycle (RC) can vary in length. This extension treats VRR displays as if they are FRR. -// refBegin vkGetRefreshCycleDurationGOOGLE - Obtain the RC duration of the PE's display +[open,refpage='vkGetRefreshCycleDurationGOOGLE',desc='Obtain the RC duration of the PE\'s display',type='protos'] +-- To query the duration of a refresh cycle (RC) for the presentation engine's display, call: @@ -54,8 +56,10 @@ include::../../api/protos/vkGetRefreshCycleDurationGOOGLE.txt[] sname:VkRefreshCycleDurationGOOGLE structure. include::../../validity/protos/vkGetRefreshCycleDurationGOOGLE.txt[] +-- -// refBegin VkRefreshCycleDurationGOOGLE - Structure containing the RC duration of a display +[open,refpage='VkRefreshCycleDurationGOOGLE',desc='Structure containing the RC duration of a display',type='structs'] +-- The sname:VkRefreshCycleDurationGOOGLE structure is defined as: @@ -66,7 +70,7 @@ include::../../api/structs/VkRefreshCycleDurationGOOGLE.txt[] include::../../validity/structs/VkRefreshCycleDurationGOOGLE.txt[] -// refEnd VkRefreshCycleDurationGOOGLE +-- The rate at which an application renders and presents new images is known as the image present rate (IPR, a.k.a. @@ -110,7 +114,8 @@ pname:actualPresentTime and pname:earliestPresentTime members of the slink:VkPastPresentationTimingGOOGLE structure are consistently different, and if pname:presentMargin is consistently large, over multiple images. -// refBegin vkGetPastPresentationTimingGOOGLE - Obtain timing of a previously-presented image +[open,refpage='vkGetPastPresentationTimingGOOGLE',desc='Obtain timing of a previously-presented image',type='protos'] +-- The implementation will maintain a limited amount of history of timing information about previous presents. @@ -152,8 +157,10 @@ ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetPastPresentationTimingGOOGLE.txt[] +-- -// refBegin VkPastPresentationTimingGOOGLE - Structure containing timing information about a previously-presented image +[open,refpage='VkPastPresentationTimingGOOGLE',desc='Structure containing timing information about a previously-presented image',type='structs'] +-- The sname:VkPastPresentationTimingGOOGLE structure is defined as: @@ -204,7 +211,7 @@ pname:refreshDuration, can also adjust features until pname:actualPresentTime is never late and pname:presentMargin is satisfactory. -// refEnd VkPastPresentationTimingGOOGLE +-- The full +VK_GOOGLE_display_timing+ extension semantics are described for swapchains created with ename:VK_PRESENT_MODE_FIFO_KHR. diff --git a/doc/specs/vulkan/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt b/doc/specs/vulkan/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt index 93d01bdc..1436c223 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_android_surface/platformCreateSurface_android.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_android,platformCreateSurface_android]] === Android Platform -// refBegin vkCreateAndroidSurfaceKHR - Create a slink:VkSurfaceKHR object for an Android native window +[open,refpage='vkCreateAndroidSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an Android native window',type='protos'] +-- To create a sname:VkSurfaceKHR object for an Android native window, call: @@ -48,8 +50,10 @@ For the system compositor, pname:currentExtent is the window size (i.e. the consumer's preferred size). include::../../validity/protos/vkCreateAndroidSurfaceKHR.txt[] +-- -// refBegin VkAndroidSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Android surface object +[open,refpage='VkAndroidSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Android surface object',type='structs'] +-- The sname:VkAndroidSurfaceCreateInfoKHR structure is defined as: @@ -68,4 +72,5 @@ include::../../api/structs/VkAndroidSurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkAndroidSurfaceCreateInfoKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_display/display.txt b/doc/specs/vulkan/chapters/VK_KHR_display/display.txt index c2b6f98b..bf6e1578 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_display/display.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_display/display.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[display,display]] @@ -16,15 +17,17 @@ displays. === Display Enumeration -// refBegin VkDisplayKHR - Opaque handle to a display object +[open,refpage='VkDisplayKHR',desc='Opaque handle to a display object',type='handles'] +-- Displays are represented by sname:VkDisplayKHR handles: include::../../api/handles/VkDisplayKHR.txt[] -// refEnd VkDisplayKHR +-- -// refBegin vkGetPhysicalDeviceDisplayPropertiesKHR - Query information about the available displays +[open,refpage='vkGetPhysicalDeviceDisplayPropertiesKHR',desc='Query information about the available displays',type='protos'] +-- Various functions are provided for enumerating the available display devices present on a Vulkan physical device. @@ -53,8 +56,10 @@ instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[] +-- -// refBegin VkDisplayPropertiesKHR - Structure describing an available display device +[open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs'] +-- The sname:VkDisplayPropertiesKHR structure is defined as: @@ -103,6 +108,7 @@ screen needs to be updated in most frames. ==== include::../../validity/structs/VkDisplayPropertiesKHR.txt[] +-- ifdef::VK_EXT_direct_mode_display[] include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[] @@ -110,7 +116,8 @@ endif::VK_EXT_direct_mode_display[] ==== Display Planes -// refBegin vkGetPhysicalDeviceDisplayPlanePropertiesKHR - Query the plane properties +[open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos'] +-- Images are presented to individual planes on a display. Devices must: support at least one plane on each display. @@ -140,8 +147,10 @@ planes for pname:physicalDevice, at most pname:pPropertyCount structures will be written. include::../../validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[] +-- -// refBegin VkDisplayPlanePropertiesKHR - Structure describing display plane properties +[open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs'] +-- The sname:VkDisplayPlanePropertiesKHR structure is defined as: @@ -157,8 +166,10 @@ include::../../api/structs/VkDisplayPlanePropertiesKHR.txt[] pname:pPropertyCount. include::../../validity/structs/VkDisplayPlanePropertiesKHR.txt[] +-- -// refBegin vkGetDisplayPlaneSupportedDisplaysKHR - Query the list of displays a plane supports +[open,refpage='vkGetDisplayPlaneSupportedDisplaysKHR',desc='Query the list of displays a plane supports',type='protos'] +-- To determine which displays a plane is usable with, call @@ -196,6 +207,7 @@ available values were returned. **** include::../../validity/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] +-- Additional properties of displays are queried using specialized query functions. @@ -203,15 +215,17 @@ functions. ==== Display Modes -// refBegin VkDisplayModeKHR - Opaque handle to a display mode object +[open,refpage='VkDisplayModeKHR',desc='Opaque handle to a display mode object',type='handles'] +-- Display modes are represented by sname:VkDisplayModeKHR handles: include::../../api/handles/VkDisplayModeKHR.txt[] -// refEnd VkDisplayModeKHR +-- -// refBegin vkGetDisplayModePropertiesKHR - Query the set of mode properties supported by the display +[open,refpage='vkGetDisplayModePropertiesKHR',desc='Query the set of mode properties supported by the display',type='protos'] +-- Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling: @@ -242,8 +256,10 @@ ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetDisplayModePropertiesKHR.txt[] +-- -// refBegin VkDisplayModePropertiesKHR - Structure describing display mode properties +[open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs'] +-- The sname:VkDisplayModePropertiesKHR structure is defined as: @@ -256,8 +272,10 @@ include::../../api/structs/VkDisplayModePropertiesKHR.txt[] describing the display parameters associated with pname:displayMode. include::../../validity/structs/VkDisplayModePropertiesKHR.txt[] +-- -// refBegin VkDisplayModeParametersKHR - Structure describing display parameters associated with a display mode +[open,refpage='VkDisplayModeParametersKHR',desc='Structure describing display parameters associated with a display mode',type='structs'] +-- The sname:VkDisplayModeParametersKHR structure is defined as: @@ -274,8 +292,10 @@ For example, a 60Hz display mode would report a pname:refreshRate of 60,000. ==== include::../../validity/structs/VkDisplayModeParametersKHR.txt[] +-- -// refBegin vkCreateDisplayModeKHR - Create a display mode +[open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos'] +-- Additional modes may: also be created by calling: @@ -292,8 +312,10 @@ include::../../api/protos/vkCreateDisplayModeKHR.txt[] * pname:pMode returns the handle of the mode created. include::../../validity/protos/vkCreateDisplayModeKHR.txt[] +-- -// refBegin VkDisplayModeCreateInfoKHR - Structure specifying parameters of a newly created display mode object +[open,refpage='VkDisplayModeCreateInfoKHR',desc='Structure specifying parameters of a newly created display mode object',type='structs'] +-- The sname:VkDisplayModeCreateInfoKHR structure is defined as: @@ -318,8 +340,10 @@ include::../../api/structs/VkDisplayModeCreateInfoKHR.txt[] **** include::../../validity/structs/VkDisplayModeCreateInfoKHR.txt[] +-- -// refBegin vkGetDisplayPlaneCapabilitiesKHR - Query capabilities of a mode and plane combination +[open,refpage='vkGetDisplayPlaneCapabilitiesKHR',desc='Query capabilities of a mode and plane combination',type='protos'] +-- Applications that wish to present directly to a display must: select which layer, or "plane" of the display they wish to target, and a mode to use with @@ -343,8 +367,10 @@ include::../../api/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] are returned. include::../../validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] +-- -// refBegin VkDisplayPlaneCapabilitiesKHR - Structure describing capabilities of a mode and plane combination +[open,refpage='VkDisplayPlaneCapabilitiesKHR',desc='Structure describing capabilities of a mode and plane combination',type='structs'] +-- The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as: @@ -402,6 +428,7 @@ Vendors may: still fail presentation requests that specify unsupported combinations. include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[] +-- ifdef::VK_EXT_display_control[] include::../VK_EXT_display_control/display_control.txt[] @@ -410,7 +437,8 @@ endif::VK_EXT_display_control[] [[wsi-display-surfaces]] === Display Surfaces -// refBegin vkCreateDisplayPlaneSurfaceKHR - Create a slink:VkSurfaceKHR structure representing a display plane and mode +[open,refpage='vkCreateDisplayPlaneSurfaceKHR',desc='Create a slink:VkSurfaceKHR structure representing a display plane and mode',type='protos'] +-- A complete display configuration includes a mode, one or more display planes and any parameters describing their behavior, and parameters describing some @@ -433,8 +461,10 @@ include::../../api/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] created surface is returned. include::../../validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] +-- -// refBegin VkDisplaySurfaceCreateInfoKHR - Structure specifying parameters of a newly created display plane surface object +[open,refpage='VkDisplaySurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created display plane surface object',type='structs'] +-- The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as: @@ -501,8 +531,10 @@ to a display surface. **** include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[] +-- -// refBegin VkDisplayPlaneAlphaFlagBitsKHR - Alpha blending type +[open,refpage='VkDisplayPlaneAlphaFlagBitsKHR',desc='Alpha blending type',type='enums'] +-- Possible values of slink:VkDisplaySurfaceCreateInfoKHR::pname:alphaMode, specifying the type of alpha blending to use on a display, are: @@ -526,4 +558,4 @@ include::../../api/enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[] source alpha values are assumed to be premultiplied into the source image's other color channels. -// refEnd VkDisplayPlaneAlphaFlagBitsKHR +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/create_shared_swapchains.txt b/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/create_shared_swapchains.txt index 310ea899..49ea748d 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/create_shared_swapchains.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/create_shared_swapchains.txt @@ -1,9 +1,11 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[create_shared_swapchains,create_shared_swapchains]] -// refBegin vkCreateSharedSwapchainsKHR - Create multiple swapchains that share presentable images +[open,refpage='vkCreateSharedSwapchainsKHR',desc='Create multiple swapchains that share presentable images',type='protos'] +-- When the +VK_KHR_display_swapchain+ extension is enabled, multiple swapchains that share presentable images are created by calling: @@ -38,3 +40,4 @@ After destroying one or more of the swapchains, the remaining swapchains and the presentable images can: continue to be used. include::../../validity/protos/vkCreateSharedSwapchainsKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/display_swapchain_present.txt b/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/display_swapchain_present.txt index 8e5258f2..3a2e6352 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/display_swapchain_present.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_display_swapchain/display_swapchain_present.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[display_swapchain_present,display_swapchain_present]] @@ -8,7 +9,8 @@ can: be specified when presenting an image to a swapchain by setting slink:VkPresentInfoKHR::pname:pNext to point to an instance of the slink:VkDisplayPresentInfoKHR structure. -// refBegin VkDisplayPresentInfoKHR - Structure describing parameters of a queue presentation to a swapchain +[open,refpage='VkDisplayPresentInfoKHR',desc='Structure describing parameters of a queue presentation to a swapchain',type='structs'] +-- The sname:VkDisplayPresentInfoKHR structure is defined as: @@ -63,3 +65,4 @@ presented pixels will be scaled accordingly. **** include::../../validity/structs/VkDisplayPresentInfoKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_incremental_present/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_incremental_present/wsi.txt index 401d5d7a..56987f5e 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_incremental_present/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_incremental_present/wsi.txt @@ -1,7 +1,9 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ -// refBegin VkPresentRegionsKHR - Structure hint of rectangular regions changed by vkQueuePresentKHR +[open,refpage='VkPresentRegionsKHR',desc='Structure hint of rectangular regions changed by vkQueuePresentKHR',type='structs'] +-- When the +VK_KHR_incremental_present+ extension is enabled, additional fields can: be specified that allow an application to specify that only @@ -40,8 +42,10 @@ include::../../api/structs/VkPresentRegionsKHR.txt[] **** include::../../validity/structs/VkPresentRegionsKHR.txt[] +-- -// refBegin VkPresentRegionKHR - Structure containing rectangular region changed by vkQueuePresentKHR for a given VkImage +[open,refpage='VkPresentRegionKHR',desc='Structure containing rectangular region changed by vkQueuePresentKHR for a given VkImage',type='structs'] +-- For a given image and swapchain, the region to present is specified by the sname:VkPresentRegionKHR structure, which is defined as: @@ -60,8 +64,10 @@ include::../../api/structs/VkPresentRegionKHR.txt[] given swapchain. include::../../validity/structs/VkPresentRegionKHR.txt[] +-- -// refBegin VkRectLayerKHR - Structure containing a rectangle, including layer, changed by vkQueuePresentKHR for a given VkImage +[open,refpage='VkRectLayerKHR',desc='Structure containing a rectangle, including layer, changed by vkQueuePresentKHR for a given VkImage',type='structs'] +-- The sname:VkRectLayerKHR structure is defined as: @@ -91,4 +97,4 @@ pixels of the image to fit the surface. VkRectLayerKHR specifies pixels of the swapchain's image(s), which will be constant for the life of the swapchain. -// refEnd VkRectLayerKHR +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformCreateSurface_mir.txt b/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformCreateSurface_mir.txt index aa898ebc..cc9a7aaa 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformCreateSurface_mir.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformCreateSurface_mir.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_mir,platformCreateSurface_mir]] === Mir Platform -// refBegin vkCreateMirSurfaceKHR - Create a slink:VkSurfaceKHR object for a Mir window +[open,refpage='vkCreateMirSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a Mir window',type='protos'] +-- To create a sname:VkSurfaceKHR object for a Mir window, call: @@ -22,8 +24,10 @@ include::../../api/protos/vkCreateMirSurfaceKHR.txt[] created surface object is returned. include::../../validity/protos/vkCreateMirSurfaceKHR.txt[] +-- -// refBegin VkMirSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Mir surface object +[open,refpage='VkMirSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Mir surface object',type='structs'] +-- The sname:VkMirSurfaceCreateInfoKHR structure is defined as: @@ -45,6 +49,7 @@ include::../../api/structs/VkMirSurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkMirSurfaceCreateInfoKHR.txt[] +-- On Mir, when a swapchain's pname:imageExtent does not match the surface's pname:currentExtent, the presentable images will be scaled to the surface's diff --git a/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformQuerySupport_mir.txt b/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformQuerySupport_mir.txt index 2fc8d3ab..bee53034 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformQuerySupport_mir.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_mir_surface/platformQuerySupport_mir.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformQuerySupport_mir,platformQuerySupport_mir]] === Mir Platform -// refBegin vkGetPhysicalDeviceMirPresentationSupportKHR - Query physical device for presentation to Mir +[open,refpage='vkGetPhysicalDeviceMirPresentationSupportKHR',desc='Query physical device for presentation to Mir',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to the Mir compositor, call: @@ -29,3 +31,4 @@ This platform-specific function can: be called prior to creating a surface. **** include::../../validity/protos/vkGetPhysicalDeviceMirPresentationSupportKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_shared_presentable_image/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_shared_presentable_image/wsi.txt index 100e9e5f..e28257ea 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_shared_presentable_image/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_shared_presentable_image/wsi.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ If a swapchain is created with pname:presentMode set to either ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or @@ -42,7 +43,8 @@ functionality for determining the timing of the presentation engine's refresh cycles. ==== -// refBegin vkGetSwapchainStatusKHR - Get a swapchain's status +[open,refpage='vkGetSwapchainStatusKHR',desc='Get a swapchain\'s status',type='protos'] +-- In order to query a swapchain's status when rendering to a shared presentable image, call: @@ -52,6 +54,7 @@ include::../../api/protos/vkGetSwapchainStatusKHR.txt[] * pname:swapchain is the swapchain to query. include::../../validity/protos/vkGetSwapchainStatusKHR.txt[] +-- The possible return values for fname:vkGetSwapchainStatusKHR() should: be interpreted as follows: diff --git a/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt index 42c96bf9..726bca2c 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[wsi]] = Window System Integration (WSI) @@ -37,7 +38,8 @@ before using them. == WSI Surface -// refBegin VkSurfaceKHR - Opaque handle to a surface object +[open,refpage='VkSurfaceKHR',desc='Opaque handle to a surface object',type='handles'] +-- Native platform surface or window objects are abstracted by surface objects, which are represented by sname:VkSurfaceKHR handles: @@ -65,7 +67,7 @@ This does not affect the loader-layer interface; layers may: wrap sname:VkSurfaceKHR objects. ==== -// refEnd VkSurfaceKHR +-- ifdef::editing-notes[] [NOTE] @@ -133,7 +135,8 @@ unavailable. A lost surface does not otherwise cause devices to be <>. -// refBegin vkDestroySurfaceKHR - Destroy a VkSurfaceKHR object +[open,refpage='vkDestroySurfaceKHR',desc='Destroy a VkSurfaceKHR object',type='protos'] +-- To destroy a sname:VkSurfaceKHR object, call: @@ -163,6 +166,7 @@ closing a window, or similar behavior. **** include::../../validity/protos/vkDestroySurfaceKHR.txt[] +-- ifdef::VK_KHR_display[] include::../VK_KHR_display/display.txt[] @@ -180,7 +184,8 @@ object) and additionally may: be determined in platform-specific manners but do not guarantee support for presentation to a particular surface object). -// refBegin vkGetPhysicalDeviceSurfaceSupportKHR - Query if presentation is supported +[open,refpage='vkGetPhysicalDeviceSurfaceSupportKHR',desc='Query if presentation is supported',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to a given surface, call: @@ -203,6 +208,7 @@ include::../../api/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[] **** include::../../validity/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[] +-- ifdef::VK_KHR_android_surface[] include::../VK_KHR_android_surface/platformQuerySupport_android.txt[] @@ -243,7 +249,8 @@ endif::VK_NN_vi_surface[] == Surface Queries -// refBegin vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities +[open,refpage='vkGetPhysicalDeviceSurfaceCapabilitiesKHR',desc='Query surface capabilities',type='protos'] +-- To query the basic capabilities of a surface, needed in order to create a swapchain, call: @@ -259,8 +266,10 @@ include::../../api/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[] returned. include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[] +-- -// refBegin VkSurfaceCapabilitiesKHR - Structure describing capabilities of a surface +[open,refpage='VkSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface',type='structs'] +-- The sname:VkSurfaceCapabilitiesKHR structure is defined as: @@ -343,10 +352,12 @@ pname:maxImageCount may: be zero. ==== include::../../validity/structs/VkSurfaceCapabilitiesKHR.txt[] +-- ifdef::VK_KHR_get_surface_capabilities2[] -// refBegin vkGetPhysicalDeviceSurfaceCapabilities2KHR Reports capabilities of a surface on a physical device +[open,refpage='vkGetPhysicalDeviceSurfaceCapabilities2KHR',desc='Reports capabilities of a surface on a physical device',type='protos'] +-- To query the basic capabilities of a surface defined by the core or extensions, call: @@ -370,8 +381,10 @@ extended inputs via chained input structures, and to return extended information via chained output structures. include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.txt[] +-- -// refBegin VkPhysicalDeviceSurfaceInfo2KHR Structure specifying a surface and related swapchain creation parameters +[open,refpage='VkPhysicalDeviceSurfaceInfo2KHR',desc='Structure specifying a surface and related swapchain creation parameters',type='structs'] +-- The sname:VkPhysicalDeviceSurfaceInfo2KHR structure is defined as: @@ -386,8 +399,10 @@ arguments to flink:vkGetPhysicalDeviceSurfaceCapabilities, with pname:sType and pname:pNext added for extensibility. include::../../validity/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[] +-- -// refBegin VkSurfaceCapabilities2KHR Structure describing capabilities of a surface +[open,refpage='VkSurfaceCapabilities2KHR',desc='Structure describing capabilities of a surface',type='structs'] +-- The sname:VkSurfaceCapabilities2KHR structure is defined as: @@ -400,9 +415,11 @@ include::../../api/structs/VkSurfaceCapabilities2KHR.txt[] specified surface. include::../../validity/structs/VkSurfaceCapabilities2KHR.txt[] +-- ifdef::VK_KHR_shared_presentable_image[] -// refBegin VkSharedPresentSurfaceCapabilitiesKHR - structure describing capabilities of a surface for shared presentation +[open,refpage='VkSharedPresentSurfaceCapabilitiesKHR',desc='structure describing capabilities of a surface for shared presentation',type='structs'] +-- The sname:VkSharedPresentSurfaceCapabilitiesKHR structure is defined as: @@ -422,7 +439,7 @@ include::../../api/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] include::../../validity/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] -// refEnd VkSharedPresentSurfaceCapabilitiesKHR +-- endif::VK_KHR_shared_presentable_image[] endif::VK_KHR_get_surface_capabilities2[] @@ -430,7 +447,8 @@ ifdef::VK_EXT_display_surface_counter[] include::../VK_EXT_display_surface_counter/surface_capabilities.txt[] endif::VK_EXT_display_surface_counter[] -// refBegin VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device +[open,refpage='VkSurfaceTransformFlagBitsKHR',desc='presentation transforms supported on a device',type='enums'] +-- Bits which may: be set in slink:VkSurfaceCapabilitiesKHR::pname:supportedTransforms indicating the @@ -465,9 +483,10 @@ include::../../api/enums/VkSurfaceTransformFlagBitsKHR.txt[] presentation transform is not specified, and is instead determined by platform-specific considerations and mechanisms outside Vulkan. -// refEnd VkSurfaceTransformFlagBitsKHR +-- -// refBegin VkCompositeAlphaFlagBitsKHR - alpha compositing modes supported on a device +[open,refpage='VkCompositeAlphaFlagBitsKHR',desc='alpha compositing modes supported on a device',type='enums'] +-- The pname:supportedCompositeAlpha member is of type elink:VkCompositeAlphaFlagBitsKHR, which contains the following values: @@ -497,9 +516,10 @@ These values are described as follows: If the application does not set the blending mode using native window system commands, then a platform-specific default will be used. -// refEnd VkCompositeAlphaFlagBitsKHR +-- -// refBegin vkGetPhysicalDeviceSurfaceFormatsKHR - Query color formats supported by surface +[open,refpage='vkGetPhysicalDeviceSurfaceFormatsKHR',desc='Query color formats supported by surface',type='protos'] +-- To query the supported swapchain format-color space pairs for a surface, call: @@ -532,8 +552,10 @@ instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[] +-- -// refBegin VkSurfaceFormatKHR - Structure describing a supported swapchain format-color space pair +[open,refpage='VkSurfaceFormatKHR',desc='Structure describing a supported swapchain format-color space pair',type='structs'] +-- The sname:VkSurfaceFormatKHR structure is defined as: @@ -545,10 +567,12 @@ include::../../api/structs/VkSurfaceFormatKHR.txt[] compatible with the surface. include::../../validity/structs/VkSurfaceFormatKHR.txt[] +-- ifdef::VK_KHR_get_surface_capabilities2[] -// refBegin vkGetPhysicalDeviceSurfaceFormats2KHR - Query color formats supported by surface +[open,refpage='vkGetPhysicalDeviceSurfaceFormats2KHR',desc='Query color formats supported by surface',type='protos'] +-- To query the supported swapchain format tuples for a surface, call: @@ -583,8 +607,10 @@ ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.txt[] +-- -// refBegin VkSurfaceFormat2KHR - Structure describing a supported swapchain format tuple +[open,refpage='VkSurfaceFormat2KHR',desc='Structure describing a supported swapchain format tuple',type='structs'] +-- The sname:VkSurfaceFormat2KHR structure is defined as: @@ -597,6 +623,7 @@ include::../../api/structs/VkSurfaceFormat2KHR.txt[] specified surface. include::../../validity/structs/VkSurfaceFormat2KHR.txt[] +-- endif::VK_KHR_get_surface_capabilities2[] @@ -608,7 +635,8 @@ the chromaticities of its primaries and a white point in CIE Lab), and a transfer function that is applied before storing or transmitting color data in the given color space. -// refBegin VkColorSpaceKHR - supported color space of the presentation engine +[open,refpage='VkColorSpaceKHR',desc='supported color space of the presentation engine',type='enums'] +-- Possible values of slink:VkSurfaceFormatKHR::pname:colorSpace, specifying supported color spaces of a presentation engine, are: @@ -683,6 +711,11 @@ conventional colorimetry [eq]#E# - corresponding electrical signal (value stored in memory) +// @@@ The ref page is ended earlier than in the original markup due to +// asciidoctor issues described in internal MR 2201. + +-- + === sRGB OETF @@ -869,9 +902,11 @@ Vulkan naming rules. The older enum is still available for backwards compatibility. ==== -// refEnd VkColorSpaceKHR +// @@@ originally, the VkColorSpaceKHR ref page ended here +// -- -// refBegin vkGetPhysicalDeviceSurfacePresentModesKHR - Query supported presentation modes +[open,refpage='vkGetPhysicalDeviceSurfacePresentModesKHR',desc='Query supported presentation modes',type='protos'] +-- To query the supported presentation modes for a surface, call: @@ -903,8 +938,10 @@ instead of ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[] +-- -// refBegin VkPresentModeKHR - presentation mode supported for a surface +[open,refpage='VkPresentModeKHR',desc='presentation mode supported for a surface',type='enums'] +-- Possible values of elements of the flink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes array, @@ -1002,7 +1039,7 @@ equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions). ==== -// refEnd VkPresentModeKHR +-- ifdef::VK_KHR_swapchain[] ifdef::VK_KHX_device_group[] @@ -1010,7 +1047,8 @@ ifdef::VK_KHX_device_group[] == Device Group Queries -// refBegin vkGetDeviceGroupPresentCapabilitiesKHX Query present capabilities from other physical devices +[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHX',desc='Query present capabilities from other physical devices',type='protos'] +-- A logical device that represents multiple physical devices may: support presenting from images on more than one physical device, or combining images @@ -1026,8 +1064,10 @@ include::../../api/protos/vkGetDeviceGroupPresentCapabilitiesKHX.txt[] logical device's capabilities. include::../../validity/protos/vkGetDeviceGroupPresentCapabilitiesKHX.txt[] +-- -// refBegin VkDeviceGroupPresentCapabilitiesKHX Present capabilities from other physical devices +[open,refpage='VkDeviceGroupPresentCapabilitiesKHX',desc='Present capabilities from other physical devices',type='structs'] +-- The sname:VkDeviceGroupPresentCapabilitiesKHX structure is defined as: @@ -1053,9 +1093,11 @@ If a device group only includes a single physical device, then pname:modes must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX. include::../../validity/structs/VkDeviceGroupPresentCapabilitiesKHX.txt[] +-- -// refBegin VkDeviceGroupPresentModeFlagBitsKHX Bitmask specifying supported device group present modes +[open,refpage='VkDeviceGroupPresentModeFlagBitsKHX',desc='Bitmask specifying supported device group present modes',type='enums'] +-- Bits which may: be set in slink:VkDeviceGroupPresentCapabilitiesKHX::pname:modes to indicate which @@ -1076,9 +1118,10 @@ include::../../api/enums/VkDeviceGroupPresentModeFlagBitsKHX.txt[] that multiple physical devices with a presentation engine can: each present their own swapchain images. -// refEnd VkDeviceGroupPresentModeFlagBitsKHX +-- -// refBegin vkGetDeviceGroupSurfacePresentModesKHX Query present capabilities for a surface +[open,refpage='vkGetDeviceGroupSurfacePresentModesKHX',desc='Query present capabilities for a surface',type='protos'] +-- Some surfaces may: not be capable of using all the device group present modes. @@ -1101,9 +1144,10 @@ flink:vkGetDeviceGroupPresentCapabilitiesKHX. include::../../validity/protos/vkGetDeviceGroupSurfacePresentModesKHX.txt[] -// refEnd vkGetDeviceGroupSurfacePresentModesKHX +-- -// refBegin vkGetPhysicalDevicePresentRectanglesKHX Query present rectangles for a surface on a physical device +[open,refpage='vkGetPhysicalDevicePresentRectanglesKHX',desc='Query present rectangles for a surface on a physical device',type='protos'] +-- When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX, the application may: need to know which regions of the surface are used when @@ -1142,7 +1186,7 @@ The rectangles returned by this command must: not overlap. include::../../validity/protos/vkGetPhysicalDevicePresentRectanglesKHX.txt[] -// refEnd vkGetPhysicalDevicePresentRectanglesKHX +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index 05905e6c..51433851 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt @@ -1,9 +1,11 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ == WSI Swapchain -// refBegin VkSwapchainKHR - Opaque handle to a swapchain object +[open,refpage='VkSwapchainKHR',desc='Opaque handle to a swapchain object',type='handles'] +-- A swapchain object (a.k.a. swapchain) provides the ability to present rendering results to a surface. @@ -70,7 +72,7 @@ referencing all of the images in the swapchain at initialization time, rather than in its main loop. ==== -// refEnd VkSwapchainKHR +-- How this all works is described below. @@ -78,7 +80,8 @@ ifdef::VK_KHR_shared_presentable_image[] include::../VK_KHR_shared_presentable_image/wsi.txt[] endif::VK_KHR_shared_presentable_image[] -// refBegin vkCreateSwapchainKHR - Create a swapchain +[open,refpage='vkCreateSwapchainKHR',desc='Create a swapchain',type='protos'] +-- To create a swapchain, call: @@ -95,8 +98,10 @@ include::../../api/protos/vkCreateSwapchainKHR.txt[] the created swapchain object will be returned. include::../../validity/protos/vkCreateSwapchainKHR.txt[] +-- -// refBegin VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object +[open,refpage='VkSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs'] +-- The sname:VkSwapchainCreateInfoKHR structure is defined as: @@ -234,23 +239,29 @@ endif::VK_KHR_shared_presentable_image[] to the pname:maxImageArrayLayers member of the sname:VkSurfaceCapabilitiesKHR structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01276]] pname:imageUsage must: be a subset of the supported usage flags present in the pname:supportedUsageFlags member of the sname:VkSurfaceCapabilitiesKHR structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface +endif::VK_KHR_shared_presentable_image[] ifdef::VK_KHR_shared_presentable_image[] - if pname:presentMode is set to ename:VK_PRESENT_MODE_IMMEDIATE_KHR, + * [[VUID-VkSwapchainCreateInfoKHR-presentMode-01427]] + If pname:presentMode is ename:VK_PRESENT_MODE_IMMEDIATE_KHR, ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or - ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR + ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR, pname:imageUsage must: be a + subset of the supported usage flags present in the + pname:supportedUsageFlags member of the slink:VkSurfaceCapabilitiesKHR + structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR + for pname:surface * [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01384]] - pname:imageUsage must: be a subset of the supported usage flags present - in the pname:sharedPresentSupportedUsageFlags member of the - sname:VkSharedPresentSurfaceCapabilitiesKHR structure returned by - fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR for the surface if - pname:presentMode is set to either - ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or - ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR + If pname:presentMode is ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR + or ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, pname:imageUsage + must: be a subset of the supported usage flags present in the + pname:sharedPresentSupportedUsageFlags member of the + slink:VkSharedPresentSurfaceCapabilitiesKHR structure returned by + flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR for pname:surface endif::VK_KHR_shared_presentable_image[] * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01277]] If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, @@ -259,18 +270,23 @@ endif::VK_KHR_shared_presentable_image[] * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]] If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, pname:queueFamilyIndexCount must: be greater than `1` - * [[VUID-VkSwapchainCreateInfoKHR-sharingMode-01393]] - If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element - of pname:pQueueFamilyIndices must: be unique and must: be less than - pname:pQueueFamilyPropertyCount returned by ifndef::VK_KHR_get_physical_device_properties2[] - flink:vkGetPhysicalDeviceQueueFamilyProperties + * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01393]] + If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each + element of pname:pQueueFamilyIndices must: be unique and must: be less + than pname:pQueueFamilyPropertyCount returned by + flink:vkGetPhysicalDeviceQueueFamilyProperties for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] ifdef::VK_KHR_get_physical_device_properties2[] - either flink:vkGetPhysicalDeviceQueueFamilyProperties or - flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR + * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01428]] + If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each + element of pname:pQueueFamilyIndices must: be unique and must: be less + than pname:pQueueFamilyPropertyCount returned by either + flink:vkGetPhysicalDeviceQueueFamilyProperties or + flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] - for the pname:physicalDevice that was used to create pname:device * [[VUID-VkSwapchainCreateInfoKHR-preTransform-01279]] pname:preTransform must: be one of the bits present in the pname:supportedTransforms member of the sname:VkSurfaceCapabilitiesKHR @@ -285,11 +301,20 @@ endif::VK_KHR_get_physical_device_properties2[] pname:presentMode must: be one of the elink:VkPresentModeKHR values returned by fname:vkGetPhysicalDeviceSurfacePresentModesKHR for the surface +ifdef::VK_KHX_device_group[] + * [[VUID-VkSwapchainCreateInfoKHR-physicalDeviceCount-01429]] + If the logical device was created with + slink:VkDeviceGroupDeviceCreateInfoKHX::pname:physicalDeviceCount equal + to 1, pname:flags must: not contain + ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX +endif::VK_KHX_device_group[] **** include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[] +-- -// refBegin VkSwapchainCreateFlagBitsKHR Bitmask controlling swapchain creation +[open,refpage='VkSwapchainCreateFlagBitsKHR',desc='Bitmask controlling swapchain creation',type='enums'] +-- Bits which can: be set in slink:VkSwapchainCreateInfoKHR::pname:flags, specifying parameters of swapchain creation, are: @@ -303,11 +328,12 @@ ifdef::VK_KHX_device_group[] must: use ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX. endif::VK_KHX_device_group[] -// refEnd VkSwapchainCreateFlagBitsKHR +-- ifdef::VK_KHX_device_group[] -// refBegin VkDeviceGroupSwapchainCreateInfoKHX Structure specifying parameters of a newly created swapchain object +[open,refpage='VkDeviceGroupSwapchainCreateInfoKHX',desc='Structure specifying parameters of a newly created swapchain object',type='structs'] +-- If the pname:pNext list of slink:VkSwapchainCreateInfoKHR includes a sname:VkDeviceGroupSwapchainCreateInfoKHX structure, then that structure @@ -326,6 +352,7 @@ If this structure is not present, pname:modes is considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX. include::../../validity/structs/VkDeviceGroupSwapchainCreateInfoKHX.txt[] +-- endif::VK_KHX_device_group[] @@ -397,7 +424,8 @@ however the application must: query the surface capabilities again, because they may: differ on a per-physical device basis. ==== -// refBegin vkDestroySwapchainKHR - Destroy a swapchain object +[open,refpage='vkDestroySwapchainKHR',desc='Destroy a swapchain object',type='protos'] +-- To destroy a swapchain object call: @@ -437,12 +465,14 @@ endif::VK_KHR_display_swapchain[] **** include::../../validity/protos/vkDestroySwapchainKHR.txt[] +-- ifdef::VK_KHR_display_swapchain[] include::../VK_KHR_display_swapchain/create_shared_swapchains.txt[] endif::VK_KHR_display_swapchain[] -// refBegin vkGetSwapchainImagesKHR - Obtain the array of presentable images associated with a swapchain +[open,refpage='vkGetSwapchainImagesKHR',desc='Obtain the array of presentable images associated with a swapchain',type='protos'] +-- To obtain the array of presentable images associated with a swapchain, call: @@ -470,6 +500,7 @@ ename:VK_SUCCESS to indicate that not all the available values were returned. include::../../validity/protos/vkGetSwapchainImagesKHR.txt[] +-- [NOTE] .Note @@ -509,7 +540,8 @@ must: be destroyed with flink:vkDestroyImage. endif::VK_KHX_device_group[] -// refBegin vkAcquireNextImageKHR - Retrieve the index of the next available presentable image +[open,refpage='vkAcquireNextImageKHR',desc='Retrieve the index of the next available presentable image',type='protos'] +-- To acquire an available presentable image to use, and retrieve the index of that image, call: @@ -541,6 +573,7 @@ include::../../api/protos/vkAcquireNextImageKHR.txt[] **** include::../../validity/protos/vkAcquireNextImageKHR.txt[] +-- When successful, fname:vkAcquireNextImageKHR acquires a presentable image that the application can: use, and sets pname:pImageIndex to the index of @@ -777,7 +810,8 @@ parameter should: be set to ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT. ifdef::VK_KHX_device_group[] -// refBegin vkAcquireNextImage2KHX Retrieve the index of the next available presentable image +[open,refpage='vkAcquireNextImage2KHX',desc='Retrieve the index of the next available presentable image',type='protos'] +-- To acquire an available presentable image to use, and retrieve the index of that image, call: @@ -791,8 +825,10 @@ include::../../api/protos/vkAcquireNextImage2KHX.txt[] index of the next image to use. include::../../validity/protos/vkAcquireNextImage2KHX.txt[] +-- -// refBegin VkAcquireNextImageInfoKHX Structure specifying parameters of the acquire +[open,refpage='VkAcquireNextImageInfoKHX',desc='Structure specifying parameters of the acquire',type='structs'] +-- The sname:VkAcquireNextImageInfoKHX structure is defined as: @@ -840,10 +876,12 @@ succeeds, which the other physical device(s) can: wait upon. **** include::../../validity/structs/VkAcquireNextImageInfoKHX.txt[] +-- endif::VK_KHX_device_group[] -// refBegin vkQueuePresentKHR - Queue an image for presentation +[open,refpage='vkQueuePresentKHR',desc='Queue an image for presentation',type='protos'] +-- After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call: @@ -890,8 +928,10 @@ signal operation, and happens-before the presentation engine accesses the image. include::../../validity/protos/vkQueuePresentKHR.txt[] +-- -// refBegin VkPresentInfoKHR - Structure describing parameters of a queue presentation +[open,refpage='VkPresentInfoKHR',desc='Structure describing parameters of a queue presentation',type='structs'] +-- The sname:VkPresentInfoKHR structure is defined as: @@ -924,18 +964,27 @@ include::../../api/structs/VkPresentInfoKHR.txt[] .Valid Usage **** +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-VkPresentInfoKHR-pImageIndices-01296]] Any given element of pname:pImageIndices must: be the index of a presentable image acquired from the swapchain specified by the corresponding element of the pname:pSwapchains array, and the presented image subresource must: be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR -ifdef::VK_KHR_shared_presentable_image[] - or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR -endif::VK_KHR_shared_presentable_image[] layout at the time the operation is executed on a sname:VkDevice +endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-VkPresentInfoKHR-pImageIndices-01430]] + Any given element of pname:pImageIndices must: be the index of a + presentable image acquired from the swapchain specified by the + corresponding element of the pname:pSwapchains array, and the presented + image subresource must: be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR + or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout at the time the + operation is executed on a sname:VkDevice +endif::VK_KHR_shared_presentable_image[] **** include::../../validity/structs/VkPresentInfoKHR.txt[] +-- ifdef::VK_KHR_incremental_present[] include::../VK_KHR_incremental_present/wsi.txt[] @@ -947,7 +996,8 @@ endif::VK_KHR_display_swapchain[] ifdef::VK_KHX_device_group[] -// refBegin VkDeviceGroupPresentInfoKHX Mode and mask controlling which physical devices' images are presented +[open,refpage='VkDeviceGroupPresentInfoKHX',desc='Mode and mask controlling which physical devices\' images are presented',type='structs'] +-- If the pname:pNext list of slink:VkPresentInfoKHR includes a sname:VkDeviceGroupPresentInfoKHX structure, then that structure includes an @@ -1039,6 +1089,7 @@ considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX. **** include::../../validity/structs/VkDeviceGroupPresentInfoKHX.txt[] +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt index ea2374f8..33e1138f 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_wayland,platformCreateSurface_wayland]] === Wayland Platform -// refBegin vkCreateWaylandSurfaceKHR - Create a slink:VkSurfaceKHR object for a Wayland window +[open,refpage='vkCreateWaylandSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a Wayland window',type='protos'] +-- To create a sname:VkSurfaceKHR object for a Wayland surface, call: @@ -22,8 +24,10 @@ include::../../api/protos/vkCreateWaylandSurfaceKHR.txt[] created surface object is returned. include::../../validity/protos/vkCreateWaylandSurfaceKHR.txt[] +-- -// refBegin VkWaylandSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Wayland surface object +[open,refpage='VkWaylandSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Wayland surface object',type='structs'] +-- The sname:VkWaylandSurfaceCreateInfoKHR structure is defined as: @@ -44,6 +48,7 @@ include::../../api/structs/VkWaylandSurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkWaylandSurfaceCreateInfoKHR.txt[] +-- On Wayland, pname:currentExtent is undefined [eq]#(0xFFFFFFFF, 0xFFFFFFFF)#. Whatever the application sets a swapchain's pname:imageExtent to will be the diff --git a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt index 98995eac..e6df0f3d 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformQuerySupport_walyand,platformQuerySupport_walyand]] === Wayland Platform -// refBegin vkGetPhysicalDeviceWaylandPresentationSupportKHR - Query physical device for presentation to Wayland +[open,refpage='vkGetPhysicalDeviceWaylandPresentationSupportKHR',desc='Query physical device for presentation to Wayland',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to a Wayland compositor, call: @@ -29,3 +31,4 @@ This platform-specific function can: be called prior to creating a surface. **** include::../../validity/protos/vkGetPhysicalDeviceWaylandPresentationSupportKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt b/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt index 61150c35..8083cf93 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformCreateSurface_win32.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_win32,platformCreateSurface_win32]] === Win32 Platform -// refBegin vkCreateWin32SurfaceKHR - Create a slink:VkSurfaceKHR object for an Win32 native window +[open,refpage='vkCreateWin32SurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an Win32 native window',type='protos'] +-- To create a sname:VkSurfaceKHR object for a Win32 window, call: @@ -22,8 +24,10 @@ include::../../api/protos/vkCreateWin32SurfaceKHR.txt[] created surface object is returned. include::../../validity/protos/vkCreateWin32SurfaceKHR.txt[] +-- -// refBegin VkWin32SurfaceCreateInfoKHR - Structure specifying parameters of a newly created Win32 surface object +[open,refpage='VkWin32SurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Win32 surface object',type='structs'] +-- The sname:VkWin32SurfaceCreateInfoKHR structure is defined as: @@ -44,6 +48,7 @@ include::../../api/structs/VkWin32SurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkWin32SurfaceCreateInfoKHR.txt[] +-- With Win32, pname:minImageExtent, pname:maxImageExtent, and pname:currentExtent are the window size. diff --git a/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformQuerySupport_win32.txt b/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformQuerySupport_win32.txt index 3da8c62e..bf9ba8cd 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformQuerySupport_win32.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_win32_surface/platformQuerySupport_win32.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformQuerySupport_win32,platformQuerySupport_win32]] === Win32 Platform -// refBegin vkGetPhysicalDeviceWin32PresentationSupportKHR - query queue family support for presentation on a Win32 display +[open,refpage='vkGetPhysicalDeviceWin32PresentationSupportKHR',desc='query queue family support for presentation on a Win32 display',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to the Microsoft Windows desktop, call: @@ -27,3 +29,4 @@ This platform-specific function can: be called prior to creating a surface. **** include::../../validity/protos/vkGetPhysicalDeviceWin32PresentationSupportKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt b/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt index 4f92c49b..65ae2fbc 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_xcb,platformCreateSurface_xcb]] === XCB Platform -// refBegin vkCreateXcbSurfaceKHR - Create a slink:VkSurfaceKHR object for a X11 window, using the XCB client-side library +[open,refpage='vkCreateXcbSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a X11 window, using the XCB client-side library',type='protos'] +-- To create a sname:VkSurfaceKHR object for an X11 window, using the XCB client-side library, call: @@ -23,8 +25,10 @@ include::../../api/protos/vkCreateXcbSurfaceKHR.txt[] created surface object is returned. include::../../validity/protos/vkCreateXcbSurfaceKHR.txt[] +-- -// refBegin VkXcbSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Xcb surface object +[open,refpage='VkXcbSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Xcb surface object',type='structs'] +-- The sname:VkXcbSurfaceCreateInfoKHR structure is defined as: @@ -47,6 +51,7 @@ include::../../api/structs/VkXcbSurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkXcbSurfaceCreateInfoKHR.txt[] +-- With Xcb, pname:minImageExtent, pname:maxImageExtent, and pname:currentExtent are the window size. diff --git a/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt b/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt index cb6fbd5b..e542734e 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformQuerySupport_xcb,platformQuerySupport_xcb]] === XCB Platform -// refBegin vkGetPhysicalDeviceXcbPresentationSupportKHR - Query physical device for presentation to X11 server using XCB +[open,refpage='vkGetPhysicalDeviceXcbPresentationSupportKHR',desc='Query physical device for presentation to X11 server using XCB',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to an X11 server, using the XCB client-side library, call: @@ -30,3 +32,4 @@ This platform-specific function can: be called prior to creating a surface. **** include::../../validity/protos/vkGetPhysicalDeviceXcbPresentationSupportKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt index 728d082f..ad17e332 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformCreateSurface_xlib,platformCreateSurface_xlib]] === Xlib Platform -// refBegin vkCreateXlibSurfaceKHR - Create a slink:VkSurfaceKHR object for an X11 window, using the Xlib client-side library +[open,refpage='vkCreateXlibSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an X11 window, using the Xlib client-side library',type='protos'] +-- To create a sname:VkSurfaceKHR object for an X11 window, using the Xlib client-side library, call: @@ -23,8 +25,10 @@ include::../../api/protos/vkCreateXlibSurfaceKHR.txt[] created surface object is returned. include::../../validity/protos/vkCreateXlibSurfaceKHR.txt[] +-- -// refBegin VkXlibSurfaceCreateInfoKHR - Structure specifying parameters of a newly created Xlib surface object +[open,refpage='VkXlibSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Xlib surface object',type='structs'] +-- The sname:VkXlibSurfaceCreateInfoKHR structure is defined as: @@ -46,6 +50,7 @@ include::../../api/structs/VkXlibSurfaceCreateInfoKHR.txt[] **** include::../../validity/structs/VkXlibSurfaceCreateInfoKHR.txt[] +-- With Xlib, pname:minImageExtent, pname:maxImageExtent, and pname:currentExtent are the window size. diff --git a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt index 9efd1db9..c9324f90 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt @@ -1,11 +1,13 @@ -// Copyright (c) 2014-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[platformQuerySupport_xlib,platformQuerySupport_xlib]] === Xlib Platform -// refBegin vkGetPhysicalDeviceXlibPresentationSupportKHR - Query physical device for presentation to X11 server using Xlib +[open,refpage='vkGetPhysicalDeviceXlibPresentationSupportKHR',desc='Query physical device for presentation to X11 server using Xlib',type='protos'] +-- To determine whether a queue family of a physical device supports presentation to an X11 server, using the Xlib client-side library, call: @@ -29,3 +31,4 @@ This platform-specific function can: be called prior to creating a surface. **** include::../../validity/protos/vkGetPhysicalDeviceXlibPresentationSupportKHR.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_MVK_ios_surface/platformCreateSurface_ios.txt b/doc/specs/vulkan/chapters/VK_MVK_ios_surface/platformCreateSurface_ios.txt index 3e71033a..50c333b9 100644 --- a/doc/specs/vulkan/chapters/VK_MVK_ios_surface/platformCreateSurface_ios.txt +++ b/doc/specs/vulkan/chapters/VK_MVK_ios_surface/platformCreateSurface_ios.txt @@ -2,7 +2,8 @@ === iOS Platform -// refBegin vkCreateIOSSurfaceMVK - Create a VkSurfaceKHR object for an iOS UIView +[open,refpage='vkCreateIOSSurfaceMVK',desc='Create a VkSurfaceKHR object for an iOS UIView',type='protos'] +-- To create a sname:VkSurfaceKHR object for an iOS code:UIView, call: @@ -19,8 +20,10 @@ include::../../api/protos/vkCreateIOSSurfaceMVK.txt[] created surface object is returned. include::../../validity/protos/vkCreateIOSSurfaceMVK.txt[] +-- -// refBegin VkIOSSurfaceCreateInfoMVK - Structure specifying parameters of a newly created iOS surface object +[open,refpage='VkIOSSurfaceCreateInfoMVK',desc='Structure specifying parameters of a newly created iOS surface object',type='structs'] +-- The slink:VkIOSSurfaceCreateInfoMVK structure is defined as: @@ -42,4 +45,5 @@ include::../../api/structs/VkIOSSurfaceCreateInfoMVK.txt[] **** include::../../validity/structs/VkIOSSurfaceCreateInfoMVK.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_MVK_macos_surface/platformCreateSurface_macos.txt b/doc/specs/vulkan/chapters/VK_MVK_macos_surface/platformCreateSurface_macos.txt index b2e05762..2325249e 100644 --- a/doc/specs/vulkan/chapters/VK_MVK_macos_surface/platformCreateSurface_macos.txt +++ b/doc/specs/vulkan/chapters/VK_MVK_macos_surface/platformCreateSurface_macos.txt @@ -2,7 +2,8 @@ === macOS Platform -// refBegin vkCreateMacOSSurfaceMVK - Create a VkSurfaceKHR object for a macOS NSView +[open,refpage='vkCreateMacOSSurfaceMVK',desc='Create a VkSurfaceKHR object for a macOS NSView',type='protos'] +-- To create a sname:VkSurfaceKHR object for a macOS code:NSView, call: @@ -19,8 +20,10 @@ include::../../api/protos/vkCreateMacOSSurfaceMVK.txt[] created surface object is returned. include::../../validity/protos/vkCreateMacOSSurfaceMVK.txt[] +-- -// refBegin VkMacOSSurfaceCreateInfoMVK - Structure specifying parameters of a newly created macOS surface object +[open,refpage='VkMacOSSurfaceCreateInfoMVK',desc='Structure specifying parameters of a newly created macOS surface object',type='structs'] +-- The slink:VkMacOSSurfaceCreateInfoMVK structure is defined as: @@ -42,4 +45,5 @@ include::../../api/structs/VkMacOSSurfaceCreateInfoMVK.txt[] **** include::../../validity/structs/VkMacOSSurfaceCreateInfoMVK.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt b/doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt index adb33c1a..dcdf801b 100644 --- a/doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt +++ b/doc/specs/vulkan/chapters/VK_NN_vi_surface/platformCreateSurface_vi.txt @@ -2,7 +2,8 @@ === VI Platform -// refBegin vkCreateViSurfaceNN - Create a slink:VkSurfaceKHR object for a VI layer +[open,refpage='vkCreateViSurfaceNN',desc='Create a slink:VkSurfaceKHR object for a VI layer',type='protos'] +-- To create a sname:VkSurfaceKHR object for an code:nn::code:vi::code:Layer, query the layer's native handle using @@ -32,8 +33,10 @@ pname:imageExtent (e.g., by matching the the result of a call to code:nn::code:vi::code:GetDisplayResolution). include::../../validity/protos/vkCreateViSurfaceNN.txt[] +-- -// refBegin VkViSurfaceCreateInfoNN - Structure specifying parameters of a newly created VI surface object +[open,refpage='VkViSurfaceCreateInfoNN',desc='Structure specifying parameters of a newly created VI surface object',type='structs'] +-- The sname:VkViSurfaceCreateInfoNN structure is defined as: @@ -52,4 +55,5 @@ include::../../api/structs/VkViSurfaceCreateInfoNN.txt[] **** include::../../validity/structs/VkViSurfaceCreateInfoNN.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt index fc44bbbd..5f3d0c6a 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt @@ -35,7 +35,8 @@ automatically synchronized against the command execution. == Features and Limitations -// refBegin vkGetPhysicalDeviceGeneratedCommandsPropertiesNVX Returns device-generated commands related properties of a physical device +[open,refpage='vkGetPhysicalDeviceGeneratedCommandsPropertiesNVX',desc='Returns device-generated commands related properties of a physical device',type='protos'] +-- To query the support of related features and limitations, call: @@ -51,8 +52,10 @@ include::../../api/protos/vkGetPhysicalDeviceGeneratedCommandsPropertiesNVX.txt[ with returned information. include::../../validity/protos/vkGetPhysicalDeviceGeneratedCommandsPropertiesNVX.txt[] +-- -// refBegin VkDeviceGeneratedCommandsFeaturesNVX Structure specifying physical device support +[open,refpage='VkDeviceGeneratedCommandsFeaturesNVX',desc='Structure specifying physical device support',type='structs'] +-- The sname:VkDeviceGeneratedCommandsFeaturesNVX structure is defined as: @@ -67,8 +70,10 @@ include::../../api/structs/VkDeviceGeneratedCommandsFeaturesNVX.txt[] ename:VK_PIPELINE_BIND_POINT_COMPUTE. include::../../validity/structs/VkDeviceGeneratedCommandsFeaturesNVX.txt[] +-- -// refBegin VkDeviceGeneratedCommandsLimitsNVX Structure specifying physical device limits +[open,refpage='VkDeviceGeneratedCommandsLimitsNVX',desc='Structure specifying physical device limits',type='structs'] +-- The sname:VkDeviceGeneratedCommandsLimitsNVX structure is defined as: @@ -88,6 +93,7 @@ include::../../api/structs/VkDeviceGeneratedCommandsLimitsNVX.txt[] memory addresses optionally used in fname:vkCmdProcessCommandsNVX. include::../../validity/structs/VkDeviceGeneratedCommandsLimitsNVX.txt[] +-- include::objecttable.txt[] diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt index bea7daca..3b31259d 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt @@ -1,6 +1,7 @@ == Indirect Commands Generation -// refBegin vkCmdReserveSpaceForCommandsNVX Perform a reservation of command buffer space +[open,refpage='vkCmdReserveSpaceForCommandsNVX',desc='Perform a reservation of command buffer space',type='protos'] +-- Command space for generated commands recorded into a secondary command buffer must: be reserved by calling: @@ -25,8 +26,10 @@ include::../../api/protos/vkCmdReserveSpaceForCommandsNVX.txt[] **** include::../../validity/protos/vkCmdReserveSpaceForCommandsNVX.txt[] +-- -// refBegin VkCmdReserveSpaceForCommandsInfoNVX Structure specifying parameters for the reservation of command buffer space +[open,refpage='VkCmdReserveSpaceForCommandsInfoNVX',desc='Structure specifying parameters for the reservation of command buffer space',type='structs'] +-- include::../../api/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[] @@ -43,6 +46,7 @@ include::../../api/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[] command buffer space will be reserved. include::../../validity/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[] +-- The generated commands will behave as if they were recorded within the call to fname:vkCmdReserveSpaceForCommandsNVX, that means they can inherit state @@ -52,7 +56,8 @@ not affect commands after the reserved space. Treat the state that can: be affected by the provided sname:VkIndirectCommandsLayoutNVX as undefined. -// refBegin vkCmdProcessCommandsNVX Performs the generation of commands on the device +[open,refpage='vkCmdProcessCommandsNVX',desc='Performs the generation of commands on the device',type='protos'] +-- The actual generation on the device is handled with: @@ -65,8 +70,10 @@ include::../../api/protos/vkCmdProcessCommandsNVX.txt[] affecting the processing of commands. include::../../validity/protos/vkCmdProcessCommandsNVX.txt[] +-- -// refBegin VkCmdProcessCommandsInfoNVX Structure specifying parameters for the generation of commands +[open,refpage='VkCmdProcessCommandsInfoNVX',desc='Structure specifying parameters for the generation of commands',type='structs'] +-- include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[] @@ -148,6 +155,7 @@ include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[] **** include::../../validity/structs/VkCmdProcessCommandsInfoNVX.txt[] +-- Referencing the functions defined in <>, fname:vkCmdProcessCommandsNVX behaves as: diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt index fb2a1651..7a9e120d 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt @@ -1,14 +1,15 @@ [[indirectmdslayout]] == Indirect Commands Layout -// refBegin VkIndirectCommandsLayoutNVX Opaque handle to an indirect commands layout object +[open,refpage='VkIndirectCommandsLayoutNVX',desc='Opaque handle to an indirect commands layout object',type='handles'] +-- The device-side command generation happens through an iterative processing of an atomic sequence comprised of command tokens, which are represented by: include::../../api/handles/VkIndirectCommandsLayoutNVX.txt[] -// refEnd VkIndirectCommandsLayoutNVX +-- === Tokenized Command Processing @@ -46,7 +47,8 @@ however some functional arguments, for example binding sets, are specified at layout creation time. The input size is different for each token. -// refBegin VkIndirectCommandsTokenTypeNVX Enum specifying +[open,refpage='VkIndirectCommandsTokenTypeNVX',desc='Enum specifying',type='enums'] +-- Possible values of those elements of the slink:VkIndirectCommandsLayoutCreateInfoNVX::pname:pTokens array which @@ -69,9 +71,10 @@ include::../../api/enums/VkIndirectCommandsTokenTypeNVX.txt[] |ename:VK_INDIRECT_COMMANDS_TOKEN_TYPE_DISPATCH_NVX | fname:vkCmdDispatchIndirect |==== -// refEnd VkIndirectCommandsTokenTypeNVX +-- -// refBegin VkIndirectCommandsLayoutTokenNVX Struct specifying the details of an indirect command layout token +[open,refpage='VkIndirectCommandsLayoutTokenNVX',desc='Struct specifying the details of an indirect command layout token',type='structs'] +-- The sname:VkIndirectCommandsLayoutTokenNVX structure specifies details to the function arguments that need to be known at layout creation time: @@ -99,8 +102,10 @@ include::../../api/structs/VkIndirectCommandsLayoutTokenNVX.txt[] **** include::../../validity/structs/VkIndirectCommandsLayoutTokenNVX.txt[] +-- -// refBegin VkIndirectCommandsTokenNVX Structure specifying parameters for the reservation of command buffer space +[open,refpage='VkIndirectCommandsTokenNVX',desc='Structure specifying parameters for the reservation of command buffer space',type='structs'] +-- The sname:VkIndirectCommandsTokenNVX structure specifies the input data for a token at processing time. @@ -125,6 +130,7 @@ include::../../api/structs/VkIndirectCommandsTokenNVX.txt[] **** include::../../validity/structs/VkIndirectCommandsTokenNVX.txt[] +-- The following code provides detailed information on how an individual @@ -218,6 +224,8 @@ void cmdProcessSequence(cmd, objectTable, indirectCommandsLayout, pIndirectComma === Creation and Deletion +[open,refpage='vkCreateIndirectCommandsLayoutNVX',desc='Create an indirect command layout object',type='protos'] +-- Indirect command layouts are created by: include::../../api/protos/vkCreateIndirectCommandsLayoutNVX.txt[] @@ -232,8 +240,10 @@ include::../../api/protos/vkCreateIndirectCommandsLayoutNVX.txt[] in which the resulting object table is returned. include::../../validity/protos/vkCreateIndirectCommandsLayoutNVX.txt[] +-- -// refBegin VkIndirectCommandsLayoutCreateInfoNVX Structure specifying the parameters of a newly created indirect commands layout object +[open,refpage='VkIndirectCommandsLayoutCreateInfoNVX',desc='Structure specifying the parameters of a newly created indirect commands layout object',type='structs'] +-- The sname:VkIndirectCommandsLayoutCreateInfoNVX structure is defined as: @@ -299,8 +309,10 @@ void cmdProcessAllSequences(cmd, objectTable, indirectCommandsLayout, pIndirectC **** include::../../validity/structs/VkIndirectCommandsLayoutCreateInfoNVX.txt[] +-- -// refBegin VkIndirectCommandsLayoutUsageFlagBitsNVX Bitmask specifying allowed usage of a indirect commands layout +[open,refpage='VkIndirectCommandsLayoutUsageFlagBitsNVX',desc='Bitmask specifying allowed usage of a indirect commands layout',type='enums'] +-- Bits which can: be set in slink:VkIndirectCommandsLayoutCreateInfoNVX::pname:flags, specifying usage @@ -323,9 +335,10 @@ include::../../api/enums/VkIndirectCommandsLayoutUsageFlagBitsNVX.txt[] indexed from 0..sequencesUsed but a user provided sname:VkBuffer encoding the index is provided. -// refEnd VkIndirectCommandsLayoutUsageFlagBitsNVX +-- -// refBegin vkDestroyIndirectCommandsLayoutNVX Destroy a object table +[open,refpage='vkDestroyIndirectCommandsLayoutNVX',desc='Destroy a object table',type='protos'] +-- Indirect command layouts are destroyed by: @@ -350,3 +363,4 @@ include::../../api/protos/vkDestroyIndirectCommandsLayoutNVX.txt[] **** include::../../validity/protos/vkDestroyIndirectCommandsLayoutNVX.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt index c27a8036..f092390d 100644 --- a/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt +++ b/doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt @@ -1,12 +1,13 @@ == Binding Object Table -// refBegin VkObjectTableNVX Opaque handle to an object table +[open,refpage='VkObjectTableNVX',desc='Opaque handle to an object table',type='handles'] +-- The device-side bindings are registered inside a table: include::../../api/handles/VkObjectTableNVX.txt[] -// refEnd VkObjectTableNVX +-- This is required as the CPU-side object pointers, for example when binding a sname:VkPipeline or sname:VkDescriptorSet, cannot be used by the device. @@ -23,6 +24,9 @@ maximum. === Table Creation +[open,refpage='vkCreateObjectTableNVX',desc='Create an object table',type='protos'] +-- + To create object tables, call: include::../../api/protos/vkCreateObjectTableNVX.txt[] @@ -37,8 +41,10 @@ include::../../api/protos/vkCreateObjectTableNVX.txt[] the resulting object table is returned. include::../../validity/protos/vkCreateObjectTableNVX.txt[] +-- -// refBegin VkObjectTableCreateInfoNVX Structure specifying the parameters of a newly created object table +[open,refpage='VkObjectTableCreateInfoNVX',desc='Structure specifying the parameters of a newly created object table',type='structs'] +-- The sname:VkObjectTableCreateInfoNVX structure is defined as: @@ -102,8 +108,10 @@ include::../../api/structs/VkObjectTableCreateInfoNVX.txt[] **** include::../../validity/structs/VkObjectTableCreateInfoNVX.txt[] +-- -// refBegin VkObjectEntryTypeNVX Enum specifying object table entry type +[open,refpage='VkObjectEntryTypeNVX',desc='Enum specifying object table entry type',type='enums'] +-- Possible values of elements of the slink:VkObjectTableCreateInfoNVX::pname:pObjectEntryTypes array, specifying @@ -126,9 +134,10 @@ include::../../api/enums/VkObjectEntryTypeNVX.txt[] * ename:VK_OBJECT_ENTRY_TYPE_PUSH_CONSTANT_NVX indicates the resource entry is registered via sname:VkObjectTablePushConstantEntryNVX. -// refEnd VkObjectEntryTypeNVX +-- -// refBegin VkObjectEntryUsageFlagBitsNVX Bitmask specifying allowed usage of an object entry +[open,refpage='VkObjectEntryUsageFlagBitsNVX',desc='Bitmask specifying allowed usage of an object entry',type='enums'] +-- Bits which can: be set in elements of the slink:VkObjectTableCreateInfoNVX::pname:pObjectEntryUsageFlags array, @@ -141,9 +150,10 @@ include::../../api/enums/VkObjectEntryUsageFlagBitsNVX.txt[] * ename:VK_OBJECT_ENTRY_USAGE_COMPUTE_BIT_NVX indicates that the resource is bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE -// refEnd VkObjectEntryUsageFlagBitsNVX +-- -// refBegin vkDestroyObjectTableNVX Destroy a object table +[open,refpage='vkDestroyObjectTableNVX',desc='Destroy a object table',type='protos'] +-- To destroy an object table, call: @@ -168,10 +178,14 @@ include::../../api/protos/vkDestroyObjectTableNVX.txt[] **** include::../../validity/protos/vkDestroyObjectTableNVX.txt[] +-- === Registering Objects +[open,refpage='vkRegisterObjectsNVX',desc='Register resource bindings in an object table',type='protos'] +-- + Resource bindings of Vulkan objects are registered at an arbitrary ftext:uint32_t index within an object table. As long as the object table references such objects, they must: not be @@ -207,7 +221,10 @@ include::../../api/protos/vkRegisterObjectsNVX.txt[] **** include::../../validity/protos/vkRegisterObjectsNVX.txt[] +-- +[open,refpage='VkObjectTableEntryNVX',desc='Common parameters of an object table resource entry',type='structs'] +-- Common to all resource entries are: include::../../api/structs/VkObjectTableEntryNVX.txt[] @@ -227,7 +244,10 @@ include::../../api/structs/VkObjectTableEntryNVX.txt[] **** include::../../validity/structs/VkObjectTableEntryNVX.txt[] +-- +[open,refpage='VkObjectTablePipelineEntryNVX',desc='Parameters of an object table pipeline entry',type='structs'] +-- include::../../api/structs/VkObjectTablePipelineEntryNVX.txt[] * pname:pipeline specifies the sname:VkPipeline that this resource entry @@ -240,6 +260,10 @@ include::../../api/structs/VkObjectTablePipelineEntryNVX.txt[] **** include::../../validity/structs/VkObjectTablePipelineEntryNVX.txt[] +-- + +[open,refpage='VkObjectTableDescriptorSetEntryNVX',desc='Parameters of an object table descriptor set entry',type='structs'] +-- include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[] @@ -255,6 +279,10 @@ include::../../api/structs/VkObjectTableDescriptorSetEntryNVX.txt[] **** include::../../validity/structs/VkObjectTableDescriptorSetEntryNVX.txt[] +-- + +[open,refpage='VkObjectTableVertexBufferEntryNVX',desc='Parameters of an object table vertex buffer entry',type='structs'] +-- include::../../api/structs/VkObjectTableVertexBufferEntryNVX.txt[] @@ -268,6 +296,10 @@ include::../../api/structs/VkObjectTableVertexBufferEntryNVX.txt[] **** include::../../validity/structs/VkObjectTableVertexBufferEntryNVX.txt[] +-- + +[open,refpage='VkObjectTableIndexBufferEntryNVX',desc='Parameters of an object table index buffer entry',type='structs'] +-- include::../../api/structs/VkObjectTableIndexBufferEntryNVX.txt[] @@ -283,6 +315,10 @@ include::../../api/structs/VkObjectTableIndexBufferEntryNVX.txt[] **** include::../../validity/structs/VkObjectTableIndexBufferEntryNVX.txt[] +-- + +[open,refpage='VkObjectTablePushConstantEntryNVX',desc='Parameters of an object table push constant entry',type='structs'] +-- include::../../api/structs/VkObjectTablePushConstantEntryNVX.txt[] @@ -298,8 +334,12 @@ include::../../api/structs/VkObjectTablePushConstantEntryNVX.txt[] **** include::../../validity/structs/VkObjectTablePushConstantEntryNVX.txt[] +-- -Using the following command to unregister resources from an object table: +[open,refpage='vkUnregisterObjectsNVX',desc='Unregister resource bindings in an object table',type='protos'] +-- + +Use the following command to unregister resources from an object table: include::../../api/protos/vkUnregisterObjectsNVX.txt[] @@ -326,3 +366,4 @@ include::../../api/protos/vkUnregisterObjectsNVX.txt[] **** include::../../validity/protos/vkUnregisterObjectsNVX.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.txt b/doc/specs/vulkan/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.txt index 2d5a8582..c5c09b5f 100644 --- a/doc/specs/vulkan/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.txt +++ b/doc/specs/vulkan/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.txt @@ -7,7 +7,8 @@ follows. :: [eq]#w~c~' = x~coeff~ x~c~ {plus} y~coeff~ y~c~ {plus} w~c~# -// refBegin VkPipelineViewportWScalingStateCreateInfoNV Structure specifying parameters of a newly created pipeline viewport W scaling state +[open,refpage='VkPipelineViewportWScalingStateCreateInfoNV',desc='Structure specifying parameters of a newly created pipeline viewport W scaling state',type='structs'] +-- The sname:VkPipelineViewportWScalingStateCreateInfoNV structure is defined as: @@ -50,13 +51,15 @@ include::../../api/structs/VkPipelineViewportWScalingStateCreateInfoNV.txt[] **** include::../../validity/structs/VkPipelineViewportWScalingStateCreateInfoNV.txt[] +-- The sname:VkPipelineViewportWScalingStateCreateInfoNV state is set by adding an instance of this structure to the pname:pNext chain of an instance of the sname:VkPipelineViewportStateCreateInfo structure and setting the graphics pipeline state with flink:vkCreateGraphicsPipelines. -// refBegin vkCmdSetViewportWScalingNV Set the viewport W scaling on a command buffer +[open,refpage='vkCmdSetViewportWScalingNV',desc='Set the viewport W scaling on a command buffer',type='protos'] +-- If the bound pipeline state object was not created with the ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV dynamic state enabled, viewport @@ -100,12 +103,14 @@ pname:viewportCount)#. **** include::../../validity/protos/vkCmdSetViewportWScalingNV.txt[] +-- Both slink:VkPipelineViewportWScalingStateCreateInfoNV and flink:vkCmdSetViewportWScalingNV use sname:VkViewportWScalingNV to set the viewport transformation parameters. -// refBegin VkViewportWScalingNV Structure specifying a viewport +[open,refpage='VkViewportWScalingNV',desc='Structure specifying a viewport',type='structs'] +-- The sname:VkViewportWScalingNV structure is defined as: @@ -115,3 +120,4 @@ include::../../api/structs/VkViewportWScalingNV.txt[] and y respectively. include::../../validity/structs/VkViewportWScalingNV.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory/allocate_memory.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory/allocate_memory.txt index 558f7f23..ce0f58a8 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory/allocate_memory.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory/allocate_memory.txt @@ -3,6 +3,8 @@ instance, add a slink:VkExportMemoryAllocateInfoNV structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure, specifying the handle types that may: be exported. +[open,refpage='VkExportMemoryAllocateInfoNV',desc='Specify memory handle types that may be exported',type='structs'] +-- The slink:VkExportMemoryAllocateInfoNV structure is defined as: include::../../api/structs/VkExportMemoryAllocateInfoNV.txt[] @@ -17,3 +19,4 @@ include::../../api/structs/VkExportMemoryAllocateInfoNV.txt[] flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV. include::../../validity/structs/VkExportMemoryAllocateInfoNV.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory_capabilities/external_image_format.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory_capabilities/external_image_format.txt index f7cd348c..91d668ee 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory_capabilities/external_image_format.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory_capabilities/external_image_format.txt @@ -1,4 +1,5 @@ -// refBegin vkGetPhysicalDeviceExternalImageFormatPropertiesNV determine image capabilities compatible with external memory handle types +[open,refpage='vkGetPhysicalDeviceExternalImageFormatPropertiesNV',desc='determine image capabilities compatible with external memory handle types',type='protos'] +-- To determine the image capabilities compatible with an external memory handle type, call: @@ -31,8 +32,10 @@ Otherwise, they are filled in as described for slink:VkExternalImageFormatPropertiesNV. include::../../validity/protos/vkGetPhysicalDeviceExternalImageFormatPropertiesNV.txt[] +-- -// refBegin VkExternalImageFormatPropertiesNV - Structure specifying external image format properties +[open,refpage='VkExternalImageFormatPropertiesNV',desc='Structure specifying external image format properties',type='structs'] +-- The sname:VkExternalImageFormatPropertiesNV structure is defined as: @@ -63,8 +66,10 @@ include::../../api/structs/VkExternalImageFormatPropertiesNV.txt[] flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV::pname:externalHandleType include::../../validity/structs/VkExternalImageFormatPropertiesNV.txt[] +-- -// refBegin VkExternalMemoryFeatureFlagBitsNV - Bitmask specifying external memory features +[open,refpage='VkExternalMemoryFeatureFlagBitsNV',desc='Bitmask specifying external memory features',type='enums',xrefs='vkGetPhysicalDeviceExternalImageFormatPropertiesNV VkExternalImageFormatPropertiesNV'] +-- Bits which can: be set in slink:VkExternalMemoryFeatureFlagBitsNV::pname:externalMemoryFeatures, @@ -80,4 +85,4 @@ include::../../api/enums/VkExternalMemoryFeatureFlagBitsNV.txt[] * ename:VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT_NV indicates that the implementation supports importing handles of the specified type. -// refEnd VkExternalMemoryFeatureFlagBitsNV vkGetPhysicalDeviceExternalImageFormatPropertiesNV VkExternalImageFormatPropertiesNV +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/get_handle_win32.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/get_handle_win32.txt index 62232827..ddd5f096 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/get_handle_win32.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/get_handle_win32.txt @@ -1,4 +1,5 @@ -// refBegin vkGetMemoryWin32HandleNV - retrieve Win32 handle to a device memory object +[open,refpage='vkGetMemoryWin32HandleNV',desc='retrieve Win32 handle to a device memory object',type='protos'] +-- To retrieve the handle corresponding to a device memory object created with slink:VkExportMemoryAllocateInfoNV::pname:handleTypes set to include @@ -24,3 +25,4 @@ include::../../api/protos/vkGetMemoryWin32HandleNV.txt[] **** include::../../validity/protos/vkGetMemoryWin32HandleNV.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/handle_permissions.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/handle_permissions.txt index c304de68..62dfe428 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/handle_permissions.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/handle_permissions.txt @@ -1,4 +1,5 @@ -// refBegin VkExportMemoryWin32HandleInfoNV - specify security attributes and access rights for Win32 memory handles +[open,refpage='VkExportMemoryWin32HandleInfoNV',desc='specify security attributes and access rights for Win32 memory handles',type='structs'] +-- When slink:VkExportMemoryAllocateInfoNV::pname:handleTypes includes ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_NV, add a @@ -27,3 +28,4 @@ Further, if the structure is not present, the access rights will be [1] https://msdn.microsoft.com/en-us/library/windows/desktop/ms686670.aspx include::../../validity/structs/VkExportMemoryWin32HandleInfoNV.txt[] +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt index 1eac0956..b0a469b4 100644 --- a/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt +++ b/doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt @@ -1,4 +1,5 @@ -// refBegin VkImportMemoryWin32HandleInfoNV - import Win32 memory created on the same physical device +[open,refpage='VkImportMemoryWin32HandleInfoNV',desc='import Win32 memory created on the same physical device',type='structs'] +-- To import memory created on the same physical device but outside of the current Vulkan instance, add a slink:VkImportMemoryWin32HandleInfoNV @@ -28,10 +29,12 @@ slink:VkMemoryAllocateInfo structure it is chained from. **** include::../../validity/structs/VkImportMemoryWin32HandleInfoNV.txt[] +-- Bits which can: be set in pname:handleType are: -// refBegin VkExternalMemoryHandleTypeFlagBitsNV - Bitmask specifying external memory handle types +[open,refpage='VkExternalMemoryHandleTypeFlagBitsNV',desc='Bitmask specifying external memory handle types',type='enums'] +-- Possible values of slink:VkImportMemoryWin32HandleInfoNV::pname:handleType, specifying the type of an external memory handle, are: @@ -61,4 +64,4 @@ defined by. ================== endif::editing-notes[] -// refEnd VkExternalMemoryHandleTypeFlagBitsNV +-- diff --git a/doc/specs/vulkan/chapters/VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt b/doc/specs/vulkan/chapters/VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt index 730a50e4..c73a6bb0 100644 --- a/doc/specs/vulkan/chapters/VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt +++ b/doc/specs/vulkan/chapters/VK_NV_win32_keyed_mutex/keyed_mutex_submit.txt @@ -1,4 +1,5 @@ -// refBegin VkWin32KeyedMutexAcquireReleaseInfoNV - use Windows keyex mutex mechanism to synchronize work +[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoNV',desc='use Windows keyex mutex mechanism to synchronize work',type='structs'] +-- When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may: be used in addition to @@ -37,3 +38,4 @@ include::../../api/structs/VkWin32KeyedMutexAcquireReleaseInfoNV.txt[] entries in pname:pReleaseSyncs. include::../../validity/structs/VkWin32KeyedMutexAcquireReleaseInfoNV.txt[] +-- diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt index b0ee65e0..c77d283b 100644 --- a/doc/specs/vulkan/chapters/clears.txt +++ b/doc/specs/vulkan/chapters/clears.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[clears]] = Clear Commands @@ -13,7 +14,8 @@ instance using flink:vkCmdClearColorImage or flink:vkCmdClearDepthStencilImage, respectively. These commands are only allowed outside of a render pass instance. -// refBegin vkCmdClearColorImage Clear regions of a color image +[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos'] +-- To clear one or more subranges of a color image, call: @@ -65,13 +67,17 @@ endif::VK_KHR_maintenance1[] pname:imageLayout must: specify the layout of the image subresource ranges of pname:image specified in pname:pRanges at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdClearColorImage-imageLayout-00005]] - pname:imageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, -endif::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or + pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdClearColorImage-imageLayout-01394]] + pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, + ename:VK_IMAGE_LAYOUT_GENERAL, or + ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdClearColorImage-pRanges-00006]] The image range of any given element of pname:pRanges must: be an image subresource range that is contained within pname:image @@ -80,8 +86,10 @@ endif::VK_KHR_shared_presentable_image[] **** include::../validity/protos/vkCmdClearColorImage.txt[] +-- -// refBegin vkCmdClearDepthStencilImage Fill regions of a combined depth/stencil image +[open,refpage='vkCmdClearDepthStencilImage',desc='Fill regions of a combined depth/stencil image',type='protos'] +-- To clear one or more subranges of a depth/stencil image, call: @@ -143,6 +151,7 @@ endif::VK_KHR_maintenance1[] **** include::../validity/protos/vkCmdClearDepthStencilImage.txt[] +-- Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers. @@ -151,7 +160,8 @@ the purposes of memory barriers. [[clears-inside]] == Clearing Images Inside A Render Pass Instance -// refBegin vkCmdClearAttachments Clear regions within currently bound framebuffer attachments +[open,refpage='vkCmdClearAttachments',desc='Clear regions within currently bound framebuffer attachments',type='protos'] +-- To clear one or more regions of color and depth/stencil attachments inside a render pass instance, call: @@ -197,8 +207,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdClearAttachments.txt[] +-- -// refBegin VkClearRect Structure specifying a clear rectangle +[open,refpage='VkClearRect',desc='Structure specifying a clear rectangle',type='structs'] +-- The sname:VkClearRect structure is defined as: @@ -213,8 +225,10 @@ pname:layerCount)# counting from the base layer of the attachment image view are cleared. include::../validity/structs/VkClearRect.txt[] +-- -// refBegin VkClearAttachment Structure specifying a clear attachment +[open,refpage='VkClearAttachment',desc='Structure specifying a clear attachment',type='structs'] +-- The sname:VkClearAttachment structure is defined as: @@ -264,12 +278,14 @@ described for flink:vkCreateRenderPass. **** include::../validity/structs/VkClearAttachment.txt[] +-- [[clears-values]] == Clear Values -// refBegin VkClearColorValue Structure specifying a clear color value +[open,refpage='VkClearColorValue',desc='Structure specifying a clear color value',type='structs'] +-- The sname:VkClearColorValue structure is defined as: @@ -303,8 +319,10 @@ If the image has more than one sample, the same value is written to all samples for any pixels being cleared. include::../validity/structs/VkClearColorValue.txt[] +-- -// refBegin VkClearDepthStencilValue Structure specifying a clear depth stencil value +[open,refpage='VkClearDepthStencilValue',desc='Structure specifying a clear depth stencil value',type='structs'] +-- The sname:VkClearDepthStencilValue structure is defined as: @@ -326,8 +344,10 @@ include::../api/structs/VkClearDepthStencilValue.txt[] **** include::../validity/structs/VkClearDepthStencilValue.txt[] +-- -// refBegin VkClearValue Structure specifying a clear value +[open,refpage='VkClearValue',desc='Structure specifying a clear value',type='structs'] +-- The sname:VkClearValue union is defined as: @@ -350,12 +370,14 @@ initial clear values in the slink:VkRenderPassBeginInfo structure. **** include::../validity/structs/VkClearValue.txt[] +-- [[clears-filling-buffers]] == Filling Buffers -// refBegin vkCmdFillBuffer Fill a region of a buffer with a fixed value +[open,refpage='vkCmdFillBuffer',desc='Fill a region of a buffer with a fixed value',type='protos'] +-- To clear buffer data, call: @@ -410,12 +432,14 @@ endif::VK_KHR_maintenance1[] **** include::../validity/protos/vkCmdFillBuffer.txt[] +-- [[clears-updating-buffers]] == Updating Buffers -// refBegin vkCmdUpdateBuffer Update a buffer's contents from host memory +[open,refpage='vkCmdUpdateBuffer',desc='Update a buffer\'s contents from host memory',type='protos'] +-- To update buffer data inline in a command buffer, call: @@ -467,6 +491,7 @@ fname:vkCmdUpdateBuffer. **** include::../validity/protos/vkCmdUpdateBuffer.txt[] +-- [NOTE] .Note diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt index a1613338..5b4a141f 100644 --- a/doc/specs/vulkan/chapters/cmdbuffers.txt +++ b/doc/specs/vulkan/chapters/cmdbuffers.txt @@ -1,10 +1,12 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[commandbuffers]] = Command Buffers -// refBegin VkCommandBuffer Opaque handle to a command buffer object +[open,refpage='VkCommandBuffer',desc='Opaque handle to a command buffer object',type='handles'] +-- Command buffers are objects used to record commands which can: be subsequently submitted to a device queue for execution. @@ -17,7 +19,7 @@ Command buffers are represented by sname:VkCommandBuffer handles: include::../api/handles/VkCommandBuffer.txt[] -// refEnd VkCommandBuffer +-- Recorded commands include commands to bind pipelines and descriptor sets to the command buffer, commands to modify dynamic state, commands to draw (for @@ -126,7 +128,8 @@ secondary command buffers that were recorded to it. [[commandbuffers-pools]] == Command Pools -// refBegin VkCommandPool Opaque handle to a command pool object +[open,refpage='VkCommandPool',desc='Opaque handle to a command pool object',type='handles'] +-- Command pools are opaque objects that command buffer memory is allocated from, and which allow the implementation to amortize the cost of resource @@ -141,9 +144,10 @@ Command pools are represented by sname:VkCommandPool handles: include::../api/handles/VkCommandPool.txt[] -// refEnd VkCommandPool +-- -// refBegin vkCreateCommandPool Create a new command pool object +[open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] +-- To create a command pool, call: @@ -157,8 +161,10 @@ include::../api/protos/vkCreateCommandPool.txt[] created pool is returned. include::../validity/protos/vkCreateCommandPool.txt[] +-- -// refBegin VkCommandPoolCreateInfo Structure specifying parameters of a newly created command pool +[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] +-- The sname:VkCommandPoolCreateInfo structure is defined as: @@ -181,8 +187,10 @@ include::../api/structs/VkCommandPoolCreateInfo.txt[] **** include::../validity/structs/VkCommandPoolCreateInfo.txt[] +-- -// refBegin VkCommandPoolCreateFlagBits Bitmask specifying usage behavior for a command pool +[open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] +-- Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to specify usage behavior for a command pool are: @@ -202,11 +210,12 @@ include::../api/enums/VkCommandPoolCreateFlagBits.txt[] If this flag is not set on a pool, then fname:vkResetCommandBuffer must: not be called for any command buffer allocated from that pool. -// refEnd VkCommandPoolCreateFlagBits +-- ifdef::VK_KHR_maintenance1[] -// refBegin vkTrimCommandPoolKHR Trim a command pool +[open,refpage='vkTrimCommandPoolKHR',desc='Trim a command pool',type='protos'] +-- To trim a command pool, call: @@ -260,10 +269,12 @@ cost of trimming is "worth" it. ==== include::../validity/protos/vkTrimCommandPoolKHR.txt[] +-- endif::VK_KHR_maintenance1[] -// refBegin vkResetCommandPool Reset a command pool +[open,refpage='vkResetCommandPool',desc='Reset a command pool',type='protos'] +-- To reset a command pool, call: @@ -292,8 +303,10 @@ into it, becomes <>. **** include::../validity/protos/vkResetCommandPool.txt[] +-- -// refBegin VkCommandPoolResetFlagBits Bitmask controlling behavior of a command pool reset +[open,refpage='VkCommandPoolResetFlagBits',desc='Bitmask controlling behavior of a command pool reset',type='enums'] +-- Bits which can: be set in flink:vkResetCommandPool::pname:flags to control the reset operation are: @@ -304,9 +317,10 @@ include::../api/enums/VkCommandPoolResetFlagBits.txt[] resetting a command pool recycles all of the resources from the command pool back to the system. -// refEnd VkCommandPoolResetFlagBits +-- -// refBegin vkDestroyCommandPool Destroy a command pool object +[open,refpage='vkDestroyCommandPool',desc='Destroy a command pool object',type='protos'] +-- To destroy a command pool, call: @@ -339,12 +353,14 @@ into it, becomes <>. **** include::../validity/protos/vkDestroyCommandPool.txt[] +-- [[commandbuffer-allocation]] == Command Buffer Allocation and Management -// refBegin vkAllocateCommandBuffers Allocate command buffers from an existing command pool +[open,refpage='vkAllocateCommandBuffers',desc='Allocate command buffers from an existing command pool',type='protos'] +-- To allocate command buffers, call: @@ -373,8 +389,10 @@ When command buffers are first allocated, they are in the <>. include::../validity/protos/vkAllocateCommandBuffers.txt[] +-- -// refBegin VkCommandBufferAllocateInfo Structure specifying the allocation parameters for command buffer object +[open,refpage='VkCommandBufferAllocateInfo',desc='Structure specifying the allocation parameters for command buffer object',type='structs'] +-- The sname:VkCommandBufferAllocateInfo structure is defined as: @@ -396,8 +414,10 @@ include::../api/structs/VkCommandBufferAllocateInfo.txt[] **** include::../validity/structs/VkCommandBufferAllocateInfo.txt[] +-- -// refBegin VkCommandBufferLevel Enumerant specifying a command buffer level +[open,refpage='VkCommandBufferLevel',desc='Enumerant specifying a command buffer level',type='enums'] +-- Possible values of slink:VkCommandBufferAllocateInfo::pname:flags, specifying the command buffer level, are: @@ -409,9 +429,10 @@ include::../api/enums/VkCommandBufferLevel.txt[] * ename:VK_COMMAND_BUFFER_LEVEL_SECONDARY specifies a secondary command buffer. -// refEnd VkCommandBufferLevel +-- -// refBegin vkResetCommandBuffer Reset a command buffer to the initial state +[open,refpage='vkResetCommandBuffer',desc='Reset a command buffer to the initial state',type='protos'] +-- To reset command buffers, call: @@ -439,8 +460,10 @@ it, becomes <>. **** include::../validity/protos/vkResetCommandBuffer.txt[] +-- -// refBegin VkCommandBufferResetFlagBits Bitmask controlling behavior of a command buffer reset +[open,refpage='VkCommandBufferResetFlagBits',desc='Bitmask controlling behavior of a command buffer reset',type='enums'] +-- Bits which can: be set in flink:vkResetCommandBuffer::pname:flags to control the reset operation are: @@ -455,9 +478,10 @@ include::../api/enums/VkCommandBufferResetFlagBits.txt[] pname:commandBuffer is moved to the <>. -// refEnd VkCommandBufferResetFlagBits +-- -// refBegin vkFreeCommandBuffers Free command buffers +[open,refpage='vkFreeCommandBuffers',desc='Free command buffers',type='protos'] +-- To free command buffers, call: @@ -486,12 +510,14 @@ recorded into it, becomes <>. **** include::../validity/protos/vkFreeCommandBuffers.txt[] +-- [[commandbuffers-recording]] == Command Buffer Recording -// refBegin vkBeginCommandBuffer Start recording a command buffer +[open,refpage='vkBeginCommandBuffer',desc='Start recording a command buffer',type='protos'] +-- To begin recording a command buffer, call: @@ -527,8 +553,10 @@ include::../api/protos/vkBeginCommandBuffer.txt[] **** include::../validity/protos/vkBeginCommandBuffer.txt[] +-- -// refBegin VkCommandBufferBeginInfo Structure specifying a command buffer begin operation +[open,refpage='VkCommandBufferBeginInfo',desc='Structure specifying a command buffer begin operation',type='structs'] +-- The sname:VkCommandBufferBeginInfo structure is defined as: @@ -564,8 +592,10 @@ include::../api/structs/VkCommandBufferBeginInfo.txt[] **** include::../validity/structs/VkCommandBufferBeginInfo.txt[] +-- -// refBegin VkCommandBufferUsageFlagBits Bitmask specifying usage behavior for command buffer +[open,refpage='VkCommandBufferUsageFlagBits',desc='Bitmask specifying usage behavior for command buffer',type='enums'] +-- Bits which can: be set in slink:VkCommandBufferBeginInfo::pname:flags to specify usage behavior for a command buffer are: @@ -583,9 +613,10 @@ include::../api/enums/VkCommandBufferUsageFlagBits.txt[] command buffer can: be resubmitted to a queue while it is in the _pending state_, and recorded into multiple primary command buffers. -// refEnd VkCommandBufferUsageFlagBits +-- -// refBegin VkCommandBufferInheritanceInfo Structure specifying command buffer inheritance info +[open,refpage='VkCommandBufferInheritanceInfo',desc='Structure specifying command buffer inheritance info',type='structs'] +-- If the command buffer is a secondary command buffer, then the sname:VkCommandBufferInheritanceInfo structure defines any state that will @@ -658,6 +689,7 @@ time. **** include::../validity/structs/VkCommandBufferInheritanceInfo.txt[] +-- If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT was not set when creating a command buffer, that command buffer must: not be submitted to a @@ -694,7 +726,8 @@ Several commands can also be recorded indirectly from sname:VkBuffer content, see <>. endif::VK_NVX_device_generated_commands[] -// refBegin vkEndCommandBuffer Finish recording a command buffer +[open,refpage='vkEndCommandBuffer',desc='Finish recording a command buffer',type='protos'] +-- To complete recording of a command buffer, call: @@ -731,6 +764,7 @@ endif::VK_EXT_debug_marker[] **** include::../validity/protos/vkEndCommandBuffer.txt[] +-- When a command buffer is in the executable state, it can: be submitted to a queue for execution. @@ -739,7 +773,8 @@ queue for execution. [[commandbuffers-submission]] == Command Buffer Submission -// refBegin vkQueueSubmit Submits a sequence of semaphores or command buffers to a queue +[open,refpage='vkQueueSubmit',desc='Submits a sequence of semaphores or command buffers to a queue',type='protos'] +-- To submit command buffers to a queue, call: @@ -868,8 +903,10 @@ See <>. **** include::../validity/protos/vkQueueSubmit.txt[] +-- -// refBegin VkSubmitInfo Structure specifying a queue submit operation +[open,refpage='VkSubmitInfo',desc='Structure specifying a queue submit operation',type='structs'] +-- The sname:VkSubmitInfo structure is defined as: @@ -928,10 +965,12 @@ otherwise execute out of order. **** include::../validity/structs/VkSubmitInfo.txt[] +-- ifdef::VK_KHX_external_semaphore_win32[] -// refBegin VkD3D12FenceSubmitInfoKHX Structure specifying values for Direct3D 12 fence-backed semaphores +[open,refpage='VkD3D12FenceSubmitInfoKHX',desc='Structure specifying values for Direct3D 12 fence-backed semaphores',type='structs'] +-- To specify the values to use when waiting for and signaling semaphores whose current state is shared with a Direct3D 12 fence, add the @@ -976,12 +1015,14 @@ pname:pWaitSemaphoreValues or pname:pSignalSemaphoreValues entry is ignored. **** include::../validity/structs/VkD3D12FenceSubmitInfoKHX.txt[] +-- endif::VK_KHX_external_semaphore_win32[] ifdef::VK_KHX_win32_keyed_mutex[] -// refBegin VkWin32KeyedMutexAcquireReleaseInfoKHX Use the Windows keyed mutex mechanism to synchronize work +[open,refpage='VkWin32KeyedMutexAcquireReleaseInfoKHX',desc='Use the Windows keyed mutex mechanism to synchronize work',type='structs'] +-- When submitting work that operates on memory imported from a Direct3D 11 resource to a queue, the keyed mutex mechanism may: be used in addition to @@ -1029,6 +1070,7 @@ include::../api/structs/VkWin32KeyedMutexAcquireReleaseInfoKHX.txt[] **** include::../validity/structs/VkWin32KeyedMutexAcquireReleaseInfoKHX.txt[] +-- endif::VK_KHX_win32_keyed_mutex[] @@ -1038,7 +1080,8 @@ endif::VK_NV_win32_keyed_mutex[] ifdef::VK_KHX_device_group[] -// refBegin VkDeviceGroupSubmitInfoKHX Structure indicating which physical devices execute semaphore operations and command buffers +[open,refpage='VkDeviceGroupSubmitInfoKHX',desc='Structure indicating which physical devices execute semaphore operations and command buffers',type='structs'] +-- If the pname:pNext list of slink:VkSubmitInfo includes a sname:VkDeviceGroupSubmitInfoKHX structure, then that structure includes @@ -1095,7 +1138,7 @@ execute on device index zero. include::../validity/structs/VkDeviceGroupSubmitInfoKHX.txt[] -// refEnd VkDeviceGroupSubmitInfoKHX +-- endif::VK_KHX_device_group[] @@ -1124,7 +1167,8 @@ may: include device loss. [[commandbuffers-secondary]] == Secondary Command Buffer Execution -// refBegin vkCmdExecuteCommands Execute a secondary command buffer from a primary command buffer +[open,refpage='vkCmdExecuteCommands',desc='Execute a secondary command buffer from a primary command buffer',type='protos'] +-- A secondary command buffer must: not be directly submitted to a queue. Instead, secondary command buffers are recorded to execute as part of a @@ -1239,6 +1283,7 @@ command buffer becomes <>. **** include::../validity/protos/vkCmdExecuteCommands.txt[] +-- ifdef::VK_KHX_device_group[] @@ -1265,7 +1310,8 @@ pname:pCommandBufferDeviceMasks member of slink:VkDeviceGroupSubmitInfoKHX. Commands only execute on a physical device if the device index is set in both device masks. -// refBegin VkDeviceGroupCommandBufferBeginInfoKHX Set the initial device mask for a command buffer +[open,refpage='VkDeviceGroupCommandBufferBeginInfoKHX',desc='Set the initial device mask for a command buffer',type='structs'] +-- If the pname:pNext list of slink:VkCommandBufferBeginInfo includes a sname:VkDeviceGroupCommandBufferBeginInfoKHX structure, then that structure @@ -1296,9 +1342,11 @@ when the command buffer begins recording. **** include::../validity/structs/VkDeviceGroupCommandBufferBeginInfoKHX.txt[] +-- -// refBegin vkCmdSetDeviceMaskKHX Modify device mask of a command buffer +[open,refpage='vkCmdSetDeviceMaskKHX',desc='Modify device mask of a command buffer',type='protos'] +-- To update the current device mask of a command buffer, call: @@ -1329,5 +1377,6 @@ all physical devices whose bit indices are not set in the mask. **** include::../validity/protos/vkCmdSetDeviceMaskKHX.txt[] +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt index 06bf7116..f8eaadca 100644 --- a/doc/specs/vulkan/chapters/copies.txt +++ b/doc/specs/vulkan/chapters/copies.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[copies]] = Copy Commands @@ -75,7 +76,8 @@ synchronization barriers. [[copies-buffers]] == Copying Data Between Buffers -// refBegin vkCmdCopyBuffer Copy data between buffer regions +[open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos'] +-- To copy data between buffer objects, call: @@ -131,8 +133,10 @@ memory. **** include::../validity/protos/vkCmdCopyBuffer.txt[] +-- -// refBegin VkBufferCopy Structure specifying a buffer copy operation +[open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs'] +-- The sname:VkBufferCopy structure is defined as: @@ -145,6 +149,7 @@ include::../api/structs/VkBufferCopy.txt[] * pname:size is the number of bytes to copy. include::../validity/structs/VkBufferCopy.txt[] +-- [[copies-images]] @@ -158,7 +163,8 @@ Rather, it simply copies raw image data. fname:vkCmdCopyImage can: copy between images with different formats, provided the formats are compatible as defined below. -// refBegin vkCmdCopyImage Copy data between images +[open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos'] +-- To copy data between image objects, call: @@ -203,9 +209,10 @@ compressed texel block of the source image is copied as a raw value to the corresponding texel of uncompressed data in the destination image. Thus, for example, it is legal to copy between a 128-bit uncompressed format and a compressed format which has a 128-bit sized compressed texel block -representing 4x4 texels (using 8 bits per texel), or between a 64-bit +representing 4{times}4 texels (using 8 bits per texel), or between a 64-bit uncompressed format and a compressed format which has a 64-bit sized -compressed texel block representing 4x4 texels (using 4 bits per texel). +compressed texel block representing 4{times}4 texels (using 4 bits per +texel). When copying between compressed and uncompressed formats the pname:extent members represent the texel dimensions of the source image and not the @@ -287,13 +294,18 @@ endif::VK_KHR_maintenance1[] pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdCopyImage-srcImageLayout-00129]] + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyImage-srcImageLayout-00129]] pname:srcImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, + ename:VK_IMAGE_LAYOUT_GENERAL, or + ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR endif::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL ifdef::VK_KHR_maintenance1[] * [[VUID-vkCmdCopyImage-dstImage-00130]] pname:dstImage must: use a format that supports @@ -313,13 +325,18 @@ endif::VK_KHR_maintenance1[] pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyImage-dstImageLayout-00134]] - pname:dstImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdCopyImage-dstImageLayout-01395]] + pname:dstImageLayout must: be + ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, + ename:VK_IMAGE_LAYOUT_GENERAL, or + ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR endif::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL * [[VUID-vkCmdCopyImage-srcImage-00135]] The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be compatible, as defined <> @@ -328,8 +345,10 @@ endif::VK_KHR_shared_presentable_image[] **** include::../validity/protos/vkCmdCopyImage.txt[] +-- -// refBegin VkImageCopy Structure specifying an image copy operation +[open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs'] +-- The sname:VkImageCopy structure is defined as: @@ -495,8 +514,10 @@ endif::VK_KHR_maintenance1[] **** include::../validity/structs/VkImageCopy.txt[] +-- -// refBegin VkImageSubresourceLayers Structure specifying a image subresource layers +[open,refpage='VkImageSubresourceLayers',desc='Structure specifying a image subresource layers',type='structs'] +-- The sname:VkImageSubresourceLayers structure is defined as: @@ -526,12 +547,14 @@ include::../api/structs/VkImageSubresourceLayers.txt[] **** include::../validity/structs/VkImageSubresourceLayers.txt[] +-- [[copies-buffers-images]] == Copying Data Between Buffers and Images -// refBegin vkCmdCopyBufferToImage Copy data from a buffer into an image +[open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos'] +-- To copy data from a buffer object to an image object, call: @@ -590,18 +613,25 @@ endif::VK_KHR_maintenance1[] pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00181]] - pname:dstImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-01396]] + pname:dstImageLayout must: be + ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, + ename:VK_IMAGE_LAYOUT_GENERAL, or + ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR endif::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or - ename:VK_IMAGE_LAYOUT_GENERAL **** include::../validity/protos/vkCmdCopyBufferToImage.txt[] +-- -// refBegin vkCmdCopyImageToBuffer Copy image data into a buffer +[open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos'] +-- To copy data from an image object to a buffer object, call: @@ -654,13 +684,17 @@ endif::VK_KHR_maintenance1[] pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00190]] - pname:srcImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397]] + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00191]] pname:dstBuffer must: have been created with ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag @@ -670,8 +704,10 @@ endif::VK_KHR_shared_presentable_image[] **** include::../validity/protos/vkCmdCopyImageToBuffer.txt[] +-- -// refBegin VkBufferImageCopy Structure specifying a buffer image copy operation +[open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs'] +-- For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each element of pname:pRegions is a structure defined as: @@ -821,6 +857,7 @@ destination image. **** include::../validity/structs/VkBufferImageCopy.txt[] +-- Pseudocode for image/buffer addressing is: @@ -896,7 +933,8 @@ copy. [[copies-imagescaling]] == Image Copies with Scaling -// refBegin vkCmdBlitImage Copy regions of an image, potentially performing format conversion, +[open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos'] +-- To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call: @@ -1040,13 +1078,17 @@ representable range of the destination format, then casting the value. pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdBlitImage-srcImageLayout-00222]] - pname:srcImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdBlitImage-srcImageLayout-01398]] + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdBlitImage-dstImage-00223]] pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by @@ -1064,13 +1106,17 @@ endif::VK_KHR_shared_presentable_image[] pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdBlitImage-dstImageLayout-00227]] - pname:dstImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdBlitImage-dstImageLayout-01399]] + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdBlitImage-srcImage-00228]] The sample count of pname:srcImage and pname:dstImage must: both be equal to ename:VK_SAMPLE_COUNT_1_BIT @@ -1118,8 +1164,10 @@ endif::VK_IMG_filter_cubic[] **** include::../validity/protos/vkCmdBlitImage.txt[] +-- -// refBegin VkImageBlit Structure specifying an image blit operation +[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs'] +-- The sname:VkImageBlit structure is defined as: @@ -1199,12 +1247,14 @@ the specified source and destination regions. **** include::../validity/structs/VkImageBlit.txt[] +-- [[copies-resolve]] == Resolving Multisample Images -// refBegin vkCmdResolveImage Resolve regions of an image +[open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos'] +-- To resolve a multisample image to a non-multisample image, call: @@ -1268,24 +1318,32 @@ pname:layerCount layers are resolved to the destination image. pname:srcImageLayout must: specify the layout of the image subresources of pname:srcImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdResolveImage-srcImageLayout-00261]] - pname:srcImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdResolveImage-srcImageLayout-01400]] + pname:srcImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdResolveImage-dstImageLayout-00262]] pname:dstImageLayout must: specify the layout of the image subresources of pname:dstImage specified in pname:pRegions at the time this command is executed on a sname:VkDevice +ifndef::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdResolveImage-dstImageLayout-00263]] - pname:dstImageLayout must: be -ifdef::VK_KHR_shared_presentable_image[] - ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL + or ename:VK_IMAGE_LAYOUT_GENERAL endif::VK_KHR_shared_presentable_image[] +ifdef::VK_KHR_shared_presentable_image[] + * [[VUID-vkCmdResolveImage-dstImageLayout-01401]] + pname:dstImageLayout must: be ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL +endif::VK_KHR_shared_presentable_image[] * [[VUID-vkCmdResolveImage-dstImage-00264]] If pname:dstImage was created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR, pname:dstImage must: have been created @@ -1306,8 +1364,10 @@ endif::VK_KHR_shared_presentable_image[] **** include::../validity/protos/vkCmdResolveImage.txt[] +-- -// refBegin VkImageResolve Structure specifying an image resolve operation +[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs'] +-- The sname:VkImageResolve structure is defined as: @@ -1381,4 +1441,5 @@ include::../api/structs/VkImageResolve.txt[] **** include::../validity/structs/VkImageResolve.txt[] +-- diff --git a/doc/specs/vulkan/chapters/debugging.txt b/doc/specs/vulkan/chapters/debugging.txt index 95d58087..cf40c39b 100644 --- a/doc/specs/vulkan/chapters/debugging.txt +++ b/doc/specs/vulkan/chapters/debugging.txt @@ -4,7 +4,8 @@ To aid developers in tracking down errors in the application's use of Vulkan, particularly in combination with an external debugger or profiler, _debugging extensions_ may be available. -// refBegin VkObjectType Specify an enumeration to track object handle types +[open,refpage='VkObjectType',desc='Specify an enumeration to track object handle types',type='enums'] +-- The elink:VkObjectType enumeration defines values, each of which corresponds to a specific Vulkan handle type. @@ -13,7 +14,7 @@ type of object through one or more extensions. include::../api/enums/VkObjectType.txt[] -// refEnd VkObjectType +-- If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter. diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt index ffa38cc9..c9da5b1f 100644 --- a/doc/specs/vulkan/chapters/descriptorsets.txt +++ b/doc/specs/vulkan/chapters/descriptorsets.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[descriptorsets]] = Resource Descriptors @@ -565,7 +566,8 @@ shader stages and shader resources. [[descriptorsets-setlayout]] === Descriptor Set Layout -// refBegin VkDescriptorSetLayout Opaque handle to a descriptor set layout object +[open,refpage='VkDescriptorSetLayout',desc='Opaque handle to a descriptor set layout object',type='handles'] +-- A descriptor set layout object is defined by an array of zero or more descriptor bindings. @@ -579,9 +581,10 @@ handles: include::../api/handles/VkDescriptorSetLayout.txt[] -// refEnd VkDescriptorSetLayout +-- -// refBegin vkCreateDescriptorSetLayout Create a new descriptor set layout +[open,refpage='vkCreateDescriptorSetLayout',desc='Create a new descriptor set layout',type='protos'] +-- To create descriptor set layout objects, call: @@ -598,8 +601,10 @@ include::../api/protos/vkCreateDescriptorSetLayout.txt[] the resulting descriptor set layout object is returned. include::../validity/protos/vkCreateDescriptorSetLayout.txt[] +-- -// refBegin VkDescriptorSetLayoutCreateInfo Structure specifying parameters of a newly created descriptor set layout +[open,refpage='VkDescriptorSetLayoutCreateInfo',desc='Structure specifying parameters of a newly created descriptor set layout',type='structs'] +-- Information about the descriptor set layout is passed in an instance of the sname:VkDescriptorSetLayoutCreateInfo structure: @@ -638,8 +643,10 @@ endif::VK_KHR_push_descriptor[] **** include::../validity/structs/VkDescriptorSetLayoutCreateInfo.txt[] +-- -// refBegin VkDescriptorSetLayoutCreateFlagBits Bitmask specifying descriptor set layout properties +[open,refpage='VkDescriptorSetLayoutCreateFlagBits',desc='Bitmask specifying descriptor set layout properties',type='enums'] +-- Bits which can: be set in slink:VkDescriptorSetLayoutCreateInfo::pname:flags to specify options for descriptor set layout are: @@ -652,9 +659,10 @@ ifdef::VK_KHR_push_descriptor[] descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. endif::VK_KHR_push_descriptor[] -// refEnd VkDescriptorSetLayoutCreateFlagBits +-- -// refBegin VkDescriptorSetLayoutBinding Structure specifying a descriptor set layout binding +[open,refpage='VkDescriptorSetLayoutBinding',desc='Structure specifying a descriptor set layout binding',type='structs'] +-- The sname:VkDescriptorSetLayoutBinding structure is defined as: @@ -676,14 +684,13 @@ include::../api/structs/VkDescriptorSetLayoutBinding.txt[] shader stages, including any additional stages defined by extensions, can: access the resource. + --- If a shader stage is not included in pname:stageFlags, then a resource must: not be accessed from that stage via this binding within any pipeline using the set layout. There are no limitations on what combinations of stages can: be used by a descriptor binding, and in particular a binding can: be used by both graphics stages and the compute stage. --- + * pname:pImmutableSamplers affects initialization of samplers. If pname:descriptorType specifies a ename:VK_DESCRIPTOR_TYPE_SAMPLER or ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then @@ -734,6 +741,7 @@ avoid wasted memory. **** include::../validity/structs/VkDescriptorSetLayoutBinding.txt[] +-- The following examples show a shader snippet using two descriptor sets, and application code that creates corresponding descriptor set layouts. @@ -802,7 +810,7 @@ layout (set=1, binding=0) uniform myUniformBuffer .API example [source,c++] -------------------------------------------------------------------------------- +--------------------------------------------------- VkResult myResult; const VkDescriptorSetLayoutBinding myDescriptorSetLayoutBinding[] = @@ -875,9 +883,10 @@ myResult = vkCreateDescriptorSetLayout( &myDescriptorSetLayoutCreateInfo[1], NULL, &myDescriptorSetLayout[1]); -------------------------------------------------------------------------------- +--------------------------------------------------- -// refBegin vkDestroyDescriptorSetLayout Destroy a descriptor set layout object +[open,refpage='vkDestroyDescriptorSetLayout',desc='Destroy a descriptor set layout object',type='protos'] +-- To destroy a descriptor set layout, call: @@ -901,12 +910,14 @@ include::../api/protos/vkDestroyDescriptorSetLayout.txt[] **** include::../validity/protos/vkDestroyDescriptorSetLayout.txt[] +-- [[descriptorsets-pipelinelayout]] === Pipeline Layouts -// refBegin VkPipelineLayout Opaque handle to a pipeline layout object +[open,refpage='VkPipelineLayout',desc='Opaque handle to a pipeline layout object',type='handles'] +-- Access to descriptor sets from a pipeline is accomplished through a _pipeline layout_. @@ -923,9 +934,10 @@ Pipeline layout objects are represented by sname:VkPipelineLayout handles: include::../api/handles/VkPipelineLayout.txt[] -// refEnd VkPipelineLayout +-- -// refBegin vkCreatePipelineLayout Creates a new pipeline layout object +[open,refpage='vkCreatePipelineLayout',desc='Creates a new pipeline layout object',type='protos'] +-- To create a pipeline layout, call: @@ -941,8 +953,10 @@ include::../api/protos/vkCreatePipelineLayout.txt[] the resulting pipeline layout object is returned. include::../validity/protos/vkCreatePipelineLayout.txt[] +-- -// refBegin VkPipelineLayoutCreateInfo Structure specifying the parameters of a newly created pipeline layout object +[open,refpage='VkPipelineLayoutCreateInfo',desc='Structure specifying the parameters of a newly created pipeline layout object',type='structs'] +-- The slink:VkPipelineLayoutCreateInfo structure is defined as: @@ -1023,8 +1037,10 @@ endif::VK_KHR_push_descriptor[] **** include::../validity/structs/VkPipelineLayoutCreateInfo.txt[] +-- -// refBegin VkPushConstantRange Structure specifying a push constant range +[open,refpage='VkPushConstantRange',desc='Structure specifying a push constant range',type='structs'] +-- The sname:VkPushConstantRange structure is defined as: @@ -1059,6 +1075,7 @@ include::../api/structs/VkPushConstantRange.txt[] **** include::../validity/structs/VkPushConstantRange.txt[] +-- Once created, pipeline layouts are used as part of pipeline creation (see <>), as part of binding descriptor sets (see @@ -1129,7 +1146,8 @@ that can: be used in any pipeline stage as described in |==== -// refBegin vkDestroyPipelineLayout Destroy a pipeline layout object +[open,refpage='vkDestroyPipelineLayout',desc='Destroy a pipeline layout object',type='protos'] +-- To destroy a pipeline layout, call: @@ -1151,6 +1169,7 @@ include::../api/protos/vkDestroyPipelineLayout.txt[] **** include::../validity/protos/vkDestroyPipelineLayout.txt[] +-- [[descriptorsets-compatibility]] @@ -1251,7 +1270,8 @@ myResult = vkCreatePipelineLayout( [[descriptorsets-allocation]] === Allocation of Descriptor Sets -// refBegin VkDescriptorPool Opaque handle to a descriptor pool object +[open,refpage='VkDescriptorPool',desc='Opaque handle to a descriptor pool object',type='handles'] +-- A _descriptor pool_ maintains a pool of descriptors, from which descriptor sets are allocated. @@ -1263,9 +1283,10 @@ Descriptor pools are represented by sname:VkDescriptorPool handles: include::../api/handles/VkDescriptorPool.txt[] -// refEnd VkDescriptorPool +-- -// refBegin vkCreateDescriptorPool Creates a descriptor pool object +[open,refpage='vkCreateDescriptorPool',desc='Creates a descriptor pool object',type='protos'] +-- To create a descriptor pool object, call: @@ -1286,8 +1307,10 @@ pname:pAllocator controls host memory allocation as described in the The created descriptor pool is returned in pname:pDescriptorPool. include::../validity/protos/vkCreateDescriptorPool.txt[] +-- -// refBegin VkDescriptorPoolCreateInfo Structure specifying parameters of a newly created descriptor pool +[open,refpage='VkDescriptorPoolCreateInfo',desc='Structure specifying parameters of a newly created descriptor pool',type='structs'] +-- Additional information about the pool is passed in an instance of the sname:VkDescriptorPoolCreateInfo structure: @@ -1339,8 +1362,10 @@ allocations. **** include::../validity/structs/VkDescriptorPoolCreateInfo.txt[] +-- -// refBegin VkDescriptorPoolCreateFlagBits Bitmask specifying certain supported operations on a descriptor pool +[open,refpage='VkDescriptorPoolCreateFlagBits',desc='Bitmask specifying certain supported operations on a descriptor pool',type='enums'] +-- Bits which can: be set in slink:VkDescriptorPoolCreateInfo::pname:flags to enable operations on a descriptor pool are: @@ -1356,9 +1381,10 @@ include::../api/enums/VkDescriptorPoolCreateFlagBits.txt[] flink:vkAllocateDescriptorSets and flink:vkResetDescriptorPool are allowed. -// refEnd VkDescriptorPoolCreateFlagBits +-- -// refBegin VkDescriptorPoolSize Structure specifying descriptor pool size +[open,refpage='VkDescriptorPoolSize',desc='Structure specifying descriptor pool size',type='structs'] +-- The sname:VkDescriptorPoolSize structure is defined as: @@ -1375,8 +1401,10 @@ include::../api/structs/VkDescriptorPoolSize.txt[] **** include::../validity/structs/VkDescriptorPoolSize.txt[] +-- -// refBegin vkDestroyDescriptorPool Destroy a descriptor pool object +[open,refpage='vkDestroyDescriptorPool',desc='Destroy a descriptor pool object',type='protos'] +-- To destroy a descriptor pool, call: @@ -1406,17 +1434,20 @@ destroying that descriptor pool. **** include::../validity/protos/vkDestroyDescriptorPool.txt[] +-- -// refBegin VkDescriptorSet Opaque handle to a descriptor set object +[open,refpage='VkDescriptorSet',desc='Opaque handle to a descriptor set object',type='handles'] +-- Descriptor sets are allocated from descriptor pool objects, and are represented by sname:VkDescriptorSet handles: include::../api/handles/VkDescriptorSet.txt[] -// refEnd VkDescriptorSet +-- -// refBegin vkAllocateDescriptorSets Allocate one or more descriptor sets +[open,refpage='vkAllocateDescriptorSets',desc='Allocate one or more descriptor sets',type='protos'] +-- To allocate descriptor sets from a descriptor pool, call: @@ -1487,8 +1518,10 @@ errors are allowed. ==== include::../validity/protos/vkAllocateDescriptorSets.txt[] +-- -// refBegin VkDescriptorSetAllocateInfo Structure specifying the allocation parameters for descriptor sets +[open,refpage='VkDescriptorSetAllocateInfo',desc='Structure specifying the allocation parameters for descriptor sets',type='structs'] +-- The sname:VkDescriptorSetAllocateInfo structure is defined as: @@ -1521,8 +1554,10 @@ endif::VK_KHR_push_descriptor[] endif::VK_KHR_maintenance1[] include::../validity/structs/VkDescriptorSetAllocateInfo.txt[] +-- -// refBegin vkFreeDescriptorSets Free one or more descriptor sets +[open,refpage='vkFreeDescriptorSets',desc='Free one or more descriptor sets',type='protos'] +-- To free allocated descriptor sets, call: @@ -1557,8 +1592,10 @@ in pname:pDescriptorSets are invalid. **** include::../validity/protos/vkFreeDescriptorSets.txt[] +-- -// refBegin vkResetDescriptorPool Resets a descriptor pool object +[open,refpage='vkResetDescriptorPool',desc='Resets a descriptor pool object',type='protos'] +-- To return all descriptor sets allocated from a given pool to the pool, rather than freeing individual descriptor sets, call: @@ -1581,12 +1618,14 @@ pool, and the descriptor sets are implicitly freed. **** include::../validity/protos/vkResetDescriptorPool.txt[] +-- [[descriptorsets-updates]] === Descriptor Set Updates -// refBegin vkUpdateDescriptorSets Update the contents of a descriptor set object +[open,refpage='vkUpdateDescriptorSets',desc='Update the contents of a descriptor set object',type='protos'] +-- Once allocated, descriptor sets can: be updated with a combination of write and copy operations. @@ -1635,8 +1674,10 @@ buffer becomes <>. **** include::../validity/protos/vkUpdateDescriptorSets.txt[] +-- -// refBegin VkWriteDescriptorSet Structure specifying the parameters of a descriptor set write operation +[open,refpage='VkWriteDescriptorSet',desc='Structure specifying the parameters of a descriptor set write operation',type='structs'] +-- The sname:VkWriteDescriptorSet structure is defined as: @@ -1741,6 +1782,11 @@ bindings as needed to update all pname:descriptorCount descriptors. ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView and pname:imageLayout members of any given element of pname:pImageInfo must: be a valid sname:VkImageView and elink:VkImageLayout, respectively + * [[VUID-VkWriteDescriptorSet-descriptorType-01402]] + If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, for + each descriptor that will be accessed via load or store operations the + pname:imageLayout member for corresponding elements of pname:pImageInfo + must: be ename:VK_IMAGE_LAYOUT_GENERAL * [[VUID-VkWriteDescriptorSet-descriptorType-00327]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:offset member @@ -1801,6 +1847,13 @@ bindings as needed to update all pname:descriptorCount descriptors. ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageView member of any given element of pname:pImageInfo must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT set + * [[VUID-VkWriteDescriptorSet-descriptorType-01403]] + If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or + ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageLayout + member of any given element of pname:pImageInfo must: be + ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, + ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or + ename:VK_IMAGE_LAYOUT_GENERAL * [[VUID-VkWriteDescriptorSet-descriptorType-00338]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of any given element of pname:pImageInfo @@ -1813,8 +1866,10 @@ bindings as needed to update all pname:descriptorCount descriptors. **** include::../validity/structs/VkWriteDescriptorSet.txt[] +-- -// refBegin VkDescriptorType Specifies the type of a descriptor in a descriptor set +[open,refpage='VkDescriptorType',desc='Specifies the type of a descriptor in a descriptor set',type='enums'] +-- The type of descriptors in a descriptor set is specified by slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the @@ -1842,9 +1897,10 @@ include::../api/enums/VkDescriptorType.txt[] slink:VkDescriptorImageInfo structures will be used to update the descriptors, and other arrays will be ignored. -// refEnd VkDescriptorType +-- -// refBegin VkDescriptorBufferInfo Structure specifying descriptor buffer info +[open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer info',type='structs'] +-- The sname:VkDescriptorBufferInfo structure is defined as: @@ -1857,13 +1913,12 @@ include::../api/structs/VkDescriptorBufferInfo.txt[] * pname:range is the size in bytes that is used for this descriptor update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the end of the buffer. -+ --- + [NOTE] .Note ==== -When using ename:VK_WHOLE_SIZE, the effective range must: not be larger than -the maximum range for the descriptor type +When setting pname:range to ename:VK_WHOLE_SIZE, the effective range must: +not be larger than the maximum range for the descriptor type (<> or <>). This means that ename:VK_WHOLE_SIZE is not typically useful in the common @@ -1875,7 +1930,6 @@ For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, pname:offset is the base offset from which the dynamic offset is applied and pname:range is the static size used for all dynamic offsets. --- .Valid Usage **** @@ -1890,8 +1944,10 @@ pname:range is the static size used for all dynamic offsets. **** include::../validity/structs/VkDescriptorBufferInfo.txt[] +-- -// refBegin VkDescriptorImageInfo Structure specifying descriptor image info +[open,refpage='VkDescriptorImageInfo',desc='Structure specifying descriptor image info',type='structs'] +-- The sname:VkDescriptorImageInfo structure is defined as: @@ -1932,8 +1988,10 @@ endif::VK_KHR_maintenance1[] include::../validity/structs/VkDescriptorImageInfo.txt[] +-- -// refBegin VkCopyDescriptorSet Structure specifying a copy descriptor set operation +[open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] +-- The sname:VkCopyDescriptorSet structure is defined as: @@ -1975,13 +2033,15 @@ include::../api/structs/VkCopyDescriptorSet.txt[] **** include::../validity/structs/VkCopyDescriptorSet.txt[] +-- ifdef::VK_KHR_descriptor_update_template[] [[descriptorsets-updates-with-template]] === Descriptor Update Templates -// refBegin VkDescriptorUpdateTemplateKHR Opaque handle to a descriptor update template +[open,refpage='VkDescriptorUpdateTemplateKHR',desc='Opaque handle to a descriptor update template',type='handles'] +-- A descriptor update template specifies a mapping from descriptor update information in host memory to descriptors in a descriptor set. @@ -1993,11 +2053,12 @@ sname:VkDescriptorUpdateTemplateKHR handles: include::../api/handles/VkDescriptorUpdateTemplateKHR.txt[] -// refEnd VkDescriptorUpdateTemplateKHR +-- === Descriptor Set Updates with Templates -// refBegin vkCreateDescriptorUpdateTemplateKHR Create a new descriptor update template +[open,refpage='vkCreateDescriptorUpdateTemplateKHR',desc='Create a new descriptor update template',type='protos'] +-- Updating a large sname:VkDescriptorSet array can: be an expensive operation since an application must: specify one slink:VkWriteDescriptorSet structure @@ -2053,9 +2114,10 @@ endif::VK_KHR_push_descriptor[] include::../validity/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] -// refEnd vkCreateDescriptorUpdateTemplateKHR +-- -// refBegin VkDescriptorUpdateTemplateCreateInfoKHR Structure specifying parameters of a newly created descriptor update template +[open,refpage='VkDescriptorUpdateTemplateCreateInfoKHR',desc='Structure specifying parameters of a newly created descriptor update template',type='structs'] +-- The slink:VkDescriptorUpdateTemplateCreateInfoKHR structure is defined as: include::../api/structs/VkDescriptorUpdateTemplateCreateInfoKHR.txt[] @@ -2137,9 +2199,10 @@ endif::VK_KHR_push_descriptor[] include::../validity/structs/VkDescriptorUpdateTemplateCreateInfoKHR.txt[] -// refEnd VkDescriptorUpdateTemplateCreateInfoKHR +-- -// refBegin VkDescriptorUpdateTemplateTypeKHR Indicates the valid usage of the descriptor update template +[open,refpage='VkDescriptorUpdateTemplateTypeKHR',desc='Indicates the valid usage of the descriptor update template',type='enums'] +-- The descriptor update template type is determined by the slink:VkDescriptorUpdateTemplateCreateInfoKHR::pname:templateType property, @@ -2156,10 +2219,11 @@ ifdef::VK_KHR_push_descriptor[] updates only. endif::VK_KHR_push_descriptor[] -// refEnd VkDescriptorUpdateTemplateTypeKHR +-- -// refBegin VkDescriptorUpdateTemplateEntryKHR Describes a single descriptor update of the descriptor update template +[open,refpage='VkDescriptorUpdateTemplateEntryKHR',desc='Describes a single descriptor update of the descriptor update template',type='structs'] +-- The sname:VkDescriptorUpdateTemplateEntryKHR structure is defined as: include::../api/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] @@ -2204,9 +2268,10 @@ include::../api/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] include::../validity/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] -// refEnd VkDescriptorUpdateTemplateEntryKHR +-- -// refBegin vkDestroyDescriptorUpdateTemplateKHR Destroy a descriptor update template object +[open,refpage='vkDestroyDescriptorUpdateTemplateKHR',desc='Destroy a descriptor update template object',type='protos'] +-- To destroy a descriptor update template, call: @@ -2232,9 +2297,10 @@ include::../api/protos/vkDestroyDescriptorUpdateTemplateKHR.txt[] include::../validity/protos/vkDestroyDescriptorUpdateTemplateKHR.txt[] -// refEnd vkDestroyDescriptorUpdateTemplateKHR +-- -// refBegin vkUpdateDescriptorSetWithTemplateKHR Update the contents of a descriptor set object using an update template +[open,refpage='vkUpdateDescriptorSetWithTemplateKHR',desc='Update the contents of a descriptor set object using an update template',type='protos'] +-- Once a sname:VkDescriptorUpdateTemplateKHR has been created, descriptor sets can: be updated by calling: @@ -2332,7 +2398,7 @@ AppDataStructure appData; vkUpdateDescriptorSetWithTemplateKHR(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData); --------------------------------------------------- -// refEnd vkUpdateDescriptorSetWithTemplateKHR +-- endif::VK_KHR_descriptor_update_template[] @@ -2340,7 +2406,8 @@ endif::VK_KHR_descriptor_update_template[] [[descriptorsets-binding]] === Descriptor Set Binding -// refBegin vkCmdBindDescriptorSets Binds descriptor sets to a command buffer +[open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] +-- To bind one or more descriptor sets to a command buffer, call: @@ -2444,13 +2511,15 @@ descriptor set. **** include::../validity/protos/vkCmdBindDescriptorSets.txt[] +-- ifdef::VK_KHR_push_descriptor[] [[descriptorsets-push-descriptors]] === Push Descriptor Updates -// refBegin vkCmdPushDescriptorSetKHR Pushes descriptor updates into a command buffer +[open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] +-- In addition to allocating descriptor sets and binding them to a command buffer, an application can: record descriptor updates into the command @@ -2538,12 +2607,13 @@ the pipeline layout. include::../validity/protos/vkCmdPushDescriptorSetKHR.txt[] -// refEnd vkCmdPushDescriptorSetKHR +-- ifdef::VK_KHR_descriptor_update_template[] === Push Descriptor Updates with Descriptor Update Templates -// refBegin vkCmdPushDescriptorSetWithTemplateKHR Pushes descriptor updates into a command buffer using a descriptor update template +[open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] +-- It is also possible to use a descriptor update template to specify the push descriptors to update. @@ -2633,7 +2703,7 @@ AppDataStructure appData; vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); --------------------------------------------------- -// refEnd vkCmdPushDescriptorSetWithTemplateKHR +-- endif::VK_KHR_descriptor_update_template[] endif::VK_KHR_push_descriptor[] @@ -2657,7 +2727,8 @@ pipelines that is expected to outperform memory-backed resource updates. The values of push constants are undefined at the start of a command buffer. -// refBegin vkCmdPushConstants Update the values of push constants +[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] +-- To update push constants, call: @@ -2695,3 +2766,4 @@ include::../api/protos/vkCmdPushConstants.txt[] **** include::../validity/protos/vkCmdPushConstants.txt[] +-- diff --git a/doc/specs/vulkan/chapters/devsandqueues.txt b/doc/specs/vulkan/chapters/devsandqueues.txt index d37a1e32..5e9c39ce 100644 --- a/doc/specs/vulkan/chapters/devsandqueues.txt +++ b/doc/specs/vulkan/chapters/devsandqueues.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[devsandqueues]] = Devices and Queues @@ -7,7 +8,8 @@ Once Vulkan is initialized, devices and queues are the primary objects used to interact with a Vulkan implementation. -// refBegin VkPhysicalDevice Opaque handle to a physical device object +[open,refpage='VkPhysicalDevice',desc='Opaque handle to a physical device object',type='handles'] +-- Vulkan separates the concept of _physical_ and _logical_ devices. A physical device usually represents a single device in a system (perhaps @@ -19,13 +21,14 @@ Physical devices are represented by sname:VkPhysicalDevice handles: include::../api/handles/VkPhysicalDevice.txt[] -// refEnd VkPhysicalDevice +-- [[devsandqueues-physical-device-enumeration]] == Physical Devices -// refBegin vkEnumeratePhysicalDevices Enumerates the physical devices accessible to a Vulkan instance +[open,refpage='vkEnumeratePhysicalDevices',desc='Enumerates the physical devices accessible to a Vulkan instance',type='protos'] +-- To retrieve a list of physical device objects representing the physical devices installed in the system, call: @@ -52,8 +55,10 @@ available, ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to indicate that not all the available physical devices were returned. include::../validity/protos/vkEnumeratePhysicalDevices.txt[] +-- -// refBegin vkGetPhysicalDeviceProperties Returns properties of a physical device +[open,refpage='vkGetPhysicalDeviceProperties',desc='Returns properties of a physical device',type='protos'] +-- To query general properties of physical devices once enumerated, call: @@ -66,8 +71,10 @@ include::../api/protos/vkGetPhysicalDeviceProperties.txt[] returned information. include::../validity/protos/vkGetPhysicalDeviceProperties.txt[] +-- -// refBegin VkPhysicalDeviceProperties Structure specifying physical device properties +[open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs'] +-- The sname:VkPhysicalDeviceProperties structure is defined as: @@ -139,8 +146,10 @@ following constraints and guidelines: in different SoCs. include::../validity/structs/VkPhysicalDeviceProperties.txt[] +-- -// refBegin VkPhysicalDeviceType Supported physical device types +[open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums'] +-- The physical device types which may: be returned in slink:VkPhysicalDeviceProperties::pname:deviceType are: @@ -163,11 +172,12 @@ does not directly affect the operation of the system. However, the device type may: correlate with other advertised properties or capabilities of the system, such as how many memory heaps there are. -// refEnd VkPhysicalDeviceType +-- ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceProperties2KHR Returns properties of a physical device +[open,refpage='vkGetPhysicalDeviceProperties2KHR',desc='Returns properties of a physical device',type='protos'] +-- To query general properties of physical devices once enumerated, call: @@ -185,8 +195,10 @@ fname:vkGetPhysicalDeviceProperties2KHR writes each member to a value indicating the value of that property or limit. include::../validity/protos/vkGetPhysicalDeviceProperties2KHR.txt[] +-- -// refBegin VkPhysicalDeviceProperties2KHR Structure specifying physical device properties +[open,refpage='VkPhysicalDeviceProperties2KHR',desc='Structure specifying physical device properties',type='structs'] +-- The sname:VkPhysicalDeviceProperties2KHR structure is defined as: @@ -203,10 +215,12 @@ The pname:pNext chain of this structure is used to extend the structure with properties defined by extensions. include::../validity/structs/VkPhysicalDeviceProperties2KHR.txt[] +-- ifdef::VK_KHX_external_memory_capabilities,VK_KHX_external_semaphore_capabilities[] -// refBegin VkPhysicalDeviceIDPropertiesKHX Structure specifying IDs related to the physical device +[open,refpage='VkPhysicalDeviceIDPropertiesKHX',desc='Structure specifying IDs related to the physical device',type='structs'] +-- To query the UUID and LUID of a device, add slink:VkPhysicalDeviceIDPropertiesKHX to the pname:pNext chain of the @@ -258,12 +272,14 @@ state. ==== include::../validity/structs/VkPhysicalDeviceIDPropertiesKHX.txt[] +-- endif::VK_KHX_external_memory_capabilities,VK_KHX_external_semaphore_capabilities[] endif::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceQueueFamilyProperties Reports properties of the queues of the specified physical device +[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] +-- To query properties of queues available on a physical device, call: @@ -287,8 +303,10 @@ available, at most pname:pQueueFamilyPropertyCount structures will be written. include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] +-- -// refBegin VkQueueFamilyProperties Structure providing information about a queue family +[open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs'] +-- The sname:VkQueueFamilyProperties structure is defined as: @@ -364,8 +382,10 @@ queried from the physical device. For physical device feature queries see the <> chapter. include::../validity/structs/VkQueueFamilyProperties.txt[] +-- -// refBegin VkQueueFlagBits Bitmask specifying capabilities of queues in a queue family +[open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums'] +-- Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags indicating capabilities of queues in a queue family are: @@ -403,11 +423,12 @@ is optional:. For further details see <>. -// refEnd VkQueueFlagBits +-- ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceQueueFamilyProperties2KHR Reports properties of the queues of the specified physical device +[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2KHR',desc='Reports properties of the queues of the specified physical device',type='protos'] +-- To query properties of queues available on a physical device, call: @@ -426,8 +447,10 @@ flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return extended information in a pname:pNext chain of output structures. include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[] +-- -// refBegin VkQueueFamilyProperties2KHR Structure providing information about a queue family +[open,refpage='VkQueueFamilyProperties2KHR',desc='Structure providing information about a queue family',type='structs'] +-- The sname:VkQueueFamilyProperties2KHR structure is defined as: @@ -440,6 +463,7 @@ include::../api/structs/VkQueueFamilyProperties2KHR.txt[] in flink:vkGetPhysicalDeviceQueueFamilyProperties. include::../validity/structs/VkQueueFamilyProperties2KHR.txt[] +-- endif::VK_KHR_get_physical_device_properties2[] @@ -481,7 +505,8 @@ flink:vkEnumeratePhysicalDeviceGroupsKHX, and a logical device is created from a subset of the physical devices in a device group by passing the physical devices through slink:VkDeviceGroupDeviceCreateInfoKHX. -// refBegin vkEnumeratePhysicalDeviceGroupsKHX Enumerates groups of physical devices that can be used to create a single logical device +[open,refpage='vkEnumeratePhysicalDeviceGroupsKHX',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] +-- To retrieve a list of the device groups present in the system, call: @@ -512,8 +537,10 @@ returned. Every physical device must: be in exactly one device group. include::../validity/protos/vkEnumeratePhysicalDeviceGroupsKHX.txt[] +-- -// refBegin VkPhysicalDeviceGroupPropertiesKHX Structure specifying physical device group properties +[open,refpage='VkPhysicalDeviceGroupPropertiesKHX',desc='Structure specifying physical device group properties',type='structs'] +-- The sname:VkPhysicalDeviceGroupPropertiesKHX structure is defined as: @@ -534,7 +561,7 @@ include::../api/structs/VkPhysicalDeviceGroupPropertiesKHX.txt[] If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must: be ename:VK_FALSE. -// refEnd VkPhysicalDeviceGroupPropertiesKHX +-- endif::VK_KHX_device_group_creation[] @@ -542,15 +569,17 @@ endif::VK_KHX_device_group_creation[] [[devsandqueues-device-creation]] === Device Creation -// refBegin VkDevice Opaque handle to a device object +[open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles'] +-- Logical devices are represented by sname:VkDevice handles: include::../api/handles/VkDevice.txt[] -// refEnd VkDevice +-- -// refBegin vkCreateDevice Create a new device instance +[open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos'] +-- A logical device is created as a _connection_ to a physical device. To create a logical device, call: @@ -602,8 +631,10 @@ ename:VK_ERROR_TOO_MANY_OBJECTS. **** include::../validity/protos/vkCreateDevice.txt[] +-- -// refBegin VkDeviceCreateInfo Structure specifying parameters of a newly created device +[open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs'] +-- The sname:VkDeviceCreateInfo structure is defined as: @@ -657,10 +688,12 @@ endif::VK_KHR_maintenance1[] **** include::../validity/structs/VkDeviceCreateInfo.txt[] +-- ifdef::VK_KHX_device_group_creation[] -// refBegin VkDeviceGroupDeviceCreateInfoKHX Create a logical device from multiple physical devices +[open,refpage='VkDeviceGroupDeviceCreateInfoKHX',desc='Create a logical device from multiple physical devices',type='structs'] +-- A logical device can: be created that connects to one or more physical devices by including a sname:VkDeviceGroupDeviceCreateInfoKHX structure in @@ -708,7 +741,7 @@ In particular, the device index of that physical device is zero. include::../validity/structs/VkDeviceGroupDeviceCreateInfoKHX.txt[] -// refEnd VkDeviceGroupDeviceCreateInfoKHX +-- endif::VK_KHX_device_group_creation[] @@ -825,7 +858,8 @@ endif::editing-notes[] [[devsandqueues-destruction]] === Device Destruction -// refBegin vkDestroyDevice Destroy a logical device +[open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] +-- To destroy a device, call: @@ -866,6 +900,7 @@ fname:vkDestroyDevice. **** include::../validity/protos/vkDestroyDevice.txt[] +-- [[devsandqueues-queues]] @@ -910,7 +945,8 @@ This is described in the following section. [[devsandqueues-queue-creation]] === Queue Creation -// refBegin VkQueue Opaque handle to a queue object +[open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] +-- Creating a logical device also creates the queues associated with that device. @@ -922,9 +958,10 @@ Queues are represented by sname:VkQueue handles: include::../api/handles/VkQueue.txt[] -// refEnd VkQueue +-- -// refBegin VkDeviceQueueCreateInfo Structure specifying parameters of a newly created device queue +[open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs'] +-- The sname:VkDeviceQueueCreateInfo structure is defined as: @@ -962,8 +999,10 @@ include::../api/structs/VkDeviceQueueCreateInfo.txt[] **** include::../validity/structs/VkDeviceQueueCreateInfo.txt[] +-- -// refBegin vkGetDeviceQueue Get a queue handle from a device +[open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos'] +-- To retrieve a handle to a VkQueue object, call: @@ -990,6 +1029,7 @@ include::../api/protos/vkGetDeviceQueue.txt[] **** include::../validity/protos/vkGetDeviceQueue.txt[] +-- [[devsandqueues-index]] diff --git a/doc/specs/vulkan/chapters/dispatch.txt b/doc/specs/vulkan/chapters/dispatch.txt index 37fcf7ca..772ec519 100644 --- a/doc/specs/vulkan/chapters/dispatch.txt +++ b/doc/specs/vulkan/chapters/dispatch.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[dispatch]] = Dispatching Commands @@ -12,7 +13,8 @@ compute pipeline. A compute pipeline must: be bound to a command buffer before any dispatch commands are recorded in that command buffer. -// refBegin vkCmdDispatch Dispatch compute work items +[open,refpage='vkCmdDispatch',desc='Dispatch compute work items',type='protos'] +-- To record a dispatch, call: @@ -126,8 +128,10 @@ endif::VK_IMG_filter_cubic[] **** include::../validity/protos/vkCmdDispatch.txt[] +-- -// refBegin vkCmdDispatchIndirect Dispatch compute work items using indirect parameters +[open,refpage='vkCmdDispatchIndirect',desc='Dispatch compute work items using indirect parameters',type='protos'] +-- To record an indirect command dispatch, call: @@ -242,8 +246,10 @@ endif::VK_IMG_filter_cubic[] **** include::../validity/protos/vkCmdDispatchIndirect.txt[] +-- -// refBegin VkDispatchIndirectCommand Structure specifying a dispatch indirect command +[open,refpage='VkDispatchIndirectCommand',desc='Structure specifying a dispatch indirect command',type='structs',xrefs='vkCmdDispatchIndirect'] +-- The sname:VkDispatchIndirectCommand structure is defined as: @@ -274,11 +280,12 @@ corresponding parameters of flink:vkCmdDispatch. include::../validity/structs/VkDispatchIndirectCommand.txt[] -// refEnd VkDispatchIndirectCommand vkCmdDispatchIndirect +-- ifdef::VK_KHX_device_group[] -// refBegin vkCmdDispatchBaseKHX Dispatch compute work items +[open,refpage='vkCmdDispatchBaseKHX',desc='Dispatch compute work items',type='protos'] +-- To record a dispatch using non-zero base values for the components of code:WorkgroupId, call: @@ -339,5 +346,6 @@ vkCmdDispatchBaseKHX(0,0,0,groupCountX,groupCountY,groupCountZ). **** include::../validity/protos/vkCmdDispatchBaseKHX.txt[] +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/drawing.txt b/doc/specs/vulkan/chapters/drawing.txt index a56c7b24..9cc918e1 100644 --- a/doc/specs/vulkan/chapters/drawing.txt +++ b/doc/specs/vulkan/chapters/drawing.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[drawing]] = Drawing Commands @@ -12,7 +13,8 @@ graphics pipeline. A graphics pipeline must: be bound to a command buffer before any drawing commands are recorded in that command buffer. -// refBegin VkPipelineInputAssemblyStateCreateInfo Structure specifying parameters of a newly created pipeline input assembly state +[open,refpage='VkPipelineInputAssemblyStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline input assembly state',type='structs'] +-- Each draw is made up of zero or more vertices and zero or more instances, which are processed by the device and result in the assembly of primitives. @@ -67,12 +69,14 @@ pname:vertexOffset value to the index value. **** include::../validity/structs/VkPipelineInputAssemblyStateCreateInfo.txt[] +-- [[drawing-primitive-topologies]] == Primitive Topologies -// refBegin VkPrimitiveTopology Supported primitive topologies +[open,refpage='VkPrimitiveTopology',desc='Supported primitive topologies',type='enums'] +-- _Primitive topology_ determines how consecutive vertices are organized into primitives, and determines the type of primitive that is used at the @@ -84,7 +88,7 @@ Supported topologies are defined by elink:VkPrimitiveTopology and include: include::../api/enums/VkPrimitiveTopology.txt[] -// refEnd VkPrimitiveTopology +-- Each primitive topology, and its construction from a list of vertices, is summarized below. @@ -394,8 +398,12 @@ Within this order implementations further sort primitives: . If geometry shading is active, by the order new primitives are generated by <>. . If the <> is not - ename:VK_POLYGON_MODE_FILL, by an implementation-dependent ordering of - the new primitives generated within the original primitive. + ename:VK_POLYGON_MODE_FILL, +ifdef::VK_NV_fill_rectangle[] + or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV, +endif::VK_NV_fill_rectangle[] + by an implementation-dependent ordering of the new primitives generated + within the original primitive. Primitive order is later used to define <>, which determines the order in which fragments output results to a @@ -442,7 +450,8 @@ ifdef::VK_AMD_draw_indirect_count[] endif::VK_AMD_draw_indirect_count[] -// refBegin vkCmdBindIndexBuffer Bind an index buffer to a command buffer +[open,refpage='vkCmdBindIndexBuffer',desc='Bind an index buffer to a command buffer',type='protos'] +-- To bind an index buffer to a command buffer, call: @@ -473,9 +482,11 @@ include::../api/protos/vkCmdBindIndexBuffer.txt[] **** include::../validity/protos/vkCmdBindIndexBuffer.txt[] +-- -// refBegin VkIndexType Type of index buffer indices +[open,refpage='VkIndexType',desc='Type of index buffer indices',type='enums'] +-- Possible values of flink:vkCmdBindIndexBuffer::pname:indexType, specifying the size of indices, are: @@ -487,7 +498,7 @@ include::../api/enums/VkIndexType.txt[] * ename:VK_INDEX_TYPE_UINT32 specifies that indices are 32-bit unsigned integer values. -// refEnd VkIndexType Type of index buffer indices +-- The parameters for each drawing command are specified directly in the command or read from buffer memory, depending on the command. @@ -497,7 +508,8 @@ as _indirect_ drawing commands. All drawing commands interact with the <> feature. -// refBegin vkCmdDraw Draw primitives +[open,refpage='vkCmdDraw',desc='Draw primitives',type='protos'] +-- To record a non-indexed draw, call: @@ -639,8 +651,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdDraw.txt[] +-- -// refBegin vkCmdDrawIndexed Issue an indexed draw into a command buffer +[open,refpage='vkCmdDrawIndexed',desc='Issue an indexed draw into a command buffer',type='protos'] +-- To record an indexed draw, call: @@ -805,8 +819,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdDrawIndexed.txt[] +-- -// refBegin vkCmdDrawIndirect Issue an indirect draw into a command buffer +[open,refpage='vkCmdDrawIndirect',desc='Issue an indirect draw into a command buffer',type='protos'] +-- To record a non-indexed indirect draw, call: @@ -977,8 +993,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdDrawIndirect.txt[] +-- -// refBegin VkDrawIndirectCommand Structure specifying a draw indirect command +[open,refpage='VkDrawIndirectCommand',desc='Structure specifying a draw indirect command',type='structs',xrefs='vkCmdDrawIndirect'] +-- The sname:VkDrawIndirectCommand structure is defined as: @@ -1006,10 +1024,11 @@ similarly named parameters of flink:vkCmdDraw. include::../validity/structs/VkDrawIndirectCommand.txt[] -// refEnd VkDrawIndirectCommand vkCmdDrawIndirect +-- ifdef::VK_AMD_draw_indirect_count[] -// refBegin vkCmdDrawIndirectCountAMD Perform an indirect draw with the draw count sourced from a buffer +[open,refpage='vkCmdDrawIndirectCountAMD',desc='Perform an indirect draw with the draw count sourced from a buffer',type='protos'] +-- To record a non-indexed draw call with a draw call count sourced from a buffer, call: @@ -1169,10 +1188,11 @@ endif::VK_KHX_multiview[] include::../validity/protos/vkCmdDrawIndirectCountAMD.txt[] -// refEnd vkCmdDrawIndirectCountAMD +-- endif::VK_AMD_draw_indirect_count[] -// refBegin vkCmdDrawIndexedIndirect Perform an indexed indirect draw +[open,refpage='vkCmdDrawIndexedIndirect',desc='Perform an indexed indirect draw',type='protos'] +-- To record an indexed indirect draw, call: @@ -1344,8 +1364,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdDrawIndexedIndirect.txt[] +-- -// refBegin VkDrawIndexedIndirectCommand Structure specifying a draw indexed indirect command +[open,refpage='VkDrawIndexedIndirectCommand',desc='Structure specifying a draw indexed indirect command',type='structs',xrefs='vkCmdDrawIndexedIndirect'] +-- The sname:VkDrawIndexedIndirectCommand structure is defined as: @@ -1382,10 +1404,11 @@ the similarly named parameters of flink:vkCmdDrawIndexed. include::../validity/structs/VkDrawIndexedIndirectCommand.txt[] -// refEnd VkDrawIndexedIndirectCommand vkCmdDrawIndexedIndirect +-- ifdef::VK_AMD_draw_indirect_count[] -// refBegin vkCmdDrawIndexedIndirectCountAMD Perform an indexed indirect draw with the draw count sourced from a buffer +[open,refpage='vkCmdDrawIndexedIndirectCountAMD',desc='Perform an indexed indirect draw with the draw count sourced from a buffer',type='protos'] +-- To record an indexed draw call with a draw call count sourced from a buffer, call: @@ -1545,5 +1568,5 @@ endif::VK_KHX_multiview[] include::../validity/protos/vkCmdDrawIndexedIndirectCountAMD.txt[] -// refEnd vkCmdDrawIndexedIndirectCountAMD +-- endif::VK_AMD_draw_indirect_count[] diff --git a/doc/specs/vulkan/chapters/extensions.txt b/doc/specs/vulkan/chapters/extensions.txt index 24af662d..ca1609c6 100644 --- a/doc/specs/vulkan/chapters/extensions.txt +++ b/doc/specs/vulkan/chapters/extensions.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[extended-functionality]] = Extended Functionality @@ -50,7 +51,8 @@ destruction of each object. See the <> document for additional information. -// refBegin vkEnumerateInstanceLayerProperties Returns up to requested number of global layer properties +[open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos'] +-- To query the available layers, call: @@ -83,8 +85,10 @@ continue to be enabled and valid for the lifetime of that instance, even if some of them become unavailable for future instances. include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[] +-- -// refBegin VkLayerProperties Structure specifying layer properties +[open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs'] +-- The sname:VkLayerProperties structure is defined as: @@ -104,6 +108,7 @@ include::../api/structs/VkLayerProperties.txt[] details that can: be used by the application to identify the layer. include::../validity/structs/VkLayerProperties.txt[] +-- To enable a layer, the name of the layer should: be added to the pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating @@ -147,7 +152,8 @@ the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo maximizes compatibility with applications written to work with the previous requirements. -// refBegin vkEnumerateDeviceLayerProperties Returns properties of available physical device layers +[open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos'] +-- To enumerate device layers, call: @@ -177,6 +183,7 @@ the same as the properties when the layer was enumerated by fname:vkEnumerateInstanceLayerProperties. include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[] +-- The pname:ppEnabledLayerNames and pname:enabledLayerCount members of sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by @@ -211,7 +218,8 @@ wrapped by the validation layers. See the <> document for additional information. -// refBegin vkEnumerateInstanceExtensionProperties Returns up to requested number of global extension properties +[open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos'] +-- To query the available instance extensions, call: @@ -250,6 +258,7 @@ if the layer implementation is replaced by a different version between those calls. include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[] +-- To enable an instance extension, the name of the extension should: be added to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo @@ -259,7 +268,8 @@ Enabling an extension does not change behavior of functionality exposed by the core Vulkan API or any other extension, other than making valid the use of the commands, enums and structures defined by that extension. -// refBegin vkEnumerateDeviceExtensionProperties Returns properties of available physical device extensions +[open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos'] +-- To query the extensions available to a given physical device, call: @@ -282,8 +292,10 @@ When pname:pLayerName is the name of a layer, the device extensions provided by that layer are returned. include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[] +-- -// refBegin VkExtensionProperties Structure specifying a extension properties +[open,refpage='VkExtensionProperties',desc='Structure specifying a extension properties',type='structs'] +-- The sname:VkExtensionProperties structure is defined as: @@ -295,6 +307,7 @@ include::../api/structs/VkExtensionProperties.txt[] It is an integer, incremented with backward compatible changes. include::../validity/structs/VkExtensionProperties.txt[] +-- [[extended-functionality-instance-extensions-and-devices]] diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt index 74ec7492..33dc4465 100644 --- a/doc/specs/vulkan/chapters/features.txt +++ b/doc/specs/vulkan/chapters/features.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[features]] = Features, Limits, and Formats @@ -40,7 +41,8 @@ required:, but may: be supported by a Vulkan implementation. Support for features is reported and enabled on a per-feature basis. Features are properties of the physical device. -// refBegin vkGetPhysicalDeviceFeatures Reports capabilities of a physical device +[open,refpage='vkGetPhysicalDeviceFeatures',desc='Reports capabilities of a physical device',type='protos'] +-- To query supported features, call: @@ -55,6 +57,7 @@ include::../api/protos/vkGetPhysicalDeviceFeatures.txt[] feature is not supported. include::../validity/protos/vkGetPhysicalDeviceFeatures.txt[] +-- Fine-grained features used by a logical device must: be enabled at sname:VkDevice creation time. @@ -99,7 +102,8 @@ all supported features. ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceFeatures2KHR Reports capabilities of a physical device +[open,refpage='vkGetPhysicalDeviceFeatures2KHR',desc='Reports capabilities of a physical device',type='protos'] +-- To query supported features defined by the core or extensions, call: @@ -116,8 +120,10 @@ fname:vkGetPhysicalDeviceFeatures2KHR writes each member to a boolean value indicating whether that feature is supported. include::../validity/protos/vkGetPhysicalDeviceFeatures2KHR.txt[] +-- -// refBegin VkPhysicalDeviceFeatures2KHR Structure describing the fine-grained features that can be supported by an implementation +[open,refpage='VkPhysicalDeviceFeatures2KHR',desc='Structure describing the fine-grained features that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceFeatures2KHR structure is defined as: @@ -138,10 +144,12 @@ which case it controls which features are enabled in the device in lieu of pname:pEnabledFeatures. include::../validity/structs/VkPhysicalDeviceFeatures2KHR.txt[] +-- endif::VK_KHR_get_physical_device_properties2[] -// refBegin VkPhysicalDeviceFeatures Structure describing the fine-grained features that can be supported by an implementation +[open,refpage='VkPhysicalDeviceFeatures',desc='Structure describing the fine-grained features that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceFeatures structure is defined as: @@ -166,7 +174,6 @@ following features: *** The pointer was not formed by code:OpImageTexelPointer and the object pointed to is not wholly contained within the bound range. + --- [NOTE] .Note ==== @@ -175,7 +182,7 @@ 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 @@ -369,22 +376,21 @@ used. ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT features must: be supported in pname:optimalTilingFeatures for the following formats: + --- - * ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK - * ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK - * ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK - * ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK - * ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK - * ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK - * ename:VK_FORMAT_EAC_R11_UNORM_BLOCK - * ename:VK_FORMAT_EAC_R11_SNORM_BLOCK - * ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK - * ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK - + ** ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK + ** ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK + ** ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK + ** ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK + ** ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK + ** ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK + ** ename:VK_FORMAT_EAC_R11_UNORM_BLOCK + ** ename:VK_FORMAT_EAC_R11_SNORM_BLOCK + ** ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK + ** ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK ++ flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for additional supported properties of individual formats. --- + * [[features-features-textureCompressionASTC_LDR]] pname:textureCompressionASTC_LDR indicates whether all of the ASTC LDR compressed texture formats are supported. @@ -394,40 +400,39 @@ additional supported properties of individual formats. ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT features must: be supported in pname:optimalTilingFeatures for the following formats: + --- - * ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK - * ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK - * ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK - + ** ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK + ** ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK + ** ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK ++ flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for additional supported properties of individual formats. --- + * [[features-features-textureCompressionBC]] pname:textureCompressionBC indicates whether all of the BC compressed texture formats are supported. @@ -437,28 +442,27 @@ additional supported properties of individual formats. ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT features must: be supported in pname:optimalTilingFeatures for the following formats: + --- - * ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK - * ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK - * ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK - * ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK - * ename:VK_FORMAT_BC2_UNORM_BLOCK - * ename:VK_FORMAT_BC2_SRGB_BLOCK - * ename:VK_FORMAT_BC3_UNORM_BLOCK - * ename:VK_FORMAT_BC3_SRGB_BLOCK - * ename:VK_FORMAT_BC4_UNORM_BLOCK - * ename:VK_FORMAT_BC4_SNORM_BLOCK - * ename:VK_FORMAT_BC5_UNORM_BLOCK - * ename:VK_FORMAT_BC5_SNORM_BLOCK - * ename:VK_FORMAT_BC6H_UFLOAT_BLOCK - * ename:VK_FORMAT_BC6H_SFLOAT_BLOCK - * ename:VK_FORMAT_BC7_UNORM_BLOCK - * ename:VK_FORMAT_BC7_SRGB_BLOCK - + ** ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK + ** ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK + ** ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK + ** ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK + ** ename:VK_FORMAT_BC2_UNORM_BLOCK + ** ename:VK_FORMAT_BC2_SRGB_BLOCK + ** ename:VK_FORMAT_BC3_UNORM_BLOCK + ** ename:VK_FORMAT_BC3_SRGB_BLOCK + ** ename:VK_FORMAT_BC4_UNORM_BLOCK + ** ename:VK_FORMAT_BC4_SNORM_BLOCK + ** ename:VK_FORMAT_BC5_UNORM_BLOCK + ** ename:VK_FORMAT_BC5_SNORM_BLOCK + ** ename:VK_FORMAT_BC6H_UFLOAT_BLOCK + ** ename:VK_FORMAT_BC6H_SFLOAT_BLOCK + ** ename:VK_FORMAT_BC7_UNORM_BLOCK + ** ename:VK_FORMAT_BC7_SRGB_BLOCK ++ flink:vkGetPhysicalDeviceFormatProperties and flink:vkGetPhysicalDeviceImageFormatProperties can: be used to check for additional supported properties of individual formats. --- + * [[features-features-occlusionQueryPrecise]] pname:occlusionQueryPrecise indicates whether occlusion queries returning actual sample counts are supported. @@ -732,10 +736,12 @@ additional supported properties of individual formats. active. include::../validity/structs/VkPhysicalDeviceFeatures.txt[] +-- ifdef::VK_KHX_multiview[] -// refBegin VkPhysicalDeviceMultiviewFeaturesKHX Structure describing multiview features that can be supported by an implementation +[open,refpage='VkPhysicalDeviceMultiviewFeaturesKHX',desc='Structure describing multiview features that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceMultiviewFeaturesKHX structure is defined as: @@ -778,10 +784,46 @@ pname:pNext chain of flink:vkCreateDevice to enable features. include::../validity/structs/VkPhysicalDeviceMultiviewFeaturesKHX.txt[] -// refEnd VkPhysicalDeviceMultiviewFeaturesKHX +-- endif::VK_KHX_multiview[] +ifdef::VK_EXT_blend_operation_advanced[] + +[open,refpage='VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT',desc='Structure describing advanced blending features that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT structure is +defined as: + +include::../api/structs/VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT.txt[] + +The members of the sname:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT +structure describe the following features: + + * [[features-features-advancedBlendCoherentOperations]] + pname:advancedBlendCoherentOperations indicates whether blending using + <> is guaranteed + to execute atomically and in <>. + If this is ename:VK_TRUE, + elink:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT is treated the + same as VK_ACCESS_COLOR_ATTACHMENT_READ_BIT and advanced blending needs + no additional synchronization over basic blending. + If this is ename:VK_FALSE, then memory dependencies are required to + guarantee order between two advanced blending operations that occur on + the same sample. + +If the sname:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT structure is +included in the pname:pNext chain of flink:vkGetPhysicalDeviceFeatures2KHR, +it is filled with values indicating whether each feature is supported. +sname:VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT can: also be used in +the pname:pNext chain of flink:vkCreateDevice to enable features. + +include::../validity/structs/VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT.txt[] +-- + +endif::VK_EXT_blend_operation_advanced[] + [[features-features-requirements]] === Feature Requirements @@ -803,7 +845,8 @@ These are available in the pname:limits member of the slink:VkPhysicalDeviceProperties structure which is returned from flink:vkGetPhysicalDeviceProperties. -// refBegin VkPhysicalDeviceLimits Structure reporting implementation-dependent physical device limits +[open,refpage='VkPhysicalDeviceLimits',desc='Structure reporting implementation-dependent physical device limits',type='structs'] +-- The sname:VkPhysicalDeviceLimits structure is defined as: @@ -1189,7 +1232,6 @@ include::../api/structs/VkPhysicalDeviceLimits.txt[] the mip filtered results. [eq]#2^pname:mipmapPrecisionBits^# is the actual number of divisions. + --- [NOTE] .Note ==== @@ -1198,7 +1240,6 @@ two levels, each level could: contribute: 0%, 33%, 66%, or 100% (this is just an example and the amount of contribution should: be covered by different equations in the spec). ==== --- * [[features-limits-maxDrawIndexedIndexValue]] pname:maxDrawIndexedIndexValue is the maximum index value that can: be used for indexed draw calls when using 32-bit indices. @@ -1241,7 +1282,6 @@ different equations in the spec). max(pname:maxViewportDimensions[0], pname:maxViewportDimensions[1])#. See <>. + --- [NOTE] .Note ==== @@ -1255,7 +1295,6 @@ Since these numbers are typically powers of two, picking the signed number range using the smallest possible number of bits ends up with the specified range. ==== --- * [[features-limits-viewportSubPixelBits]] pname:viewportSubPixelBits is the number of bits of subpixel precision for viewport bounds. The subpixel precision that floating-point viewport bounds are @@ -1492,9 +1531,11 @@ endif::VK_EXT_discard_rectangles[] Counts>>. include::../validity/structs/VkPhysicalDeviceLimits.txt[] +-- -// refBegin VkSampleCountFlagBits Bitmask specifying sample counts supported for an image used for storage operations +[open,refpage='VkSampleCountFlagBits',desc='Bitmask specifying sample counts supported for an image used for storage operations',type='enums'] +-- Bits which may: be set in the sample count limits returned by slink:VkPhysicalDeviceLimits, as well as in other queries and structures @@ -1514,11 +1555,12 @@ include::../api/enums/VkSampleCountFlagBits.txt[] * ename:VK_SAMPLE_COUNT_64_BIT specifies an image with 64 samples per pixel. -// refEnd VkSampleCountFlagBits +-- ifdef::VK_KHR_push_descriptor[] -// refBegin VkPhysicalDevicePushDescriptorPropertiesKHR Structure describing push descriptor limits that can be supported by an implementation +[open,refpage='VkPhysicalDevicePushDescriptorPropertiesKHR',desc='Structure describing push descriptor limits that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDevicePushDescriptorPropertiesKHR structure is defined as: @@ -1535,13 +1577,14 @@ structure describe the following implementation-dependent limits: include::../validity/structs/VkPhysicalDevicePushDescriptorPropertiesKHR.txt[] -// refEnd VkPhysicalDevicePushDescriptorPropertiesKHR +-- endif::VK_KHR_push_descriptor[] ifdef::VK_KHX_multiview[] -// refBegin VkPhysicalDeviceMultiviewPropertiesKHX Structure describing multiview limits that can be supported by an implementation +[open,refpage='VkPhysicalDeviceMultiviewPropertiesKHX',desc='Structure describing multiview limits that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceMultiviewPropertiesKHX structure is defined as: @@ -1563,13 +1606,14 @@ If the sname:VkPhysicalDeviceMultiviewPropertiesKHX structure is included in the pname:pNext chain of flink:VkPhysicalDeviceProperties2KHR, it is filled with the implementation-dependent limits. -// refEnd VkPhysicalDeviceMultiviewPropertiesKHX +-- endif::VK_KHX_multiview[] ifdef::VK_EXT_discard_rectangles[] -// refBegin VkPhysicalDeviceDiscardRectanglePropertiesEXT Structure describing discard rectangle limits that can be supported by an implementation +[open,refpage='VkPhysicalDeviceDiscardRectanglePropertiesEXT',desc='Structure describing discard rectangle limits that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT structure is defined as: @@ -1588,13 +1632,14 @@ If the sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT structure is included in the pname:pNext chain of flink:VkPhysicalDeviceProperties2KHR, it is filled with the implementation-dependent limits. -// refEnd VkPhysicalDeviceDiscardRectanglePropertiesEXT +-- endif::VK_EXT_discard_rectangles[] ifdef::VK_NVX_multiview_per_view_attributes[] -// refBegin VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX Structure describing multiview limits that can be supported by an implementation +[open,refpage='VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX',desc='Structure describing multiview limits that can be supported by an implementation',type='structs'] +-- The sname:VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX structure is defined as: @@ -1617,10 +1662,126 @@ structure is included in the pname:pNext chain of flink:VkPhysicalDeviceProperties2KHR, it is filled with the implementation-dependent limits. -// refEnd VkPhysicalDeviceMultiviewPerViewAttributesPropertiesNVX +-- endif::VK_NVX_multiview_per_view_attributes[] +ifdef::VK_EXT_blend_operation_advanced[] + +[open,refpage='VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT',desc='Structure describing advanced blending limits that can be supported by an implementation',type='structs'] +-- + +The sname:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT structure is +defined as: + +include::../api/structs/VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT.txt[] + +The members of the sname:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT +structure describe the following implementation-dependent limits: + + * [[features-limits-advancedBlendMaxColorAttachments]] + pname:advancedBlendMaxColorAttachments is one greater than the highest + color attachment index that can: be used in a subpass, for a pipeline + that uses an <>. + * [[features-limits-advancedBlendIndependentBlend]] + pname:advancedBlendIndependentBlend indicates whether advanced blend + operations can: vary per-attachment. + * [[features-limits-advancedBlendNonPremultipliedSrcColor]] + pname:advancedBlendNonPremultipliedSrcColor indicates whether the source + color can: be treated as non-premultiplied. + If this is ename:VK_FALSE, then + slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:srcPremultiplied + must: be ename:VK_TRUE. + * [[features-limits-advancedBlendNonPremultipliedDstColor]] + pname:advancedBlendNonPremultipliedDstColor indicates whether the + destination color can: be treated as non-premultiplied. + If this is ename:VK_FALSE, then + slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:dstPremultiplied + must: be ename:VK_TRUE. + * [[features-limits-advancedBlendCorrelatedOverlap]] + pname:advancedBlendCorrelatedOverlap indicates whether the overlap mode + can: be treated as correlated. + If this is ename:VK_FALSE, then + slink:VkPipelineColorBlendAdvancedStateCreateInfoEXT::pname:blendOverlap + must: be ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT. + * [[features-limits-advancedBlendAllOperations]] + pname:advancedBlendAllOperations indicates whether all advanced blend + operation enums are supported. + See the valid usage of slink:VkPipelineColorBlendAttachmentState. + +include::../validity/structs/VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT.txt[] + +If the sname:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT structure +is included in the pname:pNext chain of +flink:VkPhysicalDeviceProperties2KHR, it is filled with the +implementation-dependent limits. +-- + +endif::VK_EXT_blend_operation_advanced[] + + +ifdef::VK_EXT_sampler_filter_minmax[] + +[open,refpage='VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT',desc='Structure describing sampler filter minmax limits that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT structure is +defined as: + +include::../api/structs/VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT.txt[] + +The members of the sname:VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT +structure describe the following implementation-dependent limits: + + * [[features-limits-filterMinmaxSingleComponentFormats]] + pname:filterMinmaxSingleComponentFormats is a boolean value indicating + whether a minimum set of required formats support min/max filtering. + * [[features-limits-filterMinmaxImageComponentMapping]] + pname:filterMinmaxImageComponentMapping is a boolean value indicating + whether the implementation supports non-identity component mapping of + the image when doing min/max filtering. + +If the sname:VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT structure is +included in the pname:pNext chain of flink:VkPhysicalDeviceProperties2KHR, +it is filled with the implementation-dependent limits. + +If pname:filterMinmaxSingleComponentFormats is ename:VK_TRUE, the following +formats must: support the +ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT feature with +ename:VK_IMAGE_TILING_OPTIMAL, if they support +ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. + + * ename:VK_FORMAT_R8_UNORM + * ename:VK_FORMAT_R8_SNORM + * ename:VK_FORMAT_R16_UNORM + * ename:VK_FORMAT_R16_SNORM + * ename:VK_FORMAT_R16_SFLOAT + * ename:VK_FORMAT_R32_SFLOAT + * ename:VK_FORMAT_D16_UNORM + * ename:VK_FORMAT_X8_D24_UNORM_PACK32 + * ename:VK_FORMAT_D32_SFLOAT + * ename:VK_FORMAT_D16_UNORM_S8_UINT + * ename:VK_FORMAT_D24_UNORM_S8_UINT + * ename:VK_FORMAT_D32_SFLOAT_S8_UINT + +If the format is a depth/stencil format, this bit only indicates that the +depth aspect (not the stencil aspect) of an image of this format supports +min/max filtering, and that min/max filtering of the depth aspect is +supported when depth compare is disabled in the sampler. + +If pname:filterMinmaxImageComponentMapping is ename:VK_FALSE the component +mapping of the image view used with min/max filtering must: have been +created with the pname:r component set to +ename:VK_COMPONENT_SWIZZLE_IDENTITY. +Only the pname:r component of the sampled image value is defined and the +other component values are undefined. +If pname:filterMinmaxImageComponentMapping is ename:VK_TRUE this restriction +does not apply and image component mapping works as normal. + +include::../validity/structs/VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT.txt[] +-- + +endif::VK_EXT_sampler_filter_minmax[] + [[features-limits-minmax]] === Limit Requirements @@ -1747,6 +1908,10 @@ whether or not the feature is enabled. ifdef::VK_EXT_discard_rectangles[] | basetype:uint32_t | pname:maxDiscardRectangles | VK_EXT_discard_rectangles endif::VK_EXT_discard_rectangles[] +ifdef::VK_EXT_sampler_filter_minmax[] +| basetype:VkBool32 | pname:filterMinmaxSingleComponentFormats | VK_EXT_sampler_filter_minmax +| basetype:VkBool32 | pname:filterMinmaxImageComponentMapping | VK_EXT_sampler_filter_minmax +endif::VK_EXT_sampler_filter_minmax[] |==== [[features-limits-required]] @@ -1873,6 +2038,18 @@ endif::VK_EXT_discard_rectangles[] ifdef::VK_NVX_multiview_per_view_attributes[] | pname:perViewPositionAllComponents | - | - | implementation dependent endif::VK_NVX_multiview_per_view_attributes[] +ifdef::VK_EXT_sampler_filter_minmax[] +| pname:filterMinmaxSingleComponentFormats | - | - | implementation dependent +| pname:filterMinmaxImageComponentMapping | - | - | implementation dependent +endif::VK_EXT_sampler_filter_minmax[] +ifdef::VK_EXT_blend_operation_advanced[] +| pname:advancedBlendMaxColorAttachments | - | 1 | min +| pname:advancedBlendIndependentBlend | - |false| implementation dependent +| pname:advancedBlendNonPremultipliedSrcColor | - |false| implementation dependent +| pname:advancedBlendNonPremultipliedDstColor | - |false| implementation dependent +| pname:advancedBlendCorrelatedOverlap | - |false| implementation dependent +| pname:advancedBlendAllOperations | - |false| implementation dependent +endif::VK_EXT_blend_operation_advanced[] |==== 1:: @@ -1883,11 +2060,9 @@ endif::VK_NVX_multiview_per_view_attributes[] set, but they may: have additional bits set beyond this minimum. 2:: + The pname:maxPerStageResources must: be at least the smallest of the + following: + --- -The pname:maxPerStageResources must: be at least the smallest of the -following: - * the sum of the pname:maxPerStageDescriptorUniformBuffers, pname:maxPerStageDescriptorStorageBuffers, pname:maxPerStageDescriptorSampledImages, @@ -1895,9 +2070,8 @@ following: pname:maxPerStageDescriptorInputAttachments, pname:maxColorAttachments limits, or * 128. - ++ It may: not be possible to reach this limit in every stage. --- 3:: See @@ -1945,7 +2119,8 @@ flink:vkGetPhysicalDeviceFormatProperties command. [[features-formats-definition]] === Format Definition -// refBegin VkFormat Available image formats +[open,refpage='VkFormat',desc='Available image formats',type='enums'] +-- Image formats which can: be passed to, and may: be returned from Vulkan commands, are: @@ -2403,210 +2578,211 @@ include::../api/enums/VkFormat.txt[] There are optionally: 24-bits that are unused. * ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK specifies a three-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data. + a 4{times}4 rectangle of unsigned normalized RGB texel data. This format has no alpha and is considered opaque. * ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK specifies a three-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data with sRGB + a 4{times}4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding. This format has no alpha and is considered opaque. * ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK specifies a four-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data, and provides 1 - bit of alpha. + a 4{times}4 rectangle of unsigned normalized RGB texel data, and + provides 1 bit of alpha. * ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK specifies a four-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data with sRGB + a 4{times}4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding, and provides 1 bit of alpha. * ename:VK_FORMAT_BC2_UNORM_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data with the - first 64 bits encoding alpha values followed by 64 bits encoding RGB - values. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data + with the first 64 bits encoding alpha values followed by 64 bits + encoding RGB values. * ename:VK_FORMAT_BC2_SRGB_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data with the - first 64 bits encoding alpha values followed by 64 bits encoding RGB - values with sRGB nonlinear encoding. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data + with the first 64 bits encoding alpha values followed by 64 bits + encoding RGB values with sRGB nonlinear encoding. * ename:VK_FORMAT_BC3_UNORM_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data with the - first 64 bits encoding alpha values followed by 64 bits encoding RGB - values. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data + with the first 64 bits encoding alpha values followed by 64 bits + encoding RGB values. * ename:VK_FORMAT_BC3_SRGB_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data with the - first 64 bits encoding alpha values followed by 64 bits encoding RGB - values with sRGB nonlinear encoding. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data + with the first 64 bits encoding alpha values followed by 64 bits + encoding RGB values with sRGB nonlinear encoding. * ename:VK_FORMAT_BC4_UNORM_BLOCK specifies a one-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized red texel data. + a 4{times}4 rectangle of unsigned normalized red texel data. * ename:VK_FORMAT_BC4_SNORM_BLOCK specifies a one-component, block-compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of signed normalized red texel data. + a 4{times}4 rectangle of signed normalized red texel data. * ename:VK_FORMAT_BC5_UNORM_BLOCK specifies a two-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RG texel data with the - first 64 bits encoding red values followed by 64 bits encoding green + encodes a 4{times}4 rectangle of unsigned normalized RG texel data with + the first 64 bits encoding red values followed by 64 bits encoding green values. * ename:VK_FORMAT_BC5_SNORM_BLOCK specifies a two-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of signed normalized RG texel data with the - first 64 bits encoding red values followed by 64 bits encoding green + encodes a 4{times}4 rectangle of signed normalized RG texel data with + the first 64 bits encoding red values followed by 64 bits encoding green values. * ename:VK_FORMAT_BC6H_UFLOAT_BLOCK specifies a three-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned floating-point RGB texel data. + encodes a 4{times}4 rectangle of unsigned floating-point RGB texel data. * ename:VK_FORMAT_BC6H_SFLOAT_BLOCK specifies a three-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of signed floating-point RGB texel data. + encodes a 4{times}4 rectangle of signed floating-point RGB texel data. * ename:VK_FORMAT_BC7_UNORM_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_BC7_SRGB_BLOCK specifies a four-component, block-compressed format where each 128-bit compressed texel block - encodes a 4x4 rectangle of unsigned normalized RGBA texel data with sRGB - nonlinear encoding applied to the RGB components. + encodes a 4{times}4 rectangle of unsigned normalized RGBA texel data + with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK specifies a three-component, ETC2 compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data. + a 4{times}4 rectangle of unsigned normalized RGB texel data. This format has no alpha and is considered opaque. * ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK specifies a three-component, ETC2 - compressed format where each 64-bit compressed texel block encodes a 4x4 - rectangle of unsigned normalized RGB texel data with sRGB nonlinear - encoding. + compressed format where each 64-bit compressed texel block encodes a + 4{times}4 rectangle of unsigned normalized RGB texel data with sRGB + nonlinear encoding. This format has no alpha and is considered opaque. * ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK specifies a four-component, ETC2 compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data, and provides 1 - bit of alpha. + a 4{times}4 rectangle of unsigned normalized RGB texel data, and + provides 1 bit of alpha. * ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK specifies a four-component, ETC2 compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGB texel data with sRGB + a 4{times}4 rectangle of unsigned normalized RGB texel data with sRGB nonlinear encoding, and provides 1 bit of alpha. * ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK specifies a four-component, ETC2 compressed format where each 128-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGBA texel data with the first 64 - bits encoding alpha values followed by 64 bits encoding RGB values. + a 4{times}4 rectangle of unsigned normalized RGBA texel data with the + first 64 bits encoding alpha values followed by 64 bits encoding RGB + values. * ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK specifies a four-component, ETC2 compressed format where each 64-bit compressed texel block encodes - a 4x4 rectangle of unsigned normalized RGBA texel data with the first 64 - bits encoding alpha values followed by 64 bits encoding RGB values with - sRGB nonlinear encoding applied. + a 4{times}4 rectangle of unsigned normalized RGBA texel data with the + first 64 bits encoding alpha values followed by 64 bits encoding RGB + values with sRGB nonlinear encoding applied. * ename:VK_FORMAT_EAC_R11_UNORM_BLOCK specifies a one-component, ETC2 - compressed format where each 64-bit compressed texel block encodes a 4x4 - rectangle of unsigned normalized red texel data. + compressed format where each 64-bit compressed texel block encodes a + 4{times}4 rectangle of unsigned normalized red texel data. * ename:VK_FORMAT_EAC_R11_SNORM_BLOCK specifies a one-component, ETC2 - compressed format where each 64-bit compressed texel block encodes a 4x4 - rectangle of signed normalized red texel data. + compressed format where each 64-bit compressed texel block encodes a + 4{times}4 rectangle of signed normalized red texel data. * ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK specifies a two-component, ETC2 compressed format where each 128-bit compressed texel block encodes a - 4x4 rectangle of unsigned normalized RG texel data with the first 64 - bits encoding red values followed by 64 bits encoding green values. + 4{times}4 rectangle of unsigned normalized RG texel data with the first + 64 bits encoding red values followed by 64 bits encoding green values. * ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK specifies a two-component, ETC2 compressed format where each 128-bit compressed texel block encodes a - 4x4 rectangle of signed normalized RG texel data with the first 64 bits - encoding red values followed by 64 bits encoding green values. + 4{times}4 rectangle of signed normalized RG texel data with the first 64 + bits encoding red values followed by 64 bits encoding green values. * ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 4x4 rectangle of unsigned normalized RGBA texel data. + 4{times}4 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 4x4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 4{times}4 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 5x4 rectangle of unsigned normalized RGBA texel data. + 5{times}4 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 5x4 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 5{times}4 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 5x5 rectangle of unsigned normalized RGBA texel data. + 5{times}5 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 5x5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 5{times}5 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 6x5 rectangle of unsigned normalized RGBA texel data. + 6{times}5 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 6x5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 6{times}5 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 6x6 rectangle of unsigned normalized RGBA texel data. + 6{times}6 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 6x6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 6{times}6 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x5 rectangle of unsigned normalized RGBA texel data. + 8{times}5 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 8{times}5 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x6 rectangle of unsigned normalized RGBA texel data. + 8{times}6 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 8{times}6 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x8 rectangle of unsigned normalized RGBA texel data. + 8{times}8 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes an - 8x8 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear - encoding applied to the RGB components. + 8{times}8 rectangle of unsigned normalized RGBA texel data with sRGB + nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x5 rectangle of unsigned normalized RGBA texel data. + 10{times}5 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x5 rectangle of unsigned normalized RGBA texel data with sRGB + 10{times}5 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x6 rectangle of unsigned normalized RGBA texel data. + 10{times}6 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x6 rectangle of unsigned normalized RGBA texel data with sRGB + 10{times}6 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x8 rectangle of unsigned normalized RGBA texel data. + 10{times}8 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x8 rectangle of unsigned normalized RGBA texel data with sRGB + 10{times}8 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x10 rectangle of unsigned normalized RGBA texel data. + 10{times}10 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 10x10 rectangle of unsigned normalized RGBA texel data with sRGB + 10{times}10 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 12x10 rectangle of unsigned normalized RGBA texel data. + 12{times}10 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 12x10 rectangle of unsigned normalized RGBA texel data with sRGB + 12{times}10 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. * ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 12x12 rectangle of unsigned normalized RGBA texel data. + 12{times}12 rectangle of unsigned normalized RGBA texel data. * ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK specifies a four-component, ASTC compressed format where each 128-bit compressed texel block encodes a - 12x12 rectangle of unsigned normalized RGBA texel data with sRGB + 12{times}12 rectangle of unsigned normalized RGBA texel data with sRGB nonlinear encoding applied to the RGB components. -// refEnd VkFormat +-- [[features-formats-packed]] @@ -3100,7 +3276,8 @@ in the same row are compatible. [[features-formats-properties]] === Format Properties -// refBegin vkGetPhysicalDeviceFormatProperties Lists physical device's format capabilities +[open,refpage='vkGetPhysicalDeviceFormatProperties',desc='Lists physical device\'s format capabilities',type='protos'] +-- To query supported format features which are properties of the physical device, call: @@ -3115,8 +3292,10 @@ include::../api/protos/vkGetPhysicalDeviceFormatProperties.txt[] returned. include::../validity/protos/vkGetPhysicalDeviceFormatProperties.txt[] +-- -// refBegin VkFormatProperties Structure specifying image format properties +[open,refpage='VkFormatProperties',desc='Structure specifying image format properties',type='structs'] +-- The sname:VkFormatProperties structure is defined as: @@ -3150,8 +3329,10 @@ If pname:format is a block-compression format, then buffers must: not support any features for the format. include::../validity/structs/VkFormatProperties.txt[] +-- -// refBegin VkFormatFeatureFlagBits Bitmask specifying features supported by a buffer +[open,refpage='VkFormatFeatureFlagBits',desc='Bitmask specifying features supported by a buffer',type='enums'] +-- Bits which can: be set in the slink:VkFormatProperties features pname:linearTilingFeatures, pname:optimalTilingFeatures, and @@ -3195,7 +3376,6 @@ flink:vkGetPhysicalDeviceFormatProperties::pname:format: ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT or ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT. + --- If the format being queried is a depth/stencil format, this bit only indicates that the depth aspect (not the stencil aspect) of an image of this format supports linear filtering, and that linear filtering of the depth @@ -3207,7 +3387,7 @@ which differs from the normal rules of linear filtering. The resulting value must: be in the range [eq]#[0,1]# and should: be proportional to, or a weighted average of, the number of comparison passes or failures. --- + ifdef::VK_KHR_maintenance1[] * ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR specifies that an image can: be used as a source image for <>. @@ -3216,6 +3396,14 @@ ifdef::VK_KHR_maintenance1[] <>. endif::VK_KHR_maintenance1[] +ifdef::VK_EXT_sampler_filter_minmax[] + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT:: + sname:VkImage can: be used as a sampled image with a min or max + elink:VkSamplerReductionModeEXT. + This bit must: only be exposed for formats that also support the + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. +endif::VK_EXT_sampler_filter_minmax[] + ifdef::VK_IMG_filter_cubic[] include::VK_IMG_filter_cubic/filter_cubic_sampled_bit_description.txt[] endif::VK_IMG_filter_cubic[] @@ -3238,11 +3426,12 @@ flink:vkGetPhysicalDeviceProperties::pname:format: be used as a vertex attribute format (sname:VkVertexInputAttributeDescription::pname:format). -// refEnd VkFormatFeatureFlagBits +-- ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceFormatProperties2KHR Lists physical device's format capabilities +[open,refpage='vkGetPhysicalDeviceFormatProperties2KHR',desc='Lists physical device\'s format capabilities',type='protos'] +-- To query supported format features which are properties of the physical device, call: @@ -3261,8 +3450,10 @@ flink:vkGetPhysicalDeviceFormatProperties, with the ability to return extended information in a pname:pNext chain of output structures. include::../validity/protos/vkGetPhysicalDeviceFormatProperties2KHR.txt[] +-- -// refBegin VkFormatProperties2KHR Structure specifying image format properties +[open,refpage='VkFormatProperties2KHR',desc='Structure specifying image format properties',type='structs'] +-- The sname:VkFormatProperties2KHR structure is defined as: @@ -3274,6 +3465,7 @@ include::../api/structs/VkFormatProperties2KHR.txt[] describing features supported by the requested format. include::../validity/structs/VkFormatProperties2KHR.txt[] +-- endif::VK_KHR_get_physical_device_properties2[] @@ -3324,6 +3516,9 @@ endif::VK_KHR_maintenance1[] |ename:VK_FORMAT_FEATURE_BLIT_DST_BIT |ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT |ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +ifdef::VK_EXT_sampler_filter_minmax[] +|ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT +endif::VK_EXT_sampler_filter_minmax[] |==== .Feature bits in pname:bufferFeatures @@ -3795,7 +3990,8 @@ images. For example, larger dimensions or additional sample counts for certain image types, or additional capabilities for _linear_ tiling format images. -// refBegin vkGetPhysicalDeviceImageFormatProperties Lists physical device's image format capabilities +[open,refpage='vkGetPhysicalDeviceImageFormatProperties',desc='Lists physical device\'s image format capabilities',type='protos'] +-- To query additional capabilities specific to image types, call: @@ -3839,8 +4035,10 @@ than the limitations for code:usage2 and code:flags2, for all values of pname:format, pname:type, and pname:tiling. include::../validity/protos/vkGetPhysicalDeviceImageFormatProperties.txt[] +-- -// refBegin VkImageFormatProperties Structure specifying a image format properties +[open,refpage='VkImageFormatProperties',desc='Structure specifying a image format properties',type='structs'] +-- The sname:VkImageFormatProperties structure is defined as: @@ -3889,6 +4087,7 @@ implementation for use in flink:vkCreateImage, then all members of sname:VkImageFormatProperties will be filled with zero. include::../validity/structs/VkImageFormatProperties.txt[] +-- ifdef::VK_NV_external_memory_capabilities[] include::./VK_NV_external_memory_capabilities/external_image_format.txt[] @@ -3896,7 +4095,8 @@ endif::VK_NV_external_memory_capabilities[] ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceImageFormatProperties2KHR Lists physical device's image format capabilities +[open,refpage='vkGetPhysicalDeviceImageFormatProperties2KHR',desc='Lists physical device\'s image format capabilities',type='protos'] +-- To query additional capabilities specific to image types, call: @@ -3922,8 +4122,10 @@ not support, fname:vkGetPhysicalDeviceImageFormatProperties2KHR returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. include::../validity/protos/vkGetPhysicalDeviceImageFormatProperties2KHR.txt[] +-- -// refBegin VkPhysicalDeviceImageFormatInfo2KHR Structure specifying image creation parameters +[open,refpage='VkPhysicalDeviceImageFormatInfo2KHR',desc='Structure specifying image creation parameters',type='structs'] +-- The sname:VkPhysicalDeviceImageFormatInfo2KHR structure is defined as: @@ -3952,8 +4154,10 @@ arguments to flink:vkGetPhysicalDeviceImageFormatProperties, with pname:sType and pname:pNext added for extensibility. include::../validity/structs/VkPhysicalDeviceImageFormatInfo2KHR.txt[] +-- -// refBegin VkImageFormatProperties2KHR Structure specifying a image format properties +[open,refpage='VkImageFormatProperties2KHR',desc='Structure specifying a image format properties',type='structs'] +-- The sname:VkImageFormatProperties2KHR structure is defined as: @@ -3974,9 +4178,11 @@ implementation for use in flink:vkCreateImage, then all members of pname:imageFormatProperties will be filled with zero. include::../validity/structs/VkImageFormatProperties2KHR.txt[] +-- ifdef::VK_AMD_texture_gather_bias_lod[] -// refBegin VkTextureLODGatherFormatPropertiesAMD Structure informing whether or not texture gather bias/LOD functionality is supported for a given image format and a given physical device. +[open,refpage='VkTextureLODGatherFormatPropertiesAMD',desc='Structure informing whether or not texture gather bias/LOD functionality is supported for a given image format and a given physical device.',type='structs'] +-- To determine if texture gather functions that take explicit LOD and/or bias argument values can be used with a given image format, add @@ -3999,11 +4205,12 @@ include::../api/structs/VkTextureLODGatherFormatPropertiesAMD.txt[] This field is set by the implementation. User-specified value is ignored. -// refEnd VkTextureLODGatherFormatPropertiesAMD +-- endif::VK_AMD_texture_gather_bias_lod[] ifdef::VK_KHX_external_memory_capabilities[] -// refBegin VkPhysicalDeviceExternalImageFormatInfoKHX Structure specifying external image creation parameters +[open,refpage='VkPhysicalDeviceExternalImageFormatInfoKHX',desc='Structure specifying external image creation parameters',type='structs'] +-- To determine the image capabilities compatible with an external memory handle type, add slink:VkPhysicalDeviceExternalImageFormatInfoKHX to the @@ -4033,8 +4240,10 @@ flink:vkGetPhysicalDeviceImageFormatProperties2KHR returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. include::../validity/structs/VkPhysicalDeviceExternalImageFormatInfoKHX.txt[] +-- -// refBegin VkExternalMemoryHandleTypeFlagBitsKHX - Bit specifying external memory handle types +[open,refpage='VkExternalMemoryHandleTypeFlagBitsKHX',desc='Bit specifying external memory handle types',type='enums'] +-- Possible values of slink:VkPhysicalDeviceExternalImageFormatInfoKHX::pname:handleType, @@ -4086,9 +4295,10 @@ include::../api/enums/VkExternalMemoryHandleTypeFlagBitsKHX.txt[] referring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource. -// refEnd VkExternalMemoryHandleTypeFlagBitsKHX +-- -// refBegin VkExternalImageFormatPropertiesKHX Structure specifying supported external handle properties +[open,refpage='VkExternalImageFormatPropertiesKHX',desc='Structure specifying supported external handle properties',type='structs'] +-- The sname:VkExternalImageFormatPropertiesKHX structure is defined as: @@ -4102,8 +4312,10 @@ include::../api/structs/VkExternalImageFormatPropertiesKHX.txt[] image creation parameters. include::../validity/structs/VkExternalImageFormatPropertiesKHX.txt[] +-- -// refBegin VkExternalMemoryPropertiesKHX Structure specifying external memory handle type capabilities +[open,refpage='VkExternalMemoryPropertiesKHX',desc='Structure specifying external memory handle type capabilities',type='structs'] +-- The sname:VkExternalMemoryPropertiesKHX structure is defined as: @@ -4130,8 +4342,10 @@ types intended for concurrent use in a single image and intersecting them to obtain the compatible set of capabilities. include::../validity/structs/VkExternalMemoryPropertiesKHX.txt[] +-- -// refBegin VkExternalMemoryFeatureFlagBitsKHX Bitmask specifying features of an external memory handle type +[open,refpage='VkExternalMemoryFeatureFlagBitsKHX',desc='Bitmask specifying features of an external memory handle type',type='enums'] +-- Bits which may: be set in slink:VkExternalMemoryPropertiesKHX::pname:externalMemoryFeatures, @@ -4158,7 +4372,7 @@ for the following external handle types: * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHX * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHX -// refEnd VkExternalMemoryFeatureFlagBitsKHX +-- endif::VK_KHX_external_memory_capabilities[] @@ -4278,7 +4492,8 @@ In addition to the capabilities described in the previous sections (<> and <>), implementations may support additional buffer capabilities. -// refBegin vkGetPhysicalDeviceExternalBufferPropertiesKHX Query external handle types supported by buffers +[open,refpage='vkGetPhysicalDeviceExternalBufferPropertiesKHX',desc='Query external handle types supported by buffers',type='protos'] +-- To query the external handle types supported by buffers, call: @@ -4294,8 +4509,10 @@ include::../api/protos/vkGetPhysicalDeviceExternalBufferPropertiesKHX.txt[] returned. include::../validity/protos/vkGetPhysicalDeviceExternalBufferPropertiesKHX.txt[] +-- -// refBegin VkPhysicalDeviceExternalBufferInfoKHX Structure specifying buffer creation parameters +[open,refpage='VkPhysicalDeviceExternalBufferInfoKHX',desc='Structure specifying buffer creation parameters',type='structs'] +-- The sname:VkPhysicalDeviceExternalBufferInfoKHX structure is defined as: @@ -4314,8 +4531,10 @@ include::../api/structs/VkPhysicalDeviceExternalBufferInfoKHX.txt[] associated with the buffer. include::../validity/structs/VkPhysicalDeviceExternalBufferInfoKHX.txt[] +-- -// refBegin VkExternalBufferPropertiesKHX Structure specifying supported external handle capabilities +[open,refpage='VkExternalBufferPropertiesKHX',desc='Structure specifying supported external handle capabilities',type='structs'] +-- The sname:VkExternalBufferPropertiesKHX structure is defined as: @@ -4329,13 +4548,15 @@ include::../api/structs/VkExternalBufferPropertiesKHX.txt[] buffer creation parameters. include::../validity/structs/VkExternalBufferPropertiesKHX.txt[] +-- endif::VK_KHX_external_memory_capabilities[] ifdef::VK_KHX_external_semaphore_capabilities[] == Optional Semaphore Capabilities -// refBegin vkGetPhysicalDeviceExternalSemaphorePropertiesKHX Function for querying external semaphore handle capabilities. +[open,refpage='vkGetPhysicalDeviceExternalSemaphorePropertiesKHX',desc='Function for querying external semaphore handle capabilities.',type='protos'] +-- Semaphores may: support import and export of external semaphore handles. To query the external handle types supported by semaphores, call: @@ -4352,8 +4573,10 @@ include::../api/protos/vkGetPhysicalDeviceExternalSemaphorePropertiesKHX.txt[] are returned. include::../validity/protos/vkGetPhysicalDeviceExternalSemaphorePropertiesKHX.txt[] +-- -// refBegin VkPhysicalDeviceExternalSemaphoreInfoKHX Structure specifying semaphore creation parameters. +[open,refpage='VkPhysicalDeviceExternalSemaphoreInfoKHX',desc='Structure specifying semaphore creation parameters.',type='structs'] +-- The sname:VkPhysicalDeviceExternalSemaphoreInfoKHX structure is defined as: @@ -4366,8 +4589,10 @@ include::../api/structs/VkPhysicalDeviceExternalSemaphoreInfoKHX.txt[] capabilities will be returned. include::../validity/structs/VkPhysicalDeviceExternalSemaphoreInfoKHX.txt[] +-- -// refBegin VkExternalSemaphoreHandleTypeFlagBitsKHX - Bitmask of valid external semaphore handle types +[open,refpage='VkExternalSemaphoreHandleTypeFlagBitsKHX',desc='Bitmask of valid external semaphore handle types',type='enums'] +-- Bits which may: be set in slink:VkPhysicalDeviceExternalSemaphoreInfoKHX::pname:handleType, specifying @@ -4428,9 +4653,10 @@ system calls compatible with only one of the fence types may: result in undefined behavior. ==== -// refEnd VkExternalSemaphoreHandleTypeFlagBitsKHX +-- -// refBegin VkExternalSemaphorePropertiesKHX Structure describing supported external semaphore handle features +[open,refpage='VkExternalSemaphorePropertiesKHX',desc='Structure describing supported external semaphore handle features',type='structs'] +-- The sname:VkExternalSemaphorePropertiesKHX structure is defined as: @@ -4452,8 +4678,10 @@ slink:VkExternalSemaphorePropertiesKHX::pname:externalSemaphoreFeatures will be set to zero. include::../validity/structs/VkExternalSemaphorePropertiesKHX.txt[] +-- -// refBegin VkExternalSemaphoreFeatureFlagBitsKHX Bitfield describing features of an external semaphore handle type +[open,refpage='VkExternalSemaphoreFeatureFlagBitsKHX',desc='Bitfield describing features of an external semaphore handle type',type='enums'] +-- Possible values of slink:VkExternalSemaphorePropertiesKHX::pname:externalSemaphoreFeatures, @@ -4466,6 +4694,6 @@ include::../api/enums/VkExternalSemaphoreFeatureFlagBitsKHX.txt[] * ename:VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT_KHX specifies that handles of this type can: be imported as Vulkan semaphore objects. -// refEnd VkExternalSemaphoreFeatureFlagBitsKHX +-- endif::VK_KHX_external_semaphore_capabilities[] diff --git a/doc/specs/vulkan/chapters/fragops.txt b/doc/specs/vulkan/chapters/fragops.txt index 97e97c56..703b4eee 100644 --- a/doc/specs/vulkan/chapters/fragops.txt +++ b/doc/specs/vulkan/chapters/fragops.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[fragops]] = Fragment Operations @@ -45,7 +46,8 @@ ifdef::VK_EXT_discard_rectangles[] [[fragops-discard-rectangles]] == Discard Rectangles Test -// refBegin VkPipelineDiscardRectangleStateCreateInfoEXT Structure specifying discard rectangle +[open,refpage='VkPipelineDiscardRectangleStateCreateInfoEXT',desc='Structure specifying discard rectangle',type='structs'] +-- The discard rectangles test determines if fragment's framebuffer coordinates [eq]#(x~f~,y~f~)# are inclusive or exclusive to a set of discard-space @@ -76,6 +78,7 @@ include::../api/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.txt[] **** include::../validity/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.txt[] +-- The sname:VkPipelineDiscardRectangleStateCreateInfoEXT state is set by adding an instance of this structure to the pname:pNext chain of an instance @@ -88,7 +91,8 @@ rectangles are specified using the pname:pDiscardRectangles member of sname:VkPipelineDiscardRectangleStateCreateInfoEXT linked to the pipeline state object. -// refBegin vkCmdSetDiscardRectangleEXT Set discard rectangles dynamically +[open,refpage='vkCmdSetDiscardRectangleEXT',desc='Set discard rectangles dynamically',type='protos'] +-- If the pipeline state object was created with the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state enabled, the @@ -138,6 +142,7 @@ pname:discardRectangleCount)#. **** include::../validity/protos/vkCmdSetDiscardRectangleEXT.txt[] +-- The sname:VkOffset2D::pname:x and sname:VkOffset2D::pname:y values of the discard rectangle sname:VkRect2D specify the upper-left origin of the @@ -160,7 +165,8 @@ of the active discard rectangle boxes fails the discard rectangle test, and the fragment is discarded; otherwise the fragment passes the discard rectangles test. -// refBegin VkDiscardRectangleModeEXT Specify the discard rectangle mode +[open,refpage='VkDiscardRectangleModeEXT',desc='Specify the discard rectangle mode',type='enums'] +-- Possible values of slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:discardRectangleMode, @@ -173,7 +179,7 @@ include::../api/enums/VkDiscardRectangleModeEXT.txt[] * ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that a fragment not within any of the discard rectangles satisfies the test. -// refEnd VkDiscardRectangleModeEXT +-- endif::VK_EXT_discard_rectangles[] @@ -181,7 +187,8 @@ endif::VK_EXT_discard_rectangles[] [[fragops-scissor]] == Scissor Test -// refBegin vkCmdSetScissor Set the dynamic scissor rectangles on a command buffer +[open,refpage='vkCmdSetScissor',desc='Set the dynamic scissor rectangles on a command buffer',type='protos'] +-- The scissor test determines if a fragment's framebuffer coordinates [eq]#(x~f~,y~f~)# lie within the scissor rectangle corresponding to the @@ -242,6 +249,7 @@ values determining the size in pixels. **** include::../validity/protos/vkCmdSetScissor.txt[] +-- If [eq]#pname:offset.x {leq} x~f~ < pname:offset.x {plus} pname:extent.width# and [eq]#pname:offset.y {leq} y~f~ < pname:offset.y @@ -283,14 +291,15 @@ The array is sized to a length of [eq]#{lceil} pname:rasterizationSamples / If pname:pSampleMask is `NULL`, it is treated as if the mask has all bits enabled, i.e. no coverage is removed from fragments. -// refBegin VkSampleMask Mask of sample coverage information +[open,refpage='VkSampleMask',desc='Mask of sample coverage information',type='basetypes',xrefs='VkPipelineMultisampleStateCreateInfo'] +-- The elements of the sample mask array are of type basetype:VkSampleMask, each representing 32 bits of coverage information: include::../api/basetypes/VkSampleMask.txt[] -// refEnd VkSampleMask VkPipelineMultisampleStateCreateInfo +-- [[fragops-early-mode]] @@ -409,8 +418,9 @@ section). If that shader output has an integer or unsigned integer type, then these operations are skipped. -If pname:alphaToCoverageEnable is enabled, a temporary coverage value is -generated where each bit is determined by the fragment's alpha value. +If pname:alphaToCoverageEnable is enabled, a temporary coverage value with +pname:rasterizationSamples bits is generated where each bit is determined by +the fragment's alpha value. The temporary coverage value is then ANDed with the fragment coverage value to generate a new fragment coverage value. @@ -442,7 +452,8 @@ Pipeline state controlling the <>, specified through the members of the sname:VkPipelineDepthStencilStateCreateInfo structure. -// refBegin VkPipelineDepthStencilStateCreateInfo Structure specifying parameters of a newly created pipeline depth stencil state +[open,refpage='VkPipelineDepthStencilStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline depth stencil state',type='structs'] +-- The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as: @@ -476,11 +487,14 @@ include::../api/structs/VkPipelineDepthStencilStateCreateInfo.txt[] **** include::../validity/structs/VkPipelineDepthStencilStateCreateInfo.txt[] +-- + [[fragops-dbt]] == Depth Bounds Test -// refBegin vkCmdSetDepthBounds Set the depth bounds test values for a command buffer +[open,refpage='vkCmdSetDepthBounds',desc='Set the depth bounds test values for a command buffer',type='protos'] +-- The depth bounds test conditionally disables coverage of a sample based on the outcome of a comparison between the value [eq]#z~a~# in the depth @@ -514,6 +528,7 @@ include::../api/protos/vkCmdSetDepthBounds.txt[] **** include::../validity/protos/vkCmdSetDepthBounds.txt[] +-- If [eq]#pname:minDepthBounds {leq} z~a~ {leq} pname:maxDepthBounds}#, then the depth bounds test passes. @@ -542,7 +557,8 @@ The stencil test is controlled with the pname:front and pname:back members of sname:VkPipelineDepthStencilStateCreateInfo which are of type sname:VkStencilOpState. -// refBegin VkStencilOpState Structure specifying stencil operation state +[open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] +-- The sname:VkStencilOpState structure is defined as: @@ -564,6 +580,7 @@ include::../api/structs/VkStencilOpState.txt[] unsigned stencil comparison. include::../validity/structs/VkStencilOpState.txt[] +-- There are two sets of stencil-related state, the front stencil state set and the back stencil state set. @@ -587,7 +604,8 @@ ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK, and ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic states enabled, respectively. -// refBegin vkCmdSetStencilCompareMask Set the stencil compare mask dynamic state +[open,refpage='vkCmdSetStencilCompareMask',desc='Set the stencil compare mask dynamic state',type='protos'] +-- If the pipeline state object is created with the ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled, then to @@ -609,8 +627,10 @@ include::../api/protos/vkCmdSetStencilCompareMask.txt[] **** include::../validity/protos/vkCmdSetStencilCompareMask.txt[] +-- -// refBegin VkStencilFaceFlagBits Bitmask specifying sets of stencil state for which to update the compare mask +[open,refpage='VkStencilFaceFlagBits',desc='Bitmask specifying sets of stencil state for which to update the compare mask',type='enums'] +-- Bits which can: be set in the flink:vkCmdSetStencilCompareMask::pname:faceMask parameter, and similar @@ -627,9 +647,10 @@ include::../api/enums/VkStencilFaceFlagBits.txt[] ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT, and specifies that both sets of stencil state are updated. -// refEnd VkStencilFaceFlagBits +-- -// refBegin vkCmdSetStencilWriteMask Set the stencil write mask dynamic state +[open,refpage='vkCmdSetStencilWriteMask',desc='Set the stencil write mask dynamic state',type='protos'] +-- If the pipeline state object is created with the ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled, then to @@ -652,8 +673,10 @@ include::../api/protos/vkCmdSetStencilWriteMask.txt[] **** include::../validity/protos/vkCmdSetStencilWriteMask.txt[] +-- -// refBegin vkCmdSetStencilReference Set the stencil reference dynamic state +[open,refpage='vkCmdSetStencilReference',desc='Set the stencil reference dynamic state',type='protos'] +-- If the pipeline state object is created with the ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled, then to @@ -676,6 +699,7 @@ include::../api/protos/vkCmdSetStencilReference.txt[] **** include::../validity/protos/vkCmdSetStencilReference.txt[] +-- pname:reference is an integer reference value that is used in the unsigned stencil comparison. @@ -688,7 +712,8 @@ controlled by pname:compareOp. Let [eq]#R# be the masked reference value and [eq]#S# be the masked stored stencil value. -// refBegin VkCompareOp Stencil comparison function +[open,refpage='VkCompareOp',desc='Stencil comparison function',type='enums'] +-- Possible values of VkStencilOpState::pname:compareOp, specifying the stencil comparison function, are: @@ -710,9 +735,10 @@ include::../api/enums/VkCompareOp.txt[] [eq]#R {geq} S#. * ename:VK_COMPARE_OP_ALWAYS specifies that the test always passes. -// refEnd VkCompareOp +-- -// refBegin VkStencilOp Stencil comparison function +[open,refpage='VkStencilOp',desc='Stencil comparison function',type='enums'] +-- Possible values of the pname:failOp, pname:passOp, and pname:depthFailOp members of slink:VkStencilOpState, specifying what happens to the stored @@ -756,7 +782,7 @@ based on the facingness of the fragment. Fragments generated by front-facing primitives use the front mask and fragments generated by back-facing primitives use the back mask. -// refEnd VkStencilOp +-- [[fragops-depth]] @@ -832,3 +858,210 @@ The occlusion query sample counter increments by one for each sample with a coverage value of 1 in each fragment that survives all the per-fragment tests, including scissor, sample mask, alpha to coverage, stencil, and depth tests. + +ifdef::VK_NV_fragment_coverage_to_color[] + +[[fragops-coverage-to-color]] +== Fragment Coverage To Color + +[open,refpage='VkPipelineCoverageToColorStateCreateInfoNV',desc='Structure specifying whether fragment coverage replaces a color',type='structs'] +-- + +If the pname:pNext chain of slink:VkPipelineMultisampleStateCreateInfo +includes a sname:VkPipelineCoverageToColorStateCreateInfoNV structure, then +that structure controls whether the fragment coverage is substituted for a +fragment color output and, if so, which output is replaced. + +The sname:VkPipelineCoverageToColorStateCreateInfoNV structure is defined +as: + +include::../api/structs/VkPipelineCoverageToColorStateCreateInfoNV.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:coverageToColorEnable controls whether the fragment coverage value + replaces a fragment color output. + * pname:coverageToColorLocation controls which fragment shader color + output value is replaced. + +If pname:coverageToColorEnable is ename:VK_TRUE, the fragment coverage +information is treated as a bitmask with one bit for each sample (as in the +<> section), and this bitmask replaces the +first component of the color value corresponding to the fragment shader +output location with code:Location equal to pname:coverageToColorLocation +and code:Index equal to zero. +If the color attachment format has fewer bits than the sample coverage, the +low bits of the sample coverage bitmask are taken without any clamping. +If the color attachment format has more bits than the sample coverage, the +high bits of the sample coverage bitmask are filled with zeros. + +If <> is in use, the coverage +bitmask only has bits set for samples that correspond to the fragment shader +invocation that shades those samples. + +This pipeline stage occurs after sample counting and before blending, and is +always performed after fragment shading regardless of the setting of +code:EarlyFragmentTests. + +If pname:coverageToColorEnable is ename:VK_FALSE, these operations are +skipped. +If this structure is not present, it is as if pname:coverageToColorEnable is +ename:VK_FALSE. + +.Valid Usage +**** + * [[VUID-VkPipelineCoverageToColorStateCreateInfoNV-coverageToColorEnable-01404]] + If pname:coverageToColorEnable is ename:VK_TRUE, then the render pass + subpass indicated by + slink:VkGraphicsPipelineCreateInfo::pname:renderPass and + slink:VkGraphicsPipelineCreateInfo::pname:subpass must: have a color + attachment at the location selected by pname:coverageToColorLocation, + with a elink:VkFormat of ename:VK_FORMAT_R8_UINT, + ename:VK_FORMAT_R8_SINT, ename:VK_FORMAT_R16_UINT, + ename:VK_FORMAT_R16_SINT, ename:VK_FORMAT_R32_UINT, or + ename:VK_FORMAT_R32_SINT +**** + +include::../validity/structs/VkPipelineCoverageToColorStateCreateInfoNV.txt[] +-- + +endif::VK_NV_fragment_coverage_to_color[] + + +[[fragops-coverage-reduction]] +== Coverage Reduction + +Coverage reduction generates a _color sample mask_ from the coverage mask, +with one bit for each sample in the color attachment(s) for the subpass. +If a bit in the color sample mask is 0, then blending and writing to the +framebuffer are not performed for that sample. + +ifndef::VK_NV_framebuffer_mixed_samples[] + +Each color sample is associated with a unique rasterization sample, and the +value of the coverage mask is assigned to the color sample mask. + +endif::VK_NV_framebuffer_mixed_samples[] + +ifdef::VK_NV_framebuffer_mixed_samples[] + +If the pipeline's +slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is +greater than one and the slink:VkAttachmentDescription::pname:samples of the +color attachments is one, then the fragment's coverage is reduced from +pname:rasterizationSamples bits to a single bit, where the color sample mask +is 1 if any bit in the fragment's coverage is on, and 0 otherwise. + +If the pipeline's +slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is +greater than the slink:VkAttachmentDescription::pname:samples of the color +attachments in the subpass, then the fragment's coverage is reduced from +pname:rasterizationSamples bits to a color sample mask with +slink:VkAttachmentDescription::pname:samples bits. +There is an implementation-dependent association of raster samples to color +samples. +The reduced color sample mask is computed such that the bit for each color +sample is 1 if any of the associated bits in the fragment's coverage is on, +and 0 otherwise. + + +[[fragops-coverage-modulation]] +=== Coverage Modulation + +[open,refpage='VkPipelineCoverageModulationStateCreateInfoNV',desc='Structure specifying parameters controlling coverage modulation',type='structs'] +-- + +As part of coverage reduction, fragment color values can: also be modulated +(multiplied) by a value that is a function of fraction of covered +rasterization samples associated with that color sample. + +Pipeline state controlling coverage reduction is specified through the +members of the sname:VkPipelineCoverageModulationStateCreateInfoNV +structure. + +The sname:VkPipelineCoverageModulationStateCreateInfoNV structure is defined +as: + +include::../api/structs/VkPipelineCoverageModulationStateCreateInfoNV.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:coverageModulationMode controls which color components are + modulated and is of type elink:VkCoverageModulationModeNV. + * pname:coverageModulationTableEnable controls whether the modulation + factor is looked up from a table in pname:pCoverageModulationTable. + * pname:coverageModulationTableCount is the number of elements in + pname:pCoverageModulationTable. + * pname:pCoverageModulationTable is a table of modulation factors + containing a value for each number of covered samples. + +If pname:coverageModulationTableEnable is ename:VK_FALSE, then for each +color sample the associated bits of the fragment's coverage are counted and +divided by the number of associated bits to produce a modulation factor +[eq]#R# in the range [eq]#(0,1]# (a value of zero would have been killed due +to a color coverage of 0). +Specifically: + + * [eq]#N# = value of pname:rasterizationSamples + * [eq]#M# = value of slink:VkAttachmentDescription::pname:samples for any + color attachments + * [eq]#R = popcount(associated coverage bits) / (N / M)# + +If pname:coverageModulationTableEnable is ename:VK_TRUE, the value [eq]#R# +is computed using a programmable lookup table. +The lookup table has [eq]#N / M# elements, and the element of the table is +selected by: + + * [eq]#R = pname:pCoverageModulationTable[popcount(associated coverage + bits)-1]# + +Note that the table does not have an entry for [eq]#popcount(associated +coverage bits) = 0#, because such samples would have been killed. + +The values of pname:pCoverageModulationTable may: be rounded to an +implementation-dependent precision, which is at least as fine as [eq]#1 / +N#, and clamped to [eq]#[0,1]#. + +For each color attachment with a floating point or normalized color format, +each fragment output color value is replicated to [eq]#M# values which can: +each be modulated (multiplied) by that color sample's associated value of +[eq]#R#. +Which components are modulated is controlled by +pname:coverageModulationMode. + +If this structure is not present, it is as if coverageModulationMode is +ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. + +.Valid Usage +**** + * [[VUID-VkPipelineCoverageModulationStateCreateInfoNV-coverageModulationTableEnable-01405]] + If pname:coverageModulationTableEnable is ename:VK_TRUE, + pname:coverageModulationTableCount must: be equal to the number of + rasterization samples divided by the number of color samples in the + subpass. +**** + +include::../validity/structs/VkPipelineCoverageModulationStateCreateInfoNV.txt[] +-- + +[open,refpage='VkCoverageModulationModeNV',desc='Specify the discard rectangle mode',type='enums'] +-- +Possible values of +slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode, +specifying which color components are modulated, are: + +include::../api/enums/VkCoverageModulationModeNV.txt[] + + * ename:VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components + are multiplied by the modulation factor. + * ename:VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, + and blue components are multiplied by the modulation factor. + * ename:VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha + component is multiplied by the modulation factor. + * ename:VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components + are multiplied by the modulation factor. +-- + +endif::VK_NV_framebuffer_mixed_samples[] diff --git a/doc/specs/vulkan/chapters/framebuffer.txt b/doc/specs/vulkan/chapters/framebuffer.txt index 93146eb0..b4945ddf 100644 --- a/doc/specs/vulkan/chapters/framebuffer.txt +++ b/doc/specs/vulkan/chapters/framebuffer.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[framebuffer]] = The Framebuffer @@ -28,8 +29,14 @@ fixed-point color components undergo an implied conversion to floating-point as specified by <>. Blending computations are treated as if carried out in floating-point, and -will be performed with a precision and dynamic range no lower than that used -to represent destination components. +basic blend operations are performed with a precision and dynamic range no +lower than that used to represent destination components. +ifdef::VK_EXT_blend_operation_advanced[] +<> are performed +with a precision and dynamic range no lower than the smaller of that used to +represent destination components or that used to represent 16-bit +floating-point values. +endif::VK_EXT_blend_operation_advanced[] Blending applies only to fixed-point and floating-point color attachments. If the color attachment has an integer format, blending is not applied. @@ -38,7 +45,8 @@ The pipeline blend state is included in the sname:VkPipelineColorBlendStateCreateInfo structure during graphics pipeline creation: -// refBegin VkPipelineColorBlendStateCreateInfo Structure specifying parameters of a newly created pipeline color blend state +[open,refpage='VkPipelineColorBlendStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline color blend state',type='structs'] +-- The sname:VkPipelineColorBlendStateCreateInfo structure is defined as: @@ -83,8 +91,10 @@ elements in the pname:pAttachments array must: be identical. **** include::../validity/structs/VkPipelineColorBlendStateCreateInfo.txt[] +-- -// refBegin VkPipelineColorBlendAttachmentState Structure specifying a pipeline color blend attachment state +[open,refpage='VkPipelineColorBlendAttachmentState',desc='Structure specifying a pipeline color blend attachment state',type='structs'] +-- The sname:VkPipelineColorBlendAttachmentState structure is defined as: @@ -141,15 +151,61 @@ include::../api/structs/VkPipelineColorBlendAttachmentState.txt[] ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_COLOR, ename:VK_BLEND_FACTOR_SRC1_ALPHA, or ename:VK_BLEND_FACTOR_ONE_MINUS_SRC1_ALPHA +ifdef::VK_EXT_blend_operation_advanced[] + * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01406]] + If either of pname:colorBlendOp or pname:alphaBlendOp is an + <>, then + pname:colorBlendOp must: equal pname:alphaBlendOp + * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01407]] + If + slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend + is ename:VK_FALSE and pname:colorBlendOp is an + <>, then + pname:colorBlendOp must: be the same for all attachments. + * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendIndependentBlend-01408]] + If + slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendIndependentBlend + is ename:VK_FALSE and pname:alphaBlendOp is an + <>, then + pname:alphaBlendOp must: be the same for all attachments. + * [[VUID-VkPipelineColorBlendAttachmentState-advancedBlendAllOperations-01409]] + If + slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::pname:advancedBlendAllOperations + is ename:VK_FALSE, then pname:colorBlendOp must: not be + ename:VK_BLEND_OP_ZERO_EXT, ename:VK_BLEND_OP_SRC_EXT, + ename:VK_BLEND_OP_DST_EXT, ename:VK_BLEND_OP_SRC_OVER_EXT, + ename:VK_BLEND_OP_DST_OVER_EXT, ename:VK_BLEND_OP_SRC_IN_EXT, + ename:VK_BLEND_OP_DST_IN_EXT, ename:VK_BLEND_OP_SRC_OUT_EXT, + ename:VK_BLEND_OP_DST_OUT_EXT, ename:VK_BLEND_OP_SRC_ATOP_EXT, + ename:VK_BLEND_OP_DST_ATOP_EXT, ename:VK_BLEND_OP_XOR_EXT, + ename:VK_BLEND_OP_INVERT_EXT, ename:VK_BLEND_OP_INVERT_RGB_EXT, + ename:VK_BLEND_OP_LINEARDODGE_EXT, ename:VK_BLEND_OP_LINEARBURN_EXT, + ename:VK_BLEND_OP_VIVIDLIGHT_EXT, ename:VK_BLEND_OP_LINEARLIGHT_EXT, + ename:VK_BLEND_OP_PINLIGHT_EXT, ename:VK_BLEND_OP_HARDMIX_EXT, + ename:VK_BLEND_OP_PLUS_EXT, ename:VK_BLEND_OP_PLUS_CLAMPED_EXT, + ename:VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT, + ename:VK_BLEND_OP_PLUS_DARKER_EXT, ename:VK_BLEND_OP_MINUS_EXT, + ename:VK_BLEND_OP_MINUS_CLAMPED_EXT, ename:VK_BLEND_OP_CONTRAST_EXT, + ename:VK_BLEND_OP_INVERT_OVG_EXT, ename:VK_BLEND_OP_RED_EXT, + ename:VK_BLEND_OP_GREEN_EXT, or ename:VK_BLEND_OP_BLUE_EXT + * [[VUID-VkPipelineColorBlendAttachmentState-colorBlendOp-01410]] + If pname:colorBlendOp or pname:alphaBlendOp is an + <>, then + slink:VkSubpassDescription::pname:colorAttachmentCount of the subpass + this pipeline is compiled against must: be less than or equal to + slink:VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT::advancedBlendMaxColorAttachments +endif::VK_EXT_blend_operation_advanced[] **** include::../validity/structs/VkPipelineColorBlendAttachmentState.txt[] +-- [[framebuffer-blendfactors]] === Blend Factors -// refBegin VkBlendFactor Framebuffer blending factors +[open,refpage='VkBlendFactor',desc='Framebuffer blending factors',type='enums'] +-- The source and destination color and alpha blending factors are selected from the enum: @@ -199,7 +255,7 @@ In this table, the following conventions are used: * [eq]#R~c~,G~c~,B~c~# and [eq]#A~c~# represent the blend constant R, G, B, and A components, respectively. -// refEnd VkBlendFactor +-- [[framebuffer-blendconstants]] If the pipeline state object is created without the @@ -207,7 +263,8 @@ ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled then the _blend constant_ [eq]#(R~c~,G~c~,B~c~,A~c~)# is specified via the pname:blendConstants member of slink:VkPipelineColorBlendStateCreateInfo. -// refBegin vkCmdSetBlendConstants Set the values of blend constants +[open,refpage='vkCmdSetBlendConstants',desc='Set the values of blend constants',type='protos'] +-- Otherwise, to dynamically set and change the blend constant, call: @@ -227,6 +284,7 @@ include::../api/protos/vkCmdSetBlendConstants.txt[] **** include::../validity/protos/vkCmdSetBlendConstants.txt[] +-- [[framebuffer-dsb]] @@ -261,7 +319,8 @@ blending operation is not defined. [[framebuffer-blendoperations]] === Blend Operations -// refBegin VkBlendOp Framebuffer blending operations +[open,refpage='VkBlendOp',desc='Framebuffer blending operations',type='enums'] +-- Once the source and destination blend factors have been selected, they along with the source and destination components are passed to the blending @@ -274,9 +333,10 @@ include::../api/enums/VkBlendOp.txt[] <<< -The semantics of each enum value is described in the table below: +The semantics of each basic blend operations is described in the table +below: -.Blend Operations +.Basic Blend Operations [width="100%",cols="45%,30%,25%",options="header",align="center"] |==== |VkBlendOp | RGB Components | Alpha Component @@ -337,7 +397,7 @@ destination values and blend factors are each clamped to [eq]#[0,1]# or color attachment prior to evaluating the blend operations. If the color attachment is floating-point, no clamping occurs. -// refEnd VkBlendOp +-- If the numeric format of a framebuffer attachment uses sRGB encoding, the R, G, and B destination color values (after conversion from fixed-point to @@ -364,6 +424,9 @@ are performed through that attachment. Framebuffer color attachments greater than or equal to sname:VkSubpassDescription::pname:colorAttachmentCount perform no writes. +ifdef::VK_EXT_blend_operation_advanced[] +include::VK_EXT_blend_operation_advanced/advanced_blend.txt[] +endif::VK_EXT_blend_operation_advanced[] [[framebuffer-logicop]] == Logical Operations @@ -377,7 +440,8 @@ normalized integer framebuffers. Logical operations are not applied to floating-point or sRGB format color attachments. -// refBegin VkLogicOp Framebuffer logical operations +[open,refpage='VkLogicOp',desc='Framebuffer logical operations',type='enums'] +-- Logical operations are controlled by the pname:logicOpEnable and pname:logicOp members of slink:VkPipelineColorBlendStateCreateInfo. @@ -434,13 +498,14 @@ The result of the logical operation is then written to the color attachment as controlled by the component write mask, described in <>. -// refEnd VkLogicOp +-- [[framebuffer-color-write-mask]] == Color Write Mask -// refBegin VkColorComponentFlagBits Bitmask controlling which components are written to the framebuffer +[open,refpage='VkColorComponentFlagBits',desc='Bitmask controlling which components are written to the framebuffer',type='enums'] +-- Bits which can: be set in slink:VkPipelineColorBlendAttachmentState::pname:colorWriteMask to determine @@ -465,4 +530,4 @@ include::../api/enums/VkColorComponentFlagBits.txt[] The color write mask operation is applied regardless of whether blending is enabled. -// refEnd VkColorComponentFlagBits +-- diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt index ee30ebbe..d2303a3d 100644 --- a/doc/specs/vulkan/chapters/fundamentals.txt +++ b/doc/specs/vulkan/chapters/fundamentals.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[fundamentals]] = Fundamentals @@ -442,7 +443,8 @@ Vulkan uses the standard C types for the base type of scalar parameters (e.g. types from +stdint.h+), with exceptions described below, or elsewhere in the text when appropriate: -// refBegin VkBool32 Vulkan boolean type +[open,refpage='VkBool32',desc='Vulkan boolean type',type='basetypes'] +-- basetype:VkBool32 represents boolean `True` and `False` values, since C does not have a sufficiently portable built-in boolean type: @@ -459,15 +461,16 @@ Applications must: not pass any other values than ename:VK_TRUE or ename:VK_FALSE into a Vulkan implementation where a basetype:VkBool32 is expected. -// refEnd VkBool32 +-- -// refBegin VkDeviceSize Vulkan device memory size and offsets +[open,refpage='VkDeviceSize',desc='Vulkan device memory size and offsets',type='basetypes'] +-- basetype:VkDeviceSize represents device memory size and offset values: include::../api/basetypes/VkDeviceSize.txt[] -// refEnd VkDeviceSize +-- Commands that create Vulkan objects are of the form ftext:vkCreate* and take stext:Vk*CreateInfo structures with the parameters needed to create the @@ -744,7 +747,8 @@ by any extension. [[fundamentals-validusage-flags]] ==== Valid Usage for Flags -// refBegin VkFlags Vulkan bitmasks +[open,refpage='VkFlags',desc='Vulkan bitmasks',type='basetypes',xrefs='VkColorComponentFlags'] +-- A collection of flags is represented by a bitmask using the type basetype:VkFlags: @@ -759,7 +763,7 @@ that type, is used. These aliases are described in the <> appendix of the Specification. -// refEnd VkFlags VkColorComponentFlags +-- Any etext:Vk*Flags member or parameter used in the API as an input must: be a valid combination of bit flags. @@ -844,7 +848,8 @@ sections. [[fundamentals-returncodes]] === Return Codes -// refBegin VkResult Vulkan command return codes +[open,refpage='VkResult',desc='Vulkan command return codes',type='enums',xrefs='TBD'] +-- While the core Vulkan API is not designed to capture incorrect usage, some circumstances still require return codes. @@ -960,7 +965,7 @@ reporting the error until a specified point. For commands that record into command buffers (ftext:vkCmd*) run time errors are reported by fname:vkEndCommandBuffer. -// refEnd VkResult TBD +-- [[fundamentals-numerics]] @@ -1278,21 +1283,32 @@ Offsets are used to describe a pixel location within an image or framebuffer, as an (x,y) location for two-dimensional images, or an (x,y,z) location for three-dimensional images. -// refBegin VkOffset2D Structure specifying a two-dimensional offset +[open,refpage='VkOffset2D',desc='Structure specifying a two-dimensional offset',type='structs'] +-- A two-dimensional offsets is defined by the structure: include::../api/structs/VkOffset2D.txt[] -include::../validity/structs/VkOffset2D.txt[] + * pname:x is the x offset. + * pname:y is the y offset. -// refBegin VkOffset3D Structure specifying a three-dimensional offset +include::../validity/structs/VkOffset2D.txt[] +-- + +[open,refpage='VkOffset3D',desc='Structure specifying a three-dimensional offset',type='structs'] +-- A three-dimensional offset is defined by the structure: include::../api/structs/VkOffset3D.txt[] + * pname:x is the x offset. + * pname:y is the y offset. + * pname:z is the z offset. + include::../validity/structs/VkOffset3D.txt[] +-- === Extents @@ -1301,26 +1317,38 @@ Extents are used to describe the size of a rectangular region of pixels within an image or framebuffer, as (width,height) for two-dimensional images, or as (width,height,depth) for three-dimensional images. -// refBegin VkExtent2D Structure specifying a two-dimensional extent +[open,refpage='VkExtent2D',desc='Structure specifying a two-dimensional extent',type='structs'] +-- A two-dimensional extent is defined by the structure: include::../api/structs/VkExtent2D.txt[] -include::../validity/structs/VkExtent2D.txt[] + * pname:width is the width of the extent. + * pname:height is the height of the extent. -// refBegin VkExtent3D Structure specifying a three-dimensional extent +include::../validity/structs/VkExtent2D.txt[] +-- + +[open,refpage='VkExtent3D',desc='Structure specifying a three-dimensional extent',type='structs'] +-- A three-dimensional extent is defined by the structure: include::../api/structs/VkExtent3D.txt[] + * pname:width is the width of the extent. + * pname:height is the height of the extent. + * pname:depth is the depth of the extent. + include::../validity/structs/VkExtent3D.txt[] +-- === Rectangles -// refBegin VkRect2D Structure specifying a two-dimensional subregion +[open,refpage='VkRect2D',desc='Structure specifying a two-dimensional subregion',type='structs'] +-- Rectangles are used to describe a specified rectangular region of pixels within an image or framebuffer. @@ -1330,4 +1358,8 @@ Two-dimensional rectangles are defined by the structure include::../api/structs/VkRect2D.txt[] + * pname:offset is a slink:VkOffset2D specifying the rectangle offset. + * pname:extent is a slink:VkExtent2D specifying the rectangle extent. + include::../validity/structs/VkRect2D.txt[] +-- diff --git a/doc/specs/vulkan/chapters/fxvertex.txt b/doc/specs/vulkan/chapters/fxvertex.txt index ac95facc..550320a6 100644 --- a/doc/specs/vulkan/chapters/fxvertex.txt +++ b/doc/specs/vulkan/chapters/fxvertex.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[fxvertex]] = Fixed-Function Vertex Processing @@ -272,7 +273,8 @@ descriptions as part of graphics pipeline creation. The slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState points to a structure of type sname:VkPipelineVertexInputStateCreateInfo. -// refBegin VkPipelineVertexInputStateCreateInfo Structure specifying parameters of a newly created pipeline vertex input state +[open,refpage='VkPipelineVertexInputStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline vertex input state',type='structs'] +-- The sname:VkPipelineVertexInputStateCreateInfo structure is defined as: @@ -312,11 +314,13 @@ include::../api/structs/VkPipelineVertexInputStateCreateInfo.txt[] **** include::../validity/structs/VkPipelineVertexInputStateCreateInfo.txt[] +-- Each vertex input binding is specified by an instance of the sname:VkVertexInputBindingDescription structure. -// refBegin VkVertexInputBindingDescription Structure specifying vertex input binding description +[open,refpage='VkVertexInputBindingDescription',desc='Structure specifying vertex input binding description',type='structs'] +-- The sname:VkVertexInputBindingDescription structure is defined as: @@ -340,8 +344,10 @@ include::../api/structs/VkVertexInputBindingDescription.txt[] **** include::../validity/structs/VkVertexInputBindingDescription.txt[] +-- -// refBegin VkVertexInputRate Specify rate at which vertex attributes are pulled from buffers +[open,refpage='VkVertexInputRate',desc='Specify rate at which vertex attributes are pulled from buffers',type='enums'] +-- Possible values of slink:VkVertexInputBindingDescription::pname:inputRate, specifying the rate at which vertex attributes are pulled from buffers, are: @@ -353,9 +359,10 @@ include::../api/enums/VkVertexInputRate.txt[] * ename:VK_VERTEX_INPUT_RATE_INSTANCE specifies that vertex attribute addressing is a function of the instance index. -// refEnd VkVertexInputRate +-- -// refBegin VkVertexInputAttributeDescription Structure specifying vertex input attribute description +[open,refpage='VkVertexInputAttributeDescription',desc='Structure specifying vertex input attribute description',type='structs'] +-- Each vertex input attribute is specified by an instance of the sname:VkVertexInputAttributeDescription structure. @@ -390,8 +397,10 @@ include::../api/structs/VkVertexInputAttributeDescription.txt[] **** include::../validity/structs/VkVertexInputAttributeDescription.txt[] +-- -// refBegin vkCmdBindVertexBuffers Bind vertex buffers to a command buffer +[open,refpage='vkCmdBindVertexBuffers',desc='Bind vertex buffers to a command buffer',type='protos'] +-- To bind vertex buffers to a command buffer for use in subsequent draw commands, call: @@ -437,6 +446,7 @@ commands. **** include::../validity/protos/vkCmdBindVertexBuffers.txt[] +-- The address of each attribute for each code:vertexIndex and code:instanceIndex is calculated as follows: diff --git a/doc/specs/vulkan/chapters/geometry.txt b/doc/specs/vulkan/chapters/geometry.txt index df8c68c9..8b531747 100644 --- a/doc/specs/vulkan/chapters/geometry.txt +++ b/doc/specs/vulkan/chapters/geometry.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[geometry]] = Geometry Shading diff --git a/doc/specs/vulkan/chapters/initialization.txt b/doc/specs/vulkan/chapters/initialization.txt index 21b1af38..4aedb4ad 100644 --- a/doc/specs/vulkan/chapters/initialization.txt +++ b/doc/specs/vulkan/chapters/initialization.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[initialization]] = Initialization @@ -10,7 +11,8 @@ Vulkan commands, and creating a sname:VkInstance object. [[initialization-functionpointers]] == Command Function Pointers -// refBegin vkGetInstanceProcAddr Return a function pointer for a command +[open,refpage='vkGetInstanceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction'] +-- Vulkan commands are not necessarily exposed statically on a platform. Function pointers for all Vulkan commands can: be obtained with the command: @@ -65,10 +67,10 @@ be cast to the type of the command being queried. the loader, driver or layer. include::../validity/protos/vkGetInstanceProcAddr.txt[] +-- -// refEnd vkGetInstanceProcAddr PFN_vkVoidFunction - -// refBegin vkGetDeviceProcAddr Return a function pointer for a command +[open,refpage='vkGetDeviceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction'] +-- In order to support systems with multiple Vulkan implementations comprising heterogeneous collections of hardware and software, the function pointers @@ -108,15 +110,16 @@ be cast to the type of the command being queried. include::../validity/protos/vkGetDeviceProcAddr.txt[] -// refEnd vkGetDeviceProcAddr PFN_vkVoidFunction +-- -// refBegin PFN_vkVoidFunction Dummy function pointer type returned by queries +[open,refpage='PFN_vkVoidFunction',desc='Dummy function pointer type returned by queries',type='funcpointers',xrefs='vkGetDeviceProcAddr vkGetInstanceProcAddr'] +-- The definition of tlink:PFN_vkVoidFunction is: include::../api/funcpointers/PFN_vkVoidFunction.txt[] -// refEnd PFN_vkVoidFunction vkGetDeviceProcAddr vkGetInstanceProcAddr +-- ifdef::VK_KHR_get_physical_device_properties2[] @@ -146,7 +149,8 @@ endif::VK_KHR_get_physical_device_properties2[] [[initialization-instances]] == Instances -// refBegin VkInstance Opaque handle to a instance object +[open,refpage='VkInstance',desc='Opaque handle to a instance object',type='handles'] +-- There is no global state in Vulkan and all per-application state is stored in a sname:VkInstance object. @@ -157,9 +161,10 @@ Instances are represented by sname:VkInstance handles: include::../api/handles/VkInstance.txt[] -// refEnd VkInstance +-- -// refBegin vkCreateInstance Create a new Vulkan instance +[open,refpage='vkCreateInstance',desc='Create a new Vulkan instance',type='protos'] +-- To create an instance object, call: @@ -194,8 +199,10 @@ creation to succeed. **** include::../validity/protos/vkCreateInstance.txt[] +-- -// refBegin VkInstanceCreateInfo Structure specifying parameters of a newly created instance +[open,refpage='VkInstanceCreateInfo',desc='Structure specifying parameters of a newly created instance',type='structs'] +-- The sname:VkInstanceCreateInfo structure is defined as: @@ -222,13 +229,15 @@ include::../api/structs/VkInstanceCreateInfo.txt[] names of extensions to enable. include::../validity/structs/VkInstanceCreateInfo.txt[] +-- ifdef::VK_EXT_validation_flags[] include::VK_EXT_validation_flags.txt[] endif::VK_EXT_validation_flags[] -// refBegin VkApplicationInfo Structure specifying application info +[open,refpage='VkApplicationInfo',desc='Structure specifying application info',type='structs'] +-- The sname:VkApplicationInfo structure is defined as: @@ -236,12 +245,12 @@ include::../api/structs/VkApplicationInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:pApplicationName is a pointer to a null-terminated UTF-8 string - containing the name of the application. + * pname:pApplicationName is `NULL` or is a pointer to a null-terminated + UTF-8 string containing the name of the application. * pname:applicationVersion is an unsigned integer variable containing the developer-supplied version number of the application. - * pname:pEngineName is a pointer to a null-terminated UTF-8 string - containing the name of the engine (if any) used to create the + * pname:pEngineName is `NULL` or is a pointer to a null-terminated UTF-8 + string containing the name of the engine (if any) used to create the application. * pname:engineVersion is an unsigned integer variable containing the developer-supplied version number of the engine used to create the @@ -259,8 +268,10 @@ include::../api/structs/VkApplicationInfo.txt[] requested in pname:apiVersion. include::../validity/structs/VkApplicationInfo.txt[] +-- -// refBegin vkDestroyInstance Destroy an instance of Vulkan +[open,refpage='vkDestroyInstance',desc='Destroy an instance of Vulkan',type='protos'] +-- To destroy an instance, call: @@ -284,3 +295,4 @@ include::../api/protos/vkDestroyInstance.txt[] **** include::../validity/protos/vkDestroyInstance.txt[] +-- diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt index 96774367..a4fbb818 100644 --- a/doc/specs/vulkan/chapters/interfaces.txt +++ b/doc/specs/vulkan/chapters/interfaces.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[interfaces]] = Shader Interfaces @@ -1916,8 +1917,8 @@ three-component vector of 32-bit integers. code:WorkgroupSize:: -Decorating a variable with the code:WorkgroupSize built-in decoration will -make that variable contain the dimensions of a local workgroup. +Decorating an object with the code:WorkgroupSize built-in decoration will +make that object contain the dimensions of a local workgroup. If an object is decorated with the code:WorkgroupSize decoration, this must: take precedence over any execution mode set for code:LocalSize. + diff --git a/doc/specs/vulkan/chapters/introduction.txt b/doc/specs/vulkan/chapters/introduction.txt index 785079da..5f4961ab 100644 --- a/doc/specs/vulkan/chapters/introduction.txt +++ b/doc/specs/vulkan/chapters/introduction.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[introduction]] = Introduction @@ -194,7 +195,7 @@ http://dx.doi.org/10.1109/IEEESTD.2008.4610935, August, 2008. [[data-format]] A. Garrard, _Khronos Data Format Specification, version 1.1_, https://www.khronos.org/registry/dataformat/specs/1.1/dataformat.1.1.html, -June, 2016. +June, 2017. // If the author name is placed on a standalone line, we see the mysterious // asciidoc error 'list item index: expected 2 got 10'. Apparently the 'A.' diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt index dfb403da..cf15fbb6 100644 --- a/doc/specs/vulkan/chapters/memory.txt +++ b/doc/specs/vulkan/chapters/memory.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[memory]] = Memory Allocation @@ -26,7 +27,8 @@ Rather, this can: be useful for certain embedded systems, for debugging purposes (e.g. putting a guard page after all host allocations), or for memory allocation logging. -// refBegin VkAllocationCallbacks Structure containing callback function pointers for memory allocation +[open,refpage='VkAllocationCallbacks',desc='Structure containing callback function pointers for memory allocation',type='structs'] +-- Allocators are provided by the application as a pointer to a sname:VkAllocationCallbacks structure: @@ -72,8 +74,10 @@ include::../api/structs/VkAllocationCallbacks.txt[] **** include::../validity/structs/VkAllocationCallbacks.txt[] +-- -// refBegin PFN_vkAllocationFunction Application-defined memory allocation function +[open,refpage='PFN_vkAllocationFunction',desc='Application-defined memory allocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] +-- The type of pname:pfnAllocation is: @@ -123,9 +127,10 @@ command without the requested allocation, then it may: do so, and must: not generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed allocation. -// refEnd PFN_vkAllocationFunction VkAllocationCallbacks +-- -// refBegin PFN_vkReallocationFunction Application-defined memory reallocation function +[open,refpage='PFN_vkReallocationFunction',desc='Application-defined memory reallocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] +-- The type of pname:pfnReallocation is: @@ -171,9 +176,10 @@ pname:pfnReallocation must: follow the same <>. -// refEnd PFN_vkReallocationFunction VkAllocationCallbacks +-- -// refBegin PFN_vkFreeFunction Application-defined memory free function +[open,refpage='PFN_vkFreeFunction',desc='Application-defined memory free function',type='funcpointers',xrefs='VkAllocationCallbacks'] +-- The type of pname:pfnFree is: @@ -189,9 +195,10 @@ If pname:pMemory is non-`NULL`, it must: be a pointer previously allocated by pname:pfnAllocation or pname:pfnReallocation. The application should: free this memory. -// refEnd PFN_vkFreeFunction VkAllocationCallbacks +-- -// refBegin PFN_vkInternalAllocationNotification Application-defined memory allocation notification function +[open,refpage='PFN_vkInternalAllocationNotification',desc='Application-defined memory allocation notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] +-- The type of pname:pfnInternalAllocation is: @@ -209,9 +216,10 @@ include::../api/funcpointers/PFN_vkInternalAllocationNotification.txt[] This is a purely informational callback. -// refEnd PFN_vkInternalAllocationNotification VkAllocationCallbacks +-- -// refBegin PFN_vkInternalFreeNotification Application-defined memory free notification function +[open,refpage='PFN_vkInternalFreeNotification',desc='Application-defined memory free notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] +-- The type of pname:pfnInternalFree is: @@ -227,9 +235,10 @@ include::../api/funcpointers/PFN_vkInternalFreeNotification.txt[] specifying the allocation scope of the lifetime of the allocation, as described <>. -// refEnd PFN_vkInternalFreeNotification VkAllocationCallbacks +-- -// refBegin VkSystemAllocationScope Allocation scope +[open,refpage='VkSystemAllocationScope',desc='Allocation scope',type='enums',xrefs='VkAllocationCallbacks'] +-- [[memory-host-allocation-scope]] Each allocation has an _allocation scope_ which defines its lifetime and @@ -294,7 +303,7 @@ available: * Otherwise an implementation will allocate memory through an alternative mechanism that is unspecified. -// refEnd VkSystemAllocationScope VkAllocationCallbacks +-- Objects that are allocated from pools do not specify their own allocator. When an implementation requires host memory for such an object, that memory @@ -312,7 +321,8 @@ Upon freeing executable memory, pname:pfnInternalFree will be called. An implementation will only call an informational callback for executable memory allocations and frees. -// refBegin VkInternalAllocationType Allocation type +[open,refpage='VkInternalAllocationType',desc='Allocation type',type='enums',xrefs='PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification'] +-- The pname:allocationType parameter to the pname:pfnInternalAllocation and pname:pfnInternalFree functions may: be one of the following values: @@ -322,7 +332,7 @@ include::../api/enums/VkInternalAllocationType.txt[] * ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the allocation is intended for execution by the host. -// refEnd VkInternalAllocationType PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification +-- An implementation must: only make calls into an application-provided allocator during the execution of an API command. @@ -424,7 +434,8 @@ uniform buffer objects that reside in on-device memory. Memory properties of a physical device describe the memory heaps and memory types available. -// refBegin vkGetPhysicalDeviceMemoryProperties Reports memory information for the specified physical device +[open,refpage='vkGetPhysicalDeviceMemoryProperties',desc='Reports memory information for the specified physical device',type='protos'] +-- To query memory properties, call: @@ -436,8 +447,10 @@ include::../api/protos/vkGetPhysicalDeviceMemoryProperties.txt[] are returned. include::../validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[] +-- -// refBegin VkPhysicalDeviceMemoryProperties Structure specifying physical device memory properties +[open,refpage='VkPhysicalDeviceMemoryProperties',desc='Structure specifying physical device memory properties',type='structs'] +-- The sname:VkPhysicalDeviceMemoryProperties structure is defined as: @@ -574,10 +587,12 @@ can: fallback to searching for a less optimal but guaranteed set of properties such as "0" or "host-visible and coherent". include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[] +-- ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceMemoryProperties2KHR Reports memory information for the specified physical device +[open,refpage='vkGetPhysicalDeviceMemoryProperties2KHR',desc='Reports memory information for the specified physical device',type='protos'] +-- To query memory properties, call: @@ -593,8 +608,10 @@ flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return extended information in a pname:pNext chain of output structures. include::../validity/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[] +-- -// refBegin VkPhysicalDeviceMemoryProperties2KHR Structure specifying physical device memory properties +[open,refpage='VkPhysicalDeviceMemoryProperties2KHR',desc='Structure specifying physical device memory properties',type='structs'] +-- The sname:VkPhysicalDeviceMemoryProperties2KHR structure is defined as: @@ -607,10 +624,12 @@ include::../api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[] values as in flink:vkGetPhysicalDeviceMemoryProperties. include::../validity/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[] +-- endif::VK_KHR_get_physical_device_properties2[] -// refBegin VkMemoryHeap Structure specifying a memory heap +[open,refpage='VkMemoryHeap',desc='Structure specifying a memory heap',type='structs'] +-- The sname:VkMemoryHeap structure is defined as: @@ -621,8 +640,10 @@ include::../api/structs/VkMemoryHeap.txt[] attribute flags for the heap. include::../validity/structs/VkMemoryHeap.txt[] +-- -// refBegin VkMemoryHeapFlagBits Bitmask specifying attribute flags for a heap +[open,refpage='VkMemoryHeapFlagBits',desc='Bitmask specifying attribute flags for a heap',type='enums'] +-- Bits which may: be set in slink:VkMemoryHeap::pname:flags, indicating attribute flags for the heap, are: @@ -641,9 +662,10 @@ ifdef::VK_KHX_device_group_creation[] physical device's instance of the heap. endif::VK_KHX_device_group_creation[] -// refEnd VkMemoryHeapFlagBits +-- -// refBegin VkMemoryType Structure specifying memory type +[open,refpage='VkMemoryType',desc='Structure specifying memory type',type='structs'] +-- The sname:VkMemoryType structure is defined as: @@ -656,8 +678,10 @@ include::../api/structs/VkMemoryType.txt[] properties for this memory type. include::../validity/structs/VkMemoryType.txt[] +-- -// refBegin VkMemoryPropertyFlagBits Bitmask specifying properties for a memory type +[open,refpage='VkMemoryPropertyFlagBits',desc='Bitmask specifying properties for a memory type',type='enums'] +-- Bits which may: be set in slink:VkMemoryType::pname:propertyFlags, indicating properties of a memory heap, are: @@ -688,9 +712,10 @@ include::../api/enums/VkMemoryPropertyFlagBits.txt[] implementation lazily as specified in <>. -// refEnd VkMemoryPropertyFlagBits +-- -// refBegin VkDeviceMemory Opaque handle to a device memory object +[open,refpage='VkDeviceMemory',desc='Opaque handle to a device memory object',type='handles'] +-- A Vulkan device operates on data in device memory via memory objects that are represented in the API by a sname:VkDeviceMemory handle. @@ -699,9 +724,10 @@ Memory objects are represented by sname:VkDeviceMemory handles: include::../api/handles/VkDeviceMemory.txt[] -// refEnd VkDeviceMemory +-- -// refBegin vkAllocateMemory Allocate GPU memory +[open,refpage='vkAllocateMemory',desc='Allocate GPU memory',type='protos'] +-- To allocate memory objects, call: @@ -756,8 +782,10 @@ the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY should: be returned. **** include::../validity/protos/vkAllocateMemory.txt[] +-- -// refBegin VkMemoryAllocateInfo Structure containing parameters of a memory allocation +[open,refpage='VkMemoryAllocateInfo',desc='Structure containing parameters of a memory allocation',type='structs'] +-- The sname:VkMemoryAllocateInfo structure is defined as: @@ -904,10 +932,12 @@ endif::VK_KHX_external_memory_fd[] **** include::../validity/structs/VkMemoryAllocateInfo.txt[] +-- ifdef::VK_NV_dedicated_allocation[] -// refBegin VkDedicatedAllocationMemoryAllocateInfoNV Specify a dedicated memory allocation resource +[open,refpage='VkDedicatedAllocationMemoryAllocateInfoNV',desc='Specify a dedicated memory allocation resource',type='structs'] +-- If the pname:pNext list includes a sname:VkDedicatedAllocationMemoryAllocateInfoNV structure, then that @@ -965,12 +995,14 @@ endif::VK_KHX_external_memory_win32,VK_KHX_external_memory_fd[] **** include::../validity/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[] +-- endif::VK_NV_dedicated_allocation[] ifdef::VK_KHX_external_memory[] -// refBegin VkExportMemoryAllocateInfoKHX Specify exportable handle types for a device memory object +[open,refpage='VkExportMemoryAllocateInfoKHX',desc='Specify exportable handle types for a device memory object',type='structs'] +-- When allocating memory that may: be exported to another process or Vulkan instance, add a slink:VkExportMemoryAllocateInfoKHX structure to the @@ -999,12 +1031,14 @@ include::../api/structs/VkExportMemoryAllocateInfoKHX.txt[] **** include::../validity/structs/VkExportMemoryAllocateInfoKHX.txt[] +-- endif::VK_KHX_external_memory[] ifdef::VK_KHX_external_memory_win32[] -// refBegin VkExportMemoryWin32HandleInfoKHX Structure specifying additional attributes of Windows handles exported from a memory +[open,refpage='VkExportMemoryWin32HandleInfoKHX',desc='Structure specifying additional attributes of Windows handles exported from a memory',type='structs'] +-- To specify additional attributes of NT handles exported from a memory object, add the slink:VkExportMemoryWin32HandleInfoKHX structure to the @@ -1060,8 +1094,10 @@ ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHX **** include::../validity/structs/VkExportMemoryWin32HandleInfoKHX.txt[] +-- -// refBegin VkImportMemoryWin32HandleInfoKHX - import Win32 memory created on the same physical device +[open,refpage='VkImportMemoryWin32HandleInfoKHX',desc='import Win32 memory created on the same physical device',type='structs'] +-- To import memory created on the same underlying physical device but outside of the current Vulkan instance from a Windows handle, add a @@ -1101,8 +1137,10 @@ longer needed. **** include::../validity/structs/VkImportMemoryWin32HandleInfoKHX.txt[] +-- -// refBegin vkGetMemoryWin32HandleKHX Get a Windows HANDLE for a memory object +[open,refpage='vkGetMemoryWin32HandleKHX',desc='Get a Windows HANDLE for a memory object',type='protos'] +-- To export a Windows handle representing the underlying resources of a Vulkan device memory object, call: @@ -1142,8 +1180,10 @@ using the fname:CloseHandle system call when they are no longer needed. **** include::../validity/protos/vkGetMemoryWin32HandleKHX.txt[] +-- -// refBegin vkGetMemoryWin32HandlePropertiesKHX Get Properties of External Memory Win32 Handles +[open,refpage='vkGetMemoryWin32HandlePropertiesKHX',desc='Get Properties of External Memory Win32 Handles',type='protos'] +-- Windows memory handles compatible with Vulkan may: also be created by non-Vulkan APIs using methods beyond the scope of this specification. @@ -1169,9 +1209,10 @@ include::../api/protos/vkGetMemoryWin32HandlePropertiesKHX.txt[] include::../validity/protos/vkGetMemoryWin32HandlePropertiesKHX.txt[] -// refEnd vkGetMemoryWin32HandlePropertiesKHX +-- -// refBegin VkMemoryWin32HandlePropertiesKHX Properties of External Memory Windows Handles +[open,refpage='VkMemoryWin32HandlePropertiesKHX',desc='Properties of External Memory Windows Handles',type='structs'] +-- The sname:VkMemoryWin32HandlePropertiesKHX structure returned is defined as: @@ -1182,13 +1223,14 @@ include::../api/structs/VkMemoryWin32HandlePropertiesKHX.txt[] * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified windows handle can: be imported as. -// refEnd VkMemoryWin32HandlePropertiesKHX +-- endif::VK_KHX_external_memory_win32[] ifdef::VK_KHX_external_memory_fd[] -// refBegin VkImportMemoryFdInfoKHX - import memory created on the same physical device from a file descriptor +[open,refpage='VkImportMemoryFdInfoKHX',desc='import memory created on the same physical device from a file descriptor',type='structs'] +-- To import memory created on the same underlying physical device but outside of the current Vulkan instance from a POSIX file descriptor handle, add a @@ -1226,8 +1268,10 @@ after a successful import. **** include::../validity/structs/VkImportMemoryFdInfoKHX.txt[] +-- -// refBegin vkGetMemoryFdKHX Get a POSIX file descriptor for a memory object +[open,refpage='vkGetMemoryFdKHX',desc='Get a POSIX file descriptor for a memory object',type='protos'] +-- To export a POSIX file descriptor representing the underlying resources of a Vulkan device memory object, call: @@ -1263,8 +1307,10 @@ needed, or by importing a Vulkan memory object from it. **** include::../validity/protos/vkGetMemoryFdKHX.txt[] +-- -// refBegin vkGetMemoryFdPropertiesKHX Get Properties of External Memory File Descriptors +[open,refpage='vkGetMemoryFdPropertiesKHX',desc='Get Properties of External Memory File Descriptors',type='protos'] +-- POSIX file descriptor memory handles compatible with Vulkan may: also be created by non-Vulkan APIs using methods beyond the scope of this @@ -1290,9 +1336,10 @@ include::../api/protos/vkGetMemoryFdPropertiesKHX.txt[] include::../validity/protos/vkGetMemoryFdPropertiesKHX.txt[] -// refEnd vkGetMemoryFdPropertiesKHX +-- -// refBegin VkMemoryFdPropertiesKHX Properties of External Memory File Descriptors +[open,refpage='VkMemoryFdPropertiesKHX',desc='Properties of External Memory File Descriptors',type='structs'] +-- The sname:VkMemoryFdPropertiesKHX structure returned is defined as: @@ -1303,7 +1350,7 @@ include::../api/structs/VkMemoryFdPropertiesKHX.txt[] * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified file descriptor can: be imported as. -// refEnd VkMemoryFdPropertiesKHX +-- endif::VK_KHX_external_memory_fd[] @@ -1323,7 +1370,8 @@ endif::VK_NV_external_memory_win32[] ifdef::VK_KHX_device_group[] -// refBegin VkMemoryAllocateFlagsInfoKHX Structure controlling how many instances of memory will be allocated +[open,refpage='VkMemoryAllocateFlagsInfoKHX',desc='Structure controlling how many instances of memory will be allocated',type='structs'] +-- If the pname:pNext list of slink:VkMemoryAllocateInfo includes a sname:VkMemoryAllocateFlagsInfoKHX structure, then that structure includes @@ -1378,8 +1426,10 @@ allocations. **** include::../validity/structs/VkMemoryAllocateFlagsInfoKHX.txt[] +-- -// refBegin VkMemoryAllocateFlagBitsKHX Bitmask specifying flags for a device memory allocation +[open,refpage='VkMemoryAllocateFlagBitsKHX',desc='Bitmask specifying flags for a device memory allocation',type='enums'] +-- Bits which can: be set in slink:VkMemoryAllocateFlagsInfoKHX::pname:flags, controlling device memory allocation, are: @@ -1390,11 +1440,12 @@ include::../api/enums/VkMemoryAllocateFlagBitsKHX.txt[] be allocated for the devices in slink:VkMemoryAllocateFlagsInfoKHX::pname:deviceMask. -// refEnd VkMemoryAllocateFlagBitsKHX +-- endif::VK_KHX_device_group[] -// refBegin vkFreeMemory Free GPU memory +[open,refpage='vkFreeMemory',desc='Free GPU memory',type='protos'] +-- To free a memory object, call: @@ -1424,6 +1475,15 @@ the <> section. If a memory object is mapped at the time it is freed, it is implicitly unmapped. +[NOTE] +.Note +==== +As described <>, host writes are +not implicitly flushed when the memory object is unmapped, but the +implementation must: guarantee that writes that have not been flushed do not +affect any other memory. +==== + .Valid Usage **** * [[VUID-vkFreeMemory-memory-00677]] @@ -1432,6 +1492,7 @@ unmapped. **** include::../validity/protos/vkFreeMemory.txt[] +-- [[memory-device-hostaccess]] @@ -1445,7 +1506,8 @@ ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered _mappable_. Memory objects must: be mappable in order to be successfully mapped on the host. -// refBegin vkMapMemory Map a memory object into application address space +[open,refpage='vkMapMemory',desc='Map a memory object into application address space',type='protos'] +-- To retrieve a host virtual address pointer to a region of a mappable memory object, call: @@ -1533,6 +1595,7 @@ endif::VK_KHX_device_group[] **** include::../validity/protos/vkMapMemory.txt[] +-- Two commands are provided to enable applications to work with non-coherent memory allocations: fname:vkFlushMappedMemoryRanges and @@ -1551,7 +1614,8 @@ See the description of <> for more information. ==== -// refBegin vkFlushMappedMemoryRanges Flush mapped memory ranges +[open,refpage='vkFlushMappedMemoryRanges',desc='Flush mapped memory ranges',type='protos'] +-- To flush ranges of non-coherent memory from the host caches, call: @@ -1569,17 +1633,27 @@ access, via <> from the ename:VK_ACCESS_HOST_WRITE_BIT <>. -[NOTE] -.Note -==== +[[memory-device-unmap-does-not-flush]] Unmapping non-coherent memory does not implicitly flush the mapped memory, and host writes that have not been flushed may: not ever be visible to the device. +However, implementations must: ensure that writes that have not been flushed +do not become visible to any other memory. + +[NOTE] +.Note +==== +The above guarantee avoids a potential memory corruption in scenarios where +host writes to a mapped memory object have not been flushed before the +memory is unmapped (or freed), and the virtual address range is subsequently +reused for a different mapping (or memory allocation). ==== include::../validity/protos/vkFlushMappedMemoryRanges.txt[] +-- -// refBegin vkInvalidateMappedMemoryRanges Invalidate ranges of mapped memory objects +[open,refpage='vkInvalidateMappedMemoryRanges',desc='Invalidate ranges of mapped memory objects',type='protos'] +-- To invalidate ranges of non-coherent memory from the host caches, call: @@ -1608,8 +1682,10 @@ visible before the host reads or overwrites them. ==== include::../validity/protos/vkInvalidateMappedMemoryRanges.txt[] +-- -// refBegin VkMappedMemoryRange Structure specifying a mapped memory range +[open,refpage='VkMappedMemoryRange',desc='Structure specifying a mapped memory range',type='structs'] +-- The sname:VkMappedMemoryRange structure is defined as: @@ -1651,9 +1727,11 @@ include::../api/structs/VkMappedMemoryRange.txt[] **** include::../validity/structs/VkMappedMemoryRange.txt[] +-- -// refBegin vkUnmapMemory Unmap a previously mapped memory object +[open,refpage='vkUnmapMemory',desc='Unmap a previously mapped memory object',type='protos'] +-- To unmap a memory object once host access to it is no longer needed by the application, call: @@ -1670,6 +1748,7 @@ include::../api/protos/vkUnmapMemory.txt[] **** include::../validity/protos/vkUnmapMemory.txt[] +-- [[memory-device-lazy_allocation]] @@ -1694,7 +1773,8 @@ not needed once a render pass instance has completed may: allow some implementations to never allocate memory for such attachments. ==== -// refBegin vkGetDeviceMemoryCommitment Query the current commitment for a VkDeviceMemory +[open,refpage='vkGetDeviceMemoryCommitment',desc='Query the current commitment for a VkDeviceMemory',type='protos'] +-- To determine the amount of lazily-allocated memory that is currently committed for a memory object, call: @@ -1722,13 +1802,15 @@ with. **** include::../validity/protos/vkGetDeviceMemoryCommitment.txt[] +-- ifdef::VK_KHX_device_group[] [[memory-peer-memory-features]] === Peer Memory Features -// refBegin vkGetDeviceGroupPeerMemoryFeaturesKHX Query supported peer memory features of a device +[open,refpage='vkGetDeviceGroupPeerMemoryFeaturesKHX',desc='Query supported peer memory features of a device',type='protos'] +-- _Peer memory_ is memory that is allocated for a given physical device and then bound to a resource and accessed by a different physical device, in a @@ -1766,9 +1848,10 @@ include::../api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHX.txt[] include::../validity/protos/vkGetDeviceGroupPeerMemoryFeaturesKHX.txt[] -// refEnd vkGetDeviceGroupPeerMemoryFeaturesKHX +-- -// refBegin VkPeerMemoryFeatureFlagBitsKHX Bitmask specifying supported peer memory features +[open,refpage='VkPeerMemoryFeatureFlagBitsKHX',desc='Bitmask specifying supported peer memory features',type='enums'] +-- Bits which may: be set in the value returned for flink:vkGetDeviceGroupPeerMemoryFeaturesKHX::pname:pPeerMemoryFeatures, @@ -1797,6 +1880,6 @@ For example, an application doing split-frame rendering would use framebuffer attachments that include both local and peer memory bindings, but would scissor the rendering to only update local memory. -// refEnd VkPeerMemoryFeatureFlagBitsKHX +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/pipelines.txt b/doc/specs/vulkan/chapters/pipelines.txt index 2a61621e..6e6fedda 100644 --- a/doc/specs/vulkan/chapters/pipelines.txt +++ b/doc/specs/vulkan/chapters/pipelines.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[pipelines]] = Pipelines @@ -83,14 +84,15 @@ object state will override the dynamic state. Modifying dynamic state that is not set as dynamic by the pipeline state object will lead to undefined results. -// refBegin VkPipeline Opaque handle to a pipeline object +[open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles'] +-- Compute and graphics pipelines are each represented by sname:VkPipeline handles: include::../api/handles/VkPipeline.txt[] -// refEnd VkPipeline +-- [[pipelines-compute]] @@ -105,7 +107,8 @@ an entry point from a shader module, where that entry point defines a valid compute shader, in the sname:VkPipelineShaderStageCreateInfo structure contained within the sname:VkComputePipelineCreateInfo structure. -// refBegin vkCreateComputePipelines Creates a new compute pipeline object +[open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos'] +-- To create compute pipelines, call: @@ -124,9 +127,8 @@ include::../api/protos/vkCreateComputePipelines.txt[] <> chapter. * pname:pPipelines is a pointer to an array in which the resulting compute pipeline objects are returned. -+ --- ifdef::editing-notes[] ++ [NOTE] .editing-note ==== @@ -135,7 +137,6 @@ pname:pPipelines array is created based on the corresponding element of the pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below. ==== endif::editing-notes[] --- .Valid Usage **** @@ -153,8 +154,10 @@ endif::editing-notes[] **** include::../validity/protos/vkCreateComputePipelines.txt[] +-- -// refBegin VkComputePipelineCreateInfo Structure specifying parameters of a newly created compute pipeline +[open,refpage='VkComputePipelineCreateInfo',desc='Structure specifying parameters of a newly created compute pipeline',type='structs'] +-- The sname:VkComputePipelineCreateInfo structure is defined as: @@ -213,8 +216,10 @@ sname:VkPipelineShaderStageCreateInfo. **** include::../validity/structs/VkComputePipelineCreateInfo.txt[] +-- -// refBegin VkPipelineShaderStageCreateInfo Structure specifying parameters of a newly created pipeline shader stage +[open,refpage='VkPipelineShaderStageCreateInfo',desc='Structure specifying parameters of a newly created pipeline shader stage',type='structs'] +-- The sname:VkPipelineShaderStageCreateInfo structure is defined as: @@ -313,8 +318,10 @@ include::../api/structs/VkPipelineShaderStageCreateInfo.txt[] **** include::../validity/structs/VkPipelineShaderStageCreateInfo.txt[] +-- -// refBegin VkShaderStageFlagBits Bitmask specifying a pipeline stage +[open,refpage='VkShaderStageFlagBits',desc='Bitmask specifying a pipeline stage',type='enums'] +-- Commands and structures which need to specify one or more shader stages do so using a bitmask whose bits correspond to stages. @@ -337,7 +344,7 @@ include::../api/enums/VkShaderStageFlagBits.txt[] specify all shader stages supported by the device, including all additional stages which are introduced by extensions. -// refEnd VkShaderStageFlagBits +-- [[pipelines-graphics]] @@ -346,7 +353,8 @@ include::../api/enums/VkShaderStageFlagBits.txt[] Graphics pipelines consist of multiple shader stages, multiple fixed-function pipeline stages, and a pipeline layout. -// refBegin vkCreateGraphicsPipelines Create graphics pipelines +[open,refpage='vkCreateGraphicsPipelines',desc='Create graphics pipelines',type='protos'] +-- To create graphics pipelines, call: @@ -387,8 +395,10 @@ pipeline layout. **** include::../validity/protos/vkCreateGraphicsPipelines.txt[] +-- -// refBegin VkGraphicsPipelineCreateInfo Structure specifying parameters of a newly created graphics pipeline +[open,refpage='VkGraphicsPipelineCreateInfo',desc='Structure specifying parameters of a newly created graphics pipeline',type='structs'] +-- The sname:VkGraphicsPipelineCreateInfo structure is defined as: @@ -636,10 +646,23 @@ endif::VK_NV_glsl_shader[] pname:layout must: be <> with all shaders specified in pname:pStages +ifndef::VK_NV_framebuffer_mixed_samples[] * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]] If pname:subpass uses color and/or depth/stencil attachments, then the pname:rasterizationSamples member of pname:pMultisampleState must: be the same as the sample count for those subpass attachments +endif::VK_NV_framebuffer_mixed_samples[] +ifdef::VK_NV_framebuffer_mixed_samples[] + * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01411]] + If pname:subpass has a depth/stencil attachment and depth test, stencil + test, or depth bounds test are enabled, then the + pname:rasterizationSamples member of pname:pMultisampleState must: be + the same as the sample count of the depth/stencil attachment + * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01412]] + If pname:subpass has any color attachments, then the + pname:rasterizationSamples member of pname:pMultisampleState must: be + greater than or equal to the sample count for those subpass attachments +endif::VK_NV_framebuffer_mixed_samples[] * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]] If pname:subpass does not use any color and/or depth/stencil attachments, then the pname:rasterizationSamples member of @@ -674,8 +697,10 @@ endif::VK_KHX_device_group[] **** include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[] +-- -// refBegin VkPipelineCreateFlagBits Bitmask controlling how a pipeline is created +[open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums'] +-- Possible values of the pname:flags member of slink:VkGraphicsPipelineCreateInfo and slink:VkComputePipelineCreateInfo, @@ -709,9 +734,10 @@ pipeline hierarchy. See <> for more information. -// refEnd VkPipelineCreateFlagBits +-- -// refBegin VkPipelineDynamicStateCreateInfo Structure specifying parameters of a newly created pipeline dynamic state +[open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs'] +-- The sname:VkPipelineDynamicStateCreateInfo structure is defined as: @@ -727,8 +753,10 @@ include::../api/structs/VkPipelineDynamicStateCreateInfo.txt[] dynamic state commands rather than from pipeline state creation info. include::../validity/structs/VkPipelineDynamicStateCreateInfo.txt[] +-- -// refBegin VkDynamicState Indicate which dynamic state is taken from dynamic state commands +[open,refpage='VkDynamicState',desc='Indicate which dynamic state is taken from dynamic state commands',type='enums'] +-- The source of different pieces of dynamic state is specified by the slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the @@ -816,7 +844,7 @@ ifdef::VK_EXT_discard_rectangles[] sname:VkPipelineDiscardRectangleStateCreateInfoEXT. endif::VK_EXT_discard_rectangles[] -// refEnd VkDynamicState +-- === Valid Combinations of Stages for Graphics Pipelines @@ -885,7 +913,8 @@ pipeline has valid Tessellation Control and Tessellation Evaluation shaders. [[pipelines-destruction]] == Pipeline destruction -// refBegin vkDestroyPipeline Destroy a pipeline object +[open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos'] +-- To destroy a graphics or compute pipeline, call: @@ -910,6 +939,7 @@ include::../api/protos/vkDestroyPipeline.txt[] **** include::../validity/protos/vkDestroyPipeline.txt[] +-- [[pipelines-multiple]] @@ -964,7 +994,8 @@ ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set. [[pipelines-cache]] == Pipeline Cache -// refBegin VkPipelineCache Opaque handle to a pipeline cache object +[open,refpage='VkPipelineCache',desc='Opaque handle to a pipeline cache object',type='handles'] +-- Pipeline cache objects allow the result of pipeline construction to be reused between pipelines and between runs of an application. @@ -982,9 +1013,10 @@ Pipeline cache objects are represented by sname:VkPipelineCache handles: include::../api/handles/VkPipelineCache.txt[] -// refEnd VkPipelineCache +-- -// refBegin vkCreatePipelineCache Creates a new pipeline cache +[open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos'] +-- To create pipeline cache objects, call: @@ -1030,8 +1062,10 @@ fname:vkCreateComputePipelines commands. ==== include::../validity/protos/vkCreatePipelineCache.txt[] +-- -// refBegin VkPipelineCacheCreateInfo Structure specifying parameters of a newly created pipeline cache +[open,refpage='VkPipelineCacheCreateInfo',desc='Structure specifying parameters of a newly created pipeline cache',type='structs'] +-- The sname:VkPipelineCacheCreateInfo structure is defined as: @@ -1061,8 +1095,10 @@ include::../api/structs/VkPipelineCacheCreateInfo.txt[] **** include::../validity/structs/VkPipelineCacheCreateInfo.txt[] +-- -// refBegin vkMergePipelineCaches Combine the data stores of pipeline caches +[open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos'] +-- Pipeline cache objects can: be merged using the command: @@ -1091,8 +1127,10 @@ prune duplicate entries. **** include::../validity/protos/vkMergePipelineCaches.txt[] +-- -// refBegin vkGetPipelineCacheData Get the data store from a pipeline cache +[open,refpage='vkGetPipelineCacheData',desc='Get the data store from a pipeline cache',type='protos'] +-- Data can: be retrieved from a pipeline cache object using the command: @@ -1160,27 +1198,31 @@ bytes. This value includes all fields in the header including the pipeline cache version field and the size of the length field. -// refBegin VkPipelineCacheHeaderVersion Encode pipeline cache version - -The next four bytes in the header returned by flink:vkGetPipelineCacheData -encode the pipeline cache version. -This field is interpreted as a elink:VkPipelineCacheHeaderVersion value, and -must: have one of the following values: - -include::../api/enums/VkPipelineCacheHeaderVersion.txt[] - +The next four bytes encode the pipeline cache version, as described for +elink:VkPipelineCacheHeaderVersion. A consumer of the pipeline cache should: use the cache version to interpret the remainder of the cache header. -// refEnd VkPipelineCacheHeaderVersion vkCreatePipelineCache vkGetPipelineCacheData - If pname:pDataSize is less than what is necessary to store this header, nothing will be written to pname:pData and zero will be written to pname:pDataSize. include::../validity/protos/vkGetPipelineCacheData.txt[] +-- -// refBegin vkDestroyPipelineCache Destroy a pipeline cache object +[open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData'] +-- +Possible values of the second group of four bytes in the header returned by +flink:vkGetPipelineCacheData, encoding the pipeline cache version, are: + +include::../api/enums/VkPipelineCacheHeaderVersion.txt[] + + * ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the + pipeline cache. +-- + +[open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos'] +-- To destroy a pipeline cache, call: @@ -1203,6 +1245,7 @@ include::../api/protos/vkDestroyPipelineCache.txt[] **** include::../validity/protos/vkDestroyPipelineCache.txt[] +-- [[pipelines-specialization-constants]] @@ -1226,7 +1269,8 @@ contains a parameter pname:pSpecializationInfo, which can: be `NULL` to indicate no specialization constants, or point to a sname:VkSpecializationInfo structure. -// refBegin VkSpecializationInfo Structure specifying specialization info +[open,refpage='VkSpecializationInfo',desc='Structure specifying specialization info',type='structs'] +-- The sname:VkSpecializationInfo structure is defined as: @@ -1258,8 +1302,10 @@ slink:VkSpecializationMapEntry. **** include::../validity/structs/VkSpecializationInfo.txt[] +-- -// refBegin VkSpecializationMapEntry Structure specifying a specialization map entry +[open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs'] +-- The sname:VkSpecializationMapEntry structure is defined as: @@ -1284,6 +1330,7 @@ shader, that map entry does not affect the behavior of the pipeline. **** include::../validity/structs/VkSpecializationMapEntry.txt[] +-- In human readable SPIR-V: @@ -1411,7 +1458,8 @@ OpSpecConstant declarations. [[pipelines-binding]] == Pipeline Binding -// refBegin vkCmdBindPipeline Bind a pipeline object to a command buffer +[open,refpage='vkCmdBindPipeline',desc='Bind a pipeline object to a command buffer',type='protos'] +-- Once a pipeline has been created, it can: be bound to the command buffer using the command: @@ -1461,8 +1509,10 @@ No other commands are affected by the pipeline state. **** include::../validity/protos/vkCmdBindPipeline.txt[] +-- -// refBegin VkPipelineBindPoint Specify the bind point of a pipeline object to a command buffer +[open,refpage='VkPipelineBindPoint',desc='Specify the bind point of a pipeline object to a command buffer',type='enums'] +-- Possible values of flink:vkCmdBindPipeline::pname:pipelineBindPoint, specifying the bind point of a pipeline object, are: @@ -1474,4 +1524,4 @@ include::../api/enums/VkPipelineBindPoint.txt[] * ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics pipeline. -// refEnd VkPipelineBindPoint +-- diff --git a/doc/specs/vulkan/chapters/primsrast.txt b/doc/specs/vulkan/chapters/primsrast.txt index aef3d846..fb37aa99 100644 --- a/doc/specs/vulkan/chapters/primsrast.txt +++ b/doc/specs/vulkan/chapters/primsrast.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[primsrast]] = Rasterization @@ -38,7 +39,8 @@ Several factors affect rasterization, including the members of sname:VkPipelineRasterizationStateCreateInfo and sname:VkPipelineMultisampleStateCreateInfo. -// refBegin VkPipelineRasterizationStateCreateInfo Structure specifying parameters of a newly created pipeline rasterization state +[open,refpage='VkPipelineRasterizationStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline rasterization state',type='structs'] +-- The sname:VkPipelineRasterizationStateCreateInfo structure is defined as: @@ -83,15 +85,23 @@ endif::VK_AMD_rasterization_order[] * [[VUID-VkPipelineRasterizationStateCreateInfo-depthClampEnable-00782]] If the <> feature is not enabled, pname:depthClampEnable must: be ename:VK_FALSE - * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-00783]] + * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01413]] If the <> feature is not enabled, pname:polygonMode must: be ename:VK_POLYGON_MODE_FILL +ifdef::VK_NV_fill_rectangle[] + or ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV + * [[VUID-VkPipelineRasterizationStateCreateInfo-polygonMode-01414]] + If the +VK_NV_fill_rectangle+ extension is not enabled, + pname:polygonMode must: not be ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV +endif::VK_NV_fill_rectangle[] **** include::../validity/structs/VkPipelineRasterizationStateCreateInfo.txt[] +-- -// refBegin VkPipelineMultisampleStateCreateInfo Structure specifying parameters of a newly created pipeline multisample state +[open,refpage='VkPipelineMultisampleStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline multisample state',type='structs'] +-- The sname:VkPipelineMultisampleStateCreateInfo structure is defined as: @@ -129,9 +139,17 @@ include::../api/structs/VkPipelineMultisampleStateCreateInfo.txt[] enabled, pname:alphaToOneEnable must: be ename:VK_FALSE * [[VUID-VkPipelineMultisampleStateCreateInfo-minSampleShading-00786]] pname:minSampleShading must: be in the range [eq]#[0,1]# +ifdef::VK_NV_framebuffer_mixed_samples[] + * [[VUID-VkPipelineMultisampleStateCreateInfo-rasterizationSamples-01415]] + If the subpass has any color attachments and pname:rasterizationSamples + is greater than the number of color samples, then pname:minSampleShading + must: be ename:VK_FALSE +endif::VK_NV_framebuffer_mixed_samples[] + **** include::../validity/structs/VkPipelineMultisampleStateCreateInfo.txt[] +-- Rasterization only produces fragments corresponding to pixels in the framebuffer. @@ -145,11 +163,17 @@ Surviving fragments are processed by fragment shaders. Fragment shaders determine associated data for fragments, and can: also modify or replace their assigned depth values. +ifndef::VK_NV_framebuffer_mixed_samples[] + If the subpass for which this pipeline is being created uses color and/or depth/stencil attachments, then pname:rasterizationSamples must: be the same as the sample count for those subpass attachments. -Otherwise, pname:rasterizationSamples must: follow the rules for a -<>. + +endif::VK_NV_framebuffer_mixed_samples[] + +If the subpass for which this pipeline is being created does not use color +or depth/stencil attachments, pname:rasterizationSamples must: follow the +rules for a <>. [[primsrast-discard]] @@ -177,6 +201,10 @@ includes that sample location: . <> . <> for <> +ifdef::VK_NV_fragment_coverage_to_color[] + . <> +endif::VK_NV_fragment_coverage_to_color[] + . <> . <>, <>, and color writes @@ -190,7 +218,8 @@ endif::VK_AMD_rasterization_order[] ifdef::VK_AMD_rasterization_order[] an order determined by the application. -// refBegin VkPipelineRasterizationStateRasterizationOrderAMD Structure defining rasterization order for a graphics pipeline +[open,refpage='VkPipelineRasterizationStateRasterizationOrderAMD',desc='Structure defining rasterization order for a graphics pipeline',type='structs'] +-- The rasterization order to use for a graphics pipeline is specified by adding a sname:VkPipelineRasterizationStateRasterizationOrderAMD structure @@ -215,9 +244,10 @@ specifying a sname:VkPipelineRasterizationStateRasterizationOrderAMD structure then the rasterization order used by the graphics pipeline defaults to ename:VK_RASTERIZATION_ORDER_STRICT_AMD. -// refEnd VkPipelineRasterizationStateRasterizationOrderAMD +-- -// refBegin VkRasterizationOrderAMD Specify rasterization order for a graphics pipeline +[open,refpage='VkRasterizationOrderAMD',desc='Specify rasterization order for a graphics pipeline',type='enums'] +-- Possible values of slink:VkPipelineRasterizationStateRasterizationOrderAMD::pname:rasterizationOrder, @@ -232,7 +262,7 @@ include::../api/enums/VkRasterizationOrderAMD.txt[] each primitive in a subpass may: not occur in <>. -// refEnd VkRasterizationOrderAMD +-- endif::VK_AMD_rasterization_order[] @@ -444,7 +474,8 @@ centered on the line segment. Each line segment has an associated width that controls the width of that rectangle. -// refBegin vkCmdSetLineWidth Set the dynamic line width state +[open,refpage='vkCmdSetLineWidth',desc='Set the dynamic line width state',type='protos'] +-- The line width is specified by the slink:VkPipelineRasterizationStateCreateInfo::pname:lineWidth property of @@ -470,6 +501,7 @@ include::../api/protos/vkCmdSetLineWidth.txt[] **** include::../validity/protos/vkCmdSetLineWidth.txt[] +-- Not all line widths need be supported for line segment rasterization, but width 1.0 antialiased segments must: be provided. @@ -599,7 +631,8 @@ structure. [[primsrast-polygons-basic]] === Basic Polygon Rasterization -// refBegin VkFrontFace Interpret polygon front-facing orientation +[open,refpage='VkFrontFace',desc='Interpret polygon front-facing orientation',type='enums'] +-- The first step of polygon rasterization is to determine whether the triangle is _back-facing_ or _front-facing_. @@ -634,9 +667,10 @@ include::../api/enums/VkFrontFace.txt[] Any triangle which is not front-facing is back-facing, including zero-area triangles. -// refEnd VkFrontFace +-- -// refBegin VkCullModeFlagBits Bitmask controlling triangle culling +[open,refpage='VkCullModeFlagBits',desc='Bitmask controlling triangle culling',type='enums'] +-- Once the orientation of triangles is determined, they are culled according to the slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode property @@ -656,7 +690,7 @@ include::../api/enums/VkCullModeFlagBits.txt[] Following culling, fragments are produced for any triangles which have not been discarded. -// refEnd VkCullModeFlagBits +-- The rule for determining which fragments are produced by polygon rasterization is called _point sampling_. @@ -784,7 +818,8 @@ independently and a division performed for each fragment). [[primsrast-polygonmode]] === Polygon Mode -// refBegin VkPolygonMode Control polygon rasterization mode +[open,refpage='VkPolygonMode',desc='Control polygon rasterization mode',type='enums'] +-- Possible values of the slink:VkPipelineRasterizationStateCreateInfo::pname:polygonMode property of @@ -799,18 +834,41 @@ include::../api/enums/VkPolygonMode.txt[] line segments. * ename:VK_POLYGON_MODE_FILL specifies that polygons are rendered using the polygon rasterization rules in this section. +ifdef::VK_NV_fill_rectangle[] + * ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV specifies that polygons are + rendered using polygon rasterization rules, modified to consider a + sample within the primitive if the sample location is inside the + axis-aligned bounding box of the triangle after projection. + Note that the barycentric weights used in attribute interpolation can: + extend outside the range [eq]#[0,1]# when these primitives are shaded. + Special treatment is given to a sample position on the boundary edge of + the bounding box. + In such a case, if two rectangles lie on either side of a common edge + (with identical endpoints) on which a sample position lies, then exactly + one of the triangles must: produce a fragment that covers that sample + during rasterization. ++ +Polygons rendered in ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode may: be + clipped by the frustum or by user clip planes. + If clipping is applied, the triangle is culled rather than clipped. ++ +Area calculation and facingness are determined for + ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV mode using the triangle's + vertices. +endif::VK_NV_fill_rectangle[] These modes affect only the final rasterization of polygons: in particular, a polygon's vertices are shaded and the polygon is clipped and possibly culled before these modes are applied. -// refEnd VkPolygonMode +-- [[primsrast-depthbias]] === Depth Bias -// refBegin vkCmdSetDepthBias Set the depth bias dynamic state +[open,refpage='vkCmdSetDepthBias',desc='Set the depth bias dynamic state',type='protos'] +-- The depth values of all fragments generated by the rasterization of a polygon can: be offset by a single value that is computed for that polygon. @@ -883,6 +941,14 @@ resolvable difference, [eq]#r#, for the given primitive is defined as :: [eq]#r = 2^e-n^# +ifdef::VK_NV_fill_rectangle[] +If a triangle is rasterized using the +ename:VK_POLYGON_MODE_FILL_RECTANGLE_NV polygon mode, then this minimum +resolvable difference may: not be resolvable for samples outside of the +triangle, where the depth is extrapolated. +endif::VK_NV_fill_rectangle[] + + If no depth buffer is present, [eq]#r# is undefined. The bias value [eq]#o# for a polygon is @@ -923,4 +989,5 @@ floating-point representation. **** include::../validity/protos/vkCmdSetDepthBias.txt[] +-- diff --git a/doc/specs/vulkan/chapters/queries.txt b/doc/specs/vulkan/chapters/queries.txt index 1b2cdcea..2fc43dc4 100644 --- a/doc/specs/vulkan/chapters/queries.txt +++ b/doc/specs/vulkan/chapters/queries.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[queries]] = Queries @@ -21,7 +22,8 @@ Timestamp Queries>>. [[queries-pools]] == Query Pools -// refBegin VkQueryPool Opaque handle to a query pool object +[open,refpage='VkQueryPool',desc='Opaque handle to a query pool object',type='handles'] +-- Queries are managed using _query pool_ objects. Each query pool is a collection of a specific number of queries of a @@ -31,9 +33,10 @@ Query pools are represented by sname:VkQueryPool handles: include::../api/handles/VkQueryPool.txt[] -// refEnd VkQueryPool +-- -// refBegin vkCreateQueryPool Create a new query pool object +[open,refpage='vkCreateQueryPool',desc='Create a new query pool object',type='protos'] +-- To create a query pool, call: @@ -49,8 +52,10 @@ include::../api/protos/vkCreateQueryPool.txt[] resulting query pool object is returned. include::../validity/protos/vkCreateQueryPool.txt[] +-- -// refBegin VkQueryPoolCreateInfo Structure specifying parameters of a newly created query pool +[open,refpage='VkQueryPoolCreateInfo',desc='Structure specifying parameters of a newly created query pool',type='structs'] +-- The sname:VkQueryPoolCreateInfo structure is defined as: @@ -83,8 +88,10 @@ ename:VK_QUERY_TYPE_PIPELINE_STATISTICS. **** include::../validity/structs/VkQueryPoolCreateInfo.txt[] +-- -// refBegin vkDestroyQueryPool Destroy a query pool object +[open,refpage='vkDestroyQueryPool',desc='Destroy a query pool object',type='protos'] +-- To destroy a query pool, call: @@ -109,8 +116,10 @@ include::../api/protos/vkDestroyQueryPool.txt[] **** include::../validity/protos/vkDestroyQueryPool.txt[] +-- -// refBegin VkQueryType Specify the type of queries managed by a query pool +[open,refpage='VkQueryType',desc='Specify the type of queries managed by a query pool',type='enums'] +-- Possible values of slink:VkQueryPoolCreateInfo::pname:queryType, specifying the type of queries managed by the pool, are: @@ -124,7 +133,7 @@ include::../api/enums/VkQueryType.txt[] * ename:VK_QUERY_TYPE_TIMESTAMP specifies a <>. -// refEnd VkQueryType +-- [[queries-operation]] @@ -175,7 +184,8 @@ command on the same physical device. endif::VK_KHX_device_group[] -// refBegin vkCmdResetQueryPool Reset queries in a query pool +[open,refpage='vkCmdResetQueryPool',desc='Reset queries in a query pool',type='protos'] +-- To reset a range of queries in a query pool, call: @@ -203,6 +213,7 @@ unavailable. **** include::../validity/protos/vkCmdResetQueryPool.txt[] +-- Once queries are reset and ready for use, query commands can: be issued to a command buffer. @@ -247,7 +258,8 @@ must: begin and end in the same subpass. endif::VK_KHX_multiview[] -// refBegin vkCmdBeginQuery Begin a query +[open,refpage='vkCmdBeginQuery',desc='Begin a query',type='protos'] +-- To begin a query, call: @@ -323,8 +335,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdBeginQuery.txt[] +-- -// refBegin VkQueryControlFlagBits Bitmask specifying constraints on a query +[open,refpage='VkQueryControlFlagBits',desc='Bitmask specifying constraints on a query',type='enums'] +-- Bits which can: be set in flink:vkCmdBeginQuery::pname:flags, specifying constraints on the types of queries that can: be performed, are: @@ -334,9 +348,10 @@ include::../api/enums/VkQueryControlFlagBits.txt[] * ename:VK_QUERY_CONTROL_PRECISE_BIT specifies the precision of <>. -// refEnd VkQueryControlFlagBits +-- -// refBegin vkCmdEndQuery Ends a query +[open,refpage='vkCmdEndQuery',desc='Ends a query',type='protos'] +-- To end a query after the set of desired draw or dispatch commands is executed, call: @@ -381,6 +396,7 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdEndQuery.txt[] +-- [[queries-operation-memorylayout]] An application can: retrieve results either by requesting they be written @@ -409,7 +425,8 @@ In either case, the layout in memory is defined as follows: large as the size of the array of integers corresponding to a single query, the values written to memory are undefined. -// refBegin vkGetQueryPoolResults Copy results of queries in a query pool to a host memory region +[open,refpage='vkGetQueryPoolResults',desc='Copy results of queries in a query pool to a host memory region',type='protos'] +-- To retrieve status and results for a set of queries, call: @@ -539,8 +556,10 @@ e.g. to read the availability status before reading the results. **** include::../validity/protos/vkGetQueryPoolResults.txt[] +-- -// refBegin VkQueryResultFlagBits Bitmask specifying how and when query results are returned +[open,refpage='VkQueryResultFlagBits',desc='Bitmask specifying how and when query results are returned',type='enums'] +-- Bits which can: be set in flink:vkGetQueryPoolResults::pname:flags and flink:vkCmdCopyQueryPoolResults::pname:flags, specifying how and when @@ -559,9 +578,10 @@ include::../api/enums/VkQueryResultFlagBits.txt[] * ename:VK_QUERY_RESULT_PARTIAL_BIT specifies that returning partial results is acceptable. -// refEnd VkQueryResultFlagBits +-- -// refBegin vkCmdCopyQueryPoolResults Copy the results of queries in a query pool to a buffer object +[open,refpage='vkCmdCopyQueryPoolResults',desc='Copy the results of queries in a query pool to a buffer object',type='protos'] +-- To copy query statuses and numerical results directly to buffer memory, call: @@ -669,6 +689,7 @@ before using the results. **** include::../validity/protos/vkCmdCopyQueryPoolResults.txt[] +-- [[queries-operation-undefined]] @@ -750,7 +771,8 @@ finished. At least one statistic counter relevant to the operations supported on the recording command buffer must: be enabled. -// refBegin VkQueryPipelineStatisticFlagBits Bitmask specifying queried pipeline statistics +[open,refpage='VkQueryPipelineStatisticFlagBits',desc='Bitmask specifying queried pipeline statistics',type='enums'] +-- Bits which can: be set to individually enable pipeline statistics counters for query pools with slink:VkQueryPoolCreateInfo::pname:pipelineStatistics, @@ -859,7 +881,7 @@ The application can: copy the result to a buffer (via fname:vkCmdCopyQueryPoolResults), or request it be put into host memory (via fname:vkGetQueryPoolResults). -// refEnd VkQueryPipelineStatisticFlagBits +-- [[queries-timestamps]] @@ -893,7 +915,8 @@ by 1 can: be obtained from sname:VkPhysicalDeviceLimits::pname:timestampPeriod after a call to fname:vkGetPhysicalDeviceProperties. -// refBegin vkCmdWriteTimestamp Write a device timestamp into a query object +[open,refpage='vkCmdWriteTimestamp',desc='Write a device timestamp into a query object',type='protos'] +-- To request a timestamp, call: @@ -963,6 +986,9 @@ endif::VK_KHX_multiview[] .Valid Usage **** + * [[VUID-vkCmdWriteTimestamp-queryPool-01416]] + pname:queryPool must: have been created with a pname:queryType of + ename:VK_QUERY_TYPE_TIMESTAMP * [[VUID-vkCmdWriteTimestamp-queryPool-00828]] The query identified by pname:queryPool and pname:query must: be _unavailable_ @@ -981,3 +1007,4 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdWriteTimestamp.txt[] +-- diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index ca964ee6..b5f5774c 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -1,10 +1,12 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[renderpass]] = Render Pass -// refBegin VkRenderPass Opaque handle to a render pass object +[open,refpage='VkRenderPass',desc='Opaque handle to a render pass object',type='handles'] +-- A _render pass_ represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are @@ -15,7 +17,7 @@ Render passes are represented by sname:VkRenderPass handles: include::../api/handles/VkRenderPass.txt[] -// refEnd VkRenderPass +-- An _attachment description_ describes the properties of an attachment including its format, sample count, and how its contents are treated at the @@ -104,7 +106,8 @@ operations are performed in <>. [[renderpass-creation]] == Render Pass Creation -// refBegin vkCreateRenderPass Create a new render pass object +[open,refpage='vkCreateRenderPass',desc='Create a new render pass object',type='protos'] +-- To create a render pass, call: @@ -120,8 +123,10 @@ include::../api/protos/vkCreateRenderPass.txt[] resulting render pass object is returned. include::../validity/protos/vkCreateRenderPass.txt[] +-- -// refBegin VkRenderPassCreateInfo Structure specifying parameters of a newly created render pass +[open,refpage='VkRenderPassCreateInfo',desc='Structure specifying parameters of a newly created render pass',type='structs'] +-- The sname:VkRenderPassCreateInfo structure is defined as: @@ -201,11 +206,13 @@ include::../api/structs/VkRenderPassCreateInfo.txt[] **** include::../validity/structs/VkRenderPassCreateInfo.txt[] +-- ifdef::VK_KHX_multiview[] [[renderpass-multiview]] -// refBegin VkRenderPassMultiviewCreateInfoKHX Structure containing multiview info for all subpasses +[open,refpage='VkRenderPassMultiviewCreateInfoKHX',desc='Structure containing multiview info for all subpasses',type='structs'] +-- If the sname:VkRenderPassCreateInfo::pname:pNext list includes a sname:VkRenderPassMultiviewCreateInfoKHX structure, then that structure @@ -351,10 +358,12 @@ endif::VK_NVX_multiview_per_view_attributes[] **** include::../validity/structs/VkRenderPassMultiviewCreateInfoKHX.txt[] +-- endif::VK_KHX_multiview[] -// refBegin VkAttachmentDescription Structure specifying an attachment description +[open,refpage='VkAttachmentDescription',desc='Structure specifying an attachment description',type='structs'] +-- The sname:VkAttachmentDescription structure is defined as: @@ -460,8 +469,10 @@ This is described in more detail below. **** include::../validity/structs/VkAttachmentDescription.txt[] +-- -// refBegin VkAttachmentDescriptionFlagBits Bitmask specifying additional properties of an attachment +[open,refpage='VkAttachmentDescriptionFlagBits',desc='Bitmask specifying additional properties of an attachment',type='enums'] +-- Bits which can: be set in slink:VkAttachmentDescription::pname:flags describing additional properties of the attachment are: @@ -471,9 +482,10 @@ include::../api/enums/VkAttachmentDescriptionFlagBits.txt[] * ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT specifies that the attachment aliases the same device memory as other attachments. -// refEnd VkAttachmentDescriptionFlagBits +-- -// refBegin VkAttachmentLoadOp Specify how contents of an attachment are treated at the beginning of a subpass +[open,refpage='VkAttachmentLoadOp',desc='Specify how contents of an attachment are treated at the beginning of a subpass',type='enums'] +-- Possible values of slink:VkAttachmentDescription::pname:loadOp and pname:stencilLoadOp, specifying how the contents of the attachment are @@ -502,9 +514,10 @@ include::../api/enums/VkAttachmentLoadOp.txt[] For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -// refEnd VkAttachmentLoadOp +-- -// refBegin VkAttachmentStoreOp Specify how contents of an attachment are treated at the end of a subpass +[open,refpage='VkAttachmentStoreOp',desc='Specify how contents of an attachment are treated at the end of a subpass',type='enums'] +-- Possible values of slink:VkAttachmentDescription::pname:storeOp and pname:stencilStoreOp, specifying how the contents of the attachment are @@ -526,7 +539,7 @@ include::../api/enums/VkAttachmentStoreOp.txt[] For attachments with a color format, this uses the access type ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT. -// refEnd VkAttachmentStoreOp +-- ifdef::editing-notes[] [NOTE] @@ -594,7 +607,8 @@ and using these additional aliases may: allow more efficient clearing of the attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR. ==== -// refBegin VkSubpassDescription Structure specifying a subpass description +[open,refpage='VkSubpassDescription',desc='Structure specifying a subpass description',type='structs'] +-- The sname:VkSubpassDescription structure is defined as: @@ -697,10 +711,15 @@ attachment. * [[VUID-VkSubpassDescription-pResolveAttachments-00850]] Any given element of pname:pResolveAttachments must: have the same elink:VkFormat as its corresponding color attachment - * [[VUID-VkSubpassDescription-pColorAttachments-00851]] - All attachments in pname:pColorAttachments and - pname:pDepthStencilAttachment that are not ename:VK_ATTACHMENT_UNUSED - must: have the same sample count + * [[VUID-VkSubpassDescription-pColorAttachments-01417]] + All attachments in pname:pColorAttachments that are not + ename:VK_ATTACHMENT_UNUSED must: have the same sample count +ifndef::VK_NV_framebuffer_mixed_samples[] + * [[VUID-VkSubpassDescription-pDepthStencilAttachment-01418]] + If pname:pDepthStencilAttachment is not ename:VK_ATTACHMENT_UNUSED and + any attachments in pname:pColorAttachments are not + ename:VK_ATTACHMENT_UNUSED, they must: have the same sample count +endif::VK_NV_framebuffer_mixed_samples[] * [[VUID-VkSubpassDescription-None-00852]] If any input attachments are ename:VK_ATTACHMENT_UNUSED, then any pipelines bound during the subpass must: not access those input @@ -723,8 +742,10 @@ endif::VK_NVX_multiview_per_view_attributes[] **** include::../validity/structs/VkSubpassDescription.txt[] +-- -// refBegin VkSubpassDescriptionFlagBits Bitmask specifying usage of a subpass +[open,refpage='VkSubpassDescriptionFlagBits',desc='Bitmask specifying usage of a subpass',type='enums'] +-- Bits which can: be set in slink:VkSubpassDescription::pname:flags, specifying usage of the subpass, are: @@ -744,9 +765,10 @@ ifdef::VK_NVX_multiview_per_view_attributes[] Per-view viewport mask can: also be used. endif::VK_NVX_multiview_per_view_attributes[] -// refEnd VkSubpassDescriptionFlagBits +-- -// refBegin VkAttachmentReference Structure specifying an attachment reference +[open,refpage='VkAttachmentReference',desc='Structure specifying an attachment reference',type='structs'] +-- The sname:VkAttachmentReference structure is defined as: @@ -768,8 +790,10 @@ include::../api/structs/VkAttachmentReference.txt[] **** include::../validity/structs/VkAttachmentReference.txt[] +-- -// refBegin VkSubpassDependency Structure specifying a subpass dependency +[open,refpage='VkSubpassDependency',desc='Structure specifying a subpass dependency',type='structs'] +-- The sname:VkSubpassDependency structure is defined as: @@ -927,6 +951,7 @@ endif::VK_KHX_multiview[] **** include::../validity/structs/VkSubpassDependency.txt[] +-- ifdef::VK_KHX_multiview[] @@ -980,7 +1005,7 @@ exists from ename:VK_SUBPASS_EXTERNAL to the first subpass it is used in. The subpass dependency operates as if defined with the following parameters: [source,c] ----- +--------------------------------------------------- VkSubpassDependency implicitDependency = { .srcSubpass = VK_SUBPASS_EXTERNAL; .dstSubpass = firstSubpass; // First subpass attachment is used in @@ -994,7 +1019,7 @@ VkSubpassDependency implicitDependency = { VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT; .dependencyFlags = 0; }; ----- +--------------------------------------------------- Similarly, if there is no subpass dependency from the last subpass that uses an attachment to ename:VK_SUBPASS_EXTERNAL, then an implicit subpass @@ -1003,7 +1028,7 @@ ename:VK_SUBPASS_EXTERNAL. The subpass dependency operates as if defined with the following parameters: [source,c] ----- +--------------------------------------------------- VkSubpassDependency implicitDependency = { .srcSubpass = lastSubpass; // Last subpass attachment is used in .dstSubpass = VK_SUBPASS_EXTERNAL; @@ -1017,7 +1042,7 @@ VkSubpassDependency implicitDependency = { .dstAccessMask = 0; .dependencyFlags = 0; }; ----- +--------------------------------------------------- [[renderpass-layout-transitions]] As subpasses may: overlap or execute out of order with regards to other @@ -1067,7 +1092,7 @@ each layout. The subpass dependency operates as if defined with the following parameters: [source,c] ----- +--------------------------------------------------- // Used for input attachments VkPipelineStageFlags inputAttachmentStages = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT; VkAccessFlags inputAttachmentAccess = VK_ACCESS_INPUT_ATTACHMENT_READ_BIT; @@ -1085,7 +1110,7 @@ VkSubpassDependency implicitDependency = { .dstAccessMask = inputAttachmentAccess | depthStencilAttachmentAccess; .dependencyFlags = 0; }; ----- +--------------------------------------------------- [[renderpass-feedbackloop]] If a subpass uses the same attachment as both an input attachment and either @@ -1131,7 +1156,8 @@ ename:VK_IMAGE_LAYOUT_GENERAL layout. An attachment must: not be used as both a depth/stencil attachment and a color attachment. -// refBegin vkDestroyRenderPass Destroy a render pass object +[open,refpage='vkDestroyRenderPass',desc='Destroy a render pass object',type='protos'] +-- To destroy a render pass, call: @@ -1156,6 +1182,7 @@ include::../api/protos/vkDestroyRenderPass.txt[] **** include::../validity/protos/vkDestroyRenderPass.txt[] +-- [[renderpass-compatibility]] @@ -1189,7 +1216,8 @@ same render pass or a compatible render pass. == Framebuffers -// refBegin VkFramebuffer Opaque handle to a framebuffer object +[open,refpage='VkFramebuffer',desc='Opaque handle to a framebuffer object',type='handles'] +-- Render passes operate in conjunction with _framebuffers_. Framebuffers represent a collection of specific memory attachments that a @@ -1199,9 +1227,10 @@ Framebuffers are represented by sname:VkFramebuffer handles: include::../api/handles/VkFramebuffer.txt[] -// refEnd VkFramebuffer +-- -// refBegin vkCreateFramebuffer Create a new framebuffer object +[open,refpage='vkCreateFramebuffer',desc='Create a new framebuffer object',type='protos'] +-- To create a framebuffer, call: @@ -1216,8 +1245,10 @@ include::../api/protos/vkCreateFramebuffer.txt[] resulting framebuffer object is returned. include::../validity/protos/vkCreateFramebuffer.txt[] +-- -// refBegin VkFramebufferCreateInfo Structure specifying parameters of a newly created framebuffer +[open,refpage='VkFramebufferCreateInfo',desc='Structure specifying parameters of a newly created framebuffer',type='structs'] +-- The sname:VkFramebufferCreateInfo structure is defined as: @@ -1327,8 +1358,10 @@ endif::VK_KHR_maintenance1[] **** include::../validity/structs/VkFramebufferCreateInfo.txt[] +-- -// refBegin vkDestroyFramebuffer Destroy a framebuffer object +[open,refpage='vkDestroyFramebuffer',desc='Destroy a framebuffer object',type='protos'] +-- To destroy a framebuffer, call: @@ -1353,6 +1386,7 @@ include::../api/protos/vkDestroyFramebuffer.txt[] **** include::../validity/protos/vkDestroyFramebuffer.txt[] +-- [[renderpass-commands]] @@ -1363,7 +1397,8 @@ at a time, by beginning a render pass instance, iterating over the subpasses to record commands for that subpass, and then ending the render pass instance. -// refBegin vkCmdBeginRenderPass Begin a new render pass +[open,refpage='vkCmdBeginRenderPass',desc='Begin a new render pass',type='protos'] +-- To begin a render pass instance, call: @@ -1449,8 +1484,10 @@ record the commands for the first subpass of that render pass. **** include::../validity/protos/vkCmdBeginRenderPass.txt[] +-- -// refBegin VkRenderPassBeginInfo Structure specifying render pass begin info +[open,refpage='VkRenderPassBeginInfo',desc='Structure specifying render pass begin info',type='structs'] +-- The sname:VkRenderPassBeginInfo structure is defined as: @@ -1518,8 +1555,10 @@ pass. **** include::../validity/structs/VkRenderPassBeginInfo.txt[] +-- -// refBegin VkSubpassContents Specify how commands in the first subpass of a render pass are provided +[open,refpage='VkSubpassContents',desc='Specify how commands in the first subpass of a render pass are provided',type='enums'] +-- Possible values of flink:vkCmdBeginRenderPass::pname:contents, specifying how the commands in the first subpass will be provided, are: @@ -1535,11 +1574,12 @@ include::../api/enums/VkSubpassContents.txt[] only valid command on the command buffer until flink:vkCmdNextSubpass or flink:vkCmdEndRenderPass. -// refEnd VkSubpassContents +-- ifdef::VK_KHX_device_group[] -// refBegin VkDeviceGroupRenderPassBeginInfoKHX Set the initial device mask and render areas for a render pass instance +[open,refpage='VkDeviceGroupRenderPassBeginInfoKHX',desc='Set the initial device mask and render areas for a render pass instance',type='structs'] +-- If the pname:pNext list of slink:VkRenderPassBeginInfo includes a sname:VkDeviceGroupRenderPassBeginInfoKHX structure, then that structure @@ -1595,10 +1635,12 @@ devices. **** include::../validity/structs/VkDeviceGroupRenderPassBeginInfoKHX.txt[] +-- endif::VK_KHX_device_group[] -// refBegin vkGetRenderAreaGranularity Returns the granularity for optimal render area +[open,refpage='vkGetRenderAreaGranularity',desc='Returns the granularity for optimal render area',type='protos'] +-- To query the render area granularity, call: @@ -1632,8 +1674,10 @@ Similarly, pipeline barriers are valid even if their effect extends outside the render area. include::../validity/protos/vkGetRenderAreaGranularity.txt[] +-- -// refBegin vkCmdNextSubpass Transition to the next subpass of a render pass +[open,refpage='vkCmdNextSubpass',desc='Transition to the next subpass of a render pass',type='protos'] +-- To transition to the next subpass in the render pass instance after recording the commands for a subpass, call: @@ -1674,8 +1718,10 @@ commands for that subpass. **** include::../validity/protos/vkCmdNextSubpass.txt[] +-- -// refBegin vkCmdEndRenderPass End the current render pass +[open,refpage='vkCmdEndRenderPass',desc='End the current render pass',type='protos'] +-- To record a command to end a render pass instance after recording the commands for the last subpass, call: @@ -1696,4 +1742,5 @@ the final subpass. **** include::../validity/protos/vkCmdEndRenderPass.txt[] +-- diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index 22894544..af0efa54 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[resources]] = Resource Creation @@ -14,7 +15,8 @@ metadata. [[resources-buffers]] == Buffers -// refBegin VkBuffer Opaque handle to a buffer object +[open,refpage='VkBuffer',desc='Opaque handle to a buffer object',type='handles'] +-- Buffers represent linear arrays of data which are used for various purposes by binding them to a graphics or compute pipeline via descriptor sets or via @@ -25,9 +27,10 @@ Buffers are represented by sname:VkBuffer handles: include::../api/handles/VkBuffer.txt[] -// refEnd VkBuffer +-- -// refBegin vkCreateBuffer Create a new buffer object +[open,refpage='vkCreateBuffer',desc='Create a new buffer object',type='protos'] +-- To create buffers, call: @@ -53,8 +56,10 @@ include::../api/protos/vkCreateBuffer.txt[] **** include::../validity/protos/vkCreateBuffer.txt[] +-- -// refBegin VkBufferCreateInfo Structure specifying the parameters of a newly created buffer object +[open,refpage='VkBufferCreateInfo',desc='Structure specifying the parameters of a newly created buffer object',type='structs'] +-- The sname:VkBufferCreateInfo structure is defined as: @@ -67,8 +72,6 @@ include::../api/structs/VkBufferCreateInfo.txt[] * pname:size is the size in bytes of the buffer to be created. * pname:usage is a bitmask of elink:VkBufferUsageFlagBits specifying allowed usages of the buffer. - Any combination of bits can: be specified for pname:usage, but at least - one of the bits must: be set in order to create a valid buffer. * pname:sharingMode is a elink:VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families. * pname:queueFamilyIndexCount is the number of entries in the @@ -97,18 +100,23 @@ endif::editing-notes[] * [[VUID-VkBufferCreateInfo-sharingMode-00914]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, pname:queueFamilyIndexCount must: be greater than `1` +ifndef::VK_KHR_get_physical_device_properties2[] * [[VUID-VkBufferCreateInfo-sharingMode-01391]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element of pname:pQueueFamilyIndices must: be unique and must: be less than pname:pQueueFamilyPropertyCount returned by -ifndef::VK_KHR_get_physical_device_properties2[] - flink:vkGetPhysicalDeviceQueueFamilyProperties + flink:vkGetPhysicalDeviceQueueFamilyProperties for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] ifdef::VK_KHR_get_physical_device_properties2[] - either flink:vkGetPhysicalDeviceQueueFamilyProperties or - flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR + * [[VUID-VkBufferCreateInfo-sharingMode-01419]] + If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element + of pname:pQueueFamilyIndices must: be unique and must: be less than + pname:pQueueFamilyPropertyCount returned by either + flink:vkGetPhysicalDeviceQueueFamilyProperties or + flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] - for the pname:physicalDevice that was used to create pname:device * [[VUID-VkBufferCreateInfo-flags-00915]] If the <> feature is not enabled, pname:flags must: not contain @@ -150,8 +158,10 @@ endif::VK_KHX_external_memory[] **** include::../validity/structs/VkBufferCreateInfo.txt[] +-- -// refBegin VkBufferUsageFlagBits Bitmask specifying allowed usage of a buffer +[open,refpage='VkBufferUsageFlagBits',desc='Bitmask specifying allowed usage of a buffer',type='enums'] +-- Bits which can: be set in slink:VkBufferCreateInfo::pname:usage, specifying usage behavior of a buffer, are: @@ -198,9 +208,10 @@ ifdef::VK_NVX_device_generated_commands[] pname:sequencesIndexBuffer member of sname:VkCmdProcessCommandsInfoNVX endif::VK_NVX_device_generated_commands[] -// refEnd VkBufferUsageFlagBits +-- -// refBegin VkBufferCreateFlagBits Bitmask specifying additional parameters of a buffer +[open,refpage='VkBufferCreateFlagBits',desc='Bitmask specifying additional parameters of a buffer',type='enums'] +-- Bits which can: be set in slink:VkBufferCreateInfo::pname:flags, specifying additional parameters of a buffer, are: @@ -224,11 +235,12 @@ See <> and <> for details of the sparse memory features supported on a device. -// refEnd VkBufferCreateFlagBits +-- ifdef::VK_NV_dedicated_allocation[] -// refBegin VkDedicatedAllocationBufferCreateInfoNV Specify that a buffer is bound to a dedicated memory resource +[open,refpage='VkDedicatedAllocationBufferCreateInfoNV',desc='Specify that a buffer is bound to a dedicated memory resource',type='structs'] +-- If the pname:pNext list includes a sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure @@ -255,12 +267,14 @@ include::../api/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] **** include::../validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] +-- endif::VK_NV_dedicated_allocation[] ifdef::VK_KHX_external_memory[] -// refBegin VkExternalMemoryBufferCreateInfoKHX Specify that a buffer may be backed by external memory +[open,refpage='VkExternalMemoryBufferCreateInfoKHX',desc='Specify that a buffer may be backed by external memory',type='structs'] +-- To define a set of external memory handle types that may: be used as backing store for a buffer, add a slink:VkExternalMemoryBufferCreateInfoKHX @@ -277,10 +291,12 @@ include::../api/structs/VkExternalMemoryBufferCreateInfoKHX.txt[] external memory handle types. include::../validity/structs/VkExternalMemoryBufferCreateInfoKHX.txt[] +-- endif::VK_KHX_external_memory[] -// refBegin vkDestroyBuffer Destroy a buffer object +[open,refpage='vkDestroyBuffer',desc='Destroy a buffer object',type='protos'] +-- To destroy a buffer, call: @@ -305,12 +321,14 @@ include::../api/protos/vkDestroyBuffer.txt[] **** include::../validity/protos/vkDestroyBuffer.txt[] +-- [[resources-buffer-views]] == Buffer Views -// refBegin VkBufferView Opaque handle to a buffer view object +[open,refpage='VkBufferView',desc='Opaque handle to a buffer view object',type='handles'] +-- A _buffer view_ represents a contiguous range of a buffer and a specific format to be used to interpret the data. @@ -326,9 +344,10 @@ Buffer views are represented by sname:VkBufferView handles: include::../api/handles/VkBufferView.txt[] -// refEnd VkBufferView +-- -// refBegin vkCreateBufferView Create a new buffer view object +[open,refpage='vkCreateBufferView',desc='Create a new buffer view object',type='protos'] +-- To create a buffer view, call: @@ -344,8 +363,10 @@ include::../api/protos/vkCreateBufferView.txt[] buffer view object is returned. include::../validity/protos/vkCreateBufferView.txt[] +-- -// refBegin VkBufferViewCreateInfo Structure specifying parameters of a newly created buffer view +[open,refpage='VkBufferViewCreateInfo',desc='Structure specifying parameters of a newly created buffer view',type='structs'] +-- The sname:VkBufferViewCreateInfo structure is defined as: @@ -412,8 +433,10 @@ include::../api/structs/VkBufferViewCreateInfo.txt[] **** include::../validity/structs/VkBufferViewCreateInfo.txt[] +-- -// refBegin vkDestroyBufferView Destroy a buffer view object +[open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos'] +-- To destroy a buffer view, call: @@ -438,12 +461,14 @@ include::../api/protos/vkDestroyBufferView.txt[] **** include::../validity/protos/vkDestroyBufferView.txt[] +-- [[resources-images]] == Images -// refBegin VkImage Opaque handle to a image object +[open,refpage='VkImage',desc='Opaque handle to a image object',type='handles'] +-- Images represent multidimensional - up to 3 - arrays of data which can: be used for various purposes (e.g. attachments, textures), by binding them to a @@ -454,9 +479,10 @@ Images are represented by sname:VkImage handles: include::../api/handles/VkImage.txt[] -// refEnd VkImage +-- -// refBegin vkCreateImage Create a new image object +[open,refpage='vkCreateImage',desc='Create a new image object',type='protos'] +-- To create images, call: @@ -482,8 +508,10 @@ include::../api/protos/vkCreateImage.txt[] **** include::../validity/protos/vkCreateImage.txt[] +-- -// refBegin VkImageCreateInfo Structure specifying the parameters of a newly created image object +[open,refpage='VkImageCreateInfo',desc='Structure specifying the parameters of a newly created image object',type='structs'] +-- The sname:VkImageCreateInfo structure is defined as: @@ -575,18 +603,23 @@ flink:vkGetPhysicalDeviceFormatProperties. * [[VUID-VkImageCreateInfo-sharingMode-00942]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, pname:queueFamilyIndexCount must: be greater than `1` +ifndef::VK_KHR_get_physical_device_properties2[] * [[VUID-VkImageCreateInfo-sharingMode-01392]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element of pname:pQueueFamilyIndices must: be unique and must: be less than pname:pQueueFamilyPropertyCount returned by -ifndef::VK_KHR_get_physical_device_properties2[] - flink:vkGetPhysicalDeviceQueueFamilyProperties + flink:vkGetPhysicalDeviceQueueFamilyProperties for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] ifdef::VK_KHR_get_physical_device_properties2[] - either flink:vkGetPhysicalDeviceQueueFamilyProperties or - flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR + * [[VUID-VkImageCreateInfo-sharingMode-01420]] + If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element + of pname:pQueueFamilyIndices must: be unique and must: be less than + pname:pQueueFamilyPropertyCount returned by either + flink:vkGetPhysicalDeviceQueueFamilyProperties or + flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the + pname:physicalDevice that was used to create pname:device endif::VK_KHR_get_physical_device_properties2[] - for the pname:physicalDevice that was used to create pname:device * [[VUID-VkImageCreateInfo-format-00943]] pname:format must: not be ename:VK_FORMAT_UNDEFINED * [[VUID-VkImageCreateInfo-extent-00944]] @@ -873,6 +906,11 @@ ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[] in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[] ifdef::VK_KHX_device_group[] + * [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]] + If the logical device was created with + slink:VkDeviceGroupDeviceCreateInfoKHX::pname:physicalDeviceCount equal + to 1, pname:flags must: not contain + ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX * [[VUID-VkImageCreateInfo-flags-00992]] If pname:flags contains ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX, then pname:mipLevels must: be one, pname:arrayLayers must: be one, @@ -885,10 +923,12 @@ endif::VK_KHX_device_group[] **** include::../validity/structs/VkImageCreateInfo.txt[] +-- ifdef::VK_NV_dedicated_allocation[] -// refBegin VkDedicatedAllocationImageCreateInfoNV Specify that an image is bound to a dedicated memory resource +[open,refpage='VkDedicatedAllocationImageCreateInfoNV',desc='Specify that an image is bound to a dedicated memory resource',type='structs'] +-- If the pname:pNext list includes a sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure @@ -922,12 +962,14 @@ other large images may: improve performance on some devices. **** include::../validity/structs/VkDedicatedAllocationImageCreateInfoNV.txt[] +-- endif::VK_NV_dedicated_allocation[] ifdef::VK_KHX_external_memory[] -// refBegin VkExternalMemoryImageCreateInfoKHX Specify that an image may be backed by external memory +[open,refpage='VkExternalMemoryImageCreateInfoKHX',desc='Specify that an image may be backed by external memory',type='structs'] +-- To define a set of external memory handle types that may: be used as backing store for an image, add a slink:VkExternalMemoryImageCreateInfoKHX structure @@ -943,12 +985,14 @@ include::../api/structs/VkExternalMemoryImageCreateInfoKHX.txt[] external memory handle types. include::../validity/structs/VkExternalMemoryImageCreateInfoKHX.txt[] +-- endif::VK_KHX_external_memory[] ifdef::VK_NV_external_memory[] -// refBegin VkExternalMemoryImageCreateInfoNV Specify that an image may be backed by external memory +[open,refpage='VkExternalMemoryImageCreateInfoNV',desc='Specify that an image may be backed by external memory',type='structs'] +-- If the pname:pNext list includes a sname:VkExternalMemoryImageCreateInfoNV structure, then that structure defines a set of external memory handle types @@ -965,12 +1009,14 @@ include::../api/structs/VkExternalMemoryImageCreateInfoNV.txt[] external memory handle types. include::../validity/structs/VkExternalMemoryImageCreateInfoNV.txt[] +-- endif::VK_NV_external_memory[] ifdef::VK_KHX_device_group[] -// refBegin VkImageSwapchainCreateInfoKHX Specify that an image will be bound to swapchain memory +[open,refpage='VkImageSwapchainCreateInfoKHX',desc='Specify that an image will be bound to swapchain memory',type='structs'] +-- If the pname:pNext list of slink:VkImageCreateInfo includes a sname:VkImageSwapchainCreateInfoKHX structure, then that structure includes @@ -996,10 +1042,12 @@ include::../api/structs/VkImageSwapchainCreateInfoKHX.txt[] **** include::../validity/structs/VkImageSwapchainCreateInfoKHX.txt[] +-- endif::VK_KHX_device_group[] -// refBegin VkImageUsageFlagBits Bitmask specifying intended usage of an image +[open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums'] +-- Bits which can: be set in slink:VkImageCreateInfo::pname:usage, specifying intended usage of an image, are: @@ -1039,9 +1087,10 @@ include::../api/enums/VkImageUsageFlagBits.txt[] ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer. -// refEnd VkImageUsageFlagBits +-- -// refBegin VkImageCreateFlagBits Bitmask specifying additional parameters of an image +[open,refpage='VkImageCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] +-- Bits which can: be set in slink:VkImageCreateInfo::pname:flags, specifying additional parameters of an image, are: @@ -1089,9 +1138,10 @@ See <> and <> for more details. -// refEnd VkImageCreateFlagBits +-- -// refBegin VkImageType Specifies the type of an image object +[open,refpage='VkImageType',desc='Specifies the type of an image object',type='enums'] +-- Possible values of slink:VkImageCreateInfo::pname:imageType, specifying the basic dimensionality of an image, are: @@ -1102,9 +1152,10 @@ include::../api/enums/VkImageType.txt[] * ename:VK_IMAGE_TYPE_2D specifies a two-dimensional image. * ename:VK_IMAGE_TYPE_3D specifies a three-dimensional image. -// refEnd VkImageType +-- -// refBegin VkImageTiling Specifies the tiling arrangement of data in an image +[open,refpage='VkImageTiling',desc='Specifies the tiling arrangement of data in an image',type='enums'] +-- Possible values of slink:VkImageCreateInfo::pname:tiling, specifying the tiling arrangement of data elements in an image, are: @@ -1118,9 +1169,10 @@ include::../api/enums/VkImageTiling.txt[] out in memory in row-major order, possibly with some padding on each row). -// refEnd VkImageTiling +-- -// refBegin vkGetImageSubresourceLayout Retrieve information about an image subresource +[open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos'] +-- To query the host access layout of an image subresource, for an image created with linear tiling, call: @@ -1148,8 +1200,10 @@ image. **** include::../validity/protos/vkGetImageSubresourceLayout.txt[] +-- -// refBegin VkImageSubresource Structure specifying a image subresource +[open,refpage='VkImageSubresource',desc='Structure specifying a image subresource',type='structs'] +-- The sname:VkImageSubresource structure is defined as: @@ -1171,8 +1225,10 @@ include::../api/structs/VkImageSubresource.txt[] **** include::../validity/structs/VkImageSubresource.txt[] +-- -// refBegin VkSubresourceLayout Structure specifying subresource layout +[open,refpage='VkSubresourceLayout',desc='Structure specifying subresource layout',type='structs'] +-- Information about the layout of the image subresource is returned in a sname:VkSubresourceLayout structure: @@ -1239,8 +1295,10 @@ same pname:offset and pname:size are returned and represent the interleaved memory allocation. include::../validity/structs/VkSubresourceLayout.txt[] +-- -// refBegin vkDestroyImage Destroy an image object +[open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos'] +-- To destroy an image, call: @@ -1265,6 +1323,7 @@ include::../api/protos/vkDestroyImage.txt[] **** include::../validity/protos/vkDestroyImage.txt[] +-- [[resources-image-layouts]] @@ -1326,7 +1385,8 @@ layout. Calling flink:vkGetImageSubresourceLayout for a linear image returns a subresource layout mapping that is valid for either of those image layouts. -// refBegin VkImageLayout Layout of image and image subresources +[open,refpage='VkImageLayout',desc='Layout of image and image subresources',type='enums'] +-- The set of image layouts consists of: @@ -1424,13 +1484,14 @@ subresource need not be preserved). The new layout used in a transition must: not be ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED. -// refEnd VkImageLayout +-- [[resources-image-views]] == Image Views -// refBegin VkImageView Opaque handle to a image view object +[open,refpage='VkImageView',desc='Opaque handle to a image view object',type='handles'] +-- Image objects are not directly accessed by pipeline shaders for reading or writing image data. @@ -1443,9 +1504,10 @@ Image views are represented by sname:VkImageView handles: include::../api/handles/VkImageView.txt[] -// refEnd VkImageView +-- -// refBegin VkImageViewType Image view types +[open,refpage='VkImageViewType',desc='Image view types',type='enums'] +-- The types of image views that can: be created are: @@ -1458,9 +1520,10 @@ for flink:vkCreateImageView. This table also shows which SPIR-V code:OpTypeImage code:Dim and code:Arrayed parameters correspond to each image view type. -// refEnd VkImageViewType +-- -// refBegin vkCreateImageView Create an image view from an existing image +[open,refpage='vkCreateImageView',desc='Create an image view from an existing image',type='protos'] +-- To create an image view, call: @@ -1479,8 +1542,10 @@ Some of the image creation parameters are inherited by the view. The remaining parameters are contained in the pname:pCreateInfo. include::../validity/protos/vkCreateImageView.txt[] +-- -// refBegin VkImageViewCreateInfo Structure specifying parameters of a newly created image view +[open,refpage='VkImageViewCreateInfo',desc='Structure specifying parameters of a newly created image view',type='structs'] +-- The sname:VkImageViewCreateInfo structure is defined as: @@ -1506,6 +1571,9 @@ are not equal they must: be _compatible_. Image format compatibility is defined in the <> section. +Views of compatible formats will have the same mapping between texel +coordinates and memory locations irrespective of the pname:format, with only +the interpretation of the bit pattern changing. [[resources-image-views-compatibility]] .Image and image view parameter compatibility requirements @@ -1777,8 +1845,10 @@ endif::VK_KHR_maintenance1[] **** include::../validity/structs/VkImageViewCreateInfo.txt[] +-- -// refBegin VkImageSubresourceRange Structure specifying a image subresource range +[open,refpage='VkImageSubresourceRange',desc='Structure specifying a image subresource range',type='structs'] +-- The sname:VkImageSubresourceRange structure is defined as: @@ -1875,8 +1945,10 @@ endif::VK_KHR_maintenance1[] **** include::../validity/structs/VkImageSubresourceRange.txt[] +-- -// refBegin VkImageAspectFlagBits Bitmask specifying which aspects of an image are included in a view +[open,refpage='VkImageAspectFlagBits',desc='Bitmask specifying which aspects of an image are included in a view',type='enums'] +-- Bits which can: be set in an aspect mask to specify aspects of an image for purposes such as identifying a subresource, are: @@ -1889,9 +1961,10 @@ include::../api/enums/VkImageAspectFlagBits.txt[] * ename:VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect, used for sparse <> operations. -// refEnd VkImageAspectFlagBits +-- -// refBegin VkComponentMapping Structure specifying a color component mapping +[open,refpage='VkComponentMapping',desc='Structure specifying a color component mapping',type='structs'] +-- The sname:VkComponentMapping structure is defined as: @@ -1907,8 +1980,10 @@ include::../api/structs/VkComponentMapping.txt[] placed in the A component of the output vector. include::../validity/structs/VkComponentMapping.txt[] +-- -// refBegin VkComponentSwizzle Specify how a component is swizzled +[open,refpage='VkComponentSwizzle',desc='Specify how a component is swizzled',type='enums'] +-- Possible values of the members of slink:VkComponentMapping, specifying the component values placed in each component of the output vector, are: @@ -1948,9 +2023,10 @@ That is: | pname:components.a | ename:VK_COMPONENT_SWIZZLE_A |==== -// refEnd VkComponentSwizzle +-- -// refBegin vkDestroyImageView Destroy an image view object +[open,refpage='vkDestroyImageView',desc='Destroy an image view object',type='protos'] +-- To destroy an image view, call: @@ -1975,6 +2051,7 @@ include::../api/protos/vkDestroyImageView.txt[] **** include::../validity/protos/vkDestroyImageView.txt[] +-- [[resources-association]] @@ -2028,7 +2105,8 @@ physical device to copy the data from one physical device to another. endif::VK_KHX_device_group[] -// refBegin vkGetBufferMemoryRequirements Returns the memory requirements for specified Vulkan object +[open,refpage='vkGetBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] +-- To determine the memory requirements for a buffer resource, call: @@ -2041,8 +2119,10 @@ include::../api/protos/vkGetBufferMemoryRequirements.txt[] the buffer object are returned. include::../validity/protos/vkGetBufferMemoryRequirements.txt[] +-- -// refBegin vkGetImageMemoryRequirements Returns the memory requirements for specified Vulkan object +[open,refpage='vkGetImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] +-- To determine the memory requirements for an image resource, call: @@ -2055,8 +2135,10 @@ include::../api/protos/vkGetImageMemoryRequirements.txt[] the image object are returned. include::../validity/protos/vkGetImageMemoryRequirements.txt[] +-- -// refBegin VkMemoryRequirements Structure specifying memory requirements +[open,refpage='VkMemoryRequirements',desc='Structure specifying memory requirements',type='structs'] +-- The sname:VkMemoryRequirements structure is defined as: @@ -2073,6 +2155,7 @@ include::../api/structs/VkMemoryRequirements.txt[] is supported for the resource. include::../validity/structs/VkMemoryRequirements.txt[] +-- The implementation guarantees certain properties about the memory requirements returned by flink:vkGetBufferMemoryRequirements and @@ -2168,16 +2251,15 @@ endif::VK_KHX_external_memory[] a pname:propertyFlags that has the ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set. + --- [NOTE] .Note ==== The implication of this requirement is that lazily allocated memory is disallowed for buffers in all cases. ==== --- -// refBegin vkBindBufferMemory Bind device memory to a buffer object +[open,refpage='vkBindBufferMemory',desc='Bind device memory to a buffer object',type='protos'] +-- To attach memory to a buffer object, call: @@ -2256,10 +2338,12 @@ endif::VK_NV_dedicated_allocation[] **** include::../validity/protos/vkBindBufferMemory.txt[] +-- ifdef::VK_KHX_device_group[] -// refBegin vkBindBufferMemory2KHX Bind device memory to buffer objects +[open,refpage='vkBindBufferMemory2KHX',desc='Bind device memory to buffer objects',type='protos'] +-- To attach memory to buffer objects for one or more buffers at a time, call: @@ -2274,8 +2358,10 @@ On some implementations, it may: be more efficient to batch memory bindings into a single command. include::../validity/protos/vkBindBufferMemory2KHX.txt[] +-- -// refBegin VkBindBufferMemoryInfoKHX Structure specifying how to bind a buffer to memory +[open,refpage='VkBindBufferMemoryInfoKHX',desc='Structure specifying how to bind a buffer to memory',type='structs'] +-- sname:VkBindBufferMemoryInfoKHX contains members corresponding to the parameters to flink:vkBindBufferMemory, as well as new members to control @@ -2330,10 +2416,12 @@ In other words, by default each physical device attaches to instance zero. **** include::../validity/structs/VkBindBufferMemoryInfoKHX.txt[] +-- endif::VK_KHX_device_group[] -// refBegin vkBindImageMemory Bind device memory to an image object +[open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos'] +-- To attach memory to an image object, call: @@ -2396,10 +2484,12 @@ endif::VK_NV_dedicated_allocation[] **** include::../validity/protos/vkBindImageMemory.txt[] +-- ifdef::VK_KHX_device_group[] -// refBegin vkBindImageMemory2KHX Bind device memory to image objects +[open,refpage='vkBindImageMemory2KHX',desc='Bind device memory to image objects',type='protos'] +-- To attach memory to image objects for one or more images at a time, call: @@ -2414,8 +2504,10 @@ On some implementations, it may: be more efficient to batch memory bindings into a single command. include::../validity/protos/vkBindImageMemory2KHX.txt[] +-- -// refBegin VkBindImageMemoryInfoKHX Structure specifying how to bind an image to memory +[open,refpage='VkBindImageMemoryInfoKHX',desc='Structure specifying how to bind an image to memory',type='structs'] +-- sname:VkBindImageMemoryInfoKHX contains members corresponding to the parameters to flink:vkBindImageMemory, as well as new members to control @@ -2528,8 +2620,10 @@ In other words, by default each physical device attaches to instance zero. **** include::../validity/structs/VkBindImageMemoryInfoKHX.txt[] +-- -// refBegin VkBindImageMemorySwapchainInfoKHX Structure specifying swapchain image memory to bind to +[open,refpage='VkBindImageMemorySwapchainInfoKHX',desc='Structure specifying swapchain image memory to bind to',type='structs'] +-- If the pname:pNext list of slink:VkBindImageMemoryInfoKHX includes a sname:VkBindImageMemorySwapchainInfoKHX structure, then that structure @@ -2564,6 +2658,7 @@ pname:pSFRRects members of slink:VkBindImageMemoryInfoKHX. **** include::../validity/structs/VkBindImageMemorySwapchainInfoKHX.txt[] +-- endif::VK_KHX_device_group[] @@ -2626,7 +2721,8 @@ pname:bufferImageGranularity. [[resources-sharing]] == Resource Sharing Mode -// refBegin VkSharingMode Buffer and image sharing modes +[open,refpage='VkSharingMode',desc='Buffer and image sharing modes',type='enums'] +-- Buffer and image objects are created with a _sharing mode_ controlling how they can: be accessed from queues. @@ -2681,7 +2777,7 @@ queue families specified through the pname:queueFamilyIndexCount and pname:pQueueFamilyIndices members of the corresponding create info structures. -// refEnd VkSharingMode +-- ifdef::VK_KHX_external_memory[] diff --git a/doc/specs/vulkan/chapters/samplers.txt b/doc/specs/vulkan/chapters/samplers.txt index 3f0daabc..44594da4 100644 --- a/doc/specs/vulkan/chapters/samplers.txt +++ b/doc/specs/vulkan/chapters/samplers.txt @@ -1,10 +1,12 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[samplers]] = Samplers -// refBegin VkSampler Opaque handle to a sampler object +[open,refpage='VkSampler',desc='Opaque handle to a sampler object',type='handles'] +-- sname:VkSampler objects represent the state of an image sampler which is used by the implementation to read image data and apply filtering and other @@ -14,9 +16,10 @@ Samplers are represented by sname:VkSampler handles: include::../api/handles/VkSampler.txt[] -// refEnd VkSampler +-- -// refBegin vkCreateSampler Create a new sampler object +[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos'] +-- To create a sampler object, call: @@ -32,8 +35,10 @@ include::../api/protos/vkCreateSampler.txt[] sampler object is returned. include::../validity/protos/vkCreateSampler.txt[] +-- -// refBegin VkSamplerCreateInfo Structure specifying parameters of a newly created sampler +[open,refpage='VkSamplerCreateInfo',desc='Structure specifying parameters of a newly created sampler',type='structs'] +-- The sname:VkSamplerCreateInfo structure is defined as: @@ -196,12 +201,70 @@ ifdef::VK_IMG_filter_cubic[] ename:VK_FILTER_CUBIC_IMG, pname:anisotropyEnable must: be ename:VK_FALSE endif::VK_IMG_filter_cubic[] +ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] + * [[VUID-VkSamplerCreateInfo-magFilter-01422]] + If either pname:magFilter or pname:minFilter is + ename:VK_FILTER_CUBIC_IMG, the pname:reductionMode member of + slink:VkSamplerReductionModeCreateInfoEXT must: be + ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT +endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] +ifdef::VK_EXT_sampler_filter_minmax[] + * [[VUID-VkSamplerCreateInfo-compareEnable-01423]] + If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member + of slink:VkSamplerReductionModeCreateInfoEXT must: be + ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT +endif::VK_EXT_sampler_filter_minmax[] **** include::../validity/structs/VkSamplerCreateInfo.txt[] +-- -// refBegin VkFilter Specify filters used for texture lookups +ifdef::VK_EXT_sampler_filter_minmax[] +[open,refpage='VkSamplerReductionModeCreateInfoEXT',desc='Structure specifying sampler reduction mode',type='structs'] +-- +If the pname:pNext list of slink:VkSamplerCreateInfo includes a +sname:VkSamplerReductionModeCreateInfoEXT structure, then that structure +includes a mode that controls how texture filtering combines texel values. + +The sname:VkSamplerReductionModeCreateInfoEXT structure is defined as: + +include::../api/structs/VkSamplerReductionModeCreateInfoEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:reductionMode is an enum of type elink:VkSamplerReductionModeEXT + that controls how texture filtering combines texel values. + +If this structure is not present, pname:reductionMode is considered to be +ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT. + +include::../validity/structs/VkSamplerReductionModeCreateInfoEXT.txt[] +-- + +[open,refpage='VkSamplerReductionModeEXT',desc='Specify reduction mode for texture filtering',type='enums'] +-- +Reduction modes are specified by elink:VkSamplerReductionModeEXT, which +takes values: + +include::../api/enums/VkSamplerReductionModeEXT.txt[] + + * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT indicates that + texel values are combined by computing a weighted average of values in + the footprint, using weights as specified in + <>. + * ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT indicates that texel values are + combined by taking the component-wise minimum of values in the footprint + with non-zero weights. + * ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT indicates that texel values are + combined by taking the component-wise maximum of values in the footprint + with non-zero weights. +-- + +endif::VK_EXT_sampler_filter_minmax[] + +[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums'] +-- Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and pname:minFilter parameters, specifying filters used for texture lookups, are: @@ -214,9 +277,10 @@ include::../api/enums/VkFilter.txt[] These filters are described in detail in <>. -// refEnd VkFilter +-- -// refBegin VkSamplerMipmapMode Specify mipmap mode used for texture lookups +[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums'] +-- Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode, specifying the mipmap mode used for texture lookups, are: @@ -229,9 +293,10 @@ include::../api/enums/VkSamplerMipmapMode.txt[] These modes are described in detail in <>. -// refEnd VkSamplerMipmapMode +-- -// refBegin VkSamplerAddressMode Specify behavior of sampling with texture coordinates outside an image +[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums'] +-- Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode* parameters, specifying the behavior of sampling with coordinates outside the @@ -254,9 +319,10 @@ include::../api/enums/VkSamplerAddressMode.txt[] This is only valid if the +VK_KHR_mirror_clamp_to_edge+ extension is enabled. -// refEnd VkSamplerAddressMode +-- -// refBegin VkBorderColor Specify border color used for texture lookups +[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums'] +-- Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying the border color used for texture lookups, are: @@ -279,9 +345,10 @@ include::../api/enums/VkBorderColor.txt[] These colors are described in detail in <>. -// refEnd VkBorderColor +-- -// refBegin vkDestroySampler Destroy a sampler object +[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos'] +-- To destroy a sampler, call: @@ -306,3 +373,4 @@ include::../api/protos/vkDestroySampler.txt[] **** include::../validity/protos/vkDestroySampler.txt[] +-- diff --git a/doc/specs/vulkan/chapters/shaders.txt b/doc/specs/vulkan/chapters/shaders.txt index 9b3556e1..cdb4e858 100644 --- a/doc/specs/vulkan/chapters/shaders.txt +++ b/doc/specs/vulkan/chapters/shaders.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[shaders]] = Shaders @@ -39,7 +40,8 @@ subsections. [[shader-modules]] == Shader Modules -// refBegin VkShaderModule Opaque handle to a shader module object +[open,refpage='VkShaderModule',desc='Opaque handle to a shader module object',type='handles'] +-- _Shader modules_ contain _shader code_ and one or more entry points. Shaders are selected from a shader module by specifying an entry point as @@ -52,9 +54,10 @@ Shader modules are represented by sname:VkShaderModule handles: include::../api/handles/VkShaderModule.txt[] -// refEnd VkShaderModule +-- -// refBegin vkCreateShaderModule Creates a new shader module object +[open,refpage='vkCreateShaderModule',desc='Creates a new shader module object',type='protos'] +-- To create a shader module, call: @@ -79,8 +82,10 @@ be generated and the compile log will be reported back to the application by endif::VK_NV_glsl_shader[] include::../validity/protos/vkCreateShaderModule.txt[] +-- -// refBegin VkShaderModuleCreateInfo Structure specifying parameters of a newly created shader module +[open,refpage='VkShaderModuleCreateInfo',desc='Structure specifying parameters of a newly created shader module',type='structs'] +-- The sname:VkShaderModuleCreateInfo structure is defined as: @@ -143,8 +148,10 @@ endif::VK_NV_glsl_shader[] **** include::../validity/structs/VkShaderModuleCreateInfo.txt[] +-- -// refBegin vkDestroyShaderModule Destroy a shader module module +[open,refpage='vkDestroyShaderModule',desc='Destroy a shader module module',type='protos'] +-- To destroy a shader module, call: @@ -169,6 +176,7 @@ are still in use. **** include::../validity/protos/vkDestroyShaderModule.txt[] +-- [[shaders-execution]] diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt index 33dd376e..ddd13ad0 100644 --- a/doc/specs/vulkan/chapters/sparsemem.txt +++ b/doc/specs/vulkan/chapters/sparsemem.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[sparsememory]] = Sparse Resources @@ -70,19 +71,9 @@ slink:VkPhysicalDeviceFeatures. will return undefined values. ** Requested via the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT and ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bits. - ** [[features-features-sparseResidency,Sparse residency support]] is + ** [[features-features-sparseResidency]] Sparse residency support is advertised on a finer grain via the following features: + --- -ifdef::editing-notes[] -[NOTE] -.editing-note -==== -(Jon) Something wrong with markup here - "`Sparse residency support`" -doesn't show up in the bullet point. -==== -endif::editing-notes[] - *** <>: Support for creating sname:VkBuffer objects with the ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT. @@ -104,14 +95,14 @@ endif::editing-notes[] *** <>: Support for creating 2D sname:VkImage objects with 16 samples and ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. - ++ Implementations supporting pname:sparseResidencyImage2D are only required: to support sparse 2D, single-sampled images. Support is not required: for sparse 3D and MSAA images and is enabled via pname:sparseResidencyImage3D, pname:sparseResidency2Samples, pname:sparseResidency4Samples, pname:sparseResidency8Samples, and pname:sparseResidency16Samples. --- + ** A sparse image created using ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT supports all non-compressed color formats with power-of-two element size that non-sparse usage supports. @@ -714,7 +705,8 @@ These read-only capabilities are reported in the slink:VkPhysicalDeviceProperties::pname:sparseProperties member, which is a structure of type sname:VkPhysicalDeviceSparseProperties. -// refBegin VkPhysicalDeviceSparseProperties Structure specifying physical device sparse memory properties +[open,refpage='VkPhysicalDeviceSparseProperties',desc='Structure specifying physical device sparse memory properties',type='structs'] +-- The sname:VkPhysicalDeviceSparseProperties structure is defined as: @@ -766,6 +758,7 @@ include::../api/structs/VkPhysicalDeviceSparseProperties.txt[] populated with 0; writes to non-resident regions will be discarded. include::../validity/structs/VkPhysicalDeviceSparseProperties.txt[] +-- [[sparsememory-format-props]] @@ -781,7 +774,8 @@ is supported and what the sparse image block shape will be. ==== Sparse Image Format Properties API -// refBegin VkSparseImageFormatProperties Structure specifying sparse image format properties +[open,refpage='VkSparseImageFormatProperties',desc='Structure specifying sparse image format properties',type='structs'] +-- The sname:VkSparseImageFormatProperties structure is defined as: @@ -795,8 +789,10 @@ include::../api/structs/VkSparseImageFormatProperties.txt[] additional information about the sparse resource. include::../validity/structs/VkSparseImageFormatProperties.txt[] +-- -// refBegin VkSparseImageFormatFlagBits Bitmask specifying additional information about a sparse image resource +[open,refpage='VkSparseImageFormatFlagBits',desc='Bitmask specifying additional information about a sparse image resource',type='enums'] +-- Bits which can: be set in slink:VkSparseImageFormatProperties::pname:flags, specifying additional information about the sparse resource, are: @@ -814,9 +810,10 @@ include::../api/enums/VkSparseImageFormatFlagBits.txt[] pname:imageGranularity values do not match the standard sparse image block dimensions for the given pixel format. -// refEnd VkSparseImageFormatFlagBits +-- -// refBegin vkGetPhysicalDeviceSparseImageFormatProperties Retrieve properties of an image format applied to sparse images +[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties',desc='Retrieve properties of an image format applied to sparse images',type='protos'] +-- fname:vkGetPhysicalDeviceSparseImageFormatProperties returns an array of slink:VkSparseImageFormatProperties. @@ -876,10 +873,12 @@ ename:VK_IMAGE_ASPECT_STENCIL_BIT. **** include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties.txt[] +-- ifdef::VK_KHR_get_physical_device_properties2[] -// refBegin vkGetPhysicalDeviceSparseImageFormatProperties2KHR Retrieve properties of an image format applied to sparse images +[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties2KHR',desc='Retrieve properties of an image format applied to sparse images',type='protos'] +-- fname:vkGetPhysicalDeviceSparseImageFormatProperties2KHR returns an array of slink:VkSparseImageFormatProperties2KHR. @@ -907,8 +906,10 @@ return extended information by adding extension structures to its pname:pNext chain. include::../validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties2KHR.txt[] +-- -// refBegin VkPhysicalDeviceSparseImageFormatInfo2KHR Structure specifying sparse image format inputs +[open,refpage='VkPhysicalDeviceSparseImageFormatInfo2KHR',desc='Structure specifying sparse image format inputs',type='structs'] +-- The sname:VkPhysicalDeviceSparseImageFormatInfo2KHR structure is defined as: @@ -935,8 +936,10 @@ include::../api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[] **** include::../validity/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.txt[] +-- -// refBegin VkSparseImageFormatProperties2KHR Structure specifying sparse image format properties +[open,refpage='VkSparseImageFormatProperties2KHR',desc='Structure specifying sparse image format properties',type='structs'] +-- The sname:VkSparseImageFormatProperties2KHR structure is defined as: @@ -949,6 +952,7 @@ include::../api/structs/VkSparseImageFormatProperties2KHR.txt[] values as in flink:vkGetPhysicalDeviceSparseImageFormatProperties. include::../validity/structs/VkSparseImageFormatProperties2KHR.txt[] +-- endif::VK_KHR_get_physical_device_properties2[] @@ -1019,7 +1023,8 @@ image memory requirements. ==== Sparse Image Memory Requirements -// refBegin VkSparseImageMemoryRequirements Structure specifying sparse image memory requirements +[open,refpage='VkSparseImageMemoryRequirements',desc='Structure specifying sparse image memory requirements',type='structs'] +-- The sname:VkSparseImageMemoryRequirements structure is defined as: @@ -1068,8 +1073,10 @@ include::../api/structs/VkSparseImageMemoryRequirements.txt[] undefined). include::../validity/structs/VkSparseImageMemoryRequirements.txt[] +-- -// refBegin vkGetImageSparseMemoryRequirements Query the memory requirements for a sparse image +[open,refpage='vkGetImageSparseMemoryRequirements',desc='Query the memory requirements for a sparse image',type='protos'] +-- To query sparse memory requirements for an image, call: @@ -1111,6 +1118,7 @@ range describing the resource. ==== include::../validity/protos/vkGetImageSparseMemoryRequirements.txt[] +-- [[sparsememory-resource-binding]] @@ -1187,9 +1195,9 @@ ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT then the offset for the mip tail in each array layer is given as: [source,c++] --- +--------------------------------------------------- arrayMipTailOffset = imageMipTailOffset + arrayLayer * imageMipTailStride; --- +--------------------------------------------------- and the mip tail can: be bound with code:layerCount slink:VkSparseMemoryBind structures, each using pname:size = pname:imageMipTailSize and @@ -1202,7 +1210,8 @@ structures. [[sparsemem-memory-binding]] ==== Sparse Memory Binding Functions -// refBegin VkSparseMemoryBind Structure specifying a sparse memory bind operation +[open,refpage='VkSparseMemoryBind',desc='Structure specifying a sparse memory bind operation',type='structs'] +-- The sname:VkSparseMemoryBind structure is defined as: @@ -1267,8 +1276,10 @@ the binding range must: be within the range **** include::../validity/structs/VkSparseMemoryBind.txt[] +-- -// refBegin VkSparseMemoryBindFlagBits Bitmask specifying usage of a sparse memory binding operation +[open,refpage='VkSparseMemoryBindFlagBits',desc='Bitmask specifying usage of a sparse memory binding operation',type='enums'] +-- Bits which can: be set in slink:VkSparseMemoryBind::pname:flags, specifying usage of a sparse memory binding operation, are: @@ -1278,9 +1289,10 @@ include::../api/enums/VkSparseMemoryBindFlagBits.txt[] * ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT specifies that the memory being bound is only for the metadata aspect. -// refEnd VkSparseMemoryBindFlagBits +-- -// refBegin VkSparseBufferMemoryBindInfo Structure specifying a sparse buffer memory bind operation +[open,refpage='VkSparseBufferMemoryBindInfo',desc='Structure specifying a sparse buffer memory bind operation',type='structs'] +-- Memory is bound to sname:VkBuffer objects created with the ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag using the following @@ -1295,8 +1307,10 @@ include::../api/structs/VkSparseBufferMemoryBindInfo.txt[] structures. include::../validity/structs/VkSparseBufferMemoryBindInfo.txt[] +-- -// refBegin VkSparseImageOpaqueMemoryBindInfo Structure specifying sparse image opaque memory bind info +[open,refpage='VkSparseImageOpaqueMemoryBindInfo',desc='Structure specifying sparse image opaque memory bind info',type='structs'] +-- Memory is bound to opaque regions of sname:VkImage objects created with the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag using the following structure: @@ -1319,6 +1333,7 @@ include::../api/structs/VkSparseImageOpaqueMemoryBindInfo.txt[] **** include::../validity/structs/VkSparseImageOpaqueMemoryBindInfo.txt[] +-- [NOTE] .Note @@ -1360,7 +1375,8 @@ contextually clear. ==== endif::editing-notes[] -// refBegin VkSparseImageMemoryBindInfo Structure specifying sparse image memory bind info +[open,refpage='VkSparseImageMemoryBindInfo',desc='Structure specifying sparse image memory bind info',type='structs'] +-- Memory can: be bound to sparse image blocks of sname:VkImage objects created with the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag using the following @@ -1375,8 +1391,10 @@ include::../api/structs/VkSparseImageMemoryBindInfo.txt[] structures include::../validity/structs/VkSparseImageMemoryBindInfo.txt[] +-- -// refBegin VkSparseImageMemoryBind Structure specifying sparse image memory bind +[open,refpage='VkSparseImageMemoryBind',desc='Structure specifying sparse image memory bind',type='structs'] +-- The sname:VkSparseImageMemoryBind structure is defined as: @@ -1441,8 +1459,10 @@ include::../api/structs/VkSparseImageMemoryBind.txt[] **** include::../validity/structs/VkSparseImageMemoryBind.txt[] +-- -// refBegin vkQueueBindSparse Bind device memory to a sparse resource object +[open,refpage='vkQueueBindSparse',desc='Bind device memory to a sparse resource object',type='protos'] +-- To submit sparse binding operations to a queue, call: @@ -1504,8 +1524,10 @@ Additional information about fence and semaphore operation is described in **** include::../validity/protos/vkQueueBindSparse.txt[] +-- -// refBegin VkBindSparseInfo Structure specifying a sparse binding operation +[open,refpage='VkBindSparseInfo',desc='Structure specifying a sparse binding operation',type='structs'] +-- The sname:VkBindSparseInfo structure is defined as: @@ -1543,10 +1565,12 @@ include::../api/structs/VkBindSparseInfo.txt[] <>. include::../validity/structs/VkBindSparseInfo.txt[] +-- ifdef::VK_KHX_device_group[] -// refBegin VkDeviceGroupBindSparseInfoKHX Structure indicating which instances are bound +[open,refpage='VkDeviceGroupBindSparseInfoKHX',desc='Structure indicating which instances are bound',type='structs'] +-- If the pname:pNext list of slink:VkBindSparseInfo includes a sname:VkDeviceGroupBindSparseInfoKHX structure, then that structure includes @@ -1584,7 +1608,7 @@ pname:memoryDeviceIndex are assumed to be zero. include::../validity/structs/VkDeviceGroupBindSparseInfoKHX.txt[] -// refEnd VkDeviceGroupBindSparseInfoKHX +-- endif::VK_KHX_device_group[] diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt index f0fdaa02..f71bee77 100644 --- a/doc/specs/vulkan/chapters/synchronization.txt +++ b/doc/specs/vulkan/chapters/synchronization.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[synchronization]] = Synchronization and Cache Control @@ -251,7 +252,8 @@ Otherwise, execution across pipeline stages may: overlap or execute out of order with regards to other stages, unless otherwise enforced by an execution dependency. -// refBegin VkPipelineStageFlagBits - Bitmask specifying pipeline stages +[open,refpage='VkPipelineStageFlagBits',desc='Bitmask specifying pipeline stages',type='enums'] +-- Several of the synchronization commands include pipeline stage parameters, restricting the <>, such as via <>, <>, or via certain <>. +ifdef::VK_EXT_blend_operation_advanced[] + It does not include <>. + * ename:VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT is similar to + ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT, but also includes + <>. +endif::VK_EXT_blend_operation_advanced[] * ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT specifies write access to a <> during a <> or via certain <> is empty. -// refBegin vkWaitForFences Wait for one or more fences to become signaled +[open,refpage='vkWaitForFences',desc='Wait for one or more fences to become signaled',type='protos'] +-- To wait for one or more fences to enter the signaled state on the host, call: @@ -1102,6 +1128,7 @@ permanently (or seemingly permanently) dead process. ==== include::../validity/protos/vkWaitForFences.txt[] +-- [[synchronization-fences-waiting]] An execution dependency is defined by waiting for a fence to become @@ -1134,7 +1161,8 @@ endif::VK_EXT_display_control[] [[synchronization-semaphores]] == Semaphores -// refBegin VkSemaphore Opaque handle to a semaphore object +[open,refpage='VkSemaphore',desc='Opaque handle to a semaphore object',type='handles'] +-- Semaphores are a synchronization primitive that can: be used to insert a dependency between batches submitted to queues. @@ -1149,9 +1177,10 @@ Semaphores are represented by sname:VkSemaphore handles: include::../api/handles/VkSemaphore.txt[] -// refEnd VkSemaphore +-- -// refBegin vkCreateSemaphore Create a new queue semaphore object +[open,refpage='vkCreateSemaphore',desc='Create a new queue semaphore object',type='protos'] +-- To create a semaphore, call: @@ -1169,8 +1198,10 @@ include::../api/protos/vkCreateSemaphore.txt[] When created, the semaphore is in the unsignaled state. include::../validity/protos/vkCreateSemaphore.txt[] +-- -// refBegin VkSemaphoreCreateInfo Structure specifying parameters of a newly created semaphore +[open,refpage='VkSemaphoreCreateInfo',desc='Structure specifying parameters of a newly created semaphore',type='structs'] +-- The sname:VkSemaphoreCreateInfo structure is defined as: @@ -1181,10 +1212,12 @@ include::../api/structs/VkSemaphoreCreateInfo.txt[] * pname:flags is reserved for future use. include::../validity/structs/VkSemaphoreCreateInfo.txt[] +-- ifdef::VK_KHX_external_semaphore[] -// refBegin VkExportSemaphoreCreateInfoKHX Structure specifying handle types that can be exported from a semaphore +[open,refpage='VkExportSemaphoreCreateInfoKHX',desc='Structure specifying handle types that can be exported from a semaphore',type='structs'] +-- To create a semaphore object that can be exported to external handles, add the slink:VkExportSemaphoreCreateInfoKHX structure to the pname:pNext chain @@ -1210,12 +1243,14 @@ include::../api/structs/VkExportSemaphoreCreateInfoKHX.txt[] **** include::../validity/structs/VkExportSemaphoreCreateInfoKHX.txt[] +-- endif::VK_KHX_external_semaphore[] ifdef::VK_KHX_external_semaphore_win32[] -// refBegin VkExportSemaphoreWin32HandleInfoKHX Structure specifying additional attributes of Windows handles exported from a semaphore +[open,refpage='VkExportSemaphoreWin32HandleInfoKHX',desc='Structure specifying additional attributes of Windows handles exported from a semaphore',type='structs'] +-- To specify additional attributes of NT handles exported from a semaphore, add the slink:VkExportSemaphoreWin32HandleInfoKHX structure to the @@ -1267,8 +1302,10 @@ ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT_KHX **** include::../validity/structs/VkExportSemaphoreWin32HandleInfoKHX.txt[] +-- -// refBegin vkGetSemaphoreWin32HandleKHX Get a Windows HANDLE for a semaphore +[open,refpage='vkGetSemaphoreWin32HandleKHX',desc='Get a Windows HANDLE for a semaphore',type='protos'] +-- To export a Windows handle representing the state of a semaphore, call: @@ -1322,12 +1359,14 @@ using the fname:CloseHandle system call when they are no longer needed. **** include::../validity/protos/vkGetSemaphoreWin32HandleKHX.txt[] +-- endif::VK_KHX_external_semaphore_win32[] ifdef::VK_KHX_external_semaphore_fd[] -// refBegin vkGetSemaphoreFdKHX Get a POSIX file descriptor handle for a semaphore +[open,refpage='vkGetSemaphoreFdKHX',desc='Get a POSIX file descriptor handle for a semaphore',type='protos'] +-- To export a POSIX file descriptor representing the state of a semaphore, call: @@ -1378,10 +1417,12 @@ needed, or by importing Vulkan semaphore state from it. **** include::../validity/protos/vkGetSemaphoreFdKHX.txt[] +-- endif::VK_KHX_external_semaphore_fd[] -// refBegin vkDestroySemaphore Destroy a semaphore object +[open,refpage='vkDestroySemaphore',desc='Destroy a semaphore object',type='protos'] +-- To destroy a semaphore, call: @@ -1406,6 +1447,7 @@ include::../api/protos/vkDestroySemaphore.txt[] **** include::../validity/protos/vkDestroySemaphore.txt[] +-- [[synchronization-semaphores-signaling]] @@ -1627,7 +1669,8 @@ endif::VK_KHX_external_semaphore[] ifdef::VK_KHX_external_semaphore_win32[] -// refBegin vkImportSemaphoreWin32HandleKHX Import a semaphore from a Windows HANDLE +[open,refpage='vkImportSemaphoreWin32HandleKHX',desc='Import a semaphore from a Windows HANDLE',type='protos'] +-- To import semaphore state from a Windows handle, call: @@ -1645,8 +1688,10 @@ ownership using the fname:CloseHandle system call when the handle is no longer needed. include::../validity/protos/vkImportSemaphoreWin32HandleKHX.txt[] +-- -// refBegin VkImportSemaphoreWin32HandleInfoKHX Structure specifying Windows handle to import to a semaphore +[open,refpage='VkImportSemaphoreWin32HandleInfoKHX',desc='Structure specifying Windows handle to import to a semaphore',type='structs'] +-- The sname:VkImportSemaphoreWin32HandleInfoKHX structure is defined as: @@ -1682,12 +1727,14 @@ The handle types supported by pname:handleType are: **** include::../validity/structs/VkImportSemaphoreWin32HandleInfoKHX.txt[] +-- endif::VK_KHX_external_semaphore_win32[] ifdef::VK_KHX_external_semaphore_fd[] -// refBegin vkImportSemaphoreFdKHX Import a semaphore from a POSIX file descriptor +[open,refpage='vkImportSemaphoreFdKHX',desc='Import a semaphore from a POSIX file descriptor',type='protos'] +-- To import semaphore state from a POSIX file descriptor, call: @@ -1711,8 +1758,10 @@ after a successful import. **** include::../validity/protos/vkImportSemaphoreFdKHX.txt[] +-- -// refBegin VkImportSemaphoreFdInfoKHX Structure specifying POSIX file descriptor to import to a semaphore +[open,refpage='VkImportSemaphoreFdInfoKHX',desc='Structure specifying POSIX file descriptor to import to a semaphore',type='structs'] +-- The sname:VkImportSemaphoreFdInfoKHX structure is defined as: @@ -1747,6 +1796,7 @@ The handle types supported by pname:handleType are: **** include::../validity/structs/VkImportSemaphoreFdInfoKHX.txt[] +-- endif::VK_KHX_external_semaphore_fd[] @@ -1754,7 +1804,8 @@ endif::VK_KHX_external_semaphore_fd[] [[synchronization-events]] == Events -// refBegin VkEvent Opaque handle to a event object +[open,refpage='VkEvent',desc='Opaque handle to a event object',type='handles'] +-- Events are a synchronization primitive that can: be used to insert a fine-grained dependency between commands submitted to the same queue, or @@ -1771,9 +1822,10 @@ Events are represented by sname:VkEvent handles: include::../api/handles/VkEvent.txt[] -// refEnd VkEvent +-- -// refBegin vkCreateEvent Create a new event object +[open,refpage='vkCreateEvent',desc='Create a new event object',type='protos'] +-- To create an event, call: @@ -1791,8 +1843,10 @@ include::../api/protos/vkCreateEvent.txt[] When created, the event object is in the unsignaled state. include::../validity/protos/vkCreateEvent.txt[] +-- -// refBegin VkEventCreateInfo Structure specifying parameters of a newly created event +[open,refpage='VkEventCreateInfo',desc='Structure specifying parameters of a newly created event',type='structs'] +-- The sname:VkEventCreateInfo structure is defined as: @@ -1803,8 +1857,10 @@ include::../api/structs/VkEventCreateInfo.txt[] * pname:flags is reserved for future use. include::../validity/structs/VkEventCreateInfo.txt[] +-- -// refBegin vkDestroyEvent Destroy an event object +[open,refpage='vkDestroyEvent',desc='Destroy an event object',type='protos'] +-- To destroy an event, call: @@ -1829,8 +1885,10 @@ include::../api/protos/vkDestroyEvent.txt[] **** include::../validity/protos/vkDestroyEvent.txt[] +-- -// refBegin vkGetEventStatus Retrieve the status of an event object +[open,refpage='vkGetEventStatus',desc='Retrieve the status of an event object',type='protos'] +-- To query the state of an event from the host, call: @@ -1861,9 +1919,11 @@ If an event is already in the requested state, then updating it to the same state has no effect. include::../validity/protos/vkGetEventStatus.txt[] +-- [[synchronization-events-signaling-host]] -// refBegin vkSetEvent Set an event to signaled state +[open,refpage='vkSetEvent',desc='Set an event to signaled state',type='protos'] +-- To set the state of an event to signaled from the host, call: @@ -1880,9 +1940,11 @@ executed, then flink:vkSetEvent has no effect, and no event signal operation occurs. include::../validity/protos/vkSetEvent.txt[] +-- [[synchronization-events-unsignaling-host]] -// refBegin vkResetEvent Reset an event to non-signaled state +[open,refpage='vkResetEvent',desc='Reset an event to non-signaled state',type='protos'] +-- To set the state of an event to unsignaled from the host, call: @@ -1906,13 +1968,15 @@ operation occurs. **** include::../validity/protos/vkResetEvent.txt[] +-- The state of an event can: also be updated on the device by commands inserted in command buffers. [[synchronization-events-signaling-device]] -// refBegin vkCmdSetEvent Set an event object to signaled state +[open,refpage='vkCmdSetEvent',desc='Set an event object to signaled state',type='protos'] +-- To set the state of an event to signaled from a device, call: @@ -1963,9 +2027,11 @@ endif::VK_KHX_device_group[] **** include::../validity/protos/vkCmdSetEvent.txt[] +-- [[synchronization-events-unsignaling-device]] -// refBegin vkCmdResetEvent Reset an event object to non-signaled state +[open,refpage='vkCmdResetEvent',desc='Reset an event object to non-signaled state',type='protos'] +-- To set the state of an event to unsignaled from a device, call: @@ -2020,8 +2086,10 @@ endif::VK_KHX_device_group[] **** include::../validity/protos/vkCmdResetEvent.txt[] +-- -// refBegin vkCmdWaitEvents Wait for one or more events and insert a set of memory +[open,refpage='vkCmdWaitEvents',desc='Wait for one or more events and insert a set of memory',type='protos'] +-- To wait for one or more events to enter the signaled state on a device, call: @@ -2176,6 +2244,7 @@ endif::VK_KHX_device_group[] **** include::../validity/protos/vkCmdWaitEvents.txt[] +-- [[synchronization-pipeline-barriers]] @@ -2185,7 +2254,8 @@ flink:vkCmdPipelineBarrier is a synchronization command that inserts a dependency between commands submitted to the same queue, or between commands in the same subpass. -// refBegin vkCmdPipelineBarrier Insert a memory dependency +[open,refpage='vkCmdPipelineBarrier',desc='Insert a memory dependency',type='protos'] +-- To record a pipeline barrier, call: @@ -2377,8 +2447,10 @@ endif::VK_KHX_multiview[] **** include::../validity/protos/vkCmdPipelineBarrier.txt[] +-- -// refBegin VkDependencyFlagBits Bitmask specifying how execution and memory dependencies are formed +[open,refpage='VkDependencyFlagBits',desc='Bitmask specifying how execution and memory dependencies are formed',type='enums'] +-- Bits which can: be set in vkCmdPipelineBarrier::pname:dependencyFlags, specifying how execution and memory dependencies are formed, are: @@ -2398,7 +2470,7 @@ ifdef::VK_KHX_device_group[] dependency>>. endif::VK_KHX_device_group[] -// refEnd VkDependencyFlagBits +-- [[synchronization-pipeline-barriers-subpass-self-dependencies]] @@ -2467,7 +2539,8 @@ dependency that is created by a synchronization command that includes them. Global memory barriers apply to memory accesses involving all memory objects that exist at the time of its execution. -// refBegin VkMemoryBarrier Structure specifying a global memory barrier +[open,refpage='VkMemoryBarrier',desc='Structure specifying a global memory barrier',type='structs'] +-- The sname:VkMemoryBarrier structure is defined as: @@ -2489,6 +2562,7 @@ limited to access types in the <> specified by pname:dstAccessMask. include::../validity/structs/VkMemoryBarrier.txt[] +-- @@ -2504,7 +2578,8 @@ Buffer memory barriers can: also be used to define a <> for the specified buffer range. -// refBegin VkBufferMemoryBarrier Structure specifying a buffer memory barrier +[open,refpage='VkBufferMemoryBarrier',desc='Structure specifying a buffer memory barrier',type='structs'] +-- The sname:VkBufferMemoryBarrier structure is defined as: @@ -2621,6 +2696,7 @@ endif::VK_KHX_external_memory[] **** include::../validity/structs/VkBufferMemoryBarrier.txt[] +-- [[synchronization-image-memory-barriers]] @@ -2636,7 +2712,8 @@ Image memory barriers can: also be used to define <> for the specified image subresource range. -// refBegin VkImageMemoryBarrier Structure specifying the parameters of an image memory barrier +[open,refpage='VkImageMemoryBarrier',desc='Structure specifying the parameters of an image memory barrier',type='structs'] +-- The sname:VkImageMemoryBarrier structure is defined as: @@ -2799,6 +2876,7 @@ endif::VK_KHX_external_memory[] **** include::../validity/structs/VkImageMemoryBarrier.txt[] +-- [[synchronization-queue-transfers]] @@ -2920,7 +2998,8 @@ after a release or acquire operation. [[synchronization-wait-idle]] == Wait Idle Operations -// refBegin vkQueueWaitIdle Wait for a queue to become idle +[open,refpage='vkQueueWaitIdle',desc='Wait for a queue to become idle',type='protos'] +-- To wait on the host for the completion of outstanding queue operations for a given queue, call: @@ -2933,8 +3012,10 @@ fname:vkQueueWaitIdle is equivalent to submitting a fence to a queue and waiting with an infinite timeout for that fence to signal. include::../validity/protos/vkQueueWaitIdle.txt[] +-- -// refBegin vkDeviceWaitIdle Wait for a device to become idle +[open,refpage='vkDeviceWaitIdle',desc='Wait for a device to become idle',type='protos'] +-- To wait on the host for the completion of outstanding queue operations for all queues on a given logical device, call: @@ -2947,6 +3028,7 @@ fname:vkDeviceWaitIdle is equivalent to calling fname:vkQueueWaitIdle for all queues owned by pname:device. include::../validity/protos/vkDeviceWaitIdle.txt[] +-- [[synchronization-submission-host-writes]] diff --git a/doc/specs/vulkan/chapters/tessellation.txt b/doc/specs/vulkan/chapters/tessellation.txt index 195c3b13..15ba77ef 100644 --- a/doc/specs/vulkan/chapters/tessellation.txt +++ b/doc/specs/vulkan/chapters/tessellation.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[tessellation]] = Tessellation @@ -471,7 +472,8 @@ implementation-dependent. The pname:pTessellationState member of slink:VkGraphicsPipelineCreateInfo points to a structure of type sname:VkPipelineTessellationStateCreateInfo. -// refBegin VkPipelineTessellationStateCreateInfo Structure specifying parameters of a newly created pipeline tessellation state +[open,refpage='VkPipelineTessellationStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline tessellation state',type='structs'] +-- The sname:VkPipelineTessellationStateCreateInfo structure is defined as: @@ -490,3 +492,4 @@ include::../api/structs/VkPipelineTessellationStateCreateInfo.txt[] **** include::../validity/structs/VkPipelineTessellationStateCreateInfo.txt[] +-- diff --git a/doc/specs/vulkan/chapters/textures.txt b/doc/specs/vulkan/chapters/textures.txt index 8135e8af..4643fb23 100644 --- a/doc/specs/vulkan/chapters/textures.txt +++ b/doc/specs/vulkan/chapters/textures.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[textures]] = Image Operations @@ -125,8 +126,8 @@ For all coordinate types, unused coordinates are assigned a value of zero. [[textures-texel-coordinate-systems-diagrams]] image::images/vulkantexture0.png[align="center",title="Texel Coordinate Systems",{fullimagewidth}] -The Texel Coordinate Systems - For the example shown of an 8x4 texel two -dimensional image. +The Texel Coordinate Systems - For the example shown of an 8{times}4 texel +two dimensional image. * Normalized texel coordinates: ** The [eq]#s# coordinate goes from 0.0 to 1.0, left to right. @@ -156,8 +157,8 @@ dimensional image. image::images/vulkantexture1.png[align="center",title="Texel Coordinate Systems",{fullimagewidth}] -The Texel Coordinate Systems - For the example shown of an 8x4 texel two -dimensional image. +The Texel Coordinate Systems - For the example shown of an 8{times}4 texel +two dimensional image. * Texel coordinates as above. Also shown for nearest filtering: @@ -428,43 +429,35 @@ There are four cases to consider: . Valid Texel Coordinates + --- * If the texel coordinates pass validation (that is, the coordinates lie within the image), - ++ then the texel value comes from the value in image memory. --- . Border Texel + --- * If the texel coordinates fail validation, and * If the read is the result of an image sample instruction or image gather instruction, and * If the image is not a cube image, - ++ then the texel is a border texel and <> is performed. --- . Invalid Texel + --- * If the texel coordinates fail validation, and * If the read is the result of an image fetch instruction, image read instruction, or atomic instruction, - ++ then the texel is an invalid texel and <> is performed. --- . Cube Map Edge or Corner + --- Otherwise the texel coordinates lie on the borders along the edges and corners of a cube map image, and <> is performed. --- [[textures-cubemapedge]] @@ -478,20 +471,17 @@ ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. * Cube Map Edge Texel + --- - * If the texel lies along the border in either only [eq]#i# or only + ** If the texel lies along the border in either only [eq]#i# or only [eq]#j# - ++ then the texel lies along an edge, so the coordinates [eq]#(i,j)# and the array layer [eq]#l# are transformed to select the adjacent texel from the appropriate neighboring face. --- * Cube Map Corner Texel + --- - * If the texel lies along the border in both [eq]#i# and [eq]#j# - + ** If the texel lies along the border in both [eq]#i# and [eq]#j# ++ then the texel lies at a corner and there is no unique neighboring face from which to read that texel. The texel should: be replaced by the average of the three values of the @@ -499,7 +489,6 @@ adjacent texels in each incident face. However, implementations may: replace the cube map corner texel by other methods, subject to the constraint that if the three available samples have the same value, the replacement texel also has that value. --- [[textures-sparse-validation]] @@ -829,8 +818,8 @@ Derivative instructions are only available in a fragment shader. image::images/vulkantexture2.png[align="center",title="Implicit Derivatives",{fullimagewidth}] -Derivatives are computed as if there is a 2x2 neighborhood of fragments for -each fragment shader invocation. +Derivatives are computed as if there is a 2{times}2 neighborhood of +fragments for each fragment shader invocation. These neighboring fragments are used to compute derivatives with the assumption that the values of P in the neighborhood are piecewise linear. It is further assumed that the values of P in the neighborhood are locally @@ -848,7 +837,7 @@ dPdy_{i_1,j_1} & = dPdy_{i_1,j_0} & = P_{i_1,j_1} - P_{i_1,j_0} +++++++++++++++++++ The code:Fine derivative instructions must: return the values above, for a -group of fragments in a 2x2 neighborhood. +group of fragments in a 2{times}2 neighborhood. Coarse derivatives may: return only two values. In this case, the values should: be: @@ -1512,7 +1501,8 @@ parameters of the sampler, respectively. === Texel Gathering SPIR-V instructions with code:Gather in the name return a vector derived -from a 2x2 rectangular region of texels in the base level of the image view. +from a 2{times}2 rectangular region of texels in the base level of the image +view. The rules for the ename:VK_FILTER_LINEAR minification filter are applied to identify the four selected texels. Each texel is then converted to an RGBA value according to @@ -1575,39 +1565,39 @@ layer l. \end{aligned} ++++++++++++++++++++++++ -Within a mip level, ename:VK_FILTER_LINEAR filtering computes a weighted -average of 8 (for 3D), 4 (for 2D or Cube), or 2 (for 1D) texel values, using -the weights computed earlier: +Within a mip level, ename:VK_FILTER_LINEAR filtering combines 8 (for 3D), 4 +(for 2D or Cube), or 2 (for 1D) texel values, using the weights computed +earlier: [latexmath] ++++++++++++++++++++++++ \begin{aligned} -\tau_{3D}[level] & = (1-\alpha)(1-\beta)(1-\gamma)\tau_{i0j0k0}[level] \\ - & \, + (\alpha)(1-\beta)(1-\gamma)\tau_{i1j0k0}[level] \\ - & \, + (1-\alpha)(\beta)(1-\gamma)\tau_{i0j1k0}[level] \\ - & \, + (\alpha)(\beta)(1-\gamma)\tau_{i1j1k0}[level] \\ - & \, + (1-\alpha)(1-\beta)(\gamma)\tau_{i0j0k1}[level] \\ - & \, + (\alpha)(1-\beta)(\gamma)\tau_{i1j0k1}[level] \\ - & \, + (1-\alpha)(\beta)(\gamma)\tau_{i0j1k1}[level] \\ - & \, + (\alpha)(\beta)(\gamma)\tau_{i1j1k1}[level] +\tau_{3D}[level] & = reduce((1-\alpha)(1-\beta)(1-\gamma),\tau_{i0j0k0}[level], \\ + & \, (\alpha)(1-\beta)(1-\gamma),\tau_{i1j0k0}[level], \\ + & \, (1-\alpha)(\beta)(1-\gamma),\tau_{i0j1k0}[level], \\ + & \, (\alpha)(\beta)(1-\gamma),\tau_{i1j1k0}[level], \\ + & \, (1-\alpha)(1-\beta)(\gamma),\tau_{i0j0k1}[level], \\ + & \, (\alpha)(1-\beta)(\gamma),\tau_{i1j0k1}[level], \\ + & \, (1-\alpha)(\beta)(\gamma),\tau_{i0j1k1}[level], \\ + & \, (\alpha)(\beta)(\gamma),\tau_{i1j1k1}[level]) \end{aligned} ++++++++++++++++++++++++ [latexmath] ++++++++++++++++++++++++ \begin{aligned} -\tau_{2D}[level] & = (1-\alpha)(1-\beta)\tau_{i0j0}[level] \\ - & \, + (\alpha)(1-\beta)\tau_{i1j0}[level] \\ - & \, + (1-\alpha)(\beta)\tau_{i0j1}[level] \\ - & \, + (\alpha)(\beta)\tau_{i1j1}[level] +\tau_{2D}[level] & = reduce((1-\alpha)(1-\beta),\tau_{i0j0}[level], \\ + & \, (\alpha)(1-\beta),\tau_{i1j0}[level], \\ + & \, (1-\alpha)(\beta),\tau_{i0j1}[level], \\ + & \, (\alpha)(\beta),\tau_{i1j1}[level]) \end{aligned} ++++++++++++++++++++++++ [latexmath] ++++++++++++++++++++++++ \begin{aligned} -\tau_{1D}[level] & = (1-\alpha)\tau_{i0}[level] \\ - & \, + (\alpha)\tau_{i1}[level] +\tau_{1D}[level] & = reduce((1-\alpha),\tau_{i0}[level], \\ + & \, (\alpha),\tau_{i1}[level]) \end{aligned} ++++++++++++++++++++++++ @@ -1623,6 +1613,24 @@ the weights computed earlier: \end{aligned} ++++++++++++++++++++++++ +The function [eq]#reduce()# is defined to operate on pairs of weights and +texel values as follows. +When using linear or anisotropic filtering, the values of multiple texels +are combined using a weighted average to produce a filtered texture value. +ifdef::VK_EXT_sampler_filter_minmax[] +However, a filtered texture value can: also be produced by computing +per-component minimum and maximum values over the set of texels that would +normally be averaged. +The slink:VkSamplerReductionModeCreateInfoEXT::pname:reductionMode controls +the process by which multiple texels are combined to produce a filtered +texture value. +When set to ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT, a weighted +average is computed. +If the reduction mode is ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT or +ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT, reduce() computes a component-wise +minimum or maximum, respectively, of the components of the set of provided +texels with non-zero weights. +endif::VK_EXT_sampler_filter_minmax[] ifdef::VK_IMG_filter_cubic[] include::VK_IMG_filter_cubic/filter_cubic_texel_filtering.txt[] @@ -1637,7 +1645,7 @@ computes a weighted average between neighboring mip levels: \tau &= \begin{cases} \tau[d], & \text{for mip mode BASE or NEAREST} \\ - (1-\delta)\tau[d_{hi}]+\delta\tau[d_{lo}], & \text{for mip mode LINEAR} + reduce((1-\delta),\tau[d_{hi}],\delta,\tau[d_{lo}]), & \text{for mip mode LINEAR} \end{cases} \end{aligned} ++++++++++++++++++++++++ @@ -1693,6 +1701,18 @@ The sum [eq]#{tau}~2Daniso~# is defined using the single isotropic \end{aligned} ++++++++++++++++++++++++ +ifdef::VK_EXT_sampler_filter_minmax[] + +When slink:VkSamplerReductionModeCreateInfoEXT::pname:reductionMode is set +to ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT, the above summation +is used. +If the reduction mode is ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT or +ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT, then the value is instead computed +as [eq]#\tau_{2Daniso} = reduce(\tau_1, ..., \tau_N)#, combining all texel +values with non-zero weights. + +endif::VK_EXT_sampler_filter_minmax[] + ifdef::editing-notes[] [NOTE] .editing-note diff --git a/doc/specs/vulkan/chapters/vertexpostproc.txt b/doc/specs/vulkan/chapters/vertexpostproc.txt index ba81b214..111aba89 100644 --- a/doc/specs/vulkan/chapters/vertexpostproc.txt +++ b/doc/specs/vulkan/chapters/vertexpostproc.txt @@ -1,5 +1,6 @@ -// Copyright (c) 2015-2017 The Khronos Group Inc. -// Copyright notice at https://www.khronos.org/registry/speccopyright.html +// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ [[vertexpostproc]] = Fixed-Function Vertex Post-Processing @@ -42,7 +43,8 @@ ifdef::VK_NV_viewport_swizzle[] [[vertexpostproc-viewport-swizzle]] == Viewport Swizzle -// refBegin VkPipelineViewportSwizzleStateCreateInfoNV Structure specifying swizzle applied to primitive clip coordinates +[open,refpage='VkPipelineViewportSwizzleStateCreateInfoNV',desc='Structure specifying swizzle applied to primitive clip coordinates',type='structs'] +-- Each primitive sent to a given viewport has a swizzle and optional negation applied to its clip coordinates. @@ -67,6 +69,7 @@ include::../api/structs/VkPipelineViewportSwizzleStateCreateInfoNV.txt[] **** include::../validity/structs/VkPipelineViewportSwizzleStateCreateInfoNV.txt[] +-- The sname:VkPipelineViewportSwizzleStateCreateInfoNV state is set by adding an instance of this structure to the pname:pNext chain of an instance of the @@ -104,7 +107,8 @@ sname:VkPipelineViewportSwizzleStateCreateInfoNV. slink:VkPipelineViewportSwizzleStateCreateInfoNV uses sname:VkViewportSwizzleNV to set the viewport swizzle parameters. -// refBegin VkViewportSwizzleNV Structure specifying a viewport swizzle +[open,refpage='VkViewportSwizzleNV',desc='Structure specifying a viewport swizzle',type='structs'] +-- The sname:VkViewportSwizzleNV structure is defined as: @@ -120,8 +124,10 @@ include::../api/structs/VkViewportSwizzleNV.txt[] swizzle operation to apply to the w component of the primitive include::../validity/structs/VkViewportSwizzleNV.txt[] +-- -// refBegin VkViewportCoordinateSwizzleNV Specify how a viewport coordinate is swizzled +[open,refpage='VkViewportCoordinateSwizzleNV',desc='Specify how a viewport coordinate is swizzled',type='enums'] +-- Possible values of the elink:VkViewportSwizzleNV::pname:x, pname:y, pname:z, and pname:w members, specifying swizzling of the corresponding components of @@ -132,7 +138,7 @@ include::../api/enums/VkViewportCoordinateSwizzleNV.txt[] These values are described in detail in <>. -// refEnd VkViewportCoordinateSwizzleNV +-- endif::VK_NV_viewport_swizzle[] @@ -426,7 +432,8 @@ The number of viewports used by a pipeline is controlled by the pname:viewportCount member of the sname:VkPipelineViewportStateCreateInfo structure used in pipeline creation. -// refBegin VkPipelineViewportStateCreateInfo Structure specifying parameters of a newly created pipeline viewport state +[open,refpage='VkPipelineViewportStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline viewport state',type='structs'] +-- The sname:VkPipelineViewportStateCreateInfo structure is defined as: @@ -465,6 +472,7 @@ include::../api/structs/VkPipelineViewportStateCreateInfo.txt[] **** include::../validity/structs/VkPipelineViewportStateCreateInfo.txt[] +-- ifndef::VK_NV_viewport_array2[] If a geometry shader is active and has an output variable decorated with @@ -507,7 +515,8 @@ primitives such as ename:VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP. In this case, the viewport transformation is applied separately for each primitive. -// refBegin vkCmdSetViewport Set the viewport on a command buffer +[open,refpage='vkCmdSetViewport',desc='Set the viewport on a command buffer',type='protos'] +-- If the bound pipeline state object was not created with the ename:VK_DYNAMIC_STATE_VIEWPORT dynamic state enabled, viewport @@ -555,11 +564,13 @@ replace the current state for the viewport index [eq]#pname:firstViewport **** include::../validity/protos/vkCmdSetViewport.txt[] +-- Both slink:VkPipelineViewportStateCreateInfo and flink:vkCmdSetViewport use sname:VkViewport to set the viewport transformation parameters. -// refBegin VkViewport Structure specifying a viewport +[open,refpage='VkViewport',desc='Structure specifying a viewport',type='structs'] +-- The sname:VkViewport structure is defined as: @@ -649,3 +660,4 @@ endif::VK_AMD_negative_viewport_height[] **** include::../validity/structs/VkViewport.txt[] +-- diff --git a/doc/specs/vulkan/config/asciidoctor-mathematical-ext.rb b/doc/specs/vulkan/config/asciidoctor-mathematical-ext.rb new file mode 100644 index 00000000..5a00fa60 --- /dev/null +++ b/doc/specs/vulkan/config/asciidoctor-mathematical-ext.rb @@ -0,0 +1,19 @@ +require 'asciidoctor/extensions' + +# This script makes [latexmath] blocks work within table cells. +# See https://github.com/asciidoctor/asciidoctor-pdf/issues/740 + +Asciidoctor::Extensions.register do + treeprocessor do + process do |doc| + mathematicalProcessor = MathematicalTreeprocessor.new + (table_blocks = doc.find_by context: :table).each do |table| + (table.rows[:body] + table.rows[:foot]).each do |row| + row.each do |cell| + mathematicalProcessor.process cell.inner_document if cell.style == :asciidoc + end + end + end + end + end +end diff --git a/doc/specs/vulkan/config/attribs.txt b/doc/specs/vulkan/config/attribs.txt index 527f198e..07f7d179 100644 --- a/doc/specs/vulkan/config/attribs.txt +++ b/doc/specs/vulkan/config/attribs.txt @@ -1,9 +1,11 @@ // Various special / math symbols, matching LaTeX names. +// Per #845, @tobias suggested the pass:[+ ] notation to avoid asciidoctor +// EOL treatment of the attribute. :sym1: ✓ :sym2: † :times: × -:plus: + +:plus: pass:[+ ] :geq: ≥ :leq: ≤ :neq: ≠ diff --git a/doc/specs/vulkan/config/extDependency.py b/doc/specs/vulkan/config/extDependency.py index e63558f1..5ea49624 100644 --- a/doc/specs/vulkan/config/extDependency.py +++ b/doc/specs/vulkan/config/extDependency.py @@ -10,6 +10,7 @@ extensions['VK_EXT_direct_mode_display'] = [ 'VK_KHR_display', 'VK_KHR_surface' extensions['VK_EXT_discard_rectangles'] = [ 'VK_KHR_get_physical_device_properties2' ] extensions['VK_EXT_display_control'] = [ 'VK_EXT_display_surface_counter', 'VK_KHR_display', 'VK_KHR_surface', 'VK_KHR_swapchain' ] extensions['VK_EXT_display_surface_counter'] = [ 'VK_KHR_display', 'VK_KHR_surface' ] +extensions['VK_EXT_sampler_filter_minmax'] = [ 'VK_KHR_get_physical_device_properties2' ] extensions['VK_EXT_swapchain_colorspace'] = [ 'VK_KHR_surface' ] extensions['VK_GOOGLE_display_timing'] = [ 'VK_KHR_surface', 'VK_KHR_swapchain' ] extensions['VK_KHR_android_surface'] = [ 'VK_KHR_surface' ] @@ -25,7 +26,7 @@ extensions['VK_KHR_wayland_surface'] = [ 'VK_KHR_surface' ] extensions['VK_KHR_win32_surface'] = [ 'VK_KHR_surface' ] extensions['VK_KHR_xcb_surface'] = [ 'VK_KHR_surface' ] extensions['VK_KHR_xlib_surface'] = [ 'VK_KHR_surface' ] -extensions['VK_KHX_device_group'] = [ 'VK_KHR_surface', 'VK_KHR_swapchain' ] +extensions['VK_KHX_device_group'] = [ 'VK_KHR_surface', 'VK_KHR_swapchain', 'VK_KHX_device_group_creation' ] extensions['VK_KHX_external_memory'] = [ 'VK_KHR_get_physical_device_properties2', 'VK_KHX_external_memory_capabilities' ] extensions['VK_KHX_external_memory_capabilities'] = [ 'VK_KHR_get_physical_device_properties2' ] extensions['VK_KHX_external_memory_fd'] = [ 'VK_KHR_get_physical_device_properties2', 'VK_KHX_external_memory', 'VK_KHX_external_memory_capabilities' ] @@ -44,6 +45,6 @@ extensions['VK_NV_external_memory_win32'] = [ 'VK_NV_external_memory', 'VK_NV_ex extensions['VK_NV_win32_keyed_mutex'] = [ 'VK_NV_external_memory', 'VK_NV_external_memory_capabilities', 'VK_NV_external_memory_win32' ] # Define lists of all / KHR / KHX extensions -allExts = [ 'VK_AMD_draw_indirect_count', 'VK_AMD_gcn_shader', 'VK_AMD_gpu_shader_half_float', 'VK_AMD_negative_viewport_height', 'VK_AMD_rasterization_order', 'VK_AMD_shader_ballot', 'VK_AMD_shader_explicit_vertex_parameter', 'VK_AMD_shader_trinary_minmax', 'VK_AMD_texture_gather_bias_lod', 'VK_EXT_acquire_xlib_display', 'VK_EXT_debug_marker', 'VK_EXT_debug_report', 'VK_EXT_direct_mode_display', 'VK_EXT_discard_rectangles', 'VK_EXT_display_control', 'VK_EXT_display_surface_counter', 'VK_EXT_hdr_metadata', 'VK_EXT_shader_subgroup_ballot', 'VK_EXT_shader_subgroup_vote', 'VK_EXT_swapchain_colorspace', 'VK_EXT_validation_flags', 'VK_GOOGLE_display_timing', 'VK_IMG_filter_cubic', 'VK_IMG_format_pvrtc', 'VK_KHR_android_surface', 'VK_KHR_descriptor_update_template', 'VK_KHR_display', 'VK_KHR_display_swapchain', 'VK_KHR_get_physical_device_properties2', 'VK_KHR_get_surface_capabilities2', 'VK_KHR_incremental_present', 'VK_KHR_maintenance1', 'VK_KHR_mir_surface', 'VK_KHR_push_descriptor', 'VK_KHR_sampler_mirror_clamp_to_edge', 'VK_KHR_shader_draw_parameters', 'VK_KHR_shared_presentable_image', 'VK_KHR_surface', 'VK_KHR_swapchain', 'VK_KHR_wayland_surface', 'VK_KHR_win32_surface', 'VK_KHR_xcb_surface', 'VK_KHR_xlib_surface', 'VK_KHX_device_group', 'VK_KHX_device_group_creation', 'VK_KHX_external_memory', 'VK_KHX_external_memory_capabilities', 'VK_KHX_external_memory_fd', 'VK_KHX_external_memory_win32', 'VK_KHX_external_semaphore', 'VK_KHX_external_semaphore_capabilities', 'VK_KHX_external_semaphore_fd', 'VK_KHX_external_semaphore_win32', 'VK_KHX_multiview', 'VK_KHX_win32_keyed_mutex', 'VK_MVK_ios_surface', 'VK_MVK_macos_surface', 'VK_NN_vi_surface', 'VK_NVX_device_generated_commands', 'VK_NVX_multiview_per_view_attributes', 'VK_NV_clip_space_w_scaling', 'VK_NV_dedicated_allocation', 'VK_NV_external_memory', 'VK_NV_external_memory_capabilities', 'VK_NV_external_memory_win32', 'VK_NV_geometry_shader_passthrough', 'VK_NV_glsl_shader', 'VK_NV_sample_mask_override_coverage', 'VK_NV_viewport_array2', 'VK_NV_viewport_swizzle', 'VK_NV_win32_keyed_mutex' ] +allExts = [ 'VK_AMD_draw_indirect_count', 'VK_AMD_gcn_shader', 'VK_AMD_gpu_shader_half_float', 'VK_AMD_gpu_shader_int16', 'VK_AMD_negative_viewport_height', 'VK_AMD_rasterization_order', 'VK_AMD_shader_ballot', 'VK_AMD_shader_explicit_vertex_parameter', 'VK_AMD_shader_trinary_minmax', 'VK_AMD_texture_gather_bias_lod', 'VK_EXT_acquire_xlib_display', 'VK_EXT_blend_operation_advanced', 'VK_EXT_debug_marker', 'VK_EXT_debug_report', 'VK_EXT_direct_mode_display', 'VK_EXT_discard_rectangles', 'VK_EXT_display_control', 'VK_EXT_display_surface_counter', 'VK_EXT_hdr_metadata', 'VK_EXT_sampler_filter_minmax', 'VK_EXT_shader_subgroup_ballot', 'VK_EXT_shader_subgroup_vote', 'VK_EXT_swapchain_colorspace', 'VK_EXT_validation_flags', 'VK_GOOGLE_display_timing', 'VK_IMG_filter_cubic', 'VK_IMG_format_pvrtc', 'VK_KHR_android_surface', 'VK_KHR_descriptor_update_template', 'VK_KHR_display', 'VK_KHR_display_swapchain', 'VK_KHR_get_physical_device_properties2', 'VK_KHR_get_surface_capabilities2', 'VK_KHR_incremental_present', 'VK_KHR_maintenance1', 'VK_KHR_mir_surface', 'VK_KHR_push_descriptor', 'VK_KHR_sampler_mirror_clamp_to_edge', 'VK_KHR_shader_draw_parameters', 'VK_KHR_shared_presentable_image', 'VK_KHR_surface', 'VK_KHR_swapchain', 'VK_KHR_wayland_surface', 'VK_KHR_win32_surface', 'VK_KHR_xcb_surface', 'VK_KHR_xlib_surface', 'VK_KHX_device_group', 'VK_KHX_device_group_creation', 'VK_KHX_external_memory', 'VK_KHX_external_memory_capabilities', 'VK_KHX_external_memory_fd', 'VK_KHX_external_memory_win32', 'VK_KHX_external_semaphore', 'VK_KHX_external_semaphore_capabilities', 'VK_KHX_external_semaphore_fd', 'VK_KHX_external_semaphore_win32', 'VK_KHX_multiview', 'VK_KHX_win32_keyed_mutex', 'VK_MVK_ios_surface', 'VK_MVK_macos_surface', 'VK_NN_vi_surface', 'VK_NVX_device_generated_commands', 'VK_NVX_multiview_per_view_attributes', 'VK_NV_clip_space_w_scaling', 'VK_NV_dedicated_allocation', 'VK_NV_external_memory', 'VK_NV_external_memory_capabilities', 'VK_NV_external_memory_win32', 'VK_NV_fill_rectangle', 'VK_NV_fragment_coverage_to_color', 'VK_NV_framebuffer_mixed_samples', 'VK_NV_geometry_shader_passthrough', 'VK_NV_glsl_shader', 'VK_NV_sample_mask_override_coverage', 'VK_NV_viewport_array2', 'VK_NV_viewport_swizzle', 'VK_NV_win32_keyed_mutex' ] khrExts = [ 'VK_KHR_android_surface', 'VK_KHR_descriptor_update_template', 'VK_KHR_display', 'VK_KHR_display_swapchain', 'VK_KHR_get_physical_device_properties2', 'VK_KHR_get_surface_capabilities2', 'VK_KHR_incremental_present', 'VK_KHR_maintenance1', 'VK_KHR_mir_surface', 'VK_KHR_push_descriptor', 'VK_KHR_sampler_mirror_clamp_to_edge', 'VK_KHR_shader_draw_parameters', 'VK_KHR_shared_presentable_image', 'VK_KHR_surface', 'VK_KHR_swapchain', 'VK_KHR_wayland_surface', 'VK_KHR_win32_surface', 'VK_KHR_xcb_surface', 'VK_KHR_xlib_surface' ] khxExts = [ 'VK_KHX_device_group', 'VK_KHX_device_group_creation', 'VK_KHX_external_memory', 'VK_KHX_external_memory_capabilities', 'VK_KHX_external_memory_fd', 'VK_KHX_external_memory_win32', 'VK_KHX_external_semaphore', 'VK_KHX_external_semaphore_capabilities', 'VK_KHX_external_semaphore_fd', 'VK_KHX_external_semaphore_win32', 'VK_KHX_multiview', 'VK_KHX_win32_keyed_mutex' ] diff --git a/doc/specs/vulkan/config/extDependency.sh b/doc/specs/vulkan/config/extDependency.sh index e2f392da..1446be39 100644 --- a/doc/specs/vulkan/config/extDependency.sh +++ b/doc/specs/vulkan/config/extDependency.sh @@ -10,6 +10,7 @@ extensions[VK_EXT_direct_mode_display]="VK_KHR_display VK_KHR_surface" extensions[VK_EXT_discard_rectangles]="VK_KHR_get_physical_device_properties2" extensions[VK_EXT_display_control]="VK_EXT_display_surface_counter VK_KHR_display VK_KHR_surface VK_KHR_swapchain" extensions[VK_EXT_display_surface_counter]="VK_KHR_display VK_KHR_surface" +extensions[VK_EXT_sampler_filter_minmax]="VK_KHR_get_physical_device_properties2" extensions[VK_EXT_swapchain_colorspace]="VK_KHR_surface" extensions[VK_GOOGLE_display_timing]="VK_KHR_surface VK_KHR_swapchain" extensions[VK_KHR_android_surface]="VK_KHR_surface" @@ -25,7 +26,7 @@ extensions[VK_KHR_wayland_surface]="VK_KHR_surface" extensions[VK_KHR_win32_surface]="VK_KHR_surface" extensions[VK_KHR_xcb_surface]="VK_KHR_surface" extensions[VK_KHR_xlib_surface]="VK_KHR_surface" -extensions[VK_KHX_device_group]="VK_KHR_surface VK_KHR_swapchain" +extensions[VK_KHX_device_group]="VK_KHR_surface VK_KHR_swapchain VK_KHX_device_group_creation" extensions[VK_KHX_external_memory]="VK_KHR_get_physical_device_properties2 VK_KHX_external_memory_capabilities" extensions[VK_KHX_external_memory_capabilities]="VK_KHR_get_physical_device_properties2" extensions[VK_KHX_external_memory_fd]="VK_KHR_get_physical_device_properties2 VK_KHX_external_memory VK_KHX_external_memory_capabilities" @@ -44,6 +45,6 @@ extensions[VK_NV_external_memory_win32]="VK_NV_external_memory VK_NV_external_me extensions[VK_NV_win32_keyed_mutex]="VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32" # Define lists of all / KHR / KHX extensions -allExts="VK_AMD_draw_indirect_count VK_AMD_gcn_shader VK_AMD_gpu_shader_half_float VK_AMD_negative_viewport_height VK_AMD_rasterization_order VK_AMD_shader_ballot VK_AMD_shader_explicit_vertex_parameter VK_AMD_shader_trinary_minmax VK_AMD_texture_gather_bias_lod VK_EXT_acquire_xlib_display VK_EXT_debug_marker VK_EXT_debug_report VK_EXT_direct_mode_display VK_EXT_discard_rectangles VK_EXT_display_control VK_EXT_display_surface_counter VK_EXT_hdr_metadata VK_EXT_shader_subgroup_ballot VK_EXT_shader_subgroup_vote VK_EXT_swapchain_colorspace VK_EXT_validation_flags VK_GOOGLE_display_timing VK_IMG_filter_cubic VK_IMG_format_pvrtc VK_KHR_android_surface VK_KHR_descriptor_update_template VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_get_surface_capabilities2 VK_KHR_incremental_present VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_push_descriptor VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_shared_presentable_image VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface VK_KHX_device_group VK_KHX_device_group_creation VK_KHX_external_memory VK_KHX_external_memory_capabilities VK_KHX_external_memory_fd VK_KHX_external_memory_win32 VK_KHX_external_semaphore VK_KHX_external_semaphore_capabilities VK_KHX_external_semaphore_fd VK_KHX_external_semaphore_win32 VK_KHX_multiview VK_KHX_win32_keyed_mutex VK_MVK_ios_surface VK_MVK_macos_surface VK_NN_vi_surface VK_NVX_device_generated_commands VK_NVX_multiview_per_view_attributes VK_NV_clip_space_w_scaling VK_NV_dedicated_allocation VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32 VK_NV_geometry_shader_passthrough VK_NV_glsl_shader VK_NV_sample_mask_override_coverage VK_NV_viewport_array2 VK_NV_viewport_swizzle VK_NV_win32_keyed_mutex" +allExts="VK_AMD_draw_indirect_count VK_AMD_gcn_shader VK_AMD_gpu_shader_half_float VK_AMD_gpu_shader_int16 VK_AMD_negative_viewport_height VK_AMD_rasterization_order VK_AMD_shader_ballot VK_AMD_shader_explicit_vertex_parameter VK_AMD_shader_trinary_minmax VK_AMD_texture_gather_bias_lod VK_EXT_acquire_xlib_display VK_EXT_blend_operation_advanced VK_EXT_debug_marker VK_EXT_debug_report VK_EXT_direct_mode_display VK_EXT_discard_rectangles VK_EXT_display_control VK_EXT_display_surface_counter VK_EXT_hdr_metadata VK_EXT_sampler_filter_minmax VK_EXT_shader_subgroup_ballot VK_EXT_shader_subgroup_vote VK_EXT_swapchain_colorspace VK_EXT_validation_flags VK_GOOGLE_display_timing VK_IMG_filter_cubic VK_IMG_format_pvrtc VK_KHR_android_surface VK_KHR_descriptor_update_template VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_get_surface_capabilities2 VK_KHR_incremental_present VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_push_descriptor VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_shared_presentable_image VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface VK_KHX_device_group VK_KHX_device_group_creation VK_KHX_external_memory VK_KHX_external_memory_capabilities VK_KHX_external_memory_fd VK_KHX_external_memory_win32 VK_KHX_external_semaphore VK_KHX_external_semaphore_capabilities VK_KHX_external_semaphore_fd VK_KHX_external_semaphore_win32 VK_KHX_multiview VK_KHX_win32_keyed_mutex VK_MVK_ios_surface VK_MVK_macos_surface VK_NN_vi_surface VK_NVX_device_generated_commands VK_NVX_multiview_per_view_attributes VK_NV_clip_space_w_scaling VK_NV_dedicated_allocation VK_NV_external_memory VK_NV_external_memory_capabilities VK_NV_external_memory_win32 VK_NV_fill_rectangle VK_NV_fragment_coverage_to_color VK_NV_framebuffer_mixed_samples VK_NV_geometry_shader_passthrough VK_NV_glsl_shader VK_NV_sample_mask_override_coverage VK_NV_viewport_array2 VK_NV_viewport_swizzle VK_NV_win32_keyed_mutex" khrExts="VK_KHR_android_surface VK_KHR_descriptor_update_template VK_KHR_display VK_KHR_display_swapchain VK_KHR_get_physical_device_properties2 VK_KHR_get_surface_capabilities2 VK_KHR_incremental_present VK_KHR_maintenance1 VK_KHR_mir_surface VK_KHR_push_descriptor VK_KHR_sampler_mirror_clamp_to_edge VK_KHR_shader_draw_parameters VK_KHR_shared_presentable_image VK_KHR_surface VK_KHR_swapchain VK_KHR_wayland_surface VK_KHR_win32_surface VK_KHR_xcb_surface VK_KHR_xlib_surface" khxExts="VK_KHX_device_group VK_KHX_device_group_creation VK_KHX_external_memory VK_KHX_external_memory_capabilities VK_KHX_external_memory_fd VK_KHX_external_memory_win32 VK_KHX_external_semaphore VK_KHX_external_semaphore_capabilities VK_KHX_external_semaphore_fd VK_KHX_external_semaphore_win32 VK_KHX_multiview VK_KHX_win32_keyed_mutex" diff --git a/doc/specs/vulkan/copyright-spec.txt b/doc/specs/vulkan/copyright-spec.txt index 5ac9c17a..77d40901 100644 --- a/doc/specs/vulkan/copyright-spec.txt +++ b/doc/specs/vulkan/copyright-spec.txt @@ -1,31 +1,35 @@ -Copyright (C) 2014-2017 The Khronos Group Inc. All Rights Reserved. +Copyright 2014-2017 The Khronos Group Inc. This specification is protected by copyright laws and contains material proprietary -to the Khronos Group, Inc. It or any components may not be reproduced, republished, -distributed, transmitted, displayed, broadcast or otherwise exploited in any -manner without the express prior written permission of Khronos Group. You may -use this specification for implementing the functionality therein, without altering or -removing any trademark, copyright or other notice from the specification, but the -receipt or possession of this specification does not convey any rights to reproduce, -disclose, or distribute its contents, or to manufacture, use, or sell anything that it -may describe, in whole or in part. +to Khronos. Except as described by these terms, it or any components +may not be reproduced, republished, distributed, transmitted, displayed, broadcast +or otherwise exploited in any manner without the express prior written permission +of Khronos. -Khronos Group grants express permission to any current Promoter, Contributor -or Adopter member of Khronos to copy and redistribute UNMODIFIED versions -of this specification in any fashion, provided that NO CHARGE is made for the -specification and the latest available update of the specification for any version -of the API is used whenever possible. Such distributed specification may be reformatted -AS LONG AS the contents of the specification are not changed in any -way. The specification may be incorporated into a product that is sold as long as -such product includes significant independent work developed by the seller. A link -to the current version of this specification on the Khronos Group web-site should -be included whenever possible with specification distributions. +This specification has been created under the Khronos Intellectual Property Rights +Policy, which is Attachment A of the Khronos Group Membership Agreement available at +www.khronos.org/files/member_agreement.pdf. Khronos Group grants a conditional +copyright license to use and reproduce the unmodified specification for any purpose, +without fee or royalty, EXCEPT no licenses to any patent, trademark or other +intellectual property rights are granted under these terms. Parties desiring to +implement the specification and make use of Khronos trademarks in relation to that +implementation, and receive reciprocal patent license protection under the Khronos +IP Policy must become Adopters and confirm the implementation as conformant under +the process defined by Khronos for this specification; +see https://www.khronos.org/adopters. -This specification has been created under the Khronos Intellectual Property Rights Policy, -which is Attachment A of the Khronos Group Membership Agreement available at -www.khronos.org/files/member_agreement.pdf. This specification contains substantially -unmodified functionality from, and is a successor to, Khronos specifications including -OpenGL, OpenGL ES and OpenCL. +Khronos makes no, and expressly disclaims any, representations or warranties, +express or implied, regarding this specification, including, without limitation: +merchantability, fitness for a particular purpose, non-infringement of any +intellectual property, correctness, accuracy, completeness, timeliness, and +reliability. Under no circumstances will Khronos, or any of its Promoters, +Contributors or Members, or their respective partners, officers, directors, +employees, agents or representatives be liable for any damages, whether direct, +indirect, special or consequential damages for lost revenues, lost profits, or +otherwise, arising from or in connection with these materials. + +This specification contains substantially unmodified functionality from, and is a +successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL. Some parts of this Specification are purely informative and do not define requirements necessary for compliance and so are outside the Scope of this Specification. These @@ -50,19 +54,8 @@ Scope. Requirements defined by external documents not created by Khronos may con contributions from non-members of Khronos not covered by the Khronos Intellectual Property Rights Policy. -Khronos Group makes no, and expressly disclaims any, representations or warranties, -express or implied, regarding this specification, including, without limitation, -any implied warranties of merchantability or fitness for a particular purpose -or non-infringement of any intellectual property. Khronos Group makes no, and -expressly disclaims any, warranties, express or implied, regarding the correctness, -accuracy, completeness, timeliness, and reliability of the specification. Under no -circumstances will the Khronos Group, or any of its Promoters, Contributors or -Members or their respective partners, officers, directors, employees, agents or -representatives be liable for any damages, whether direct, indirect, special or -consequential damages for lost revenues, lost profits, or otherwise, arising from or in -connection with these materials. - -Khronos is a trademark, and Vulkan is a registered trademark of The Khronos -Group Inc. OpenCL is a trademark of Apple Inc. and OpenGL is a registered -trademark of Silicon Graphics International, both used under license by -Khronos. +Vulkan is a registered trademark, and Khronos is a trademark of The Khronos +Group Inc. ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple Inc.; +and OpenGL is a registered trademark of Silicon Graphics International, all used under license by +Khronos. All other product names, trademarks, and/or company names are used solely for +identification and belong to their respective owners. diff --git a/doc/specs/vulkan/fixupRef.py b/doc/specs/vulkan/fixupRef.py index 7ca90a51..7eece726 100755 --- a/doc/specs/vulkan/fixupRef.py +++ b/doc/specs/vulkan/fixupRef.py @@ -23,11 +23,6 @@ from reflib import * from vkapi import * import argparse, copy, io, os, pdb, re, string, sys -# Return True if name is a Vulkan extension name (ends with an upper-case -# author ID). This assumes that author IDs are at least two characters. -def isextension(name): - return name[-2:].isalpha() and name[-2:].isupper() - # Return 'None' for None, the string otherwise def noneStr(str): if str == None: @@ -40,13 +35,26 @@ def escapeQuote(str): return str.replace("'", "\'") # Start a refpage open block -def openBlock(name, desc, type, fp): - print("[open,refpage='" + name + - "',desc='" + desc + - "',type='" + type + "']", - file=fp) +def openBlock(pi, fp): + if pi.refs != '': + print("[open,refpage='" + pi.name + + "',desc='" + pi.desc + + "',type='" + pi.type + + "',xrefs='" + pi.refs + "']", + file=fp) + else: + print("[open,refpage='" + pi.name + + "',desc='" + pi.desc + + "',type='" + pi.type + "']", + file=fp) print('--', file=fp) +# End a refpage open block +def closeBlock(pi, fp): + print('--', file=fp) + # Just for finding block ends while debugging + # print("// end [open,refpage='" + pi.name + "']", file=fp) + # Replace old // refBegin .. // refEnd references in an asciidoc # file with open blocks, per # ??? . # specFile - filename to extract from @@ -72,58 +80,58 @@ def replaceRef(specFile, outDir, overwrite = False, skipped = set()): # Map the page info dictionary into a dictionary of actions # keyed by line number they're performed on/after: - # { 'refBegin', name, description } -> replace refBegin line with block start - # { 'addBegin', name, description } -> add block start preceding this line - # { 'refEnd', name, description } -> replace refEnd line with block end - # { 'addEnd', name, description } -> add block end following this line + # 'action' : 'begin' or 'end'. What to do on a refBegin or refEnd line + # 'replace': True if this line needs to be replaced + # 'name' : Name of the ref page being defined + # 'desc' : One-line description of the ref page being defined + # 'type' : Type of the ref page being defined, 'structs', 'protos', etc. + # 'refs' : Space-separated string of crossreferenced pages actions = { } for name in pageMap.keys(): pi = pageMap[name] - # Leave refBegin/refEnd alone for enums, for now - if pi.type != 'enums' and pi.extractPage: + # Cleanup parameters for output + pi.name = noneStr(pi.name) + pi.desc = escapeQuote(noneStr(pi.desc)) + + if pi.extractPage: if (file[pi.begin][0:11] == '// refBegin'): # Replace line actions[pi.begin] = { - 'action' : 'begin', - 'replace': True, - 'name' : pi.name, - 'desc' : pi.desc, - 'type' : pi.type + 'action' : 'begin', + 'replace' : True, + 'pageinfo' : pi } else: # Insert line actions[pi.begin] = { - 'action' : 'begin', - 'replace': False, - 'name' : pi.name, - 'desc' : pi.desc, - 'type' : pi.type + 'action' : 'begin', + 'replace' : False, + 'pageinfo' : pi } if (file[pi.end][0:9] == '// refEnd'): # Replace line actions[pi.end] = { - 'action' : 'end', - 'replace': True, - 'name' : pi.name, - 'desc' : pi.desc, - 'type' : pi.type + 'action' : 'end', + 'replace' : True, + 'pageinfo' : pi } else: # Insert line actions[pi.end] = { - 'action' : 'end', - 'replace': False, - 'name' : pi.name, - 'desc' : pi.desc, - 'type' : pi.type + 'action' : 'end', + 'replace' : False, + 'pageinfo' : pi } else: + logWarn('Skipping replacement for', pi.name, 'at', specFile, + 'line', pi.begin) print('Skipping replacement for', pi.name, 'at', specFile, 'line', pi.begin) + printPageInfo(pi, file) skipped.add(specFile) if overwrite: @@ -138,18 +146,20 @@ def replaceRef(specFile, outDir, overwrite = False, skipped = set()): if line in actions.keys(): action = actions[line]['action'] replace = actions[line]['replace'] - name = noneStr(actions[line]['name']) - desc = escapeQuote(noneStr(actions[line]['desc'])) - type = actions[line]['type'] + pi = actions[line]['pageinfo'] + + logDiag('ACTION:', action, 'REPLACE:', replace, 'at line', line) + logDiag('PageInfo of action:') + printPageInfo(pi, file) if action == 'begin': - openBlock(name, desc, type, fp) + openBlock(pi, fp) if not replace: print(text, file=fp, end='') elif action == 'end': if not replace: print(text, file=fp, end='') - print('--', file=fp) + closeBlock(pi, fp) else: print('ERROR: unrecognized action:', action, 'in', specFile, 'at line', line) @@ -178,7 +188,7 @@ if __name__ == '__main__': parser.add_argument('-log', action='store', dest='logFile', help='Set the log file for both diagnostics and warnings') parser.add_argument('-outdir', action='store', dest='outDir', - default='man', + default='out', help='Set the base directory in which pages are generated') parser.add_argument('-overwrite', action='store_true', help='Overwrite input filenames instead of writing different output filenames') diff --git a/doc/specs/vulkan/genRef.py b/doc/specs/vulkan/genRef.py index d0ecdf57..31d506aa 100755 --- a/doc/specs/vulkan/genRef.py +++ b/doc/specs/vulkan/genRef.py @@ -35,11 +35,11 @@ def isextension(name): # needed by all the standalone ref pages. def printCopyrightSourceComments(fp): - print('// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a', file=fp) - print('// Creative Commons Attribution 4.0 International License; see', file=fp) - print('// http://creativecommons.org/licenses/by/4.0/', file=fp) - print('', file=fp) - + print('// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a', file=fp) + print('// Creative Commons Attribution 4.0 International License; see', file=fp) + print('// http://creativecommons.org/licenses/by/4.0/', file=fp) + print('', file=fp) + def printFooter(fp): print('include::footer.txt[]', file=fp) print('', file=fp) @@ -113,7 +113,7 @@ def remapIncludes(lines, baseDir, specDir): # 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) + logDiag('remapIncludes: remapping', line, '->', newLine) newLines.append(newLine) else: newLines.append(line) @@ -129,16 +129,16 @@ def remapIncludes(lines, baseDir, specDir): # fp - file to write to def refPageHead(pageName, pageDesc, specText, fieldName, fieldText, descText, fp): printCopyrightSourceComments(fp) - + print(':data-uri:', ':icons: font', 'include::../config/attribs.txt[]', - '', + '', sep='\n', file=fp) - + s = pageName + '(3)' print('= ' + s, - '', + '', sep='\n', file=fp) if pageDesc.strip() == '': @@ -189,13 +189,13 @@ def refPageTail(pageName, seeAlso, fp, auto = False): if auto: notes.extend([ 'This page is a generated document.', - 'Fixes and changes should be made to the generator scripts,' + 'Fixes and changes should be made to the generator scripts, ' 'not directly.', ]) else: notes.extend([ - 'This page is extracted from the Vulkan Specification.', - 'Fixes and changes should be made to the Specification,' + 'This page is extracted from the Vulkan Specification. ', + 'Fixes and changes should be made to the Specification, ' 'not directly.', ]) @@ -234,7 +234,7 @@ def emitPage(baseDir, specDir, pi, file): # Specification text lines = remapIncludes(file[pi.begin:pi.include+1], baseDir, specDir) specText = ''.join(lines) - + # Member/parameter list, if there is one field = None fieldText = None @@ -254,13 +254,13 @@ def emitPage(baseDir, specDir, pi, file): descText = ''.join(lines) # Substitute xrefs to point at the main spec - specLinksPattern = re.compile(r'<<([^>,]+)[,]?[ \t\n]*([^>,]*)>>') + specLinksPattern = re.compile(r'<<([^>,]+)[,]?[ \t\n]*([^>,]*)>>') specLinksSubstitute = r"link:{html_spec_relative}#\1[\2]" specText, n = specLinksPattern.subn(specLinksSubstitute, specText) if fieldText != None: fieldText, n = specLinksPattern.subn(specLinksSubstitute, fieldText) descText, n = specLinksPattern.subn(specLinksSubstitute, descText) - + refPageHead(pi.name, pi.desc, specText, @@ -337,7 +337,7 @@ def autoGenFlagsPage(baseDir, flagName): flagBits = name + 'FlagBits' + author desc = 'Bitmask of ' + flagBits else: - logWarn('autoGenFlagsPage:', pageName, 'does not not end in "Flags{author ID}". Cannot infer FlagBits type.') + logWarn('autoGenFlagsPage:', pageName, 'does not end in "Flags{author ID}". Cannot infer FlagBits type.') flagBits = None desc = 'Unknown Vulkan flags type' @@ -407,7 +407,7 @@ def genRef(specFile, baseDir): # Save the path to this file for later use in rewriting relative includes specDir = os.path.dirname(os.path.abspath(specFile)) - pageMap = findRefs(file) + pageMap = findRefs(file, specFile) logDiag(specFile + ': found', len(pageMap.keys()), 'potential pages') sys.stderr.flush() @@ -523,6 +523,8 @@ if __name__ == '__main__': parser.add_argument('-basedir', action='store', dest='baseDir', default='man', help='Set the base directory in which pages are generated') + parser.add_argument('-noauto', action='store_true', + help='Don\'t generate inferred ref pages automatically') parser.add_argument('files', metavar='filename', nargs='*', help='a filename to extract ref pages from') parser.add_argument('--version', action='version', version='%(prog)s 1.0') @@ -542,31 +544,33 @@ if __name__ == '__main__': # This relies on the dictionaries of API constructs in vkapi.py. # For Flags (e.g. Vk*Flags types), it's easy to autogenerate pages. - for page in flags.keys(): - if not (page in genDict.keys()): - logWarn('Autogenerating flags page:', page, 'which should be included in the spec') - autoGenFlagsPage(baseDir, page) - - # autoGenHandlePage is no longer needed because they are added to - # the spec sources now. - # for page in structs.keys(): - # if typeCategory[page] == 'handle': - # autoGenHandlePage(baseDir, page) - - sections = [ - [ enums, 'Enumerated Types' ], - [ structs, 'Structures' ], - [ protos, 'Prototypes' ], - [ funcpointers, 'Function Pointers' ], - [ basetypes, 'Vulkan Scalar Types' ] ] - - for (apiDict,title) in sections: - flagged = False - for page in apiDict.keys(): + if not results.noauto: + for page in flags.keys(): if not (page in genDict.keys()): - if not flagged: - logWarn(title, 'with no ref page generated:') - flagged = True - logWarn(' ', page) + logWarn('Autogenerating flags page:', page, + 'which should be included in the spec') + autoGenFlagsPage(baseDir, page) - genSinglePageRef(baseDir) + # autoGenHandlePage is no longer needed because they are added to + # the spec sources now. + # for page in structs.keys(): + # if typeCategory[page] == 'handle': + # autoGenHandlePage(baseDir, page) + + sections = [ + [ enums, 'Enumerated Types' ], + [ structs, 'Structures' ], + [ protos, 'Prototypes' ], + [ funcpointers, 'Function Pointers' ], + [ basetypes, 'Vulkan Scalar Types' ] ] + + for (apiDict,title) in sections: + flagged = False + for page in apiDict.keys(): + if not (page in genDict.keys()): + if not flagged: + logWarn(title, 'with no ref page generated:') + flagged = True + logWarn(' ', page) + + genSinglePageRef(baseDir) diff --git a/doc/specs/vulkan/reflib.py b/doc/specs/vulkan/reflib.py index 43d4ee95..7ef1513b 100644 --- a/doc/specs/vulkan/reflib.py +++ b/doc/specs/vulkan/reflib.py @@ -23,6 +23,13 @@ import io,os,re,sys errFile = sys.stderr warnFile = sys.stdout diagFile = None +logSourcefile = None +logProcname = None +logLine = None + +# Remove \' escape sequences in a string (refpage description) +def unescapeQuotes(str): + return str.replace('\\\'', '\'') def write(*args, **kwargs ): file = kwargs.pop('file',sys.stdout) @@ -30,6 +37,32 @@ def write(*args, **kwargs ): file.write(' '.join([str(arg) for arg in args])) file.write(end) +# Metadata which may be printed (if not None) for diagnostic messages +def setLogSourcefile(filename): + global logSourcefile + logSourcefile = filename + +def setLogProcname(procname): + global logProcname + logProcname = procname + +def setLogLine(line): + global logLine + logLine = line + +# Generate prefix for a diagnostic line using metadata and severity +def logHeader(severity): + global logSourcefile, logProcname, logLine + + msg = severity + ': ' + if logProcname: + msg = msg + ' in ' + logProcname + if logSourcefile: + msg = msg + ' for ' + logSourcefile + if logLine: + msg = msg + ' line ' + str(logLine) + return msg + ' ' + # Set the file handle to log either or both warnings and diagnostics to. # setDiag and setWarn are True if the corresponding handle is to be set. # filename is None for no logging, '-' for stdout, or a pathname. @@ -52,14 +85,14 @@ def logDiag(*args, **kwargs): file = kwargs.pop('file', diagFile) end = kwargs.pop('end','\n') if file != None: - file.write('DIAG: ' + ' '.join([str(arg) for arg in args])) + file.write(logHeader('DIAG') + ' '.join([str(arg) for arg in args])) file.write(end) def logWarn(*args, **kwargs): file = kwargs.pop('file', warnFile) end = kwargs.pop('end','\n') if file != None: - file.write('WARN: ' + ' '.join([str(arg) for arg in args])) + file.write(logHeader('WARN') + ' '.join([str(arg) for arg in args])) file.write(end) def logErr(*args, **kwargs): @@ -67,7 +100,7 @@ def logErr(*args, **kwargs): end = kwargs.pop('end','\n') strfile = io.StringIO() - strfile.write( 'ERROR: ' + ' '.join([str(arg) for arg in args])) + strfile.write(logHeader('ERROR') + ' '.join([str(arg) for arg in args])) strfile.write(end) if file != None: @@ -128,7 +161,7 @@ def printPageInfoField(desc, line, file): def printPageInfo(pi, file): logDiag('TYPE: ', pi.type) logDiag('NAME: ', pi.name) - logDiag('WARN: ', pi.Warning) + logDiag('WARNING:', pi.Warning) logDiag('EXTRACT:', pi.extractPage) logDiag('EMBED: ', pi.embed) logDiag('DESC: ', pi.desc) @@ -199,6 +232,19 @@ def loadFile(filename): return file +# Clamp a line number to be in the range [minline,maxline]. +# If the line number is None, just return it. +# If minline is None, don't clamp to that value. +def clampToBlock(line, minline, maxline): + if line == None: + return line + elif minline and line < minline: + return minline + elif line > maxline: + return maxline + else: + return line + # Fill in missing fields in pageInfo structures, to the extent they can be # inferred. # pageMap - dictionary of pageInfo structures @@ -224,19 +270,16 @@ def fixupRefs(pageMap, specFile, file): # pi.Warning = 'No begin, validity, or end lines identified' # continue - # If there's no refBegin line, try to determine where the page - # starts by going back a paragraph from the include statement. - if pi.begin == None: - if pi.include != None: - # structs and protos are the only pages with sufficiently - # regular structure to guess at the boundaries - if pi.type == 'structs' or pi.type == 'protos': - pi.begin = prevPara(file, pi.include) - else: - pi.begin = pi.include + # Using open block delimiters, ref pages must *always* have a + # defined begin and end. If either is undefined, that's fatal. if pi.begin == None: pi.extractPage = False - pi.Warning = 'Can\'t identify beginning of page' + pi.Warning = 'Can\'t identify begin of ref page open block' + continue + + if pi.end == None: + pi.extractPage = False + pi.Warning = 'Can\'t identify end of ref page open block' continue # If there's no description of the page, infer one from the type @@ -250,16 +293,6 @@ def fixupRefs(pageMap, specFile, file): pi.Warning = 'No short description available, cannot infer from the type' continue - # If there's no refEnd line, try to determine where the page ends - # by the location of the validity include - if pi.end == None: - if pi.validity != None: - pi.end = pi.validity - else: - pi.extractPage = False - pi.Warning = 'Can\'t identify end of page (no validity include)' - continue - # Try to determine where the parameter and body sections of the page # begin. funcpointer, proto, and struct pages infer the location of # the parameter and body sections. Other pages infer the location of @@ -275,6 +308,11 @@ def fixupRefs(pageMap, specFile, file): else: pi.Warning = 'Page does not have an API definition include::' + # It's possible for the inferred param and body lines to run past + # the end of block, if, for example, there is no parameter section. + pi.param = clampToBlock(pi.param, pi.include, pi.end) + pi.body = clampToBlock(pi.body, pi.param, pi.end) + # We can get to this point with .include, .param, and .validity # all being None, indicating those sections weren't found. @@ -324,91 +362,181 @@ def fixupRefs(pageMap, specFile, file): # These patterns are only compiled once. includePat = re.compile('^include::(\.\./)+api/+(?P\w+)/(?P\w+).txt\[\]') validPat = re.compile('^include::(\.\./)+validity/(?P\w+)/(?P\w+).txt\[\]') -beginPat = re.compile('^// *refBegin (?P\w+) *(?P.*)') -bodyPat = re.compile('^// *refBody (?P\w+) *(?P.*)') -endPat = re.compile('^// *refEnd (?P\w+) *(?P.*)') +beginPat = re.compile('^\[open,(?Prefpage=.*)\]') +# attribute key/value pairs of an open block +attribStr = "([a-z]+)='([^'\\\\]*(?:\\\\.[^'\\\\]*)*)'" +attribPat = re.compile(attribStr) +bodyPat = re.compile('^// *refBody') # Identify reference pages in a list of strings, returning a dictionary of # pageInfo entries for each one found, or None on failure. -def findRefs(file): +def findRefs(file, filename): + setLogSourcefile(filename) + setLogProcname('findRefs') + + # To reliably detect the open blocks around reference pages, we must + # first detect the '[open,refpage=...]' markup delimiting the block; + # skip past the '--' block delimiter on the next line; and identify the + # '--' block delimiter closing the page. + # This can't be done solely with pattern matching, and requires state to + # track 'inside/outside block'. + # When looking for open blocks, possible states are: + # 'outside' - outside a block + # 'start' - have found the '[open...]' line + # 'inside' - have found the following '--' line + openBlockState = 'outside' + # This is a dictionary of interesting line numbers and strings related # to a Vulkan API name pageMap = {} numLines = len(file) - line = numLines - 1 + line = 0 + + # Track the pageInfo object corresponding to the current open block + pi = None + + while (line < numLines): + setLogLine(line) - while (line >= 0): # Only one of the patterns can possibly match. Add it to # the dictionary for that name. + + # [open,refpage=...] starting a refpage block + matches = beginPat.search(file[line]) + if matches != None: + logDiag('Matched open block pattern') + attribs = matches.group('attribs') + + openBlockState = 'start' + + # Parse the block attributes + matches = attribPat.findall(attribs) + + # Extract each attribute + name = None + desc = None + type = None + xrefs = None + + for (key,value) in matches: + logDiag('got attribute', key, '=', value) + if key == 'refpage': + name = value + elif key == 'desc': + desc = unescapeQuotes(value) + elif key == 'type': + type = value + elif key == 'xrefs': + xrefs = value + else: + logWarn('unknown open block attribute:', key) + + if name == None or desc == None or type == None: + logWarn('missing one or more required open block attributes:' + 'refpage, desc, or type') + # Leave pi == None so open block delimiters are ignored + else: + pi = lookupPage(pageMap, name) + pi.desc = desc + # Must match later type definitions in interface/validity includes + pi.type = type + if xrefs: + pi.refs = xrefs + logDiag('open block for', name, 'added DESC =', desc, + 'TYPE =', type, 'XREFS =', xrefs) + + line = line + 1 + continue + + # '--' starting or ending and open block + if file[line].rstrip() == '--': + if openBlockState == 'outside': + # Only refpage open blocks should use -- delimiters + logWarn('Unexpected double-dash block delimiters') + elif openBlockState == 'start': + # -- delimiter following [open,refpage=...] + openBlockState = 'inside' + + if pi == None: + logWarn('no pageInfo available for opening -- delimiter') + else: + pi.begin = line + 1 + logDiag('opening -- delimiter: added BEGIN =', pi.begin) + elif openBlockState == 'inside': + # -- delimiter ending an open block + if pi == None: + logWarn('no pageInfo available for closing -- delimiter') + else: + pi.end = line - 1 + logDiag('closing -- delimiter: added END =', pi.end) + + openBlockState = 'outside' + pi = None + else: + logWarn('unknown openBlockState:', openBlockState) + + line = line + 1 + continue + matches = validPat.search(file[line]) if matches != None: - logDiag('findRefs: Matched validPat on line', line, '->', file[line], end='') + logDiag('Matched validity pattern') type = matches.group('type') name = matches.group('name') - pi = lookupPage(pageMap, name) - if pi.type and type != pi.type: - logErr('ERROR: pageMap[' + name + '] type:', - pi.type, 'does not match type:', type, - 'at line:', line) - pi.type = type - pi.validity = line - logDiag('findRefs:', name, '@', line, 'added TYPE =', pi.type, 'VALIDITY =', pi.validity) - line = line - 1 + + if pi != None: + if pi.type and type != pi.type: + logWarn('ERROR: pageMap[' + name + '] type:', + pi.type, 'does not match type:', type) + pi.type = type + pi.validity = line + logDiag('added TYPE =', pi.type, 'VALIDITY =', pi.validity) + else: + logWarn('validity include:: line NOT inside block') + + line = line + 1 continue matches = includePat.search(file[line]) if matches != None: - logDiag('findRefs: Matched includePat on line', line, '->', file[line], end='') + logDiag('Matched include pattern') type = matches.group('type') name = matches.group('name') - pi = lookupPage(pageMap, name) - if pi.type and type != pi.type: - logErr('ERROR: pageMap[' + name + '] type:', - pi.type, 'does not match type:', type, - 'at line:', line) - pi.type = type - pi.include = line - logDiag('findRefs:', name, '@', line, 'added TYPE =', pi.type, 'INCLUDE =', pi.include) - line = line - 1 - continue + if pi != None: + if pi.type and type != pi.type: + logWarn('ERROR: pageMap[' + name + '] type:', + pi.type, 'does not match type:', type) + pi.type = type + pi.include = line + logDiag('added TYPE =', pi.type, 'INCLUDE =', pi.include) + else: + logWarn('interface include:: line NOT inside block') - matches = beginPat.search(file[line]) - if matches != None: - logDiag('findRefs: Matched beginPat on line', line, '->', file[line], end='') - name = matches.group('name') - pi = lookupPage(pageMap, name) - pi.begin = line - pi.desc = matches.group('desc').strip() - if pi.desc[0:2] == '- ': - pi.desc = pi.desc[2:] - logDiag('findRefs:', name, '@', line, 'added BEGIN =', pi.begin, 'DESC =', pi.desc) - line = line - 1 + line = line + 1 continue matches = bodyPat.search(file[line]) if matches != None: - logDiag('findRefs: Matched bodyPat on line', line, '->', file[line], end='') - name = matches.group('name') - pi = lookupPage(pageMap, name) - pi.body = line - logDiag('findRefs:', name, '@', line, 'added BODY =', pi.body) - line = line - 1 + logDiag('Matched // refBody pattern') + if pi != None: + pi.body = line + logDiag('added BODY =', pi.body) + else: + logWarn('// refBody line NOT inside block') + + line = line + 1 continue - matches = endPat.search(file[line]) - if matches != None: - logDiag('findRefs: Matched endPat on line', line, '->', file[line], end='') - name = matches.group('name') - pi = lookupPage(pageMap, name) - pi.refs = matches.group('refs') - pi.end = line - logDiag('findRefs:', name, '@', line, 'added END =', pi.end, 'Crossrefs =', pi.refs) - line = line - 1 - continue - - line = line - 1 + line = line + 1 continue + if pi != None: + logErr('Unclosed open block at EOF!') + + setLogSourcefile(None) + setLogProcname(None) + setLogLine(None) + return pageMap diff --git a/doc/specs/vulkan/reflow.py b/doc/specs/vulkan/reflow.py index 8b0d16d0..4fe3edc8 100755 --- a/doc/specs/vulkan/reflow.py +++ b/doc/specs/vulkan/reflow.py @@ -580,7 +580,7 @@ global vuPat vuPat = re.compile('^(?P [*]+)( *)(?P.*)', re.DOTALL) # The value to start tagging VU statements at, unless overridden by -nextvu -startVUID = 1394 +startVUID = 1431 if __name__ == '__main__': parser = argparse.ArgumentParser() diff --git a/doc/specs/vulkan/style/extensions.txt b/doc/specs/vulkan/style/extensions.txt index 33f54fb7..e71cea89 100644 --- a/doc/specs/vulkan/style/extensions.txt +++ b/doc/specs/vulkan/style/extensions.txt @@ -437,7 +437,6 @@ for extensions, which include (but may not be limited to) the following: For example, for `VK_EXT_debug_marker`, `appendices.txt` is modified to add: + --- [source,asciidoc] .Example Markup ---- @@ -445,7 +444,6 @@ for extensions, which include (but may not be limited to) the following: \include::appendices/VK_EXT_debug_marker.txt[] \endif::VK_EXT_debug_marker[] ---- --- * Extensions usually make significant additions and changes to the Vulkan specification. They often add an entirely new chapter, or a new section of an existing @@ -454,7 +452,6 @@ for extensions, which include (but may not be limited to) the following: of the "`Debugging`" chapter in `chapters/debugging.txt`, by including in that file: + --- [source,asciidoc] .Example Markup ---- @@ -462,7 +459,6 @@ for extensions, which include (but may not be limited to) the following: \include::chapters/VK_EXT_debug_marker/wsi.txt[] \endif::VK_EXT_debug_marker[] ---- --- * In every other place where the extension alters the behavior of the core Specification, make such changes and protect the modifications with the same asciidoc conditionals. @@ -470,7 +466,6 @@ for extensions, which include (but may not be limited to) the following: These are added to `chapters/fundamentals.txt` in the "`Return Codes`" section as follows: + --- [source,asciidoc] .Example Markup ---- @@ -479,7 +474,6 @@ for extensions, which include (but may not be limited to) the following: \include::VK_KHR_surface/VkResultErrorDescriptions_surface.txt[] \endif::VK_KHR_surface[] ---- --- * If two extensions interact, the asciidoc conditionals must be carefully structured so as to properly document the interactions if the specification is built with both extensions. @@ -488,7 +482,6 @@ for extensions, which include (but may not be limited to) the following: and http://asciidoctor.org/docs/user-manual/#checking-multiple-attributes-ifdef-and-ifndef-only). + --- [source,asciidoc] .Example Markup ---- @@ -503,7 +496,6 @@ for extensions, which include (but may not be limited to) the following: ... discussion of VK_KHR_fum ... \endif::VK_KHR_fum[] ---- --- * In cases where a new extension (A) modifies both core and an existing extension (B), if the new extension (A) becomes part of the core at a future release (i.e. is no longer an extension), the portion of the new @@ -540,7 +532,6 @@ for extensions, which include (but may not be limited to) the following: the trouble. For example, instead of + --- [source,asciidoc] .Example Markup ---- @@ -554,11 +545,9 @@ for extensions, which include (but may not be limited to) the following: is ename:VK_QUEUE_FAMILY_IGNORED. \endif::VK_KHX_external_memory[] ---- --- + - Use +Use + --- [source,asciidoc] .Example Markup ---- @@ -579,7 +568,6 @@ ifdef::VK_KHX_external_memory[] either order endif::VK_KHX_external_memory[] ---- --- == Assigning Extension Token Values @@ -721,7 +709,7 @@ the following definitions were in effect: ---- -== Extension Objects, Enums, and Typedefs +== Extension Handles, Objects, Enums, and Typedefs Expanding on previous discussion, extensions can add values to existing enums; and can add their own commands, enums, typedefs, etc. @@ -729,6 +717,24 @@ This is done by adding to <>. All such additions will be included in the `vulkan.h` header supplied by Khronos. +If the extension adds a new handle to Vulkan, a corresponding value must be +added to ename:VkObjectType (as defined in the "`Debugging`" section of the +<>) in order to allow components to +identify and track objects of the new type. + +The new enumeration value must conform to the naming defined in the +<> section. +In this case, the type's etext:Vk prefix is replaced with the enum prefix +etext:VK_OBJECT_TYPE_, and the rest of the handle name is converted as +described in that section. + +[source,asciidoc] +.Conversion of Handle to VkObjectType Examples: +---- + VkSurfaceKHR -> VK_OBJECT_TYPE_SURFACE_KHR + VkDescriptorUpdateTemplateKHR -> VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR +---- + [NOTE] .Note ==== @@ -739,7 +745,6 @@ The use of a `default:` statement, within a `switch`, may avoid future compilation issues. ==== - [[extension-function_prototypes]] == Extension Function Prototypes diff --git a/doc/specs/vulkan/style/markup.txt b/doc/specs/vulkan/style/markup.txt index 1f3b75a5..f75fe0e3 100644 --- a/doc/specs/vulkan/style/markup.txt +++ b/doc/specs/vulkan/style/markup.txt @@ -135,8 +135,8 @@ long as the colliding numbers are not in the same section. Like this example footnote. [NOTE] +==== .Example Markup --- [source,asciidoc] ---- See reference^2^ @@ -151,8 +151,7 @@ See reference^2^ 2:: Reference 2. --- - +==== [[markup-sample-section-lists]] === Lists @@ -165,14 +164,12 @@ See reference^2^ * Lists should have text indented by 4 spaces and the list item delimiter (e.g. one or more asterisks, for bullet lists) indented by two spaces. + --- Note that continuation blocks for list items longer than one paragraph cannot be indented, only the first paragraph. - ++ In general, successive list items should not be separated by white space. However, list continuation blocks should be followed by a `+` on a line by itself, or by a blank line, due to limitations of the asciidoc parser. --- + * Indent bullet lists two spaces (to the bullet), 4 spaces (to the text, if it extends over multiple lines). @@ -187,15 +184,53 @@ itself, or by a blank line, due to limitations of the asciidoc parser. * The second item is described with two paragraphs. The second paragraph is in a continuation block: + --- This is a continuation block containing the second paragraph, --- + ** This is a nested list item for the second item. Since it follows a continuation block, it must be separated by a blank line or `+` from that block. ---- +[example] +==== + * This is the first item in a bullet list. + * The second item is described with two paragraphs. + The second paragraph is in a continuation block: ++ +This is a continuation block containing the second paragraph, ++ + ** This is a nested list item for the second item. + Since it follows a continuation block, it must be separated by a blank + line or `+` from that block. +==== + + * It's possible to continue a paragraph of the first bullet after a list + of sub-bullets if so desired by using continuations in a similar + fashion: + +[source,asciidoc] +.Example Markup +---- + * This an item in a bullet list. ++ + ** This is a nested list item for the second item. + Since it follows a continuation block, it must be separated by a blank + line or `+` from that block. ++ +This is a continuation of the first bullet +---- + +[example] +==== + * This an item in a bullet list. ++ + ** This is a nested list item for the second item. + Since it follows a continuation block, it must be separated by a blank + line or `+` from that block. ++ +This is a continuation of the first bullet +==== + [[markup-labelled-lists]] ==== Labelled Lists @@ -368,37 +403,35 @@ table: | fname{cl} | Formats the macro argument like flink{cl}. Does not generate a cross-reference. Example: fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool. - The flink{cl} macro is preferred. + + Only use this macro <>. | ftext{cl} | Formats the macro argument like fname{cl}. May contain asterisks for wildcards. Not validated. Example: ftext{cl}vkCmd* -> ftext:vkCmd*. - Only use ftext{cl} when it is necessary to describe - something that should be rendered like a command name, - but is not actually one (e.g. is a wildcard or subset of - an actual command name). + Only use this macro <>. | slink{cl} | Generates a cross-reference or link to the definition - of the structure in the macro argument. Example: - slink{cl}VkMemoryHeap -> - slink:VkMemoryHeap. + of the structure or handle in the macro argument. Example: + slink{cl}VkMemoryHeap -> slink:VkMemoryHeap. | sname{cl} | Formats the macro argument like slink{cl}. Does not generate a cross-reference. May also be an abstract structure or handle name. Example: sname{cl}VkCommandPoolCreateInfo -> - sname:VkCommandPoolCreateInfo. The slink{cl} macro is - preferred if a definition of the target type with an - anchor exists in the document. + sname:VkCommandPoolCreateInfo. + + Only use this macro <>. | stext{cl} | Formats the macro argument like sname{cl}. May contain asterisks for wildcards. Not validated. Example: stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo. - Only use stext{cl} when it is necessary to describe - something that should be rendered like a structure name, - but is not actually one (e.g. is a wildcard or subset of - an actual structure name). -| elink{cl} | Formats the macro argument as a Vulkan enumeration - name and links to the definition of that enumeration type. - Example: ename{cl}VkResult -> ename:VkResult. + Only use this macro <>. +| elink{cl} | Formats the macro argument as a Vulkan enumerated + type name and links to the definition of that enumeration + type. Example: ename{cl}VkResult -> ename:VkResult. | ename{cl} | Formats the macro argument as a Vulkan enumerant name. Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET. | etext{cl} | Formats the macro argument like ename{cl}. Not validated. @@ -406,10 +439,8 @@ table: etext{cl}VK_IMAGE_CREATE_SPARSE_* -> etext:VK_IMAGE_CREATE_SPARSE_* - Only use etext{cl} when it is necessary to describe - something that should be rendered like a enumerant name, - but is not actually one (e.g. is a wildcard or subset of - an actual enumerant name). + Only use this macro <>. | pname{cl} | Formats the macro argument as a Vulkan parameter or structure member name. Example: pname{cl}device -> pname:device. @@ -417,10 +448,8 @@ table: asterisks for wildcards. Not validated. Example: ptext{cl}sparseResidency* -> ptext:sparseResidency*. - Only use ptext{cl} when it is necessary to describe - something that should be rendered like a parameter name, - but is not actually one (e.g. is a wildcard or subset of - an actual parameter name). + Only use this macro <>. | tlink{cl} | Generates a cross-reference or link to the definition of the Vulkan type in the macro argument. Example: tlink{cl}PFN_vkAllocationFunction -> @@ -429,8 +458,10 @@ table: | tname{cl} | Formats the macro argument like tlink{cl}. Does not generate a cross-reference. Example: tname{cl}PFN_vkAllocationFunction -> - tname:PFN_vkAllocationFunction. The tlink{cl} macro is - preferred. + tname:PFN_vkAllocationFunction. + + Only use this macro <>. | dlink{cl} | Generates a cross-reference or link to the definition of the Vulkan C macro in the macro argument. Example: dlink{cl}VK_NULL_HANDLE -> dlink:VK_NULL_HANDLE. There are @@ -438,8 +469,10 @@ table: "`API Boilerplate`" appendix of the <> | dname{cl} | Formats the macro argument like dlink{cl}. Does not - generate a cross-reference. The dlink{cl} macro - is preferred. + generate a cross-reference. + + Only use this macro <>. | basetype{cl} | Formats the macro argument like a basic scalar type or API handle name. Not validated. Examples: basetype{cl}VkBool32 -> basetype:VkBool32, @@ -466,6 +499,37 @@ slink:VkMemoryHeap::pname:flags ---- +[[markup-macros-api-name]] +==== When To Use *name: Macros + +Only use the fname{cl}, sname{cl}, tname{cl}, and dname{cl} macros if no +definition of the target type with a corresponding anchor exists in the +document. +Anchors are automatically defined when including the generated API interface +definitions under `doc/specs/vulkan/api/.../*txt`. +If an anchor does exist, use the corresponding *link{cl} macro. + +[NOTE] +.Note +==== +There are many legacy uses of the *name{cl} macros that will be replaced +over time. +These uses date from before anchors were added to the generated API +definitions. +==== + + +[[markup-macros-api-text]] +==== When To Use *text: Macros + +Only use the ftext{cl}, stext{cl}, etext{cl}, and ptext{cl} macros when +describing something something that should be rendered like a command, +structure, enumerant, or parameter name, respectively, but is not actually +one. +Typically these macros are used for wildcards describing multiple API names +with common prefixes or suffixes, or common subsets of API names. + + ==== Other Markup Uses of standard Asciidoc markup are less common. diff --git a/doc/specs/vulkan/style/writing.txt b/doc/specs/vulkan/style/writing.txt index d9b74602..4ecccd2b 100644 --- a/doc/specs/vulkan/style/writing.txt +++ b/doc/specs/vulkan/style/writing.txt @@ -450,8 +450,11 @@ example description to explain how and why it looks as it does. [[sample-command]] == Sample Command Description: Creating Command Pools -// refBegin vkCreateCommandPool Create a new command pool object +// Three dashes are used here to allow the inner [source] block to show the +// correct two dashes. +[open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] +-- To create a command pool, call: include::../api/protos/vkCreateCommandPool.txt[] @@ -459,8 +462,10 @@ include::../api/protos/vkCreateCommandPool.txt[] [NOTE] .Guideline ==== -Begin the command description with a comment delimiting the language for -<>. +Begin the command description with an open block delimiting the contents as +a reference page. +The open block contains several required attribute values, as described 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 @@ -469,10 +474,14 @@ more passive phrasing like "`A command pool is created by calling:`" or After the description, include the autogenerated prototype for the command from the `../protos/` directory: -[source,asciidoc] ----- -// refBegin vkCreateCommandPool Create a new command pool object +// The 'subs=attributes+' and '{blank}--' are one way to allow the inner +// [source] block to show the correct two dashes. See +// http://discuss.asciidoctor.org/Another-markup-escaping-question-td5665.html +[source,asciidoc,subs=attributes+] +---- +[open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] +{blank}-- To create a command pool, call: \include::../api/protos/vkCreateCommandPool.txt[] @@ -518,6 +527,7 @@ the proper type is used to return the newly created object. ==== include::../validity/protos/vkCreateCommandPool.txt[] +-- [NOTE] .Guideline @@ -525,23 +535,32 @@ include::../validity/protos/vkCreateCommandPool.txt[] Some parameter and member validation language for commands and structures is _implicit_ (autogenerated from `vk.xml`), and included from the `../validity/` directories. -There may be additional validation language which is explicit, and such -language is written in a separate block in the specification preceding the -validity include. -The fname:vkCreateCommandPool used as an example here has no such explicit -language, but the sname:VkCommandPoolCreateInfo used below does have -explicit language. +All Vulkan command and structure language should include the autogenerated +file at the end of their descriptions. +It is harmless to include a nonexistent file, in the rare cases where no +implicit validity language exists. -[source,asciidoc] +[source,asciidoc,subs=attributes+] ---- \include::../validity/protos/vkCreateCommandPool.txt[] +{blank}-- ---- +End the open block surrounding the command description after the implicit +validity include. +All content within the block will be extracted for the corresponding +reference page. + Structures and enumerations first used as parameters of a command are described next. + ==== -// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool +// Three dashes are used here to allow the inner [source] block to show the +// correct two dashes. + +[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] +-- The sname:VkCommandPoolCreateInfo structure is defined as: @@ -550,9 +569,10 @@ include::../api/structs/VkCommandPoolCreateInfo.txt[] [NOTE] .Guideline ==== -Begin the structure description with a `refBegin` comment delimiting the -language for <> -and including a summary line for the reference page. +Begin the structure description with an open block delimiting the contents +as a reference page, in the same fashion as described above for commands. +The open block contains several required attribute values, as described for +<>. Use a short, active paragraph to introduce the structure, usually just "`The sname:VkStructureName structure is defined as:`". @@ -560,10 +580,10 @@ sname:VkStructureName structure is defined as:`". After the description, include the autogenerated definition for the structure from the `../structs/` directory: -[source,asciidoc] +[source,asciidoc,subs=attributes+] ---- -// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of -a newly created command pool +[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] +{blank}-- The sname:VkCommandPoolCreateInfo structure is defined as: @@ -573,22 +593,12 @@ The sname:VkCommandPoolCreateInfo structure is defined as: * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:flags is a combination of bitmask flags indicating usage behavior - for the pool and command buffers allocated from it. - Possible values 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. - * pname:queueFamilyIndex designates a queue family. - Command buffers in this command pool must: be submitted on queues from - the same family. + * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating + usage behavior for the pool and command buffers allocated from it. + * pname:queueFamilyIndex designates a queue family as described in section + <>. + All command buffers allocated from this command pool must: be submitted + on queues from the same queue family. [NOTE] .Guideline @@ -602,24 +612,45 @@ members 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:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating + usage behavior for the pool and command buffers allocated from it. + * pname:queueFamilyIndex designates a queue family as described in section + <>. + All command buffers allocated from this command pool must: be submitted + on queues from the same queue family. ---- -In some cases, such as when the type of a member is itself a new type, the -entry will cover multiple paragraphs. +These entries should be short and functional, without describing details of +e.g. new enumerant values, function of individual parameter settings, etc. +They can refer to other types using the appropriate *link: macros or to +related sections of the specification using asciidoc xrefs. + +In rare cases, an entry will cover multiple paragraphs. In these cases the normal list nesting and indentation guidelines cannot be applied due to limitations of the asciidoc parser. It is usually best to append a continuation block following the first paragraph of such a list item: -[source,asciidoc] +// @@@ Use VkCommandBufferInheritanceInfo:framebuffer for a current example instead +ifdef::editing-notes[] +[NOTE] +.editing-note +==== +This example is obsolete and incorrect. +Use VkCommandBufferInheritanceInfo:framebuffer for a current example +instead. +==== +endif::editing-notes[] + +[source,asciidoc,subs=attributes+] ---- * pname:flags is a bitmask indicating usage behavior for the pool and command buffers allocated from it. Bits which can: be set include: + --- +{blank}-- // refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool \include::../api/enums/VkCommandPoolCreateFlagBits.txt[] --- +{blank}-- + ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers allocated @@ -632,11 +663,24 @@ paragraph of such a list item: .Valid Usage **** - * pname:queueFamilyIndex must: be the index of a queue family available in + * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] + pname:queueFamilyIndex must: be the index of a queue family available in the calling command's pname:device parameter **** +[NOTE] +.Guideline +==== +In addition to implicit validity language, there may be additional +validation language which is explicit. +Such language is written in a separate block in the specification, +_preceding_ the validity include. +The fname:vkCreateCommandPool example above has no such explicit language, +but this example does have explicit language. +==== + include::../validity/structs/VkCommandPoolCreateInfo.txt[] +-- [NOTE] .Guideline @@ -649,7 +693,8 @@ validity language include for this structure: ---- .Valid Usage **** - * pname:queueFamilyIndex must: be the index of a queue family available in + * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] + pname:queueFamilyIndex must: be the index of a queue family available in the calling command's pname:device parameter **** @@ -663,12 +708,12 @@ greater than zero`", write each condition as a separate statement. In contrast, "`width {times} height must: be less than 1024`" is a single assertion involving multiple parameters. -Do not use "unless" to call out exceptions - always write valid usage -statements of the form "if _A_ then _B_". -This may result in harder to read statements in a few cases, but keeps -things consistent. +Do not use "`unless`" to call out exceptions - always write valid usage +statements of the form "`if _A_ then _B_`". +This may result in harder to read statements in a few cases, but maintains +consistency. In many cases, it may lead to a simpler VU statement, or splitting one large -VU into multiple. +VU into multiple new ones. Do not use nested lists or other writing structure where Valid Usage statements are not self-contained. @@ -682,82 +727,112 @@ appendix, but is normally performed only when preparing to integrate functionality into the Vulkan Specification prior to publication. It is something authors of new functionality should be aware of, but are not themselves responsible for. +For example, when writing the explicit pname:queueFamilyIndex statement +shown above, the tag + +[source,asciidoc] +---- +[[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] +---- + +was inserted by a script, not the original author. ==== [[writing-refpages]] == Markup For Automatic Reference Page Extraction -The Vulkan reference pages are (mostly) being extracted from corresponding +The Vulkan reference pages are (mostly) 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: +The extraction scripts for a given page rely on the existence of an asciidoc +`open` block surrounding markup describing that page, with attributes used +to specify properties of the reference page. +Additional heuristics and non-asciidoc tags, described below, are used to +identify subsections of a reference page in some cases. + +In general the open block introduction will look like: - * Optional (but usually specified) comment line specifying the interface - name and the short description used in the title of the corresponding - ref page: -+ --- [source,asciidoc] ---- -// refBegin name - description ----- +[open,refpage='name',desc='short description',type='pagetype',xrefs='xrefs'] -- -+ - * A paragraph of text introducing the definition of the interface. - If the `refBegin` comment does not exist, this paragraph must be - present. +---- + +Attributes which can be set on the block are: + + * *refpage* - the name of the reference page, e.g. the Vulkan interface + (command, structure, enumerant, handle, etc.) name. This attribute is + required. + * *desc* - short description / summary of the page, used in the page + title. This attribute is required. + * *type* - type of the interface, which must match the directory name + following `api/` in the interface `include::` line within the block, and + must be one of `basetypes`, `defines`, `enums`, `flags`, `funcpointers`, + `handles`, `protos`, or `structs`. This attribute is required. + * *xrefs* - list of whitespace-separated names of other reference pages + which should be added to the `See Also` section of this page. Most + cross-references are automatically generated based on the immediate + dependency information in `vk.xml`, but in some cases, such as referring + between `*FlagBits` and `*Flags` types, this additional tagging is + useful. This attribute is optional. + +Attributes of the open block must be written in this format, using single +quotes as delimiters (even though asciidoc markup also allows double +quotes), and escape single quotes in e.g. the *desc* attribute value with +backquotes. + +After the open block is started, the following markup should be provided: + + * A single paragraph of text describing the definition of the interface. + This paragraph is optional, but strongly recommended. * The `include` line for the interface, which must be consistent with the - interface name in the comment line. + page name and type in the open block attributes. This paragraph is + required. * 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. + This list is required, unless the interface has nothing to describe, + such as an empty structure or enumeration, or a function with no + parameters. + * Paragraphs of text making up the `Description` section of the ref page. + This section is optional. If it is necessary due to constraints of asciidoc markup to have an - empty line in the bullet list section^1^, add a `refBody` comment + empty line in the bullet list section^1^, add a `// refBody` comment immediately following the bullet list and preceding this section: + --- [source,asciidoc] ---- -// refBody name +// refBody ---- --- + - * 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: + * An explicit Valid Usage block. This block is required if the interface + has such Valid Usage constraints. + * The `include` line for the implicit valid usage block. + This line is required for for commands and structures, but not for + interfaces such as enumerated types, which do not have implicit valid + usage blocks. + * Finally, a two-dash asciidoc delimiter closing the open block: + --- [source,asciidoc] ---- -// refEnd name [seeAlsoNames]* ----- -- +---- 1:: The only example of such markup in the 1.0.28 Vulkan Specification source is the stext:VkPhysicalDeviceLimits structure description. -All elements specifying an interface name (`refBegin`, `refBody`, and -`refEnd` comments, interface `include` line, and validity `include` line) -must use the same interface name, if present. +All elements specifying an interface name (open block `refpage` attributes, +interface `include` lines, and validity `include` lines) 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. +will extract the wrong text - and the language will be structurally +incorrect, as well. 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 7d45c341..217d0d57 100644 --- a/doc/specs/vulkan/styleguide.txt +++ b/doc/specs/vulkan/styleguide.txt @@ -157,6 +157,11 @@ include::style/vuid.txt[] = Revision History +* 2017-06-12 - Add sections describing when to use the + <> and <> markup macros instead of the *link{cl} macros, and clarify + that slink{cl} should be used for handle as well as structure names + (internal issue 886). * 2017-05-08 - Add appendix describing <> and how they're generated. * 2017-03-19 - Add naming rule for < Copyright (c) 2015-2017 The Khronos Group Inc. -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and/or associated documentation files (the -"Materials"), to deal in the Materials without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Materials, and to -permit persons to whom the Materials are furnished to do so, subject to -the following conditions: +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Materials. + http://www.apache.org/licenses/LICENSE-2.0 -THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY -CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, -TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. ------------------------------------------------------------------------ @@ -29,8 +22,9 @@ and normative part of the Vulkan Specification, including a canonical machine-readable definition of the API, parameter and member validation language incorporated into the Specification and reference pages, and other material which is registered by Khronos, such as tags used by extension and -layer authors. The only authoritative version of vk.xml is the one -maintained in the master branch of the Khronos Vulkan GitHub project. +layer authors. The authoritative public version of vk.xml is maintained in +the master branch of the Khronos Vulkan GitHub project. The authoritative +private version is maintained in the 1.0 branch of the member gitlab server. @@ -112,7 +106,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 51 +#define VK_HEADER_VERSION 53 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -240,6 +234,8 @@ maintained in the master branch of the Khronos Vulkan GitHub project. typedef VkFlags VkSurfaceCounterFlagsEXT; typedef VkFlags VkPipelineViewportSwizzleStateCreateFlagsNV; typedef VkFlags VkPipelineDiscardRectangleStateCreateFlagsEXT; + typedef VkFlags VkPipelineCoverageToColorStateCreateFlagsNV; + typedef VkFlags VkPipelineCoverageModulationStateCreateFlagsNV; VK_DEFINE_HANDLE(VkInstance) @@ -375,6 +371,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. + @@ -399,6 +396,8 @@ maintained in the master branch of the Khronos Vulkan GitHub project. + + typedef void (VKAPI_PTR *PFN_vkInternalAllocationNotification)( @@ -954,7 +953,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext VkPipelineMultisampleStateCreateFlags flags VkSampleCountFlagBits rasterizationSamples VkBool32 sampleShadingEnable @@ -975,7 +974,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext VkPipelineColorBlendStateCreateFlags flags VkBool32 logicOpEnable VkLogicOp logicOp @@ -1057,7 +1056,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - const void* pNext + const void* pNext VkSamplerCreateFlags flags VkFilter magFilter VkFilter minFilter @@ -1770,12 +1769,12 @@ maintained in the master branch of the Khronos Vulkan GitHub project. VkStructureType sType - void* pNext + void* pNext VkPhysicalDeviceFeatures features VkStructureType sType - void* pNext + void* pNext VkPhysicalDeviceProperties properties @@ -2279,6 +2278,55 @@ maintained in the master branch of the Khronos Vulkan GitHub project. void* pNext VkBool32 supportsTextureGatherLODBiasAMD + + VkStructureType sType + const void* pNext + VkPipelineCoverageToColorStateCreateFlagsNV flags + VkBool32 coverageToColorEnable + uint32_t coverageToColorLocation + + + VkStructureType sType + void* pNext + VkBool32 filterMinmaxSingleComponentFormats + VkBool32 filterMinmaxImageComponentMapping + + + VkStructureType sType + const void* pNext + VkSamplerReductionModeEXT reductionMode + + + VkStructureType sType + void* pNext + VkBool32 advancedBlendCoherentOperations + + + VkStructureType sType + void* pNext + uint32_t advancedBlendMaxColorAttachments + VkBool32 advancedBlendIndependentBlend + VkBool32 advancedBlendNonPremultipliedSrcColor + VkBool32 advancedBlendNonPremultipliedDstColor + VkBool32 advancedBlendCorrelatedOverlap + VkBool32 advancedBlendAllOperations + + + VkStructureType sType + const void* pNext + VkBool32 srcPremultiplied + VkBool32 dstPremultiplied + VkBlendOverlapEXT blendOverlap + + + VkStructureType sType + const void* pNext + VkPipelineCoverageModulationStateCreateFlagsNV flags + VkCoverageModulationModeNV coverageModulationMode + VkBool32 coverageModulationTableEnable + uint32_t coverageModulationTableCount + const float* pCoverageModulationTable + @@ -3240,7 +3288,22 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + + + + + + + + + + + + + + + + @@ -5258,14 +5321,14 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + @@ -5362,7 +5425,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5374,25 +5437,25 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + - + - + @@ -5498,7 +5561,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5516,25 +5579,25 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + - + - + @@ -5561,7 +5624,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5573,7 +5636,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5583,7 +5646,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5594,7 +5657,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5633,7 +5696,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5709,13 +5772,13 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + @@ -5939,7 +6002,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -5998,14 +6061,14 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + @@ -6013,7 +6076,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -6024,7 +6087,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -6063,26 +6126,26 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - - + + - + - + - + @@ -6092,7 +6155,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -6103,7 +6166,7 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + @@ -6117,25 +6180,25 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - + - + - + @@ -6336,10 +6399,16 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - - + + + + + + + + @@ -6348,10 +6417,10 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - - + + @@ -6444,16 +6513,73 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - + + + + + @@ -6468,16 +6594,21 @@ maintained in the master branch of the Khronos Vulkan GitHub project. - + - - + + + + + + - + - - + + + @@ -6510,5 +6641,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 f9571404..3255e7d7 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 51 +#define VK_HEADER_VERSION 53 #define VK_NULL_HANDLE 0 @@ -305,6 +305,13 @@ typedef enum VkStructureType { VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR = 1000119002, VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK = 1000122000, VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK = 1000123000, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_FILTER_MINMAX_PROPERTIES_EXT = 1000130000, + VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT = 1000130001, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_FEATURES_EXT = 1000148000, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BLEND_OPERATION_ADVANCED_PROPERTIES_EXT = 1000148001, + VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT = 1000148002, + VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV = 1000149000, + VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV = 1000152000, VK_STRUCTURE_TYPE_BEGIN_RANGE = VK_STRUCTURE_TYPE_APPLICATION_INFO, VK_STRUCTURE_TYPE_END_RANGE = VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO, VK_STRUCTURE_TYPE_RANGE_SIZE = (VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO - VK_STRUCTURE_TYPE_APPLICATION_INFO + 1), @@ -658,6 +665,7 @@ typedef enum VkPolygonMode { VK_POLYGON_MODE_FILL = 0, VK_POLYGON_MODE_LINE = 1, VK_POLYGON_MODE_POINT = 2, + VK_POLYGON_MODE_FILL_RECTANGLE_NV = 1000153000, VK_POLYGON_MODE_BEGIN_RANGE = VK_POLYGON_MODE_FILL, VK_POLYGON_MODE_END_RANGE = VK_POLYGON_MODE_POINT, VK_POLYGON_MODE_RANGE_SIZE = (VK_POLYGON_MODE_POINT - VK_POLYGON_MODE_FILL + 1), @@ -758,6 +766,52 @@ typedef enum VkBlendOp { VK_BLEND_OP_REVERSE_SUBTRACT = 2, VK_BLEND_OP_MIN = 3, VK_BLEND_OP_MAX = 4, + VK_BLEND_OP_ZERO_EXT = 1000148000, + VK_BLEND_OP_SRC_EXT = 1000148001, + VK_BLEND_OP_DST_EXT = 1000148002, + VK_BLEND_OP_SRC_OVER_EXT = 1000148003, + VK_BLEND_OP_DST_OVER_EXT = 1000148004, + VK_BLEND_OP_SRC_IN_EXT = 1000148005, + VK_BLEND_OP_DST_IN_EXT = 1000148006, + VK_BLEND_OP_SRC_OUT_EXT = 1000148007, + VK_BLEND_OP_DST_OUT_EXT = 1000148008, + VK_BLEND_OP_SRC_ATOP_EXT = 1000148009, + VK_BLEND_OP_DST_ATOP_EXT = 1000148010, + VK_BLEND_OP_XOR_EXT = 1000148011, + VK_BLEND_OP_MULTIPLY_EXT = 1000148012, + VK_BLEND_OP_SCREEN_EXT = 1000148013, + VK_BLEND_OP_OVERLAY_EXT = 1000148014, + VK_BLEND_OP_DARKEN_EXT = 1000148015, + VK_BLEND_OP_LIGHTEN_EXT = 1000148016, + VK_BLEND_OP_COLORDODGE_EXT = 1000148017, + VK_BLEND_OP_COLORBURN_EXT = 1000148018, + VK_BLEND_OP_HARDLIGHT_EXT = 1000148019, + VK_BLEND_OP_SOFTLIGHT_EXT = 1000148020, + VK_BLEND_OP_DIFFERENCE_EXT = 1000148021, + VK_BLEND_OP_EXCLUSION_EXT = 1000148022, + VK_BLEND_OP_INVERT_EXT = 1000148023, + VK_BLEND_OP_INVERT_RGB_EXT = 1000148024, + VK_BLEND_OP_LINEARDODGE_EXT = 1000148025, + VK_BLEND_OP_LINEARBURN_EXT = 1000148026, + VK_BLEND_OP_VIVIDLIGHT_EXT = 1000148027, + VK_BLEND_OP_LINEARLIGHT_EXT = 1000148028, + VK_BLEND_OP_PINLIGHT_EXT = 1000148029, + VK_BLEND_OP_HARDMIX_EXT = 1000148030, + VK_BLEND_OP_HSL_HUE_EXT = 1000148031, + VK_BLEND_OP_HSL_SATURATION_EXT = 1000148032, + VK_BLEND_OP_HSL_COLOR_EXT = 1000148033, + VK_BLEND_OP_HSL_LUMINOSITY_EXT = 1000148034, + VK_BLEND_OP_PLUS_EXT = 1000148035, + VK_BLEND_OP_PLUS_CLAMPED_EXT = 1000148036, + VK_BLEND_OP_PLUS_CLAMPED_ALPHA_EXT = 1000148037, + VK_BLEND_OP_PLUS_DARKER_EXT = 1000148038, + VK_BLEND_OP_MINUS_EXT = 1000148039, + VK_BLEND_OP_MINUS_CLAMPED_EXT = 1000148040, + VK_BLEND_OP_CONTRAST_EXT = 1000148041, + VK_BLEND_OP_INVERT_OVG_EXT = 1000148042, + VK_BLEND_OP_RED_EXT = 1000148043, + VK_BLEND_OP_GREEN_EXT = 1000148044, + VK_BLEND_OP_BLUE_EXT = 1000148045, VK_BLEND_OP_BEGIN_RANGE = VK_BLEND_OP_ADD, VK_BLEND_OP_END_RANGE = VK_BLEND_OP_MAX, VK_BLEND_OP_RANGE_SIZE = (VK_BLEND_OP_MAX - VK_BLEND_OP_ADD + 1), @@ -959,6 +1013,7 @@ typedef enum VkFormatFeatureFlagBits { VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG = 0x00002000, VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR = 0x00004000, VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR = 0x00008000, + VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT_EXT = 0x00010000, VK_FORMAT_FEATURE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF } VkFormatFeatureFlagBits; typedef VkFlags VkFormatFeatureFlags; @@ -1236,6 +1291,7 @@ typedef enum VkAccessFlagBits { VK_ACCESS_MEMORY_WRITE_BIT = 0x00010000, VK_ACCESS_COMMAND_PROCESS_READ_BIT_NVX = 0x00020000, VK_ACCESS_COMMAND_PROCESS_WRITE_BIT_NVX = 0x00040000, + VK_ACCESS_COLOR_ATTACHMENT_READ_NONCOHERENT_BIT_EXT = 0x00080000, VK_ACCESS_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF } VkAccessFlagBits; typedef VkFlags VkAccessFlags; @@ -5925,6 +5981,134 @@ VKAPI_ATTR VkResult VKAPI_CALL vkCreateMacOSSurfaceMVK( #endif #endif /* VK_USE_PLATFORM_MACOS_MVK */ +#define VK_EXT_sampler_filter_minmax 1 +#define VK_EXT_SAMPLER_FILTER_MINMAX_SPEC_VERSION 1 +#define VK_EXT_SAMPLER_FILTER_MINMAX_EXTENSION_NAME "VK_EXT_sampler_filter_minmax" + + +typedef enum VkSamplerReductionModeEXT { + VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT = 0, + VK_SAMPLER_REDUCTION_MODE_MIN_EXT = 1, + VK_SAMPLER_REDUCTION_MODE_MAX_EXT = 2, + VK_SAMPLER_REDUCTION_MODE_BEGIN_RANGE_EXT = VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT, + VK_SAMPLER_REDUCTION_MODE_END_RANGE_EXT = VK_SAMPLER_REDUCTION_MODE_MAX_EXT, + VK_SAMPLER_REDUCTION_MODE_RANGE_SIZE_EXT = (VK_SAMPLER_REDUCTION_MODE_MAX_EXT - VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT + 1), + VK_SAMPLER_REDUCTION_MODE_MAX_ENUM_EXT = 0x7FFFFFFF +} VkSamplerReductionModeEXT; + +typedef struct VkSamplerReductionModeCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkSamplerReductionModeEXT reductionMode; +} VkSamplerReductionModeCreateInfoEXT; + +typedef struct VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT { + VkStructureType sType; + void* pNext; + VkBool32 filterMinmaxSingleComponentFormats; + VkBool32 filterMinmaxImageComponentMapping; +} VkPhysicalDeviceSamplerFilterMinmaxPropertiesEXT; + + + +#define VK_AMD_gpu_shader_int16 1 +#define VK_AMD_GPU_SHADER_INT16_SPEC_VERSION 1 +#define VK_AMD_GPU_SHADER_INT16_EXTENSION_NAME "VK_AMD_gpu_shader_int16" + + +#define VK_EXT_blend_operation_advanced 1 +#define VK_EXT_BLEND_OPERATION_ADVANCED_SPEC_VERSION 2 +#define VK_EXT_BLEND_OPERATION_ADVANCED_EXTENSION_NAME "VK_EXT_blend_operation_advanced" + + +typedef enum VkBlendOverlapEXT { + VK_BLEND_OVERLAP_UNCORRELATED_EXT = 0, + VK_BLEND_OVERLAP_DISJOINT_EXT = 1, + VK_BLEND_OVERLAP_CONJOINT_EXT = 2, + VK_BLEND_OVERLAP_BEGIN_RANGE_EXT = VK_BLEND_OVERLAP_UNCORRELATED_EXT, + VK_BLEND_OVERLAP_END_RANGE_EXT = VK_BLEND_OVERLAP_CONJOINT_EXT, + VK_BLEND_OVERLAP_RANGE_SIZE_EXT = (VK_BLEND_OVERLAP_CONJOINT_EXT - VK_BLEND_OVERLAP_UNCORRELATED_EXT + 1), + VK_BLEND_OVERLAP_MAX_ENUM_EXT = 0x7FFFFFFF +} VkBlendOverlapEXT; + +typedef struct VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT { + VkStructureType sType; + void* pNext; + VkBool32 advancedBlendCoherentOperations; +} VkPhysicalDeviceBlendOperationAdvancedFeaturesEXT; + +typedef struct VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT { + VkStructureType sType; + void* pNext; + uint32_t advancedBlendMaxColorAttachments; + VkBool32 advancedBlendIndependentBlend; + VkBool32 advancedBlendNonPremultipliedSrcColor; + VkBool32 advancedBlendNonPremultipliedDstColor; + VkBool32 advancedBlendCorrelatedOverlap; + VkBool32 advancedBlendAllOperations; +} VkPhysicalDeviceBlendOperationAdvancedPropertiesEXT; + +typedef struct VkPipelineColorBlendAdvancedStateCreateInfoEXT { + VkStructureType sType; + const void* pNext; + VkBool32 srcPremultiplied; + VkBool32 dstPremultiplied; + VkBlendOverlapEXT blendOverlap; +} VkPipelineColorBlendAdvancedStateCreateInfoEXT; + + + +#define VK_NV_fragment_coverage_to_color 1 +#define VK_NV_FRAGMENT_COVERAGE_TO_COLOR_SPEC_VERSION 1 +#define VK_NV_FRAGMENT_COVERAGE_TO_COLOR_EXTENSION_NAME "VK_NV_fragment_coverage_to_color" + +typedef VkFlags VkPipelineCoverageToColorStateCreateFlagsNV; + +typedef struct VkPipelineCoverageToColorStateCreateInfoNV { + VkStructureType sType; + const void* pNext; + VkPipelineCoverageToColorStateCreateFlagsNV flags; + VkBool32 coverageToColorEnable; + uint32_t coverageToColorLocation; +} VkPipelineCoverageToColorStateCreateInfoNV; + + + +#define VK_NV_framebuffer_mixed_samples 1 +#define VK_NV_FRAMEBUFFER_MIXED_SAMPLES_SPEC_VERSION 1 +#define VK_NV_FRAMEBUFFER_MIXED_SAMPLES_EXTENSION_NAME "VK_NV_framebuffer_mixed_samples" + + +typedef enum VkCoverageModulationModeNV { + VK_COVERAGE_MODULATION_MODE_NONE_NV = 0, + VK_COVERAGE_MODULATION_MODE_RGB_NV = 1, + VK_COVERAGE_MODULATION_MODE_ALPHA_NV = 2, + VK_COVERAGE_MODULATION_MODE_RGBA_NV = 3, + VK_COVERAGE_MODULATION_MODE_BEGIN_RANGE_NV = VK_COVERAGE_MODULATION_MODE_NONE_NV, + VK_COVERAGE_MODULATION_MODE_END_RANGE_NV = VK_COVERAGE_MODULATION_MODE_RGBA_NV, + VK_COVERAGE_MODULATION_MODE_RANGE_SIZE_NV = (VK_COVERAGE_MODULATION_MODE_RGBA_NV - VK_COVERAGE_MODULATION_MODE_NONE_NV + 1), + VK_COVERAGE_MODULATION_MODE_MAX_ENUM_NV = 0x7FFFFFFF +} VkCoverageModulationModeNV; + +typedef VkFlags VkPipelineCoverageModulationStateCreateFlagsNV; + +typedef struct VkPipelineCoverageModulationStateCreateInfoNV { + VkStructureType sType; + const void* pNext; + VkPipelineCoverageModulationStateCreateFlagsNV flags; + VkCoverageModulationModeNV coverageModulationMode; + VkBool32 coverageModulationTableEnable; + uint32_t coverageModulationTableCount; + const float* pCoverageModulationTable; +} VkPipelineCoverageModulationStateCreateInfoNV; + + + +#define VK_NV_fill_rectangle 1 +#define VK_NV_FILL_RECTANGLE_SPEC_VERSION 1 +#define VK_NV_FILL_RECTANGLE_EXTENSION_NAME "VK_NV_fill_rectangle" + + #ifdef __cplusplus } #endif