Skip to content

GitLab

Commit 51a6f47b authored by Matthew Waters's avatar Matthew Waters 🐨 Committed by Tim-Philipp Müller
Browse files

gl/docs: document new API added in 1.10 

GstGLRenderbuffer
GstGLFramebuffer
GstGLQuery
GstEGLImage
GstGLMemoryEGL
parent 8faebcf9
Hide whitespace changes
Inline Side-by-side
gst-libs/gst/gl/egl/gsteglimage.c
View file @ 51a6f47b
......@@ -21,6 +21,19 @@
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION:gsteglimage
* @short_description: EGLImage abstraction
* @title: GstEGLImage
* @see_also: #GstGLMemoryEGL, #GstGLContext
*
* #GstEGLImage represents and holds an #EGLImage handle.
*
* A #GstEGLImage can be created from a dmabuf with gst_egl_image_from_dmabuf()
* or #GstGLMemoryEGL provides a #GstAllocator to allocate #EGLImage's bound to
* and OpenGL texture.
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
......@@ -90,6 +103,12 @@ gst_egl_image_ensure_debug_category (void)
#endif /* GST_DISABLE_GST_DEBUG */
#endif /* GST_GL_HAVE_DMABUF */
/**
* gst_egl_image_get_image:
* @image: a #GstEGLImage
*
* Returns: the #EGLImageKHR of @image
*/
EGLImageKHR
gst_egl_image_get_image (GstEGLImage * image)
{
......@@ -98,6 +117,12 @@ gst_egl_image_get_image (GstEGLImage * image)
return image->image;
}
/**
* gst_egl_image_get_orientation:
* @image: a #GstEGLImage
*
* Returns: the orientation of @image
*/
GstVideoGLTextureOrientation
gst_egl_image_get_orientation (GstEGLImage * image)
{
......@@ -132,6 +157,17 @@ _gst_egl_image_copy (GstMiniObject * obj)
return gst_mini_object_ref (obj);
}
/**
* gst_egl_image_new_wrapped:
* @context: a #GstGLContext (must be an EGL context)
* @image: the image to wrap
* @type: the #GstVideoGLTextureType
* @orientation: the #GstVideoGLTextureOrientation
* @user_data: user data
* @user_data_destroy: called when @user_data is no longer needed
*
* Returns: a new #GstEGLImage wrapping @image
*/
GstEGLImage *
gst_egl_image_new_wrapped (GstGLContext * context, EGLImageKHR image,
GstVideoGLTextureType type, GstVideoGLTextureOrientation orientation,
......@@ -236,6 +272,16 @@ _destroy_egl_image (GstEGLImage * image, gpointer user_data)
image->context->eglDestroyImage (image->context->egl_display, image->image);
}
/**
* gst_egl_image_from_dmabuf:
* @context: a #GstGLContext (must be an EGL context)
* @dmabuf: the DMA-Buf file descriptor
* @in_info: the #GstVideoInfo in @dmabuf
* @plane: the plane in @in_info to create and #GstEGLImage for
* @offset: the byte-offset in the data
*
* Returns: a #GstEGLImage wrapping @dmabuf or %NULL on failure
*/
GstEGLImage *
gst_egl_image_from_dmabuf (GstGLContext * context,
gint dmabuf, GstVideoInfo * in_info, gint plane, gsize offset)
......
gst-libs/gst/gl/egl/gsteglimage.h
View file @ 51a6f47b
......@@ -42,6 +42,11 @@ typedef struct _GstEGLImage GstEGLImage;
typedef void (*GstEGLImageDestroyNotify) (GstEGLImage * image,
gpointer data);
/**
* GstEGLImage:
*
* Opaque #GstEGLImage struct.
*/
struct _GstEGLImage
{
GstMiniObject parent;
......@@ -89,8 +94,8 @@ gst_egl_image_ref (GstEGLImage * image)
}
/**
* gst_buffer_unref:
* @buf: (transfer full): a #GstBuffer.
* gst_egl_image_unref:
* @image: (transfer full): a #GstEGLImage.
*
* Decreases the refcount of the image. If the refcount reaches 0, the image
* with the associated metadata and memory will be freed.
......
gst-libs/gst/gl/egl/gstglmemoryegl.c
View file @ 51a6f47b
......@@ -39,6 +39,14 @@ GST_DEBUG_CATEGORY_STATIC (GST_CAT_GL_MEMORY);
G_DEFINE_TYPE (GstGLMemoryEGLAllocator, gst_gl_memory_egl_allocator,
GST_TYPE_GL_MEMORY_ALLOCATOR);
/**
* gst_is_gl_memory_egl:
* @mem: a #GstMemory to test
*
* Returns: whether @mem is a #GstGLMemoryEGL
*
* Since: 1.10
*/
gboolean
gst_is_gl_memory_egl (GstMemory * mem)
{
......@@ -54,6 +62,14 @@ _gl_mem_get_parent (GstGLMemoryEGL * gl_mem)
return parent ? parent : gl_mem;
}
/**
* gst_gl_memory_egl_get_image:
* @mem: a #GstGLMemoryEGL
*
* Returns: The EGLImage held by @mem
*
* Since: 1.10
*/
EGLImageKHR
gst_gl_memory_egl_get_image (GstGLMemoryEGL * mem)
{
......@@ -62,6 +78,14 @@ gst_gl_memory_egl_get_image (GstGLMemoryEGL * mem)
return gst_egl_image_get_image (_gl_mem_get_parent (mem)->image);
}
/**
* gst_gl_memory_egl_get_display:
* @mem: a #GstGLMemoryEGL
*
* Returns: The EGLDisplay @mem is associated with
*
* Since: 1.10
*/
EGLDisplay
gst_gl_memory_egl_get_display (GstGLMemoryEGL * mem)
{
......@@ -70,6 +94,14 @@ gst_gl_memory_egl_get_display (GstGLMemoryEGL * mem)
context)->egl_display;
}
/**
* gst_gl_memory_egl_get_orientation:
* @mem: a #GstGLMemoryEGL
*
* Returns: The orientation of @mem
*
* Since: 1.10
*/
GstVideoGLTextureOrientation
gst_gl_memory_egl_get_orientation (GstGLMemoryEGL * mem)
{
......@@ -225,6 +257,8 @@ gst_gl_memory_egl_allocator_init (GstGLMemoryEGLAllocator * allocator)
*
* Initializes the GL Memory allocator. It is safe to call this function
* multiple times. This must be called before any other GstGLMemoryEGL operation.
*
* Since: 1.10
*/
void
gst_gl_memory_egl_init_once (void)
......
gst-libs/gst/gl/egl/gstglmemoryegl.h
View file @ 51a6f47b
......@@ -53,13 +53,14 @@ GType gst_gl_memory_egl_allocator_get_type(void);
*/
struct _GstGLMemoryEGL
{
/* <private> */
GstGLMemory mem;
GstEGLImage *image;
};
/**
* GST_GL_MEMORY_EGL_ALLOCATOR:
* GST_GL_MEMORY_EGL_ALLOCATOR_NAME:
*
* The name of the GL Memory EGL allocator
*/
......@@ -75,22 +76,25 @@ GstVideoGLTextureOrientation gst_gl_memory_egl_get_orientation
(GstGLMemoryEGL * mem);
/**
* GstGLAllocator
* GstGLMemoryEGLAllocator
*
* Opaque #GstGLAllocator struct
* Opaque #GstGLMemoryEGLAllocator struct
*/
struct _GstGLMemoryEGLAllocator
{
/* <private> */
GstGLMemoryAllocator parent;
};
/**
* GstGLAllocatorClass:
* GstGLMemoryEGLAllocatorClass:
*
* The #GstGLAllocatorClass only contains private data
* The #GstGLMemoryEGLAllocatorClass only contains private data
*/
struct _GstGLMemoryEGLAllocatorClass
{
/* <private> */
GstGLMemoryAllocatorClass parent_class;
};
......
gst-libs/gst/gl/gstglframebuffer.c
View file @ 51a6f47b
......@@ -17,6 +17,27 @@
* Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION:gstglframebuffer
* @short_description: OpenGL framebuffer abstraction
* @title: GstGLFramebuffer
* @see_also: #GstGLBaseMemory, #GstGLMemory, #GstGLContext
*
* A #GstGLFramebuffer represents and holds an OpenGL framebuffer object with
* it's associated attachments.
*
* A #GstGLFramebuffer can be created with gst_gl_framebuffer_new() or
* gst_gl_framebuffer_new_with_default_depth() and bound with
* gst_gl_framebuffer_bind(). Other resources can be bound with
* gst_gl_framebuffer_attach()
*
* Note: OpenGL framebuffers are not shareable resources so cannot be used
* between multiple OpenGL contexts.
*
* Since: 1.10
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
......@@ -139,6 +160,14 @@ gst_gl_framebuffer_finalize (GObject * object)
G_OBJECT_CLASS (gst_gl_framebuffer_parent_class)->finalize (object);
}
/**
* gst_gl_framebuffer_new:
* @context: a #GstGLContext
*
* Returns: a new #GstGLFramebuffer
*
* Since: 1.10
*/
GstGLFramebuffer *
gst_gl_framebuffer_new (GstGLContext * context)
{
......@@ -162,6 +191,16 @@ gst_gl_framebuffer_new (GstGLContext * context)
return fb;
}
/**
* gst_gl_framebuffer_new_with_default_depth:
* @context: a #GstGLContext
* @width: width for the depth buffer
* @height: for the depth buffer
*
* Returns: a new #GstGLFramebuffer with a depth buffer of @width and @height
*
* Since: 1.10
*/
GstGLFramebuffer *
gst_gl_framebuffer_new_with_default_depth (GstGLContext * context, guint width,
guint height)
......@@ -205,6 +244,20 @@ gst_gl_framebuffer_new_with_default_depth (GstGLContext * context, guint width,
return fb;
}
/**
* gst_gl_framebuffer_draw_to_texture:
* @fb: a #GstGLFramebuffer
* @mem: the #GstGLMemory to draw to
* @func: the function to run
* @user_data: data to pass to @func
*
* Perform the steps necessary to have the output of a glDraw* command in
* @func update the contents of @mem.
*
* Returns: the result of executing @func
*
* Since: 1.10
*/
gboolean
gst_gl_framebuffer_draw_to_texture (GstGLFramebuffer * fb, GstGLMemory * mem,
GstGLFramebufferFunc func, gpointer user_data)
......@@ -243,6 +296,14 @@ gst_gl_framebuffer_draw_to_texture (GstGLFramebuffer * fb, GstGLMemory * mem,
return ret;
}
/**
* gst_gl_framebuffer_bind:
* @fb: a #GstGLFramebuffer
*
* Bind @fb into the current thread
*
* Since: 1.10
*/
void
gst_gl_framebuffer_bind (GstGLFramebuffer * fb)
{
......@@ -257,6 +318,14 @@ gst_gl_framebuffer_bind (GstGLFramebuffer * fb)
gl->BindFramebuffer (GL_FRAMEBUFFER, fb->fbo_id);
}
/**
* gst_gl_context_clear_framebuffer:
* @context: a #GstGLContext
*
* Unbind the current framebuffer
*
* Since: 1.10
*/
void
gst_gl_context_clear_framebuffer (GstGLContext * context)
{
......@@ -362,6 +431,16 @@ _attach_renderbuffer (GstGLFramebuffer * fb, guint attachment_point,
fb->attachments = g_array_append_val (fb->attachments, attach);
}
/**
* gst_gl_framebuffer_attach:
* @fb: a #GstGLFramebuffer
* @attachment_point: the OpenGL attachment point to bind @mem to
* @mem: the memory object to bind to @attachment_point
*
* attach @mem to @attachment_point
*
* Since: 1.10
*/
void
gst_gl_framebuffer_attach (GstGLFramebuffer * fb, guint attachment_point,
GstGLBaseMemory * mem)
......@@ -396,6 +475,17 @@ gst_gl_framebuffer_attach (GstGLFramebuffer * fb, guint attachment_point,
_update_effective_dimensions (fb);
}
/**
* gst_gl_framebuffer_get_effective_dimensions:
* @fb: a #GstGLFramebuffer
* @width: (out) (allow-none): output width
* @height: (out) (allow-none): output height
*
* Retreive the effective dimensions from the current attachments attached to
* @fb.
*
* Since: 1.10
*/
void
gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb,
guint * width, guint * height)
......@@ -408,6 +498,14 @@ gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb,
*height = fb->priv->effective_height;
}
/**
* gst_gl_context_check_framebuffer_status:
* @context: a #GstGLContext
*
* Returns: whether whether the current framebuffer is complete
*
* Since: 1.10
*/
gboolean
gst_gl_context_check_framebuffer_status (GstGLContext * context)
{
......@@ -443,6 +541,14 @@ gst_gl_context_check_framebuffer_status (GstGLContext * context)
return FALSE;
}
/**
* gst_gl_framebuffer_get_id:
* @fb: a #GstGLFramebuffer
*
* Returns: the OpenGL id for @fb
*
* Since: 1.10
*/
guint
gst_gl_framebuffer_get_id (GstGLFramebuffer * fb)
{
......
gst-libs/gst/gl/gstglframebuffer.h
View file @ 51a6f47b
......@@ -40,19 +40,24 @@ typedef struct _GstGLFramebufferPrivate GstGLFramebufferPrivate;
/**
* GstGLFramebufferFunc:
* @data: user data
* @stuff: user data
*
* callback definition for operating through a Framebuffer object
* callback definition for operating through a #GstGLFramebuffer object
*/
typedef gboolean (*GstGLFramebufferFunc) (gpointer stuff);
/**
* GstGLFramebuffer:
*
* Opaque #GstGLFramebuffer struct
*/
struct _GstGLFramebuffer
{
/* <private> */
GstObject object;
GstGLContext *context;
/* <private> */
guint fbo_id;
GArray *attachments;
......@@ -61,8 +66,14 @@ struct _GstGLFramebuffer
GstGLFramebufferPrivate *priv;
};
/**
* GstGLFramebufferClass:
*
* Opaque #GstGLFramebufferClass struct
*/
struct _GstGLFramebufferClass
{
/* <private> */
GstObjectClass object_class;
gpointer _padding[GST_PADDING];
......
gst-libs/gst/gl/gstglquery.c
View file @ 51a6f47b
......@@ -18,6 +18,18 @@
* Boston, MA 02110-1301, USA.
*/
/**
* SECTION:gstglquery
* @short_description: OpenGL query abstraction
* @title: GstGLQuery
* @see_also:
*
* A #GstGLQuery represents and holds an OpenGL query object. Various types of
* queries can be run or counters retrieved.
*
* Since: 1.10
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
......@@ -110,6 +122,14 @@ _log_time (gpointer user_data)
return gst_info_strdup_printf ("%" GST_TIME_FORMAT, GST_TIME_ARGS (result));
}
/**
* gst_gl_query_init:
* @query: a #GstGLQuery
* @context: a #GstGLContext
* @query_type: the #GstGLQueryType
*
* Since: 1.10
*/
void
gst_gl_query_init (GstGLQuery * query, GstGLContext * context,
GstGLQueryType query_type)
......@@ -136,6 +156,14 @@ gst_gl_query_init (GstGLQuery * query, GstGLContext * context,
query->debug.user_data = query;
}
/**
* gst_gl_query_unset:
* @query: a #GstGLQuery
*
* Free any dynamically allocated resources
*
* Since: 1.10
*/
void
gst_gl_query_unset (GstGLQuery * query)
{
......@@ -159,6 +187,17 @@ gst_gl_query_unset (GstGLQuery * query)
gst_object_unref (query->context);
}
/**
* gst_gl_query_new:
* @context: a #GstGLContext
* @query_type: the #GstGLQueryType to create
*
* Free with gst_gl_query_free()
*
* Returns: a new #GstGLQuery
*
* Since: 1.10
*/
GstGLQuery *
gst_gl_query_new (GstGLContext * context, GstGLQueryType query_type)
{
......@@ -169,6 +208,14 @@ gst_gl_query_new (GstGLContext * context, GstGLQueryType query_type)
return query;
}
/**
* gst_gl_query_free:
* @query: a #GstGLQuery
*
* Frees a #GstGLQuery
*
* Since: 1.10
*/
void
gst_gl_query_free (GstGLQuery * query)
{
......@@ -178,6 +225,14 @@ gst_gl_query_free (GstGLQuery * query)
g_free (query);
}
/**
* gst_gl_query_start:
* @query: a #GstGLQuery
*
* Start counting the query
*
* Since: 1.10
*/
void
gst_gl_query_start (GstGLQuery * query)
{
......@@ -199,6 +254,14 @@ gst_gl_query_start (GstGLQuery * query)
gl->BeginQuery (query->query_type, query->query_id);
}
/**
* gst_gl_query_end:
* @query: a #GstGLQuery
*
* End counting the query
*
* Since: 1.10
*/
void
gst_gl_query_end (GstGLQuery * query)
{
......@@ -220,6 +283,14 @@ gst_gl_query_end (GstGLQuery * query)
query->start_called = FALSE;
}
/**
* gst_gl_query_counter:
* @query: a #GstGLQuery
*
* Record the result of a counter
*
* Since: 1.10
*/
void
gst_gl_query_counter (GstGLQuery * query)
{
......@@ -240,6 +311,14 @@ gst_gl_query_counter (GstGLQuery * query)
gl->QueryCounter (query->query_id, query->query_type);
}
/**
* gst_gl_query_result:
* @query: a #GstGLQuery
*
* Returns: the result of the query
*
* Since: 1.10
*/
guint64
gst_gl_query_result (GstGLQuery * query)
{
......
gst-libs/gst/gl/gstglquery.h
View file @ 51a6f47b
......@@ -25,6 +25,12 @@
G_BEGIN_DECLS
/**
* GstGLQueryType:
* @GST_GL_QUERY_NONE: no query
* @GST_GL_QUERY_TIME_ELAPSED: query the time elapsed
* @GST_GL_QUERY_TIMESTAMP: query the current time
*/
typedef enum
{
GST_GL_QUERY_NONE,
......@@ -32,6 +38,11 @@ typedef enum
GST_GL_QUERY_TIMESTAMP,
} GstGLQueryType;
/**
* GstGLQuery:
*
* Opaque #GstGLQuery struct
*/
struct _GstGLQuery
{
/* <private> */
......
gst-libs/gst/gl/gstglrenderbuffer.c
View file @ 51a6f47b
......@@ -39,6 +39,8 @@
*
* #GstGLRenderbuffer is created or wrapped through gst_gl_base_memory_alloc()
* with #GstGLRenderbufferAllocationParams.
*
* Since: 1.10
*/
#define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0))
......@@ -227,7 +229,7 @@ gst_gl_renderbuffer_allocator_init (GstGLRenderbufferAllocator * allocator)
*
* Returns: the configured width of @gl_mem
*
* Since: 1.8
* Since: 1.10
*/
gint
gst_gl_renderbuffer_get_width (GstGLRenderbuffer * gl_mem)
......@@ -243,7 +245,7 @@ gst_gl_renderbuffer_get_width (GstGLRenderbuffer * gl_mem)
*
* Returns: the configured height of @gl_mem
*
* Since: 1.8
* Since: 1.10
*/
gint
gst_gl_renderbuffer_get_height (GstGLRenderbuffer * gl_mem)
......@@ -259,7 +261,7 @@ gst_gl_renderbuffer_get_height (GstGLRenderbuffer * gl_mem)
*
* Returns: the #GstVideoGLTextureType of @gl_mem
*
* Since: 1.8
* Since: 1.10
*/
GstVideoGLTextureType
gst_gl_renderbuffer_get_type (GstGLRenderbuffer * gl_mem)
......@@ -275,7 +277,7 @@ gst_gl_renderbuffer_get_type (GstGLRenderbuffer * gl_mem)
*
* Returns: the OpenGL renderbuffer handle of @gl_mem
*
* Since: 1.8
* Since: 1.10
*/
guint
gst_gl_renderbuffer_get_id (GstGLRenderbuffer * gl_mem)
......@@ -291,7 +293,7 @@ gst_gl_renderbuffer_get_id (GstGLRenderbuffer * gl_mem)
* Initializes the GL Base Texture allocator. It is safe to call this function
* multiple times. This must be called before any other GstGLRenderbuffer operation.
*
* Since: 1.4
* Since: 1.10
*/
void
gst_gl_renderbuffer_init_once (void)
......