vkCreateImage

vkCreateImage is a Vulkan API function used to create an image object on a logical device. An image represents a region of image-backed memory that can be used for textures, render targets, or other image-based resources. The image object is created with a description provided by a VkImageCreateInfo structure and is not bound to device memory at creation; memory binding occurs later with vkBindImageMemory. The created image handle can then be used in subsequent operations such as creating image views or using it in pipelines.

The function takes four parameters: the logical device, a pointer to a VkImageCreateInfo that specifies the image type (1D, 2D, or 3D), format, extent (width, height, depth), mip levels, array layers, samples, tiling, usage flags, sharing mode, queue family indices, and the initial layout of the image; an optional allocation callback structure; and a pointer to a VkImage handle that will receive the created image. The VkImageCreateInfo may also reference additional structures via pNext for extension-specific features.

vkCreateImage returns a VkResult indicating success or failure. On success, VK_SUCCESS is returned and a valid VkImage handle is written to the pImage parameter. On failure, common results include VK_ERROR_OUT_OF_HOST_MEMORY, VK_ERROR_OUT_OF_DEVICE_MEMORY, VK_ERROR_INITIALIZATION_FAILED, or VK_ERROR_TOO_MANY_OBJECTS, among others such as VK_ERROR_DEVICE_LOST or feature- or format-support related errors if the requested configuration is not supported by the device.

Notes and usage considerations: the image must eventually be bound to device memory with vkBindImageMemory, and its properties must be compatible with the intended usage and layout transitions. Proper memory requirements should be queried via vkGetImageMemoryRequirements before allocation. Images are commonly paired with buffers and image views for shader access, sampling, or render pass operations. Related functions include vkDestroyImage for cleanup and vkGetImageMemoryRequirements to determine memory needs.