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