V-EZ API Documentation

V-EZ is designed to be a C based light-weight layer around Vulkan which maintains mostly identical semantics but abstracts away the lower level complexities. The motivation behind this design is to accelerate adoption of Vulkan among software vendors outside of the gaming industry, who desire modern graphics API features without all of the low level responsibilities.

The following is a short list of low level Vulkan API features and responsibilities which are abstracted in V-EZ and no longer a concern of the application.

Below is a diagram of the Vulkan API objects and their interactions.

The next image is a diagram of V-EZ. Notice the number of native Vulkan objects which are abstracted and whose responsibility is removed from the application.

V-EZ incurs only slight overhead compared to native Vulkan API calls. However in most cases the performance overhead is negligible. Existing best practices with respect to Vulkan are still applicable with V-EZ. These include, but are not limited to:

Most object handles created by V-EZ are the native Vulkan objects. These can be used in native Vulkan. There are only a few exceptions, which are prefixed with vez rather than vk. These object handles may only be passed to V-EZ.

Any native Vulkan API functions that do not exist within V-EZ may be used with Vulkan object handles returned by V-EZ.

The first step to using V-EZ is to create a VkInstance object by calling vezCreateInstance with appropriate parameter values set in VezInstanceCreateInfo and VezApplicationInfo. These structures allow an application to pass information about itself to V-EZ. Below is a simple example call.

As with Vulkan, instance layers and extensions can be enabled by passing the relevant string names to VezInstanceCreateInfo::ppEnabledLayerNames and VezInstanceCreateInfo::ppEnabledExtensionNames. For example, to enable the LunarG standard validation layer, the above code would be modified to be the following below.

The vezEnumerateInstanceExtensionProperties and vezEnumerateInstanceLayerProperties may be used to enumerate available instance extensions and layers. The behavior is identical to native Vulkan. For more information about vkCreateInstance and instance layers and extensions, see the Vulkan spec.

A VkInstance object is destroyed by calling VezDestroyInstance when an application terminates.

V-EZ does not abstract or wrap creation of surfaces in Vulkan. Applications must use the platform specific WSI Vulkan extensions to create the surface. See the Vulkan spec for details.

To retrieve a list of physical devices in the system, call vezEnumeratePhysicalDevices, which behaves identically to its counterpart in Vulkan. Physical device properties and features can be retrieved via vezGetPhysicalDeviceProperties and vezGetPhysicalDeviceFeatures. The following code snippet demonstrates enumerating all available physical devices in a system and their properties and features.

Device objects represent logical connections to physical devices (see the Vulkan spec). An application must create separate device object handles for each physical device it will use. vezCreateDevice is used to create a logical connection to a physical device.

An application may specify a list of device level extensions to enable (see the Vulkan spec) by populating vezCreateDeviceInfo::ppEnabledExtensionNames. Device level layers can be enabled by populating vezCreateDeviceInfo::ppEnabledLayerNames. The code snippet below demonstrates creating a device with the VK_KHR_swapchain extension enabled.

To determine if a physical device supports a particular surface format, call vezGetPhysicalDeviceSurfaceFormats. This will retrieve an array of VkFormat and VkColorSpace values which can be used to check for required compatibility, for example HDR10. In some cases a surface attached to a window handle may not support being presented to, or may only support present with a specific queue family index (see Queues). This can be determined by calling vezGetPhysicalDevicePresentSupport.

After enumerating supported image formats and color spaces for a given physical device, an application can create one or more swapchains in V-EZ by calling vezCreateSwapchain with appropriate parameters for VezSwapchainCreateInfo. In contrast to Vulkan, V-EZ manages most of the responsibilities of an application’s swapchain.

If the format specified in VezSwapchainCreateInfo was not supported, V-EZ will choose a default one. An application may query the final image format by calling vezGetSwapchainSurfaceFormat.

Below is a coding listing demonstrating each preceeding section.

As discussed in the Vulkan spec, each physical device may have one or more queue families. A physical device’s queue families can be queried with vezGetPhysicalDeviceQueueFamilyProperties. The returned VkQueueFamilyProperties array contains the following fields:

In V-EZ there is no need to explicitly create or request the different queue families. By default, all queue families and the maximum counts are created and accessible to the application. An application can obtain VkQueue handles to each queue family by calling vezGetDeviceQueue with the desired queueFamilyIndex and queueIndex, which must be less than queueCount obtained in VkQueueFamilyProperties. Utility functions are also provided to explicitly request the graphics, compute or transfer queue families.

VkQueue handles do not need to be explicitly destroyed by the application.

Queue submission behavior and syntax in V-EZ is nearly identical to Vulkan. An application fills in a VezSubmitInfo structure as described in the Vulkan spec. Please see 4.3.5 Queue Submission for detailed information on this topic.

