From cab7ffaa12bcdb972ba8245fb6a99d402c1fa916 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 3 Jul 2020 19:42:41 -0700 Subject: [PATCH] Change log for July 3, 2020 Vulkan 1.2.146 spec update: * Update release number to 146 for this update. Github Issues: * Fix valid usage generation script for optional bitmasks in a non-optional array (public pull request 1228). * Add lunr to `package.json` and update the locally cached copy (public pull request 1238). * Require that newly released extensions have etext:*_SPEC_VERSION `1` (public issue 1263). * Add to the NOTE in slink:VkPhysicalDeviceIDProperties, advising implementations on returning unique pname:deviceUUID values and avoiding hardwired values, especially 0 (public issue 1273). * Add noscript fallback for HTML output (public pull request 1289). * Fix duplicated VUIDs in flink:vkCmdExecuteGeneratedCommandsNV (public pull request 1304). * Fix link markup in <> chapter, nested link markup, and linear equation markup in <> (public pull requests 1305, 1306, 1307). Internal Issues: * Add comments to extending enums in the generated API interfaces showing which core version and/or extensions provide the enum, matching recent changes to show this information for commands and structures (internal issue 1431). * Only allow code:Invocation memory scope in the <> section when memory semantics is *None* (internal issue 1782). * Make reflow script handle literal block delimiters and lines containing only whitespace properly (internal issues 2039, 2042). * Clarify definition of <> (internal issue 2236). * Add missing `errorcodes=` XML attributes for some `<>` commands. * Clarify <> and the related <>, <>, <>, <> limits (internal merge request 3922). * Remove redundant valid usage statement VUID-VkFramebufferCreateInfo-flags-03188 (internal merge request 3934). * Update style guide to recommend new extension spec language be contained in existing asciidoctor files, unless it's of enough scope to create a and new chapter (internal merge request 3955). New Extensions: * `<>` (public pull requests 1292, 1294). * `<>` (internal merge request 3914). --- appendices/VK_EXT_fragment_density_map2.txt | 118 ++++++++++++++++++++ config/vuid-expander.rb | 21 ++++ scripts/testSpecVersion.py | 71 ++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 appendices/VK_EXT_fragment_density_map2.txt create mode 100644 config/vuid-expander.rb create mode 100755 scripts/testSpecVersion.py diff --git a/appendices/VK_EXT_fragment_density_map2.txt b/appendices/VK_EXT_fragment_density_map2.txt new file mode 100644 index 0000000000..34f8932774 --- /dev/null +++ b/appendices/VK_EXT_fragment_density_map2.txt @@ -0,0 +1,118 @@ +// Copyright (c) 2020 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/VK_EXT_fragment_density_map2.txt[] + +*Last Modified Date*:: + 2020-06-16 +*Interactions and External Dependencies*:: + - Interacts with Vulkan 1.1 +*Contributors*:: + - Matthew Netsch, Qualcomm Technologies, Inc. + - Jonathan Tinkham, Qualcomm Technologies, Inc. + - Jonathan Wicks, Qualcomm Technologies, Inc. + - Jan-Harald Fredriksen, ARM + +This extension adds additional features and properties to +`<>` in order to reduce fragment density map +host latency as well as improved queries for subsampled sampler +implementation-dependent behavior. + +=== New Object Types + +None. + +=== New Enum Constants + + * Extending elink:VkImageViewCreateFlagBits: + ** ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_FEATURES_EXT + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FRAGMENT_DENSITY_MAP_2_PROPERTIES_EXT + +=== New Enums + +None. + +=== New Structures + + * slink:VkPhysicalDeviceFragmentDensityMap2FeaturesEXT + * slink:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT + +=== New Functions + +None. + +=== New Variable Decorations + +None. + +=== Version History + + * Revision 1, 2020-06-16 (Matthew Netsch) + - Initial version + +ifdef::isrefpage[] +=== Examples + +==== Additional limits for subsampling + +Some implementations may not support subsampled samplers if certain +implementation limits are not observed by the app. +slink:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT provides additional +limits to require apps remain within these boundaries if they wish to use +subsampling. + +==== Improved host latency + +By default, the fragment density map is locked by the host for reading +between flink:vkCmdBeginRenderPass during recording and +ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT during draw +execution. + +This can introduce large latency for certain use cases between recording the +frame and displaying the frame. +Apps may wish to modify the fragment density map just before draw execution. + +ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT is intended +to help address this for implementations that do not support the +<> feature by +deferring the start of the locked range to flink:vkEndCommandBuffer. + + +[source,c++] +---------------------------------------- +// Create view for fragment density map +VkImageViewCreateInfo createInfo = +{ + ​VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, + // ... + VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT, + fdmImage, // Created with VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT + // ... +}; + +// ... + +// Begin fragment density map render pass with deferred view. +// By default, fdmImage must not be modified after this call +// unless view is created with the FDM dynamic or deferred flags. +vkCmdBeginRenderPass(commandBuffer, pRenderPassBegin, contents); + +// ... + +vkCmdEndRenderPass(VkCommandBuffer commandBuffer); + +// Can keep making modifications to deferred fragment density maps +// while recording commandBuffer ... + +result = vkEndCommandBuffer(commandBuffer); + +// Must now freeze modifying fdmImage until after the +// VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT of +// the last executing draw that uses the fdmImage in the +// last submit of commandBuffer. + +---------------------------------------- +endif::isrefpage[] diff --git a/config/vuid-expander.rb b/config/vuid-expander.rb new file mode 100644 index 0000000000..ba8eac8d8a --- /dev/null +++ b/config/vuid-expander.rb @@ -0,0 +1,21 @@ +# Copyright 2020 The Khronos Group Inc. +# +# SPDX-License-Identifier: Apache-2.0 + +require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal' + +include ::Asciidoctor + +# Preprocessor hook to insert vuid: inline macro after every VUID anchor +class VUIDExpanderPreprocessor < Extensions::Preprocessor + def process document, reader + new_lines = reader.read_lines.map do | line | + line.gsub(/\[\[(VUID.*?)\]\]/, '[[\1]]vuid:\1') + end + Reader.new(new_lines) + end +end + +Extensions.register do + preprocessor VUIDExpanderPreprocessor +end diff --git a/scripts/testSpecVersion.py b/scripts/testSpecVersion.py new file mode 100755 index 0000000000..c6666eee8a --- /dev/null +++ b/scripts/testSpecVersion.py @@ -0,0 +1,71 @@ +#!/usr/bin/python3 +# +# Copyright (c) 2017-2020 The Khronos Group Inc. +# +# SPDX-License-Identifier: Apache-2.0 + +# testSpecVersion - check if SPEC_VERSION values for an unpublished +# extension branch meet the requirement of being 1. +# +# Usage: textSpecVersion.py [-branch branchname] [-registry file] +# +# Checks for an XML matching the branch name specified +# on the command line, or the current branch if not specified. +# +# If found, and the SPEC_VERSION for that has a value of '1', # +# of '1', succeeds. +# If not found, the branch is not an extension staging branch; succeeds. + +# Otherwise, fails. + +import argparse +import sys +import xml.etree.ElementTree as etree +from reflib import getBranch + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + + parser.add_argument('-branch', action='store', + default=None, + help='Specify branch to check against') + parser.add_argument('-registry', action='store', + default='xml/vk.xml', + help='Use specified registry file instead of vk.xml') + args = parser.parse_args() + + try: + tree = etree.parse(args.registry) + except: + print('ERROR - cannot open registry XML file', args.registry) + sys.exit(1) + + errors = '' + if args.branch is None: + (args.branch, errors) = getBranch() + if args.branch is None: + print('ERROR - Cannot determine current git branch:', errors) + sys.exit(1) + + elem = tree.find('extensions/extension[@name="' + args.branch + '"]') + + if elem == None: + print('Success - assuming', args.branch, 'is not an extension branch') + sys.exit(0) + + for enum in elem.findall('require/enum'): + name = enum.get('name') + + if name is not None and name[-13:] == '_SPEC_VERSION': + value = enum.get('value') + if value == '1': + print('Success - {} = 1 for branch {}'.format( + name, args.branch)) + sys.exit(0) + else: + print('ERROR - {} = {} for branch {}, but must be 1'.format( + name, value, args.branch)) + sys.exit(1) + + print('ERROR - no SPEC_VERSION token found for branch', args.branch) + sys.exit(1)