From c3cf9521a58286c1242d8548b096c644b8a76a78 Mon Sep 17 00:00:00 2001 From: Seungha Yang Date: Fri, 26 Aug 2022 00:16:56 +0900 Subject: [PATCH] d3d11: Update library doc * Private header name is changed to gstd3d11-private.h to follow naming convention * Add Since mark everywhere * Update member variable names to be consistent with the other object implementations in this library * Correct outdated documentation Part-of: --- .../{gstd3d11_private.h => gstd3d11-private.h} | 0 .../gst-libs/gst/d3d11/gstd3d11bufferpool.cpp | 11 ++--- .../gst-libs/gst/d3d11/gstd3d11bufferpool.h | 17 ++++++- .../gst-libs/gst/d3d11/gstd3d11compile.cpp | 20 ++++++++- .../gst-libs/gst/d3d11/gstd3d11converter.cpp | 13 +++++- .../gst-libs/gst/d3d11/gstd3d11converter.h | 20 +++++++-- .../gst-libs/gst/d3d11/gstd3d11device.cpp | 4 +- .../gst-libs/gst/d3d11/gstd3d11device.h | 28 ++++++++++++ .../gst-libs/gst/d3d11/gstd3d11format.cpp | 10 ++++- .../gst-libs/gst/d3d11/gstd3d11format.h | 7 +++ .../gst-libs/gst/d3d11/gstd3d11memory.cpp | 12 ++++- .../gst-libs/gst/d3d11/gstd3d11memory.h | 52 ++++++++++++++++++---- .../gst-libs/gst/d3d11/gstd3d11utils.cpp | 28 ++++++++++-- .../sys/d3d11/gstd3d11pluginutils.h | 2 +- 14 files changed, 195 insertions(+), 29 deletions(-) rename subprojects/gst-plugins-bad/gst-libs/gst/d3d11/{gstd3d11_private.h => gstd3d11-private.h} (100%) diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11_private.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11-private.h similarity index 100% rename from subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11_private.h rename to subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11-private.h diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.cpp index 461ddb6..785fd72 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.cpp @@ -26,19 +26,20 @@ #include "gstd3d11memory.h" #include "gstd3d11device.h" #include "gstd3d11utils.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include /** * SECTION:gstd3d11bufferpool * @title: GstD3D11BufferPool - * @short_description: buffer pool for #GstD3D11Memory objects - * @see_also: #GstBufferPool, #GstGLMemory + * @short_description: buffer pool for GstD3D11Memory object + * @see_also: #GstBufferPool, #GstD3D11Memory * - * a #GstD3D11BufferPool is an object that allocates buffers with #GstD3D11Memory + * This GstD3D11BufferPool is an object that allocates buffers + * with #GstD3D11Memory * - * A #GstGLBufferPool is created with gst_d3d11_buffer_pool_new() + * Since: 1.22 */ GST_DEBUG_CATEGORY_STATIC (gst_d3d11_buffer_pool_debug); diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.h index eed9de8..dd19668 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11bufferpool.h @@ -34,6 +34,13 @@ G_BEGIN_DECLS #define GST_IS_D3D11_BUFFER_POOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GST_TYPE_D3D11_BUFFER_POOL)) #define GST_D3D11_BUFFER_POOL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GST_TYPE_D3D11_BUFFER_POOL, GstD3D11BufferPoolClass)) +/** + * GstD3D11BufferPool: + * + * Opaque GstD3D11BufferPool struct + * + * Since: 1.22 + */ struct _GstD3D11BufferPool { GstBufferPool parent; @@ -42,13 +49,19 @@ struct _GstD3D11BufferPool /*< private >*/ GstD3D11BufferPoolPrivate *priv; - gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstD3D11BufferPoolClass: + * + * Opaque GstD3D11BufferPoolClass struct + * + * Since: 1.22 + */ struct _GstD3D11BufferPoolClass { - GstBufferPoolClass bufferpool_class; + GstBufferPoolClass parent_class; /*< private >*/ gpointer _gst_reserved[GST_PADDING]; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11compile.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11compile.cpp index 51937bd..220d086 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11compile.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11compile.cpp @@ -24,11 +24,21 @@ #include "gstd3d11compile.h" #include "gstd3d11device.h" #include "gstd3d11utils.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include #include #include +/** + * SECTION:gstd3d11compile + * @title: GstD3D11Compile + * @short_description: HLSL compiler and utility + * + * A set of HLSL compile helper methods + * + * Since: 1.22 + */ + /* *INDENT-OFF* */ using namespace Microsoft::WRL; /* *INDENT-ON* */ @@ -59,6 +69,8 @@ static pD3DCompile GstD3DCompileFunc = nullptr; * Loads HLSL compiler library * * Returns: %TRUE if HLSL compiler library is available + * + * Since: 1.22 */ gboolean gst_d3d11_compile_init (void) @@ -123,6 +135,8 @@ gst_d3d11_compile_init (void) * Compiles HLSL code or an effect file into bytecode for a given target * * Returns: HRESULT return code + * + * Since: 1.22 */ HRESULT gst_d3d11_compile (LPCVOID src_data, SIZE_T src_data_size, LPCSTR source_name, @@ -147,6 +161,8 @@ gst_d3d11_compile (LPCVOID src_data, SIZE_T src_data_size, LPCSTR source_name, * Compiles pixel shader code and creates ID3D11PixelShader * * Returns: HRESULT return code + * + * Since: 1.22 */ HRESULT gst_d3d11_create_pixel_shader_simple (GstD3D11Device * device, @@ -220,6 +236,8 @@ gst_d3d11_create_pixel_shader_simple (GstD3D11Device * device, * ID3D11InputLayout * * Returns: HRESULT return code + * + * Since: 1.22 */ HRESULT gst_d3d11_create_vertex_shader_simple (GstD3D11Device * device, diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.cpp index 49af140..76d3f2e 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.cpp @@ -23,7 +23,7 @@ # include #endif -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include "gstd3d11converter.h" #include "gstd3d11device.h" #include "gstd3d11utils.h" @@ -34,6 +34,17 @@ #include #include +/** + * SECTION:gstd3d11converter + * @title: GstD3D11Converter + * @short_description: Direct3D11 video converter object + * + * This object performs various video conversion operation + * via Direct3D11 API + * + * Since: 1.22 + */ + GST_DEBUG_CATEGORY_STATIC (gst_d3d11_converter_debug); #define GST_CAT_DEFAULT gst_d3d11_converter_debug diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.h index a9994d6..585704e 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11converter.h @@ -35,9 +35,9 @@ G_BEGIN_DECLS #define GST_D3D11_CONVERTER_CAST(obj) ((GstD3D11Converter*)(obj)) /** - * GstD3D11ConverterMethod: - * @GST_D3D11_CONVERTER_METHOD_SHADER: Performs conversion using pixel shader - * @GST_D3D11_CONVERTER_METHOD_VIDEO_PROCESSOR: Performs conversion using video processor + * GstD3D11ConverterBackend: + * @GST_D3D11_CONVERTER_BACKEND_SHADER: Performs conversion using pixel shader + * @GST_D3D11_CONVERTER_BACKEND_VIDEO_PROCESSOR: Performs conversion using video processor * * Since: 1.22 */ @@ -81,6 +81,13 @@ GType gst_d3d11_converter_backend_get_type (void); */ #define GST_D3D11_CONVERTER_OPT_PRIMARIES_MODE "GstD3D11Converter.primaries-mode" +/** + * GstD3D11Converter: + * + * Opaque GstD3D11Converter struct + * + * Since: 1.22 + */ struct _GstD3D11Converter { GstObject parent; @@ -92,6 +99,13 @@ struct _GstD3D11Converter gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstD3D11ConverterClass: + * + * Opaque GstD3D11ConverterClass struct + * + * Since: 1.22 + */ struct _GstD3D11ConverterClass { GstObjectClass parent_class; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.cpp index b537f6d..db42e39 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.cpp @@ -25,7 +25,7 @@ #include "gstd3d11device.h" #include "gstd3d11utils.h" #include "gstd3d11format.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include "gstd3d11memory.h" #include #include @@ -35,8 +35,8 @@ /** * SECTION:gstd3d11device - * @short_description: Direct3D11 device abstraction * @title: GstD3D11Device + * @short_description: Direct3D11 device abstraction * * #GstD3D11Device wraps ID3D11Device and ID3D11DeviceContext for GPU resources * to be able to be shared among various elements. Caller can get native diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.h index 01b2728..2f77d98 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11device.h @@ -39,8 +39,22 @@ G_BEGIN_DECLS #define GST_D3D11_FENCE(obj) ((GstD3D11Fence *)obj) #define GST_D3D11_FENCE_CAST(obj) (GST_D3D11_FENCE(obj)) +/** + * GST_D3D11_DEVICE_HANDLE_CONTEXT_TYPE: + * + * The name used in #GstContext queries for requesting a #GstD3D11Device + * + * Since: 1.22 + */ #define GST_D3D11_DEVICE_HANDLE_CONTEXT_TYPE "gst.d3d11.device.handle" +/** + * GstD3D11Device: + * + * Opaque GstD3D11Device struct + * + * Since: 1.22 + */ struct _GstD3D11Device { GstObject parent; @@ -50,6 +64,13 @@ struct _GstD3D11Device gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstD3D11DeviceClass: + * + * Opaque GstD3D11DeviceClass struct + * + * Since: 1.22 + */ struct _GstD3D11DeviceClass { GstObjectClass parent_class; @@ -98,6 +119,13 @@ gboolean gst_d3d11_device_get_format (GstD3D11Device * devi GstVideoFormat format, GstD3D11Format * device_format); +/** + * GstD3D11Fence: + * + * An abstraction of the ID3D11Fence interface + * + * Since: 1.22 + */ struct _GstD3D11Fence { GstMiniObject parent; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.cpp index f79ad5c..af6ee93 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.cpp @@ -25,10 +25,18 @@ #include "gstd3d11utils.h" #include "gstd3d11device.h" #include "gstd3d11memory.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include +/** + * SECTION:gstd3d11format + * @title: GstD3D11Format + * @short_description: Bridge of Direct3D11 and GStreamer video format representation + * + * Since: 1.22 + */ + #ifndef GST_DISABLE_GST_DEBUG #define GST_CAT_DEFAULT ensure_debug_category() static GstDebugCategory * diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.h index 3dc55cc..15ba733 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11format.h @@ -43,6 +43,13 @@ G_BEGIN_DECLS #define GST_D3D11_ALL_FORMATS \ "{ " GST_D3D11_COMMON_FORMATS " ," GST_D3D11_EXTRA_IN_FORMATS " }" +/** + * GstD3D11Format: + * + * Represent video format information in Direct3D11 term. + * + * Since: 1.22 + */ struct _GstD3D11Format { GstVideoFormat format; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.cpp index 2a2f3c8..3707e21 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.cpp @@ -26,7 +26,15 @@ #include "gstd3d11memory.h" #include "gstd3d11device.h" #include "gstd3d11utils.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" + +/** + * SECTION:gstd3d11memory + * @title: GstD3D11Memory + * @short_description: Direct3D11 memory abstraction layer + * + * Since: 1.22 + */ GST_DEBUG_CATEGORY_STATIC (gst_d3d11_allocator_debug); #define GST_CAT_DEFAULT gst_d3d11_allocator_debug @@ -237,7 +245,7 @@ gst_d3d11_allocation_params_alignment (GstD3D11AllocationParams * params, * gst_d3d11_allocation_params_copy: * @src: a #GstD3D11AllocationParams * - * Returns: a copy of @src + * Returns: (transfer full): a copy of @src * * Since: 1.22 */ diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.h b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.h index 2e0ce6f..e4ec529 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11memory.h @@ -133,15 +133,20 @@ GST_D3D11_API GType gst_d3d11_memory_native_type_get_type (void); #define GST_TYPE_D3D11_MEMORY_NATIVE_TYPE (gst_d3d11_memory_native_type_get_type()) +/** + * GstD3D11AllocationParams: + * + * Contains set of parameters for #GstD3D11Memory allocation + * + * Since: 1.22 + */ struct _GstD3D11AllocationParams { /* Texture description per plane */ D3D11_TEXTURE2D_DESC desc[GST_VIDEO_MAX_PLANES]; - GstVideoInfo info; GstVideoInfo aligned_info; GstD3D11Format d3d11_format; - GstD3D11AllocationFlags flags; /*< private >*/ @@ -168,6 +173,13 @@ GST_D3D11_API gboolean gst_d3d11_allocation_params_alignment (GstD3D11AllocationParams * parms, const GstVideoAlignment * align); +/** + * GstD3D11Memory: + * + * Represents information about a Direct3D11 memory object + * + * Since: 1.22 + */ struct _GstD3D11Memory { GstMemory mem; @@ -237,19 +249,30 @@ ID3D11VideoProcessorOutputView * gst_d3d11_memory_get_processor_output_view (Gs ID3D11VideoDevice * video_device, ID3D11VideoProcessorEnumerator * enumerator); +/** + * GstD3D11Allocator: + * + * A Direct3D11 memory allocator + * + * Since: 1.22 + */ struct _GstD3D11Allocator { - GstAllocator allocator; + GstAllocator parent; /*< private >*/ GstD3D11AllocatorPrivate *priv; - gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstD3D11AllocatorClass: + * + * Since: 1.22 + */ struct _GstD3D11AllocatorClass { - GstAllocatorClass allocator_class; + GstAllocatorClass parent_class; gboolean (*set_actvie) (GstD3D11Allocator * allocator, gboolean active); @@ -283,22 +306,35 @@ GST_D3D11_API gboolean gst_d3d11_allocator_set_active (GstD3D11Allocator * allocator, gboolean active); +/** + * GstD3D11PoolAllocator: + * + * Allocates #GstD3D11Memory objects and pooling allocated memory + * + * Since: 1.22 + */ struct _GstD3D11PoolAllocator { - GstD3D11Allocator allocator; + GstD3D11Allocator parent; /*< public >*/ GstD3D11Device *device; /*< private >*/ GstD3D11PoolAllocatorPrivate *priv; - gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstD3D11PoolAllocatorClass: + * + * Opaque GstD3D11PoolAllocatorClass struct + * + * Since: 1.22 + */ struct _GstD3D11PoolAllocatorClass { - GstD3D11AllocatorClass allocator_class; + GstD3D11AllocatorClass parent_class; /*< private >*/ gpointer _gst_reserved[GST_PADDING]; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11utils.cpp b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11utils.cpp index a2b0a41..b311af3a 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11utils.cpp +++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11utils.cpp @@ -23,12 +23,20 @@ #include "gstd3d11utils.h" #include "gstd3d11device.h" -#include "gstd3d11_private.h" +#include "gstd3d11-private.h" #include #include #include +/** + * SECTION:gstd3d11utils + * @title: GstD3D11Utils + * @short_description: Direct3D11 specific utility methods + * + * Since: 1.22 + */ + /* *INDENT-OFF* */ static std::recursive_mutex _context_lock; /* *INDENT-ON* */ @@ -505,7 +513,6 @@ gst_d3d11_ensure_element_data_for_adapter_luid (GstElement * element, * * Since: 1.22 */ - GstContext * gst_d3d11_context_new (GstD3D11Device * device) { @@ -523,7 +530,7 @@ gst_d3d11_context_new (GstD3D11Device * device) * gst_d3d11_luid_to_int64: * @luid: A pointer to LUID struct * - * Converts from a LUID to a 64-bit signed integer. + * Converts @luid to a 64-bit signed integer. * See also Int64FromLuid method defined in * windows.devices.display.core.interop.h Windows SDK header * @@ -542,6 +549,21 @@ gst_d3d11_luid_to_int64 (const LUID * luid) return val.QuadPart; } +/** + * _gst_d3d11_result: + * @result: HRESULT D3D11 API return code + * @device: (nullable): Associated #GstD3D11Device + * @cat: a #GstDebugCategory + * @file: the file that checking the result code + * @function: the function that checking the result code + * @line: the line that checking the result code + * + * Prints debug message if @result code indicates the operation was failed. + * + * Returns: %TRUE if D3D11 API call result is SUCCESS + * + * Since: 1.22 + */ gboolean _gst_d3d11_result (HRESULT hr, GstD3D11Device * device, GstDebugCategory * cat, const gchar * file, const gchar * function, gint line) diff --git a/subprojects/gst-plugins-bad/sys/d3d11/gstd3d11pluginutils.h b/subprojects/gst-plugins-bad/sys/d3d11/gstd3d11pluginutils.h index 5915d51..30aa631 100644 --- a/subprojects/gst-plugins-bad/sys/d3d11/gstd3d11pluginutils.h +++ b/subprojects/gst-plugins-bad/sys/d3d11/gstd3d11pluginutils.h @@ -24,7 +24,7 @@ #include #include #include -#include +#include G_BEGIN_DECLS -- 2.7.4