// Copyright 2020-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_fragment_density_map2.txt[]

=== Other Extension Metadata

*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

=== Description

This extension adds additional features and properties to
`apiext: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.

include::{generated}/interfaces/VK_EXT_fragment_density_map.txt[]

=== 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[]