vulkan

Header: kmsroots/vulkan.h

Table of contents (click to go)

Function Pointers

API Documentation

KMR_VK_INSTANCE_PROC_ADDR

KMR_VK_INSTANCE_PROC_ADDR

Due to Vulkan not directly exposing functions for all platforms. Dynamically (at runtime) retrieve or acquire the address of a VkInstance function. Via token concatenation and String-izing Tokens.

#define KMR_VK_INSTANCE_PROC_ADDR(inst, var, func) \
        do { \
                var = (PFN_vk##func) vkGetInstanceProcAddr(inst, "vk" #func); \
                assert(var); \
        } while(0);

KMR_VK_DEVICE_PROC_ADDR

KMR_VK_DEVICE_PROC_ADDR

Due to Vulkan not directly exposing functions for all platforms. Dynamically (at runtime) retrieve or acquire the address of a VkDevice (logical device) function. Via token concatenation and String-izing Tokens

#define KMR_VK_DEVICE_PROC_ADDR(dev, var, func) \
        do { \
                var = (PFN_vk##func) vkGetDeviceProcAddr(dev, "vk" #func); \
                assert(var); \
        } while(0);

kmr_vk_instance_create_info

struct kmr_vk_instance_create_info

const char *appName;
const char *engineName;
uint32_t enabledLayerCount;
const char **enabledLayerNames;
uint32_t enabledExtensionCount;
const char **enabledExtensionNames;

appName: A member of the VkApplicationInfo structure reserved for the name of the application.
engineName: A member of the VkApplicationInfo structure reserved for the name of the engine

name (if any) used to create application.
enabledLayerCount: A member of the VkInstanceCreateInfo structure used to pass the number of Vulkan

Validation Layers a client wants to enable.
enabledLayerNames: A member of the VkInstanceCreateInfo structure used to pass a pointer to an array

of strings containing the name of the Vulkan Validation Layers one wants to enable.
enabledExtensionCount: A member of the VkInstanceCreateInfo structure used to pass the the number of vulkan

instance extensions a client wants to enable.
enabledExtensionNames: A member of the VkInstanceCreateInfo structure used to pass a pointer to an array

of strings containing the name of the Vulkan Instance Extensions one wants to enable.

kmr_vk_instance_create

VkInstance kmr_vk_instance_create(struct kmr_vk_instance_create_info *kmrvk);

Creates a VkInstance object which allows the Vulkan API to better reference & store object state/data. It also acts as an easy wrapper that allows one to define instance extensions. VkInstance extensions basically allow developers to define what an app is setup to do. So, if a client wants the application to work with wayland surface or X11 surface etc… Client should enable those extensions inorder to gain access to those particular capabilities.

Parameters:: kmrvk

Pointer to a struct kmr_vk_instance_create_info
Returns:: on success: VkInstance

on faliure: VK_NULL_HANDLE

kmr_vk_surface_type

enum kmr_vk_surface_type

KMR_SURFACE_WAYLAND_CLIENT
KMR_SURFACE_XCB_CLIENT

Display server protocol options. ENUM used by kmr_vk_surface_create() to create a VkSurfaceKHR object based upon platform specific information

KMR_SURFACE_WAYLAND_CLIENT: Value set to 0
KMR_SURFACE_XCB_CLIENT: Value set to 1

kmr_vk_surface_create_info

struct kmr_vk_surface_create_info

kmr_vk_surface_type surfaceType;
VkInstance instance;
void *surface;
void *display;
unsigned int window;

surfaceType: Must pass a valid enum kmr_vk_surface_type value. Used in determine what

vkCreate*SurfaceKHR function and associated structs to utilize when creating the

VkSurfaceKHR object.
instance: Must pass a valid VkInstance handle to associate VkSurfaceKHR with a VkInstance.
surface: Must pass a pointer to a struct wl_surface object
display: Must pass either a pointer to struct wl_display object or a pointer to an xcb_connection_t
window: Must pass an xcb_window_t window id or an unsigned int representing XID

kmr_vk_surface_create

VkSurfaceKHR kmr_vk_surface_create(struct kmr_vk_surface_create_info *kmrvk);

Creates a VkSurfaceKHR object based upon platform specific information about the given surface. VkSurfaceKHR are the interface between the window and Vulkan defined images in a given swapchain if vulkan swapchain exists.

Parameters:: kmrvk

Pointer to a struct kmr_vk_surface_create_info
Returns:: on success: VkSurfaceKHR

on faliure: VK_NULL_HANDLE

kmr_vk_phdev

struct kmr_vk_phdev

VkInstance instance;
VkPhysicalDevice physDevice;
VkPhysicalDeviceProperties physDeviceProperties;
VkPhysicalDeviceFeatures physDeviceFeatures;
int kmsfd;
VkPhysicalDeviceDrmPropertiesEXT physDeviceDrmProperties;

instance: Must pass a valid VkInstance handle associated with VkPhysicalDevice.
physDevice: Must pass one of the supported VkPhysicalDeviceType’s.
physDeviceProperties: Structure specifying physical device properties. Like allocation limits for Image

Array Layers or maximum resolution that the device supports.
physDeviceFeatures: Structure describing the features that can be supported by an physical device

Only included if meson option kms set true

kmsfd: KMS device node file descriptor passed via struct kmr_vk_phdev_create_info
physDeviceDrmProperties: Structure containing DRM information of a physical device. A VkPhysicalDeviceProperties2

structure is utilized to populate this member. Member information is then checked by the

implementation to see if passed KMS device node file descriptor

(struct kmr_vk_phdev_create_info { kmsfd }) is equal to the physical device

suggested by (struct kmr_vk_phdev_create_info { deviceType }).

Contains data stored after associating a DRM file descriptor with a vulkan physical device.

kmr_vk_phdev_create_info

struct kmr_vk_phdev_create_info

VkInstance instance;
VkPhysicalDeviceType deviceType;
int kmsfd;

instance: Must pass a valid VkInstance handle which to find VkPhysicalDevice with.
deviceType: Must pass one of the supported VkPhysicalDeviceType’s.

Only included if meson option kms set true

kmsfd: Must pass a valid kms file descriptor for which a VkPhysicalDevice will be created

if corresponding DRM properties match.

kmr_vk_phdev_create

struct kmr_vk_phdev kmr_vk_phdev_create(struct kmr_vk_phdev_create_info *kmrvk);

Retrieves a VkPhysicalDevice handle if certain characteristics of a physical device are meet. Also retrieves a given physical device properties and features to be later used by the application.

Parameters:: kmrvk

Pointer to a struct kmr_vk_phdev_create_info
Returns:: on success: struct kmr_vk_phdev

on failure: struct kmr_vk_phdev { with members nulled, int’s set to -1 }

kmr_vk_queue

struct kmr_vk_queue

char name[20];
VkQueue queue;
int familyIndex;
int queueCount;

name: Stores the name of the queue in string format. Not required by API.
queue: VkQueue handle used when submitting command buffers to physical device. Address

given to handle in kmr_vk_lgdev_create() after VkDevice handle creation.
familyIndex: VkQueue family index associate with selected struct kmr_vk_queue_create_info

{ queueFlag }.
queueCount: Number of queues in a given VkQueue family

kmr_vk_queue_create_info

struct kmr_vk_queue_create_info

VkPhysicalDevice physDevice;
VkQueueFlags queueFlag;

physDevice: Must pass a valid VkPhysicalDevice handle to query queues associate with phsyical device
queueFlag: Must pass one VkQueueFlagBits, if multiple flags are bitwised or’d function will fail

to return VkQueue family index (struct kmr_vk_queue).

kmr_vk_queue_create

struct kmr_vk_queue kmr_vk_queue_create(struct kmr_vk_queue_create_info *kmrvk);

Queries the queues a given physical device contains. Then returns a queue family index and the queue count given a single VkQueueFlagBits. Queue are used in vulkan to submit commands up to the GPU.

Parameters:: kmrvk

Pointer to a struct kmr_vk_queue_create_info
Returns:: on success: struct kmr_vk_queue

on failure: struct kmr_vk_queue { with members nulled, int’s set to -1 }

kmr_vk_lgdev

struct kmr_vk_lgdev

VkDevice logicalDevice;
uint32_t queueCount;
struct kmr_vk_queue *queues;

logicalDevice: Returned VkDevice handle which represents vulkan’s access to physical device
queueCount: Amount of elements in pointer to array of struct kmr_vk_queue. This information

gets populated with the data pass through struct kmr_vk_lgdev_create_info

{ queueCount }.
queues: Pointer to an array of struct kmr_vk_queue. This information gets populated with the

data pass through struct kmr_vk_lgdev_create_info { queues }.

Members queueCount & queues are strictly for struct kmr_vk_lgdev

to have extra information amount VkQueue’s

kmr_vk_lgdev_create_info

struct kmr_vk_lgdev_create_info

VkInstance instance;
VkPhysicalDevice physDevice;
VkPhysicalDeviceFeatures *enabledFeatures;
uint32_t enabledExtensionCount;
const char *const *enabledExtensionNames;
uint32_t queueCount;
struct kmr_vk_queue *queues;

instance: Must pass a valid VkInstance handle to create VkDevice handle from.
physDevice: Must pass a valid VkPhysicalDevice handle to associate VkDevice handle with.
enabledFeatures: Must pass a valid pointer to a VkPhysicalDeviceFeatures with X features enabled
enabledExtensionCount: Must pass the amount of Vulkan Device extensions to enable.
enabledExtensionNames: Must pass an array of strings containing Vulkan Device extension to enable.
queueCount: Must pass the amount of struct kmr_vk_queue { queue, familyIndex } to

create along with a given logical device
queues: Must pass a pointer to an array of struct kmr_vk_queue { queue, familyIndex } to

create along with a given logical device

kmr_vk_lgdev_create

struct kmr_vk_lgdev kmr_vk_lgdev_create(struct kmr_vk_lgdev_create_info *kmrvk);

Creates a VkDevice handle and allows vulkan to have a connection to a given physical device. The VkDevice handle is more of a local object its state and operations are local to it and are not seen by other logical devices. Function also acts as an easy wrapper that allows client to define device extensions. Device extensions basically allow developers to define what operations a given logical device is capable of doing. So, if one wants the device to be capable of utilizing a swap chain, etc… You have to enable those extensions inorder to gain access to those particular capabilities. Allows for creation of multiple VkQueue’s although the only one we needis the Graphics queue.

struct kmr_vk_queue { queue } handle is assigned in this function as vkGetDeviceQueue requires a logical device handle.

Parameters:: kmrvk

Pointer to a struct kmr_vk_lgdev_create_info
Returns:: on success: struct kmr_vk_lgdev

on failure: struct kmr_vk_lgdev { with members nulled, int’s set to -1 }

kmr_vk_swapchain

struct kmr_vk_swapchain

VkDevice logicalDevice;
VkSwapchainKHR swapchain;

logicalDevice: VkDevice handle (Logical Device) that stores VkSwapchainKHR state/data.
swapchain: Vulkan object storing reference to swapchain state/data.

kmr_vk_swapchain_create_info

struct kmr_vk_swapchain_create_info

VkDevice logicalDevice;
VkSurfaceKHR surface;
VkSurfaceCapabilitiesKHR surfaceCapabilities;
VkSurfaceFormatKHR surfaceFormat;
VkExtent2D extent2D;
uint32_t imageArrayLayers;
VkImageUsageFlags imageUsage;
VkSharingMode imageSharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t *queueFamilyIndices;
VkCompositeAlphaFlagBitsKHR compositeAlpha;
VkPresentModeKHR presentMode;
VkBool32 clipped;
VkSwapchainKHR oldSwapChain;

More information can be found at VkSwapchainCreateInfoKHR.

logicalDevice: Must pass a valid VkDevice handle (Logical Device) to associate swapchain state/data with.
surface: Must pass a valid VkSurfaceKHR handle. Can be acquired with a call to

kmr_vk_surface_create()
surfaceCapabilities: Passed the queried surface capabilities. Can be acquired with a call to

kmr_vk_get_surface_capabilities().
surfaceFormat: Pass colorSpace & pixel format of choice. Recommend querrying first via

kmr_vk_get_surface_formats() then check if pixel format and colorSpace

you want is supported by a given physical device.
extent2D: The width and height in pixels of the images in the VkSwapchainKHR.
imageArrayLayers: Number of views in a multiview/stereo surface.
imageUsage: Intended use of images in VkSwapchainKHR.
imageSharingMode: Sets whether images can only be accessed by a single VkQueue or multiple VkQueue’s.
queueFamilyIndexCount: Amount of VkQueue families that may have access to the VkSwapchainKHR images. Only

set if imageSharingMode is not set to VK_SHARING_MODE_EXCLUSIVE.
queueFamilyIndices: Pointer to an array of VkQueue family indices that have access to images in

the VkSwapchainKHR.
compositeAlpha: How to blend images with external graphics.
presentMode: How images are queued and presented internally by the swapchain (FIFO, MAIL_BOX

are the only ones known not to lead to tearing).
clipped: Allow vulkan to clip images not in view. (i.e clip/display part of the image

if it’s behind a window).
oldSwapChain: If a VkSwapchainKHR is still in use while a window is resized passing pointer to old

VkSwapchainKHR may aid in resource (memory) reuse as the application is allowed to

present images already acquired from old VkSwapchainKHR. Thus, no need to waste

memory & clock cycles creating new images.

kmr_vk_swapchain_create

struct kmr_vk_swapchain kmr_vk_swapchain_create(struct kmr_vk_swapchain_create_info *kmrvk);

Creates VkSwapchainKHR object that provides ability to present renderered results to a given VkSurfaceKHR Minimum image count is equal to VkSurfaceCapabilitiesKHR.minImageCount + 1. The VkSwapchainKHR can be defined as a set of images that can be drawn to and presented to a VkSurfaceKHR.

Parameters:: kmrvk

Pointer to a struct kmr_vk_swapchain_create_info
Returns:: on success: struct kmr_vk_swapchain

on failure: struct kmr_vk_swapchain { with members nulled }

kmr_vk_image_handle

struct kmr_vk_image_handle

VkImage image;
VkDeviceMemory deviceMemory[4];
uint8_t deviceMemoryCount;

image: Reference to data about VkImage itself. May be a texture, etc…
deviceMemory: Actual memory buffer whether CPU or GPU visible associate with VkImage object.

If struct kmr_vk_image_create_info { useExternalDmaBuffer } set to true

deviceMemory represents Vulkan API usable memory associated with

external DMA-BUFS.
deviceMemoryCount: The amount of DMA-BUF fds (drmFormatModifierPlaneCount) per VkImage Resource.

kmr_vk_image_view_handle

struct kmr_vk_image_view_handle

VkImageView view;

view: Represents a way to interface with the actual VkImage itself. Describes to the

vulkan api how to interface with a given VkImage. How to read the given image and

exactly what in the image to read (color channels, etc…)

kmr_vk_image

struct kmr_vk_image

VkDevice logicalDevice;
uint32_t imageCount;
struct kmr_vk_image_handle *imageHandles;
struct kmr_vk_image_view_handle *imageViewHandles;
VkSwapchainKHR swapchain;

logicalDevice: VkDevice handle (Logical Device) associated with VkImageView & VkImage objects.
imageCount: Amount of VkImage’s created. If VkSwapchainKHR reference is passed value would

be the amount of images in the given swapchain.
imageHandles: Pointer to an array of VkImage handles.
imageViewHandles: Pointer to an array of VkImageView handles.
swapchain: Member not required, but used for storage purposes. A valid VkSwapchainKHR

reference to the VkSwapchainKHR passed to kmr_vk_image_create.

Represents the swapchain that created VkImage’s.

kmr_vk_image_view_create_info

struct kmr_vk_image_view_create_info

VkImageViewCreateFlags imageViewflags;
VkImageViewType imageViewType;
VkFormat imageViewFormat;
VkComponentMapping imageViewComponents;
VkImageSubresourceRange imageViewSubresourceRange;

More information can be found at VkImageViewCreateInfo.

imageViewflags: Specifies additional prameters associated with VkImageView. Normally set to zero.
imageViewType: Specifies what the image view type is. Specifies coordinate system utilized by the

image when being addressed. imageViewType type must have compatible

VkImageType when VkSwapChainKHR == VK_NULL_HANDLE.
imageViewFormat: Image Format (Bits per color channel, the color channel ordering, etc…).
imageViewComponents: Makes it so that we can select what value goes to what color channel. Basically if we

want to assign red channel value to green channel. Or set all (RGBA) color channel values

to the value at B channel this is how we achieve that.
imageViewSubresourceRange: Gates an image so that only a part of an image is allowed to be viewable.

kmr_vk_vimage_create_info

struct kmr_vk_vimage_create_info

VkImageCreateFlags imageflags;
VkImageType imageType;
VkFormat imageFormat;
VkExtent3D imageExtent3D;
uint32_t imageMipLevels;
uint32_t imageArrayLayers;
VkSampleCountFlagBits imageSamples;
VkImageTiling imageTiling;
VkImageUsageFlags imageUsage;
VkSharingMode imageSharingMode;
uint32_t imageQueueFamilyIndexCount;
const uint32_t *imageQueueFamilyIndices;
VkImageLayout imageInitialLayout;
uint64_t imageDmaBufferFormatModifier;
uint32_t imageDmaBufferCount;
int *imageDmaBufferFds;
const VkSubresourceLayout *imageDmaBufferResourceInfo;
uint32_t *imageDmaBufferMemTypeBits;

More information can be found at VkImageCreateInfo.

imageflags: Bits used to specify additional parameters for a given VkImage.
imageType: Coordinate system the pixels in the image will use when being addressed.
imageFormat: Image Format (Bits per color channel, the color channel ordering, etc…).
imageExtent3D: Dimension (i.e. width, height, and depth) of the given image(s).
imageMipLevels: The number of levels of detail available for minified sampling of the image.
imageArrayLayers: The number of layers in the image.
imageSamples: Bitmask specifying sample counts supported for an image used for storage operations.
imageTiling: Specifies the tiling arrangement (image layout) of data in an image (linear, optimal).
imageUsage: Describes to vulkan the intended usage for the VkImage.
imageSharingMode: Vulkan image may be owned by one device queue family or shared by multiple device

queue families. Sets whether images can only be accessed by a single queue or

multiple queues.
imageQueueFamilyIndexCount: Array size of imageQueueFamilyIndices. Amount of queue families may own given vulkan image.
imageQueueFamilyIndices: Pointer to an array of queue families to associate/own a given vulkan image.
imageInitialLayout: Set the inital memory layout of a VkImage.
imageDmaBufferFormatModifier: A 64-bit, vendor-prefixed, semi-opaque unsigned integer describing vendor-specific details

of an image’s memory layout. Acquired when a call to kmr_buffer_create() is made

and stored in struct kmr_buffer.bufferObjects[0].modifier.
imageDmaBufferCount: Amount of elements in imageDmaBufferFds, imageDmaBufferResourceInfo,

and imageDmaBufferMemTypeBits. Value should be

struct kmr_buffer.bufferObjects[0].planeCount.
imageDmaBufferFds: Array of DMA-BUF fds. Acquired when a call to kmr_buffer_create() is made and

stored in struct kmr_buffer.bufferObjects[0].dmaBufferFds[4].
imageDmaBufferResourceInfo: Info about the DMA-BUF including offset, size, pitch, etc. Most of which is acquired after a

call to kmr_buffer_create() is made and stored in

struct kmr_buffer.bufferObjects[0].{pitches[4], offsets[4], etc..}
imageDmaBufferMemTypeBits: Array of VkMemoryRequirements.memoryTypeBits that can be acquired after a call to

kmr_vk_get_external_fd_memory_properties().

kmr_vk_image_create_info

struct kmr_vk_image_create_info

VkDevice logicalDevice;
VkSwapchainKHR swapchain;
uint32_t imageCount;
struct kmr_vk_image_view_create_info *imageViewCreateInfos;
struct kmr_vk_vimage_create_info *imageCreateInfos;
VkPhysicalDevice physDevice;
VkMemoryPropertyFlagBits memPropertyFlags;
bool useExternalDmaBuffer;

logicalDevice: Must pass a valid VkDevice handle (Logical Device) to associate VkImage/VkImageView

state/data with.
swapchain: Must pass a valid VkSwapchainKHR handle. Used when retrieving references to

underlying VkImage If VkSwapchainKHR reference is not passed value. Application

will need to set amount of VkImage’s/VkImageView’s via imageCount.
imageCount: Must pass amount of VkImage’s/VkImageView’s to create.

if swapchain == VK_NULL_HANDLE set to 0.
imageViewCreateInfos: Pointer to an array of size imageCount containing everything required to create an individual

VkImageView. If a imageCount value given array size must be at least imageCount

in size. If not given array size must equal 1.

Bellow only required if swapchain == VK_NULL_HANDLE

imageCreateInfos: Pointer to an array of size imageCount containing everything required to create an individual

VkImage. If a imageCount value given array size must be at least imageCount in

size. If not given array size must equal 1.
physDevice: Must pass a valid VkPhysicalDevice handle as it is used to query memory properties.
memPropertyFlags: Used to determine the type of actual memory to allocated. Whether CPU (host) or GPU visible.
useExternalDmaBuffer: Set to true if VkImage resources created needs to be associated with an external DMA-BUF created by GBM.

kmr_vk_image_create

struct kmr_vk_image kmr_vk_image_create(struct kmr_vk_image_create_info *kmrvk);

Function creates/retrieve VkImage’s and associates VkImageView’s with said images. If a VkSwapchainKHR reference is passed function retrieves all images in the swapchain and uses that to associate VkImageView objects. If VkSwapchainKHR reference is not passed function creates VkImage object’s given the passed data. Then associates VkDeviceMemory & VkImageView objects with the VkImage. Amount of images created is based upon struct kmr_vk_image_create_info { imageCount }.

Parameters:: kmrvk

Pointer to a struct kmr_vk_image_create_info
Returns:: on success: struct kmr_vk_image

on failure: struct kmr_vk_image { with members nulled }

kmr_vk_shader_module

struct kmr_vk_shader_module

VkDevice logicalDevice;
VkShaderModule shaderModule;
const char *shaderName;

logicalDevice: VkDevice handle (Logical Device) associated with VkShaderModule.
shaderModule: Contains shader code and one or more entry points.
shaderName: Name given to shader module can be safely ignored not required by API.

kmr_vk_shader_module_create_info

struct kmr_vk_shader_module_create_info

VkDevice logicalDevice;
size_t sprivByteSize;
const unsigned char *sprivBytes;
const char *shaderName;

logicalDevice: Must pass a valid VkDevice handle (Logical Device) to associate VkShaderModule

state/data with.
sprivByteSize: Must pass the sizeof SPIR-V byte code
sprivBytes: Must pass pointer to SPIR-V byte code itself
shaderName: Name given to shader module can be safely ignored not required by API.

kmr_vk_shader_module_create

struct kmr_vk_shader_module kmr_vk_shader_module_create(struct kmr_vk_shader_module_create_info *kmrvk);

Function creates VkShaderModule from passed SPIR-V byte code.

Parameters:: kmrvk

Pointer to a struct kmr_vk_shader_module_create_info
Returns:: on success: struct kmr_vk_shader_module

on failure: struct kmr_vk_shader_module { with members nulled }

kmr_vk_pipeline_layout

struct kmr_vk_pipeline_layout

VkDevice logicalDevice;
VkPipelineLayout pipelineLayout;

logicalDevice: VkDevice handle (Logical Device) associated with VkPipelineLayout
pipelineLayout: Stores collection of data describing the vulkan resources that are needed to

produce final image. This data is later used during graphics pipeline runtime.

kmr_vk_pipeline_layout_create_info

struct kmr_vk_pipeline_layout_create_info

VkDevice logicalDevice;
uint32_t descriptorSetLayoutCount;
const VkDescriptorSetLayout *descriptorSetLayouts;
uint32_t pushConstantRangeCount;
const VkPushConstantRange *pushConstantRanges;

More information can be found at VkPipelineLayoutCreateInfo.

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
descriptorSetLayoutCount: Must pass the array size of descriptorSetLayouts
descriptorSetLayouts: Must pass a pointer to an array of descriptor set layouts so a given graphics

pipeline can know how a shader can access a given vulkan resource.
pushConstantRangeCount: Must pass the array size of pushConstantRanges
pushConstantRanges: Must pass a pointer to an array of push constant definitions that describe at what

shader stage and the sizeof the data being pushed to the GPU to be later utilized by

the shader at a given stage. If the shader needs to recieve smaller values quickly

instead of creating a dynamic uniform buffer and updating the value at memory address.

Push constants allow for smaller data to be more efficiently passed up to the GPU by

passing values directly to the shader.

kmr_vk_pipeline_layout_create

struct kmr_vk_pipeline_layout kmr_vk_pipeline_layout_create(struct kmr_vk_pipeline_layout_create_info *kmrvk);

Function creates a VkPipelineLayout handle that is then later used by the graphics pipeline itself so that is knows what vulkan resources are need to produce the final image, at what shader stages these resources will be accessed, and how to access them. Describes the layout of the data that will be given to the pipeline for a single draw operation.

Parameters:: kmrvk

Pointer to a struct kmr_vk_pipeline_layout_create_info
Returns:: on success: struct kmr_vk_pipeline_layout

on failure: struct kmr_vk_pipeline_layout { with members nulled }

kmr_vk_render_pass

struct kmr_vk_render_pass

VkDevice logicalDevice;
VkRenderPass renderPass;

logicalDevice: VkDevice handle (Logical Device) associated with render pass instance
renderPass: Represents a collection of attachments, subpasses, and dependencies between the subpasses

kmr_vk_render_pass_create_info

struct kmr_vk_render_pass_create_info

VkDevice logicalDevice;
uint32_t attachmentDescriptionCount;
const VkAttachmentDescription *attachmentDescriptions;
uint32_t subpassDescriptionCount;
const VkSubpassDescription *subpassDescriptions;
uint32_t subpassDependencyCount;
const VkSubpassDependency *subpassDependencies;

More information can be found at VkRenderPassCreateInfo.

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
attachmentDescriptionCount: Must pass array size of attachmentDescriptions
attachmentDescriptions: Describes the type of location to output fragment data to

Depth attachment outputs to a VkImage used for depth

Color attachment outputs to a VkImage used for coloring insides of a triangle
subpassDescriptionCount: Must pass array size of subpassDescriptions
subpassDescriptions: What type of pipeline attachments are bounded to (Graphics being the one we want) and

the final layout of the image before its presented on the screen.
subpassDependencyCount: Must pass array size of subpassDependencies
subpassDependencies: Pointer to an array of subpass dependencies that define stages in a pipeline where image

transitions need to occur before sending output to framebuffer then later the viewport.

kmr_vk_render_pass_create

struct kmr_vk_render_pass kmr_vk_render_pass_create(struct kmr_vk_render_pass_create_info *kmrvk);

Function creates a VkRenderPass handle that is then later used by the graphics pipeline itself so that is knows how many attachments (color, depth, etc…) there will be per VkFramebuffer, how many samples an attachment has (samples to use for multisampling), and how their contents should be handled throughout rendering operations. Subpasses within a render pass then references the attachments for every draw operations and connects attachments (i.e. VkImage’s connect to a VkFramebuffer) to the graphics pipeline. In short the render pass is the intermediary step between your graphics pipeline and the framebuffer. It describes how you want to render things to the viewport upon render time. Example at render time we wish to color in the center of a triangle. We want to give the appearance of depth to an image.

Parameters:: kmrvk

Pointer to a struct kmr_vk_render_pass_create_info
Returns:: on success: struct kmr_vk_render_pass

on failure: struct kmr_vk_render_pass { with members nulled }

kmr_vk_graphics_pipeline

struct kmr_vk_graphics_pipeline

VkDevice logicalDevice;
VkPipeline graphicsPipeline;

logicalDevice: VkDevice handle (Logical Device) associated with VkPipeline (Graphics Pipeline)
graphicsPipeline: Handle to a pipeline object. Storing what to do during each stage of the graphics pipeline.

kmr_vk_graphics_pipeline_create_info

struct kmr_vk_graphics_pipeline_create_info

VkDevice logicalDevice;
uint32_t shaderStageCount;
const VkPipelineShaderStageCreateInfo *shaderStages;
const VkPipelineVertexInputStateCreateInfo *vertexInputState;
const VkPipelineInputAssemblyStateCreateInfo *inputAssemblyState;
const VkPipelineTessellationStateCreateInfo *tessellationState;
const VkPipelineViewportStateCreateInfo *viewportState;
const VkPipelineRasterizationStateCreateInfo *rasterizationState;
const VkPipelineMultisampleStateCreateInfo *multisampleState;
const VkPipelineDepthStencilStateCreateInfo *depthStencilState;
const VkPipelineColorBlendStateCreateInfo *colorBlendState;
const VkPipelineDynamicStateCreateInfo *dynamicState;
VkPipelineLayout pipelineLayout;
VkRenderPass renderPass;
uint32_t subpass;

More information can be found at VkGraphicsPipelineCreateInfo.

logicalDevice: Must pass a valid VkDevice handle (Logical Device) to associate graphics pipeline

state/data with.
shaderStageCount: Must pass the array size of shaderStages. Amount of shaders being used by

the graphics pipeline.
shaderStages: Defines shaders (via VkShaderModule) and at what shader stages the created VkPipeline

will utilize them.
vertexInputState: Defines the layout and format of vertex input data. Provides details for loading vertex data.

So the graphics pipeline understands how the vertices are stored in the buffer.
inputAssemblyState: Defines how to assemble vertices to primitives (i.e. triangles or lines).

For more info see VkPrimitiveTopology.
tessellationState: TBA
viewportState: VkViewPort defines how to populate image with pixel data (i.e populate only the top half

or bottom half). Scissor defines how to crop an image. How much of image should be drawn

(i.e draw whole image, right half, middle, etc…)
rasterizationState: Handles how raw vertex data turns into cordinates on screen and in a pixel buffer.

Handle computation of fragments (pixels) from primitives (i.e. triangles or lines).
multisampleState: If you want to do clever anti-aliasing through multisampling. Stores multisampling information.
depthStencilState: How to handle depth + stencil data. If a draw has 2 or more objects we don’t want to be

drawing the back object on top of the object that should be in front of it.
colorBlendState: Defines how to blend fragments at the end of the pipeline.
dynamicState: Graphics pipelines settings are static once set they can’t change. To get new settings you’d

have to create a whole new pipeline. There are settings however that can be changed at

runtime. We define which settings here.
pipelineLayout: Pass VkPipelineLayout handle to define the resources (i.e. descriptor sets, push constants)

given to the pipeline for a single draw operation.
renderPass: Pass VkRenderPass handle which holds a pipeline and handles how it is execute. With final

outputs being to a framebuffer. One can have multiple smaller subpasses inside of render

pass. Used to bind a given render pass to the graphics pipeline. Contains multiple

attachments that go to all plausible pipeline outputs (i.e Depth, Color, etc..).
subpass: Pass the index of the subpass to use in the renderPass instance.

kmr_vk_graphics_pipeline_create

struct kmr_vk_graphics_pipeline kmr_vk_graphics_pipeline_create(struct kmr_vk_graphics_pipeline_create_info *kmrvk);

Function creates a VkPipeline handle that references a sequence of operations that first takes raw vertices (points on a coordinate plane), textures coordinates, color coordinates, tangent, etc.. [NOTE: Data combinded is called a mesh]. Utilizes shaders to plot the points on a coordinate system then the rasterizer converts all plotted points and turns it into fragments/pixels for your fragment shader to then color in.

Parameters:: kmrvk

Pointer to a struct kmr_vk_graphics_pipeline_create_info
Returns:: on success: struct kmr_vk_graphics_pipeline

on failure: struct kmr_vk_graphics_pipeline { with members nulled }

kmr_vk_framebuffer_handle

struct kmr_vk_framebuffer_handle

VkFramebuffer framebuffer;

framebuffer: Framebuffers represent a collection of specific memory attachments that a render pass

instance uses. Connection between an image (or images) and the render pass instance.

kmr_vk_framebuffer

struct kmr_vk_framebuffer

VkDevice logicalDevice;
uint8_t framebufferCount;
struct kmr_vk_framebuffer_handle *framebufferHandles;

logicalDevice: VkDevice handle (Logical Device) associated with framebufferCount VkFramebuffer’s.
framebufferCount: Amount of VkFramebuffer handles created.
framebufferHandles: Pointer to an array of VkFramebuffer handles.

kmr_vk_framebuffer_images

struct kmr_vk_framebuffer_images

VkImageView imageAttachments[6];

imageAttachments: Allow at most 6 attachments (VkImageView -> VkImage) per VkFramebuffer.

kmr_vk_framebuffer_create_info

struct kmr_vk_framebuffer_create_info

VkDevice logicalDevice;
uint8_t framebufferCount;
uint8_t framebufferImageAttachmentCount;
struct kmr_vk_framebuffer_images *framebufferImages;
VkRenderPass renderPass;
uint32_t width;
uint32_t height;
uint32_t layers;

More information can be found at VkFramebufferCreateInfo.

logicalDevice: Must pass a valid VkDevice handle (Logical Device).
framebufferCount: Amount of VkFramebuffer handles to create (i.e the array length of framebufferImages)
framebufferImageAttachmentCount: Amount of framebuffer attachments (VkImageView -> VkImage) per VkFramebuffer.
framebufferImages: Pointer to an array of VkImageView handles which the renderPass instance will

merge to create final VkFramebuffer. These VkImageView -> VkImage handles must always

be in a format that equals to the render pass attachment format.
renderPass: Defines the render pass a given framebuffer is compatible with
width: Framebuffer width in pixels
height: Framebuffer height in pixels
layers: TBA

kmr_vk_framebuffer_create

struct kmr_vk_framebuffer kmr_vk_framebuffer_create(struct kmr_vk_framebuffer_create_info *kmrvk);

Creates framebufferCount amount of VkFramebuffer handles. Can think of this function as creating the frames to hold the pictures in them, with each frame only containing one picture. Note framebuffer VkImage’s (framebufferImages -> imageAttachments) must match up one to one with attachments in the VkRenderpass instance. Meaning if are renderPass instance has 1 color + 1 depth attachment. Then each VkFramebuffer must have one VkImage for color and one VkImage for depth.

Parameters:: kmrvk

Pointer to a struct kmr_vk_framebuffer_create_info
Returns:: on success: struct kmr_vk_framebuffer

on failure: struct kmr_vk_framebuffer { with members nulled }

kmr_vk_command_buffer_handle

struct kmr_vk_command_buffer_handle

VkCommandBuffer commandBuffer;

commandBuffer: Handle used to pre-record commands before they are submitted to a device queue and

sent off to the GPU.

kmr_vk_command_buffer

struct kmr_vk_command_buffer

VkDevice logicalDevice;
VkCommandPool commandPool;
uint32_t commandBufferCount;
struct kmr_vk_command_buffer_handle *commandBufferHandles;

logicalDevice: VkDevice handle (Logical Device) associated with VkCommandPool
commandPool: The memory pool which the buffers where allocated from.
commandBufferCount: Amount of VkCommandBuffer’s allocated from memory pool.

Array size of commandBufferHandles.
commandBufferHandles: Pointer to an array of VkCommandBuffer handles

kmr_vk_command_buffer_create_info

struct kmr_vk_command_buffer_create_info

VkDevice logicalDevice;
uint32_t queueFamilyIndex;
uint32_t commandBufferCount;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
queueFamilyIndex: Designates a queue family with VkCommandPool. All command buffers allocated

from VkCommandPool must used same queue.
commandBufferCount: The amount of command buffers to allocate from a given pool

kmr_vk_command_buffer_create

struct kmr_vk_command_buffer kmr_vk_command_buffer_create(struct kmr_vk_command_buffer_create_info *kmrvk);

Function creates a VkCommandPool handle then allocates VkCommandBuffer handles from that pool. The amount of VkCommandBuffer’s allocated is based upon commandBufferCount. Function only allocates primary command buffers. VkCommandPool flags set VK_COMMAND_POOL_CREATE_TRANSIENT_BIT | VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT

Parameters:: kmrvk

Pointer to a struct kmr_vk_command_buffer_create_info
Returns:: on success: struct kmr_vk_command_buffer

on failure: struct kmr_vk_command_buffer { with members nulled }

kmr_vk_command_buffer_record_info

struct kmr_vk_command_buffer_record_info

uint32_t commandBufferCount;
struct kmr_vk_command_buffer_handle *commandBufferHandles;
VkCommandBufferUsageFlagBits commandBufferUsageflags;

commandBufferCount: Array size of commandBufferHandles
commandBufferHandles: Pointer to an array of kmr_vk_command_buffer_handle which contains your

actual VkCommandBuffer handles to start writing commands to.
commandBufferUsageflags: VkCommandBufferUsageFlagBits

kmr_vk_command_buffer_record_begin

int kmr_vk_command_buffer_record_begin(struct kmr_vk_command_buffer_record_info *kmrvk);

Function sets recording command in command buffers up to commandBufferCount. Thus, allowing each command buffer to become writeable. Allowing for the application to write commands into it. Theses commands are later put into a queue to be sent off to the GPU.

Parameters:: kmrvk

Pointer to a struct kmr_vk_command_buffer_record_info
Returns:: on success: 0

on failure: -1

kmr_vk_command_buffer_record_end

int kmr_vk_command_buffer_record_end(struct kmr_vk_command_buffer_record_info *kmrvk);

Function stops command buffer to recording. Thus, ending each command buffers ability to accept commands.

Parameters:: kmrvk

Pointer to a struct kmr_vk_command_buffer_record_info
Returns:: on success: 0

on failure: -1

kmr_vk_fence_handle

struct kmr_vk_fence_handle

VkFence fence;

fence: May be used to insert a dependency from a queue to the host. Used to block host (CPU)

operations until commands in a command buffer are finished. Handles CPU - GPU syncs.

It is up to host to set VkFence to an unsignaled state after GPU set it to a signaled

state when a resource becomes available. Host side we wait for that signal then

conduct XYZ operations. This is how we block.

kmr_vk_semaphore_handle

struct kmr_vk_semaphore_handle

VkSemaphore semaphore;

semaphore: May be used to insert a dependency between queue operations or between a queue

operation and the host. Used to block queue operations until commands in a

command buffer are finished. Handles GPU - GPU syncs. Solely utilized on the

GPU itself. Thus, only the GPU can control the state of a semphore.

kmr_vk_sync_obj

struct kmr_vk_sync_obj

VkDevice logicalDevice;
uint32_t fenceCount;
struct kmr_vk_fence_handle *fenceHandles;
uint32_t semaphoreCount;
struct kmr_vk_semaphore_handle *semaphoreHandles;

logicalDevice: VkDevice handle (Logical Device) associated with fenceCount

VkFence objects and semaphoreCount VkSemaphore
fenceCount: Array size of fenceHandles array
fenceHandles: Pointer to an array of VkFence handles
semaphoreCount: Array size of semaphoreHandles array
semaphoreHandles: Pointer to an array of VkSemaphore handles

kmr_vk_sync_obj_create_info

struct kmr_vk_sync_obj_create_info

VkDevice logicalDevice;
VkSemaphoreType semaphoreType;
uint8_t semaphoreCount;
uint8_t fenceCount;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
semaphoreType: Specifies the type of semaphore to create (VkSemaphoreType).
semaphoreCount: Amount of VkSemaphore objects to allocate.

Initial value of each semaphore is set to zero.
fenceCount: Amount of VkFence objects to allocate.

kmr_vk_sync_obj_create

struct kmr_vk_sync_obj kmr_vk_sync_obj_create(struct kmr_vk_sync_obj_create_info *kmrvk);

Creates VkFence and VkSemaphore synchronization objects. Vulkan API calls that execute work on the GPU happen asynchronously. Vulkan API function calls return before operations are fully finished. So we need synchronization objects to make sure operations that require other operations to finish can happen after.

Parameters:: kmrvk

Pointer to a struct kmr_vk_sync_obj_create_info
Returns:: on success: struct kmr_vk_sync_obj

on failure: struct kmr_vk_sync_obj { with members nulled }

kmr_vk_sync_obj_type

enum kmr_vk_sync_obj_type

KMR_VK_SYNC_OBJ_FENCE
KMR_VK_SYNC_OBJ_SEMAPHORE

KMR_VK_SYNC_OBJ_FENCE: Value set to 0
KMR_VK_SYNC_OBJ_SEMAPHORE: Value set to 1

kmr_vk_sync_obj_handle

union kmr_vk_sync_obj_handle

VkFence fence;
VkSemaphore semaphore;

Lessens memory as only one type of Vulkan synchronization primitive is used at a given time.

fence: See struct kmr_vk_fence_handle
semaphore: See struct kmr_vk_semaphore_handle

kmr_vk_sync_obj_import_external_sync_fd_info

struct kmr_vk_sync_obj_import_external_sync_fd_info

VkDevice logicalDevice;
int syncFd;
kmr_vk_sync_obj_type syncType;
kmr_vk_sync_obj_handle syncHandle;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
syncFd: External Posix file descriptor to import and associate with Vulkan sync object.
syncType: Specifies the type of Vulkan sync object to bind to.
syncHandle: Must pass one valid Vulkan sync object VkFence or VkSemaphore.

kmr_vk_sync_obj_import_external_sync_fd

int kmr_vk_sync_obj_import_external_sync_fd(struct kmr_vk_sync_obj_import_external_sync_fd_info *kmrvk);

From external POSIX DMA-BUF synchronization file descriptor bind to choosen Vulkan synchronization object. The file descriptors can be acquired via a call to kmr_dma_buf_export_sync_file_create().

Parameters:: kmrvk

Pointer to a struct kmr_vk_sync_obj_import_external_sync_fd_info
Returns:: on success: 0

on failure: -1

kmr_vk_sync_obj_export_external_sync_fd_info

struct kmr_vk_sync_obj_export_external_sync_fd_info

VkDevice logicalDevice;
kmr_vk_sync_obj_type syncType;
kmr_vk_sync_obj_handle syncHandle;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
syncType: Specifies the type of Vulkan sync object to bind to.
syncHandle: Must pass one valid Vulkan sync object VkFence or VkSemaphore.

kmr_vk_sync_obj_export_external_sync_fd

int kmr_vk_sync_obj_export_external_sync_fd(struct kmr_vk_sync_obj_export_external_sync_fd_info *kmrvk);

Creates POSIX file descriptor associated with Vulkan synchronization object. This file descriptor can later be associated with a DMA-BUF fd via kmr_dma_buf_import_sync_file_create().

Parameters:: kmrvk

Pointer to a struct kmr_vk_sync_obj_export_external_sync_fd_info
Returns:: on success: POSIX file descriptor associated with Vulkan sync object

on failure: -1

kmr_vk_buffer

struct kmr_vk_buffer

VkDevice logicalDevice;
VkBuffer buffer;
VkDeviceMemory deviceMemory;

logicalDevice: VkDevice handle (Logical Device) associated with VkBuffer
buffer: Header for the given buffer that stores information about the buffer
deviceMemory: Pointer to actual memory whether CPU or GPU visible associated with

VkBuffer header object.

kmr_vk_buffer_create_info

struct kmr_vk_buffer_create_info

VkDevice logicalDevice;
VkPhysicalDevice physDevice;
VkBufferCreateFlagBits bufferFlags;
VkDeviceSize bufferSize;
VkBufferUsageFlags bufferUsage;
VkSharingMode bufferSharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t *queueFamilyIndices;
VkMemoryPropertyFlagBits memPropertyFlags;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
physDevice: Must pass a valid VkPhysicalDevice handle as it is used to

query memory properties.
bufferFlags: Used when configuring sparse buffer memory
bufferSize: Size of underlying buffer to allocate
bufferUsage: Specifies type of buffer (i.e vertex, etc…). Multiple buffer types

can be selected here via bitwise or operations.
bufferSharingMode: Vulkan buffers may be owned by one device queue family or shared by

multiple device queue families.
queueFamilyIndexCount: Must pass array size of queueFamilyIndices. Amount of

queue families may own given VkBuffer.
queueFamilyIndices: Pointer to an array of queue family indices to associate/own a

given VkBuffer.
memPropertyFlags: Used to determine the type of actual memory to allocated.

Whether CPU (host) or GPU visible.

kmr_vk_buffer_create

struct kmr_vk_buffer kmr_vk_buffer_create(struct kmr_vk_buffer_create_info *kmrvk);

Function creates VkBuffer header and binds pointer to actual memory (VkDeviceMemory) to said VkBuffer headers. This allows host visible data (i.e vertex data) to be given to the GPU.

Parameters:: kmrvk

Pointer to a struct kmr_vk_buffer_create_info
Returns:: on success: struct kmr_vk_buffer

on failure: struct kmr_vk_buffer { with members nulled }

kmr_vk_descriptor_set_layout

struct kmr_vk_descriptor_set_layout

VkDevice logicalDevice;
VkDescriptorSetLayout descriptorSetLayout;

logicalDevice: VkDevice handle (Logical Device) associated with VkDescriptorSetLayout
descriptorSetLayout: Describes how a descriptor set connects up to graphics pipeline. The layout

defines what type of descriptor set to allocate, a binding link used by vulkan

to give shader access to resources, and at what graphics pipeline stage

will the shader descriptor need access to a given resource.

kmr_vk_descriptor_set_layout_create_info

struct kmr_vk_descriptor_set_layout_create_info

VkDevice logicalDevice;
VkDescriptorSetLayoutCreateFlags descriptorSetLayoutCreateflags;
uint32_t descriptorSetLayoutBindingCount;
VkDescriptorSetLayoutBinding *descriptorSetLayoutBindings;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
descriptorSetLayoutCreateflags: Options for descriptor set layout
descriptorSetLayoutBindingCount: Must pass the array size of descriptorSetLayoutBindings
descriptorSetLayoutBindings: Pointer to an array of shader variable (descriptor) attributes. Attributes include the

binding location set in the shader, the type of descriptor allowed to be allocated,

and what graphics pipeline stage will shader have access to vulkan resources assoicated

with VkDescriptorSetLayoutBinding { binding }.

kmr_vk_descriptor_set_layout_create

struct kmr_vk_descriptor_set_layout kmr_vk_descriptor_set_layout_create(struct kmr_vk_descriptor_set_layout_create_info *kmrvk);

Function creates descriptor set layout which is used during pipeline creation to define how a given shader may access vulkan resources. Also used during VkDescriptorSet creation to define what type of descriptor to allocate within a descriptor set, binding locate used by both vulkan and shader to determine how shader can access vulkan resources, and at what pipeline stage.

Parameters:: kmrvk

Pointer to a struct kmr_vk_descriptor_set_layout_create_info
Returns:: on success: struct kmr_vk_descriptor_set_layout

on failure: struct kmr_vk_descriptor_set_layout { with members nulled }

kmr_vk_descriptor_set_handle

struct kmr_vk_descriptor_set_handle

VkDescriptorSet descriptorSet;

descriptorSet: Represents a set of descriptors. Descriptors can be defined as resources shared across

draw operations. If there is only one uniform buffer object (type of descriptor) in the

shader then there is only one descriptor in the set. If the uniform buffer object

(type of descriptor) in the shader is an array of size N. Then there are N descriptors

of the same type in a given descriptor set. Types of descriptor sets include Images,

Samplers, uniform…

kmr_vk_descriptor_set

struct kmr_vk_descriptor_set

VkDevice logicalDevice;
VkDescriptorPool descriptorPool;
uint32_t descriptorSetsCount;
struct kmr_vk_descriptor_set_handle *descriptorSetHandles;

logicalDevice: VkDevice handle (Logical Device) associated with VkDescriptorPool which

contains one or more descriptor sets.
descriptorPool: Pointer to a Vulkan Descriptor Pool used to allocate and dellocate descriptor sets.
descriptorSetsCount: Number of descriptor sets in the descriptorSetHandles array
descriptorSetHandles: Pointer to an array of descriptor sets

kmr_vk_descriptor_set_create_info

struct kmr_vk_descriptor_set_create_info

VkDevice logicalDevice;
VkDescriptorPoolSize *descriptorPoolInfos;
uint32_t descriptorPoolInfoCount;
VkDescriptorSetLayout *descriptorSetLayouts;
uint32_t descriptorSetLayoutCount;
VkDescriptorPoolCreateFlags descriptorPoolCreateflags;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
descriptorPoolInfos: Must pass a pointer to an array of descriptor sets information. With each

elements information corresponding to number of descriptors a given pool

needs to allocate and the type of descriptors in the pool. Per my understanding

this is just so the VkDescriptorPool knows what to preallocate. No descriptor

is assigned to a set when the pool is created. Given an array of descriptor

set layouts the actual assignment of descriptor to descriptor set happens in

the vkAllocateDescriptorSets function.
descriptorPoolInfoCount: Number of descriptor sets in pool or array size of descriptorPoolInfos
descriptorSetLayouts: Pointer to an array of VkDescriptorSetLayout. Each set must contain it’s own layout.

This variable must be of same size as descriptorPoolInfos
descriptorSetLayoutCount: Array size of descriptorSetLayouts corresponding to the actual number of descriptor

sets in the pool.
descriptorPoolCreateflags: Enables certain operations on a pool (i.e enabling freeing of descriptor sets)

kmr_vk_descriptor_set_create

struct kmr_vk_descriptor_set kmr_vk_descriptor_set_create(struct kmr_vk_descriptor_set_create_info *kmrvk);

Function allocates a descriptor pool then descriptorPoolInfoCount amount of sets from descriptor pool. This is how we establishes connection between a the shader and vulkan resources at specific graphics pipeline stages. One can think of a descriptor pool as a range of addresses that contain segments or sub range addresses. Each segment is a descriptor set within the pool and each set contains a certain number of descriptors.

Descriptor Pool

Descriptor Set	1	2	3	4
Descriptors	1\|2\|3\|4\|5	1\|2\|3	1	1\|2

Parameters:: kmrvk

Pointer to a struct kmr_vk_descriptor_set_create_info
Returns:: on success: struct kmr_vk_descriptor_set

on failure: struct kmr_vk_descriptor_set { with members nulled }

kmr_vk_sampler

struct kmr_vk_sampler

VkDevice logicalDevice;
VkSampler sampler;

logicalDevice: VkDevice handle (Logical Device) associated with VkSampler
sampler: VkSampler handle represent the state of an image sampler which is used

by the implementation to read image data and apply filtering and other

transformations for the shader.

kmr_vk_sampler_create_info

struct kmr_vk_sampler_create_info

VkDevice logicalDevice;
VkSamplerCreateFlags samplerFlags;
VkFilter samplerMagFilter;
VkFilter samplerMinFilter;
VkSamplerAddressMode samplerAddressModeU;
VkSamplerAddressMode samplerAddressModeV;
VkSamplerAddressMode samplerAddressModeW;
VkBorderColor samplerBorderColor;
VkBool32 samplerAnisotropyEnable;
float samplerMaxAnisotropy;
VkBool32 samplerCompareEnable;
VkCompareOp samplerCompareOp;
VkSamplerMipmapMode samplerMipmapMode;
float samplerMipLodBias;
float samplerMinLod;
float samplerMaxLod;
VkBool32 samplerUnnormalizedCoordinates;

More information can be found at VkSamplerCreateInfo.

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
samplerFlags: TBA
samplerMagFilter: How to render when image is magnified on screen (Camera close to texture)
samplerMinFilter: How to render when image is minimized on screen (Camera further away from texture)
samplerAddressModeU: How to handle texture wrap in U (x) direction
samplerAddressModeV: How to handle texture wrap in V (y) direction
samplerAddressModeW: How to handle texture wrap in W (z) direction
samplerBorderColor: Used if samplerAddressMode{U,V,W} == VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

set border beyond texture.
samplerMipmapMode: Mipmap interpolation mode
samplerMipLodBias: Level of details bias for mip level. Sets value to add to mip levels.
samplerMinLod: Minimum level of detail to pick miplevel
samplerMaxLod: Maximum level of detail to pick miplevel
samplerUnnormalizedCoordinates: Sets if the texture coordinates should be normalized (between 0 and 1)
samplerAnisotropyEnable: Enable/Disable Anisotropy
samplerMaxAnisotropy: Anisotropy sample level
samplerCompareEnable: TBA
samplerCompareOp: TBA

kmr_vk_sampler_create

struct kmr_vk_sampler kmr_vk_sampler_create(struct kmr_vk_sampler_create_info *kmrvk);

Functions creates VkSampler handle this object accesses the image using pre-defined methods. These methods cover concepts such as picking a point between two texels or beyond the edge of the image. Describes how an image should be read.

Loaded images (png, jpg) -> VkImage -> Sampler interacts with the VkImage.

Parameters:: kmrvk

Pointer to a struct kmr_vk_sampler_create_info
Returns:: on success: struct kmr_vk_sampler

on failure: struct kmr_vk_sampler { with members nulled }

kmr_vk_resource_copy_type

enum kmr_vk_resource_copy_type

KMR_VK_RESOURCE_COPY_VK_BUFFER_TO_VK_BUFFER
KMR_VK_RESOURCE_COPY_VK_BUFFER_TO_VK_IMAGE
KMR_VK_RESOURCE_COPY_VK_IMAGE_TO_VK_BUFFER

ENUM Used by struct kmr_vk_resource_copy_info to specify type of source resource to copy over to a given type of destination resource.

KMR_VK_RESOURCE_COPY_VK_BUFFER_TO_VK_BUFFER: Value set to 0
KMR_VK_RESOURCE_COPY_VK_BUFFER_TO_VK_IMAGE: Value set to 1
KMR_VK_RESOURCE_COPY_VK_IMAGE_TO_VK_BUFFER: Value set to 2

kmr_vk_resource_copy_buffer_to_buffer_info

struct kmr_vk_resource_copy_buffer_to_buffer_info

VkBufferCopy *copyRegion;

copyRegion: Specifies the byte offset to use for given

struct kmr_vk_resource_copy_info { srcResource } memory address.

Then, specifies the byte offset to use for given

struct kmr_vk_resource_copy_info { dstResource } memory address.

Along with including the byte size (VkBufferCopy { size }) to copy

from srcResource to dstResource.

kmr_vk_resource_copy_buffer_to_image_info

struct kmr_vk_resource_copy_buffer_to_image_info

VkBufferImageCopy *copyRegion;
VkImageLayout imageLayout;

copyRegion: Specifies the byte offset to use for given

struct kmr_vk_resource_copy_info { srcResource } memory address.

Along with specifying what portion of the (dstResource) image to update or copy

given srcResource.

VkBufferImageCopy.
imageLayout: Memory layout of the destination image subresources after the copy

kmr_vk_resource_copy_info

struct kmr_vk_resource_copy_info

kmr_vk_resource_copy_type resourceCopyType;
void *resourceCopyInfo;
VkCommandBuffer commandBuffer;
VkQueue queue;
void *srcResource;
void *dstResource;

resourceCopyType: Determines what vkCmdCopyBuffer* function to utilize
resourceCopyInfo: The structs to pass to vkCmdCopyBuffer*
commandBuffer: Command buffer used for recording. Best to utilize one already create via

kmr_vk_command_buffer_create(). To save on unnecessary allocations.
queue: The physical device queue (graphics or transfer) to submit the copy buffer command to.
srcResource: Pointer to source vulkan resource containing raw data.

(i.e Vkbuffer, VkImage, etc…)
dstResource: Pointer to destination vulkan resource to copy srcResource data to.

(i.e Vkbuffer, VkImage, etc…)

kmr_vk_resource_copy

int kmr_vk_resource_copy(struct kmr_vk_resource_copy_info *kmrvk);

Function copies data from one vulkan resource to another. Best utilized when copying data from CPU visible buffer over to GPU visible buffer. That way the GPU can acquire data (vertex data) more quickly.

Parameters:: kmrvk

Pointer to a struct kmr_vk_resource_copy_info
Returns:: on success: 0

on failure: -1

kmr_vk_resource_pipeline_barrier_info

struct kmr_vk_resource_pipeline_barrier_info

VkCommandBuffer commandBuffer;
VkQueue queue;
VkPipelineStageFlags srcPipelineStage;
VkPipelineStageFlags dstPipelineStage;
VkDependencyFlags dependencyFlags;
VkMemoryBarrier *memoryBarrier;
VkBufferMemoryBarrier *bufferMemoryBarrier;
VkImageMemoryBarrier *imageMemoryBarrier;

commandBuffer: Command buffer used for recording. Best to utilize one already create via

kmr_vk_command_buffer_create(). To save on unnecessary allocations.
queue: The physical device queue (graphics or transfer) to submit the pipeline

barrier command to.
srcPipelineStage: Specifies in which pipeline stage operations occur before the barrier.
dstPipelineStage: Specifies in which pipeline stage operations will wait on the barrier.
dependencyFlags: Defines types of dependencies
memoryBarrier: Specifies pipeline barrier for vulkan memory
bufferMemoryBarrier: Specifies pipeline barrier for vulkan buffer resource
imageMemoryBarrier: Specifies pipeline barrier for vulkan image resource

kmr_vk_resource_pipeline_barrier

int kmr_vk_resource_pipeline_barrier(struct kmr_vk_resource_pipeline_barrier_info *kmrvk);

Function is used to synchronize access to vulkan resources. Basically ensuring that a write to a resources finishes before reading from it.

Parameters:: kmrvk

Pointer to a struct kmr_vk_resource_pipeline_barrier_info
Returns:: on success: 0

on failure: -1

kmr_vk_get_surface_capabilities

VkSurfaceCapabilitiesKHR kmr_vk_get_surface_capabilities(VkPhysicalDevice physDev, VkSurfaceKHR surface);

Populates the VkSurfaceCapabilitiesKHR struct with supported GPU device surface capabilities. Queries what a physical device is capable of supporting for any given surface.

Parameters:: physDev

Must pass a valid VkPhysicalDevice handle.

surface

Must pass a valid VkSurfaceKHR handle.
Returns:: Populated VkSurfaceCapabilitiesKHR

kmr_vk_surface_format

struct kmr_vk_surface_format

uint32_t surfaceFormatCount;
VkSurfaceFormatKHR *surfaceFormats;

surfaceFormatCount: Amount of color formats a given surface supports. Array size of surfaceFormats.
surfaceFormats: Pointer to a array of VkSurfaceFormatKHR which stores color space and pixel format

kmr_vk_get_surface_formats

struct kmr_vk_surface_format kmr_vk_get_surface_formats(VkPhysicalDevice physDev, VkSurfaceKHR surface);

Creates block of memory with all supported color space’s and pixel formats a given physical device supports for any given surface. Application must free struct kmr_vk_surface_format { surfaceFormats }.

Parameters:: physDev

Must pass a valid VkPhysicalDevice handle

surface

Must pass a valid VkSurfaceKHR handle
Returns:: on success: struct kmr_vk_surface_format

on failure: struct kmr_vk_surface_format { with members nulled }

kmr_vk_surface_present_mode

struct kmr_vk_surface_present_mode

uint32_t presentModeCount;
VkPresentModeKHR *presentModes;

presentModeCount: Amount of present modes a given surface supports. Array size of presentModes.
presentModes: Pointer to an array of VkPresentModeKHR which stores values of potential surface present modes.

kmr_vk_get_surface_present_modes

struct kmr_vk_surface_present_mode kmr_vk_get_surface_present_modes(VkPhysicalDevice physDev, VkSurfaceKHR surface);

Creates block of memory with all supported presentation modes for a surface Application must free struct kmr_vk_surface_present_mode { presentModes } More information on presentation modes can be found here: VkPresentModeKHR

Parameters:: physDev

Must pass a valid VkPhysicalDevice handle

surface

Must pass a valid VkSurfaceKHR handle
Returns:: on success: struct kmr_vk_surface_present_mode

on failure: struct kmr_vk_surface_present_mode { with members nulled }

kmr_vk_phdev_format_prop

struct kmr_vk_phdev_format_prop

VkFormatProperties *formatProperties;
uint32_t formatPropertyCount;

formatProperties: Pointer to an array of type (VkFormatProperties) specifying a given image format (VkFormat) properties
formatPropertyCount: The amount of elements contained in formatProperties array

kmr_vk_phdev_format_prop_info

struct kmr_vk_phdev_format_prop_info

VkPhysicalDevice physDev;
VkFormat *formats;
uint32_t formatCount;
VkDrmFormatModifierPropertiesEXT *modifierProperties;
uint32_t modifierCount;

physDev: Must pass a valid VkPhysicalDevice handle
formats: Must pass a pointer to an array of type VkFormat to get VkFormatProperties from
formatCount: Must pass the amount of elements in formats array
modifierProperties: The properties of a format when combined with a DRM format modifier

kmr_buffer_create() and stored in struct kmr_buffer.bufferObjects[0].modifier
modifierCount: Array size of modifierProperties. Value may be acquired after a call to

kmr_buffer_create and stored in struct kmr_buffer.bufferObjects[0].planeCount

kmr_vk_get_phdev_format_properties

struct kmr_vk_phdev_format_prop kmr_vk_get_phdev_format_properties(struct kmr_vk_phdev_format_prop_info *kmrvk);

Queries a given physical device supported format properties Application must free struct kmr_vk_phdev_format_prop { formatProperties }

Parameters:: kmrvk

Pointer to a struct kmr_vk_phdev_format_prop_info
Returns:: on success: struct kmr_vk_phdev_format_prop

on failure: struct kmr_vk_phdev_format_prop { with members nulled }

kmr_vk_get_external_semaphore_properties

VkExternalSemaphoreProperties kmr_vk_get_external_semaphore_properties(VkPhysicalDevice physDev, VkExternalSemaphoreHandleTypeFlagBits handleType);

Function returns a given physical device external semaphore handle capabilities.

Parameters:: physDev

Must pass a valid VkPhysicalDevice handle

handleType:

Must pass bitwise or value specifying the external semaphore

handle type for which capabilities/properties will be returned.

See: VkExternalSemaphoreHandleTypeFlagBits
Returns:: Populated VkExternalSemaphoreProperties

kmr_vk_get_external_fd_memory_properties

uint32_t kmr_vk_get_external_fd_memory_properties(VkDevice logicalDevice, int externalMemoryFd, VkExternalMemoryHandleTypeFlagBits handleType);

Get Properties of External Memory File Descriptors

Parameters:: logicalDevice

Must pass a valid VkDevice handle (Logical Device)

externalMemoryFd

File descriptor to externally create memory.

handleType

Describes the type of file descriptor externalMemoryFd is.

See: VkExternalMemoryHandleTypeFlagBits
Returns:: on success: VkMemoryFdPropertiesKHR { memoryTypeBits }

on failure: UINT32_MAX

kmr_vk_memory_export_external_fd_info

struct kmr_vk_memory_export_external_fd_info

VkDevice logicalDevice;
VkDeviceMemory deviceMemory;
VkExternalMemoryHandleTypeFlagBits handleType;

logicalDevice: Must pass a valid VkDevice handle (Logical Device)
deviceMemory: Must pass a valid VkDeviceMemory handle to retrieve POSIX file descriptor.
handleType: Type of file descriptor to create from deviceMemory

kmr_vk_memory_export_external_fd

int kmr_vk_memory_export_external_fd(struct kmr_vk_memory_export_external_fd_info *kmrvk);

Creates POSIX file descriptor associated with a VkDeviceMemory object. VkDeviceMemory objects are associated with the actual memory whether CPU or GPU visible. VkBuffer, VkImage headers need to be backed by VkDeviceMemory. Application must call close(2) on resulting file descriptor.

Parameters:: kmrvk

Pointer to a struct kmr_vk_memory_export_external_fd_info
Returns:: on success: POSIX file descriptor associated with VkDeviceMemory

on failure: -1

kmr_vk_memory_map_info

struct kmr_vk_memory_map_info

VkDevice logicalDevice;
VkDeviceMemory deviceMemory;
VkDeviceSize deviceMemoryOffset;
VkDeviceSize memoryBufferSize;
const void *bufferData;

logicalDevice: Must pass a valid VkDevice handle (Logical Device). The device associated with deviceMemory.
deviceMemory: Pointer to Vulkan API created memory associated with logicalDevice
deviceMemoryOffset: Byte offset within deviceMemory buffer
memoryBufferSize: Byte size of the data to copy over.
bufferData: Pointer to memory to copy into deviceMemory at deviceMemoryOffset

kmr_vk_memory_map

void kmr_vk_memory_map(struct kmr_vk_memory_map_info *kmrvk);

Function maps bytes of buffer data from application generated buffer to Vulkan generated buffer. So, that the Vulkan api can have better understanding and control over data it utilizes.

NOTE:

Use sparingly as consistently mapping and unmapping memory is very inefficient. Try to avoid utilizing in render loops. Although that’s how it’s written in multiple kmsroots examples.

Parameters:: kmrvk

Pointer to a struct kmr_vk_memory_map_info