VKNULLHANDLE

VK_NULL_HANDLE is a sentinel value used in the Vulkan API to represent a null or uninitialized handle. It is defined in Vulkan header files as a single, consistent value that can be compared across all handle types, including both dispatchable handles (such as VkInstance, VkDevice, VkQueue) and non-dispatchable handles (such as VkBuffer, VkImage). In practice, VK_NULL_HANDLE is defined as zero.

The main purpose of VK_NULL_HANDLE is to provide a standardized way to indicate an absence of a valid Vulkan object. It is commonly used to initialize handle variables, to check whether a handle has been created successfully, or to signal that a parameter refers to no object. Because all Vulkan handle types share the same null value, code can initialize any handle with VK_NULL_HANDLE and perform straightforward comparisons like if (handle == VK_NULL_HANDLE).

Usage examples are straightforward: initialize a handle, for example VkInstance instance = VK_NULL_HANDLE; after a successful creation, the handle should be changed to a valid object. It is also common to pass VK_NULL_HANDLE as a parameter to functions when an optional object is not provided, depending on the command and extension being used. Developers should not call Vulkan functions with VK_NULL_HANDLE for objects that must be valid.

Note on terminology: VKNULLHANDLE is not a standard Vulkan term. The official constant is VK_NULL_HANDLE. If VKNULLHANDLE appears in code or documentation, it may be a nonstandard alias or a misnominal reference to VK_NULL_HANDLE.

See also VK_NULL_HANDLE, Vulkan handles, dispatchable and non-dispatchable handles.