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>
2024-12-19 14:56:36 +00:00 · 2022-08-26 00:16:56 +09:00 · 2022-08-26 00:16:56 +09:00 · c3cf9521a5
commit c3cf9521a5
parent 21ac55bac2
14 changed files with 195 additions and 29 deletions
--- a/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11-private.h
+++ b/subprojects/gst-plugins-bad/gst-libs/gst/d3d11/gstd3d11-private.h
--- 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);
--- 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];
--- 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,
--- 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

--- 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;
--- 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
--- 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;
--- 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 *
--- 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;
--- 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
 */
--- 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];
--- 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)
--- 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