funnel-vk.h File Reference

libfunnel Vulkan API integration More...

#include "funnel.h"
#include <vulkan/vulkan.h>

Go to the source code of this file.

Functions
int	funnel_stream_init_vulkan (struct funnel_stream *stream, VkInstance instance, VkPhysicalDevice physical_device, VkDevice device)
	Set up a stream for Vulkan integration.
int	funnel_stream_vk_set_usage (struct funnel_stream *stream, VkImageUsageFlagBits usage)
	Set the required buffer usage.
int	funnel_stream_vk_add_format (struct funnel_stream *stream, VkFormat format, bool alpha, VkFormatFeatureFlagBits features)
	Add a supported Vulkan format.
int	funnel_buffer_get_vk_image (struct funnel_buffer *buf, VkImage *pimage)
	Get the VkImage for a Funnel buffer.
int	funnel_buffer_get_vk_format (struct funnel_buffer *buf, VkFormat *pformat, bool *phas_alpha)
	Get the VkFormat for a Funnel buffer.
int	funnel_buffer_get_vk_semaphores (struct funnel_buffer *buf, VkSemaphore *pacquire, VkSemaphore *prelease)
	Get the VkSemaphores for acquiring and releasing the buffer.
int	funnel_buffer_get_vk_fence (struct funnel_buffer *buf, VkFence *pfence)
	Get the VkFence that must be signaled by the queue batch.

Detailed Description

libfunnel Vulkan API integration

See test-vk.c for a usage example.

Required Vulkan device extensions

For Vulkan 1.2+:

• VK_KHR_external_semaphore_fd
• VK_KHR_external_memory_fd
• VK_EXT_external_memory_dma_buf
• VK_EXT_image_drm_format_modifier

In addition, for Vulkan 1.1:

• VK_KHR_image_format_list

In addition, for Vulkan 1.0:

• VK_KHR_external_memory
• VK_KHR_maintenance1
• VK_KHR_bind_memory2
• VK_KHR_sampler_ycbcr_conversion
• VK_KHR_get_memory_requirements2
• VK_KHR_external_semaphore

Required Vulkan device extensions

For Vulkan 1.1+:

No extensions required.

In addition, for Vulkan 1.0:

• VK_KHR_get_physical_device_properties2
• VK_KHR_external_memory_capabilities
• VK_KHR_external_semaphore_capabilities

Function Documentation

funnel_stream_init_vulkan()

int funnel_stream_init_vulkan	(	struct funnel_stream *	stream,
		VkInstance	instance,
		VkPhysicalDevice	physical_device,
		VkDevice	device )

Set up a stream for Vulkan integration.

[Synchronization: external]

Parameters

stream	Stream [Lifetime: borrowed]
instance	VkInstance to use for the stream [Lifetime: borrowed-by stream]
physical_device	VkPhysicalDevice to use for the stream [Lifetime: borrowed-by stream]
device	VkDevice to use for the stream [Lifetime: borrowed-by stream]

Returns

0 on success, or a negative error number on error.

Return values

-EEXIST	The API was already initialized once
-EOPNOTSUPP	Missing Vulkan extensions
-EPROTONOSUPPORT	GPU driver not supported (PipeWire version too old)
-ENODEV	Could not locate DRM render node GBM or Vulkan initialization failed

Examples

test-vk.c.

funnel_stream_vk_set_usage()

int funnel_stream_vk_set_usage	(	struct funnel_stream *	stream,
		VkImageUsageFlagBits	usage )

Set the required buffer usage.

This will control the usage for images allocated by libfunnel.

funnel_stream_vk_add_format() will fail if the requested usages are not available. In this case, you may reconfigure the usage and try again.

[Synchronization: external]

Parameters

stream	Stream [Lifetime: borrowed]
usage	Required VkImageUsageFlagBits.

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL

Invalid argument API is not Vulkan

Examples

test-vk.c.

funnel_stream_vk_add_format()

