From: Seungha Yang <seungha@centricular.com>
Date: Thu, 25 Aug 2022 15:16:56 +0000 (+0900)
Subject: d3d11: Update library doc
X-Git-Tag: 1.22.0~1043
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c3cf9521a58286c1242d8548b096c644b8a76a78;p=platform%2Fupstream%2Fgstreamer.git

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: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/2945>
---

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 <string.h>
 
 /**
  * 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 <gmodule.h>
 #include <wrl.h>
 #include <string.h>
 
+/**
+ * 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 <config.h>
 #endif
 
-#include "gstd3d11_private.h"
+#include "gstd3d11-private.h"
 #include "gstd3d11converter.h"
 #include "gstd3d11device.h"
 #include "gstd3d11utils.h"
@@ -34,6 +34,17 @@
 #include <string.h>
 #include <math.h>
 
+/**
+ * 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 <gmodule.h>
 #include <wrl.h>
@@ -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 <string.h>
 
+/**
+ * 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 <windows.h>
 #include <versionhelpers.h>
 #include <mutex>
 
+/**
+ * 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 <gst/gst.h>
 #include <gst/video/video.h>
 #include <gst/d3d11/gstd3d11.h>
-#include <gst/d3d11/gstd3d11_private.h>
+#include <gst/d3d11/gstd3d11-private.h>
 
 G_BEGIN_DECLS