From 69da10445624a5ebcb0378f965dc8856e063c7ae Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Fri, 13 Jan 2017 11:08:10 +1100 Subject: [PATCH] glutils: document functions --- ext/gl/gstglimagesink.c | 1 + gst-libs/gst/gl/gstglfeature.c | 7 ++++ gst-libs/gst/gl/gstglutils.c | 87 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 92 insertions(+), 3 deletions(-) diff --git a/ext/gl/gstglimagesink.c b/ext/gl/gstglimagesink.c index 79ef08e..9779aab 100644 --- a/ext/gl/gstglimagesink.c +++ b/ext/gl/gstglimagesink.c @@ -93,6 +93,7 @@ #include "gstglimagesink.h" #include "gstglsinkbin.h" +#include "gstglutils.h" #include diff --git a/gst-libs/gst/gl/gstglfeature.c b/gst-libs/gst/gl/gstglfeature.c index 7b9b7ec..56fd0fe 100644 --- a/gst-libs/gst/gl/gstglfeature.c +++ b/gst-libs/gst/gl/gstglfeature.c @@ -43,6 +43,13 @@ _init_debug (void) } } +/** + * gst_gl_check_extension: + * @name: the extension to search for + * @ext: the list of possible extensions + * + * Returns: whether @name is in the space seperated list of @ext + */ gboolean gst_gl_check_extension (const char *name, const gchar * ext) { diff --git a/gst-libs/gst/gl/gstglutils.c b/gst-libs/gst/gl/gstglutils.c index fb19156..2b97111 100644 --- a/gst-libs/gst/gl/gstglutils.c +++ b/gst-libs/gst/gl/gstglutils.c @@ -241,15 +241,40 @@ gst_gl_display_context_propagate (GstElement * element, GstGLDisplay * display) gst_element_post_message (GST_ELEMENT_CAST (element), msg); } +/** + * gst_gl_ensure_element_data: + * @element: the #GstElement running the query + * @display_ptr: (inout): the resulting #GstGLDisplay + * @other_context_ptr: (inout): the resulting #GstGLContext + * + * Perform the steps necessary for retrieving a #GstGLDisplay and (optionally) + * an application provided #GstGLContext from the surrounding elements or from + * the application using the #GstContext mechanism. + * + * If the contents of @display_ptr or @other_context_ptr are not %NULL, then no + * #GstContext query is necessary for #GstGLDisplay or #GstGLContext retrieval + * or is performed. + * + * This performs #GstContext queries (if necessary) for a winsys display + * connection with %GST_GL_DISPLAY_CONTEXT_TYPE, "gst.x11.display.handle", and + * "GstWaylandDisplayHandleContextType" stopping after the first successful + * retrieval. + * + * This also performs a #GstContext query (if necessary) for an optional + * application provided #GstGLContext using the name "gst.gl.app_context". + * The returned #GstGLContext will be shared with a GStreamer created OpenGL context. + * + * Returns: whether a #GstGLDisplay exists in @display_ptr + */ gboolean gst_gl_ensure_element_data (gpointer element, GstGLDisplay ** display_ptr, - GstGLContext ** context_ptr) + GstGLContext ** other_context_ptr) { GstGLDisplay *display; g_return_val_if_fail (element != NULL, FALSE); g_return_val_if_fail (display_ptr != NULL, FALSE); - g_return_val_if_fail (context_ptr != NULL, FALSE); + g_return_val_if_fail (other_context_ptr != NULL, FALSE); /* 1) Check if the element already has a context of the specific * type. @@ -272,7 +297,7 @@ gst_gl_ensure_element_data (gpointer element, GstGLDisplay ** display_ptr, gst_gl_display_context_propagate (element, display); get_gl_context: - if (*context_ptr) + if (*other_context_ptr) goto done; gst_gl_context_query (element); @@ -281,6 +306,21 @@ done: return *display_ptr != NULL; } +/** + * gst_gl_handle_set_context: + * @element: a #GstElement + * @context: a #GstContext + * @display: (inout) (transfer full): location of a #GstGLDisplay + * @other_context: (inout) (transfer full): location of a #GstGLContext + * + * Helper function for implementing GstElement::set_context() in OpenGL capable + * elements. + * + * Retrieve's the #GstGLDisplay or #GstGLContext in @context and places the + * result in @display or @other_context respectively. + * + * Returns: whether the @display or @other_context could be set successfully + */ gboolean gst_gl_handle_set_context (GstElement * element, GstContext * context, GstGLDisplay ** display, GstGLContext ** other_context) @@ -366,6 +406,17 @@ gst_gl_handle_set_context (GstElement * element, GstContext * context, return TRUE; } +/** + * gst_gl_handle_context_query: + * @element: a #GstElement + * @query: a #GstQuery of type %GST_QUERY_CONTEXT + * @display: (transfer none) (nullable): a #GstGLDisplay + * @context: (transfer none) (nullable): a #GstGLContext + * @other_context: (transfer none) (nullable): application provided #GstGLContext + * + * Returns: Whether the @query was successfully responded to from the passed + * @display, @context, and @other_context. + */ gboolean gst_gl_handle_context_query (GstElement * element, GstQuery * query, GstGLDisplay * display, GstGLContext * gl_context, @@ -507,6 +558,19 @@ gst_gl_handle_context_query (GstElement * element, GstQuery * query, return FALSE; } +/** + * gst_gl_query_local_gl_context: + * @element: a #GstElement to query from + * @direction: the #GstPadDirection to query + * @context_ptr: (inout): location containing the current and/or resulting + * #GstGLContext + * + * Performs a GST_QUERY_CONTEXT query of type "gst.gl.local_context" on all + * #GstPads in @element of @direction for the local OpenGL context used by + * GStreamer elements. + * + * Returns: whether @context_ptr contains a #GstGLContext + */ gboolean gst_gl_query_local_gl_context (GstElement * element, GstPadDirection direction, GstGLContext ** context_ptr) @@ -535,6 +599,14 @@ gst_gl_query_local_gl_context (GstElement * element, GstPadDirection direction, return *context_ptr != NULL; } +/** + * gst_gl_get_plane_data_size: + * @info: a #GstVideoInfo + * @align: a #GstVideoAlignment or %NULL + * @plane: plane number in @info to retrieve the data size of + * + * Retrieve the size in bytes of a video plane of data with a certain alignment + */ gsize gst_gl_get_plane_data_size (GstVideoInfo * info, GstVideoAlignment * align, guint plane) @@ -555,6 +627,15 @@ gst_gl_get_plane_data_size (GstVideoInfo * info, GstVideoAlignment * align, return plane_size; } +/** + * gst_gl_get_plane_start: + * @info: a #GstVideoInfo + * @valign: a #GstVideoAlignment or %NULL + * @plane: plane number in @info to retrieve the data size of + * + * Returns: difference between the supposed start of the plane from the @info + * and where the data from the previous plane ends. + */ gsize gst_gl_get_plane_start (GstVideoInfo * info, GstVideoAlignment * valign, guint plane) -- 2.7.4