C Specification
While the core Vulkan API is not designed to capture incorrect usage, some circumstances still require return codes. Commands in Vulkan return their status via return codes that are in one of two categories:
-
Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.
-
Run time error codes are returned when a command needs to communicate a failure that could only be detected at run time. All run time error codes are negative values.
All return codes in Vulkan are reported via VkResult return values. The possible codes are:
typedef enum VkResult {
VK_SUCCESS = 0,
VK_NOT_READY = 1,
VK_TIMEOUT = 2,
VK_EVENT_SET = 3,
VK_EVENT_RESET = 4,
VK_INCOMPLETE = 5,
VK_ERROR_OUT_OF_HOST_MEMORY = -1,
VK_ERROR_OUT_OF_DEVICE_MEMORY = -2,
VK_ERROR_INITIALIZATION_FAILED = -3,
VK_ERROR_DEVICE_LOST = -4,
VK_ERROR_MEMORY_MAP_FAILED = -5,
VK_ERROR_LAYER_NOT_PRESENT = -6,
VK_ERROR_EXTENSION_NOT_PRESENT = -7,
VK_ERROR_FEATURE_NOT_PRESENT = -8,
VK_ERROR_INCOMPATIBLE_DRIVER = -9,
VK_ERROR_TOO_MANY_OBJECTS = -10,
VK_ERROR_FORMAT_NOT_SUPPORTED = -11,
VK_ERROR_FRAGMENTED_POOL = -12,
VK_ERROR_UNKNOWN = -13,
VK_ERROR_OUT_OF_POOL_MEMORY = -1000069000,
VK_ERROR_INVALID_EXTERNAL_HANDLE = -1000072003,
VK_ERROR_FRAGMENTATION = -1000161000,
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS = -1000257000,
VK_ERROR_SURFACE_LOST_KHR = -1000000000,
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR = -1000000001,
VK_SUBOPTIMAL_KHR = 1000001003,
VK_ERROR_OUT_OF_DATE_KHR = -1000001004,
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR = -1000003001,
VK_ERROR_VALIDATION_FAILED_EXT = -1000011001,
VK_ERROR_INVALID_SHADER_NV = -1000012000,
VK_ERROR_INCOMPATIBLE_VERSION_KHR = -1000150000,
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
VK_ERROR_NOT_PERMITTED_EXT = -1000174001,
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT = -1000255000,
VK_THREAD_IDLE_KHR = 1000268000,
VK_THREAD_DONE_KHR = 1000268001,
VK_OPERATION_DEFERRED_KHR = 1000268002,
VK_OPERATION_NOT_DEFERRED_KHR = 1000268003,
VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT = 1000297000,
VK_ERROR_OUT_OF_POOL_MEMORY_KHR = VK_ERROR_OUT_OF_POOL_MEMORY,
VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR = VK_ERROR_INVALID_EXTERNAL_HANDLE,
VK_ERROR_FRAGMENTATION_EXT = VK_ERROR_FRAGMENTATION,
VK_ERROR_INVALID_DEVICE_ADDRESS_EXT = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR = VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS,
VK_RESULT_MAX_ENUM = 0x7FFFFFFF
} VkResult;
Description
-
VK_SUCCESSCommand successfully completed -
VK_NOT_READYA fence or query has not yet completed -
VK_TIMEOUTA wait operation has not completed in the specified time -
VK_EVENT_SETAn event is signaled -
VK_EVENT_RESETAn event is unsignaled -
VK_INCOMPLETEA return array was too small for the result -
VK_SUBOPTIMAL_KHRA swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully. -
VK_THREAD_IDLE_KHRA deferred operation is not complete but there is currently no work for this thread to do at the time of this call. -
VK_THREAD_DONE_KHRA deferred operation is not complete but there is no work remaining to assign to additional threads. -
VK_OPERATION_DEFERRED_KHRA deferred operation was requested and at least some of the work was deferred. -
VK_OPERATION_NOT_DEFERRED_KHRA deferred operation was requested and no operations were deferred.
-
VK_ERROR_OUT_OF_HOST_MEMORYA host memory allocation has failed. -
VK_ERROR_OUT_OF_DEVICE_MEMORYA device memory allocation has failed. -
VK_ERROR_INITIALIZATION_FAILEDInitialization of an object could not be completed for implementation-specific reasons. -
VK_ERROR_DEVICE_LOSTThe logical or physical device has been lost. See Lost Device -
VK_ERROR_MEMORY_MAP_FAILEDMapping of a memory object has failed. -
VK_ERROR_LAYER_NOT_PRESENTA requested layer is not present or could not be loaded. -
VK_ERROR_EXTENSION_NOT_PRESENTA requested extension is not supported. -
VK_ERROR_FEATURE_NOT_PRESENTA requested feature is not supported. -
VK_ERROR_INCOMPATIBLE_DRIVERThe requested version of Vulkan is not supported by the driver or is otherwise incompatible for implementation-specific reasons. -
VK_ERROR_TOO_MANY_OBJECTSToo many objects of the type have already been created. -
VK_ERROR_FORMAT_NOT_SUPPORTEDA requested format is not supported on this device. -
VK_ERROR_FRAGMENTED_POOLA pool allocation has failed due to fragmentation of the pool’s memory. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. This should be returned in preference toVK_ERROR_OUT_OF_POOL_MEMORY, but only if the implementation is certain that the pool allocation failure was due to fragmentation. -
VK_ERROR_SURFACE_LOST_KHRA surface is no longer available. -
VK_ERROR_NATIVE_WINDOW_IN_USE_KHRThe requested window is already in use by Vulkan or another API in a manner which prevents it from being used again. -
VK_ERROR_OUT_OF_DATE_KHRA surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface. -
VK_ERROR_INCOMPATIBLE_DISPLAY_KHRThe display used by a swapchain does not use the same presentable image layout, or is incompatible in a way that prevents sharing an image. -
VK_ERROR_INVALID_SHADER_NVOne or more shaders failed to compile or link. More details are reported back to the application viahttps://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_debug_reportif enabled. -
VK_ERROR_OUT_OF_POOL_MEMORYA pool memory allocation has failed. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. If the failure was definitely due to fragmentation of the pool,VK_ERROR_FRAGMENTED_POOLshould be returned instead. -
VK_ERROR_INVALID_EXTERNAL_HANDLEAn external handle is not a valid handle of the specified type. -
VK_ERROR_FRAGMENTATIONA descriptor pool creation has failed due to fragmentation. -
VK_ERROR_INVALID_DEVICE_ADDRESS_EXTA buffer creation failed because the requested address is not available. -
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESSA buffer creation or memory allocation failed because the requested address is not available. A shader group handle assignment failed because the requested shader group handle information is no longer valid. -
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXTAn operation on a swapchain created withVK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXTfailed as it did not have exlusive full-screen access. This may occur due to implementation-dependent reasons, outside of the application’s control. -
VK_ERROR_UNKNOWNAn unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred. -
VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXTA pipeline creation failed because some or all of the data necessary to create the pipeline was not pre-compiled.
If a command returns a run time error, unless otherwise specified any output
parameters will have undefined contents, except that if the output
parameter is a structure with sType and pNext fields, those
fields will be unmodified.
Any structures chained from pNext will also have undefined contents,
except that sType and pNext will be unmodified.
Out of memory errors do not damage any currently existing Vulkan objects. Objects that have already been successfully created can still be used by the application.
VK_ERROR_UNKNOWN will be returned by an implementation when an
unexpected error occurs that cannot be attributed to valid behavior of the
application and implementation.
|
Note
If This error should not be expected from any command if application behavior is valid, and if the implementation is bug-free, but it can be returned by any error returning command when that is not the case. |
Performance-critical commands generally do not have return codes.
If a run time error occurs in such commands, the implementation will defer
reporting the error until a specified point.
For commands that record into command buffers (vkCmd*) run time errors
are reported by vkEndCommandBuffer.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
Copyright
Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.