Vulkan

Table of Contents

• Initialize Vulkan
• Create a Vulkan Instance and a Surface
  • Fill in the application, engine and api versions
  • Choose a Vulkan validation mode
• Create a Vulkan Surface from an existing Instance
• Vulkan Usage
• Memory Allocator

Initialize Vulkan

Initializing Vulkan is different than initializing other graphics APIs such as OpenGL, but FPL helps you in the first steps.

The very first thing you need is a Vulkan Instance (VkInstance).

Secondly you require a Vulkan Surface (VkSurfaceKHR) to present the graphical result to the screen.

FPL can create the Instance and the Surface for you.

The surface creation is mandatory, but an exiting instance can optionally be passed to the fplSettings structure if needed.

• Create a Vulkan Instance and a Surface
• Create a Vulkan Surface from an existing Instance

Create a Vulkan Instance and a Surface

First you have to create a fplSettings structure and initialize it with default settings using fplSetDefaultSettings().

Second you set the fplVideoSettings::backend to fplVideoBackendType_Vulkan .

We can reference the fplVulkanSettings type stored in fplGraphicsApiSettings::vulkan for convenience usage later.

fplSettings settings;
fplSetDefaultSettings(&settings);
 
// Reference of the video settings
fplVideoSettings *videoSettings = &settings.video;
 
// Forcing the video backend to Vulkan
videoSettings->backend = fplVideoBackendType_Vulkan;
 
// Reference of the vulkan settings for later usage
fplVulkanSettings *vulkanSettings = &videoSettings.graphics.vulkan;

Fill in the application, engine and api versions

fplVulkanSettings *vulkanSettings = &videoSettings.graphics.vulkan;
 
vulkanSettings->appName = "The name of your application";
vulkanSettings->appVersion = fplStructInit(fplVersionInfo, "1.0.0", "1", "0", "0"); // Version of your application
 
vulkanSettings->engineName = "The name of your engine";
vulkanSettings->engineVersion = fplStructInit(fplVersionInfo, "1.0.0", "1", "0", "0"); // Version of your engine
 
vulkanSettings->apiVersion = fplStructInit(fplVersionInfo, "1.1.0", "1", "1", "0"); // Preferred Vulkan API version (should be greater or equal than 1.1.0)

Choose a Vulkan validation mode

static void VulkanValidationLayerCallback(void *userData, const char *message, const VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity, const VkDebugUtilsMessageTypeFlagsEXT messageType, const VkDebugUtilsMessengerCallbackDataEXT *debugUtilsMessengerCallbackData) {
    fplConsoleFormatOut("Vulkan Validation: %s\n", message);
}
 
fplVulkanSettings *vulkanSettings = &videoSettings.graphics.vulkan;
 
vulkanSettings->validationLayerMode = fplVulkanValidationLayerMode_Disabled; // Do not use the Vulkan Validation Layer as an instance extension
 
// or
vulkanSettings->validationLayerMode = fplVulkanValidationLayerMode_Logging; // Enable Vulkan Validation Layer as an instance extension and log everything to FPL directly, using the FPL logging system
 
// or
vulkanSettings->validationLayerMode = fplVulkanValidationLayerMode_User; // Enable Vulkan Validation Layer as an instance extension and let the user handle the logging
vulkanSettings->validationLayerCallback = VulkanValidationLayerCallback; // The user callback
vulkanSettings->userData = (void *)YourUserData; // The user data passed to the callback

Continue with Vulkan Usage

Create a Vulkan Surface from an existing Instance

If you already have a Vulkan Instance (VkInstance), you can simply pass that to the fplVulkanSettings::instanceHandle field and initialize FPL with fplPlatformInit():

VkInstance yourVulkanInstance;
 
fplVulkanSettings *vulkanSettings = &videoSettings.graphics.vulkan;
 
vulkanSettings->instance = yourVulkanInstance; // Pass in your vulkan instance to FPL
 
if (fplPlatformInit(fplInitFlags_Video, &settings)) {
    // ... Vulkan Surface is created now and are ready to use
}

Continue with Vulkan Usage

Vulkan Usage

After you have created a Vulkan Instance and a Surface, you can query it by calling fplGetVideoSurface() directly after fplPlatformInit():

if (fplPlatformInit(fplInitFlags_All, &settings)) {
    // Get video surface
    const fplVideoSurface *surface = fplGetVideoSurface();
    fplAssert(surface != fpl_null);
    
    // Get the VkInstance and VkSurfaceKHR
    VkInstance instanceHandle = (VkInstance)surface->vulkan.instanceHandle;
    VkSurfaceKHR surfaceHandle = (VkSurfaceKHR)surface->vulkan.surfaceKHR;
    fplAssert(instanceHandle != VK_NULL_HANDLE);
    fplAssert(surfaceHandle != VK_NULL_HANDLE);
 
    // ... continue the Vulkan initialization process
}

After that, the typical Vulkan process continues:

• Finding the physical device (VkPhysicalDevice)
• Creating a logical device (VkDevice)
• Find the right queue families, surface formats, frame buffer formats, etc.
• Creating a VkSwapChainKHR with VkImageView, etc.
• Creating the full pipeline with VkCommandPool, VkCommandBuffer, etc.

See the FPL_Vulkan demo for more details or learn more about Vulkan: Vulkan-Tutorials

Memory Allocator

If you have an existing memory allocator for Vulkan, you can pass that to FPL before calling fplPlatformInit():

VkAllocationCallbacks *yourMemoryAllocator;
 
fplVulkanSettings *vulkanSettings = &videoSettings.graphics.vulkan;
 
vulkanSettings->allocator = (void *)yourMemoryAllocator; // Pass in your memory allocator