The primary differences are with respect to semaphores and fences. In V-EZ, semaphores and fences are never explicitly created by an application. Instead an application requests them to be created when calling VezQueueSubmit by passing valid, uninitialized, object handles to VezSubmitInfo::pSignalSemaphores and the final pFence parameter of VezQueueSubmit. V-EZ will allocate the objects and store them in these handles. An application is responsible for calling vezDestroyFence for any VkFence object handle returned by V-EZ. As in Vulkan, an application must ensure any queue submission has completed and the VkFence object has been signaled before deletion.

For semaphores returned by V-EZ, an application may only pass them to proceeding calls to VezQueueSubmit as wait semaphores. V-EZ will ensure the object handles are properly destroyed after the queue submission completes. External semaphores created by native Vulkan may be passed to V-EZ via VezSubmitInfo::pWaitSemaphores.

More on semaphores and fences will be discussed in Synchronization.

V-EZ alleviates most of the responsibility for managing the Vulkan swapchain from the application. The only operation an application must perform to display a rendered image to a window is call vezQueuePresent with the VezPresentInfo parameter correctly set. The semantics of VezPresentInfo differ quite a bit from Vulkan’s VkPresentInfoKHR. Namely, in V-EZ an application presents a VkImage object handle rather than specifying the image index of the Vulkan swapchain. Furthermore, V-EZ allows an application to specify signal semaphores in VezPresentInfo which can be used to determine when the VkImage object handle is no longer in use.

More than one swapchain may be presented in a single call. The pImages array must contains the same number of entries as pSwapchains.

The code listing below demonstrates presenting an image the application has rendered into, specifying a single wait semaphore from a previous queue submission and retrieving a signal semaphore.

As described in the Vulkan spec, fences are a synchronization primitive that can be used between a queue and the host. In Vulkan, a fence is either signaled, after the execution of a queue submission, or unsignaled after being reset. In V-EZ, fences are never reset. Once a fence is requested, its status may be queried via vezGetFenceStatus or waited on with vezWaitForFences. An application must call vezDestroyFence when the object is no longer used.

Semaphores are a synchronization primitive used to insert dependencies between queue submissions within the same queue or between different queues. Like fences, semaphores can be signaled or unsignaled. For a more detailed explanation of semaphores, see the Vulkan spec.

An application may obtain semaphore objects when calling vkQueueSubmit or vkQueuePresent. In both cases, the semaphores are set to be signaled when either operation completes and may be passed as wait semaphores to a proceeding queue submission or present operation. In V-EZ, semaphores are never explicitly destroyed by the application, rather once they are passed as wait semaphores to a proceeding queue operation, the application no longer maintains ownership. See the previous code listing in Queue Presentation.

The only exception to this behavior is if a semaphore created by VEZ is then passed as a wait semaphore to a native Vulkan queue submission. In this case, the application must call vezDestroySemaphore once the native Vulkan queue submission completes and the semaphore has been waited on.

Events in V-EZ have identical behavior and operation as in Vulkan. See the Vulkan spec for more information.

Wait idle operations in V-EZ have identical behavior and operation as in Vulkan. See the Vulkan spec for more information.

Shader modules represent the different shader stages of a pipeline. In Vulkan shader modules can only be created from SPIR-V binaries. However V-EZ allows shader module creation from both SPIR-V and GLSL source. To create a shader module, vezCreateShaderModule is called with VezShaderModuleCreateInfo specifying the stage and GLSL source or SPIR_V binary. The behavior and syntax remain largely the same as Vulkan, with the exception of added GLSL support. The code listing below shows a shader module being created from GLSL source.

The VezShaderModuleCreateInfo::pEntryPoint field is only required when creating a shader module from GLSL source. For more information on shader modules, please see the Vulkan spec.

To create a graphics pipeline, call vezCreateGraphicsPipeline with an array of VezPipelineShaderStageCreateInfo entries, one for each shader stage the pipeline will use. The code listing below assumes vertex and fragment shader modules have already been created.

The VezPipelineShaderStageCreateInfo::pEntryPoint allows an application to re-specify alternate entry points for a shader module. This is useful in the case where a single shader module contains multiple entry points for a given shader stage and used between more than one pipeline.

Compute pipelines are created with a single VezPipelineShaderStageCreateInfo object and a call to vezCreateComputePipeline.

Specialization constants in V-EZ work the same as they do in Vulkan. An application sets VezPipelineShaderStageCreateInfo::pSpecializationInfo accordingly. For more information on specialization constants, please see the Vulkan spec.

Push constants are a "high speed path to modify constant data in pipelines that is expected to out perform memory-backed resource updates". For more information on push constants, please see the Vulkan spec.

