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