VkResult(3)

# VkResult(3) Manual Page

## Name

VkResult - Vulkan command return codes

## 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_OUT_OF_POOL_MEMORY = -1000069000,
        VK_ERROR_INVALID_EXTERNAL_HANDLE = -1000072003,
        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_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
        VK_ERROR_FRAGMENTATION_EXT = -1000161000,
        VK_ERROR_NOT_PERMITTED_EXT = -1000174001,
        VK_ERROR_INVALID_DEVICE_ADDRESS_EXT = -1000244000,
        VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT = -1000255000,
        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_RESULT_MAX_ENUM = 0x7FFFFFFF
    } VkResult;

## Description

Success Codes

- `VK_SUCCESS` Command successfully completed

- `VK_NOT_READY` A fence or query has not yet completed

- `VK_TIMEOUT` A wait operation has not completed in the specified time

- `VK_EVENT_SET` An event is signaled

- `VK_EVENT_RESET` An event is unsignaled

- `VK_INCOMPLETE` A return array was too small for the result

- `VK_SUBOPTIMAL_KHR` A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.

Error codes

- `VK_ERROR_OUT_OF_HOST_MEMORY` A host memory allocation has failed.

- `VK_ERROR_OUT_OF_DEVICE_MEMORY` A device memory allocation has failed.

- `VK_ERROR_INITIALIZATION_FAILED` Initialization of an object could not be completed for implementation-specific reasons.

- `VK_ERROR_DEVICE_LOST` The logical or physical device has been lost. See Lost Device

- `VK_ERROR_MEMORY_MAP_FAILED` Mapping of a memory object has failed.

- `VK_ERROR_LAYER_NOT_PRESENT` A requested layer is not present or could not be loaded.

- `VK_ERROR_EXTENSION_NOT_PRESENT` A requested extension is not supported.

- `VK_ERROR_FEATURE_NOT_PRESENT` A requested feature is not supported.

- `VK_ERROR_INCOMPATIBLE_DRIVER` The requested version of Vulkan is not supported by the driver or is otherwise incompatible for implementation-specific reasons.

- `VK_ERROR_TOO_MANY_OBJECTS` Too many objects of the type have already been created.

- `VK_ERROR_FORMAT_NOT_SUPPORTED` A requested format is not supported on this device.

- `VK_ERROR_FRAGMENTED_POOL` A 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 to `VK_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_KHR` A surface is no longer available.

- `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR` The 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_KHR` A 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_KHR` The 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_NV` One or more shaders failed to compile or link. More details are reported back to the application via `https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_EXT_debug_report` if enabled.

- `VK_ERROR_OUT_OF_POOL_MEMORY` A 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_POOL` should be returned instead.

- `VK_ERROR_INVALID_EXTERNAL_HANDLE` An external handle is not a valid handle of the specified type.

- `VK_ERROR_FRAGMENTATION_EXT` A descriptor pool creation has failed due to fragmentation.

- `VK_ERROR_INVALID_DEVICE_ADDRESS_EXT` A buffer creation failed because the requested address is not available.

- `VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT` An operation on a swapchain created with `VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT` failed as it did not have exlusive full-screen access. This may occur due to implementation-dependent reasons, outside of the application’s control.

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.

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`.

## See Also

VkPresentInfoKHR

## 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-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.