V-EZ simplifies the use of push constants by only requiring an application call vezCmdPushConstants to update the memory, requiring only an offset, size and pointer to host data to update the push constants memory with. A valid pipeline must be bound before calling vezCmdPushConstants.

In the case where multiple shader stages within a pipeline define push constants at different byte offsets, an application may query these offsets and sizes with V-EZ’s pipeline reflection described in the next section.

Unlike Vulkan, V-EZ allows full pipeline shader stage reflection if the shader stages were created from GLSL source, or the SPIR-V binary source contains the relevant meta-data. To enumerate all pipeline resources call vezEnumeratePipelineResources, which returns an array of VkPipelineResource entries.

The stages field is a bitmask of all shader stages the resource is used in. For example, a the same uniform buffer binding might be bound and accessed in both the vertex and fragment shader stages.

The resourceType field specifies one of the following values:

The baseType field specifies the data type. For GLSL vec4, baseType would be VEZ_PIPELINE_RESOURCE_BASE_TYPE_FLOAT for example.

The access field specifies whether the resource has read and/or write access.

The set and binding fields specify the set number and binding point in the shader as declared in the GLSL source or SPIR-V binary. For additional information on this, please see the GLSL Guide at the end of this document.

For shader stage inputs and outputs, the location field specifies the location binding. Examples include fragment stage output, inputs and outputs between shader stages, etc.

For renderpass subpasses, the inputAttachmentIndex specifies the index the attachment is bound to.

The vecSize field specifies the number of components. If the shader resource is vec3, vecSize will equal 3. For scalar pipeline resources, vecSize will be 1.

The 'arraySize' field specifies the number of elements in the pipeline resource’s array declaration. For example, in the code listing below, the arraySize would be 10.

The 'offset' and 'size' specify the byte offset and byte size of a resource when declared inside of a struct.

If an application knows the name of the pipeline resource to query, vkGetPipelineResource may be used.

For uniform and shader storage buffer objects, the pMembers field forms a multi-level linked list of members of these structured bindings. See the PipelineReflection sample for how to iterate over these.

Graphics pipelines must be bound between vezCmdBeginRenderPass and vezCmdEndRenderPass calls. Compute pipelines must be bound outside of a render pass. To bind a pipeline, call vezCmdBindPipeline.

An application now only needs to manage vertex input formats at the mesh or object level. V-EZ moves the specification of the VkVertexInputBindingDescription and VkVertexInputAttributeDescription arrays to the VkVertexInputFormat object creation. In the code listing below, a vertex input format is created specifying a single binding point and two vertex attributes.

The rules and semantics of specifying VkVertexInputBindingDescription and VkVertexInputAttributeDescription follow the same rules as specified in the Vulkan spec.

When an application no longer requires a VezVertexInputFormat it should be destroyed by calling vezDestroyVertexInputFormat.

Buffers are represented by VkBuffer handles and created by calling vkCreateBuffer. The code listing below demonstrates creating a buffer to be used for staging, or data transfers optimized for host to device.

The application must always specify the intended usage for a buffer using the VezBufferUsageFlagBits enumeration values. In the code listing above, the buffer is only used as a source for data transfers.

Like Vulkan, V-EZ allows an application to specify an array of queue family indices the buffer will be used with. If an application sets queueFamilyIndexCount to 0, V-EZ defaults the buffer to being accessible to all queue families.

When a VkBuffer handle is no longer used by an application, it should be destroyed with vezDestroyBuffer.

Creating buffer views from buffers has nearly identical syntax to Vulkan. An application calls vezCreateBufferView with appropriate values for fields in VezBufferViewCreateInfo. Buffer views are destroyed by calling vezDestroyBufferView. For more information on buffer views, see the Vulkan spec.

Images are represented by VkImage handles and created by calling vezCreateImage. Like buffers, VezMemoryFlags is passed to vezCreateImage allowing an application to specify how the memory will be used and where the it should reside. The syntax and behavior of vezCreateImage and VezImageCreateInfo in V-EZ are nearly identical to Vulkan, see the Vulkan spec for more information.

As with buffers, if the queueFamilyIndexCount in VezImageCreateInfo is set to 0, then V-EZ assumes the image will be used with all available queue families.

See the Vulkan spec for more information on image views. The behavior and syntax in V-EZ is nearly identical to Vulkan.

In Vulkan, an application must specify an array of VkImageView attachments, a compatible Render Pass, and the dimensions when creating a framebuffer. V-EZ simplifies this to only requiring the array of attachments and the dimensions. Render passes are never explicitly created by applications V-EZ (see Render Passes), and therefore are not required when creating a framebuffer.

The coding listing below demonstrates creating a simple framebuffer from a color and depth image. Note that the usage parameter for the color image has the VK_IMAGE_USAGE_TRANSFER_SRC_BIT set. This is required for any image presented to a window when calling vezQueuePresent.

