1// Copyright 2018-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_EXT_fragment_density_map.adoc[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2021-09-30 11*Interactions and External Dependencies*:: 12 - This extension requires 13 {spirv}/EXT/SPV_EXT_fragment_invocation_density.html[`SPV_EXT_fragment_invocation_density`] 14 - This extension provides API support for 15 {GLSLregistry}/ext/GLSL_EXT_fragment_invocation_density.txt[`GL_EXT_fragment_invocation_density`] 16*Contributors*:: 17 - Matthew Netsch, Qualcomm Technologies, Inc. 18 - Robert VanReenen, Qualcomm Technologies, Inc. 19 - Jonathan Wicks, Qualcomm Technologies, Inc. 20 - Tate Hornbeck, Qualcomm Technologies, Inc. 21 - Sam Holmes, Qualcomm Technologies, Inc. 22 - Jeff Leger, Qualcomm Technologies, Inc. 23 - Jan-Harald Fredriksen, ARM 24 - Jeff Bolz, NVIDIA 25 - Pat Brown, NVIDIA 26 - Daniel Rakos, AMD 27 - Piers Daniell, NVIDIA 28 29=== Description 30 31This extension allows an application to specify areas of the render target 32where the fragment shader may be invoked fewer times. 33These fragments are broadcasted out to multiple pixels to cover the render 34target. 35 36The primary use of this extension is to reduce workloads in areas where 37lower quality may not be perceived such as the distorted edges of a lens or 38the periphery of a user's gaze. 39 40include::{generated}/interfaces/VK_EXT_fragment_density_map.adoc[] 41 42=== New or Modified Built-In Variables 43 44 * <<interfaces-builtin-variables-fraginvocationcount,code:FragInvocationCountEXT>> 45 * <<interfaces-builtin-variables-fragsize,code:FragSizeEXT>> 46 47=== New SPIR-V Capabilities 48 49 * <<spirvenv-capabilities-table-FragmentDensityEXT, 50 code:FragmentDensityEXT>> 51 52ifdef::isrefpage[] 53=== Examples 54 55==== Fragment Density Map 56 57An image can be bound as a fragment density map attachment to a render pass. 58This image contains normalized (x, y) float component fragment density 59values for regions of the framebuffer that will be used in rasterization for 60every subpass. 61A float component ranges from (0.0, 1.0] where 1.0 means full density along 62that axis. 63Implementations <<fragmentdensitymapops,use these values as hints>> to 64optimize rendering in areas of low density. 65Subpass color and depth attachments can be created as subsampled, which can 66help to further optimize rendering in areas of low density. 67 68The density map image can be modified by the application until calling 69fname:vkCmdBeginRenderPass for the render pass that uses the image. 70If ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT is used, 71then the application can modify the image until the device reads it during 72ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT. 73 74[source,c++] 75---------------------------------------- 76// Create fragment density map 77VkImageCreateInfo imageCreateInfo = 78{ 79 VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, 80 nullptr, 81 0, 82 VK_IMAGE_TYPE_2D, // Must be 2D 83 VK_FORMAT_R8G8_UNORM, // Must have VK_FORMAT_FEATURE_FRAGMENT_DENSITY_MAP_BIT_EXT 84 {64, 64, 1}, // extent 85 1, // mipLevels 86 2, // arrayLayers; 1 for each multiview view 87 VK_SAMPLE_COUNT_1_BIT, // Must be 1x MSAA 88 tiling, 89 VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, 90 // ... 91}; 92 93vkCreateImage(device, &imageCreateInfo, nullptr, &fdmImage); 94 95VkImageViewCreateInfo viewCreateInfo = 96{ 97 VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, 98 nullptr, 99 0, // VkImageViewCreateFlags 100 fdmImage, 101 VK_IMAGE_VIEW_TYPE_2D_ARRAY, 102 VK_FORMAT_R8G8_UNORM, 103 {0}, // VK_COMPONENT_SWIZZLE_IDENTITY 104 {VK_IMAGE_ASPECT_COLOR_BIT, 105 0, // baseMipLevel 106 1, // levelCount; must be 1 107 0, // baseArrayLayer 108 2, // layerCount 109 } 110}; 111 112vkCreateImageView(device, &viewCreateInfo, nullptr, &fdmImageView); 113 114// Add fdmImage to render pass 115 116VkAttachmentReference fragmentDensityMapAttachmentReference = 117{ 118 fdmAttachmentIdx, 119 VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT, 120}; 121 122VkRenderPassFragmentDensityMapCreateInfoEXT fdmAttachmentCreateInfo = 123{ 124 VK_STRUCTURE_TYPE_RENDER_PASS_FRAGMENT_DENSITY_MAP_CREATE_INFO_EXT, 125 // ... 126 fragmentDensityMapAttachmentReference, 127}; 128 129VkRenderPassCreateInfo2 renderPassCreateInfo = 130{ 131 VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2, 132 &fdmAttachmentCreateInfo, 133 // ... 134}; 135 136vkCreateRenderPass2(device, &renderPassCreateInfo, nullptr, &renderPass); 137 138// Add fdmImage to framebuffer 139// Color attachments can be created with VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 140// All attachments must be created with VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSETS_BIT_EXT 141VkFramebufferCreateInfo framebufferCreateInfo = 142{ 143 VK_STRUCTURE_TYPE_FRAME_BUFFER_CREATE_INFO, 144 // ... 145 renderPass, 146 // ... 147 pAttachments, // Includes fdmImageView at fdmAttachmentIdx 148 1024, // width 149 1024, // height 150 1 // layers; must be 1 if using multiview 151}; 152 153vkCreateFramebuffer(device, &framebufferCreateInfo, nullptr, &framebuffer); 154 155// Start recording render pass in command buffer 156 157VkRenderPassBeginInfo renderPassBeginInfo = 158{ 159 VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO, 160 // ... 161 renderPass, 162 framebuffer, 163 // ... 164}; 165 166// Can no longer modify the fdmImage's contents after this call 167vkCmdBeginRenderPass2(commandBuffer, &renderPassBeginInfo, pSubpassBeginInfo); 168 169---------------------------------------- 170endif::isrefpage[] 171 172=== Version History 173 174 * Revision 1, 2018-09-25 (Matthew Netsch) 175 ** Initial version 176 * Revision 2, 2021-09-30 (Jon Leech) 177 ** Add interaction with `apiext:VK_KHR_format_feature_flags2` to `vk.xml` 178 179