1 /*
2 * Copyright © 2021 Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice (including the next
12 * paragraph) shall be included in all copies or substantial portions of the
13 * Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 */
23 #ifndef VK_IMAGE_H
24 #define VK_IMAGE_H
25
26 #include "vk_object.h"
27
28 #include "util/u_math.h"
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 struct vk_image {
35 struct vk_object_base base;
36
37 VkImageCreateFlags create_flags;
38 VkImageType image_type;
39
40 /* format is from VkImageCreateInfo::format or
41 * VkExternalFormatANDROID::externalFormat. This works because only one of
42 * them can be defined and the runtime uses VkFormat for external formats.
43 */
44 VkFormat format;
45
46 VkExtent3D extent;
47 uint32_t mip_levels;
48 uint32_t array_layers;
49 VkSampleCountFlagBits samples;
50 VkImageTiling tiling;
51 VkImageUsageFlags usage;
52
53 /* Derived from format */
54 VkImageAspectFlags aspects;
55
56 /* VK_EXT_separate_stencil_usage */
57 VkImageUsageFlags stencil_usage;
58
59 /* VK_KHR_external_memory */
60 VkExternalMemoryHandleTypeFlags external_handle_types;
61
62 /* wsi_image_create_info::scanout */
63 bool wsi_legacy_scanout;
64
65 #ifndef _WIN32
66 /* VK_EXT_drm_format_modifier
67 *
68 * Initialized by vk_image_create/init() to DRM_FORMAT_MOD_INVALID. It's
69 * the job of the driver to parse the VK_EXT_drm_format_modifier extension
70 * structs and choose the actual modifier.
71 *
72 * Must be DRM_FORMAT_MOD_INVALID unless tiling is
73 * VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.
74 */
75 uint64_t drm_format_mod;
76 #endif
77
78 #ifdef ANDROID
79 /* AHARDWAREBUFFER_FORMAT for this image or 0
80 *
81 * A default is provided by the Vulkan runtime code based on the VkFormat
82 * but it may be overridden by the driver as needed.
83 */
84 uint32_t ahb_format;
85 #endif
86 };
87 VK_DEFINE_NONDISP_HANDLE_CASTS(vk_image, base, VkImage,
88 VK_OBJECT_TYPE_IMAGE);
89
90 void vk_image_init(struct vk_device *device,
91 struct vk_image *image,
92 const VkImageCreateInfo *pCreateInfo);
93 void vk_image_finish(struct vk_image *image);
94
95 void *vk_image_create(struct vk_device *device,
96 const VkImageCreateInfo *pCreateInfo,
97 const VkAllocationCallbacks *alloc,
98 size_t size);
99 void vk_image_destroy(struct vk_device *device,
100 const VkAllocationCallbacks *alloc,
101 struct vk_image *image);
102
103 VkResult
104 vk_image_create_get_format_list(struct vk_device *device,
105 const VkImageCreateInfo *pCreateInfo,
106 const VkAllocationCallbacks *pAllocator,
107 VkFormat **formats,
108 uint32_t *format_count);
109
110 void vk_image_set_format(struct vk_image *image, VkFormat format);
111
112 VkImageUsageFlags vk_image_usage(const struct vk_image *image,
113 VkImageAspectFlags aspect_mask);
114
115 VkImageAspectFlags vk_image_expand_aspect_mask(const struct vk_image *image,
116 VkImageAspectFlags aspect_mask);
117
118 static inline VkExtent3D
vk_image_mip_level_extent(const struct vk_image * image,uint32_t mip_level)119 vk_image_mip_level_extent(const struct vk_image *image,
120 uint32_t mip_level)
121 {
122 const VkExtent3D extent = {
123 u_minify(image->extent.width, mip_level),
124 u_minify(image->extent.height, mip_level),
125 u_minify(image->extent.depth, mip_level),
126 };
127 return extent;
128 }
129
130 /* This is defined as a macro so that it works for both
131 * VkImageSubresourceRange and VkImageSubresourceLayers
132 */
133 #define vk_image_subresource_layer_count(_image, _range) \
134 ((_range)->layerCount == VK_REMAINING_ARRAY_LAYERS ? \
135 (_image)->array_layers - (_range)->baseArrayLayer : (_range)->layerCount)
136
137 static inline uint32_t
vk_image_subresource_level_count(const struct vk_image * image,const VkImageSubresourceRange * range)138 vk_image_subresource_level_count(const struct vk_image *image,
139 const VkImageSubresourceRange *range)
140 {
141 return range->levelCount == VK_REMAINING_MIP_LEVELS ?
142 image->mip_levels - range->baseMipLevel : range->levelCount;
143 }
144
145 static inline VkExtent3D
vk_image_sanitize_extent(const struct vk_image * image,const VkExtent3D imageExtent)146 vk_image_sanitize_extent(const struct vk_image *image,
147 const VkExtent3D imageExtent)
148 {
149 switch (image->image_type) {
150 case VK_IMAGE_TYPE_1D:
151 return (VkExtent3D) { imageExtent.width, 1, 1 };
152 case VK_IMAGE_TYPE_2D:
153 return (VkExtent3D) { imageExtent.width, imageExtent.height, 1 };
154 case VK_IMAGE_TYPE_3D:
155 return imageExtent;
156 default:
157 unreachable("invalid image type");
158 }
159 }
160
161 VkExtent3D
162 vk_image_extent_to_elements(const struct vk_image *image, VkExtent3D extent);
163
164 static inline VkOffset3D
vk_image_sanitize_offset(const struct vk_image * image,const VkOffset3D imageOffset)165 vk_image_sanitize_offset(const struct vk_image *image,
166 const VkOffset3D imageOffset)
167 {
168 switch (image->image_type) {
169 case VK_IMAGE_TYPE_1D:
170 return (VkOffset3D) { imageOffset.x, 0, 0 };
171 case VK_IMAGE_TYPE_2D:
172 return (VkOffset3D) { imageOffset.x, imageOffset.y, 0 };
173 case VK_IMAGE_TYPE_3D:
174 return imageOffset;
175 default:
176 unreachable("invalid image type");
177 }
178 }
179
180 VkOffset3D
181 vk_image_offset_to_elements(const struct vk_image *image, VkOffset3D offset);
182
183 struct vk_image_buffer_layout {
184 /**
185 * VkBufferImageCopy2::bufferRowLength or
186 * VkBufferImageCopy2::extent::width as needed.
187 */
188 uint32_t row_length;
189
190 /**
191 * VkBufferImageCopy2::bufferImageHeight or
192 * VkBufferImageCopy2::extent::height as needed.
193 */
194 uint32_t image_height;
195
196 /** Size of a single element (pixel or compressed block) in bytes */
197 uint32_t element_size_B;
198
199 /** Row stride in bytes */
200 uint32_t row_stride_B;
201
202 /** Image (or layer) stride in bytes
203 *
204 * For 1D or 2D array images, this is the stride in bytes between array
205 * slices. For 3D images, this is the stride in bytes between fixed-Z
206 * slices.
207 */
208 uint64_t image_stride_B;
209 };
210
211 struct vk_image_buffer_layout
212 vk_image_buffer_copy_layout(const struct vk_image *image,
213 const VkBufferImageCopy2* region);
214
215 struct vk_image_buffer_layout
216 vk_memory_to_image_copy_layout(const struct vk_image *image,
217 const VkMemoryToImageCopyEXT* region);
218
219 struct vk_image_buffer_layout
220 vk_image_to_memory_copy_layout(const struct vk_image *image,
221 const VkImageToMemoryCopyEXT* region);
222
223 struct vk_image_view {
224 struct vk_object_base base;
225
226 VkImageViewCreateFlags create_flags;
227 struct vk_image *image;
228 VkImageViewType view_type;
229
230 /** VkImageViewCreateInfo::format or vk_image::format */
231 VkFormat format;
232
233 /** Image view format, relative to the selected aspects
234 *
235 * For a depth/stencil image:
236 *
237 * - If vk_image_view::aspects contains both depth and stencil, this will
238 * be the full depth/stencil format of the image.
239 *
240 * - If only one aspect is selected, this will be the depth-only or
241 * stencil-only format, as per the selected aspect.
242 *
243 * For color images, we have three cases:
244 *
245 * 1. It's a single-plane image in which case this is the unmodified
246 * format provided to VkImageViewCreateInfo::format or
247 * vk_image::format.
248 *
249 * 2. It's a YCbCr view of a multi-plane image in which case the
250 * client will have asked for VK_IMAGE_ASPECT_COLOR_BIT and the
251 * format provided will be the full planar format. In this case,
252 * the format will be the full format containing all the planes.
253 *
254 * 3. It's a single-plane view of a multi-plane image in which case
255 * the client will have asked for VK_IMAGE_ASPECT_PLANE_N_BIT and
256 * will have provided a format compatible with that specific
257 * plane of the multi-planar format. In this case, the format will be
258 * the plane-compatible format requested by the client.
259 */
260 VkFormat view_format;
261
262 /* Component mapping, aka swizzle
263 *
264 * Unlike the swizzle provided via VkImageViewCreateInfo::components, this
265 * will never contain VK_COMPONENT_SWIZZLE_IDENTITY. It will be resolved
266 * to VK_COMPONENT_SWIZZLE_R/G/B/A, as appropriate.
267 */
268 VkComponentMapping swizzle;
269
270 /** Aspects from the image represented by this view
271 *
272 * For depth/stencil images, this is the aspectMask provided by
273 * VkImageViewCreateinfo::subresourceRange::aspectMask.
274 *
275 * For color images, we have three cases:
276 *
277 * 1. It's a single-plane image in which case this only aspect is
278 * VK_IMAGE_ASPECT_COLOR_BIT.
279 *
280 * 2. It's a YCbCr view of a multi-plane image in which case the
281 * client will have asked for VK_IMAGE_ASPECT_COLOR_BIT and the
282 * format provided will be the full planar format. In this case,
283 * aspects will be the full set of plane aspects in the image.
284 *
285 * 3. It's a single-plane view of a multi-plane image in which case
286 * the client will have asked for VK_IMAGE_ASPECT_PLANE_N_BIT and
287 * will have provided a format compatible with that specific
288 * plane of the multi-planar format. In this case, aspects will be
289 * VK_IMAGE_ASPECT_PLANE_N_BIT where N is the selected plane.
290 *
291 * This seems almost backwards from the API but ensures that
292 * vk_image_view::aspects is always a subset of vk_image::aspects.
293 */
294 VkImageAspectFlags aspects;
295
296 uint32_t base_mip_level;
297 uint32_t level_count;
298 uint32_t base_array_layer;
299 uint32_t layer_count;
300
301 /* VK_EXT_sliced_view_of_3d */
302 struct {
303 /* VkImageViewSlicedCreateInfoEXT::sliceOffset
304 *
305 * This field will be 0 for 1D and 2D images, 2D views of 3D images, or
306 * when no VkImageViewSlicedCreateInfoEXT is provided.
307 */
308 uint32_t z_slice_offset;
309
310 /* VkImageViewSlicedCreateInfoEXT::sliceCount
311 *
312 * This field will be 1 for 1D and 2D images or 2D views of 3D images.
313 * For 3D views, it will be VkImageViewSlicedCreateInfoEXT::sliceCount
314 * or image view depth (see vk_image_view::extent) when no
315 * VkImageViewSlicedCreateInfoEXT is provided.
316 */
317 uint32_t z_slice_count;
318 } storage;
319
320 /* VK_EXT_image_view_min_lod */
321 float min_lod;
322
323 /* Image extent at LOD 0 */
324 VkExtent3D extent;
325
326 /* VK_KHR_maintenance2 */
327 VkImageUsageFlags usage;
328 };
329 VK_DEFINE_NONDISP_HANDLE_CASTS(vk_image_view, base, VkImageView,
330 VK_OBJECT_TYPE_IMAGE_VIEW);
331
332 void vk_image_view_init(struct vk_device *device,
333 struct vk_image_view *image_view,
334 bool driver_internal,
335 const VkImageViewCreateInfo *pCreateInfo);
336 void vk_image_view_finish(struct vk_image_view *image_view);
337
338 void *vk_image_view_create(struct vk_device *device,
339 bool driver_internal,
340 const VkImageViewCreateInfo *pCreateInfo,
341 const VkAllocationCallbacks *alloc,
342 size_t size);
343 void vk_image_view_destroy(struct vk_device *device,
344 const VkAllocationCallbacks *alloc,
345 struct vk_image_view *image_view);
346
347 static inline VkImageSubresourceRange
vk_image_view_subresource_range(const struct vk_image_view * view)348 vk_image_view_subresource_range(const struct vk_image_view *view)
349 {
350 VkImageSubresourceRange range = {
351 .aspectMask = view->aspects,
352 .baseMipLevel = view->base_mip_level,
353 .levelCount = view->level_count,
354 .baseArrayLayer = view->base_array_layer,
355 .layerCount = view->layer_count,
356 };
357
358 return range;
359 }
360
361 bool vk_image_layout_is_read_only(VkImageLayout layout,
362 VkImageAspectFlagBits aspect);
363 bool vk_image_layout_is_depth_only(VkImageLayout layout);
364
365 VkImageUsageFlags vk_image_layout_to_usage_flags(VkImageLayout layout,
366 VkImageAspectFlagBits aspect);
367
368 VkImageLayout vk_att_ref_stencil_layout(const VkAttachmentReference2 *att_ref,
369 const VkAttachmentDescription2 *attachments);
370 VkImageLayout vk_att_desc_stencil_layout(const VkAttachmentDescription2 *att_desc,
371 bool final);
372
373 #ifdef __cplusplus
374 }
375 #endif
376
377 #endif /* VK_IMAGE_H */
378