Skip to content

Efficient thread-safe ktxTexture_VkUploadEx_WithSuballocator() with queue guard callbacks #1231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
toomuchvoltage wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Efficient thread-safe ktxTexture_VkUploadEx_WithSuballocator() with queue guard callbacks #1231

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
97a487e
Queue guard callbacks that can make UploadEx efficiently thread-safe …
toomuchvoltage May 22, 2026
9b042a2
Transfer queue support
toomuchvoltage May 24, 2026
86ae1ab
Don't leave the memory mapped on the way out
toomuchvoltage May 25, 2026
03dc28a
Reverting commit for transfer queue support. Changing Vulkan usage in…
toomuchvoltage Jul 30, 2026
00e3f9a
Merge branch 'main' into main
toomuchvoltage Aug 1, 2026
82a5bad
Sample usage for tests. These only serve as a guide and do not stress…
toomuchvoltage Aug 1, 2026
b1170cb
Other than map and unmap, VMA is thread-safe: memory guards were too …
toomuchvoltage Aug 10, 2026
339c047
Addressing comment issues. Making the first set more succinct.
toomuchvoltage Aug 10, 2026
6c155ad
* Noting that a per-thread VDI is a necessary prerequisite for thread…
toomuchvoltage Aug 15, 2026
130a536
* Common path for cleaning up partially initialized resources during …
toomuchvoltage Aug 17, 2026
d52645a
Merge branch 'main' into main
toomuchvoltage Aug 18, 2026
6da6d8e
* Better comments with more emphasis on the necessity of a per-thread…
toomuchvoltage Aug 23, 2026
4f7d857
* Further clarifications on `VDI` and `queueMutexCallbacks` parameter…
toomuchvoltage Aug 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions lib/include/ktxvulkan.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,9 @@ typedef VkResult(*ktxVulkanTexture_subAllocatorBindImageFuncPtr)(VkImage image,
typedef VkResult(*ktxVulkanTexture_subAllocatorMemoryMapFuncPtr)(uint64_t allocId, uint64_t pageNumber, VkDeviceSize *mapLength, void** dataPtr);
typedef void (*ktxVulkanTexture_subAllocatorMemoryUnmapFuncPtr)(uint64_t allocId, uint64_t pageNumber);
typedef void (*ktxVulkanTexture_subAllocatorFreeMemFuncPtr)(uint64_t allocId);
typedef void (*ktxVulkanTexture_queueLockFuncPtr)(VkQueue queueToLock);
typedef void (*ktxVulkanTexture_queueUnlockFuncPtr)(VkQueue queueToUnlock);

/**
* @class ktxVulkanTexture_subAllocatorCallbacks
* @~English
Expand Down Expand Up @@ -234,6 +237,35 @@ KTX_API void KTX_APIENTRY
ktxVulkanDeviceInfo_Destruct(ktxVulkanDeviceInfo* This);
KTX_API void KTX_APIENTRY
ktxVulkanDeviceInfo_Destroy(ktxVulkanDeviceInfo* This);


/**
* @class ktxVulkanTexture_queueGuardCallbacks
* @~English
* @brief Struct that contains callbacks necessary for guarding access to the supplied queue in vdi.
*
* As a prerequisite, a per-thread VDI is necessary for thread-safety.
* Needs to be used in conjunction with suballocator callbacks that are also thread-safe.
* Together they can make UploadEx fully thread-safe in an efficient manner.
* The suballocator callbacks need to guard around memory objects and if sparse binding
* support is introduced, will need to guard around both memory and queue objects.
* Thread-safety for the external bookkeeping mechanism is also a necessity.
*
*/
typedef struct {
ktxVulkanTexture_queueLockFuncPtr queueLockFuncPtr; /*!< Pointer to function for commencing mutually exclusive access to the vdi queue. */
ktxVulkanTexture_queueUnlockFuncPtr queueUnlockFuncPtr; /*!< Pointer to function for ending mutually exclusive access to the vdi queue. */
} ktxVulkanTexture_QueueGuardCallbacks;

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_VkUploadEx_WithSuballocatorAndQueueGuard(ktxTexture* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
VkImageTiling tiling,
VkImageUsageFlags usageFlags,
VkImageLayout finalLayout,
ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks,
ktxVulkanTexture_QueueGuardCallbacks* queueMutexCallbacks);

KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_VkUploadEx_WithSuballocator(ktxTexture* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
Expand All @@ -251,6 +283,14 @@ KTX_API KTX_error_code KTX_APIENTRY
ktxTexture_VkUpload(ktxTexture* texture, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture *vkTexture);
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_VkUploadEx_WithSuballocatorAndQueueGuard(ktxTexture1* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
VkImageTiling tiling,
VkImageUsageFlags usageFlags,
VkImageLayout finalLayout,
ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks,
ktxVulkanTexture_QueueGuardCallbacks* queueMutexCallbacks);
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_VkUploadEx_WithSuballocator(ktxTexture1* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
VkImageTiling tiling,
Expand All @@ -267,6 +307,14 @@ KTX_API KTX_error_code KTX_APIENTRY
ktxTexture1_VkUpload(ktxTexture1* texture, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture *vkTexture);
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_VkUploadEx_WithSuballocatorAndQueueGuard(ktxTexture2* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
VkImageTiling tiling,
VkImageUsageFlags usageFlags,
VkImageLayout finalLayout,
ktxVulkanTexture_subAllocatorCallbacks* subAllocatorCallbacks,
ktxVulkanTexture_QueueGuardCallbacks* queueMutexCallbacks);
KTX_API KTX_error_code KTX_APIENTRY
ktxTexture2_VkUploadEx_WithSuballocator(ktxTexture2* This, ktxVulkanDeviceInfo* vdi,
ktxVulkanTexture* vkTexture,
VkImageTiling tiling,
Expand Down
Loading
Loading