Struct VulkanSettingsDecisionMaker

Struct Documentation

struct inexor::vulkan_renderer::VulkanSettingsDecisionMaker

This class makes automatic decisions about setting up Vulkan. Examples:

  • Which graphics card will be used if more than one is available?

  • Which surface color format should be used?

  • Which graphics card’s queue families should be used?

  • Which presentation modes should be used?

Public Static Functions

static std::size_t rate_graphics_card(VkPhysicalDevice graphics_card)

Rate a graphics card by its features.

Todo:

Implement additional graphics card rating criteria if desired.

Note

The current implementation just sums up all available memory as a score.

Parameters

graphics_card – The graphics card which will be rated.

Returns

The graphics card’s score which is greater or equal to 0.

static bool is_graphics_card_suitable(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Automatically decide if a graphics card is suitable for this application’s purposes. In order to be a suitable graphics card for Inexor’s purposes, it must fulfill the following criteria:

  • It must support a swapchain.

  • It must support presentation.

    Todo:

    Add more checks to the validation mechanism if necessary, e.h. check for geometry shader support.

Warning

When implementing additional graphics card suitability criteria, do not return false for graphics cards which are not VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU!

Parameters

graphics_card – The graphics card which will be checked for suitability.

Returns

true if the graphics card is suitable.

static VkPhysicalDeviceType graphics_card_type(VkPhysicalDevice graphics_card)

Gets the VkPhysicalDeviceType of a graphics card.

Parameters

graphics_card – The graphics card.

Returns

The type of the graphics card.

static std::optional<VkPhysicalDevice> graphics_card(VkInstance vulkan_instance, VkSurfaceKHR surface, std::optional<std::uint32_t> preferred_gpu_index = std::nullopt)

Automatically select the best graphics card considering all available ones. Please take a look at Inexor’s advanced device selection mechanism which is build into this method. If there is only one graphics card available, we don’t have a choice and must try that one. The user can manually specify which graphics card will be used with command line argument gpu <index>. Please note that the graphics cards index starts with 0.

Parameters
  • vulkan_instance – A pointer to the Vulkan instance handle.

  • surface – The selected (window) surface.

  • preferred_graphics_card_index – The preferred graphics card (by array index).

Returns

A physical device which was chosen if a suitable one could be found, std::nullopt otherwise.

static std::uint32_t swapchain_image_count(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Automatically decide how many images will be used in the swap chain.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The number of images that will be used in swap chain.

static std::optional<VkSurfaceFormatKHR> swapchain_surface_color_format(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Automatically decide which surface color to use in swapchain.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The surface format for swapchain if any could be determined, std::nullopt otherwise.

static SwapchainSettings swapchain_extent(VkPhysicalDevice graphics_card, VkSurfaceKHR surface, std::uint32_t window_width, std::uint32_t window_height)

Automatically decide which width and height to use as swapchain extent.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

  • window_width – The width of the window.

  • window_height – The height of the window.

static VkSurfaceTransformFlagsKHR image_transform(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Automatically find the image transform, relative to the presentation engine’s natural orientation, applied to the image content prior to presentation.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The image transform flags.

static std::optional<VkCompositeAlphaFlagBitsKHR> find_composite_alpha_format(VkPhysicalDevice selected_graphics_card, VkSurfaceKHR surface)

Find a supported composite alpha format.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The composite alpha flag bits.

static std::optional<VkPresentModeKHR> decide_present_mode(VkPhysicalDevice graphics_card, VkSurfaceKHR surface, bool vsync = false)

Automatically decide which presentation mode the presentation engine will be using.

Note

We can only use presentation modes that are available in the current system. The preferred presentation mode is VK_PRESENT_MODE_MAILBOX_KHR.

Warning

Just checking whether swap extension is supported is not enough because presentation support is a queue family property! A physical device may support swap chains, but that doesn’t mean that all its queue families also support it.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

  • vsync – True if vertical synchronization is desired, false otherwise.

Returns

The presentation mode which will be used by the presentation engine.

static std::optional<std::uint32_t> find_graphics_queue_family(VkPhysicalDevice graphics_card)

Decide which graphics queue family index to use in case it is not possible to use one for both graphics and presentation.

Warning

This function should only be used when it is not possible to use one queue family for both graphics and presentation!

Parameters

graphics_card – The selected graphics card.

Returns

The index of the queue family which can be used for graphics.

static std::optional<std::uint32_t> find_presentation_queue_family(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Decide which presentation queue family index to use in case it is not possible to use one for both graphics and presentation.

Warning

This function should only be used when it is not possible to use one queue family for both graphics and presentation!

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The index of the queue family which can be used for presentation.

static std::optional<std::uint32_t> find_queue_family_for_both_graphics_and_presentation(VkPhysicalDevice graphics_card, VkSurfaceKHR surface)

Check if there is a queue family (index) which can be used for both graphics and presentation.

Parameters
  • graphics_card – The selected graphics card.

  • surface – The selected (window) surface.

Returns

The queue family index which can be used for both graphics and presentation (if existent), std::nullopt otherwise.

static std::optional<std::uint32_t> find_distinct_data_transfer_queue_family(VkPhysicalDevice graphics_card)

Find a queue family which has VK_QUEUE_TRANSFER_BIT, but not VK_QUEUE_GRAPHICS_BIT.

Warning

It might be the case that there is no distinct queue family available on your system! This means that find_distinct_data_transfer_queue_family must be called to find any queue family which has VK_QUEUE_TRANSFER_BIT (besides other flags).

Parameters

graphics_card – The selected graphics card.

Returns

The index of the queue family which can be used exclusively for data transfer.

static std::optional<std::uint32_t> find_any_data_transfer_queue_family(VkPhysicalDevice graphics_card)

Find a queue family which supports VK_QUEUE_TRANSFER_BIT.

Warning

You should try to find a distinct queue family first using find_distinct_data_transfer_queue_family! Distinct queue families have VK_QUEUE_TRANSFER_BIT, but not VK_QUEUE_GRAPHICS_BIT. It is very likely that the queue family which can be found using this method has VK_QUEUE_GRAPHICS_BIT as well. This could result in suboptimal use of queues which could decrease performance.

Parameters

graphics_card – The selected graphics card.

Returns

The index of the queue family which can be used for data transfer.

Returns

A queue family index which can be used for data transfer if any could be found, std::nullopt otherwise.

static std::optional<VkFormat> find_depth_buffer_format(VkPhysicalDevice graphics_card, const std::vector<VkFormat> &formats, VkImageTiling tiling, VkFormatFeatureFlags feature_flags)

Find a suitable depth buffer format.

Parameters
  • graphics_card – The selected graphics card.

  • formats – The depth buffer formats to check for.

  • tiling – The desired depth buffer’s image tiling.

  • feature_flags – The desired depth buffer’s feature flags.

Returns

A VkFormat value if a suitable depth buffer format could be found, std::nullopt otherwise.