[gst-devel] Re: [gst-cvs] ensonic gstreamer: gstreamer/ gstreamer/docs/gst/ gstreamer/docs/gst/tmpl/ gstreamer/gst/
Thomas Vander Stichele
thomas at apestaart.org
Fri Sep 23 09:21:09 CEST 2005
Hi Stefan,
did you know that documenting args for function-like defines does not
work inline with gtk-doc 1.4 or older ? This breaks the build. Any
solution you know of ?
Thomas
On Fri, 2005-09-23 at 07:31 -0700, Stefan Kost wrote:
> CVS Root: /cvs/gstreamer
> Module: gstreamer
> Changes by: ensonic
> Date: Fri Sep 23 2005 07:31:33 PDT
>
> Log message:
> * docs/gst/gstreamer-sections.txt:
> * docs/gst/tmpl/.cvsignore:
> * docs/gst/tmpl/gstelement.sgml:
> * docs/gst/tmpl/gstinfo.sgml:
> * docs/gst/tmpl/gstobject.sgml:
> * gst/gstelement.c:
> * gst/gstelement.h:
> * gst/gstinfo.c:
> * gst/gstinfo.h:
> * gst/gstobject.c: (gst_object_class_init):
> * gst/gstobject.h:
> inlined 3 more biiiig doc files and added some missing docs on the fly
>
> Modified files:
> . : ChangeLog
> docs/gst : gstreamer-sections.txt
> docs/gst/tmpl : .cvsignore
> gst : gstelement.c gstelement.h gstinfo.c gstinfo.h
> gstobject.c gstobject.h
> Removed files:
> docs/gst/tmpl : gstelement.sgml gstinfo.sgml gstobject.sgml
>
> Links:
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/ChangeLog.diff?r1=1.1552&r2=1.1553
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/gstreamer-sections.txt.diff?r1=1.176&r2=1.177
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/.cvsignore.diff?r1=1.21&r2=1.22
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstelement.sgml
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstinfo.sgml
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstobject.sgml
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstelement.c.diff?r1=1.363&r2=1.364
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstelement.h.diff?r1=1.206&r2=1.207
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstinfo.c.diff?r1=1.105&r2=1.106
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstinfo.h.diff?r1=1.85&r2=1.86
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstobject.c.diff?r1=1.96&r2=1.97
> http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstobject.h.diff?r1=1.58&r2=1.59
>
> ====Begin Diffs====
> Index: ChangeLog
> ===================================================================
> RCS file: /cvs/gstreamer/gstreamer/ChangeLog,v
> retrieving revision 1.1552
> retrieving revision 1.1553
> diff -u -d -r1.1552 -r1.1553
> --- ChangeLog 23 Sep 2005 11:41:29 -0000 1.1552
> +++ ChangeLog 23 Sep 2005 14:31:21 -0000 1.1553
> @@ -1,3 +1,18 @@
> +2005-09-23 Stefan Kost <ensonic at users.sf.net>
> +
> + * docs/gst/gstreamer-sections.txt:
> + * docs/gst/tmpl/.cvsignore:
> + * docs/gst/tmpl/gstelement.sgml:
> + * docs/gst/tmpl/gstinfo.sgml:
> + * docs/gst/tmpl/gstobject.sgml:
> + * gst/gstelement.c:
> + * gst/gstelement.h:
> + * gst/gstinfo.c:
> + * gst/gstinfo.h:
> + * gst/gstobject.c: (gst_object_class_init):
> + * gst/gstobject.h:
> + inlined 3 more biiiig doc files and added some missing docs on the fly
> 2005-09-23 Thomas Vander Stichele <thomas at apestaart dot org>
>
> * check/gst/.cvsignore:
> Index: gstreamer-sections.txt
> RCS file: /cvs/gstreamer/gstreamer/docs/gst/gstreamer-sections.txt,v
> retrieving revision 1.176
> retrieving revision 1.177
> diff -u -d -r1.176 -r1.177
> --- gstreamer-sections.txt 22 Sep 2005 15:08:01 -0000 1.176
> +++ gstreamer-sections.txt 23 Sep 2005 14:31:21 -0000 1.177
> @@ -437,10 +437,10 @@
> GST_STATE_WAIT
> GST_ELEMENT_NAME
> GST_ELEMENT_PARENT
> +GST_ELEMENT_BUS
> GST_ELEMENT_CLOCK
> GST_ELEMENT_PADS
> GST_ELEMENT_ERROR
> -GST_ELEMENT_BUS
> GST_ELEMENT_WARNING
> GST_ELEMENT_IS_LOCKED_STATE
> Index: .cvsignore
> RCS file: /cvs/gstreamer/gstreamer/docs/gst/tmpl/.cvsignore,v
> retrieving revision 1.21
> retrieving revision 1.22
> diff -u -d -r1.21 -r1.22
> --- .cvsignore 21 Sep 2005 09:48:40 -0000 1.21
> +++ .cvsignore 23 Sep 2005 14:31:21 -0000 1.22
> @@ -15,6 +15,7 @@
> gstcollectpads.sgml
> gstcompat.sgml
> gstconfig.sgml
> +gstelement.sgml
> gstelementdetails.sgml
> gstelementfactory.sgml
> gstenumtypes.sgml
> @@ -30,11 +31,13 @@
> gstimplementsinterface.sgml
> gstindex.sgml
> gstindexfactory.sgml
> +gstinfo.sgml
> gstiterator.sgml
> gstmacros.sgml
> gstmemchunk.sgml
> gstmessage.sgml
> gstminiobject.sgml
> +gstobject.sgml
> gstparse.sgml
> gstpluginfeature.sgml
> gstpushsrc.sgml
> --- gstelement.sgml DELETED ---
> --- gstinfo.sgml DELETED ---
> --- gstobject.sgml DELETED ---
> Index: gstelement.c
> RCS file: /cvs/gstreamer/gstreamer/gst/gstelement.c,v
> retrieving revision 1.363
> retrieving revision 1.364
> diff -u -d -r1.363 -r1.364
> --- gstelement.c 22 Sep 2005 18:07:22 -0000 1.363
> +++ gstelement.c 23 Sep 2005 14:31:21 -0000 1.364
> @@ -19,7 +19,52 @@
> * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
> * Boston, MA 02111-1307, USA.
> */
> -
> +/**
> + * SECTION:gstelement
> + * @short_description: Abstract base class for all pipeline elements
> + * @see_also: #GstElementFactory, #GstPad
> + *
> + * GstElement is the base class needed to construct an element that can be
> + * used in a GStreamer pipeline. As such, it is not a functional entity, and
> + * cannot do anything when placed in a pipeline.
> + *
> + * The name of a GstElement can be get with gst_element_get_name() and set with
> + * gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
> + * core. Do not use this in plug-ins or applications in order to retain ABI
> + * compatibility.
> + * All elements have pads (of the type #GstPad). These pads link to pads on
> + * other elements. Buffers flow between these linked pads.
> + * A GstElement has a GList of #GstPad structures for all their input (or sink)
> + * and output (or source) pads.
> + * Core and plug-in writers can add and remove pads with gst_element_add_pad()
> + * and gst_element_remove_pad().
> + * Application writers can manipulate ghost pads (copies of real pads inside a bin)
> + * with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
> + * A pad of an element can be retrieved by name with gst_element_get_pad().
> + * A GList of all pads can be retrieved with gst_element_get_pad_list().
> + * Elements can be linked through their pads.
> + * If the link is straightforward, use the gst_element_link()
> + * convenience function to link two elements, or gst_element_link_many()
> + * for more elements in a row.
> + * Use gst_element_link_filtered() to link two elements constrained by
> + * a specified set of #GstCaps.
> + * For finer control, use gst_element_link_pads() and
> + * gst_element_link_pads_filtered() to specify the pads to link on
> + * each element by name.
> + * Each element has a state (see #GstState). You can get and set the state
> + * of an element with gst_element_get_state() and gst_element_set_state().
> + * You can wait for an element to change it's state with gst_element_wait_state_change().
> + * To get a string representation of a #GstState, use
> + * gst_element_state_get_name().
> + * You can get and set a #GstClock on an element using gst_element_get_clock()
> + * and gst_element_set_clock(). You can wait for the clock to reach a given
> + * #GstClockTime using gst_element_clock_wait().
> + */
> #include "gst_private.h"
> #include <glib.h>
> #include <stdarg.h>
> Index: gstelement.h
> RCS file: /cvs/gstreamer/gstreamer/gst/gstelement.h,v
> retrieving revision 1.206
> retrieving revision 1.207
> diff -u -d -r1.206 -r1.207
> --- gstelement.h 22 Sep 2005 16:51:27 -0000 1.206
> +++ gstelement.h 23 Sep 2005 14:31:21 -0000 1.207
> @@ -82,7 +82,21 @@
> /* NOTE: this probably should be done with an #ifdef to decide
> * whether to safe-cast or to just do the non-checking cast.
> + * GST_STATE:
> + * @obj: Element to return state for.
> + * This macro returns the current state of the element.
> #define GST_STATE(obj) (GST_ELEMENT(obj)->current_state)
> + * GST_STATE_PENDING:
> + * @obj: Element to return the pending state for.
> + * This macro returns the currently pending state of the element.
> #define GST_STATE_PENDING(obj) (GST_ELEMENT(obj)->pending_state)
> #define GST_STATE_FINAL(obj) (GST_ELEMENT(obj)->final_state)
> #define GST_STATE_ERROR(obj) (GST_ELEMENT(obj)->state_error)
> @@ -125,28 +139,72 @@
> GST_STATE_CHANGE_READY_TO_NULL = 1<<(GST_STATE_READY+8) | 1<<GST_STATE_NULL
> } GstStateChange;
> + * GstElementFlags:
> + * @GST_ELEMENT_LOCKED_STATE: ignore state changes from parent
> + * @GST_ELEMENT_IS_SINK: the element is a sink
> + * @GST_ELEMENT_UNPARENTING: Child is being removed from the parent bin.
> + * gst_bin_remove() on a child already being removed immediately returns FALSE
> + * @GST_ELEMENT_FLAG_LAST: offset to define more flags
> + * The standard flags that an element may have.
> typedef enum
> {
> - /* ignore state changes from parent */
> GST_ELEMENT_LOCKED_STATE = GST_OBJECT_FLAG_LAST,
> -
> - /* the element is a sink */
> GST_ELEMENT_IS_SINK,
> - /* Child is being removed from the parent bin. gst_bin_remove on a
> - * child already being removed immediately returns FALSE */
> GST_ELEMENT_UNPARENTING,
> - /* use some padding for future expansion */
> GST_ELEMENT_FLAG_LAST = GST_OBJECT_FLAG_LAST + 16
> } GstElementFlags;
> + * GST_ELEMENT_IS_LOCKED_STATE:
> + * @obj: A #GstElement to query
> + * Check if the element is in the loacked state and therefore will ignore state
> + * changes from its parent object.
> #define GST_ELEMENT_IS_LOCKED_STATE(obj) (GST_FLAG_IS_SET(obj,GST_ELEMENT_LOCKED_STATE))
> + * GST_ELEMENT_NAME:
> + * Gets the name of this element. Use only in core as this is not
> + * ABI-compatible. Others use gst_element_get_name()
> #define GST_ELEMENT_NAME(obj) (GST_OBJECT_NAME(obj))
> + * GST_ELEMENT_PARENT:
> + * Get the parent object of this element.
> #define GST_ELEMENT_PARENT(obj) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj)))
> + * GST_ELEMENT_BUS:
> + * Get the message bus of this element.
> #define GST_ELEMENT_BUS(obj) (GST_ELEMENT_CAST(obj)->bus)
> + * GST_ELEMENT_CLOCK:
> + * Get the clock of this element
> #define GST_ELEMENT_CLOCK(obj) (GST_ELEMENT_CAST(obj)->clock)
> + * GST_ELEMENT_PADS:
> + * Get the pads of this elements.
> #define GST_ELEMENT_PADS(obj) (GST_ELEMENT_CAST(obj)->pads)
> /**
> @@ -176,7 +234,20 @@
> __txt, __dbg, __FILE__, GST_FUNCTION, __LINE__); \
> } G_STMT_END
> -/* log a (non-fatal) warning message and post it on the bus */
> + * GST_ELEMENT_WARNING:
> + * @el: the element that throws the error
> + * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError)
> + * @code: error code defined for that domain (see #GstError)
> + * @text: the message to display (format string and args enclosed in
> + parentheses)
> + * @debug: debugging information for the message (format string and args
> + enclosed in parentheses)
> + * Utility function that elements can use in case they encountered a non-fatal
> + * data processing problem. The pipeline will throw a warning signal and the
> + * application will be informed.
> #define GST_ELEMENT_WARNING(el, domain, code, text, debug) \
> G_STMT_START { \
> gchar *__txt = _gst_element_error_printf text; \
> @@ -304,9 +375,43 @@
> GType gst_element_get_type (void);
> /* basic name and parentage stuff from GstObject */
> + * gst_element_get_name:
> + * @elem: a #GstElement to set the name of.
> + * @name: the new name of the element.
> + * Gets the name of the element.
> #define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT(elem))
> + * gst_element_set_name:
> + * Sets the name of the element, getting rid of the old name if there was one.
> + * Returns: the name of the element.
> #define gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT(elem),name)
> + * gst_element_get_parent:
> + * @elem: a #GstElement to get the parent of.
> + * Gets the parent of an element.
> + * Returns: the #GstObject parent of the element.
> #define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT(elem))
> + * gst_element_set_parent:
> + * @elem: a #GstElement to set the parent of.
> + * @name: the new parent #GstObject of the element.
> + * Sets the parent of an element.
> #define gst_element_set_parent(elem,parent) gst_object_set_parent(GST_OBJECT(elem),parent)
> /* clocking */
> Index: gstinfo.c
> RCS file: /cvs/gstreamer/gstreamer/gst/gstinfo.c,v
> retrieving revision 1.105
> retrieving revision 1.106
> diff -u -d -r1.105 -r1.106
> --- gstinfo.c 21 Sep 2005 21:39:06 -0000 1.105
> +++ gstinfo.c 23 Sep 2005 14:31:21 -0000 1.106
> @@ -20,6 +20,64 @@
> + * SECTION:gstinfo
> + * @short_description: Debugging and logging facillities
> + * @see_also: #GstConfig, #Gst for command line parameters
> + * and environment variables that affect the debugging output.
> + * GStreamer's debugging subsystem is an easy way to get information about what
> + * the application is doing.
> + * It is not meant for programming errors. Use GLibs methods (g_warning and so
> + * on for that.
> + * The debugging subsystem works only after GStreamer has been initilized
> + * - for example by calling gst_init().
> + * The debugging subsystem is used to log informational messages while the
> + * application runs.
> + * Each messages has some properties attached to it. Among these properties
> + * are the debugging category, the severity (called "level" here) and an obtional
> + * #GObject it belongs to. Each of these messages is sent to all registered
> + * debugging handlers, which then handle the messages. GStreamer attaches a
> + * default handler on startup, which outputs requested messages to stderr.
> + * Messages are output by using shortcut macros like #GST_DEBUG,
> + * #GST_CAT_ERROR_OBJECT or similar. These all expand to calling gst_debug_log()
> + * with the right parameters.
> + * The only thing a developer will probably want to do is define his own
> + * categories. This is easily done with 3 lines. At the top of your code, declare
> + * the variables and set the default category.
> + * <informalexample>
> + * <programlisting>
> + * GST_DEBUG_CATEGORY (my_category); // define category
> + * &hash;define GST_CAT_DEFAULT my_category // set as default
> + * </programlisting>
> + * </informalexample>
> + * After that you only need to initialize the category.
> + * GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
> + * Initialization must be done before the category is used first. Plugins do this
> + * in their plugin_init function, libraries and applications should do that
> + * during their initialization.
> + * The whole debugging subsystem can be disabled at build time with passing the
> + * --disable-gst-debug switch to configure. If this is done, every function, macro
> + * and even structs described in this file evaluate to default values or nothing
> + * at all. So don't take addresses of these functions or use other tricks.
> + * If you must do that for some reason, there is still an option. If the debugging
> + * subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in <gst/gst.h>,
> + * so you can check that before doing your trick.
> + * Disabling the debugging subsystem will give you a slight (read: unnoticable)
> + * speed increase and will reduce the size of your compiled code. The GStreamer
> + * library itself becomes around 10% smaller.
> + * Please note that there are naming conventions for the names of debugging
> + * categories. These are explained at GST_DEBUG_CATEGORY_INIT().
> #include "gstinfo.h"
> Index: gstinfo.h
> RCS file: /cvs/gstreamer/gstreamer/gst/gstinfo.h,v
> retrieving revision 1.85
> retrieving revision 1.86
> diff -u -d -r1.85 -r1.86
> --- gstinfo.h 20 Jul 2005 16:20:39 -0000 1.85
> +++ gstinfo.h 23 Sep 2005 14:31:21 -0000 1.86
> @@ -30,14 +30,36 @@
> G_BEGIN_DECLS
> -/*
> - * GStreamer's debugging subsystem is an easy way to get information about what
> - * the application is doing.
> - * It is not meant for programming errors. Use GLibs methods (g_warning and so
> - * on for that.
> + * GstDebugLevel:
> + * @GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate
> + * debugging output.
> + * @GST_LEVEL_ERROR: Error messages are to be used only when an error occured
> + * that stops the application from keeping working correctly.
> + * An examples is gst_element_error, which outputs a message with this priority.
> + * It does not mean that the application is terminating as with g_errror.
> + * @GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour
> + * that could lead to problems or weird behaviour later on. An example of this
> + * would be clocking issues ("your computer is pretty slow") or broken input
> + * data ("Can't synchronize to stream.")
> + * @GST_LEVEL_INFO: Informational messages should be used to keep the developer
> + * updated about what is happening.
> + * Examples where this should be used are when a typefind function has
> + * successfully determined the type of the stream or when an mp3 plugin detects
> + * the format to be used. ("This file has mono sound.")
> + * @GST_LEVEL_DEBUG: Debugging messages should be used when something common
> + * happens that is not the expected default behavior.
> + * An example would be notifications about state changes or receiving/sending of
> + * events.
> + * @GST_LEVEL_LOG: Log messages are messages that are very common but might be
> + * useful to know. As a rule of thumb a pipeline that is iterating as expected
> + * should never output anzthing else but LOG messages.
> + * Examples for this are referencing/dereferencing of objects or cothread switches.
> + * @GST_LEVEL_COUNT: The number of defined debugging levels.
> + * The level defines the importance of a debugging message. The more important a
> + * message is, the greater the probability that the debugging system outputs it.
> -/* log levels */
> typedef enum {
> GST_LEVEL_NONE = 0,
> GST_LEVEL_ERROR,
> @@ -49,8 +71,16 @@
> GST_LEVEL_COUNT
> } GstDebugLevel;
> -/* we can now override this to be more general in maintainer builds
> - * or cvs checkouts */
> + * GST_LEVEL_DEFAULT:
> + * Defines the default debugging level to be used with GStreamer. It is normally
> + * set to #GST_LEVEL_NONE so nothing get printed.
> + * As it can be configured at compile time, developer builds may chose to
> + * override that though.
> + * You can use this as an argument to gst_debug_set_default_threshold() to
> + * reset the debugging output to default behaviour.
> #ifndef GST_LEVEL_DEFAULT
> #define GST_LEVEL_DEFAULT GST_LEVEL_NONE
> #endif
> @@ -64,6 +94,30 @@
> * Background color codes:
> * 40=black 41=red 42=green 43=yellow 44=blue 45=magenta 46=cyan 47=white
> + * GstDebugColorFlags:
> + * @GST_DEBUG_FG_BLACK: Use black as foreground color.
> + * @GST_DEBUG_FG_RED: Use red as foreground color.
> + * @GST_DEBUG_FG_GREEN: Use green as foreground color.
> + * @GST_DEBUG_FG_YELLOW: Use yellow as foreground color.
> + * @GST_DEBUG_FG_BLUE: Use blue as foreground color.
> + * @GST_DEBUG_FG_MAGENTA: Use magenta as foreground color.
> + * @GST_DEBUG_FG_CYAN: Use cyan as foreground color.
> + * @GST_DEBUG_FG_WHITE: Use white as foreground color.
> + * @GST_DEBUG_BG_BLACK: Use black as background color.
> + * @GST_DEBUG_BG_RED: Use red as background color.
> + * @GST_DEBUG_BG_GREEN: Use green as background color.
> + * @GST_DEBUG_BG_YELLOW: Use yellow as background color.
> + * @GST_DEBUG_BG_BLUE: Use blue as background color.
> + * @GST_DEBUG_BG_MAGENTA: Use magenta as background color.
> + * @GST_DEBUG_BG_CYAN: Use cyan as background color.
> + * @GST_DEBUG_BG_WHITE: Use white as background color.
> + * @GST_DEBUG_BOLD: Make the output bold.
> + * @GST_DEBUG_UNDERLINE: Underline the output.
> + * These are some terminal style flags you can use when creating your
> + * debugging categories to make them stand out in debugging output.
> /* colors */
> GST_DEBUG_FG_BLACK = 0x0000,
> @@ -93,6 +147,12 @@
> #define GST_DEBUG_FORMAT_MASK (0xFF00)
> typedef struct _GstDebugCategory GstDebugCategory;
> + * GstDebugCategory:
> + * This is the struct that describes the categories. Once initialized with
> + * #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
> struct _GstDebugCategory {
> /*< private >*/
> gint threshold;
> @@ -104,17 +164,39 @@
> /********** some convenience macros for debugging **********/
> -/* This is needed in printf's if a char* might be NULL. Solaris crashes then. */
> + * GST_STR_NULL:
> + * @str: The string to check.
> + * Macro to use when a string must not be NULL, but may be NULL. If the string
> + * is NULL, "(NULL)" is printed instead.
> + * In GStreamer printf string arguments may not be NULL, because on some
> + * platforms (ie Solaris) the libc crashes in that case. This includes debugging
> + * strings.
> #define GST_STR_NULL(str) ((str) ? (str) : "(NULL)")
> -/* easier debugging for pad names */
> /* FIXME, not MT safe */
> + * GST_DEBUG_PAD_NAME:
> + * @pad: The pad to debug.
> + * Evaluates to 2 strings, that describe the pad. Often used in debugging
> + * statements.
> #define GST_DEBUG_PAD_NAME(pad) \
> (GST_OBJECT_PARENT(pad) != NULL) ? \
> GST_STR_NULL (GST_OBJECT_NAME (GST_OBJECT_PARENT(pad))) : \
> "''", GST_OBJECT_NAME (pad)
> -/* You might want to define GST_FUNCTION in apps' configure script. */
> + * GST_FUNCTION:
> + * This macro should evaluate to the name of the current function and be should
> + * be defined when configuring your project, as it is compiler dependant. If it
> + * is not defined, some default value is used. It is used to provide debugging
> + * output with the function name of the message.
> #ifndef GST_FUNCTION
> #if defined (__GNUC__)
> # define GST_FUNCTION ((const char*) (__PRETTY_FUNCTION__))
> @@ -275,10 +357,26 @@
> gchar * gst_debug_construct_term_color (guint colorinfo);
> + * GST_CAT_DEFAULT:
> + * Default gstreamer core debug log category. Please define your own.
> GST_EXPORT GstDebugCategory * GST_CAT_DEFAULT;
> /* this symbol may not be used */
> extern gboolean __gst_debug_enabled;
> + * GST_CAT_LEVEL_LOG:
> + * @cat: category to use
> + * @level: the severity of the message
> + * @object: the #GObject the message belongs to or NULL if none
> + * @...: A printf-style message to output
> + * Outputs a debugging message. This is the most general macro for outputting
> + * debugging messages. You will probably want to use one of the ones described
> + * below.
> #ifdef G_HAVE_ISO_VARARGS
> #define GST_CAT_LEVEL_LOG(cat,level,object,...) G_STMT_START{ \
> if (__gst_debug_enabled) { \
> @@ -318,6 +416,156 @@
> #endif /* G_HAVE_ISO_VARARGS */
> + * GST_CAT_ERROR_OBJECT:
> + * @obj: the #GObject the message belongs to
> + * @...: printf-style message to output
> + * Output an error message belonging to the given object in the given category.
> + * GST_CAT_WARNING_OBJECT:
> + * Output a warning message belonging to the given object in the given category.
> + * GST_CAT_INFO_OBJECT:
> + * Output an informational message belonging to the given object in the given
> + * category.
> + * GST_CAT_DEBUG_OBJECT:
> + * Output an debugging message belonging to the given object in the given category.
> + * GST_CAT_LOG_OBJECT:
> + * Output an logging message belonging to the given object in the given category.
> + * GST_CAT_ERROR:
> + * Output an error message in the given category.
> + * GST_CAT_WARNING:
> + * Output an warning message in the given category.
> + * GST_CAT_INFO:
> + * Output an informational message in the given category.
> + * GST_CAT_DEBUG:
> + * Output an debugging message in the given category.
> + * GST_CAT_LOG:
> + * Output an logging message in the given category.
> + * GST_ERROR_OBJECT:
> + * Output an error message belonging to the given object in the default category.
> + * GST_WARNING_OBJECT:
> + * Output a warning message belonging to the given object in the default category.
> + * GST_INFO_OBJECT:
> + * Output an informational message belonging to the given object in the default
> + * GST_DEBUG_OBJECT:
> + * Output a debugging message belonging to the given object in the default
> + * GST_LOG_OBJECT:
> + * Output a logging message belonging to the given object in the default category.
> +
> + * GST_ERROR:
> + * Output an error message in the default category.
> + * GST_WARNING:
> + * Output a warning message in the default category.
> + * GST_INFO:
> + * Output an informational message in the default category.
> + * GST_DEBUG:
> + * Output a debugging message in the default category.
> + * GST_LOG:
> + * Output a logging message in the default category.
> #define GST_CAT_ERROR_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_ERROR, obj, __VA_ARGS__)
> @@ -592,14 +840,36 @@
> /********** function pointer stuff **********/
> typedef void (* GstDebugFuncPtr) (void);
> void _gst_debug_register_funcptr (GstDebugFuncPtr func,
> gchar * ptrname);
> G_CONST_RETURN gchar *
> _gst_debug_nameof_funcptr (GstDebugFuncPtr func);
> + * GST_DEBUG_FUNCPTR:
> + * @ptr: pointer to the function to register
> + * Register a pointer to a function with its name, so it can later be used by
> + * GST_DEBUG_FUNCPTR_NAME().
> + * Returns: The ptr to the function
> #define GST_DEBUG_FUNCPTR(ptr) \
> (_gst_debug_register_funcptr((GstDebugFuncPtr)(ptr), #ptr) , ptr)
> + * GST_DEBUG_FUNCPTR_NAME:
> + * @ptr: pointer to the function to look up the name
> + * Retrieves the name of the function, if it was previously registered with
> + * GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer.
> + * Make sure you free the string after use.
> + * Returns: The name of the function
> #define GST_DEBUG_FUNCPTR_NAME(ptr) \
> _gst_debug_nameof_funcptr((GstDebugFuncPtr)ptr)
> Index: gstobject.c
> RCS file: /cvs/gstreamer/gstreamer/gst/gstobject.c,v
> retrieving revision 1.96
> retrieving revision 1.97
> diff -u -d -r1.96 -r1.97
> --- gstobject.c 20 Sep 2005 11:09:50 -0000 1.96
> +++ gstobject.c 23 Sep 2005 14:31:21 -0000 1.97
> @@ -20,6 +20,60 @@
> + * SECTION:gstobject
> + * @short_description: Base class for the GStreamer object hierarchy
> + * GstObject provides a root for the object hierarchy tree filed in by the
> + * GST library. It is currently a thin wrapper on top of
> + * #GObject. It is an abstract class that is not very usable on its own.
> + * GstObject gives us basic refcounting, parenting functionality and locking.
> + * Most of the function are just extended for special gstreamer needs and can be
> + * found under the same name in the base class of GstObject which is GObject
> + * (e.g. g_object_ref() becomes gst_object_ref()).
> + * The most interesting difference between GstObject and GObject is the "floating"
> + * reference count. A GObject is created with a reference count of 1, owned by the
> + * creator of the GObject. (The owner of a reference is the code section that has
> + * the right to call gst_object_unref() in order to remove that reference.)
> + * A GstObject is created with a reference count of 1 also, but it isn't owned by
> + * anyone; calling gst_object_unref() on the newly-created GtkObject is incorrect.
> + * Instead, the initial reference count of a GstObject is "floating". The floating
> + * reference can be removed by anyone at any time, by calling gst_object_sink().
> + * gst_object_sink() does nothing if an object is already sunk (has no floating
> + * reference).
> + * When you add a GstElement to its parent container, the parent container will do
> + * this:
> + * gst_object_ref (GST_OBJECT (child_element));
> + * gst_object_sink (GST_OBJECT (child_element));
> + * This means that the container now owns a reference to the child element (since
> + * it called gst_object_ref()), and the child element has no floating reference.
> + * The purpose of the floating reference is to keep the child element alive until
> + * you add it to a parent container:
> + * element = gst_element_factory_make (factoryname, name);
> + * // element has one floating reference to keep it alive
> + * gst_bin_add (GST_BIN (bin), element);
> + * // element has one non-floating reference owned by the container
> + * Another effect of this is, that calling gst_object_unref() on a bin object, will
> + * also destoy all the GstElement objects in it. The same is true for calling
> + * gst_bin_remove().
> + * In contrast to GObject instances GstObject add a name property. The functions
> + * gst_object_set_name() and gst_object_get_name() are used to set/get the name
> + * of the object.
> @@ -44,7 +98,7 @@
> * we use our own atomic refcounting to do proper MT safe refcounting.
> *
> * The hack has several side-effect. At first you should use
> - * gst_object_ref/unref() whenever you can. Next When using g_value_set/get_object();
> + * gst_object_ref/unref() whenever you can. Next when using g_value_set/get_object();
> * you need to manually fix the refcount.
> * A proper fix is of course to make the glib refcounting threadsafe which is
> @@ -168,16 +222,42 @@
> g_param_spec_string ("name", "Name", "The name of the object",
> NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
> + /**
> + * GstObject::parent-set:
> + * @gstobject: the object which received the signal.
> + * @parent: the new parent
> + *
> + * Is emitted when the parent of an object is set.
> + */
> gst_object_signals[PARENT_SET] =
> g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
> G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,
> g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
> + * GstObject::parent-unset:
> + * @parent: the old parent
> + * Is emitted when the parent of an object is unset.
> gst_object_signals[PARENT_UNSET] =
> g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),
> G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,
> NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
> #ifndef GST_DISABLE_LOADSAVE_REGISTRY
> - /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER */
> + * GstObject::object-saved:
> + * @xml_node: the xmlNodePtr of the parent node
> + * Is trigered whenever a new object is saved to XML. You can connect to this
> + * signal to insert custom XML tags into the core XML.
> + /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER
> + * (if libxml would use GObject)
> gst_object_signals[OBJECT_SAVED] =
> g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),
> G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,
> @@ -185,6 +265,17 @@
> klass->restore_thyself = gst_object_real_restore_thyself;
> + * GstObject::deep-notify:
> + * @prop_object: the object that originated the signal
> + * @prop: the property that changed
> + * The deep notify signal is used to be notified of property changes. It is
> + * typically attached to the toplevel bin to receive notifications from all
> + * the elements contained in that bin.
> gst_object_signals[DEEP_NOTIFY] =
> g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
> G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
> Index: gstobject.h
> RCS file: /cvs/gstreamer/gstreamer/gst/gstobject.h,v
> retrieving revision 1.58
> retrieving revision 1.59
> diff -u -d -r1.58 -r1.59
> --- gstobject.h 20 Sep 2005 11:09:50 -0000 1.58
> +++ gstobject.h 23 Sep 2005 14:31:21 -0000 1.59
> @@ -41,12 +41,20 @@
> #define GST_OBJECT_CAST(obj) ((GstObject*)(obj))
> #define GST_OBJECT_CLASS_CAST(klass) ((GstObjectClass*)(klass))
> -/* make sure we don't change the object size but stil make it compile
> +/* make sure we don't change the object size but still make it compile
> * without libxml */
> #ifdef GST_DISABLE_LOADSAVE_REGISTRY
> #define xmlNodePtr gpointer
> + * GstObjectFlags:
> + * @GST_OBJECT_DISPOSING: the object is been destroyed, do use it anymore
> + * @GST_OBJECT_FLOATING: the object has a floating reference count (e.g. its
> + * not assigned to a bin)
> + * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
> GST_OBJECT_DISPOSING = 0,
> @@ -65,26 +73,112 @@
> /* we do a GST_OBJECT_CAST to avoid type checking, better call these
> * function with a valid object! */
> + * GST_LOCK:
> + * @obj: Object to lock.
> + * This macro will obtain a lock on the object, making serialization possible.
> + * It block until the lock can be obtained.
> #define GST_LOCK(obj) g_mutex_lock(GST_OBJECT_CAST(obj)->lock)
> + * GST_TRYLOCK:
> + * @obj: Object to try to get a lock on.
> + * This macro will try to obtain a lock on the object, but will return with
> + * FALSE if it can't get it immediately.
> #define GST_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_CAST(obj)->lock)
> + * @obj: Object to unlock.
> + * This macro releases a lock on the object.
> #define GST_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_CAST(obj)->lock)
> + * @obj: Object to get the mutex of.
> + * Acquire a reference to the mutex of this object.
> #define GST_GET_LOCK(obj) (GST_OBJECT_CAST(obj)->lock)
> + * GST_OBJECT_NAME:
> + * @obj: Object to get the name of.
> + * Get the name of this object
> #define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name)
> + * GST_OBJECT_PARENT:
> + * @obj: Object to get the parent of.
> + * Get the parent of this object
> #define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent)
> -/* for the flags we double-not to make them comparable to TRUE and FALSE */
> + * GST_FLAGS:
> + * @obj: Object to return flags for.
> + * This macro returns the entire set of flags for the object.
> #define GST_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags)
> +/* for the flags we double-not to make them comparable to TRUE and FALSE */
> + * GST_FLAG_IS_SET:
> + * @obj: Object to check for flags.
> + * @flag: Flag to check for, must be a single bit in guint32.
> + * This macro checks to see if the given flag is set.
> #define GST_FLAG_IS_SET(obj,flag) (!!(GST_FLAGS (obj) & (1<<(flag))))
> + * GST_FLAG_SET:
> + * @obj: Object to set flag in.
> + * @flag: Flag to set, can by any number of bits in guint32.
> + * This macro sets the given bits.
> #define GST_FLAG_SET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) |= (1<<(flag))); }G_STMT_END
> + * GST_FLAG_UNSET:
> + * @obj: Object to unset flag in.
> + * @flag: Flag to set, must be a single bit in guint32.
> + * This macro usets the given bits.
> #define GST_FLAG_UNSET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) &= ~(1<<(flag))); }G_STMT_END
> + * GST_OBJECT_IS_DISPOSING:
> + * @obj: Object to check
> + * Check if the given object is beeing destroyed.
> #define GST_OBJECT_IS_DISPOSING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
> + * GST_OBJECT_IS_FLOATING:
> + * @obj:Object to check
> + * Check if the given object is floating (has no owner).
> #define GST_OBJECT_IS_FLOATING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
> typedef struct _GstObject GstObject;
> typedef struct _GstObjectClass GstObjectClass;
> + * GstObject:
> + * @name: The name of the object
> struct _GstObject {
> GObject object;
>
>
> -------------------------------------------------------
> SF.Net email is sponsored by:
> Tame your development challenges with Apache's Geronimo App Server.
> Download it for free - -and be entered to win a 42" plasma tv or your very
> own Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php
> _______________________________________________
> gstreamer-cvs-verbose mailing list
> gstreamer-cvs-verbose at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/gstreamer-cvs-verbose
Dave/Dina : future TV today ! - http://www.davedina.org/
<-*- thomas (dot) apestaart (dot) org -*->
What should I tell her
She's going to ask
If I ignore it it gets uncomfortable
She'll want to argue about the past
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.fm/
More information about the gstreamer-devel
mailing list