From 70fda3ff780ac2eb197c3f2879df549fe999d23b Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Thu, 11 Apr 2019 16:52:54 +1000 Subject: [PATCH] vulkan: large docs update --- gst-libs/gst/vulkan/gstvkbuffermemory.c | 43 +++++++--- gst-libs/gst/vulkan/gstvkbuffermemory.h | 2 +- gst-libs/gst/vulkan/gstvkbufferpool.c | 6 +- gst-libs/gst/vulkan/gstvkcommandpool.c | 24 ++++++ gst-libs/gst/vulkan/gstvkcommandpool.h | 4 +- gst-libs/gst/vulkan/gstvkdevice.c | 106 +++++++++++++++++++++++- gst-libs/gst/vulkan/gstvkdevice.h | 9 +- gst-libs/gst/vulkan/gstvkdisplay.c | 95 ++++++++++++++++++--- gst-libs/gst/vulkan/gstvkdisplay.h | 24 ++++-- gst-libs/gst/vulkan/gstvkerror.c | 23 ++++- gst-libs/gst/vulkan/gstvkfence.c | 27 ++++++ gst-libs/gst/vulkan/gstvkfence.h | 6 +- gst-libs/gst/vulkan/gstvkimagememory.c | 70 +++++++++++++++- gst-libs/gst/vulkan/gstvkimagememory.h | 14 ++-- gst-libs/gst/vulkan/gstvkinstance.c | 73 +++++++++++++++- gst-libs/gst/vulkan/gstvkmemory.c | 29 +++++-- gst-libs/gst/vulkan/gstvkmemory.h | 4 +- gst-libs/gst/vulkan/gstvkqueue.c | 57 ++++++++++++- gst-libs/gst/vulkan/gstvkqueue.h | 3 +- gst-libs/gst/vulkan/gstvkutils.c | 91 +++++++++++++++++++- gst-libs/gst/vulkan/gstvkutils.h | 2 +- gst-libs/gst/vulkan/gstvkwindow.c | 75 +++++++++++++++-- gst-libs/gst/vulkan/gstvkwindow.h | 3 +- gst-libs/gst/vulkan/meson.build | 2 +- gst-libs/gst/vulkan/vulkan_fwd.h | 6 -- 25 files changed, 711 insertions(+), 87 deletions(-) diff --git a/gst-libs/gst/vulkan/gstvkbuffermemory.c b/gst-libs/gst/vulkan/gstvkbuffermemory.c index 0490c10578..dc9e7f0b38 100644 --- a/gst-libs/gst/vulkan/gstvkbuffermemory.c +++ b/gst-libs/gst/vulkan/gstvkbuffermemory.c @@ -26,11 +26,11 @@ /** * SECTION:vkbuffermemory - * @title: vkbuffermemory + * @title: GstVulkanBufferMemory * @short_description: memory subclass for Vulkan buffer memory - * @see_also: #GstMemory, #GstAllocator + * @see_also: #GstVulkanMemory, #GstMemory, #GstAllocator * - * GstVulkanBufferMemory is a #GstMemory subclass providing support for the + * #GstVulkanBufferMemory is a #GstMemory subclass providing support for the * mapping of Vulkan device memory. */ @@ -336,14 +336,18 @@ _vk_buffer_mem_free (GstAllocator * allocator, GstMemory * memory) /** * gst_vulkan_buffer_memory_alloc: - * @device:a #GstVulkanDevice - * @memory_type_index: the Vulkan memory type index - * @params: a #GstAllocationParams - * @size: the size to allocate + * @device: a #GstVulkanDevice + * @format: the format for the buffer + * @size: size of the new buffer + * @usage: buffer usage flags + * @mem_prop_flags: memory properties flags for the backing memory * - * Allocated a new #GstVulkanBufferMemory. + * Allocate a new #GstVulkanBufferMemory. * - * Returns: a #GstMemory object backed by a vulkan device memory + * Returns: (transfer full): a #GstMemory object backed by a vulkan buffer + * backed by vulkan device memory + * + * Since: 1.18 */ GstMemory * gst_vulkan_buffer_memory_alloc (GstVulkanDevice * device, VkFormat format, @@ -357,6 +361,21 @@ gst_vulkan_buffer_memory_alloc (GstVulkanDevice * device, VkFormat format, return (GstMemory *) mem; } +/** + * gst_vulkan_buffer_memory_wrapped: + * @device: a #GstVulkanDevice + * @buffer: a #VkBuffer + * @format: the #VkFormat of @buffer + * @usage: usage flags of @buffer + * @user_data: (allow-none): user data to call @notify with + * @notify: (allow-none): a #GDestroyNotify called when @buffer is no longer in use + * + * Allocated a new wrapped #GstVulkanBufferMemory with @buffer. + * + * Returns: (transfer full): a #GstMemory object backed by a vulkan device memory + * + * Since: 1.18 + */ GstMemory * gst_vulkan_buffer_memory_wrapped (GstVulkanDevice * device, VkBuffer buffer, VkFormat format, VkBufferUsageFlags usage, gpointer user_data, @@ -402,8 +421,10 @@ gst_vulkan_buffer_memory_allocator_init (GstVulkanBufferMemoryAllocator * /** * gst_vulkan_buffer_memory_init_once: * - * Initializes the Vulkan memory allocator. It is safe to call this function + * Initializes the Vulkan buffer memory allocator. It is safe to call this function * multiple times. This must be called before any other #GstVulkanBufferMemory operation. + * + * Since: 1.18 */ void gst_vulkan_buffer_memory_init_once (void) @@ -429,6 +450,8 @@ gst_vulkan_buffer_memory_init_once (void) * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstVulkanBufferMemory + * + * Since: 1.18 */ gboolean gst_is_vulkan_buffer_memory (GstMemory * mem) diff --git a/gst-libs/gst/vulkan/gstvkbuffermemory.h b/gst-libs/gst/vulkan/gstvkbuffermemory.h index d00ba6fbda..d15aa8c59e 100644 --- a/gst-libs/gst/vulkan/gstvkbuffermemory.h +++ b/gst-libs/gst/vulkan/gstvkbuffermemory.h @@ -41,7 +41,7 @@ GType gst_vulkan_buffer_memory_allocator_get_type(void); #define GST_VULKAN_BUFFER_MEMORY_ALLOCATOR_CAST(obj) ((GstVulkanBufferMemoryAllocator *)(obj)) #define GST_VULKAN_BUFFER_MEMORY_ALLOCATOR_NAME "VulkanBuffer" -#define GST_CAPS_FEATURE_MEMORY_VULKAN_BUFFER "memory:" GST_VULKAN_BUFFER_MEMORY_ALLOCATOR_NAME +#define GST_CAPS_FEATURE_MEMORY_VULKAN_BUFFER "memory:VulkanBuffer" struct _GstVulkanBufferMemory { diff --git a/gst-libs/gst/vulkan/gstvkbufferpool.c b/gst-libs/gst/vulkan/gstvkbufferpool.c index 86acb34a32..d55a1b5bfb 100644 --- a/gst-libs/gst/vulkan/gstvkbufferpool.c +++ b/gst-libs/gst/vulkan/gstvkbufferpool.c @@ -198,9 +198,11 @@ mem_create_failed: /** * gst_vulkan_buffer_pool_new: - * @context: the #GstGLContext to use + * @device: the #GstVulkanDevice to use * - * Returns: a #GstBufferPool that allocates buffers with #GstGLMemory + * Returns: (transfer full): a #GstBufferPool that allocates buffers with #GstGLMemory + * + * Since: 1.18 */ GstBufferPool * gst_vulkan_buffer_pool_new (GstVulkanDevice * device) diff --git a/gst-libs/gst/vulkan/gstvkcommandpool.c b/gst-libs/gst/vulkan/gstvkcommandpool.c index 1272f01b41..e9814c9566 100644 --- a/gst-libs/gst/vulkan/gstvkcommandpool.c +++ b/gst-libs/gst/vulkan/gstvkcommandpool.c @@ -24,6 +24,13 @@ #include "gstvkcommandpool.h" +/** + * SECTION:vkcommandpool + * @title: GstVulkanCommandPool + * @short_description: Vulkan command pool + * @see_also: #GstVulkanDevice + */ + #define GST_CAT_DEFAULT gst_vulkan_command_pool_debug GST_DEBUG_CATEGORY (GST_CAT_DEFAULT); @@ -63,6 +70,14 @@ gst_vulkan_command_pool_dispose (GObject * object) G_OBJECT_CLASS (parent_class)->dispose (object); } +/** + * gst_vulkan_command_pool_get_queue + * @pool: a #GstVulkanCommandPool + * + * Returns: (transfer full): the parent #GstVulkanQueue for this command pool + * + * Since: 1.18 + */ GstVulkanQueue * gst_vulkan_command_pool_get_queue (GstVulkanCommandPool * pool) { @@ -71,6 +86,15 @@ gst_vulkan_command_pool_get_queue (GstVulkanCommandPool * pool) return pool->queue ? gst_object_ref (pool->queue) : NULL; } +/** + * gst_vulkan_command_pool_create: (skip) + * @pool: a #GstVulkanCommandPool + * @error: a #GError + * + * Returns: a new primary VkCommandBuffer + * + * Since: 1.18 + */ VkCommandBuffer gst_vulkan_command_pool_create (GstVulkanCommandPool * pool, GError ** error) { diff --git a/gst-libs/gst/vulkan/gstvkcommandpool.h b/gst-libs/gst/vulkan/gstvkcommandpool.h index cb7c7ae254..4332a90953 100644 --- a/gst-libs/gst/vulkan/gstvkcommandpool.h +++ b/gst-libs/gst/vulkan/gstvkcommandpool.h @@ -1,6 +1,6 @@ /* * GStreamer - * Copyright (C) 2015 Matthew Waters + * Copyright (C) 2019 Matthew Waters * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -21,7 +21,7 @@ #ifndef __GST_VULKAN_COMMAND_POOL_H__ #define __GST_VULKAN_COMMAND_POOL_H__ -#include +#include #define GST_TYPE_VULKAN_COMMAND_POOL (gst_vulkan_command_pool_get_type()) #define GST_VULKAN_COMMAND_POOL(o) (G_TYPE_CHECK_INSTANCE_CAST((o), GST_TYPE_VULKAN_COMMAND_POOL, GstVulkanCommandPool)) diff --git a/gst-libs/gst/vulkan/gstvkdevice.c b/gst-libs/gst/vulkan/gstvkdevice.c index 0017416e11..b76b1f0e36 100644 --- a/gst-libs/gst/vulkan/gstvkdevice.c +++ b/gst-libs/gst/vulkan/gstvkdevice.c @@ -26,6 +26,15 @@ #include +/** + * SECTION:vkdevice + * @title: GstVulkanDevice + * @short_description: Vulkan device + * @see_also: #GstVulkanInstance + * + * A #GstVulkanDevice encapsulates a VkDevice + */ + #define GST_CAT_DEFAULT gst_vulkan_device_debug GST_DEBUG_CATEGORY (GST_CAT_DEFAULT); GST_DEBUG_CATEGORY_STATIC (GST_CAT_CONTEXT); @@ -44,6 +53,14 @@ G_DEFINE_TYPE_WITH_CODE (GstVulkanDevice, gst_vulkan_device, GST_TYPE_OBJECT, "Vulkan Device"); GST_DEBUG_CATEGORY_GET (GST_CAT_CONTEXT, "GST_CONTEXT")); +/** + * gst_vulkan_device_new: + * @instance: the parent #GstVulkanInstance + * + * Returns: (transfer full): a new #GstVulkanDevice + * + * Since: 1.18 + */ GstVulkanDevice * gst_vulkan_device_new (GstVulkanInstance * instance) { @@ -139,6 +156,17 @@ _physical_device_info (GstVulkanDevice * device, GError ** error) return TRUE; } +/** + * gst_vulkan_device_open: + * @device: a #GstVulkanDevice + * @error: a #GError + * + * Attempts to create the internal #VkDevice object. + * + * Returns: whether a vulkan device could be created + * + * Since: 1.18 + */ gboolean gst_vulkan_device_open (GstVulkanDevice * device, GError ** error) { @@ -290,6 +318,16 @@ error: } } +/** + * gst_vulkan_device_get_queue: + * @device: a #GstVulkanDevice + * @queue_family: a queue family to retrieve + * @queue_i: index of the family to retrieve + * + * Returns: (transfer full): a new #GstVulkanQueue + * + * Since: 1.18 + */ GstVulkanQueue * gst_vulkan_device_get_queue (GstVulkanDevice * device, guint32 queue_family, guint32 queue_i) @@ -313,6 +351,16 @@ gst_vulkan_device_get_queue (GstVulkanDevice * device, guint32 queue_family, return ret; } +/** + * gst_vulkan_device_foreach_queue: + * @device: a #GstVulkanDevice + * @func: (scope call): a #GstVulkanDeviceForEachQueueFunc to run for each #GstVulkanQueue + * @user_data: (closure func): user data to pass to each call of @func + * + * Iterate over each queue family available on #GstVulkanDevice + * + * Since: 1.18 + */ void gst_vulkan_device_foreach_queue (GstVulkanDevice * device, GstVulkanDeviceForEachQueueFunc func, gpointer user_data) @@ -334,6 +382,17 @@ gst_vulkan_device_foreach_queue (GstVulkanDevice * device, } } +/** + * gst_vulkan_device_get_proc_address: + * @device: a #GstVulkanDevice + * @name: name of the function to retrieve + * + * Performs vkGetDeviceProcAddr() with @device and @name + * + * Returns: the function pointer for @name or %NULL + * + * Since: 1.18 + */ gpointer gst_vulkan_device_get_proc_address (GstVulkanDevice * device, const gchar * name) @@ -347,6 +406,14 @@ gst_vulkan_device_get_proc_address (GstVulkanDevice * device, return vkGetDeviceProcAddr (device->device, name); } +/** + * gst_vulkan_device_get_instance: + * @device: a #GstVulkanDevice + * + * Returns: (transfer full): the #GstVulkanInstance used to create this @device + * + * Since: 1.18 + */ GstVulkanInstance * gst_vulkan_device_get_instance (GstVulkanDevice * device) { @@ -355,6 +422,14 @@ gst_vulkan_device_get_instance (GstVulkanDevice * device) return device->instance ? gst_object_ref (device->instance) : NULL; } +/** + * gst_vulkan_device_get_physical_device: (skip) + * @device: a #GstVulkanDevice + * + * Returns: The VkPhysicalDevice used to create @device + * + * Since: 1.18 + */ VkPhysicalDevice gst_vulkan_device_get_physical_device (GstVulkanDevice * device) { @@ -375,7 +450,7 @@ gst_vulkan_device_get_physical_device (GstVulkanDevice * device) * * Sets @device on @context * - * Since: 1.10 + * Since: 1.18 */ void gst_context_set_vulkan_device (GstContext * context, GstVulkanDevice * device) @@ -402,7 +477,7 @@ gst_context_set_vulkan_device (GstContext * context, GstVulkanDevice * device) * * Returns: Whether @device was in @context * - * Since: 1.10 + * Since: 1.18 */ gboolean gst_context_get_vulkan_device (GstContext * context, GstVulkanDevice ** device) @@ -423,6 +498,21 @@ gst_context_get_vulkan_device (GstContext * context, GstVulkanDevice ** device) return ret; } +/** + * gst_vulkan_device_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type #GST_QUERY_CONTEXT + * @device: the #GstVulkanDevice + * + * If a #GstVulkanDevice is requested in @query, sets @device as the reply. + * + * Intended for use with element query handlers to respond to #GST_QUERY_CONTEXT + * for a #GstVulkanDevice. + * + * Returns: whether @query was responded to with @device + * + * Since: 1.18 + */ gboolean gst_vulkan_device_handle_context_query (GstElement * element, GstQuery * query, GstVulkanDevice ** device) @@ -456,6 +546,18 @@ gst_vulkan_device_handle_context_query (GstElement * element, GstQuery * query, return res; } +/** + * gst_vulkan_device_run_context_query: + * @element: a #GstElement + * @device: (inout): a #GstVulkanDevice + * + * Attempt to retrieve a #GstVulkanDevice using #GST_QUERY_CONTEXT from the + * surrounding elements of @element. + * + * Returns: whether @device contains a valid #GstVulkanDevice + * + * Since: 1.18 + */ gboolean gst_vulkan_device_run_context_query (GstElement * element, GstVulkanDevice ** device) diff --git a/gst-libs/gst/vulkan/gstvkdevice.h b/gst-libs/gst/vulkan/gstvkdevice.h index 3e297520e7..d8b6834f2c 100644 --- a/gst-libs/gst/vulkan/gstvkdevice.h +++ b/gst-libs/gst/vulkan/gstvkdevice.h @@ -21,9 +21,8 @@ #ifndef __GST_VULKAN_DEVICE_H__ #define __GST_VULKAN_DEVICE_H__ -#include - -#include +#include +#include G_BEGIN_DECLS @@ -87,10 +86,6 @@ GstVulkanQueue * gst_vulkan_device_get_queue (GstVulkanDevice * d guint32 queue_i); GST_VULKAN_API VkPhysicalDevice gst_vulkan_device_get_physical_device (GstVulkanDevice * device); -GST_VULKAN_API -gboolean gst_vulkan_device_create_cmd_buffer (GstVulkanDevice * device, - VkCommandBuffer * cmd, - GError ** error); GST_VULKAN_API void gst_context_set_vulkan_device (GstContext * context, diff --git a/gst-libs/gst/vulkan/gstvkdisplay.c b/gst-libs/gst/vulkan/gstvkdisplay.c index 89468b42ab..07bf67378c 100644 --- a/gst-libs/gst/vulkan/gstvkdisplay.c +++ b/gst-libs/gst/vulkan/gstvkdisplay.c @@ -1,9 +1,6 @@ /* * GStreamer - * Copyright (C) 2007 David A. Schleef - * Copyright (C) 2008 Julien Isorce - * Copyright (C) 2008 Filippo Argiolas - * Copyright (C) 2013 Matthew Waters + * Copyright (C) 2015 Matthew Waters * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -40,6 +37,15 @@ #include "ios/gstvkdisplay_ios.h" #endif +/** + * SECTION:vkdisplay + * @title: GstVulkanDisplay + * @short_description: window system display + * @see_also: #GstVulkanInstance, #GstVulkanWindow + * + * A #GstVulkanDisplay represents a connection to a display server on the platform + */ + GST_DEBUG_CATEGORY_STATIC (GST_CAT_CONTEXT); #define GST_CAT_DEFAULT gst_vulkan_display_debug GST_DEBUG_CATEGORY_STATIC (GST_CAT_DEFAULT); @@ -168,6 +174,16 @@ gst_vulkan_display_finalize (GObject * object) G_OBJECT_CLASS (gst_vulkan_display_parent_class)->finalize (object); } +/** + * gst_vulkan_display_new_with_type: + * @instance: a #GstVulkanInstance + * @type: the #GstVulkanDisplayType to create + * + * Returns: (transfer full): a new #GstVulkanDisplay or %NULL if e.g. @type is + * unsupported + * + * Since: 1.18 + */ GstVulkanDisplay * gst_vulkan_display_new_with_type (GstVulkanInstance * instance, GstVulkanDisplayType type) @@ -198,7 +214,7 @@ gst_vulkan_display_new_with_type (GstVulkanInstance * instance, * * Returns: (transfer full): a new #GstVulkanDisplay * - * Since: 1.10 + * Since: 1.18 */ GstVulkanDisplay * gst_vulkan_display_new (GstVulkanInstance * instance) @@ -227,7 +243,7 @@ gst_vulkan_display_new (GstVulkanInstance * instance) * * Returns: the winsys specific handle of @display * - * Since: 1.10 + * Since: 1.18 */ gpointer gst_vulkan_display_get_handle (GstVulkanDisplay * display) @@ -253,7 +269,7 @@ gst_vulkan_display_default_get_handle (GstVulkanDisplay * display) * * Returns: the #GstVulkanDisplayType of @display * - * Since: 1.10 + * Since: 1.18 */ GstVulkanDisplayType gst_vulkan_display_get_handle_type (GstVulkanDisplay * display) @@ -268,7 +284,9 @@ gst_vulkan_display_get_handle_type (GstVulkanDisplay * display) * gst_vulkan_display_create_window: * @display: a #GstVulkanDisplay * - * Returns: a new #GstVulkanWindow for @display or %NULL. + * Returns: (transfer full): a new #GstVulkanWindow for @display or %NULL. + * + * Since: 1.18 */ GstVulkanWindow * gst_vulkan_display_create_window (GstVulkanDisplay * display) @@ -326,6 +344,15 @@ _find_window_list_item (GstVulkanDisplay * display, GstVulkanWindow * window) return l; } +/** + * gst_vulkan_display_remove_window: + * @display: a #GstVUlkanDisplay: + * @window: the #GstVulkanWindow to remove + * + * Returns: whether the window was successfully removed + * + * Since: 1.18 + */ gboolean gst_vulkan_display_remove_window (GstVulkanDisplay * display, GstVulkanWindow * window) @@ -353,7 +380,7 @@ gst_vulkan_display_remove_window (GstVulkanDisplay * display, * * Sets @display on @context * - * Since: 1.10 + * Since: 1.18 */ void gst_context_set_vulkan_display (GstContext * context, @@ -381,7 +408,7 @@ gst_context_set_vulkan_display (GstContext * context, * * Returns: Whether @display was in @context * - * Since: 1.10 + * Since: 1.18 */ gboolean gst_context_get_vulkan_display (GstContext * context, @@ -403,6 +430,18 @@ gst_context_get_vulkan_display (GstContext * context, return ret; } +/** + * gst_vulkan_display_choose_type: + * @instance: a #GstVulkanInstance + * + * This function will read the %GST_VULKAN_WINDOW environment variable for + * a user choice or choose the first supported implementation. + * + * Returns: the default #GstVulkanDisplayType #GstVulkanInstance will choose + * on creation + * + * Since: 1.18 + */ GstVulkanDisplayType gst_vulkan_display_choose_type (GstVulkanInstance * instance) { @@ -447,6 +486,15 @@ gst_vulkan_display_choose_type (GstVulkanInstance * instance) return GST_VULKAN_DISPLAY_TYPE_NONE; } +/** + * gst_vulkan_display_type_to_extension_string: + * @type: a #GstVulkanDisplayType + * + * Returns: the Vulkan extension string required for creating a VkSurfaceKHR + * using a window system handle or %NULL + * + * Since: 1.18 + */ const gchar * gst_vulkan_display_type_to_extension_string (GstVulkanDisplayType type) { @@ -474,6 +522,21 @@ gst_vulkan_display_type_to_extension_string (GstVulkanDisplayType type) return NULL; } +/** + * gst_vulkan_display_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type #GST_QUERY_CONTEXT + * @display: the #GstVulkanDisplay + * + * If a #GstVulkanDisplay is requested in @query, sets @device as the reply. + * + * Intended for use with element query handlers to respond to #GST_QUERY_CONTEXT + * for a #GstVulkanDisplay. + * + * Returns: whether @query was responded to with @display + * + * Since: 1.18 + */ gboolean gst_vulkan_display_handle_context_query (GstElement * element, GstQuery * query, GstVulkanDisplay ** display) @@ -507,6 +570,18 @@ gst_vulkan_display_handle_context_query (GstElement * element, GstQuery * query, return res; } +/** + * gst_vulkan_display_run_context_query: + * @element: a #GstElement + * @display: (inout): a #GstVulkanDisplay + * + * Attempt to retrieve a #GstVulkanDisplay using #GST_QUERY_CONTEXT from the + * surrounding elements of @element. + * + * Returns: whether @display contains a valid #GstVulkanDisplay + * + * Since: 1.18 + */ gboolean gst_vulkan_display_run_context_query (GstElement * element, GstVulkanDisplay ** display) diff --git a/gst-libs/gst/vulkan/gstvkdisplay.h b/gst-libs/gst/vulkan/gstvkdisplay.h index 5fe9179dfd..bcfe45b198 100644 --- a/gst-libs/gst/vulkan/gstvkdisplay.h +++ b/gst-libs/gst/vulkan/gstvkdisplay.h @@ -1,9 +1,6 @@ /* * GStreamer - * Copyright (C) 2007 David A. Schleef - * Copyright (C) 2008 Julien Isorce - * Copyright (C) 2008 Filippo Argiolas - * Copyright (C) 2013 Matthew Waters + * Copyright (C) 2015 Matthew Waters * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -26,7 +23,8 @@ #include -#include +#include +#include G_BEGIN_DECLS @@ -42,7 +40,19 @@ GType gst_vulkan_display_get_type (void); #define GST_VULKAN_DISPLAY_CONTEXT_TYPE_STR "gst.vulkan.display" -enum _GstVulkanDisplayType +typedef struct _GstVulkanDisplay GstVulkanDisplay; +typedef struct _GstVulkanDisplayClass GstVulkanDisplayClass; +typedef struct _GstVulkanDisplayPrivate GstVulkanDisplayPrivate; + +/** + * GstVulkanDisplayType: + * @GST_VULKAN_DISPLAY_TYPE_NONE: no display + * @GST_VULKAN_DISPLAY_TYPE_XCB: XCB display + * @GST_VULKAN_DISPLAY_TYPE_WAYLAND: wayland display + * @GST_VULKAN_DISPLAY_TYPE_COCOA: cocoa display for macOS + * @GST_VULKAN_DISPLAY_TYPE_IOS: ios display + */ +typedef enum { GST_VULKAN_DISPLAY_TYPE_NONE = 0, GST_VULKAN_DISPLAY_TYPE_XCB = (1 << 0), @@ -51,7 +61,7 @@ enum _GstVulkanDisplayType GST_VULKAN_DISPLAY_TYPE_IOS = (1 << 3), GST_VULKAN_DISPLAY_TYPE_ANY = G_MAXUINT32 -}; +} GstVulkanDisplayType; /** * GstVulkanDisplay: diff --git a/gst-libs/gst/vulkan/gstvkerror.c b/gst-libs/gst/vulkan/gstvkerror.c index 2e22bc703a..47c3bedd1c 100644 --- a/gst-libs/gst/vulkan/gstvkerror.c +++ b/gst-libs/gst/vulkan/gstvkerror.c @@ -74,6 +74,20 @@ _vk_result_to_string (VkResult result) return "Unknown Error"; } +/** + * gst_vulkan_error_to_g_error: (skip) + * @result: a VkResult + * @error: (inout) (optional): a #GError to fill + * @format: the printf-like format to write into the #GError + * @...: arguments for @format + * + * if @result indicates an error condition, fills out #Gerror with details of + * the error + * + * Returns: @result for easy chaining + * + * Since: 1.18 + */ VkResult gst_vulkan_error_to_g_error (VkResult result, GError ** error, const char *format, ...) @@ -87,8 +101,13 @@ gst_vulkan_error_to_g_error (VkResult result, GError ** error, return result; result_str = _vk_result_to_string (result); - if (result_str == NULL) - return result; + if (result_str == NULL) { + if (result < 0) { + result_str = "Unknown"; + } else { + return result; + } + } va_start (args, format); g_vasprintf (&string, format, args); diff --git a/gst-libs/gst/vulkan/gstvkfence.c b/gst-libs/gst/vulkan/gstvkfence.c index d39e1f0e47..a8580aeed5 100644 --- a/gst-libs/gst/vulkan/gstvkfence.c +++ b/gst-libs/gst/vulkan/gstvkfence.c @@ -24,6 +24,15 @@ #include "gstvkfence.h" +/** + * SECTION:vkfence + * @title: GstVulkanFence + * @short_description: Vulkan fences + * @see_also: #GstVulkanDevice + * + * A #GstVulkanFence encapsulates a VkFence + */ + GST_DEBUG_CATEGORY (gst_debug_vulkan_fence); #define GST_CAT_DEFAULT gst_debug_vulkan_fence @@ -54,6 +63,16 @@ gst_vulkan_fence_free (GstVulkanFence * fence) g_free (fence); } +/** + * gst_vulkan_fence_new: + * @device: the parent #GstVulkanDevice + * @flags: set of flags to create the fence with + * @error: a #GError for the failure condition + * + * Returns: whether a new #GstVulkanFence or %NULL on error + * + * Since: 1.18 + */ GstVulkanFence * gst_vulkan_fence_new (GstVulkanDevice * device, VkFenceCreateFlags flags, GError ** error) @@ -86,6 +105,14 @@ gst_vulkan_fence_new (GstVulkanDevice * device, VkFenceCreateFlags flags, return fence; } +/** + * gst_vulkan_fence_is_signaled: + * @fence: a #GstVulkanFence + * + * Returns: whether @fence has been signalled + * + * Since: 1.18 + */ gboolean gst_vulkan_fence_is_signaled (GstVulkanFence * fence) { diff --git a/gst-libs/gst/vulkan/gstvkfence.h b/gst-libs/gst/vulkan/gstvkfence.h index f67903ad29..171f241698 100644 --- a/gst-libs/gst/vulkan/gstvkfence.h +++ b/gst-libs/gst/vulkan/gstvkfence.h @@ -23,6 +23,8 @@ #include +G_BEGIN_DECLS + #define GST_TYPE_VULKAN_FENCE (gst_vulkan_fence_get_type ()) GST_VULKAN_API GType gst_vulkan_fence_get_type (void); @@ -30,8 +32,6 @@ GType gst_vulkan_fence_get_type (void); #define GST_VULKAN_FENCE_CAST(f) ((GstVulkanFence *) f) #define GST_VULKAN_FENCE_FENCE(f) (GST_VULKAN_FENCE_CAST(f)->fence) -G_BEGIN_DECLS - struct _GstVulkanFence { GstMiniObject parent; @@ -46,8 +46,6 @@ GstVulkanFence * gst_vulkan_fence_new (GstVulkanDevice * device, VkFenceCreateFlags flags, GError ** error); GST_VULKAN_API -GstVulkanFence * gst_vulkan_fence_wait (GstVulkanFence * fence); -GST_VULKAN_API gboolean gst_vulkan_fence_is_signaled (GstVulkanFence * fence); static inline GstVulkanFence * diff --git a/gst-libs/gst/vulkan/gstvkimagememory.c b/gst-libs/gst/vulkan/gstvkimagememory.c index 27e7b68b2b..888c7a3809 100644 --- a/gst-libs/gst/vulkan/gstvkimagememory.c +++ b/gst-libs/gst/vulkan/gstvkimagememory.c @@ -26,7 +26,7 @@ /** * SECTION:vkimagememory - * @title: GstVkImageMemory + * @title: GstVulkanImageMemory * @short_description: memory subclass for Vulkan image memory * @see_also: #GstMemory, #GstAllocator * @@ -39,6 +39,15 @@ GST_DEBUG_CATEGORY_STATIC (GST_CAT_DEFUALT); static GstAllocator *_vulkan_image_memory_allocator; +/** + * gst_vulkan_format_from_video_format: (skip) + * @v_format: the #GstVideoFormat + * @plane: the plane + * + * Returns: the VkFormat to use for @v_format and @plane + * + * Since: 1.18 + */ VkFormat gst_vulkan_format_from_video_format (GstVideoFormat v_format, guint plane) { @@ -437,6 +446,16 @@ _access_flags_from_layout (VkImageLayout image_layout) return 0; } +/** + * gst_vulkan_image_memory_set_layout: + * @vk_mem: a #GstVulkanImageMemory + * @image_layout: the new iamge layout + * @barrier: (inout): the barrier to fill + * + * Returns: wether the layout could be performed + * + * Since: 1.18 + */ gboolean gst_vulkan_image_memory_set_layout (GstVulkanImageMemory * vk_mem, VkImageLayout image_layout, VkImageMemoryBarrier * barrier) @@ -463,10 +482,19 @@ gst_vulkan_image_memory_set_layout (GstVulkanImageMemory * vk_mem, /** * gst_vulkan_image_memory_alloc: + * @device: a #GstVulkanDevice + * @format: the VkFormat for the new image + * @width: width for the new image + * @height: height for the new image + * @tiling: tiling for the new image + * @usage: usage flags for the new image + * @mem_prop_flags: VkDeviceMemory property flags for the new image * * Allocated a new #GstVulkanImageMemory. * * Returns: a #GstMemory object backed by a vulkan device memory + * + * Since: 1.18 */ GstMemory * gst_vulkan_image_memory_alloc (GstVulkanDevice * device, VkFormat format, @@ -481,6 +509,22 @@ gst_vulkan_image_memory_alloc (GstVulkanDevice * device, VkFormat format, return (GstMemory *) mem; } +/** + * gst_vulkan_image_memory_wrapped: + * @device: a #GstVulkanDevice + * @image: a VkImage + * @format: the VkFormat for @image + * @width: width of @image + * @height: height of @image + * @tiling: tiling of @image + * @usage: usage flags of @image + * @user_data: (nullable): user data for @notify + * @notify: a #DestroyNotify when @image is no longer needed + * + * Return: a new #GstVulkanImageMemory wrapping @image + * + * Since: 1.18 + */ GstMemory * gst_vulkan_image_memory_wrapped (GstVulkanDevice * device, VkImage image, VkFormat format, gsize width, gsize height, VkImageTiling tiling, @@ -494,6 +538,14 @@ gst_vulkan_image_memory_wrapped (GstVulkanDevice * device, VkImage image, return (GstMemory *) mem; } +/** + * gst_vulkan_image_memory_get_width: + * @image: a #GstVulkanImageMemory + * + * Return: the width of @image + * + * Since: 1.18 + */ guint32 gst_vulkan_image_memory_get_width (GstVulkanImageMemory * image) { @@ -503,6 +555,14 @@ gst_vulkan_image_memory_get_width (GstVulkanImageMemory * image) return image->create_info.extent.width; } +/** + * gst_vulkan_image_memory_get_height: + * @image: a #GstVulkanImageMemory + * + * Return: the height of @image + * + * Since: 1.18 + */ guint32 gst_vulkan_image_memory_get_height (GstVulkanImageMemory * image) { @@ -542,8 +602,10 @@ gst_vulkan_image_memory_allocator_init (GstVulkanImageMemoryAllocator * /** * gst_vulkan_image_memory_init_once: * - * Initializes the Vulkan memory allocator. It is safe to call this function + * Initializes the Vulkan image memory allocator. It is safe to call this function * multiple times. This must be called before any other #GstVulkanImageMemory operation. + * + * Since: 1.18 */ void gst_vulkan_image_memory_init_once (void) @@ -566,9 +628,11 @@ gst_vulkan_image_memory_init_once (void) /** * gst_is_vulkan_image_memory: - * @mem:a #GstMemory + * @mem: a #GstMemory * * Returns: whether the memory at @mem is a #GstVulkanImageMemory + * + * Since: 1.18 */ gboolean gst_is_vulkan_image_memory (GstMemory * mem) diff --git a/gst-libs/gst/vulkan/gstvkimagememory.h b/gst-libs/gst/vulkan/gstvkimagememory.h index 208918f106..56969b6aac 100644 --- a/gst-libs/gst/vulkan/gstvkimagememory.h +++ b/gst-libs/gst/vulkan/gstvkimagememory.h @@ -21,14 +21,10 @@ #ifndef __GST_VULKAN_IMAGE_MEMORY_H__ #define __GST_VULKAN_IMAGE_MEMORY_H__ -#include -#include -#include +#include #include -#include - G_BEGIN_DECLS #define GST_TYPE_VULKAN_IMAGE_MEMORY_ALLOCATOR (gst_vulkan_image_memory_allocator_get_type()) @@ -43,7 +39,11 @@ GType gst_vulkan_image_memory_allocator_get_type(void); #define GST_VULKAN_IMAGE_MEMORY_ALLOCATOR_CAST(obj) ((GstVulkanImageMemoryAllocator *)(obj)) #define GST_VULKAN_IMAGE_MEMORY_ALLOCATOR_NAME "VulkanImage" -#define GST_CAPS_FEATURE_MEMORY_VULKAN_IMAGE "memory:" GST_VULKAN_IMAGE_MEMORY_ALLOCATOR_NAME +#define GST_CAPS_FEATURE_MEMORY_VULKAN_IMAGE "memory:VulkanImage" + +typedef struct _GstVulkanImageMemory GstVulkanImageMemory; +typedef struct _GstVulkanImageMemoryAllocator GstVulkanImageMemoryAllocator; +typedef struct _GstVulkanImageMemoryAllocatorClass GstVulkanImageMemoryAllocatorClass; struct _GstVulkanImageMemory { @@ -114,7 +114,7 @@ GstMemory * gst_vulkan_image_memory_wrapped (GstVulkanDevice * devic GST_VULKAN_API gboolean gst_vulkan_image_memory_set_layout (GstVulkanImageMemory * vk_mem, - VkImageLayout, + VkImageLayout image_layout, VkImageMemoryBarrier * barrier); GST_VULKAN_API diff --git a/gst-libs/gst/vulkan/gstvkinstance.c b/gst-libs/gst/vulkan/gstvkinstance.c index 16b03ba4ad..a4c2f8274b 100644 --- a/gst-libs/gst/vulkan/gstvkinstance.c +++ b/gst-libs/gst/vulkan/gstvkinstance.c @@ -26,6 +26,16 @@ #include +/** + * SECTION:vkinstance + * @title: GstVulkanInstance + * @short_description: memory subclass for Vulkan image memory + * @see_also: #GstMemory, #GstAllocator + * + * GstVulkanImageMemory is a #GstMemory subclass providing support for the + * mapping of Vulkan device memory. + */ + #define APP_SHORT_NAME "GStreamer" #define GST_CAT_DEFAULT gst_vulkan_instance_debug @@ -89,7 +99,9 @@ gst_vulkan_instance_class_init (GstVulkanInstanceClass * klass) * Overrides the #GstVulkanDevice creation mechanism. * It can be called from any thread. * - * Returns: the newly created #GstVulkanDevice. + * Returns: (transfer full): the newly created #GstVulkanDevice. + * + * Since: 1.18 */ gst_vulkan_instance_signals[SIGNAL_CREATE_DEVICE] = g_signal_new ("create-device", G_TYPE_FROM_CLASS (klass), @@ -155,6 +167,15 @@ _gst_vk_debug_callback (VkDebugReportFlagsEXT msgFlags, return FALSE; } +/** + * gst_vulkan_instance_open: + * @instance: a #GstVulkanInstance + * @error: #GError + * + * Returns: whether the instance vould be created + * + * Since: 1.18 + */ gboolean gst_vulkan_instance_open (GstVulkanInstance * instance, GError ** error) { @@ -373,6 +394,17 @@ error: } } +/** + * gst_vulkan_instance_get_proc_address: + * @instance: a #GstVulkanInstance + * @name: name of the function to retrieve + * + * Performs vkGetInstanceProcAddr() with @instance and @name + * + * Returns: the function pointer for @name or %NULL + * + * Since: 1.18 + */ gpointer gst_vulkan_instance_get_proc_address (GstVulkanInstance * instance, const gchar * name) @@ -386,6 +418,14 @@ gst_vulkan_instance_get_proc_address (GstVulkanInstance * instance, return vkGetInstanceProcAddr (instance->instance, name); } +/** + * gst_vulkan_instance_create_device: + * @instance: a #GstVulkanIncstance + * + * Returns: (transfer full): a new #GstVulkanDevice + * + * Since: 1.18 + */ GstVulkanDevice * gst_vulkan_instance_create_device (GstVulkanInstance * instance, GError ** error) @@ -415,7 +455,7 @@ gst_vulkan_instance_create_device (GstVulkanInstance * instance, * * Sets @instance on @context * - * Since: 1.10 + * Since: 1.18 */ void gst_context_set_vulkan_instance (GstContext * context, @@ -443,7 +483,7 @@ gst_context_set_vulkan_instance (GstContext * context, * * Returns: Whether @instance was in @context * - * Since: 1.10 + * Since: 1.18 */ gboolean gst_context_get_vulkan_instance (GstContext * context, @@ -465,6 +505,21 @@ gst_context_get_vulkan_instance (GstContext * context, return ret; } +/** + * gst_vulkan_instance_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type #GST_QUERY_CONTEXT + * @instance: the #GstVulkanInstance + * + * If a #GstVulkanInstance is requested in @query, sets @instance as the reply. + * + * Intended for use with element query handlers to respond to #GST_QUERY_CONTEXT + * for a #GstVulkanInstance. + * + * Returns: whether @query was responded to with @instance + * + * Since: 1.18 + */ gboolean gst_vulkan_instance_handle_context_query (GstElement * element, GstQuery * query, GstVulkanInstance ** instance) @@ -498,6 +553,18 @@ gst_vulkan_instance_handle_context_query (GstElement * element, return res; } +/** + * gst_vulkan_instance_run_context_query: + * @element: a #GstElement + * @instance: (inout): a #GstVulkanInstance + * + * Attempt to retrieve a #GstVulkanInstance using #GST_QUERY_CONTEXT from the + * surrounding elements of @element. + * + * Returns: whether @instance contains a valid #GstVulkanInstance + * + * Since: 1.18 + */ gboolean gst_vulkan_instance_run_context_query (GstElement * element, GstVulkanInstance ** instance) diff --git a/gst-libs/gst/vulkan/gstvkmemory.c b/gst-libs/gst/vulkan/gstvkmemory.c index b81a55101e..06167f8f94 100644 --- a/gst-libs/gst/vulkan/gstvkmemory.c +++ b/gst-libs/gst/vulkan/gstvkmemory.c @@ -28,7 +28,7 @@ /** * SECTION:vkmemory - * @title: GstVkMemory + * @title: GstVulkanMemory * @short_description: memory subclass for Vulkan device memory * @see_also: #GstMemory, #GstAllocator * @@ -250,24 +250,35 @@ _vk_mem_free (GstAllocator * allocator, GstMemory * memory) gst_object_unref (mem->device); } +/** + * gst_vulkan_memory_find_memory_type_index_with_type_properties: + * @device: a #GstVulkanDevice + * @type_bits: memory type bits to search for + * @properties: memory properties to search for + * @type_index: resulting index of the memory type + * + * Returns: whether a valid memory type could be found + * + * Since: 1.18 + */ gboolean gst_vulkan_memory_find_memory_type_index_with_type_properties (GstVulkanDevice * - device, guint32 typeBits, VkMemoryPropertyFlags properties, - guint32 * typeIndex) + device, guint32 type_bits, VkMemoryPropertyFlags properties, + guint32 * type_index) { guint32 i; /* Search memtypes to find first index with those properties */ for (i = 0; i < 32; i++) { - if ((typeBits & 1) == 1) { + if ((type_bits & 1) == 1) { /* Type is available, does it match user properties? */ if ((device->memory_properties.memoryTypes[i]. propertyFlags & properties) == properties) { - *typeIndex = i; + *type_index = i; return TRUE; } } - typeBits >>= 1; + type_bits >>= 1; } return FALSE; @@ -283,6 +294,8 @@ gst_vulkan_memory_find_memory_type_index_with_type_properties (GstVulkanDevice * * Allocated a new #GstVulkanMemory. * * Returns: a #GstMemory object backed by a vulkan device memory + * + * Since: 1.18 */ GstMemory * gst_vulkan_memory_alloc (GstVulkanDevice * device, guint32 memory_type_index, @@ -326,6 +339,8 @@ gst_vulkan_memory_allocator_init (GstVulkanMemoryAllocator * allocator) * * Initializes the Vulkan memory allocator. It is safe to call this function * multiple times. This must be called before any other #GstVulkanMemory operation. + * + * Since: 1.18 */ void gst_vulkan_memory_init_once (void) @@ -351,6 +366,8 @@ gst_vulkan_memory_init_once (void) * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstVulkanMemory + * + * Since: 1.18 */ gboolean gst_is_vulkan_memory (GstMemory * mem) diff --git a/gst-libs/gst/vulkan/gstvkmemory.h b/gst-libs/gst/vulkan/gstvkmemory.h index d2191865e5..b45d25a3a8 100644 --- a/gst-libs/gst/vulkan/gstvkmemory.h +++ b/gst-libs/gst/vulkan/gstvkmemory.h @@ -102,9 +102,9 @@ GstMemory * gst_vulkan_memory_alloc (GstVulkanDevice * device, GST_VULKAN_API gboolean gst_vulkan_memory_find_memory_type_index_with_type_properties (GstVulkanDevice * device, - guint32 typeBits, + guint32 type_bits, VkMemoryPropertyFlags properties, - guint32 * typeIndex); + guint32 * type_index); G_END_DECLS diff --git a/gst-libs/gst/vulkan/gstvkqueue.c b/gst-libs/gst/vulkan/gstvkqueue.c index ccbd09dc0a..8d187ad2ac 100644 --- a/gst-libs/gst/vulkan/gstvkqueue.c +++ b/gst-libs/gst/vulkan/gstvkqueue.c @@ -24,6 +24,15 @@ #include "gstvkqueue.h" +/** + * SECTION:vkqueue + * @title: GstVulkanQueue + * @short_description: Vulkan command queue + * @see_also: #GstVulkanDevice + * + * GstVulkanQueue encapsulates the vulkan command queue. + */ + #define GST_CAT_DEFAULT gst_vulkan_queue_debug GST_DEBUG_CATEGORY (GST_CAT_DEFAULT); GST_DEBUG_CATEGORY_STATIC (GST_CAT_CONTEXT); @@ -61,6 +70,14 @@ gst_vulkan_queue_dispose (GObject * object) G_OBJECT_CLASS (parent_class)->dispose (object); } +/** + * gst_vulkan_queue_get_device + * @queue: a #GstVulkanQueue + * + * Returns: (transfer full): the #GstVulkanDevice for @queue + * + * Since: 1.18 + */ GstVulkanDevice * gst_vulkan_queue_get_device (GstVulkanQueue * queue) { @@ -69,6 +86,15 @@ gst_vulkan_queue_get_device (GstVulkanQueue * queue) return queue->device ? gst_object_ref (queue->device) : NULL; } +/** + * gst_vulkan_queue_create_command_pool: + * @queue: a #GstVulkanQueue + * @error: a #GError + * + * Returns: (transfer full): a new #GstVUlkanCommandPool or %NULL + * + * Since: 1.18 + */ GstVulkanCommandPool * gst_vulkan_queue_create_command_pool (GstVulkanQueue * queue, GError ** error) { @@ -112,7 +138,7 @@ error: * * Sets @queue on @context * - * Since: 1.10 + * Since: 1.18 */ void gst_context_set_vulkan_queue (GstContext * context, GstVulkanQueue * queue) @@ -139,7 +165,7 @@ gst_context_set_vulkan_queue (GstContext * context, GstVulkanQueue * queue) * * Returns: Whether @queue was in @context * - * Since: 1.10 + * Since: 1.18 */ gboolean gst_context_get_vulkan_queue (GstContext * context, GstVulkanQueue ** queue) @@ -160,6 +186,21 @@ gst_context_get_vulkan_queue (GstContext * context, GstVulkanQueue ** queue) return ret; } +/** + * gst_vulkan_queue_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type #GST_QUERY_CONTEXT + * @queue: the #GstVulkanQueue + * + * If a #GstVulkanQueue is requested in @query, sets @queue as the reply. + * + * Intended for use with element query handlers to respond to #GST_QUERY_CONTEXT + * for a #GstVulkanQueue. + * + * Returns: whether @query was responded to with @queue + * + * Since: 1.18 + */ gboolean gst_vulkan_queue_handle_context_query (GstElement * element, GstQuery * query, GstVulkanQueue ** queue) @@ -193,6 +234,18 @@ gst_vulkan_queue_handle_context_query (GstElement * element, GstQuery * query, return res; } +/** + * gst_vulkan_queue_run_context_query: + * @element: a #GstElement + * @queue: (inout): a #GstVulkanQueue + * + * Attempt to retrieve a #GstVulkanQueue using #GST_QUERY_CONTEXT from the + * surrounding elements of @element. + * + * Returns: whether @queue contains a valid #GstVulkanQueue + * + * Since: 1.18 + */ gboolean gst_vulkan_queue_run_context_query (GstElement * element, GstVulkanQueue ** queue) diff --git a/gst-libs/gst/vulkan/gstvkqueue.h b/gst-libs/gst/vulkan/gstvkqueue.h index 6b93991b25..658cebc726 100644 --- a/gst-libs/gst/vulkan/gstvkqueue.h +++ b/gst-libs/gst/vulkan/gstvkqueue.h @@ -21,7 +21,8 @@ #ifndef __GST_VULKAN_QUEUE_H__ #define __GST_VULKAN_QUEUE_H__ -#include +#include +#include #define GST_TYPE_VULKAN_QUEUE (gst_vulkan_queue_get_type()) #define GST_VULKAN_QUEUE(o) (G_TYPE_CHECK_INSTANCE_CAST((o), GST_TYPE_VULKAN_QUEUE, GstVulkanQueue)) diff --git a/gst-libs/gst/vulkan/gstvkutils.c b/gst-libs/gst/vulkan/gstvkutils.c index 426bcdc0ca..bce3c3f074 100644 --- a/gst-libs/gst/vulkan/gstvkutils.c +++ b/gst-libs/gst/vulkan/gstvkutils.c @@ -24,6 +24,15 @@ #include "gstvkutils.h" +/** + * SECTION:vkutils + * @title: Vulkan Utils + * @short_description: Vulkan utilities + * @see_also: #GstVulkanInstance, #GstVulkanDevice + * + * GstVulkanQueue encapsulates the vulkan command queue. + */ + GST_DEBUG_CATEGORY_STATIC (GST_CAT_CONTEXT); static void @@ -59,6 +68,16 @@ _vk_pad_query (const GValue * item, GValue * value, gpointer user_data) return TRUE; } +/** + * gst_vulkan_run_query: + * @element: a #GstElement + * @query: the #GstQuery to perform + * @direction: the #GstPadDirection to perform query on + * + * Returns: whether @query was answered successfully + * + * Since: 1.18 + */ gboolean gst_vulkan_run_query (GstElement * element, GstQuery * query, GstPadDirection direction) @@ -118,6 +137,16 @@ _vulkan_local_context_query (GstElement * element, return query; } +/** + * gst_vulkan_global_context_query: + * @element: a #GstElement + * @context_type: the context type to query for + * + * Performs the steps necessary for executing a context query including + * posting a message for the application to respond. + * + * Since: 1.18 + */ void gst_vulkan_global_context_query (GstElement * element, const gchar * context_type) @@ -148,6 +177,16 @@ gst_vulkan_global_context_query (GstElement * element, */ } +/** + * gst_vulkan_local_context_query: + * @element: a #GstElement + * @context_type: the context type to query for + * + * Performs the steps necessary for executing a context query between only + * other elements in the pipeline + * + * Since: 1.18 + */ GstQuery * gst_vulkan_local_context_query (GstElement * element, const gchar * context_type) @@ -185,8 +224,28 @@ _vk_context_propagate (GstElement * element, GstContext * context) gst_element_post_message (GST_ELEMENT_CAST (element), msg); } +/** + * gst_vulkan_ensure_element_data: + * @element: a #GstElement + * @display_ptr: (inout) (optional): the resulting #GstVulkanDisplay + * @instance_ptr: (inout): the resulting #GstVulkanInstance + * + * Perform the steps necessary for retrieving a #GstVulkanInstance and + * (optionally) an #GstVulkanDisplay from the surrounding elements or from + * the application using the #GstContext mechanism. + * + * If the contents of @display_ptr or @instance_ptr are not %NULL, then no + * #GstContext query is necessary and no #GstVulkanInstance or #GstVulkanDisplay + * retrieval is performed. + * + * Returns: whether a #GstVulkanInstance exists in @instance_ptr and if + * @display_ptr is not %NULL, whether a #GstVulkanDisplay exists in + * @display_ptr + * + * Since: 1.18 + */ gboolean -gst_vulkan_ensure_element_data (gpointer element, +gst_vulkan_ensure_element_data (GstElement * element, GstVulkanDisplay ** display_ptr, GstVulkanInstance ** instance_ptr) { g_return_val_if_fail (element != NULL, FALSE); @@ -251,6 +310,23 @@ gst_vulkan_ensure_element_data (gpointer element, return *display_ptr != NULL && *instance_ptr != NULL; } +/** + * gst_vulkan_handle_set_context: + * @element: a #GstElement + * @context: a #GstContext + * @display: (inout) (transfer full) (optional): location of a #GstVulkanDisplay + * @instance: (inout) (transfer full): location of a #GstVulkanInstance + * + * Helper function for implementing #GstElementClass.set_context() in + * Vulkan capable elements. + * + * Retrieve's the #GstVulkanDisplay or #GstVulkanInstance in @context and places + * the result in @display or @instance respectively. + * + * Returns: whether the @display or @instance could be set successfully + * + * Since: 1.18 + */ gboolean gst_vulkan_handle_set_context (GstElement * element, GstContext * context, GstVulkanDisplay ** display, GstVulkanInstance ** instance) @@ -299,6 +375,19 @@ gst_vulkan_handle_set_context (GstElement * element, GstContext * context, return TRUE; } +/** + * gst_vulkan_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type %GST_QUERY_CONTEXT + * @display: (transfer none) (nullable): a #GstVulkanDisplay + * @instance: (transfer none) (nullable): a #GstVulkanInstance + * @device: (transfer none) (nullable): a #GstVulkanInstance + * + * Returns: Whether the @query was successfully responded to from the passed + * @display, @instance, and @device. + * + * Since: 1.18 + */ gboolean gst_vulkan_handle_context_query (GstElement * element, GstQuery * query, GstVulkanDisplay ** display, GstVulkanInstance ** instance, diff --git a/gst-libs/gst/vulkan/gstvkutils.h b/gst-libs/gst/vulkan/gstvkutils.h index c1a954fbe1..3201cf3b41 100644 --- a/gst-libs/gst/vulkan/gstvkutils.h +++ b/gst-libs/gst/vulkan/gstvkutils.h @@ -26,7 +26,7 @@ G_BEGIN_DECLS GST_VULKAN_API -gboolean gst_vulkan_ensure_element_data (gpointer element, +gboolean gst_vulkan_ensure_element_data (GstElement * element, GstVulkanDisplay ** display_ptr, GstVulkanInstance ** instance_ptr); GST_VULKAN_API diff --git a/gst-libs/gst/vulkan/gstvkwindow.c b/gst-libs/gst/vulkan/gstvkwindow.c index f5b8456c47..d2d8092f93 100644 --- a/gst-libs/gst/vulkan/gstvkwindow.c +++ b/gst-libs/gst/vulkan/gstvkwindow.c @@ -1,6 +1,6 @@ /* * GStreamer - * Copyright (C) 2012 Matthew Waters + * Copyright (C) 2015 Matthew Waters * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -20,9 +20,9 @@ /** * SECTION:vkwindow - * @short_description: window/surface abstraction * @title: GstVulkanWindow - * @see_also: #GstGLContext, #GstGLDisplay + * @short_description: window/surface abstraction + * @see_also: #GstVulkanDisplay * * GstVulkanWindow represents a window that elements can render into. A window can * either be a user visible window (onscreen) or hidden (offscreen). @@ -157,11 +157,11 @@ gst_vulkan_window_class_init (GstVulkanWindowClass * klass) /** * gst_vulkan_window_new: - * @display: a #GstGLDisplay + * @display: a #GstVulkanDisplay * * Returns: (transfer full): a new #GstVulkanWindow using @display's connection * - * Since: 1.10 + * Since: 1.18 */ GstVulkanWindow * gst_vulkan_window_new (GstVulkanDisplay * display) @@ -214,6 +214,14 @@ gst_vulkan_window_finalize (GObject * object) G_OBJECT_CLASS (gst_vulkan_window_parent_class)->finalize (object); } +/** + * gst_vulkan_window_get_display: + * @window: a #GstVulkanWindow + * + * Returns: (transfer full): the #GstVulkanDisplay for @window + * + * Since: 1.18 + */ GstVulkanDisplay * gst_vulkan_window_get_display (GstVulkanWindow * window) { @@ -222,6 +230,15 @@ gst_vulkan_window_get_display (GstVulkanWindow * window) return gst_object_ref (window->display); } +/** + * gst_vulkan_window_get_surface: (skip) + * @window: a #GstVulkanWindow + * @error: a #GError + * + * Returns: the VkSurface for displaying into + * + * Since: 1.18 + */ VkSurfaceKHR gst_vulkan_window_get_surface (GstVulkanWindow * window, GError ** error) { @@ -234,6 +251,17 @@ gst_vulkan_window_get_surface (GstVulkanWindow * window, GError ** error) return klass->get_surface (window, error); } +/** + * gst_vulkan_window_get_presentation_support: + * @window: a #GstVulkanWindow + * @device: a #GstVulkanDevice + * @queue_family_idx: the queue family + * + * Returns: whether the given combination of @window, @device and + * @queue_family_idx supports presentation + * + * Since: 1.18 + */ gboolean gst_vulkan_window_get_presentation_support (GstVulkanWindow * window, GstVulkanDevice * device, guint32 queue_family_idx) @@ -247,6 +275,15 @@ gst_vulkan_window_get_presentation_support (GstVulkanWindow * window, return klass->get_presentation_support (window, device, queue_family_idx); } +/** + * gst_vulkan_window_open: + * @window: a #GstVulkanWindow + * @error: a #GError + * + * Returns: whether @window could be sucessfully opened + * + * Since: 1.18 + */ gboolean gst_vulkan_window_open (GstVulkanWindow * window, GError ** error) { @@ -259,6 +296,14 @@ gst_vulkan_window_open (GstVulkanWindow * window, GError ** error) return klass->open (window, error); } +/** + * gst_vulkan_window_close: + * @window: a #GstVulkanWindow + * + * Attempt to close the window. + * + * Since: 1.18 + */ void gst_vulkan_window_close (GstVulkanWindow * window) { @@ -275,6 +320,18 @@ gst_vulkan_window_close (GstVulkanWindow * window) klass->close (window); } +/** + * gst_vulkan_window_resize: + * @window: a #GstVulkanWindow + * @width: the new width + * @height: the new height + * + * Resize the output surface. + * + * Currently intended for subclasses to update internal state. + * + * Since: 1.18 + */ void gst_vulkan_window_resize (GstVulkanWindow * window, gint width, gint height) { @@ -286,6 +343,14 @@ gst_vulkan_window_resize (GstVulkanWindow * window, gint width, gint height) /* XXX: possibly queue a resize/redraw */ } +/** + * gst_vulkan_window_redraw: + * @window: a #GstVulkanWindow + * + * Ask the @window to redraw its contents + * + * Since: 1.18 + */ void gst_vulkan_window_redraw (GstVulkanWindow * window) { diff --git a/gst-libs/gst/vulkan/gstvkwindow.h b/gst-libs/gst/vulkan/gstvkwindow.h index cebd2f62d9..1ece99bce9 100644 --- a/gst-libs/gst/vulkan/gstvkwindow.h +++ b/gst-libs/gst/vulkan/gstvkwindow.h @@ -1,7 +1,6 @@ /* * GStreamer - * Copyright (C) 2008 Julien Isorce - * Copyright (C) 2012 Matthew Waters + * Copyright (C) 2015 Matthew Waters * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public diff --git a/gst-libs/gst/vulkan/meson.build b/gst-libs/gst/vulkan/meson.build index 9137eef082..8c96ec6941 100644 --- a/gst-libs/gst/vulkan/meson.build +++ b/gst-libs/gst/vulkan/meson.build @@ -183,7 +183,7 @@ if vulkan_dep.found() and has_vulkan_header if build_gir vulkan_gir = gnome.generate_gir(gstvulkan, - sources : vulkan_sources + [vulkan_enumtypes_h, vulkan_enumtypes_c], + sources : vulkan_sources + vulkan_headers + [vulkan_enumtypes_h, vulkan_enumtypes_c], namespace : 'GstVulkan', nsversion : api_version, identifier_prefix : 'Gst', diff --git a/gst-libs/gst/vulkan/vulkan_fwd.h b/gst-libs/gst/vulkan/vulkan_fwd.h index 941cceb2eb..b4fdac74b2 100644 --- a/gst-libs/gst/vulkan/vulkan_fwd.h +++ b/gst-libs/gst/vulkan/vulkan_fwd.h @@ -40,8 +40,6 @@ typedef struct _GstVulkanCommandPool GstVulkanCommandPool; typedef struct _GstVulkanCommandPoolClass GstVulkanCommandPoolClass; typedef struct _GstVulkanCommandPoolPrivate GstVulkanCommandPoolPrivate; -typedef enum _GstVulkanDisplayType GstVulkanDisplayType; - typedef struct _GstVulkanDisplay GstVulkanDisplay; typedef struct _GstVulkanDisplayClass GstVulkanDisplayClass; typedef struct _GstVulkanDisplayPrivate GstVulkanDisplayPrivate; @@ -60,10 +58,6 @@ typedef struct _GstVulkanBufferMemory GstVulkanBufferMemory; typedef struct _GstVulkanBufferMemoryAllocator GstVulkanBufferMemoryAllocator; typedef struct _GstVulkanBufferMemoryAllocatorClass GstVulkanBufferMemoryAllocatorClass; -typedef struct _GstVulkanImageMemory GstVulkanImageMemory; -typedef struct _GstVulkanImageMemoryAllocator GstVulkanImageMemoryAllocator; -typedef struct _GstVulkanImageMemoryAllocatorClass GstVulkanImageMemoryAllocatorClass; - typedef struct _GstVulkanBufferPool GstVulkanBufferPool; typedef struct _GstVulkanBufferPoolClass GstVulkanBufferPoolClass; typedef struct _GstVulkanBufferPoolPrivate GstVulkanBufferPoolPrivate;