From dff43480ee70321609b6dc2072f58edb87f78d11 Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Sun, 6 Mar 2016 19:32:21 +1100 Subject: [PATCH] gl*memory: document new functionality and objects --- gst-libs/gst/gl/gstgl_enums.h | 9 ++ gst-libs/gst/gl/gstglbasememory.c | 40 ++++++- gst-libs/gst/gl/gstglbasememory.h | 131 ++++++++++++++++++++- gst-libs/gst/gl/gstglbuffer.c | 32 +++++- gst-libs/gst/gl/gstglbuffer.h | 9 +- gst-libs/gst/gl/gstglformat.c | 71 ++++++++++++ gst-libs/gst/gl/gstglformat.h | 34 ++++++ gst-libs/gst/gl/gstglmemory.c | 183 ++++++++++++++++++++++++++---- gst-libs/gst/gl/gstglmemory.h | 4 +- gst-libs/gst/gl/gstglmemorypbo.c | 31 ++++- 10 files changed, 503 insertions(+), 41 deletions(-) diff --git a/gst-libs/gst/gl/gstgl_enums.h b/gst-libs/gst/gl/gstgl_enums.h index c4578e4eee..25c7b39ac8 100644 --- a/gst-libs/gst/gl/gstgl_enums.h +++ b/gst-libs/gst/gl/gstgl_enums.h @@ -21,6 +21,15 @@ #ifndef _GST_GL_ENUMS_H_ #define _GST_GL_ENUMS_H_ +/** + * GstGLTextureTarget: + * @GST_GL_TEXTURE_TARGET_NONE: no texture target + * @GST_GL_TEXTURE_TARGET_2D: 2D texture target + * @GST_GL_TEXTURE_TARGET_RECTANGLE: rectangle texture target + * @GST_GL_TEXTURE_TARGET_EXTERNAL_OES: external oes texture target + * + * Since: 1.8 + */ typedef enum { GST_GL_TEXTURE_TARGET_NONE, diff --git a/gst-libs/gst/gl/gstglbasememory.c b/gst-libs/gst/gl/gstglbasememory.c index 7300da5bad..062c19c593 100644 --- a/gst-libs/gst/gl/gstglbasememory.c +++ b/gst-libs/gst/gl/gstglbasememory.c @@ -107,6 +107,8 @@ _mem_create_gl (GstGLContext * context, struct create_data *transfer) * @notify: (allow-none): a #GDestroyNotify * * Initializes @mem with the required parameters + * + * Since: 1.8 */ void gst_gl_base_memory_init (GstGLBaseMemory * mem, GstAllocator * allocator, @@ -176,7 +178,8 @@ _align_data (gpointer data, gsize align) guint8 *ret = data; gsize aoffset; - /* do alignment */ + /* do alignment, data must have enough padding at the end to move at most + * align bytes */ if ((aoffset = ((guintptr) ret & align))) { aoffset = (align + 1) - aoffset; ret += aoffset; @@ -457,6 +460,8 @@ _mem_free (GstAllocator * allocator, GstMemory * memory) * * Initializes the GL Base Memory allocator. It is safe to call this function * multiple times. This must be called before any other GstGLBaseMemory operation. + * + * Since: 1.8 */ void gst_gl_base_memory_init_once (void) @@ -508,6 +513,8 @@ gst_gl_base_memory_allocator_init (GstGLBaseMemoryAllocator * allocator) * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstGLBaseMemory + * + * Since: 1.8 */ gboolean gst_is_gl_base_memory (GstMemory * mem) @@ -525,6 +532,8 @@ gst_is_gl_base_memory (GstMemory * mem) * @size: the number of bytes to copy * * Returns: whether the copy suceeded. + * + * Since: 1.8 */ gboolean gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest, @@ -564,7 +573,7 @@ gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest, * gst_gl_allocation_params_init: * @params: the #GstGLAllocationParams to initialize * @struct_size: the struct size of the implementation - * @alloc: some alloc flags + * @alloc_flags: some alloc flags * @copy: a copy function * @free: a free function * @context: (transfer none): a #GstGLContext @@ -579,6 +588,8 @@ gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest, * when freeing the memory. * * Returns: whether the paramaters could be initialized + * + * Since: 1.8 */ gboolean gst_gl_allocation_params_init (GstGLAllocationParams * params, @@ -617,6 +628,8 @@ gst_gl_allocation_params_init (GstGLAllocationParams * params, * * Returns: a copy of the #GstGLAllocationParams specified by @src or %NULL on * failure + * + * Since: 1.8 */ GstGLAllocationParams * gst_gl_allocation_params_copy (GstGLAllocationParams * src) @@ -638,6 +651,8 @@ gst_gl_allocation_params_copy (GstGLAllocationParams * src) * @params: the #GstGLAllocationParams to initialize * * Frees the #GstGLAllocationParams and all associated data. + * + * Since: 1.8 */ void gst_gl_allocation_params_free (GstGLAllocationParams * params) @@ -648,6 +663,15 @@ gst_gl_allocation_params_free (GstGLAllocationParams * params) g_free (params); } +/** + * gst_gl_allocation_params_free_data: + * @params: the source #GstGLAllocationParams + * + * Frees the dynamically allocated data in @params. Direct subclasses + * should call this function in their own overriden free function. + * + * Since: 1.8 + */ void gst_gl_allocation_params_free_data (GstGLAllocationParams * params) { @@ -657,6 +681,16 @@ gst_gl_allocation_params_free_data (GstGLAllocationParams * params) gst_allocation_params_free (params->alloc_params); } +/** + * gst_gl_allocation_params_copy_data: + * @src: the source #GstGLAllocationParams + * @dest: the destination #GstGLAllocationParams + * + * Copies the dynamically allocated data from @src to @dest. Direct subclasses + * should call this function in their own overriden copy function. + * + * Since: 1.8 + */ void gst_gl_allocation_params_copy_data (GstGLAllocationParams * src, GstGLAllocationParams * dest) @@ -679,6 +713,8 @@ G_DEFINE_BOXED_TYPE (GstGLAllocationParams, gst_gl_allocation_params, * @params: the #GstGLAllocationParams to allocate the memory with * * Returns: a new #GstGLBaseMemory from @allocator with the requested @params. + * + * Since: 1.8 */ GstGLBaseMemory * gst_gl_base_memory_alloc (GstGLBaseMemoryAllocator * allocator, diff --git a/gst-libs/gst/gl/gstglbasememory.h b/gst-libs/gst/gl/gstglbasememory.h index adea5baefc..f862c85c52 100644 --- a/gst-libs/gst/gl/gstglbasememory.h +++ b/gst-libs/gst/gl/gstglbasememory.h @@ -44,6 +44,13 @@ GType gst_gl_base_memory_allocator_get_type(void); GQuark gst_gl_base_memory_error_quark (void); #define GST_GL_BASE_MEMORY_ERROR (gst_gl_base_memory_error_quark ()) +/** + * GstGLBaseMemoryError: + * @GST_GL_BASE_MEMORY_ERROR_FAILED: generic faliure + * @GST_GL_BASE_MEMORY_ERROR_OLD_LIBS: the implementation is too old and doesn't + * implement enough features + * @GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE: a resource could not be found + */ typedef enum { GST_GL_BASE_MEMORY_ERROR_FAILED, @@ -51,6 +58,13 @@ typedef enum GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE, } GstGLBaseMemoryError; +/** + * GstGLBaseMemoryTransfer: + * @GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD: the texture needs downloading + * to the data pointer + * @GST_GL_BASE_MEMORY_TRANSFER_NEED_UPLOAD: the data pointer needs uploading + * to the texture + */ typedef enum { GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD = (GST_MEMORY_FLAG_LAST << 0), @@ -101,9 +115,22 @@ struct _GstGLBaseMemory }; typedef struct _GstGLAllocationParams GstGLAllocationParams; -/* subclass has to compose with the parent class */ +/** + * GstGLAllocationParamsCopyFunc: + * @src: the source #GstGLAllocationParams to copy from + * @dest: the source #GstGLAllocationParams to copy + * + * Copies the parameters from @src into @dest. The subclass must compose copy + * functions from the superclass. + */ typedef void (*GstGLAllocationParamsCopyFunc) (GstGLAllocationParams * src, GstGLAllocationParams * dest); -/* subclass has to compose with the parent class */ +/** + * GstGLAllocationParamsFreeFunc: + * @params: a #GstGLAllocationParams + * + * Free any dynamically allocated data. The subclass must call the superclass' + * free. + */ typedef void (*GstGLAllocationParamsFreeFunc) (gpointer params); #define GST_TYPE_GL_ALLOCATION_PARAMS (gst_gl_allocation_params_get_type()) @@ -114,6 +141,20 @@ GType gst_gl_allocation_params_get_type (void); #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE (1 << 2) #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER (1 << 16) +/** + * GstGLAllocationParams: + * @struct_size: the size of the struct (including and subclass data) + * @copy: a #GstGLAllocationParamsCopyFunc + * @free: a #GstGLAllocationParamsFreeFunc + * @alloc_flags: allocation flags + * @alloc_size: the allocation size + * @alloc_params: the #GstAllocationParams + * @context: a #GstGLContext + * @notify: a #GDestroyNotify + * @user_data: argument to call @notify with + * @wrapped_data: the wrapped data pointer + * @gl_handle: the wrapped OpenGL handle + */ /* Because GstAllocationParams is not subclassable, start our own subclass * chain. FIXME: 2.0 make GstAllocationParams subclassable */ struct _GstGLAllocationParams @@ -158,35 +199,113 @@ void gst_gl_allocation_params_free_data (GstGLAllocationPara void gst_gl_allocation_params_copy_data (GstGLAllocationParams * src, GstGLAllocationParams * dest); +/** + * GstGLBaseMemoryAllocatorAllocFunction: + * @allocator: a #GstGLBaseMemoryAllocator + * @params: the #GstGLAllocationParams to allocate the memory with + * + * Note: not called with a GL context current + * + * Returns: a newly allocated #GstGLBaseMemory from @allocator and @params + * + * Since: 1.8 + */ typedef GstGLBaseMemory * (*GstGLBaseMemoryAllocatorAllocFunction) (GstGLBaseMemoryAllocator * allocator, GstGLAllocationParams * params); + +/** + * GstGLBaseMemoryAllocatorCreateFunction: + * @mem: a #GstGLBaseMemory + * @error: a #GError to use on failure + * + * As this virtual method is called with an OpenGL context current, use this + * function to allocate and OpenGL resources needed for your application + * + * Returns: whether the creation succeeded + * + * Since: 1.8 + */ typedef gboolean (*GstGLBaseMemoryAllocatorCreateFunction) (GstGLBaseMemory * mem, GError ** error); + +/** + * GstGLBaseMemoryAllocatorMapFunction: + * @mem: a #GstGLBaseMemory + * @info: a #GstMapInfo to map with + * @maxsize: the size to map + * + * Also see gst_memory_map(); + * + * Returns: the mapped pointer + * + * Since: 1.8 + */ typedef gpointer (*GstGLBaseMemoryAllocatorMapFunction) (GstGLBaseMemory * mem, GstMapInfo * info, gsize maxsize); +/** + * GstGLBaseMemoryAllocatorUnmapFunction: + * @mem: a #GstGLBaseMemory + * @info: a #GstMapInfo to map with + * + * Also see gst_memory_unmap(); + * + * Since: 1.8 + */ typedef void (*GstGLBaseMemoryAllocatorUnmapFunction) (GstGLBaseMemory * mem, GstMapInfo * info); + +/** + * GstGLBaseMemoryAllocatorCopyFunction: + * @mem: a #GstGLBaseMemory + * @offset: the offset to copy from + * @size: the number of bytes to copy + * + * Also see gst_memory_copy(); + * + * Returns: the newly copied #GstGLMemory or %NULL + * + * Since: 1.8 + */ typedef GstGLBaseMemory * (*GstGLBaseMemoryAllocatorCopyFunction) (GstGLBaseMemory * mem, gssize offset, gssize size); + +/** + * GstGLBaseMemoryAllocatorDestroyFunction: + * @mem: a #GstGLBaseMemory + * + * Destroy any resources allocated throughout the lifetime of @mem + * + * Since: 1.8 + */ typedef void (*GstGLBaseMemoryAllocatorDestroyFunction) (GstGLBaseMemory * mem); /** * GstGLBaseMemoryAllocator * - * Opaque #GstGLAllocator struct + * Opaque #GstGLBaseMemoryAllocator struct + * + * Since: 1.8 */ struct _GstGLBaseMemoryAllocator { + /*< private >*/ GstAllocator parent; GstMemoryCopyFunction fallback_mem_copy; }; /** * GstGLBaseMemoryAllocatorClass: + * @parent_class: the parent class + * @alloc: a #GstGLBaseMemoryAllocatorAllocFunctions + * @create: a #GstGLBaseMemoryAllocatorCreateFunction + * @map: a #GstGLBaseMemoryAllocatorMapFunction + * @unmap: a #GstGLBaseMemoryAllocatorUnmapFunction + * @copy: a #GstGLBaseMemoryAllocatorCopyFunction + * @destroy: a #GstGLBaseMemoryAllocatorDestroyFunction * - * The #GstGLBaseMemoryAllocatorClass only contains private data + * Since: 1.8 */ struct _GstGLBaseMemoryAllocatorClass { @@ -211,6 +330,8 @@ struct _GstGLBaseMemoryAllocatorClass * GST_GL_BASE_MEMORY_ALLOCATOR_NAME: * * The name of the GL buffer allocator + * + * Since: 1.8 */ #define GST_GL_BASE_MEMORY_ALLOCATOR_NAME "GLBaseMemory" @@ -222,7 +343,7 @@ void gst_gl_base_memory_init (GstGLBaseMemory * mem, GstMemory * parent, GstGLContext * context, GstAllocationParams * params, - gsize maxsize, + gsize size, gpointer user_data, GDestroyNotify notify); diff --git a/gst-libs/gst/gl/gstglbuffer.c b/gst-libs/gst/gl/gstglbuffer.c index 4b01000850..2abdd6d77a 100644 --- a/gst-libs/gst/gl/gstglbuffer.c +++ b/gst-libs/gst/gl/gstglbuffer.c @@ -227,6 +227,19 @@ _gl_buffer_unmap (GstGLBuffer * mem, GstMapInfo * info) /* XXX: optimistically transfer data */ } +/** + * gst_gl_buffer_copy_buffer_sub_data: + * @src: the source #GstGLBuffer + * @dest: the destination #GstGLBuffer + * @offset: the offset to copy from @src + * @size: the size to copy from @src + * + * Copies @src into @dest using glCopyBufferSubData(). + * + * Returns: whether the copy operation succeeded + * + * Since: 1.8 + */ static gboolean gst_gl_buffer_copy_buffer_sub_data (GstGLBuffer * src, GstGLBuffer * dest, gssize offset, gssize size) @@ -332,6 +345,19 @@ _gst_gl_buffer_allocation_params_free_data (GstGLBufferAllocationParams * gst_gl_allocation_params_free_data (¶ms->parent); } +/** + * gst_gl_buffer_allocation_params_new: + * @context: a #GstGLContext + * @alloc_size: the size in bytes to allocate + * @alloc_params: (allow-none): the #GstAllocationParams for @tex_id + * @gl_target: the OpenGL target to allocate + * @gl_usage: the OpenGL usage hint to allocate with + * + * Returns: a new #GstGLBufferAllocationParams for allocating OpenGL buffer + * objects + * + * Since: 1.8 + */ GstGLBufferAllocationParams * gst_gl_buffer_allocation_params_new (GstGLContext * context, gsize alloc_size, GstAllocationParams * alloc_params, guint gl_target, guint gl_usage) @@ -413,7 +439,9 @@ gst_gl_buffer_allocator_init (GstGLBufferAllocator * allocator) * gst_gl_buffer_init_once: * * Initializes the GL Buffer allocator. It is safe to call this function - * multiple times. This must be called before any other GstGLBuffer operation. + * multiple times. This must be called before any other #GstGLBuffer operation. + * + * Since: 1.8 */ void gst_gl_buffer_init_once (void) @@ -439,6 +467,8 @@ gst_gl_buffer_init_once (void) * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstGLBuffer + * + * Since: 1.8 */ gboolean gst_is_gl_buffer (GstMemory * mem) diff --git a/gst-libs/gst/gl/gstglbuffer.h b/gst-libs/gst/gl/gstglbuffer.h index 306ac38006..ef519d8534 100644 --- a/gst-libs/gst/gl/gstglbuffer.h +++ b/gst-libs/gst/gl/gstglbuffer.h @@ -44,7 +44,8 @@ GType gst_gl_buffer_allocator_get_type(void); * @mem: the parent object * @context: the #GstGLContext to use for GL operations * @id: the buffer id for this memory - * @target: the GL target of this texture for binding purposes + * @target: the OpenGL target of this texture for binding purposes + * @usage_hints: the OpenGL usage hints this buffer was created with * * Represents information about a GL buffer */ @@ -61,6 +62,12 @@ typedef struct _GstGLBufferAllocationParams GstGLBufferAllocationParams; #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER (1 << 4) +/** + * GstGLBufferAllocationParams: + * @parent: parent object + * @gl_target: the OpenGL target to bind the buffer to + * @gl_usage: the OpenGL usage hint to create the buffer with + */ struct _GstGLBufferAllocationParams { GstGLAllocationParams parent; diff --git a/gst-libs/gst/gl/gstglformat.c b/gst-libs/gst/gl/gstglformat.c index e8e5e46cee..237e25095b 100644 --- a/gst-libs/gst/gl/gstglformat.c +++ b/gst-libs/gst/gl/gstglformat.c @@ -108,6 +108,14 @@ _gl_type_n_bytes (guint type) } } +/** + * gst_gl_format_type_n_bytes: + * @format: the OpenGL format, %GL_RGBA, %GL_LUMINANCE, etc + * @type: the OpenGL type, %GL_UNSIGNED_BYTE, %GL_FLOAT, etc + * + * Returns: the number of bytes the specified @format, @type combination takes + * per pixel + */ guint gst_gl_format_type_n_bytes (guint format, guint type) { @@ -115,6 +123,12 @@ gst_gl_format_type_n_bytes (guint format, guint type) _gl_type_n_bytes (type); } +/** + * gst_gl_texture_type_n_bytes: + * @tex_format: a #GstVideoGLTextureType + * + * Returns: the number of bytes @tex_format used per pixel + */ guint gst_gl_texture_type_n_bytes (GstVideoGLTextureType tex_format) { @@ -128,6 +142,12 @@ gst_gl_texture_type_n_bytes (GstVideoGLTextureType tex_format) return gst_gl_format_type_n_bytes (format, type); } +/** + * gst_gl_format_from_gl_texture_type: + * @tex_format: a #GstVideoGLTextureType + * + * Returns: the OpenGL format specified by @tex_format + */ guint gst_gl_format_from_gl_texture_type (GstVideoGLTextureType tex_format) { @@ -150,6 +170,15 @@ gst_gl_format_from_gl_texture_type (GstVideoGLTextureType tex_format) } } +/** + * gst_gl_texture_type_from_format: + * @context: a #GstGLContext + * @v_format: a #GstVideoFormat + * @plane: the plane number (starting from 0) + * + * Returns: the #GstVideoGLTextureType for the specified @format and @plane + * that can be allocated using @context + */ GstVideoGLTextureType gst_gl_texture_type_from_format (GstGLContext * context, GstVideoFormat v_format, guint plane) @@ -227,6 +256,15 @@ gst_gl_texture_type_from_format (GstGLContext * context, return GST_VIDEO_GL_TEXTURE_TYPE_RGBA; } +/** + * gst_gl_sized_gl_format_from_gl_format_type: + * @context: a #GstGLContext + * @format: an OpenGL format, %GL_RGBA, %GL_LUMINANCE, etc + * @type: an OpenGL type, %GL_UNSIGNED_BYTE, %GL_FLOAT, etc + * + * Returns: the sized internal format specified by @format and @type that can + * be used in @context + */ guint gst_gl_sized_gl_format_from_gl_format_type (GstGLContext * context, guint format, guint type) @@ -288,6 +326,12 @@ gst_gl_sized_gl_format_from_gl_format_type (GstGLContext * context, return 0; } +/** + * gst_gl_texture_target_to_string: + * @target: a #GstGLTextureTarget + * + * Returns: the stringified version of @target or %NULL + */ const gchar * gst_gl_texture_target_to_string (GstGLTextureTarget target) { @@ -303,6 +347,13 @@ gst_gl_texture_target_to_string (GstGLTextureTarget target) } } +/** + * gst_gl_texture_target_to_string: + * @str: a string equivalant to one of the GST_GL_TEXTURE_TARGET_*_STR values + * + * Returns: the #GstGLTextureTarget represented by @str or + * %GST_GL_TEXTURE_TARGET_NONE + */ GstGLTextureTarget gst_gl_texture_target_from_string (const gchar * str) { @@ -319,6 +370,13 @@ gst_gl_texture_target_from_string (const gchar * str) return GST_GL_TEXTURE_TARGET_NONE; } +/** + * gst_gl_texture_target_to_gl: + * @target: a #GstGLTextureTarget + * + * Returns: the OpenGL value for binding the @target with glBindTexture() and + * similar functions or 0 + */ guint gst_gl_texture_target_to_gl (GstGLTextureTarget target) { @@ -334,6 +392,13 @@ gst_gl_texture_target_to_gl (GstGLTextureTarget target) } } +/** + * gst_gl_texture_target_from_gl: + * @target: an OpenGL texture binding target + * + * Returns: the #GstGLTextureTarget that's equiavalant to @target or + * %GST_GL_TEXTURE_TARGET_NONE + */ GstGLTextureTarget gst_gl_texture_target_from_gl (guint target) { @@ -349,6 +414,12 @@ gst_gl_texture_target_from_gl (guint target) } } +/** + * gst_gl_texture_target_to_buffer_pool_option: + * @target: a #GstGLTextureTarget + * + * Returns: a string representing the @GstBufferPoolOption specified by @target + */ const gchar * gst_gl_texture_target_to_buffer_pool_option (GstGLTextureTarget target) { diff --git a/gst-libs/gst/gl/gstglformat.h b/gst-libs/gst/gl/gstglformat.h index c8e67645f4..fcd618a491 100644 --- a/gst-libs/gst/gl/gstglformat.h +++ b/gst-libs/gst/gl/gstglformat.h @@ -26,12 +26,46 @@ #include #include +/** + * GST_GL_TEXTURE_TARGET_2D_STR: + * + * String used for %GST_GL_TEXTURE_TARGET_2D in things like caps values + */ #define GST_GL_TEXTURE_TARGET_2D_STR "2D" + +/** + * GST_GL_TEXTURE_TARGET_RECTANGLE_STR: + * + * String used for %GST_GL_TEXTURE_TARGET_RECTANGLE in things like caps values + */ #define GST_GL_TEXTURE_TARGET_RECTANGLE_STR "rectangle" + +/** + * GST_GL_TEXTURE_TARGET_EXTERNAL_OES_STR: + * + * String used for %GST_GL_TEXTURE_TARGET_EXTERNAL_OES in things like caps values + */ #define GST_GL_TEXTURE_TARGET_EXTERNAL_OES_STR "external-oes" +/** + * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_2D: + * + * String used for %GST_GL_TEXTURE_TARGET_2D as a #GstBufferPool pool option + */ #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_2D "GstBufferPoolOptionGLTextureTarget2D" + +/** + * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_RECTANGLE: + * + * String used for %GST_GL_TEXTURE_TARGET_RECTANGLE as a #GstBufferPool pool option + */ #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_RECTANGLE "GstBufferPoolOptionGLTextureTargetRectangle" + +/** + * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_EXTERNAL_OES: + * + * String used for %GST_GL_TEXTURE_TARGET_ESTERNAL_OES as a #GstBufferPool pool option + */ #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_EXTERNAL_OES "GstBufferPoolOptionGLTextureTargetExternalOES" G_BEGIN_DECLS diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c index 95974d874d..020bc7ce1a 100644 --- a/gst-libs/gst/gl/gstglmemory.c +++ b/gst-libs/gst/gl/gstglmemory.c @@ -34,22 +34,15 @@ * @short_description: memory subclass for GL textures * @see_also: #GstMemory, #GstAllocator, #GstGLBufferPool * - * GstGLMemory is a #GstGLBaseBuffer subclass providing support for the mapping of - * GL textures. + * GstGLMemory is a #GstGLBaseMemory subclass providing support for the mapping of + * OpenGL textures. * - * #GstGLMemory is created through gst_gl_memory_alloc() or system memory can - * be wrapped through gst_gl_memory_wrapped(). + * #GstGLMemory is created or wrapped through gst_gl_base_memory_alloc() + * with #GstGLVideoAllocationParams. * * Data is uploaded or downloaded from the GPU as is necessary. */ -/* Implementation notes - * - * PBO transfer's are implemented using GstGLBaseBuffer. We just need to - * ensure that the texture data is written/read to/from before/after calling - * the parent class which performs the pbo buffer transfer. - */ - #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0)) #define USING_OPENGL3(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL3, 3, 1)) #define USING_GLES(context) (gst_gl_context_check_gl_version (context, GST_GL_API_GLES, 1, 0)) @@ -266,12 +259,18 @@ _gl_tex_create (GstGLMemory * gl_mem, GError ** error) * @allocator: the #GstAllocator to initialize with * @parent: (allow-none): the parent #GstMemory to initialize with * @context: the #GstGLContext to initialize with + * @target: the #GstGLTextureTarget for this #GstGLMemory * @params: (allow-none): the @GstAllocationParams to initialize with - * @size: the number of bytes to be allocated + * @info: the #GstVideoInfo for this #GstGLMemory + * @plane: the plane number (starting from 0) for this #GstGLMemory + * @valign: (allow-none): optional #GstVideoAlignment parameters * @notify: (allow-none): a #GDestroyNotify * @user_data: (allow-none): user data to call @notify with * - * Initializes @mem with the required parameters + * Initializes @mem with the required parameters. @info is assumed to have + * already have been modified with gst_video_info_align(). + * + * Since: 1.8 */ void gst_gl_memory_init (GstGLMemory * mem, GstAllocator * allocator, @@ -326,6 +325,21 @@ gst_gl_memory_init (GstGLMemory * mem, GstAllocator * allocator, mem->mem.mem.size); } +/** + * gst_gl_memory_read_pixels: + * @gl_mem: a #GstGLMemory + * @read_pointer: the data pointer to pass to glReadPixels + * + * Reads the texture in #GstGLMemory into @read_pointer if no buffer is bound + * to %GL_PIXEL_PACK_BUFFER. Otherwise @read_pointer is the byte offset into + * the currently bound %GL_PIXEL_PACK_BUFFER buffer to store the result of + * glReadPixels. See the OpenGL specification for glReadPixels for more + * details. + * + * Returns: whether theread operation succeeded + * + * Since: 1.8 + */ gboolean gst_gl_memory_read_pixels (GstGLMemory * gl_mem, gpointer read_pointer) { @@ -453,6 +467,15 @@ _upload_cpu_write (GstGLMemory * gl_mem, GstMapInfo * info, gsize maxsize) gst_gl_memory_texsubimage (gl_mem, gl_mem->mem.data); } +/** + * gst_gl_memory_texsubimage: + * @gl_mem: a #GstGLMemory + * @read_pointer: the data pointer to pass to glTexSubImage + * + * See gst_gl_memory_read_pixels() for what @read_pointer signifies. + * + * Since: 1.8 + */ void gst_gl_memory_texsubimage (GstGLMemory * gl_mem, gpointer read_pointer) { @@ -559,6 +582,22 @@ _gl_tex_unmap (GstGLMemory * gl_mem, GstMapInfo * info) alloc_class->unmap (GST_GL_BASE_MEMORY_CAST (gl_mem), info); } +/** + * gst_gl_memory_copy_texiamge: + * @gl_mem: the source #GstGLMemory + * @tex_id: the destination texture id + * @out_target: the destination #GstGLTextureTarget + * @out_tex_type: the destination #GstVideoGLTextureType + * @out_width: the destination width + * @out_height: the destination height + * + * Copies the texture in #GstGLMemory into the texture specified by @tex_id, + * @out_target, @out_tex_type, @out_width and @out_height. + * + * Returns: whether the copy succeeded. + * + * Since: 1.8 + */ gboolean gst_gl_memory_copy_teximage (GstGLMemory * src, guint tex_id, GstGLTextureTarget out_target, GstVideoGLTextureType out_tex_type, @@ -820,7 +859,7 @@ gst_gl_memory_allocator_init (GstGLMemoryAllocator * allocator) * gst_gl_memory_copy_into: * @gl_mem:a #GstGLMemory * @tex_id:OpenGL texture id - * @taget: the #GstGLTextureTarget + * @target: the #GstGLTextureTarget * @tex_type: the #GstVideoGLTextureType * @width: width of @tex_id * @height: height of @tex_id @@ -828,18 +867,9 @@ gst_gl_memory_allocator_init (GstGLMemoryAllocator * allocator) * Copies @gl_mem into the texture specfified by @tex_id. The format of @tex_id * is specified by @tex_type, @width and @height. * - * If @respecify is %TRUE, then the copy is performed in terms of the texture - * data. This is useful for splitting RGBA textures into RG or R textures or - * vice versa. The requirement for this to succeed is that the backing texture - * data must be the same size, i.e. say a RGBA8 texture is converted into a RG8 - * texture, then the RG texture must have twice as many pixels available for - * output as the RGBA texture. - * - * Otherwise, if @respecify is %FALSE, then the copy is performed per texel - * using glCopyTexImage. See the OpenGL specification for details on the - * mappings between texture formats. - * * Returns: Whether the copy suceeded + * + * Since: 1.8 */ gboolean gst_gl_memory_copy_into (GstGLMemory * gl_mem, guint tex_id, @@ -861,6 +891,14 @@ gst_gl_memory_copy_into (GstGLMemory * gl_mem, guint tex_id, return copy_params.result; } +/** + * gst_gl_memory_get_texture_width: + * @gl_mem: a #GstGLMemory + * + * Returns: the texture width of @gl_mem + * + * Since: 1.8 + */ gint gst_gl_memory_get_texture_width (GstGLMemory * gl_mem) { @@ -869,6 +907,14 @@ gst_gl_memory_get_texture_width (GstGLMemory * gl_mem) return gl_mem->tex_width; } +/** + * gst_gl_memory_get_texture_height: + * @gl_mem: a #GstGLMemory + * + * Returns: the texture height of @gl_mem + * + * Since: 1.8 + */ gint gst_gl_memory_get_texture_height (GstGLMemory * gl_mem) { @@ -877,6 +923,14 @@ gst_gl_memory_get_texture_height (GstGLMemory * gl_mem) return _get_plane_height (&gl_mem->info, gl_mem->plane); } +/** + * gst_gl_memory_get_texture_type: + * @gl_mem: a #GstGLMemory + * + * Returns: the #GstVideoGLTextureType of @gl_mem + * + * Since: 1.8 + */ GstVideoGLTextureType gst_gl_memory_get_texture_type (GstGLMemory * gl_mem) { @@ -885,6 +939,14 @@ gst_gl_memory_get_texture_type (GstGLMemory * gl_mem) return gl_mem->tex_type; } +/** + * gst_gl_memory_get_texture_target: + * @gl_mem: a #GstGLMemory + * + * Returns: the #GstGLTextureTarget of @gl_mem + * + * Since: 1.8 + */ GstGLTextureTarget gst_gl_memory_get_texture_target (GstGLMemory * gl_mem) { @@ -893,6 +955,14 @@ gst_gl_memory_get_texture_target (GstGLMemory * gl_mem) return gl_mem->tex_target; } +/** + * gst_gl_memory_get_texture_id: + * @gl_mem: a #GstGLMemory + * + * Returns: the OpenGL texture handle of @gl_mem + * + * Since: 1.8 + */ guint gst_gl_memory_get_texture_id (GstGLMemory * gl_mem) { @@ -906,6 +976,8 @@ gst_gl_memory_get_texture_id (GstGLMemory * gl_mem) * * Initializes the GL Base Texture allocator. It is safe to call this function * multiple times. This must be called before any other GstGLMemory operation. + * + * Since: 1.4 */ void gst_gl_memory_init_once (void) @@ -931,6 +1003,8 @@ gst_gl_memory_init_once (void) * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstGLMemory + * + * Since: 1.4 */ gboolean gst_is_gl_memory (GstMemory * mem) @@ -956,6 +1030,30 @@ _gst_gl_video_allocation_params_set_video_alignment (GstGLVideoAllocationParams } } +/** + * gst_gl_video_allocation_params_init_full: + * @params: a #GstGLVideoAllocationParams to initialize + * @struct_size: the size of the struct in @params + * @alloc_flags: some allocation flags + * @copy: a copy function + * @free: a free function + * @context: a #GstGLContext + * @alloc_params: (allow-none): the #GstAllocationParams for @wrapped_data + * @v_info: the #GstVideoInfo for @wrapped_data + * @plane: the video plane @wrapped_data represents + * @valign: (allow-none): any #GstVideoAlignment applied to symem mappings of @wrapped_data + * @target: the #GstGLTextureTarget + * @wrapped_data: (allow-none): the optional data pointer to wrap + * @gl_handle: the optional OpenGL handle to wrap or 0 + * @user_data: (allow-none): user data to call @notify with + * @notify: (allow-none): a #GDestroyNotify + * + * Intended for subclass usage + * + * Returns: initializes @params with the parameters specified + * + * Since: 1.8 + */ gboolean gst_gl_video_allocation_params_init_full (GstGLVideoAllocationParams * params, gsize struct_size, guint alloc_flags, GstGLAllocationParamsCopyFunc copy, @@ -1003,6 +1101,8 @@ gst_gl_video_allocation_params_init_full (GstGLVideoAllocationParams * params, * @target: the #GstGLTextureTarget for @wrapped_data * * Returns: a new #GstGLVideoAllocationParams for allocating #GstGLMemory's + * + * Since: 1.8 */ GstGLVideoAllocationParams * gst_gl_video_allocation_params_new (GstGLContext * context, @@ -1040,6 +1140,8 @@ gst_gl_video_allocation_params_new (GstGLContext * context, * @notify: (allow-none): a #GDestroyNotify * * Returns: a new #GstGLVideoAllocationParams for wrapping @wrapped_data + * + * Since: 1.8 */ GstGLVideoAllocationParams * gst_gl_video_allocation_params_new_wrapped_data (GstGLContext * context, @@ -1078,6 +1180,8 @@ gst_gl_video_allocation_params_new_wrapped_data (GstGLContext * context, * @notify: (allow-none): a #GDestroyNotify * * Returns: a new #GstGLVideoAllocationParams for wrapping @tex_id + * + * Since: 1.8 */ GstGLVideoAllocationParams * gst_gl_video_allocation_params_new_wrapped_texture (GstGLContext * context, @@ -1103,6 +1207,15 @@ gst_gl_video_allocation_params_new_wrapped_texture (GstGLContext * context, return params; } +/** + * gst_gl_video_allocation_params_free_data: + * @params: a #GstGLVideoAllocationParams + * + * Unset and free any dynamically allocated resources. Intended for subclass + * usage only to chain up at the end of a subclass free function. + * + * Since: 1.8 + */ void gst_gl_video_allocation_params_free_data (GstGLVideoAllocationParams * params) { @@ -1112,6 +1225,16 @@ gst_gl_video_allocation_params_free_data (GstGLVideoAllocationParams * params) gst_gl_allocation_params_free_data (¶ms->parent); } +/** + * gst_gl_video_allocation_params_copy_data: + * @src_vid: source #GstGLVideoAllocationParams to copy from + * @dest_vid: destination #GstGLVideoAllocationParams to copy into + * + * Copy and set any dynamically allocated resources in @dest_vid. Intended + * for subclass usage only to chain up at the end of a subclass copy function. + * + * Since: 1.8 + */ void gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid, GstGLVideoAllocationParams * dest_vid) @@ -1141,6 +1264,8 @@ gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid, * @params: the #GstGLVideoAllocationParams to allocate with * * Returns: whether the buffer was correctly setup + * + * Since: 1.8 */ gboolean gst_gl_memory_setup_buffer (GstGLMemoryAllocator * allocator, @@ -1191,6 +1316,14 @@ gst_gl_memory_setup_buffer (GstGLMemoryAllocator * allocator, return TRUE; } +/** + * gst_gl_memory_allocator_get_default: + * @context: a #GstGLContext + * + * Returns: the default #GstGLMemoryAllocator supported by @context + * + * Since: 1.8 + */ GstGLMemoryAllocator * gst_gl_memory_allocator_get_default (GstGLContext * context) { diff --git a/gst-libs/gst/gl/gstglmemory.h b/gst-libs/gst/gl/gstglmemory.h index d595773dec..b032a5ce7a 100644 --- a/gst-libs/gst/gl/gstglmemory.h +++ b/gst-libs/gst/gl/gstglmemory.h @@ -138,8 +138,8 @@ GstGLVideoAllocationParams * gst_gl_video_allocation_params_new_wrapped_texture /* subclass usage */ void gst_gl_video_allocation_params_free_data (GstGLVideoAllocationParams * params); /* subclass usage */ -void gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src, - GstGLVideoAllocationParams * dest); +void gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid, + GstGLVideoAllocationParams * dest_vid); /** * GstGLMemoryAllocator diff --git a/gst-libs/gst/gl/gstglmemorypbo.c b/gst-libs/gst/gl/gstglmemorypbo.c index 8e8bbb83a9..f653e1c389 100644 --- a/gst-libs/gst/gl/gstglmemorypbo.c +++ b/gst-libs/gst/gl/gstglmemorypbo.c @@ -34,8 +34,8 @@ * @short_description: memory subclass for GL textures * @see_also: #GstMemory, #GstAllocator, #GstGLBufferPool * - * GstGLMemoryPBO is a #GstGLMemory subclass providing support for the mapping of - * GL textures. + * #GstGLMemoryPBO is created or wrapped through gst_gl_base_memory_alloc() + * with #GstGLVideoAllocationParams. * * #GstGLMemoryPBO is created through gst_gl_memory_pbo_alloc() or system memory can * be wrapped through gst_gl_memory_pbo_wrapped(). @@ -731,8 +731,9 @@ gst_gl_memory_pbo_allocator_init (GstGLMemoryPBOAllocator * allocator) /** * gst_gl_memory_pbo_copy_into_texture: * @gl_mem:a #GstGLMemoryPBO - * @tex_id:OpenGL texture id - * @tex_type: a #GstVideoGLTextureType + * @tex_id: the destination texture id + * @target: the destination #GstGLTextureTarget + * @tex_type: the destination #GstVideoGLTextureType * @width: width of @tex_id * @height: height of @tex_id * @stride: stride of the backing texture data @@ -753,6 +754,8 @@ gst_gl_memory_pbo_allocator_init (GstGLMemoryPBOAllocator * allocator) * mappings between texture formats. * * Returns: Whether the copy suceeded + * + * Since: 1.8 */ gboolean gst_gl_memory_pbo_copy_into_texture (GstGLMemoryPBO * gl_mem, guint tex_id, @@ -789,6 +792,14 @@ _download_transfer (GstGLContext * context, GstGLMemoryPBO * gl_mem) g_mutex_unlock (&mem->lock); } +/** + * gst_gl_memory_pbo_download_transfer: + * @gl_mem: a #GstGLMemoryPBO + * + * Transfer the texture data from the texture into the PBO if necessary. + * + * Since: 1.8 + */ void gst_gl_memory_pbo_download_transfer (GstGLMemoryPBO * gl_mem) { @@ -815,6 +826,14 @@ _upload_transfer (GstGLContext * context, GstGLMemoryPBO * gl_mem) g_mutex_unlock (&mem->lock); } +/** + * gst_gl_memory_pbo_download_transfer: + * @gl_mem: a #GstGLMemoryPBO + * + * Transfer the texture data from the PBO into the texture if necessary. + * + * Since: 1.8 + */ void gst_gl_memory_pbo_upload_transfer (GstGLMemoryPBO * gl_mem) { @@ -850,10 +869,12 @@ gst_gl_memory_pbo_init_once (void) } /** - * gst_is_gl_memory: + * gst_is_gl_memory_pbo: * @mem:a #GstMemory * * Returns: whether the memory at @mem is a #GstGLMemoryPBO + * + * Since: 1.8 */ gboolean gst_is_gl_memory_pbo (GstMemory * mem)