// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

VkResult(3)
===========

Name
----
VkResult - Vulkan command return codes

C Specification
---------------

// refBegin VkResult Vulkan command return codes

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 basetype:VkResult return
values. The possible codes are:

include::../enums/VkResult.txt[]


Description
-----------

[[fundamentals-successcodes]]
.Success codes
* ename:VK_SUCCESS
    Command successfully completed
* ename:VK_NOT_READY
    A fence or query has not yet completed
* ename:VK_TIMEOUT
    A wait operation has not completed in the specified time
* ename:VK_EVENT_SET
    An event is signaled
* ename:VK_EVENT_RESET
    An event is unsignaled
* ename:VK_INCOMPLETE
    A return array was too small for the result

[[fundamentals-errorcodes]]
.Error codes
* ename:VK_ERROR_OUT_OF_HOST_MEMORY
    A host memory allocation has failed.
* ename:VK_ERROR_OUT_OF_DEVICE_MEMORY
    A device memory allocation has failed.
* ename:VK_ERROR_INITIALIZATION_FAILED
    Initialization of an object could not be completed for
    implementation-specific reasons.
* ename:VK_ERROR_DEVICE_LOST
    The logical or physical device has been lost. See
    <<devsandqueues-lost-device,Lost Device>>
* ename:VK_ERROR_MEMORY_MAP_FAILED
    Mapping of a memory object has failed.
* ename:VK_ERROR_LAYER_NOT_PRESENT
    A requested layer is not present or could not be loaded.
* ename:VK_ERROR_EXTENSION_NOT_PRESENT
    A requested extension is not supported.
* ename:VK_ERROR_FEATURE_NOT_PRESENT
    A requested feature is not supported.
* ename:VK_ERROR_INCOMPATIBLE_DRIVER
    The requested version of Vulkan is not supported by the driver or
    is otherwise incompatible for implementation-specific reasons.
* ename:VK_ERROR_TOO_MANY_OBJECTS
    Too many objects of the type have already been created.
* ename:VK_ERROR_FORMAT_NOT_SUPPORTED
    A requested format is not supported on this device.

If a command returns a run time error, it will leave any result pointers
unmodified, unless other behavior is explicitly defined in the specification.

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 (ftext:vkCmd*) run time errors are reported by
fname:vkEndCommandBuffer.

// refEnd VkResult TBD


See Also
--------

No cross-references are available


Document Notes
--------------

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkResult

This page is extracted from the Vulkan Specification.
Fixes and changes should be made to the Specification,not directly.

include::footer.txt[]