gl/docs: some documentation updates

Add some missing/incomplete docs
This commit is contained in:
Matthew Waters 2017-07-28 11:00:12 +01:00
parent 23da53306f
commit 3d2785965d
18 changed files with 202 additions and 9 deletions

View file

@ -855,7 +855,6 @@ GST_TYPE_GL_COLOR_CONVERT
<FILE>gstglcontext</FILE>
<TITLE>GstGLContext</TITLE>
GST_GL_CONTEXT_ERROR
gst_gl_context_error_quark
GstGLContextError
GstGLContextThreadFunc
GstGLContext
@ -898,6 +897,7 @@ GST_GL_CONTEXT_CAST
GstGLContextPrivate
gst_gl_context_get_type
<SUBSECTION Private>
gst_gl_context_error_quark
GST_GL_DEBUG_PROC
GST_GL_HAVE_DMABUF
GST_GL_HAVE_EGLATTRIB
@ -905,6 +905,7 @@ GST_GL_HAVE_GLCHAR
GST_GL_HAVE_GLEGLIMAGEOES
GST_GL_HAVE_GLES2
GST_GL_HAVE_GLES3
GST_GL_HAVE_GLES3EXT3_H
GST_GL_HAVE_GLINT64
GST_GL_HAVE_GLINTPTR
GST_GL_HAVE_GLSIZEIPTR
@ -923,6 +924,8 @@ GST_GL_HAVE_WINDOW_EAGL
GST_GL_HAVE_WINDOW_WAYLAND
GST_GL_HAVE_WINDOW_WIN32
GST_GL_HAVE_WINDOW_X11
GST_GL_HAVE_WINDOW_VIV_FB
GST_GL_HAVE_VIV_DIRECTVIV
</SECTION>
<SECTION>
@ -1237,6 +1240,7 @@ GstGLFramebufferFunc
gst_gl_framebuffer_draw_to_texture
gst_gl_framebuffer_get_effective_dimensions
gst_gl_framebuffer_get_id
gst_gl_context_check_framebuffer_status
<SUBSECTION Standard>
GstGLFramebufferPrivate
GST_GL_FRAMEBUFFER
@ -1526,7 +1530,6 @@ GST_GL_SHADER_GET_CLASS
<FILE>gstglsl</FILE>
<TITLE>GstGLSL</TITLE>
GST_GLSL_ERROR
gst_glsl_error_quark
GstGLSLError
GstGLSLProfile
GstGLSLVersion
@ -1539,6 +1542,8 @@ gst_glsl_version_profile_to_string
gst_glsl_string_get_version_profile
gst_gl_context_supports_glsl_profile_version
gst_gl_version_to_glsl_version
<SUBSECTION Standard>
gst_glsl_error_quark
</SECTION>
<SECTION>

View file

@ -39,6 +39,14 @@ GType gst_egl_image_get_type (void);
typedef struct _GstEGLImage GstEGLImage;
/**
* GstEGLImageDestroyNotify:
* @image: a #GstEGLImage
* @data: user data passed to gst_egl_image_new_wrapped()
*
* Function to be called when the GstEGLImage is destroyed. It should free
* the associated #EGLImage if necessary
*/
typedef void (*GstEGLImageDestroyNotify) (GstEGLImage * image,
gpointer data);

View file

