// 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

`<<VK_EXT_fragment_density_map>>` 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

<<features-fragmentdensitymapdynamic,fragmentDensityMapDynamic>> 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[]

require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include ::Asciidoctor

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

Extensions.register do

preprocessor VUIDExpanderPreprocessor

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)