From d55bbf7f55f37a2d94e84e1eea17b97dc29a2ac8 Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Thu, 27 Sep 2012 15:53:46 +1000 Subject: [PATCH] [600/906] docs: add docs for new objects and expand on some existing ones --- gst-libs/gst/gl/gstglbufferpool.c | 23 +++- gst-libs/gst/gl/gstglbufferpool.h | 12 +- gst-libs/gst/gl/gstgldisplay.h | 271 ++++++++++++++++++++------------------ gst-libs/gst/gl/gstgldownload.c | 112 ++++++++++++++++ gst-libs/gst/gl/gstgldownload.h | 32 ++++- gst-libs/gst/gl/gstglfilter.c | 15 ++- gst-libs/gst/gl/gstglfilter.h | 114 +++++++++------- gst-libs/gst/gl/gstglmemory.c | 22 +++- gst-libs/gst/gl/gstglmemory.h | 62 ++++++++- gst-libs/gst/gl/gstglupload.c | 120 +++++++++++++++++ gst-libs/gst/gl/gstglupload.h | 31 ++++- 11 files changed, 617 insertions(+), 197 deletions(-) diff --git a/gst-libs/gst/gl/gstglbufferpool.c b/gst-libs/gst/gl/gstglbufferpool.c index d8a4cc2..6f9ae01 100644 --- a/gst-libs/gst/gl/gstglbufferpool.c +++ b/gst-libs/gst/gl/gstglbufferpool.c @@ -24,6 +24,19 @@ #include "gstglbufferpool.h" +/** + * SECTION:gstglbufferpool + * @short_description: buffer pool for #GstGLMemory objects + * @see_also: #GstBufferPool, #GstGLMemory + * + * a #GstGLBufferPool is an object that allocates buffers with #GstGLMemory + * + * A #GstGLBufferPool is created with gst_gl_buffer_pool_new() + * + * #GstGLBufferPool implements the VideoMeta buffer pool option + * #GST_BUFFER_POOL_OPTION_VIDEO_META + */ + /* bufferpool */ struct _GstGLBufferPoolPrivate { @@ -159,7 +172,7 @@ gst_gl_buffer_pool_alloc (GstBufferPool * pool, GstBuffer ** buffer, gst_buffer_append_memory (buf, gl_mem); if (priv->add_videometa) { - GST_DEBUG_OBJECT (pool, "adding GstGLMeta"); + GST_DEBUG_OBJECT (pool, "adding GstVideoMeta"); /* these are just the defaults for now */ gst_buffer_add_video_meta (buf, 0, GST_VIDEO_INFO_FORMAT (info), GST_VIDEO_INFO_WIDTH (info), @@ -179,11 +192,17 @@ no_buffer: mem_create_failed: { - GST_WARNING_OBJECT (pool, "Could create GL Memory"); + GST_WARNING_OBJECT (pool, "Could not create GL Memory"); return GST_FLOW_ERROR; } } +/** + * gst_gl_buffer_pool_new: + * @display: the #GstGLDisplay to use + * + * Returns: a #GstBufferPool that allocates buffers with #GstGLMemory + */ GstBufferPool * gst_gl_buffer_pool_new (GstGLDisplay * display) { diff --git a/gst-libs/gst/gl/gstglbufferpool.h b/gst-libs/gst/gl/gstglbufferpool.h index 071def8..eaf506c 100644 --- a/gst-libs/gst/gl/gstglbufferpool.h +++ b/gst-libs/gst/gl/gstglbufferpool.h @@ -35,11 +35,17 @@ typedef struct _GstGLBufferPoolClass GstGLBufferPoolClass; typedef struct _GstGLBufferPoolPrivate GstGLBufferPoolPrivate; /* buffer pool functions */ +GType gst_gl_buffer_pool_get_type (void); #define GST_TYPE_GL_BUFFER_POOL (gst_gl_buffer_pool_get_type()) #define GST_IS_GL_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_GL_BUFFER_POOL)) #define GST_GL_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_GL_BUFFER_POOL, GstGLBufferPool)) #define GST_GL_BUFFER_POOL_CAST(obj) ((GstGLBufferPool*)(obj)) +/** + * GstGLBufferPool: + * + * Opaque GstGLBufferPool struct + */ struct _GstGLBufferPool { GstBufferPool bufferpool; @@ -49,12 +55,16 @@ struct _GstGLBufferPool GstGLBufferPoolPrivate *priv; }; +/** + * GstGLBufferPoolClass: + * + * The #GstGLBufferPoolClass structure contains only private data + */ struct _GstGLBufferPoolClass { GstBufferPoolClass parent_class; }; -GType gst_gl_buffer_pool_get_type (void); GstBufferPool *gst_gl_buffer_pool_new (GstGLDisplay * display); G_END_DECLS diff --git a/gst-libs/gst/gl/gstgldisplay.h b/gst-libs/gst/gl/gstgldisplay.h index 8e4b820..62ed838 100644 --- a/gst-libs/gst/gl/gstgldisplay.h +++ b/gst-libs/gst/gl/gstgldisplay.h @@ -32,162 +32,187 @@ G_BEGIN_DECLS -#define GST_TYPE_GL_DISPLAY \ - (gst_gl_display_get_type()) -#define GST_GL_DISPLAY(obj) \ - (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_GL_DISPLAY,GstGLDisplay)) -#define GST_GL_DISPLAY_CLASS(klass) \ +GType gst_gl_display_get_type (void); +#define GST_TYPE_GL_DISPLAY (gst_gl_display_get_type()) +#define GST_GL_DISPLAY(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_GL_DISPLAY,GstGLDisplay)) +#define GST_GL_DISPLAY_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_GL_DISPLAY,GstGLDisplayClass)) -#define GST_IS_GL_DISPLAY(obj) \ +#define GST_IS_GL_DISPLAY(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_GL_DISPLAY)) -#define GST_IS_GL_DISPLAY_CLASS(klass) \ +#define GST_IS_GL_DISPLAY_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_GL_DISPLAY)) #define GST_GL_DISPLAY_CAST(obj) ((GstGLDisplay*)(obj)) typedef struct _GstGLDisplay GstGLDisplay; typedef struct _GstGLDisplayClass GstGLDisplayClass; -//Color space conversion method +/** + * GstGLDisplayConversion: + * + * %GST_GL_DISPLAY_CONVERSION_GLSL: Convert using GLSL (shaders) + * %GST_GL_DISPLAY_CONVERSION_MATRIX: Convert using the ARB_imaging extension (not implemented) + * %GST_GL_DISPLAY_CONVERSION_MESA: Convert using support in MESA + */ typedef enum { - GST_GL_DISPLAY_CONVERSION_GLSL, //ARB_fragment_shade - GST_GL_DISPLAY_CONVERSION_MATRIX, //ARB_imaging - GST_GL_DISPLAY_CONVERSION_MESA, //MESA_ycbcr_texture + GST_GL_DISPLAY_CONVERSION_GLSL, + GST_GL_DISPLAY_CONVERSION_MATRIX, + GST_GL_DISPLAY_CONVERSION_MESA, } GstGLDisplayConversion; - -//Projection type +/** + * GstGLDisplayProjection: + * + * %GST_GL_DISPLAY_PROJECTION_ORTHO2D: Orthogonal projection + * %GST_GL_DISPLAY_CONVERSION_MATRIX: Perspective projection + */ typedef enum { GST_GL_DISPLAY_PROJECTION_ORTHO2D, GST_GL_DISPLAY_PROJECTION_PERSPECTIVE } GstGLDisplayProjection; -//Texture pool elements -typedef struct _GstGLDisplayTex -{ - GLuint texture; -} GstGLDisplayTex; - - -//Client callbacks -typedef void (*CRCB) (GLuint, GLuint, gpointer); -typedef gboolean (*CDCB) (GLuint, GLuint, GLuint, gpointer); - +/** + * CRCB: + * @width: new width + * @height: new height: + * @data: user data + * + * client reshape callback + */ +typedef void (*CRCB) (GLuint width, GLuint height, gpointer data); +/** + * CDCB: + * @texture: texture to draw + * @width: new width + * @height: new height: + * @data: user data + * + * client draw callback + */ +typedef gboolean (*CDCB) (GLuint texture, GLuint width, GLuint height, gpointer data); +/** + * GstGLDisplayThreadFunc: + * @display: a #GstGLDisplay + * @data: user data + * + * Represents a function to run in the GL thread + */ typedef void (*GstGLDisplayThreadFunc) (GstGLDisplay * display, gpointer data); -//opengl scene callback +/** + * GLCB: + * @width: the width + * @height: the height + * @texture: texture + * @stuff: user data + * + * callback definition for operating on textures + */ typedef void (*GLCB) (gint, gint, guint, gpointer stuff); +/** + * GLCB_V2: + * @stuff: user data + * + * callback definition for operating through a Framebuffer object + */ typedef void (*GLCB_V2) (gpointer stuff); #define GST_GL_DISPLAY_ERR_MSG(obj) ("%s", GST_GL_DISPLAY_CAST(obj)->error_message) +/** + * GstGLDisplay: + * + * the contents of a #GstGLDisplay are private and should only be accessed + * through the provided API + */ struct _GstGLDisplay { - GObject object; - - //thread safe - GMutex *mutex; - - //gl context - GThread *gl_thread; - GstGLWindow *gl_window; - gboolean isAlive; - GHashTable *texture_pool; - - //conditions - GCond *cond_create_context; - GCond *cond_destroy_context; - - //generic gl code - GstGLDisplayThreadFunc generic_callback; - gpointer data; - - //action redisplay - GLuint redisplay_texture; - GLuint redisplay_texture_width; - GLuint redisplay_texture_height; - gboolean keep_aspect_ratio; + GObject object; + + /* thread safe */ + GMutex *mutex; + + /* gl context */ + GThread *gl_thread; + GstGLWindow *gl_window; + gboolean isAlive; + + /* conditions */ + GCond *cond_create_context; + GCond *cond_destroy_context; + + /* generic gl code */ + GstGLDisplayThreadFunc generic_callback; + gpointer data; + + /* action redisplay */ + GLuint redisplay_texture; + GLuint redisplay_texture_width; + GLuint redisplay_texture_height; + gboolean keep_aspect_ratio; #ifdef OPENGL_ES2 - GstGLShader *redisplay_shader; - gchar *redisplay_vertex_shader_str; - gchar *redisplay_fragment_shader_str; - GLint redisplay_attr_position_loc; - GLint redisplay_attr_texture_loc; + GstGLShader *redisplay_shader; + gchar *redisplay_vertex_shader_str; + gchar *redisplay_fragment_shader_str; + GLint redisplay_attr_position_loc; + GLint redisplay_attr_texture_loc; #endif - //action gen and del texture - GLuint gen_texture; - GLuint gen_texture_width; - GLuint gen_texture_height; + /* action gen and del texture */ + GLuint gen_texture; + GLuint gen_texture_width; + GLuint gen_texture_height; GstVideoFormat gen_texture_video_format; - //client callbacks - CRCB clientReshapeCallback; - CDCB clientDrawCallback; - gpointer client_data; + /* client callbacks */ + CRCB clientReshapeCallback; + CDCB clientDrawCallback; + gpointer client_data; GstGLDisplayConversion colorspace_conversion; - GSList *uploads; - GSList *downloads; - - //foreign gl context - gulong external_gl_context; - - //filter gen fbo - GLuint gen_fbo_width; - GLuint gen_fbo_height; - GLuint generated_fbo; - GLuint generated_depth_buffer; - - //filter use fbo - GLuint use_fbo; - GLuint use_depth_buffer; - GLuint use_fbo_texture; - GLuint use_fbo_width; - GLuint use_fbo_height; - GLCB use_fbo_scene_cb; - GLCB_V2 use_fbo_scene_cb_v2; - gdouble use_fbo_proj_param1; - gdouble use_fbo_proj_param2; - gdouble use_fbo_proj_param3; - gdouble use_fbo_proj_param4; + GSList *uploads; + GSList *downloads; + + /* foreign gl context */ + gulong external_gl_context; + + /* filter gen fbo */ + GLuint gen_fbo_width; + GLuint gen_fbo_height; + GLuint generated_fbo; + GLuint generated_depth_buffer; + + /* filter use fbo */ + GLuint use_fbo; + GLuint use_depth_buffer; + GLuint use_fbo_texture; + GLuint use_fbo_width; + GLuint use_fbo_height; + GLCB use_fbo_scene_cb; + GLCB_V2 use_fbo_scene_cb_v2; + gdouble use_fbo_proj_param1; + gdouble use_fbo_proj_param2; + gdouble use_fbo_proj_param3; + gdouble use_fbo_proj_param4; GstGLDisplayProjection use_fbo_projection; - gpointer *use_fbo_stuff; - GLuint input_texture_width; - GLuint input_texture_height; - GLuint input_texture; - - //filter del fbo - GLuint del_fbo; - GLuint del_depth_buffer; + gpointer *use_fbo_stuff; + GLuint input_texture_width; + GLuint input_texture_height; + GLuint input_texture; - //action gen and del shader - const gchar *gen_shader_fragment_source; - const gchar *gen_shader_vertex_source; - GstGLShader *gen_shader; - GstGLShader *del_shader; + /* filter del fbo */ + GLuint del_fbo; + GLuint del_depth_buffer; - //fragement shader upload - gchar *text_shader_upload_YUY2_UYVY; - GstGLShader *shader_upload_YUY2; - GstGLShader *shader_upload_UYVY; - - gchar *text_shader_upload_I420_YV12; - GstGLShader *shader_upload_I420_YV12; - - gchar *text_shader_upload_AYUV; - GstGLShader *shader_upload_AYUV; - -#ifdef OPENGL_ES2 - gchar *text_vertex_shader_upload; - GLint shader_upload_attr_position_loc; - GLint shader_upload_attr_texture_loc; -#endif + /* action gen and del shader */ + const gchar *gen_shader_fragment_source; + const gchar *gen_shader_vertex_source; + GstGLShader *gen_shader; + GstGLShader *del_shader; gchar *error_message; - }; @@ -196,12 +221,10 @@ struct _GstGLDisplayClass GObjectClass object_class; }; -GType gst_gl_display_get_type (void); - -//------------------------------------------------------------ -//-------------------- Public declarations ------------------ -//------------------------------------------------------------ +/*-----------------------------------------------------------*\ + -------------------- Public declarations ------------------- +\*-----------------------------------------------------------*/ GstGLDisplay *gst_gl_display_new (void); gboolean gst_gl_display_create_context (GstGLDisplay * display, @@ -219,12 +242,6 @@ void gst_gl_display_gen_texture_thread (GstGLDisplay * display, GLuint * pTextur GstVideoFormat v_format, GLint width, GLint height); void gst_gl_display_del_texture (GstGLDisplay * display, GLuint * pTexture); -gboolean gst_gl_display_init_upload (GstGLDisplay * display, - GstVideoFormat video_format, guint gl_width, guint gl_height, - gint video_width, gint video_height); -gboolean gst_gl_display_do_upload (GstGLDisplay * display, GLuint texture, - GstVideoFrame * frame); - gboolean gst_gl_display_gen_fbo (GstGLDisplay * display, gint width, gint height, GLuint * fbo, GLuint * depthbuffer); gboolean gst_gl_display_use_fbo (GstGLDisplay * display, gint texture_fbo_width, diff --git a/gst-libs/gst/gl/gstgldownload.c b/gst-libs/gst/gl/gstgldownload.c index d371155..a37165d 100644 --- a/gst-libs/gst/gl/gstgldownload.c +++ b/gst-libs/gst/gl/gstgldownload.c @@ -27,6 +27,22 @@ #include "gstgldownload.h" #include "gstglmemory.h" +/** + * SECTION:gstgldownload + * @short_description: an object that downloads GL textures + * @see_also: #GstGLUpload, #GstGLMemory + * + * #GstGLDownload is an object that downloads GL textures into system memory. + * + * A #GstGLDownload can be created with gst_gl_download_new() or found with + * gst_gl_display_find_download(). + * + * All of the _thread() variants should only be called within the GL thread + * they don't try to take a lock on the associated #GstGLDisplay and + * don't dispatch to the GL thread. Rather they run the required code in the + * calling thread. + */ + static void _do_download (GstGLDisplay * display, GstGLDownload * download); static void _do_download_draw_rgb (GstGLDisplay * display, GstGLDownload * download); @@ -193,6 +209,12 @@ gst_gl_download_init (GstGLDownload * download) gst_video_info_init (&download->info); } +/** + * gst_gl_download_new: + * @display: a #GstGLDisplay + * + * Returns: a new #GstGLDownload object + */ GstGLDownload * gst_gl_download_new (GstGLDisplay * display) { @@ -254,6 +276,17 @@ _init_format_pre (GstGLDownload * download, GstVideoFormat v_format, return TRUE; } +/** + * gst_gl_download_init_format: + * @download: a #GstGLDownload + * @v_format: a #GstVideoFormat + * @out_width: the width to download to + * @out_height: the height to download to + * + * Initializes @download with the information required for download. + * + * Returns: whether the initialization was successful + */ gboolean gst_gl_download_init_format (GstGLDownload * download, GstVideoFormat v_format, guint out_width, guint out_height) @@ -284,6 +317,17 @@ gst_gl_download_init_format (GstGLDownload * download, GstVideoFormat v_format, return TRUE; } +/** + * gst_gl_download_init_format_thread: + * @download: a #GstGLDownload + * @v_format: a #GstVideoFormat + * @out_width: the width to download to + * @out_height: the height to download to + * + * Initializes @download with the information required for download. + * + * Returns: whether the initialization was successful + */ gboolean gst_gl_download_init_format_thread (GstGLDownload * download, GstVideoFormat v_format, guint out_width, guint out_height) @@ -328,6 +372,15 @@ _perform_with_memory_pre (GstGLDownload * download, GstGLMemory * gl_mem) return TRUE; } +/** + * gst_gl_download_perform_with_memory: + * @download: a #GstGLDownload + * @gl_mem: a #GstGLMemory + * + * Downloads the texture in @gl_mem + * + * Returns: whether the download was successful + */ gboolean gst_gl_download_perform_with_memory (GstGLDownload * download, GstGLMemory * gl_mem) @@ -357,6 +410,17 @@ gst_gl_download_perform_with_memory (GstGLDownload * download, return ret; } +/** + * gst_gl_download_perform_with_data: + * @download: a #GstGLDownload + * @texture_id: the texture id to download + * @data: (out): where the downloaded data should go + * + * Downloads @texture_id into @data. @data size and format is specified by + * the #GstVideoFormat passed to gst_gl_download_init_format() + * + * Returns: whether the download was successful + */ gboolean gst_gl_download_perform_with_data (GstGLDownload * download, GLuint texture_id, gpointer data[GST_VIDEO_MAX_PLANES]) @@ -412,6 +476,15 @@ gst_gl_download_perform_with_data_unlocked (GstGLDownload * download, return TRUE; } +/** + * gst_gl_download_perform_with_memory_thread: + * @download: a #GstGLDownload + * @gl_mem: a #GstGLMemory + * + * Downloads the texture in @gl_mem + * + * Returns: whether the download was successful + */ gboolean gst_gl_download_perform_with_memory_thread (GstGLDownload * download, GstGLMemory * gl_mem) @@ -441,6 +514,17 @@ gst_gl_download_perform_with_memory_thread (GstGLDownload * download, return ret; } +/** + * gst_gl_download_perform_with_data_thread: + * @download: a #GstGLDownload + * @texture_id: the texture id to download + * @data: (out): where the downloaded data should go + * + * Downloads @texture_id into @data. @data size and format is specified by + * the #GstVideoFormat passed to gst_gl_download_init_format() + * + * Returns: whether the download was successful + */ gboolean gst_gl_download_perform_with_data_thread (GstGLDownload * download, GLuint texture_id, gpointer data[GST_VIDEO_MAX_PLANES]) @@ -471,6 +555,21 @@ gst_gl_download_perform_with_data_unlocked_thread (GstGLDownload * download, return TRUE; } +/** + * gst_gl_display_find_download_unlocked: + * @display: a #GstGLDisplay + * @v_format: a #GstVideoFormat + * @out_width: the width to download to + * @out_height: the height to download to + * + * Finds a #GstGLDownload with the required download settings, creating one + * if needed. The returned object may not be initialized so you still + * have to call gst_gl_download_init_format. + * + * This function is safe to be called in the GL thread + * + * Returns: a #GstGLDownload object with the required settings + */ GstGLDownload * gst_gl_display_find_download_unlocked (GstGLDisplay * display, GstVideoFormat v_format, guint out_width, guint out_height) @@ -501,6 +600,19 @@ gst_gl_display_find_download_unlocked (GstGLDisplay * display, return ret; } +/** + * gst_gl_display_find_download: + * @display: a #GstGLDisplay + * @v_format: a #GstVideoFormat + * @out_width: the width to download to + * @out_height: the height to download to + * + * Finds a #GstGLDownload with the required download settings, creating one + * if needed. The returned object may not be initialized so you still + * have to call gst_gl_download_init_format. + * + * Returns: a #GstGLDownload object with the required settings + */ GstGLDownload * gst_gl_display_find_download (GstGLDisplay * display, GstVideoFormat v_format, guint out_width, guint out_height) diff --git a/gst-libs/gst/gl/gstgldownload.h b/gst-libs/gst/gl/gstgldownload.h index ef672a4..d065c90 100644 --- a/gst-libs/gst/gl/gstgldownload.h +++ b/gst-libs/gst/gl/gstgldownload.h @@ -44,6 +44,15 @@ GType gst_gl_download_get_type (void); typedef struct _GstGLDownload GstGLDownload; typedef struct _GstGLDownloadClass GstGLDownloadClass; +/** + * GstGLDownload + * @parent: the parent object + * @lock: thread safety + * @display: a #GstGLDisplay + * @info: the output video info + * + * Download information about GL textures + */ struct _GstGLDownload { GObject parent; @@ -52,6 +61,10 @@ struct _GstGLDownload GstGLDisplay *display; + /* output data */ + GstVideoInfo info; + + /* */ gpointer data[GST_VIDEO_MAX_PLANES]; gboolean initted; @@ -66,18 +79,24 @@ struct _GstGLDownload GLint shader_attr_texture_loc; #endif - /* output data */ - GstVideoInfo info; - - /* */ gpointer _reserved[GST_PADDING]; }; +/** + * GstGLDownloadClass: + * + * The #GstGLDownloadClass struct only contains private data + */ struct _GstGLDownloadClass { GObjectClass object_class; }; +/** + * GST_GL_DOWNLOAD_FORMATS: + * + * The currently supported formats that can be downloaded + */ #ifndef OPENGL_ES2 # define GST_GL_DOWNLOAD_FORMATS "{ RGB, RGBx, RGBA, BGR, BGRx, BGRA, xRGB, " \ "xBGR, ARGB, ABGR, I420, YV12, YUY2, UYVY, AYUV }" @@ -85,6 +104,11 @@ struct _GstGLDownloadClass # define GST_GL_DOWNLOAD_FORMATS "{ RGB, RGBx, RGBA, I420, YV12, YUY2, UYVY, AYUV }" #endif /* !OPENGL_ES2 */ +/** + * GST_GL_DOWNLOAD_VIDEO_CAPS: + * + * The currently supported #GstCaps that can be downloaded + */ #define GST_GL_DOWNLOAD_VIDEO_CAPS GST_VIDEO_CAPS_MAKE (GST_GL_DOWNLOAD_FORMATS) GstGLDownload * gst_gl_download_new (GstGLDisplay * display); diff --git a/gst-libs/gst/gl/gstglfilter.c b/gst-libs/gst/gl/gstglfilter.c index 702c010..28308f9 100644 --- a/gst-libs/gst/gl/gstglfilter.c +++ b/gst-libs/gst/gl/gstglfilter.c @@ -882,6 +882,17 @@ gst_gl_filter_decide_allocation (GstBaseTransform * trans, GstQuery * query) return TRUE; } +/** + * gst_gl_filter_filter_texture: + * @filter: a #GstGLFilter + * @inbuf: an input buffer + * @outbuf: an output buffer + * + * Perform automatic upload if needed, call filter_texture vfunc and then an + * automatic download if needed. + * + * Returns: whether the transformation succeeded + */ gboolean gst_gl_filter_filter_texture (GstGLFilter * filter, GstBuffer * inbuf, GstBuffer * outbuf) @@ -1094,10 +1105,10 @@ _draw_with_shader_cb (gint width, gint height, guint texture, gpointer stuff) * @target: the output texture * @shader: the shader to use. * - * Transforms @input into @output using @shader on through FBO. @resize should + * Transforms @input into @output using @shader on FBO. @resize should * only ever be %TRUE whenever @input is the input texture of @filter. * - * See also: #gst_gl_filter_render_to_target() + * See also: gst_gl_filter_render_to_target() */ /* attach target to a FBO, use shader, pass input as "tex" uniform to * the shader, render input to a quad */ diff --git a/gst-libs/gst/gl/gstglfilter.h b/gst-libs/gst/gl/gstglfilter.h index 3201b5a..feae3e6 100644 --- a/gst-libs/gst/gl/gstglfilter.h +++ b/gst-libs/gst/gl/gstglfilter.h @@ -31,88 +31,106 @@ G_BEGIN_DECLS +GType gst_gl_filter_get_type(void); #define GST_TYPE_GL_FILTER (gst_gl_filter_get_type()) #define GST_GL_FILTER(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_GL_FILTER,GstGLFilter)) #define GST_IS_GL_FILTER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_GL_FILTER)) #define GST_GL_FILTER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass) ,GST_TYPE_GL_FILTER,GstGLFilterClass)) #define GST_IS_GL_FILTER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass) ,GST_TYPE_GL_FILTER)) #define GST_GL_FILTER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj) ,GST_TYPE_GL_FILTER,GstGLFilterClass)) + typedef struct _GstGLFilter GstGLFilter; typedef struct _GstGLFilterClass GstGLFilterClass; - -typedef gboolean (*GstGLFilterSetCaps) (GstGLFilter* filter, - GstCaps* incaps, GstCaps* outcaps); -typedef gboolean (*GstGLFilterProcessFunc) (GstGLFilter *filter, - GstBuffer *inbuf, GstBuffer *outbuf); -typedef gboolean (*GstGLFilterProcessTexture) (GstGLFilter *filter, - guint in_tex, guint out_tex); -typedef gboolean (*GstGLFilterOnInitFBO) (GstGLFilter *filter); -typedef void (*GstGLFilterOnReset) (GstGLFilter *filter); -typedef void (*GstGLFilterOnStart) (GstGLFilter *filter); -typedef void (*GstGLFilterOnStop) (GstGLFilter *filter); - -typedef void (*GstGLFilterGLStartFunc) (GstGLFilter *filter); -typedef void (*GstGLFilterGLStopFunc) (GstGLFilter *filter); - +/** + * GstGLFilter: + * @base_transform: parent #GstBaseTransform + * @pool: the currently configured #GstBufferPool + * @display: the currently configured #GstGLDisplay + * @in_info: the video info for input buffers + * @out_info: the video info for output buffers + * @fbo: GL Framebuffer object used for transformations + * @depthbuffer: GL renderbuffer attached to @fbo + * @upload: the object used for uploading data, if needed + * @download: the object used for downloading data, if needed + * + * #GstGLFilter is a base class that provides the logic of getting the GL context + * from downstream and automatic upload/download for non-#GstGLMemory + * #GstBuffers. + */ struct _GstGLFilter { - GstBaseTransform base_transform; + GstBaseTransform base_transform; - GstBufferPool *pool; + GstBufferPool *pool; - GstGLDisplay *display; + GstGLDisplay *display; - GstVideoInfo in_info; - GstVideoInfo out_info; - GLuint fbo; - GLuint depthbuffer; + GstVideoInfo in_info; + GstVideoInfo out_info; + GLuint fbo; + GLuint depthbuffer; - GstGLShader *default_shader; + GstGLUpload *upload; + GstGLDownload *download; - GLuint in_tex_id; - GLuint out_tex_id; - GstGLUpload *upload; - GstGLDownload *download; + /* */ + GLuint in_tex_id; + GLuint out_tex_id; - gulong external_gl_context; + GstGLShader *default_shader; + + gulong external_gl_context; }; +/** + * GstGLFilterClass: + * @base_transform_class: parent class + * @set_caps: mirror from #GstBaseTransform + * @filter: perform operations on the input and output buffers. In general, + * you should avoid using this method if at all possible. One valid + * use-case for using this is keeping previous buffers for future calculations. + * Note: If @filter exists, then @filter_texture is not run + * @filter_texture: given @in_tex, transform it into @out_tex. Not used + * if @filter exists + * @onInitFBO: perform initialization when the Framebuffer object is created + * @onStart: called when element activates see also #GstBaseTransform + * @onStop: called when the element deactivates e also #GstBaseTransform + * @onReset: called on inizialation and after @onStop + * @display_init_cb: execute arbitrary gl code on start + * @display_reset_cb: execute arbitrary gl code at stop + */ struct _GstGLFilterClass { GstBaseTransformClass base_transform_class; - GstGLFilterSetCaps set_caps; - GstGLFilterProcessFunc filter; - GstGLFilterProcessTexture filter_texture; - GstGLFilterOnInitFBO onInitFBO; - GstGLFilterOnStart onStart; - GstGLFilterOnStop onStop; - GstGLFilterOnReset onReset; + gboolean (*set_caps) (GstGLFilter* filter, GstCaps* incaps, GstCaps* outcaps); + gboolean (*filter) (GstGLFilter *filter, GstBuffer *inbuf, GstBuffer *outbuf); + gboolean (*filter_texture) (GstGLFilter *filter, guint in_tex, guint out_tex); + gboolean (*onInitFBO) (GstGLFilter *filter); + + void (*onStart) (GstGLFilter *filter); + void (*onStop) (GstGLFilter *filter); + void (*onReset) (GstGLFilter *filter); /* useful to init and cleanup custom gl resources */ - GstGLFilterGLStartFunc display_init_cb; /* run arbitrary gl code at start */ - GstGLFilterGLStopFunc display_reset_cb; /* run arbitrary gl code at stop */ + void (*display_init_cb) (GstGLFilter *filter); + void (*display_reset_cb) (GstGLFilter *filter); }; -GType gst_gl_filter_get_type(void); - gboolean gst_gl_filter_filter_texture (GstGLFilter * filter, GstBuffer * inbuf, GstBuffer * outbuf); -void -gst_gl_filter_render_to_target (GstGLFilter *filter, gboolean resize, GLuint input, - GLuint target, GLCB func, gpointer data); +void gst_gl_filter_render_to_target (GstGLFilter *filter, gboolean resize, GLuint input, + GLuint target, GLCB func, gpointer data); #ifndef OPENGL_ES2 -void -gst_gl_filter_render_to_target_with_shader (GstGLFilter * filter, gboolean resize, - GLuint input, GLuint target, GstGLShader *shader); +void gst_gl_filter_render_to_target_with_shader (GstGLFilter * filter, gboolean resize, + GLuint input, GLuint target, GstGLShader *shader); void gst_gl_filter_draw_texture (GstGLFilter *filter, GLuint texture, guint width, guint height); -#endif +#endif /* !OPENGL_ES2 */ G_END_DECLS -#endif - +#endif /* _GST_GL_FILTER_H_ */ diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c index 5e9af90..5e51e4d 100644 --- a/gst-libs/gst/gl/gstglmemory.c +++ b/gst-libs/gst/gl/gstglmemory.c @@ -26,6 +26,20 @@ #include "gstglmemory.h" +/** + * SECTION:gstglmemory + * @short_description: memory subclass for GL textures + * @see_also: #GstMemory, #GstAllocator, #GstGLBufferPool + * + * GstGLMemory is a #GstMemory subclass providing support for the mapping of + * GL textures. + * + * #GstGLMemory is created through gst_gl_memory_alloc() or system memory can + * be wrapped through gst_gl_memory_wrapped(). + * + * Data is uploaded or downloaded from the GPU as is necessary. + */ + GST_DEBUG_CATEGORY_STATIC (GST_CAT_GL_MEMORY); #define GST_CAT_DEFUALT GST_CAT_GL_MEMORY @@ -367,8 +381,8 @@ _gl_mem_free (GstAllocator * allocator, GstMemory * mem) * @format: the format for the texture * @width: width of the texture * @height: height of the texture - * - * Returns: a GstMemory object with a GL texture specified by @format, @width and @height + * + * Returns: a #GstMemory object with a GL texture specified by @format, @width and @height * from @display */ GstMemory * @@ -399,7 +413,7 @@ gst_gl_memory_alloc (GstGLDisplay * display, GstVideoFormat format, * @user_data: data called with for @notify * @notify: function called with @user_data when @data needs to be freed * - * Returns: a GstMemory object with a GL texture specified by @format, @width and @height + * Returns: a #GstGLMemory object with a GL texture specified by @format, @width and @height * from @display and contents specified by @data */ GstGLMemory * @@ -472,7 +486,7 @@ gst_gl_memory_init (void) * gst_is_gl_memory: * @mem:a #GstMemory * - * Returns: whether the memory in @mem is a #GstGLMemory + * Returns: whether the memory at @mem is a #GstGLMemory */ gboolean gst_is_gl_memory (GstMemory * mem) diff --git a/gst-libs/gst/gl/gstglmemory.h b/gst-libs/gst/gl/gstglmemory.h index 55880d3..9db482c 100644 --- a/gst-libs/gst/gl/gstglmemory.h +++ b/gst-libs/gst/gl/gstglmemory.h @@ -31,9 +31,6 @@ G_BEGIN_DECLS -typedef struct _GstGLUpload GstGLUpload; -typedef struct _GstGLDownload GstGLDownload; - #define GST_TYPE_GL_ALLOCATOR (gst_gl_allocator_get_type()) GType gst_gl_allocator_get_type(void); @@ -48,6 +45,11 @@ typedef struct _GstGLMemory GstGLMemory; typedef struct _GstGLAllocator GstGLAllocator; typedef struct _GstGLAllocatorClass GstGLAllocatorClass; +/** + * GstGLMemoryFlags: + * + * Flags indicating the current state of a #GstGLMemory + */ typedef enum { GST_GL_MEMORY_FLAG_DOWNLOAD_INITTED = (GST_MEMORY_FLAG_LAST << 0), @@ -70,11 +72,14 @@ typedef enum /** * GstGLMemory: * @mem: the parent object - * @display: the #GstGLDisplay to use - * @tex_id: the texture id + * @display: the #GstGLDisplay to use for GL operations + * @tex_id: the texture id for this memory + * @v_format: the video format of this texture * @gl_format: the format of the texture * @width: width of the texture * @height: height of the texture + * @download: the object used to download this texture into @v_format + * @upload: the object used to upload this texture from @v_format * * Represents information about a GL texture */ @@ -90,9 +95,9 @@ struct _GstGLMemory GLuint height; GstGLDownload *download; - GLenum render_target; GstGLUpload *upload; + /* */ GstMapFlags map_flags; gpointer data; @@ -101,11 +106,46 @@ struct _GstGLMemory gpointer user_data; }; +/** + * GST_GL_MEMORY_ALLOCATOR: + * + * The name of the GL memore allocator + */ #define GST_GL_MEMORY_ALLOCATOR "GLMemory" +/** + * GST_GL_MEMORY_FLAGS: + * @mem: a #GstGLMemory + * + * Get the currently set flags on @mem + */ #define GST_GL_MEMORY_FLAGS(mem) GST_MEMORY_FLAGS(mem) + +/** + * GST_GL_MEMORY_FLAG_IS_SET: + * @mem: a #GstGLMemory + * @flag: a flag + * + * Returns: Whether @flag is set on @mem + */ #define GST_GL_MEMORY_FLAG_IS_SET(mem,flag) GST_MEMORY_FLAG_IS_SET(mem,flag) + +/** + * GST_GL_MEMORY_FLAG_SET: + * @mem: a #GstGLMemory + * @flag: a flag + * + * Set @flag on @mem + */ #define GST_GL_MEMORY_FLAG_SET(mem,flag) GST_MINI_OBJECT_FLAG_SET(mem,flag) + +/** + * GST_GL_MEMORY_FLAG_UNSET: + * @mem: a #GstGLMemory + * @flag: a flag + * + * Unset @flag on @mem + */ #define GST_GL_MEMORY_FLAG_UNSET(mem,flag) GST_MEMORY_FLAG_UNSET(mem,flag) void gst_gl_memory_init (void); @@ -119,11 +159,21 @@ GstGLMemory * gst_gl_memory_wrapped (GstGLDisplay * display, GstVideoFormat form gboolean gst_is_gl_memory (GstMemory * mem); +/** + * GstGLAllocator + * + * Opaque #GstGLAllocator struct + */ struct _GstGLAllocator { GstAllocator parent; }; +/** + * GstGLAllocatorClass: + * + * The #GstGLAllocatorClass only contains private data + */ struct _GstGLAllocatorClass { GstAllocatorClass parent_class; diff --git a/gst-libs/gst/gl/gstglupload.c b/gst-libs/gst/gl/gstglupload.c index f409723..30b9441 100644 --- a/gst-libs/gst/gl/gstglupload.c +++ b/gst-libs/gst/gl/gstglupload.c @@ -27,6 +27,22 @@ #include "gstglupload.h" #include "gstglmemory.h" +/** + * SECTION:gstglupload + * @short_description: an object that uploads to GL textures + * @see_also: #GstGLDownload, #GstGLMemory + * + * #GstGLUpload is an object that uploads data from system memory into GL textures. + * + * A #GstGLUpload can be created with gst_gl_upload_new() or found with + * gst_gl_display_find_upload(). + * + * All of the _thread() variants should only be called within the GL thread + * they don't try to take a lock on the associated #GstGLDisplay and + * don't dispatch to the GL thread. Rather they run the required code in the + * calling thread. + */ + static void _do_upload (GstGLDisplay * display, GstGLUpload * upload); static void _do_upload_draw (GstGLDisplay * display, GstGLUpload * upload); static void _do_upload_fill (GstGLDisplay * display, GstGLUpload * upload); @@ -170,6 +186,12 @@ gst_gl_upload_init (GstGLUpload * upload) gst_video_info_init (&upload->info); } +/** + * gst_gl_upload_new: + * @display: a #GstGLDisplay + * + * Returns: a new #GstGLUpload object + */ GstGLUpload * gst_gl_upload_new (GstGLDisplay * display) { @@ -218,6 +240,19 @@ gst_gl_upload_finalize (GObject * object) } } +/** + * gst_gl_upload_init_format: + * @upload: a #GstGLUpload + * @v_format: a #GstVideoFormat + * @in_width: the width of the data to upload + * @in_height: the height of the data to upload + * @out_width: the width to upload to + * @out_height: the height to upload to + * + * Initializes @upload with the information required for upload. + * + * Returns: whether the initialization was successful + */ gboolean gst_gl_upload_init_format (GstGLUpload * upload, GstVideoFormat v_format, guint in_width, guint in_height, guint out_width, guint out_height) @@ -253,6 +288,19 @@ gst_gl_upload_init_format (GstGLUpload * upload, GstVideoFormat v_format, return TRUE; } +/** + * gst_gl_upload_init_format: + * @upload: a #GstGLUpload + * @v_format: a #GstVideoFormat + * @in_width: the width of the data to upload + * @in_height: the height of the data to upload + * @out_width: the width to upload to + * @out_height: the height to upload to + * + * Initializes @upload with the information required for upload. + * + * Returns: whether the initialization was successful + */ gboolean gst_gl_upload_init_format_thread (GstGLUpload * upload, GstVideoFormat v_format, guint in_width, guint in_height, guint out_width, guint out_height) @@ -287,6 +335,15 @@ gst_gl_upload_init_format_thread (GstGLUpload * upload, GstVideoFormat v_format, return TRUE; } +/** + * gst_gl_upload_perform_with_memory: + * @upload: a #GstGLUpload + * @gl_mem: a #GstGLMemory + * + * Uploads the texture in @gl_mem + * + * Returns: whether the upload was successful + */ gboolean gst_gl_upload_perform_with_memory (GstGLUpload * upload, GstGLMemory * gl_mem) { @@ -321,6 +378,17 @@ gst_gl_upload_perform_with_memory (GstGLUpload * upload, GstGLMemory * gl_mem) return ret; } +/** + * gst_gl_upload_perform_with_data: + * @upload: a #GstGLUpload + * @texture_id: the texture id to download + * @data: where the downloaded data should go + * + * Uploads @data into @texture_id. @data size and format is specified by + * the #GstVideoFormat passed to gst_gl_upload_init_format() + * + * Returns: whether the upload was successful + */ gboolean gst_gl_upload_perform_with_data (GstGLUpload * upload, GLuint texture_id, gpointer data[GST_VIDEO_MAX_PLANES]) @@ -372,6 +440,15 @@ gst_gl_upload_perform_with_data_unlocked (GstGLUpload * upload, return TRUE; } +/** + * gst_gl_upload_perform_with_memory_thread: + * @upload: a #GstGLUpload + * @gl_mem: a #GstGLMemory + * + * Uploads the texture in @gl_mem + * + * Returns: whether the upload was successful + */ gboolean gst_gl_upload_perform_with_memory_thread (GstGLUpload * upload, GstGLMemory * gl_mem) @@ -406,6 +483,17 @@ gst_gl_upload_perform_with_memory_thread (GstGLUpload * upload, return ret; } +/** + * gst_gl_upload_perform_with_data_thread: + * @upload: a #GstGLUpload + * @texture_id: the texture id to download + * @data: where the downloaded data should go + * + * Uploads @data into @texture_id. @data size and format is specified by + * the #GstVideoFormat passed to gst_gl_upload_init_format() + * + * Returns: whether the upload was successful + */ gboolean gst_gl_upload_perform_with_data_thread (GstGLUpload * upload, GLuint texture_id, gpointer data[GST_VIDEO_MAX_PLANES]) @@ -437,6 +525,23 @@ gst_gl_upload_perform_with_data_unlocked_thread (GstGLUpload * upload, return TRUE; } +/** + * gst_gl_display_find_upload_unlocked: + * @display: a #GstGLDisplay + * @v_format: a #GstVideoFormat + * @in_width: the width of the data to upload + * @in_height: the height of the data to upload + * @out_width: the width to upload to + * @out_height: the height to upload to + * + * Finds a #GstGLDownload with the required upload settings, creating one + * if needed. The returned object may not be initialized so you still + * have to call gst_gl_upload_init_format. + * + * This function is safe to be called in the GL thread + * + * Returns: a #GstGLUpload object with the required settings + */ GstGLUpload * gst_gl_display_find_upload_unlocked (GstGLDisplay * display, GstVideoFormat v_format, guint in_width, guint in_height, @@ -469,6 +574,21 @@ gst_gl_display_find_upload_unlocked (GstGLDisplay * display, return ret; } +/** + * gst_gl_display_find_upload: + * @display: a #GstGLDisplay + * @v_format: a #GstVideoFormat + * @in_width: the width of the data to upload + * @in_height: the height of the data to upload + * @out_width: the width to upload to + * @out_height: the height to upload to + * + * Finds a #GstGLDownload with the required upload settings, creating one + * if needed. The returned object may not be initialized so you still + * have to call gst_gl_upload_init_format. + * + * Returns: a #GstGLUpload object with the required settings + */ GstGLUpload * gst_gl_display_find_upload (GstGLDisplay * display, GstVideoFormat v_format, guint in_width, guint in_height, guint out_width, guint out_height) diff --git a/gst-libs/gst/gl/gstglupload.h b/gst-libs/gst/gl/gstglupload.h index cc1bfba..7ced67c 100644 --- a/gst-libs/gst/gl/gstglupload.h +++ b/gst-libs/gst/gl/gstglupload.h @@ -44,6 +44,15 @@ GType gst_gl_upload_get_type (void); typedef struct _GstGLUpload GstGLUpload; typedef struct _GstGLUploadClass GstGLUploadClass; +/** + * GstGLUpload + * @parent: the parent object + * @lock: thread safety + * @display: a #GstGLDisplay + * @info: the output video info + * + * Upload information for GL textures + */ struct _GstGLUpload { GObject parent; @@ -52,6 +61,10 @@ struct _GstGLUpload GstGLDisplay *display; + /* input data */ + GstVideoInfo info; + + /* */ gpointer data[GST_VIDEO_MAX_PLANES]; gboolean initted; @@ -68,18 +81,25 @@ struct _GstGLUpload GLint shader_attr_texture_loc; #endif - /* input data */ - GstVideoInfo info; - /* */ gpointer _reserved[GST_PADDING]; }; +/** + * GstGLUploadClass: + * + * The #GstGLUploadClass struct only contains private data + */ struct _GstGLUploadClass { GObjectClass object_class; }; +/** + * GST_GL_UPLOAD_FORMATS: + * + * The currently supported formats that can be uploaded + */ #ifndef OPENGL_ES2 # define GST_GL_UPLOAD_FORMATS "{ RGB, RGBx, RGBA, BGR, BGRx, BGRA, xRGB, " \ "xBGR, ARGB, ABGR, I420, YV12, YUY2, UYVY, AYUV }" @@ -87,6 +107,11 @@ struct _GstGLUploadClass # define GST_GL_UPLOAD_FORMATS "{ RGB, RGBx, RGBA, I420, YV12, YUY2, UYVY, AYUV }" #endif +/** + * GST_GL_UPLOAD_VIDEO_CAPS: + * + * The currently supported #GstCaps that can be uploaded + */ #define GST_GL_UPLOAD_VIDEO_CAPS GST_VIDEO_CAPS_MAKE (GST_GL_UPLOAD_FORMATS) GstGLUpload * gst_gl_upload_new (GstGLDisplay * display); -- 2.7.4