@ -20,7 +20,7 @@
/**
* SECTION:gstglapi
* @title: GstGLApi
* @title: GstGLAPI
* @short_description: OpenGL API specific functionality
* @see_also: #GstGLDisplay, #GstGLContext
*

View file

@ -192,6 +192,16 @@ _align_data (gpointer data, gsize align)
}
/* subclass usage only */
/**
* gst_gl_base_memory_alloc_data:
* @gl_mem: a #GstGLBaseMemory
*
* Note: only intended for subclass usage to allocate the sytem memory buffer
* on demand. If there is already a non-NULL data pointer in @gl_mem->data,
* then this function imply returns TRUE.
*
* Returns: whether the system memory could be allocated
*/
gboolean
gst_gl_base_memory_alloc_data (GstGLBaseMemory * gl_mem)
{

View file

@ -29,6 +29,12 @@
G_BEGIN_DECLS
/**
* GST_GL_BASE_MEMORY_ERROR:
*
* Error domain for GStreamer's GL memory module. Errors in this domain will be
* from the #GstGLBaseMemoryError enumeration
*/
#define GST_TYPE_GL_BASE_MEMORY (gst_gl_base_memory_get_type())
GST_EXPORT
GType gst_gl_base_memory_get_type(void);
@ -145,9 +151,34 @@ typedef void (*GstGLAllocationParamsFreeFunc) (gpointer params);
GST_EXPORT
GType gst_gl_allocation_params_get_type (void);
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC:
*
* GL Allocation flag indicating that the implementation should allocate the
* necessary resources.
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC (1 << 0)
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM:
*
* GL Allocation flag for using the provided system memory data as storage.
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM (1 << 1)
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE:
*
* GL Allocation flag for using the provided GPU handle as storage.
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE (1 << 2)
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER:
*
* Values >= than #GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER can be used for
* user-defined purposes.
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER (1 << 16)
/**

View file

@ -64,6 +64,11 @@ typedef struct _GstGLBufferAllocationParams GstGLBufferAllocationParams;
GST_EXPORT
GType gst_gl_buffer_allocation_params_get_type (void);
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER:
*
* GL allocation flag indicating the allocation of a GL buffer.
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER (1 << 4)
/**
@ -116,6 +121,11 @@ struct _GstGLBufferAllocatorClass
gpointer _padding[GST_PADDING];
};
/**
* GST_CAPS_FEATURE_MEMORY_GL_BUFFER:
*
* Name of the caps feature indicating the use of GL buffers
*/
#define GST_CAPS_FEATURE_MEMORY_GL_BUFFER "memory:GLBuffer"
/**

View file

@ -838,7 +838,11 @@ gst_gl_context_get_gl_api (GstGLContext * context)
* Note: On success, you need to cast the returned function pointer to the
* correct type to be able to call it correctly. On 32-bit Windows, this will
* include the %GSTGLAPI identifier to use the correct calling convention.
* e.g. void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret)
* e.g.
*
* |[<!-- language="C" -->
* void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret)
* ]|
*
* Returns: a function pointer or %NULL
*

View file

@ -43,6 +43,13 @@ GType gst_gl_context_get_type (void);
GST_EXPORT
GQuark gst_gl_context_error_quark (void);
/**
* GST_GL_CONTEXT_ERROR:
*
* Error domain for GStreamer's GL context module. Errors in this domain will
* be from the #GstGLContextError enumeration
*/
#define GST_GL_CONTEXT_ERROR (gst_gl_context_error_quark ())
/**

View file

@ -50,6 +50,7 @@ GType gst_gl_display_get_type (void);
* @GST_GL_DISPLAY_TYPE_WIN32: Win32 display
* @GST_GL_DISPLAY_TYPE_DISPMANX: Dispmanx display
* @GST_GL_DISPLAY_TYPE_EGL: EGL display
* @GST_GL_DISPLAY_TYPE_VIV_FB: Vivante Framebuffer display
* @GST_GL_DISPLAY_TYPE_ANY: any display type
*/
typedef enum
@ -117,6 +118,11 @@ GstGLAPI gst_gl_display_get_gl_api (GstGLDisplay * display);
GST_EXPORT
GstGLAPI gst_gl_display_get_gl_api_unlocked (GstGLDisplay * display);
/**
* GST_GL_DISPLAY_CONTEXT_TYPE:
*
* The name used in #GstContext queries for requesting a #GstGLDisplay
*/
#define GST_GL_DISPLAY_CONTEXT_TYPE "gst.gl.GLDisplay"
GST_EXPORT
void gst_context_set_gl_display (GstContext * context, GstGLDisplay * display);

View file

@ -896,8 +896,7 @@ gst_gl_filter_decide_allocation (GstBaseTransform * trans, GstQuery * query)
* @inbuf: an input buffer
* @outbuf: an output buffer
*
* Perform automatic upload if needed, call filter_texture vfunc and then an
* automatic download if needed.
* Calls filter_texture vfunc with correctly mapped #GstGLMemorys
*
* Returns: whether the transformation succeeded
*

View file

@ -509,6 +509,8 @@ gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb,
/**
* gst_gl_context_check_framebuffer_status:
* @context: a #GstGLContext
* @fbo_target: the GL value of the framebuffer target, GL_FRAMEBUFFER,
* GL_READ_FRAMEBUFFER, GL_DRAW_FRAMEBUFFER
*
* Returns: whether whether the current framebuffer is complete
*

View file

@ -618,7 +618,7 @@ _gl_tex_unmap (GstGLMemory * gl_mem, GstMapInfo * info)
}
/**
* gst_gl_memory_copy_texiamge:
* gst_gl_memory_copy_teximage:
* @gl_mem: the source #GstGLMemory
* @tex_id: the destination texture id
* @out_target: the destination #GstGLTextureTarget

View file

@ -43,7 +43,17 @@ GType gst_gl_memory_allocator_get_type(void);
#define GST_GL_MEMORY_CAST(obj) ((GstGLMemory *) obj)
/**
* GST_CAPS_FEATURE_MEMORY_GL_MEMORY:
*
* Name of the caps feature for indicating the use of #GstGLMemory
*/
#define GST_CAPS_FEATURE_MEMORY_GL_MEMORY "memory:GLMemory"
/**
* GST_GL_MEMORY_VIDEO_FORMATS_STR:
*
* List of video formats that are supported by #GstGLMemory
*/
#define GST_GL_MEMORY_VIDEO_FORMATS_STR \
"{ RGBA, BGRA, RGBx, BGRx, ARGB, ABGR, xRGB, xBGR, RGB, BGR, RGB16, BGR16, " \
"AYUV, I420, YV12, NV12, NV21, YUY2, UYVY, Y41B, Y42B, Y444, " \
@ -90,6 +100,11 @@ GType gst_gl_video_allocation_params_get_type (void);
typedef struct _GstGLVideoAllocationParams GstGLVideoAllocationParams;
/**
* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_VIDEO:
*
* GL allocation flag indicating the allocation of 2D video frames
*/
#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_VIDEO (1 << 3)
/**
@ -99,7 +114,7 @@ typedef struct _GstGLVideoAllocationParams GstGLVideoAllocationParams;
* @plane: the video plane index to allocate
* @valign: the #GstVideoAlignment to align the system representation to (may be %NULL for the default)
* @target: the #GstGLTextureTarget to allocate
* @tex_fomrat: the #GstGLFormat to allocate
* @tex_format: the #GstGLFormat to allocate
*/
struct _GstGLVideoAllocationParams
{

View file

@ -58,7 +58,7 @@ struct _GstGLMemoryPBO
};
/**
* GST_GL_MEMORY_PBO_ALLOCATOR:
* GST_GL_MEMORY_PBO_ALLOCATOR_NAME:
*
* The name of the GL Memory PBO allocator
*/

View file

@ -94,6 +94,12 @@ static const struct glsl_profile_string glsl_profiles[] = {
{GST_GLSL_PROFILE_COMPATIBILITY, "compatibility"},
};
/**
* gst_glsl_version_to_string:
* @version: a #GstGLSLVersion
*
* Returns: (nullable): the name of @version or %NULL on error
*/
const gchar *
gst_glsl_version_to_string (GstGLSLVersion version)
{
@ -110,6 +116,12 @@ gst_glsl_version_to_string (GstGLSLVersion version)
return NULL;
}
/**
* gst_glsl_version_from_string:
* @string: a GLSL version string
*
* Returns: the #GstGLSLVersion of @string or %GST_GLSL_VERSION_NONE on error
*/
GstGLSLVersion
gst_glsl_version_from_string (const gchar * string)
{
@ -133,6 +145,12 @@ gst_glsl_version_from_string (const gchar * string)
return 0;
}
/**
* gst_glsl_profile_to_string:
* @profile: a #GstGLSLProfile
*
* Returns: (nullable): the name for @profile or %NULL on error
*/
const gchar *
gst_glsl_profile_to_string (GstGLSLProfile profile)
{
@ -153,6 +171,12 @@ gst_glsl_profile_to_string (GstGLSLProfile profile)
return NULL;
}
/**
* gst_glsl_profile_from_string:
* @string: a GLSL version string
*
* Returns: the #GstGLSLProfile of @string or %GST_GLSL_PROFILE_NONE on error
*/
GstGLSLProfile
gst_glsl_profile_from_string (const gchar * string)
{
@ -203,6 +227,13 @@ _is_valid_version_profile (GstGLSLVersion version, GstGLSLProfile profile)
return FALSE;
}
/**
* gst_glsl_version_profile_to_string:
* @version: a #GstGLSLVersion
* @profile: a #GstGLSLVersion
*
* Returns: the combined GLSL #version string for @version and @profile
*/
gchar *
gst_glsl_version_profile_to_string (GstGLSLVersion version,
GstGLSLProfile profile)
@ -262,6 +293,17 @@ _check_valid_version_preprocessor_string (const gchar * str)
return NULL;
}
/**
* gst_glsl_version_profile_from_string:
* @string: a valid GLSL #version string
* @version_ret: (out): resulting #GstGLSLVersion
* @profile_ret: (out): resulting #GstGLSLVersion
*
* Note: this function expects either a #version GLSL preprocesser directive
* or a valid GLSL version and/or profile.
*
* Returns: TRUE if a valid #version string was found, FALSE otherwise
*/
gboolean
gst_glsl_version_profile_from_string (const gchar * string,
GstGLSLVersion * version_ret, GstGLSLProfile * profile_ret)
@ -417,6 +459,17 @@ _gst_glsl_shader_string_find_version (const gchar * str)
return NULL;
}
/**
* gst_glsl_string_get_version_profile:
* @s: string to search for a valid #version string
* @version: (out): resulting #GstGLSLVersion
* @profile: (out): resulting #GstGLSLProfile
*
* Note: this function first searches the first 1 kilobytes for a #version
* preprocessor directive and then executes gst_glsl_version_profile_from_string().
*
* Returns: TRUE if a valid #version string was found, FALSE otherwise
*/
gboolean
gst_glsl_string_get_version_profile (const gchar * s, GstGLSLVersion * version,
GstGLSLProfile * profile)
@ -443,6 +496,14 @@ error:
}
}
/**
* gst_gl_version_to_glsl_version:
* @gl_api: the #GstGLAPI
* @maj: the major GL version
* @min: the minor GL version
*
* Returns: The minimum supported #GstGLSLVersion available for @gl_api, @maj and @min
*/
GstGLSLVersion
gst_gl_version_to_glsl_version (GstGLAPI gl_api, gint maj, gint min)
{
@ -485,6 +546,14 @@ gst_gl_version_to_glsl_version (GstGLAPI gl_api, gint maj, gint min)
return 0;
}
/**
* gst_gl_context_supports_glsl_profile_version:
* @context: a #GstGLContext
* @version: a #GstGLSLVersion
* @profile: a #GstGLSLProfile
*
* Returns: Whether @context supports the combination of @version with @profile
*/
gboolean
gst_gl_context_supports_glsl_profile_version (GstGLContext * context,
GstGLSLVersion version, GstGLSLProfile profile)

