From 3e1c4a2c42af8a03aab6588b77c36014f1ab852a Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Tue, 23 Aug 2005 11:53:58 +0000 Subject: [PATCH] inlined more doc comments, added missing comments and fixed comments fixed typos Original commit message from CVS: * docs/gst/gstreamer-sections.txt: * docs/gst/tmpl/.cvsignore: * docs/gst/tmpl/gstbin.sgml: * docs/gst/tmpl/gstbuffer.sgml: * gst/base/gstbasesrc.c: * gst/gstbin.c: (gst_bin_get_type), (gst_bin_class_init): * gst/gstbuffer.c: * gst/gstbuffer.h: * tools/gst-launch.1.in: inlined more doc comments, added missing comments and fixed comments fixed typos --- ChangeLog | 14 ++ docs/gst/gstreamer-sections.txt | 6 +- docs/gst/tmpl/.gitignore | 4 + docs/gst/tmpl/gstbin.sgml | 219 ----------------- docs/gst/tmpl/gstbuffer.sgml | 407 -------------------------------- gst/base/gstbasesrc.c | 2 +- gst/gstbin.c | 56 ++++- gst/gstbuffer.c | 71 +++++- gst/gstbuffer.h | 193 ++++++++++++++- libs/gst/base/gstbasesrc.c | 2 +- tools/gst-launch.1.in | 2 +- 11 files changed, 342 insertions(+), 634 deletions(-) delete mode 100644 docs/gst/tmpl/gstbin.sgml delete mode 100644 docs/gst/tmpl/gstbuffer.sgml diff --git a/ChangeLog b/ChangeLog index c51537c831..8c9ba8d337 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2005-08-23 Stefan Kost + + * docs/gst/gstreamer-sections.txt: + * docs/gst/tmpl/.cvsignore: + * docs/gst/tmpl/gstbin.sgml: + * docs/gst/tmpl/gstbuffer.sgml: + * gst/base/gstbasesrc.c: + * gst/gstbin.c: (gst_bin_get_type), (gst_bin_class_init): + * gst/gstbuffer.c: + * gst/gstbuffer.h: + * tools/gst-launch.1.in: + inlined more doc comments, added missing comments and fixed comments + fixed typos + 2005-08-23 Thomas Vander Stichele * gst/gstbuffer.c: (gst_buffer_new_and_alloc): diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index a5be2f602f..46ba9c9f19 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -85,6 +85,7 @@ GST_BUFFER_DATA GST_BUFFER_SIZE GST_BUFFER_TIMESTAMP GST_BUFFER_DURATION +GST_BUFFER_CAPS GST_BUFFER_OFFSET GST_BUFFER_OFFSET_END @@ -109,17 +110,20 @@ GST_BUFFER_DURATION_IS_VALID GST_BUFFER_TIMESTAMP_IS_VALID GST_BUFFER_OFFSET_IS_VALID GST_BUFFER_OFFSET_END_IS_VALID +GST_BUFFER_MALLOCDATA - gst_buffer_stamp gst_buffer_join gst_buffer_merge GST_BUFFER +GST_BUFFER_CLASS GST_IS_BUFFER +GST_IS_BUFFER_CLASS GST_TYPE_BUFFER GST_TYPE_BUFFER_FLAG +GST_BUFFER_CAST gst_buffer_get_type gst_buffer_flag_get_type diff --git a/docs/gst/tmpl/.gitignore b/docs/gst/tmpl/.gitignore index b22ac3dc5d..cc2d236548 100644 --- a/docs/gst/tmpl/.gitignore +++ b/docs/gst/tmpl/.gitignore @@ -1,10 +1,14 @@ *.bak unused-build.stamp +gst.sgml gstadapter.sgml gstbasesink.sgml gstbasesrc.sgml gstbasetransform.sgml +gstbin.sgml +gstbuffer.sgml gstcollectpads.sgml +gstevent.sgml gstfakesrc.sgml gstfakesink.sgml gstfilesrc.sgml diff --git a/docs/gst/tmpl/gstbin.sgml b/docs/gst/tmpl/gstbin.sgml deleted file mode 100644 index 18938a4efb..0000000000 --- a/docs/gst/tmpl/gstbin.sgml +++ /dev/null @@ -1,219 +0,0 @@ - -GstBin - - -Base class for elements that contain other elements - - - -GstBin is the simplest of the container elements, allowing elements to -become children of itself. Pads from the child elements can be ghosted to -the bin, making the bin itself look transparently like any other element, -allowing for deep nesting of predefined sub-pipelines. - - -A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you want -to create a toplevel bin because a normal bin doesn't have a scheduler of its -own. - - -After the bin has been created you will typically add elements to it with -gst_bin_add(). You can remove elements with gst_bin_remove(). - - -An element can be retrieved from a bin with gst_bin_get_by_name(), using the -elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal -purposes and will query the parent bins when the element is not found in the -current bin. - - -The list of elements in a bin can be retrieved with gst_bin_get_list(). - - -After the bin has been set to the PLAYING state (with gst_element_set_state()), -gst_bin_iterate() is used to process the elements in the bin. - - -The "element_added" signal is fired whenever a new element is added to the bin. - - -The "element_removed" signal is fired whenever an element is removed from the bin. - - -gst_bin_destroy() is used to destroy the bin. - - -To control the selection of the clock in a bin, you can use the following methods: -gst_bin_auto_clock() to let the bin select a clock automatically, gst_bin_get_clock() to -get the current clock of the bin and gst_bin_use_clock() to specify a clock explicitly. -Note that the default behaviour is to automatically select a clock from one of the -clock providers in the bin. - - - - - - - - - - - - - - - -@numchildren: -@children: -@children_cookie: -@child_bus: -@eosed: - - - -Will be emitted if a new element was removed/added to this bin. - - -@gstbin: the object which received the signal. -@arg1: the element that was added to the bin. - - - -Will be emitted if an element was removed from this bin. - - -@gstbin: the object which received the signal. -@arg1: the element that was removed from the bin. - - - - - - -@parent_class: -@add_element: -@remove_element: - - - - - - -@GST_BIN_FLAG_LAST: - - - - - - -@name: -@Returns: - - - - - - - -@bin: -@element: -@Returns: - - - - - - - -@bin: -@element: -@Returns: - - - - - - - -@bin: -@name: -@Returns: - - - - - - - -@bin: -@name: -@Returns: - - - - - - - -@bin: -@interface: -@Returns: - - - - - - - -@bin: -@Returns: - - - - - - - -@bin: -@Returns: - - - - - - - -@bin: -@Returns: - - - - - - - -@bin: -@interface: -@Returns: - - - - - - - -@bin: -@element_1: -@Varargs: - - - - - - - -@bin: -@element_1: -@Varargs: - - diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml deleted file mode 100644 index 08d3c89932..0000000000 --- a/docs/gst/tmpl/gstbuffer.sgml +++ /dev/null @@ -1,407 +0,0 @@ - -GstBuffer - - -Data-passing buffer type, supporting sub-buffers. - - - -Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type -provides all the state necessary to define a region of memory as part of a -stream. Sub-buffers are also supported, allowing a smaller region of a -buffer to become its own buffer, with mechanisms in place to ensure that -neither memory space goes away. - - -Buffers are usually created with gst_buffer_new(). After a buffer has been -created one will typically allocate memory for it and set the size of the -buffer data. The following example creates a buffer that can hold a given -video frame with a given width, height and bits per plane. - -Creating a buffer for a video frame - - GstBuffer *buffer; - gint size, width, height, bpp; - - ... - - size = width * height * bpp; - - buffer = gst_buffer_new (); - GST_BUFFER_SIZE (buffer) = size; - GST_BUFFER_MALLOCDATA (buffer) = g_alloc (size); - GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer); - ... - - - - -Alternatively, use gst_buffer_new_and_alloc() -to create a buffer with preallocated data of a given size. - - -If an element knows what pad you will push the buffer out on, it should use -gst_pad_alloc_buffer() instead to create a buffer. This allows downstream -elements to provide special buffers to write in, like hardware buffers. - - -gst_buffer_ref() is used to increase the refcount of a buffer. This must be -done when you want to keep a handle to the buffer after pushing it to the -next element. - - -To efficiently create a smaller buffer out of an existing one, you can -use gst_buffer_create_sub(). - - -If the plug-in wants to modify the buffer in-place, it should first obtain -a buffer that is safe to modify by using gst_buffer_make_writable(). This -function is optimized so that a copy will only be made when it is necessary. - - -Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() -and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it -a certain #GstBufferFlag is set. - - -Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and -gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE. - - -An element should either unref the buffer or push it out on a src pad -using gst_pad_push() (see #GstPad). - -Buffers usually are freed by unreffing them with gst_buffer_unref(). -Do not use gst_buffer_free() : this function effectively frees the buffer -regardless of the refcount, which is dangerous. - - - -Last reviewed on August 12th, 2004 (0.8.5) - - - - -#GstPad, #GstMiniObject - - - - - - - -The basic structure of a buffer. - - -@mini_object: -@data: -@size: -@timestamp: -@duration: -@caps: -@offset: -@offset_end: - - - - - - -@Returns: - - - - - - - -@size: -@Returns: - - - - - - - -@GST_BUFFER_FLAG_READONLY: -@GST_BUFFER_FLAG_ORIGINAL: -@GST_BUFFER_FLAG_PREROLL: -@GST_BUFFER_FLAG_DISCONT: -@GST_BUFFER_FLAG_IN_CAPS: -@GST_BUFFER_FLAG_GAP: -@GST_BUFFER_FLAG_DELTA_UNIT: -@GST_BUFFER_FLAG_LAST: - - - -Gets the flags from this buffer. - - -@buf: a #GstBuffer to retrieve the flags from. - - - - -Gives the status of a given flag of a buffer. - - -@buf: a #GstBuffer to query flags of. -@flag: the #GstBufferFlag to check. - - - - -Sets a buffer flag. - - -@buf: a #GstBuffer to modify flags of. -@flag: the #GstBufferFlag to set. - - - - -Clears a buffer flag. - - -@buf: a #GstBuffer to modify flags of. -@flag: the #GstBufferFlag to clear. - - - - -A convenience function to set the data and size on a buffer - - -@buf: The buffer to modify -@data: The data to set on the buffer -@size: The size to set on the buffer - - - - -Retrieves a pointer to the data element of this buffer. - - -@buf: a #GstBuffer to get data pointer of. -@Returns: the pointer to the actual data contents of the buffer. - - - - -Gets the size of the data in this buffer. - - -@buf: a #GstBuffer to get data size of. - - - - -Gets the timestamp for this buffer. - - -@buf: a #GstBuffer to get timestamp of. - - - - -Gets the duration in nanoseconds of the data in the buffer. -Value will be GST_CLOCK_TIME_NONE if the duration is unknown. - - -@buf: a #GstBuffer to get the duration from. - - - - -Gets the offset in the source file of the beinning of this buffer. - - -@buf: a #GstBuffer to get offset of. - - - - -Gets the offset in the source file of the end of this buffer. - - -@buf: a #GstBuffer to get offset of. - - - - -Increases the refcount of the given buffer by one. - - -@buf: a #GstBuffer to increase the refcount of. - - - - -Decreases the refcount of the buffer. If the refcount reaches 0, the buffer -will be freed. - - -@buf: a #GstBuffer to unref. - - - - -Copies the given buffer using the copy function of the parent GstData structure. - - -@buf: a #GstBuffer to copy. -@Returns: a new #GstBuffer copy of the buffer. - - - - -Tests if you can safely write data into a buffer's data array. - - -@buf: a #GstBuffer to check - - - - - - - -@buf: - - - - - - - -@obuf: -@nbuf: - - - - - - - -@buffer: -@Returns: - - - - - - - -@buffer: -@caps: - - - - - - - -@parent: -@offset: -@size: -@Returns: - - - - - - - -@buf1: -@buf2: -@Returns: - - - - - - - -@buf1: -@offset: -@buf2: -@len: -@Returns: - - - - -The name used for tracing memory allocations - - - - - - - - - - - - - -Tests if the duration is known. - - -@buffer: the #GstBuffer to check for the duration - - - - -Tests if the timestamp is known. - - -@buffer: the #GstBuffer to check for the timestamp - - - - - - - -@buffer: - - - - - - - -@buffer: - - - - - - - -@dest: -@src: - - - - - - - -@buf1: -@buf2: -@Returns: - - - - - - - -@buf1: -@buf2: -@Returns: - - diff --git a/gst/base/gstbasesrc.c b/gst/base/gstbasesrc.c index 637c704702..b1abb15775 100644 --- a/gst/base/gstbasesrc.c +++ b/gst/base/gstbasesrc.c @@ -251,7 +251,7 @@ gst_base_src_set_live (GstBaseSrc * src, gboolean live) } /** - * gst_base_src_get_live: + * gst_base_src_is_live: * @src: base source instance * * Check if an element is in live mode. diff --git a/gst/gstbin.c b/gst/gstbin.c index 7a5bc86f9f..429b7ccec2 100644 --- a/gst/gstbin.c +++ b/gst/gstbin.c @@ -22,6 +22,46 @@ * * MT safe. */ +/** + * SECTION:gstbin + * @short_description: Base class for elements that contain other elements + * + * GstBin is the simplest of the container elements, allowing elements to + * become children of itself. Pads from the child elements can be ghosted to + * the bin, making the bin itself look transparently like any other element, + * allowing for deep nesting of predefined sub-pipelines. + * + * A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you + * want to create a toplevel bin because a normal bin doesn't have a scheduler + * of its own. + * + * After the bin has been created you will typically add elements to it with + * gst_bin_add(). You can remove elements with gst_bin_remove(). + * + * An element can be retrieved from a bin with gst_bin_get_by_name(), using the + * elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal + * purposes and will query the parent bins when the element is not found in the + * current bin. + * + * The list of elements in a bin can be retrieved with gst_bin_get_list(). + * + * After the bin has been set to the PLAYING state (with gst_element_set_state()), + * gst_bin_iterate() is used to process the elements in the bin. + * + * The "element_added" signal is fired whenever a new element is added to the + * bin. Likewise the "element_removed" signal is fired whenever an element is + * removed from the bin. + * + * gst_bin_destroy() is used to destroy the bin. + * + * To control the selection of the clock in a bin, you can use the following + * methods: + * gst_bin_auto_clock() to let the bin select a clock automatically, + * gst_bin_get_clock() to get the current clock of the bin and + * gst_bin_use_clock() to specify a clock explicitly. + * Note that the default behaviour is to automatically select a clock from one + * of the clock providers in the bin. + */ #include "gst_private.h" @@ -183,10 +223,24 @@ gst_bin_class_init (GstBinClass * klass) parent_class = g_type_class_ref (GST_TYPE_ELEMENT); + /** + * GstBin::element-added: + * @bin: the object which emitted the signal. + * @element: the element that was added to the bin + * + * Will be emitted if a new element was removed/added to this bin. + */ gst_bin_signals[ELEMENT_ADDED] = g_signal_new ("element-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstBinClass, element_added), NULL, NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_ELEMENT); + /** + * GstBin::element-removed: + * @bin: the object which emitted the signal. + * @element: the element that was removed from the bin + * + * Will be emitted if an element was removed from this bin. + */ gst_bin_signals[ELEMENT_REMOVED] = g_signal_new ("element-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstBinClass, element_removed), NULL, @@ -1688,7 +1742,7 @@ gst_bin_get_by_interface (GstBin * bin, GType interface) } /** - * gst_bin_get_all_by_interface: + * gst_bin_iterate_all_by_interface: * @bin: bin to find elements in * @interface: interface to be implemented by interface * diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c index a074ee791d..6166286941 100644 --- a/gst/gstbuffer.c +++ b/gst/gstbuffer.c @@ -19,7 +19,74 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ - +/** + * SECTION:gstbuffer + * @short_description: Data-passing buffer type, supporting sub-buffers. + * @see_also: #GstPad, #GstMiniObject + * + * Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type + * provides all the state necessary to define a region of memory as part of a + * stream. Sub-buffers are also supported, allowing a smaller region of a + * buffer to become its own buffer, with mechanisms in place to ensure that + * neither memory space goes away. + * + * Buffers are usually created with gst_buffer_new(). After a buffer has been + * created one will typically allocate memory for it and set the size of the + * buffer data. The following example creates a buffer that can hold a given + * video frame with a given width, height and bits per plane. + * + * Creating a buffer for a video frame + * + * GstBuffer *buffer; + * gint size, width, height, bpp; + * + * ... + * + * size = width * height * bpp; + * + * buffer = gst_buffer_new (); + * GST_BUFFER_SIZE (buffer) = size; + * GST_BUFFER_MALLOCDATA (buffer) = g_alloc (size); + * GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer); + * ... + * + * + * + * Alternatively, use gst_buffer_new_and_alloc() + * to create a buffer with preallocated data of a given size. + * + * If an element knows what pad you will push the buffer out on, it should use + * gst_pad_alloc_buffer() instead to create a buffer. This allows downstream + * elements to provide special buffers to write in, like hardware buffers. + * + * gst_buffer_ref() is used to increase the refcount of a buffer. This must be + * done when you want to keep a handle to the buffer after pushing it to the + * next element. + * + * To efficiently create a smaller buffer out of an existing one, you can + * use gst_buffer_create_sub(). + * + * If the plug-in wants to modify the buffer in-place, it should first obtain + * a buffer that is safe to modify by using gst_buffer_make_writable(). This + * function is optimized so that a copy will only be made when it is necessary. + * + * Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() + * and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it + * a certain #GstBufferFlag is set. + * + * Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() + * and gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE. + * + * An element should either unref the buffer or push it out on a src pad + * using gst_pad_push() (see #GstPad). + * + * Buffers usually are freed by unreffing them with gst_buffer_unref(). + * Do not use gst_buffer_free() : this function effectively frees the buffer + * regardless of the refcount, which is dangerous. + * + * Last reviewed on August 12th, 2004 (0.8.5) + * + */ #include "gst_private.h" #include "gstbuffer.h" @@ -320,7 +387,7 @@ gst_subbuffer_init (GTypeInstance * instance, gpointer g_class) } /** - * gst_buffer_create_subbuffer: + * gst_buffer_create_sub: * @parent: a parent #GstBuffer to create a subbuffer from. * @offset: the offset into parent #GstBuffer. * @size: the size of the new #GstBuffer sub-buffer (with size > 0). diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h index fc648ac462..550f3224fb 100644 --- a/gst/gstbuffer.h +++ b/gst/gstbuffer.h @@ -33,6 +33,11 @@ G_BEGIN_DECLS typedef struct _GstBuffer GstBuffer; typedef struct _GstBufferClass GstBufferClass; +/** + * GST_BUFFER_TRACE_NAME: + * + * The name used for tracing memory allocations. + */ #define GST_BUFFER_TRACE_NAME "GstBuffer" #define GST_TYPE_BUFFER (gst_buffer_get_type()) @@ -43,25 +48,157 @@ typedef struct _GstBufferClass GstBufferClass; #define GST_BUFFER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BUFFER, GstBufferClass)) #define GST_BUFFER_CAST(obj) ((GstBuffer *)(obj)) +/** + * GST_BUFFER_FLAGS: + * @buf: a #GstBuffer to retrieve the flags from. + * + * Gets the flags from this buffer. + * + * Returns: the set of #GstBufferFlag items + */ #define GST_BUFFER_FLAGS(buf) GST_MINI_OBJECT_FLAGS(buf) +/** + * GST_BUFFER_FLAG_IS_SET: + * @buf: a #GstBuffer to query flags of. + * @flag: the #GstBufferFlag to check. + * + * Gives the status of a given flag of a buffer. + * + * Returns: %TRUE if flag is set. + */ #define GST_BUFFER_FLAG_IS_SET(buf,flag) GST_MINI_OBJECT_FLAG_IS_SET (buf, flag) +/** + * GST_BUFFER_FLAG_SET: + * @buf: a #GstBuffer to modify flags of. + * @flag: the #GstBufferFlag to set. + * + * Sets a buffer flag. + */ #define GST_BUFFER_FLAG_SET(buf,flag) GST_MINI_OBJECT_FLAG_SET (buf, flag) +/** + * GST_BUFFER_FLAG_UNSET: + * @buf: a #GstBuffer to modify flags of. + * @flag: the #GstBufferFlag to clear. + * + * Clears a buffer flag. + */ #define GST_BUFFER_FLAG_UNSET(buf,flag) GST_MINI_OBJECT_FLAG_UNSET (buf, flag) +/** + * GST_BUFFER_DATA: + * @buf: a #GstBuffer to get data pointer of. + * + * Retrieves a pointer to the data element of this buffer. + * + * Returns: the pointer to the actual data contents of the buffer. + */ #define GST_BUFFER_DATA(buf) (GST_BUFFER_CAST(buf)->data) +/** + * GST_BUFFER_SIZE: + * @buf: a #GstBuffer to get data size of. + * + * Gets the size of the data in this buffer. + * + * Returns: the buffer size in bytes + */ #define GST_BUFFER_SIZE(buf) (GST_BUFFER_CAST(buf)->size) +/** + * GST_BUFFER_TIMESTAMP: + * @buf: a #GstBuffer to get the timestamp of.: + * + * Gets the timestamp for this buffer. + * + * Returns: the timestamp for this buffer + */ #define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER_CAST(buf)->timestamp) +/** + * GST_BUFFER_DURATION: + * @buf: a #GstBuffer to get the duration from. + * + * Gets the duration in nanoseconds of the data in the buffer. + * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown. + * + * Returns: the duration of the buffer + */ #define GST_BUFFER_DURATION(buf) (GST_BUFFER_CAST(buf)->duration) +/** + * GST_BUFFER_CAPS: + * @buf: a #GstBuffer to get the caps of. + * + * Gets the caps for this buffer. + * + * Returns: the #GstCaps for this buffer + */ #define GST_BUFFER_CAPS(buf) (GST_BUFFER_CAST(buf)->caps) +/** + * GST_BUFFER_OFFSET: + * @buf: a #GstBuffer to get the offset of. + * + * Gets the offset in the source file of the beginning of this buffer. + * + * Returns: the start offset for this buffer + */ #define GST_BUFFER_OFFSET(buf) (GST_BUFFER_CAST(buf)->offset) +/** + * GST_BUFFER_OFFSET_END: + * @buf: a #GstBuffer to get the offset of. + * + * Gets the offset in the source file of the end of this buffer. + * + * Returns: the end offset for this buffer + */ #define GST_BUFFER_OFFSET_END(buf) (GST_BUFFER_CAST(buf)->offset_end) +/** + * GST_BUFFER_MALLOCDATA: + * @buf: a #GstBuffer to get access to the malloc_data field + * + * If the buffers data should be automatically freed by buffer management at the + * end of the buffers lifecycle, also set the data to the mallocdata field. + */ #define GST_BUFFER_MALLOCDATA(buf) (GST_BUFFER_CAST(buf)->malloc_data) +/** + * GST_BUFFER_OFFSET_NONE: + * + * Constant for no-offset return results. + */ #define GST_BUFFER_OFFSET_NONE ((guint64)-1) +/** + * GST_BUFFER_DURATION_IS_VALID: + * @buffer: the #GstBuffer to check for the duration + * + * Tests if the duration is known. + * + * Returns: %TRUE for success + */ #define GST_BUFFER_DURATION_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer))) +/** + * GST_BUFFER_TIMESTAMP_IS_VALID: + * @buffer: the #GstBuffer to check for the timestamp + * + * Tests if the timestamp is known. + * + * Returns: %TRUE for success + */ #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer))) +/** + * GST_BUFFER_OFFSET_IS_VALID: + * @buffer: the #GstBuffer to check for the start offset + * + * Tests if the start offset is known. + * + * Returns: %TRUE for success + */ #define GST_BUFFER_OFFSET_IS_VALID(buffer) (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE) +/** + * GST_BUFFER_OFFSET_END_IS_VALID: + * @buffer: the #GstBuffer to check for the end offset + * + * Tests if the end offset is known. + * + * Returns: %TRUE for success + */ #define GST_BUFFER_OFFSET_END_IS_VALID(buffer) (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE) /** @@ -115,9 +252,9 @@ struct _GstBuffer { guint64 offset; guint64 offset_end; - /*< private >*/ guint8 *malloc_data; + /*< private >*/ gpointer _gst_reserved[GST_PADDING]; }; @@ -131,6 +268,14 @@ GType gst_buffer_get_type (void); GstBuffer* gst_buffer_new (void); GstBuffer* gst_buffer_new_and_alloc (guint size); +/** + * gst_buffer_set_data: + * @buf: The buffer to modify + * @data: The data to set on the buffer + * @size: The size to set on the buffer + * + * A convenience function to set the data and size on a buffer. + */ #define gst_buffer_set_data(buf, data, size) \ G_STMT_START { \ GST_BUFFER_DATA (buf) = data; \ @@ -138,13 +283,59 @@ G_STMT_START { \ } G_STMT_END /* refcounting */ +/** + * gst_buffer_ref: + * @buf: a #GstBuffer to increase the refcount of. + * + * Increases the refcount of the given buffer by one. + */ #define gst_buffer_ref(buf) GST_BUFFER_CAST (gst_mini_object_ref (GST_MINI_OBJECT (buf))) +/** + * gst_buffer_unref: + * @buf: a #GstBuffer to decrease the refcount of. + * + * Decreases the refcount of the buffer. If the refcount reaches 0, the buffer + * will be freed. + */ #define gst_buffer_unref(buf) gst_mini_object_unref (GST_MINI_OBJECT (buf)) + /* copy buffer */ +/** + * gst_buffer_copy: + * @buf: a #GstBuffer to copy. + * + * Copies the given buffer using the copy function of the parent #GstData + * structure. + * + * Returns: a new #GstBuffer copy of the buffer. + */ #define gst_buffer_copy(buf) GST_BUFFER_CAST (gst_mini_object_copy (GST_MINI_OBJECT (buf))) +/** + * gst_buffer_is_writable: + * @buf: a #GstBuffer to check + * + * Tests if you can safely write data into a buffer's data array. + * + * Returns: %TRUE if buffer is writable + */ #define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT (buf)) +/** + * gst_buffer_make_writable: + * @buf: a #GstBuffer to make writable + * + * Makes a buffer writable. + * + * Returns: a #GstBuffer that is writable + */ #define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT (buf))) +/** + * gst_buffer_replace: + * @obuf: a #GstBuffer to receive the data + * @nbuf: a #GstBuffer to take the data from + * + * Replaces the data in @obuf with the one in @nbuf + */ #define gst_buffer_replace(obuf,nbuf) gst_mini_object_replace ((GstMiniObject **)(obuf), GST_MINI_OBJECT (nbuf)) GstCaps* gst_buffer_get_caps (GstBuffer *buffer); diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c index 637c704702..b1abb15775 100644 --- a/libs/gst/base/gstbasesrc.c +++ b/libs/gst/base/gstbasesrc.c @@ -251,7 +251,7 @@ gst_base_src_set_live (GstBaseSrc * src, gboolean live) } /** - * gst_base_src_get_live: + * gst_base_src_is_live: * @src: base source instance * * Check if an element is in live mode. diff --git a/tools/gst-launch.1.in b/tools/gst-launch.1.in index d605bbf20b..4c12cd1358 100644 --- a/tools/gst-launch.1.in +++ b/tools/gst-launch.1.in @@ -135,7 +135,7 @@ set. Every element between the braces is put into the bin. Using curly braces (second line) is a short cut for using the first line and "thread" as the BINTYPE. .br -Please not the dot that has to be used after the BINTYPE. +Please note the dot that has to be used after the BINTYPE. .B Links