int funnel_stream_vk_add_format	(	struct funnel_stream *	stream,
		VkFormat	format,
		bool	alpha,
		VkFormatFeatureFlagBits	features )

Add a supported Vulkan format.

Must be called in preference order (highest to lowest). Only some formats are supported by libfunnel:

• VK_FORMAT_R8G8B8A8_SRGB
• VK_FORMAT_R8G8B8A8_UNORM
• VK_FORMAT_B8G8R8A8_SRGB
• VK_FORMAT_B8G8R8A8_UNORM

The corresponding UNORM variants are also acceptable, and equivalent. funnel_buffer_get_vk_format will always return the SRGB formats. If you need UNORM (because you are doing sRGB/gamma conversion in your shader), you can use UNORM constants when you create a VkImageView.

[Synchronization: external]

Parameters

stream	Stream [Lifetime: borrowed]
format	VkFormat
alpha	Whether alpha is meaningful or ignored
features	Required VkFormatFeatureFlagBits. Adding a format will fail if the requested features are not available.

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL	Invalid argument API is not Vulkan
-EOPNOTSUPP	VkFormat is not supported by libfunnel
-ENOENT	VkFormat is not supported by the device or not usable

Examples

test-vk.c.

funnel_buffer_get_vk_image()

int funnel_buffer_get_vk_image	(	struct funnel_buffer *	buf,
		VkImage *	pimage )

Get the VkImage for a Funnel buffer.

The VkImage is only valid while buf is dequeued, or before the destroy callback is used (if you use buffer callbacks).

[Synchronization: external]

Parameters

	buf	Buffer [Lifetime: borrowed]
[out]	pimage	VkImage for the buffer [Lifetime: borrowed-from buf]

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL

Invalid argument API is not Vulkan

Examples

test-vk.c.

funnel_buffer_get_vk_format()

int funnel_buffer_get_vk_format	(	struct funnel_buffer *	buf,
		VkFormat *	pformat,
		bool *	phas_alpha )

Get the VkFormat for a Funnel buffer.

[Synchronization: external]

Parameters

	buf	Buffer [Lifetime: borrowed]
[out]	pformat	VkFormat for the buffer
[out]	phas_alpha	Boolean indicating whether alpha is enabled

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL	Invalid argument API is not Vulkan
-EIO	Format is unsupported (internal error)

funnel_buffer_get_vk_semaphores()

int funnel_buffer_get_vk_semaphores	(	struct funnel_buffer *	buf,
		VkSemaphore *	pacquire,
		VkSemaphore *	prelease )

Get the VkSemaphores for acquiring and releasing the buffer.

The user must wait on the acquire VkSemaphore object before accessing the buffer, and signal the release VkSemaphore after accessing the buffer. These semaphores are valid while the buffer is dequeued.

[Synchronization: external]

Parameters

	buf	Buffer [Lifetime: borrowed]
[out]	pacquire	Acquire VkSemaphore [Lifetime: borrowed-from buf]
[out]	prelease	Release VkSemaphore [Lifetime: borrowed-from buf]

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL	Invalid argument API is not Vulkan
-EBUSY	Already called once for this buffer
-EIO	Failed to import acquire semaphore into Vulkan

Examples

test-vk.c.

funnel_buffer_get_vk_fence()

int funnel_buffer_get_vk_fence	(	struct funnel_buffer *	buf,
		VkFence *	pfence )

Get the VkFence that must be signaled by the queue batch.

The user must pass this fence to vkQueueSubmit() (or similar), such that it is signaled when all operations on the buffer are complete. This fence is valid while the buffer is dequeued.

[Synchronization: external]

Parameters

	buf	Buffer [Lifetime: borrowed]
[out]	pfence	Completion VkFence [Lifetime: borrowed-from buf]

Returns

0 on success, or a negative error number on error.

Return values

-EINVAL	Invalid argument API is not Vulkan
-EBUSY	Already called once for this buffer

Examples

test-vk.c.