View file

@ -27,6 +27,13 @@ G_BEGIN_DECLS
GST_EXPORT
GQuark gst_glsl_error_quark (void);
/**
* GST_GLSL_ERROR:
*
* Error domain for GStreamer's GLSL module. Errors in this domain will be
* from the #GstGLSLError enumeration
*/
#define GST_GLSL_ERROR (gst_glsl_error_quark ())
/**

View file

@ -41,6 +41,7 @@ GType gst_gl_upload_get_type (void);
* @GST_GL_UPLOAD_DONE: No further processing required
* @GST_GL_UPLOAD_ERROR: An unspecified error occured
* @GST_GL_UPLOAD_UNSUPPORTED: The configuration is unsupported.
* @GST_GL_UPLOAD_RECONFIGURE: This element requires a reconfiguration.
*/
typedef enum
{

View file

@ -50,6 +50,12 @@ GType gst_gl_window_get_type (void);
GST_EXPORT
GQuark gst_gl_window_error_quark (void);
/**
* GST_GL_WINDOW_ERROR:
*
* Error domain for GStreamer's GL window module. Errors in this domain will be
* from the #GstGLWindowError enumeration
*/
#define GST_GL_WINDOW_ERROR (gst_gl_window_error_quark ())
/**
@ -68,7 +74,20 @@ typedef enum
typedef void (*GstGLWindowCB) (gpointer data);
typedef void (*GstGLWindowResizeCB) (gpointer data, guint width, guint height);
/**
* GST_GL_WINDOW_CB:
* @f: the function to cast
*
* Cast to the currect function type for generic window callbacks
*/
#define GST_GL_WINDOW_CB(f) ((GstGLWindowCB) (f))
/**
* GST_GL_WINDOW_RESIZE_CB:
* @f: the function to cast
*
* Cast to the currect function type for window resize callbacks
*/
#define GST_GL_WINDOW_RESIZE_CB(f) ((GstGLWindowResizeCB) (f))
/**