From d09aae68a54504e005ef48e5bee2e8b9a754641b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Manuel=20J=C3=A1quez=20Leal?= Date: Thu, 13 May 2021 10:27:49 +0200 Subject: [PATCH] libs: va: Documentation and annotations. Part-of: --- gst-libs/gst/va/gstvadisplay.c | 18 ++++++++++++++ gst-libs/gst/va/gstvadisplay.h | 17 +++++++++---- gst-libs/gst/va/gstvadisplay_drm.c | 30 +++++++++++++++++++---- gst-libs/gst/va/gstvadisplay_wrapped.c | 33 +++++++++++++++++++++++--- 4 files changed, 87 insertions(+), 11 deletions(-) diff --git a/gst-libs/gst/va/gstvadisplay.c b/gst-libs/gst/va/gstvadisplay.c index 65a0511aae..4d6c739746 100644 --- a/gst-libs/gst/va/gstvadisplay.c +++ b/gst-libs/gst/va/gstvadisplay.c @@ -18,6 +18,24 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstvadisplay + * @title: GstVaDisplay + * @short_description: Generic VADisplay wrapper. + * @sources: + * - gstvadisplay.h + * + * It is a generic wrapper for VADisplay. To create new instances + * subclasses are required, depending on the display type to use + * (v.gr. DRM, X11, Wayland, etc.). + * + * The purpose of this class is to be shared among pipelines via + * #GstContext so all the VA processing elements will use the same + * display entry. Application developers can create their own + * subclass, based on their display, and shared it via the synced bus + * message for the application. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/gst-libs/gst/va/gstvadisplay.h b/gst-libs/gst/va/gstvadisplay.h index 09def14daa..a4f4fcb2a8 100644 --- a/gst-libs/gst/va/gstvadisplay.h +++ b/gst-libs/gst/va/gstvadisplay.h @@ -60,6 +60,8 @@ typedef enum * * Check whether the display is the implementation of the specified * #GstVaImplementation type. + * + * Since: 1.20 */ #define GST_VA_DISPLAY_IS_IMPLEMENTATION(display, impl) \ (gst_va_display_is_implementation (display, G_PASTE (GST_VA_IMPLEMENTATION_, impl))) @@ -73,6 +75,7 @@ typedef enum /** * GstVaDisplay: + * @parent: parent #GstObject * * The common VA display object structure. * @@ -80,24 +83,30 @@ typedef enum */ struct _GstVaDisplay { - /*< private > */ GstObject parent; }; /** * GstVaDisplayClass: + * @parent_class: parent #GstObjectClass * * The common VA display object class structure. - * @create_va_display: The function to create the real VA display. * * Since: 1.20 */ struct _GstVaDisplayClass { - /*< private > */ GstObjectClass parent_class; - /*< public > */ + /** + * GstVaDisplayClass::create_va_display: + * @self: a #GstVaDisplay instance + * + * This is called when the subclass has to create the internal + * VADisplay. + * + * Returns: The created VADisplay + */ gpointer (*create_va_display) (GstVaDisplay * self); }; diff --git a/gst-libs/gst/va/gstvadisplay_drm.c b/gst-libs/gst/va/gstvadisplay_drm.c index 092bab58b3..d2a32fb529 100644 --- a/gst-libs/gst/va/gstvadisplay_drm.c +++ b/gst-libs/gst/va/gstvadisplay_drm.c @@ -18,6 +18,16 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstvadisplaydrm + * @title: GstVaDisplayDrm + * @short_description: VADisplay from a DRM device + * @sources: + * - gstvadisplay_drm.h + * + * This is a #GstVaDisplay subclass to instantiate with DRM devices. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -33,17 +43,29 @@ #include #endif +/** + * GstVaDisplayDrm: + * @parent: parent #GstVaDisplay + * + * Since: 1.20 + */ struct _GstVaDisplayDrm { GstVaDisplay parent; + /* */ gchar *path; gint fd; }; +/** + * GstVaDisplayDrmClass: + * @parent_class: parent #GstVaDisplayClass + * + * Since: 1.20 + */ struct _GstVaDisplayDrmClass { - /*< private > */ GstVaDisplayClass parent_class; }; @@ -173,9 +195,9 @@ gst_va_display_drm_init (GstVaDisplayDrm * self) * Creates a new #GstVaDisplay from a DRM device . It will try to open * and operate the device in @path. * - * Returns: a newly allocated #GstVaDisplay if the specified DRM - * render device could be opened and initialized; otherwise %NULL - * is returned. + * Returns: (transfer full): a newly allocated #GstVaDisplay if the + * specified DRM render device could be opened and initialized; + * otherwise %NULL is returned. * * Since: 1.20 **/ diff --git a/gst-libs/gst/va/gstvadisplay_wrapped.c b/gst-libs/gst/va/gstvadisplay_wrapped.c index 4626a2f791..a153871e34 100644 --- a/gst-libs/gst/va/gstvadisplay_wrapped.c +++ b/gst-libs/gst/va/gstvadisplay_wrapped.c @@ -18,20 +18,42 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstvadisplaywrapped + * @title: GstVaDisplayWrapped + * @short_description: User's custom VADisplay + * @sources: + * - gstvadisplay_wrapped.h + * + * This is a #GstVaDisplay instantiaton subclass for custom created + * VADisplay, such as X11 or Wayland, wrapping it. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif #include "gstvadisplay_wrapped.h" +/** + * GstVaDisplayWrapped: + * @parent: parent #GstVaDisplay + * + * Since: 1.20 + */ struct _GstVaDisplayWrapped { GstVaDisplay parent; }; +/** + * GstVaDisplayWrappedClass: + * @parent_class: parent #GstVaDisplayClass + * + * Since: 1.20 + */ struct _GstVaDisplayWrappedClass { - /*< private > */ GstVaDisplayClass parent_class; }; @@ -51,12 +73,17 @@ gst_va_display_wrapped_init (GstVaDisplayWrapped * self) /** * gst_va_display_wrapped_new: - * @handle: a #VADisplay to wrap + * @handle: a VADisplay to wrap * * Creates a #GstVaDisplay wrapping an already created and initialized * VADisplay. * - * Returns: a new #GstVaDisplay if @handle is valid, Otherwise %NULL. + * The lifetime of @handle must be hold by the provider while the + * pipeline is instantiated. Do not call vaTerminate on it while the + * pipeline is not in NULL state. + * + * Returns: (transfer full): a new #GstVaDisplay if @handle is valid, + * Otherwise %NULL. * * Since: 1.20 **/