Final Platform Layer  0.9.6-beta
Vulkan

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

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;
// Reference of the video settings
fplVideoSettings *videoSettings = &settings.video;
// Forcing the video backend to 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
// ... 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():

// 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:

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
fplVideoSurface::vulkan
fplVideoSurfaceVulkan vulkan
The Vulkan surface properties.
Definition: final_platform_layer.h:6543
fplGraphicsApiSettings::vulkan
fplVulkanSettings vulkan
Vulkan settings.
Definition: final_platform_layer.h:3554
fplVideoBackendType_Vulkan
Vulkan.
Definition: final_platform_layer.h:3454
fplVulkanSettings::userData
void * userData
User data passed to any callbacks.
Definition: final_platform_layer.h:3538
fplVideoSurface
Stores the surface properties for the active video backend.
Definition: final_platform_layer.h:6537
fplVulkanSettings::allocator
const void * allocator
The vulkan allocator (VkAllocationCallbacks)
Definition: final_platform_layer.h:3534
fplVulkanValidationLayerMode_User
Enable validations and use fplVulkanValidationLayerCallback to call back to to the user.
Definition: final_platform_layer.h:3500
fplVulkanSettings::appName
const char * appName
The application name (Only required if fplVulkanSettings::instanceHandle is fpl_null)
Definition: final_platform_layer.h:3528
fplVulkanSettings::validationLayerCallback
fplVulkanValidationLayerCallback * validationLayerCallback
The validation layer callback (Only used when fplVulkanSettings::validationLayerMode is set to fplVul...
Definition: final_platform_layer.h:3536
fplGetVideoSurface
const fpl_common_api fplVideoSurface * fplGetVideoSurface()
Gets the current fplVideoSurface that stores all handles used for the active video backend.
fplSettings
A structure containing settings, such as window, video, etc.
Definition: final_platform_layer.h:3930
fplStructInit
#define fplStructInit
Initializes a struct by the given type.
Definition: final_platform_layer.h:2212
fplVulkanSettings::engineVersion
fplVersionInfo engineVersion
The engine version (Only required if fplVulkanSettings::instanceHandle is fpl_null)
Definition: final_platform_layer.h:3524
fplVideoSettings::backend
fplVideoBackendType backend
video backend type
Definition: final_platform_layer.h:3565
fplVulkanSettings::engineName
const char * engineName
The engine name (Only required if fplVulkanSettings::instanceHandle is fpl_null)
Definition: final_platform_layer.h:3530
fplInitFlags_All
All init flags.
Definition: final_platform_layer.h:3390
fplVulkanSettings
A structure that contains Vulkan video settings.
Definition: final_platform_layer.h:3520
fplPlatformInit
fpl_common_api bool fplPlatformInit(const fplInitFlags initFlags, const fplSettings *initSettings)
Initializes the platform layer.
fplAssert
#define fplAssert(exp)
Breaks with an runtime assertion, when the specified expression evaluates to false.
Definition: final_platform_layer.h:2081
fplVideoSettings::graphics
fplGraphicsApiSettings graphics
Graphics API settings.
Definition: final_platform_layer.h:3563
fplVulkanValidationLayerMode_Logging
Enable validations and print out validations to the FPL logging system.
Definition: final_platform_layer.h:3498
fplVulkanSettings::validationLayerMode
fplVulkanValidationLayerMode validationLayerMode
The fplVulkanValidationLayerMode.
Definition: final_platform_layer.h:3540
fplSettings::video
fplVideoSettings video
Video settings.
Definition: final_platform_layer.h:3934
fplVideoSurfaceVulkan::surfaceKHR
void * surfaceKHR
The Vulkan Surface KHR (VkSurfaceKHR)
Definition: final_platform_layer.h:6489
fplInitFlags_Video
Use a video backbuffer (This flag ensures that fplInitFlags_Window is included always)
Definition: final_platform_layer.h:3384
fplVulkanValidationLayerMode_Disabled
Do not use the validation.
Definition: final_platform_layer.h:3496
fpl_null
#define fpl_null
Null.
Definition: final_platform_layer.h:2166
fplVulkanSettings::apiVersion
fplVersionInfo apiVersion
The preferred Vulkan api version (Only required if fplVulkanSettings::instanceHandle is fpl_null)
Definition: final_platform_layer.h:3526
fplVideoSettings
A structure that contains video settings such as backend, v-sync, API-settings, etc.
Definition: final_platform_layer.h:3561
fplVulkanSettings::appVersion
fplVersionInfo appVersion
The application version (Only required if fplVulkanSettings::instanceHandle is fpl_null)
Definition: final_platform_layer.h:3522
fplVersionInfo
A structure that contains version informations.
Definition: final_platform_layer.h:3178
fplConsoleFormatOut
fpl_common_api void fplConsoleFormatOut(const char *format,...)
Writes the given formatted text to the standard output console buffer.
fplSetDefaultSettings
fpl_common_api void fplSetDefaultSettings(fplSettings *settings)
Resets the given settings container to default values for window, video, audio, etc.