Framebuffers are destroyed by calling vezDestroyFramebuffer.

To create a command buffer an application calls vezAllocateCommandBuffers. The intended queue the command buffer will be used on must be specified.

A command buffer must be destroyed by calling vezFreeCommandBuffers.

An application may begin recording commands to a VkCommandBuffer handle by calling vezBeginCommandBuffer. The only required parameter is VkCommandBufferUsageFlags which gives hints to the driver about how it will be used. See the Vulkan spec for more details. Unlike native Vulkan, V-EZ’s equivalent command buffer functions do not require the VkCommandBuffer handle be passed in. Rather, all vezCmd* functions are associated with the VkCommandBuffer passed to vezBeginCommandBuffer within the same application thread. Commands recorded across threads must indepdently call vezBeginCommandBuffer. An application ends recording by calling vezEndCommandBuffer.

Like Vulkan, an application must wait for a previously submitted VkCommandBuffer object handle to not be in use before re-recording. Applications should track queue submissions with fences and query the fence status, or wait, before re-recording commands. See fences under Synchronization.

As described in Pipelines, V-EZ removes all graphics state specification from pipeline creation. In V-EZ, graphics state is set dynamically while recording a command buffer. Furthermore, all available dynamic states from Vulkan are enabled by default and their corresponding command buffer functions made available in V-EZ. States are not required to be set within a render pass. The following is a list of states available to be set.

An application is not required to set these, as V-EZ sets default values when an application calls vezBeginCommandBuffer. The following tables list the default values for each state.

All state blocks are set together, therefore default values must still be set when the application only needs to set a single field. For example, when enabling backface culling, the polygonMode should still be set. The code listing below demonstrates setting setting the viewport, expected primitive topology and enabling backface culling and depth testing.

In Vulkan descriptor sets are required for binding resources to different bindings for use in a pipeline. The complexities of descriptor set layouts, descriptor pools and updating descriptor set objects has been abstracted away in V-EZ. Instead a simplified interface of explicitly binding buffers, bufferViews, and images to set and binding indices during command buffer recording is exposed. These bindings are persistent only with a command buffer, but maintain persistence across pipeline bindings.

Each binding function for different resource types requires the set number, binding, and array element index. The following functions are available for binding each resource type.

vkCmdBindImageView allows an application to specify a sampler alongside the image view. When sampler is VK_NULL_HANDLE, the binding represents a sampled image or texture2D in GLSL. When sample is not VK_NULL_HANDLE, it represents a combined image sampler or 'sampler2D' in GLSL. See 13.1.3 Sampled Image in the Vulkan spec for more details.

To begin a render pass, an application may call vkCmdBeginRenderPass. The VezRenderPassBeginInfo structure requires a target framebuffer to be specified, an array of VezAttachmentReference structures which define load operations, store operations and clear values. The code listing below demonstrates beginning a render pass with two attachments, namely a single color attachment and a depth stencil attachment. Both attachments are cleared and any values written by the fragment shader stage stored.

By default, calling vkCmdBeginRenderPass starts the first subpass. To transition to a proceeding one, an application may call vezCmdNextSubpass. No parameters are required except the command buffer the call is being recorded to.

As previously stated, V-EZ determines which framebuffer attachments are written to within each subpass based on the pipeline objects that are bound and draw calls made.

To end a render pass, call vezCmdEndRenderPass.

Vulkan allows framebuffer attachments to be used as inputs or outputs within a render pass. One subpass may write to a color attachment while a proceeding subpass may read from it. V-EZ infers this information from the bound pipeline shader stages, specifically the GLSL subpassInput uniform type (see 13.1.11. Input Attachment in the Vulkan spec for more details. In the code snippet below, the first subpass outputs to two attachments for color and surface normals.

In the next subpass, the framebuffer attachment storing the normals, index 1, is bound as an input attachment within the shader.

The input_attachment_index value used in the shader should match the index of the attachment when the framebuffer was created. In V-EZ these must be absolute indices. The same applies for the location index for output attachments.

V-EZ exposes map and unmap operations for VkBuffer handles only. An application must ensure that the target VkBuffer handle was created with the correct VezMemoryFlags. The VEZ_MEMORY_GPU_ONLY is the only enumeration value which cannot be mapped.

To map and unmap a buffer, an application calls VezMapBuffer and vezUnmapBuffer. Care must be taken to call vezFlushMappedBufferRanges to guarantee writes by the host are made available to the device. The behavior remains nearly indentical to Vulkan’s vkMapMemory function. See the Vulkan spec for more details.

V-EZ simplifies host to device data transfers by providing two utility functions. Both are synchronous function calls on the host and block the calling thread until completion.