From 5afb6e6809ad1d8eb73e2e347d32a9239c3f845d Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Fri, 23 Sep 2005 14:31:21 +0000 Subject: [PATCH] inlined 3 more biiiig doc files and added some missing docs on the fly Original commit message from CVS: * 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 --- ChangeLog | 15 + common | 2 +- docs/gst/gstreamer-sections.txt | 2 +- docs/gst/tmpl/.gitignore | 3 + docs/gst/tmpl/gstelement.sgml | 1057 --------------------------------------- docs/gst/tmpl/gstinfo.sgml | 742 --------------------------- docs/gst/tmpl/gstobject.sgml | 464 ----------------- gst/gstelement.c | 47 +- gst/gstelement.h | 123 ++++- gst/gstinfo.c | 58 +++ gst/gstinfo.h | 294 ++++++++++- gst/gstobject.c | 95 +++- gst/gstobject.h | 98 +++- 13 files changed, 709 insertions(+), 2291 deletions(-) delete mode 100644 docs/gst/tmpl/gstelement.sgml delete mode 100644 docs/gst/tmpl/gstinfo.sgml delete mode 100644 docs/gst/tmpl/gstobject.sgml diff --git a/ChangeLog b/ChangeLog index d98a90b..feda752 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2005-09-23 Stefan Kost + + * 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 * check/gst/.cvsignore: diff --git a/common b/common index cd4da6a..345fd98 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit cd4da6a319d9f92d28f7b8a3b412577e6de50b64 +Subproject commit 345fd9851051274dd758a19bbe33dbb561b4d303 diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index e28a3d3..cdfbca3 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -437,10 +437,10 @@ GST_STATE_UNLOCK 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 diff --git a/docs/gst/tmpl/.gitignore b/docs/gst/tmpl/.gitignore index 158e81e..acf2fa0 100644 --- a/docs/gst/tmpl/.gitignore +++ b/docs/gst/tmpl/.gitignore @@ -15,6 +15,7 @@ gstchildproxy.sgml gstcollectpads.sgml gstcompat.sgml gstconfig.sgml +gstelement.sgml gstelementdetails.sgml gstelementfactory.sgml gstenumtypes.sgml @@ -30,11 +31,13 @@ gstghostpad.sgml 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 diff --git a/docs/gst/tmpl/gstelement.sgml b/docs/gst/tmpl/gstelement.sgml deleted file mode 100644 index faff527..0000000 --- a/docs/gst/tmpl/gstelement.sgml +++ /dev/null @@ -1,1057 +0,0 @@ - -GstElement - - -Abstract base class for all pipeline elements - - - -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(). - - - - -#GstElementFactory, #GstPad - - - - - - - - - - - - -@state_lock: -@state_cond: -@current_state: -@pending_state: -@final_state: -@state_error: -@no_preroll: -@bus: -@clock: -@base_time: -@numpads: -@pads: -@numsrcpads: -@srcpads: -@numsinkpads: -@sinkpads: -@pads_cookie: - - - - - - -@gstelement: the object which received the signal. - - - - - - -@gstelement: the object which received the signal. -@arg1: - - - - - - -@gstelement: the object which received the signal. -@arg1: - - - - - - -@gstelement: the object which received the signal. -@arg1: -@arg2: - - - - - - -@parent_class: -@details: -@elementfactory: -@padtemplates: -@numpadtemplates: -@pad_templ_cookie: -@request_new_pad: -@release_pad: -@get_state: -@change_state: -@set_bus: -@get_clock: -@set_clock: -@get_index: -@set_index: -@send_event: -@get_query_types: -@query: - - - -This enum defines the standard flags that an element may have. - - -@GST_ELEMENT_LOCKED_STATE: -@GST_ELEMENT_IS_SINK: -@GST_ELEMENT_UNPARENTING: -@GST_ELEMENT_FLAG_LAST: - - - - - - -@GST_STATE_VOID_PENDING: -@GST_STATE_NULL: -@GST_STATE_READY: -@GST_STATE_PAUSED: -@GST_STATE_PLAYING: - - - - - - -@GST_STATE_CHANGE_NULL_TO_READY: -@GST_STATE_CHANGE_READY_TO_PAUSED: -@GST_STATE_CHANGE_PAUSED_TO_PLAYING: -@GST_STATE_CHANGE_PLAYING_TO_PAUSED: -@GST_STATE_CHANGE_PAUSED_TO_READY: -@GST_STATE_CHANGE_READY_TO_NULL: - - - - - - -@GST_STATE_CHANGE_FAILURE: -@GST_STATE_CHANGE_SUCCESS: -@GST_STATE_CHANGE_ASYNC: -@GST_STATE_CHANGE_NO_PREROLL: - - - -This macro returns the current state of the element. - - -@obj: Element to return state for. - - - - -This macro returns the currently pending state of the element. - - -@obj: Element to return the pending state for. - - - - - - - -@obj: - - - - - - - -@elem: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@elem: - - - - - - - -@elem: - - - - - - - -@elem: - - - - - - - -@obj: - - - - - - - -@elem: - - - - - - - -@elem: -@timeval: - - - - - - - -@elem: - - - - - - - -@elem: - - - - - - - -@elem: - - - - -Gets the name of this element. Used in the core. Not ABI-compatible. - - -@obj: A #GstElement to query - - - - -Get the parent object of this element. - - -@obj: a #GstElement to query - - - - -Get the clock of this element - - -@obj: a #GstElement to query - - - - -Get the pads of this elements. - - -@obj: a #GstElement to query - - - - - - - -@el: -@domain: -@code: -@text: -@debug: - -@message: - - - - - - - -@obj: - - - - - - - -@el: -@domain: -@code: -@text: -@debug: - - - - - - - -@obj: - - - - - - - -@element: -@Returns: - - - - - - - -@element: - - - - - - - -@element: -@pad: -@Returns: - - - - - - - -@klass: -@templ: - - - - - - - -@element_class: -@name: -@Returns: - - - - - - - -@element_class: -@Returns: - - - - - - - -@klass: -@first_name: -@Varargs: - - - - - - - -@klass: -@details: - - - - - - - -@element: - - - - - - - -@element: - - - - - - - -@factory: -@caps: -@Returns: - - - - - - - -@factory: -@caps: -@Returns: - - - - - - - -@factory: -@Returns: - - - - - - - -@element: -@pad: -@Returns: - - - - - - - -@element: -@list: - - - - - - - -@element: -@pad: -@list: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@pad: -@caps: -@Returns: - - - - - - - -@element: -@compattempl: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - -Gets the name of the element. - - -@elem: -@Returns: the name of the element. - - - - - - - - - - -@element: -@name: -@Returns: GList of #GstPads - - - - -Gets the parent of an element. - - -@elem: a #GstElement to get the parent of. -@Returns: the #GstObject parent of the element. - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@name: -@Returns: - - - - - - - -@element: -@state: -@pending: -@timeout: -@Returns: - - - - - - - -@element: -@name: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@src: -@dest: -@Returns: - - - - - - - -@element_1: -@element_2: -@Varargs: -@Returns: - - - - - - - -@src: -@dest: -@filter: -@Returns: - - - - - - - -@src: -@srcpadname: -@dest: -@destpadname: -@Returns: - - - - - - - -@src: -@srcpadname: -@dest: -@destpadname: -@filter: -@Returns: - - - - - - - -@element: - - - - - - - -@element: -@type: -@domain: -@code: -@text: -@debug: -@file: -@function: -@line: - - - - - - - -@element: - - - - - - - -@element: -@message: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@query: -@Returns: - -@type: -@format: -@value: - - - - - - - -@element: -@src_format: -@src_val: -@dest_fmt: -@dest_val: -@Returns: - - - - - - - -@element: -@format: -@cur: -@end: -@Returns: - - - - - - - -@element: -@pad: - - - - - - - -@element: -@pad: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@element: -@rate: -@format: -@flags: -@cur_type: -@cur: -@stop_type: -@stop: -@Returns: - -@seek_type: -@offset: - - - - - - - -@element: -@event: -@Returns: - - - - - - - -@element: -@time: - - - - - - - -@element: -@bus: - - - - - - - -@element: -@clock: - - - - - - - -@element: -@index: - - - - - - - -@element: -@locked_state: -@Returns: - - - - -Sets the name of the element, getting rid of the old name if there was one. - - -@elem: a #GstElement to set the name of. -@name: the new name of the element. - - - - -Sets the parent of an element. - - -@elem: a #GstElement to set the parent of. -@parent: the new #GstObject parent of the object. - - - - - - - -@element: -@state: -@Returns: - - - - - - - -@element: -@state: -@Returns: - - - - - - - -@state: -@Returns: - - - - - - - -@element: -@Returns: - - - - - - - -@src: -@dest: - - - - - - - -@element_1: -@element_2: -@Varargs: - - - - - - - -@src: -@srcpadname: -@dest: -@destpadname: - - - - - diff --git a/docs/gst/tmpl/gstinfo.sgml b/docs/gst/tmpl/gstinfo.sgml deleted file mode 100644 index a8b3a38..0000000 --- a/docs/gst/tmpl/gstinfo.sgml +++ /dev/null @@ -1,742 +0,0 @@ - -GstInfo - - -Debugging and logging - - - -This file describes the debugging subsystem. The debugging subsystem works -only after GStreamer was initilized - for example by calling #gst_init. - - - -The debugging subsystem is used to send informational strings to the debugging -developer. Each messages has some properties attached to it. 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. - - -GST_DEBUG_CATEGORY (my_category); /* define category */ -&hash;define GST_CAT_DEFAULT my_category /* set as default */ - - -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(). - - - - -configuration, -initialization for command line parameters -and environment variables that affect the debugging output. - - - - - - - -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. - - -@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. - - - -Defines the default debugging level to be used with GStreamer. It is -normally set to #GST_LEVEL_ERROR so only errors are printed. 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. - - - - - - -These are some terminal-oriented flags you can use when creating your debugging -categories to make them stand out in debugging output. - - -@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. - - - -This is the struct that describes the categories. Once initialized with -#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore. - - - - - -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. - - -@str: The string to check. -@Returns: A string that is guaranteed to be not NULL. - - - - -Evaluates to 2 strings, that describe the pad. Often used in debugging -statements. - - -@pad: The pad to debug. - - - - -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. - - - - - - - - - - - - - - - - - - - - - - -@category: -@level: -@file: -@function: -@line: -@object: -@message: -@data: - - - - - - - -@category: -@level: -@file: -@function: -@line: -@object: -@format: -@Varargs: - - - - - - - -@category: -@level: -@file: -@function: -@line: -@object: -@format: -@args: - - - - - - - -@message: -@Returns: - - - - - - - -@category: -@level: -@file: -@function: -@line: -@object: -@message: -@unused: - - - - - - - -@level: -@Returns: - - - - - - - -@func: -@data: - - - - - - - -@func: -@Returns: - - - - - - - -@data: -@Returns: - - - - - - - -@active: - - - - - - - -@Returns: - - - - - - - -@colored: - - - - - - - -@Returns: - - - - - - - -@level: - - - - - - - -@Returns: - - - - - - - -@name: -@level: - - - - - - - -@name: - - - - - - - -@cat: - - - - - - - -@cat: - - - - - - - -@cat: - - - - - - - -@cat: -@name: -@color: -@description: - - - - - - - -@category: - - - - - - - -@category: -@level: - - - - - - - -@category: - - - - - - - -@category: -@Returns: - - - - - - - -@category: -@Returns: - - - - - - - -@category: -@Returns: - - - - - - - -@category: -@Returns: - - - - - - - -@Returns: - - - - - - - -@colorinfo: -@Returns: - - - - - - - - - - - -GST_CAT_LEVEL_LOG: -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. - - -@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 - - - - -Output an error message belonging to the given object in the given category. - - -@cat: category to use -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output a warning message belonging to the given object in the given category. - - -@cat: category to use -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an informational message belonging to the given object in the given -category. - - -@cat: category to use -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an debugging message belonging to the given object in the given category. - - -@cat: category to use -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an logging message belonging to the given object in the given category. - - -@cat: category to use -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an error message in the given category. - - -@cat: category to use -@...: printf-style message to output - - - - -Output a warning message in the given category. - - -@cat: category to use -@...: printf-style message to output - - - - -Output an informational message in the given category. - - -@cat: category to use -@...: printf-style message to output - - - - -Output a debuggign message in the given category. - - -@cat: category to use -@...: printf-style message to output - - - - -Output a logging message in the given category. - - -@cat: category to use -@...: printf-style message to output - - - - -Output an error message belonging to the given object in the default category. - - -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output a warning message belonging to the given object in the default category. - - -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an informational message belonging to the given object in the default -category. - - -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output a debugging message belonging to the given object in the default -category. - - -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output a logging message belonging to the given object in the default category. - - -@obj: the #GObject the message belongs to -@...: printf-style message to output - - - - -Output an error message in the default category. - - -@...: printf-style message to output - - - - -Output a warning message in the default category. - - -@...: printf-style message to output - - - - -Output an informational message in the default category. - - -@...: printf-style message to output - - - - -Output a debugging message in the default category. - - -@...: printf-style message to output - - - - -Output a logging message in the default category. - - -@...: printf-style message to output - - - - -Register a pointer to a function with its name, so it can later be used by -GST_DEBUG_FUNCPTR_NAME(). - - -@ptr: The function to register -Returns: The ptr to the function. - - - - -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. - - - - -@ptr: pointer to the function -Returns: The name of the function - - - - - - - -@func: -@data: - - - - - - - -@void: - - - - - - - - - - - - - - - - - - - - - -@t: - - diff --git a/docs/gst/tmpl/gstobject.sgml b/docs/gst/tmpl/gstobject.sgml deleted file mode 100644 index 7baef0a..0000000 --- a/docs/gst/tmpl/gstobject.sgml +++ /dev/null @@ -1,464 +0,0 @@ - -GstObject - - -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 */ - gtk_bin_add (GTK_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(). - - - -gst_object_set_name() and gst_object_get_name() are used to set/get the name of the -object. - - - - - - - - - - - - - - - -@refcount: -@lock: -@name: -@name_prefix: -@parent: -@flags: - - - -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. - - -@gstobject: the object which received the signal. -@arg1: the object that originated the signal -@arg2: the property that changed - - - -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. - - -@gstobject: the object which received the signal. -@arg1: the xmlNodePtr of the parent node - - - -Is emitted when the parent of an object is set. - - -@gstobject: the object which received the signal. -@arg1: the new parent - - - -Is emitted when the parent of an object is unset. - - -@gstobject: the object which received the signal. -@arg1: the old parent - - - -The name of the object - - - - -Flags for an object - - -@GST_OBJECT_DISPOSING: -@GST_OBJECT_FLOATING: -@GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag - - - -This macro returns the entire set of flags for the object. - - -@obj: Object to return flags for. - - - - -This macro checks to see if the given flag is set. - - -@obj: GstSrc to check for flag in. -@flag: Flag to check for, must be a single bit in guint32. - - - - -This macro sets the given bits. - - -@obj: Object to set flag in. -@flag: Flag to set, can by any number of bits in guint32. - - - - -This macro usets the given bits. - - -@obj: Object to unset flag in. -@flag: Flag to set, must be a single bit in guint32. - - - - -Get the name of this object - - -@obj: Object to get the name of. - - - - -Get the parent of this object - - -@obj: Object to get the parent of. - - - - -This macro will obtain a lock on the object, making serialization -possible. - - -@obj: Object to lock. - - - - -This macro will try to obtain a lock on the object, but will return with -FALSE if it can't get it immediately. - - -@obj: Object to try to get a lock on. - - - - -This macro releases a lock on the object. - - -@obj: Object to unlock. - - - - -Acquire a reference to the mutex of this object. - - -@obj: Object to get the mutex of. - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@obj: - - - - - - - -@object: -@name: -@Returns: - - - - - - - -@object: -@Returns: - - - - - - - -@object: -@parent: -@Returns: - - - - - - - -@object: -@Returns: - - - - - - - -@object: - - - - - - - -@object: -@Returns: - - - - - - - -@object: -@name_prefix: - - - - - - - -@object: -@orig: -@pspec: -@excluded_props: - - - - - - - -@source: -@error: -@debug: - - - - - - - -@list: -@name: -@Returns: - - - - - - - -@object: -@parent: -@Returns: - - - - - - - -@object: -@self: - - - - - - - -@object: the object -@Returns: - - - - - - - -@object: the object - -@Returns: - - - - - - - -@object: the object - - - - - - - -@oldobj: -@newobj: - - - - - - - -@object: -@Returns: - - - - - - - -@klass: -@name: -@func: -@func_data: -@Returns: - - - - - - - -@object: -@name: -@self: - - diff --git a/gst/gstelement.c b/gst/gstelement.c index 1e88023..0f64186 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -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 #include diff --git a/gst/gstelement.h b/gst/gstelement.h index b0b3871..f9ca261 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -82,7 +82,21 @@ typedef enum { /* 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 @@ typedef enum /*< flags=0 >*/ GST_STATE_CHANGE_READY_TO_NULL = 1<<(GST_STATE_READY+8) | 1<bus) + +/** + * GST_ELEMENT_CLOCK: + * @obj: A #GstElement to query + * + * Get the clock of this element + */ #define GST_ELEMENT_CLOCK(obj) (GST_ELEMENT_CAST(obj)->clock) + +/** + * GST_ELEMENT_PADS: + * @obj: A #GstElement to query + * + * Get the pads of this elements. + */ #define GST_ELEMENT_PADS(obj) (GST_ELEMENT_CAST(obj)->pads) /** @@ -176,7 +234,20 @@ G_STMT_START { \ __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 @@ void gst_element_class_set_details (GstElementClass *klass, 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: + * @elem: a #GstElement to set the name of. + * + * 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 */ diff --git a/gst/gstinfo.c b/gst/gstinfo.c index e777a29..70ffb70 100644 --- a/gst/gstinfo.c +++ b/gst/gstinfo.c @@ -20,6 +20,64 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * 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. + * + * + * GST_DEBUG_CATEGORY (my_category); // define category + * &hash;define GST_CAT_DEFAULT my_category // set as default + * + * + * 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 "gst_private.h" #include "gstinfo.h" diff --git a/gst/gstinfo.h b/gst/gstinfo.h index d9c15ca..1b31d8c 100644 --- a/gst/gstinfo.h +++ b/gst/gstinfo.h @@ -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 @@ typedef enum { 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 @@ typedef enum { * 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. + */ typedef enum { /* colors */ GST_DEBUG_FG_BLACK = 0x0000, @@ -93,6 +147,12 @@ typedef enum { #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 @@ struct _GstDebugCategory { /********** 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 @@ GSList * 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 @@ GST_CAT_LEVEL_LOG (GstDebugCategory * cat, GstDebugLevel level, #endif #endif /* G_HAVE_ISO_VARARGS */ +/** + * GST_CAT_ERROR_OBJECT: + * @cat: category to use + * @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: + * @cat: category to use + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output a warning message belonging to the given object in the given category. + */ +/** + * GST_CAT_INFO_OBJECT: + * @cat: category to use + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output an informational message belonging to the given object in the given + * category. + */ +/** + * GST_CAT_DEBUG_OBJECT: + * @cat: category to use + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output an debugging message belonging to the given object in the given category. + */ +/** + * GST_CAT_LOG_OBJECT: + * @cat: category to use + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output an logging message belonging to the given object in the given category. + */ + + +/** + * GST_CAT_ERROR: + * @cat: category to use + * @...: printf-style message to output + * + * Output an error message in the given category. + */ +/** + * GST_CAT_WARNING: + * @cat: category to use + * @...: printf-style message to output + * + * Output an warning message in the given category. + */ +/** + * GST_CAT_INFO: + * @cat: category to use + * @...: printf-style message to output + * + * Output an informational message in the given category. + */ +/** + * GST_CAT_DEBUG: + * @cat: category to use + * @...: printf-style message to output + * + * Output an debugging message in the given category. + */ +/** + * GST_CAT_LOG: + * @cat: category to use + * @...: printf-style message to output + * + * Output an logging message in the given category. + */ + + +/** + * GST_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 default category. + */ +/** + * GST_WARNING_OBJECT: + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output a warning message belonging to the given object in the default category. + */ +/** + * GST_INFO_OBJECT: + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output an informational message belonging to the given object in the default + * category. + */ +/** + * GST_DEBUG_OBJECT: + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output a debugging message belonging to the given object in the default + * category. + */ +/** + * GST_LOG_OBJECT: + * @obj: the #GObject the message belongs to + * @...: printf-style message to output + * + * Output a logging message belonging to the given object in the default category. + */ + + +/** + * GST_ERROR: + * @...: printf-style message to output + * + * Output an error message in the default category. + */ +/** + * GST_WARNING: + * @...: printf-style message to output + * + * Output a warning message in the default category. + */ +/** + * GST_INFO: + * @...: printf-style message to output + * + * Output an informational message in the default category. + */ +/** + * GST_DEBUG: + * @...: printf-style message to output + * + * Output a debugging message in the default category. + */ +/** + * GST_LOG: + * @...: printf-style message to output + * + * Output a logging message in the default category. + */ + #ifdef G_HAVE_ISO_VARARGS #define GST_CAT_ERROR_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_ERROR, obj, __VA_ARGS__) @@ -592,14 +840,36 @@ GST_LOG (const char *format, ...) /********** 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) diff --git a/gst/gstobject.c b/gst/gstobject.c index 79cc899..11f5086 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -20,6 +20,60 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * 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. + */ #include "gst_private.h" @@ -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 @@ gst_object_class_init (GstObjectClass * klass) 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: + * @gstobject: the object which received the signal. + * @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: + * @gstobject: the object which received the signal. + * @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 @@ gst_object_class_init (GstObjectClass * klass) klass->restore_thyself = gst_object_real_restore_thyself; #endif + + /** + * GstObject::deep-notify: + * @gstobject: the object which received the signal. + * @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 | diff --git a/gst/gstobject.h b/gst/gstobject.h index 31e2645..28ffaff 100644 --- a/gst/gstobject.h +++ b/gst/gstobject.h @@ -41,12 +41,20 @@ GST_EXPORT GType _gst_object_type; #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 #endif +/** + * 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 + * + */ typedef enum { GST_OBJECT_DISPOSING = 0, @@ -65,26 +73,112 @@ typedef enum /* 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) +/** + * GST_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) +/** + * GST_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; -- 2.7.4