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 24 #ifndef VK_COMMAND_BUFFER_H 25 #define VK_COMMAND_BUFFER_H 26 27 #include "vk_object.h" 28 #include "util/u_dynarray.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 struct vk_command_buffer { 35 struct vk_object_base base; 36 37 /** 38 * VK_EXT_debug_utils 39 * 40 * The next two fields represent debug labels storage. 41 * 42 * VK_EXT_debug_utils spec requires that upon triggering a debug message 43 * with a command buffer attached to it, all "active" labels will also be 44 * provided to the callback. The spec describes two distinct ways of 45 * attaching a debug label to the command buffer: opening a label region 46 * and inserting a single label. 47 * 48 * Label region is active between the corresponding `*BeginDebugUtilsLabel` 49 * and `*EndDebugUtilsLabel` calls. The spec doesn't mention any limits on 50 * nestedness of label regions. This implementation assumes that there 51 * aren't any. 52 * 53 * The spec, however, doesn't explain the lifetime of a label submitted by 54 * an `*InsertDebugUtilsLabel` call. The LunarG whitepaper [1] (pp 12-15) 55 * provides a more detailed explanation along with some examples. According 56 * to those, such label remains active until the next `*DebugUtilsLabel` 57 * call. This means that there can be no more than one such label at a 58 * time. 59 * 60 * \c labels contains all active labels at this point in order of submission 61 * \c region_begin denotes whether the most recent label opens a new region 62 * If \t labels is empty \t region_begin must be true. 63 * 64 * Anytime we modify labels, we first check for \c region_begin. If it's 65 * false, it means that the most recent label was submitted by 66 * `*InsertDebugUtilsLabel` and we need to remove it before doing anything 67 * else. 68 * 69 * See the discussion here: 70 * https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/10318#note_1061317 71 * 72 * [1] https://www.lunarg.com/wp-content/uploads/2018/05/Vulkan-Debug-Utils_05_18_v1.pdf 73 */ 74 struct util_dynarray labels; 75 bool region_begin; 76 }; 77 78 VK_DEFINE_HANDLE_CASTS(vk_command_buffer, base, VkCommandBuffer, 79 VK_OBJECT_TYPE_COMMAND_BUFFER) 80 81 VkResult MUST_CHECK 82 vk_command_buffer_init(struct vk_command_buffer *command_buffer, 83 struct vk_device *device); 84 85 void 86 vk_command_buffer_reset(struct vk_command_buffer *command_buffer); 87 88 void 89 vk_command_buffer_finish(struct vk_command_buffer *command_buffer); 90 91 #ifdef __cplusplus 92 } 93 #endif 94 95 #endif /* VK_COMMAND_BUFFER_H */ 96