mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-26 19:51:11 +00:00
Code Issues 1 Projects Releases Wiki Activity

inlined 3 more biiiig doc files and added some missing docs on the fly

Browse source 
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
This commit is contained in:
Stefan Kost 2005-09-23 14:31:21 +00:00
parent 6570aadc78
commit 5afb6e6809
13 changed files with 709 additions and 2291 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
ChangeLog
View file

@ -1,3 +1,18 @@
2005-09-23 Stefan Kost <ensonic@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:

2
common

@ -1 +1 @@
Subproject commit cd4da6a319d9f92d28f7b8a3b412577e6de50b64
Subproject commit 345fd9851051274dd758a19bbe33dbb561b4d303

2
docs/gst/gstreamer-sections.txt
View file

@ -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

3
docs/gst/tmpl/.gitignore vendored
View file

@ -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

1057
docs/gst/tmpl/gstelement.sgml
View file

File diff suppressed because it is too large Load diff

742
docs/gst/tmpl/gstinfo.sgml
View file

@ -1,742 +0,0 @@
<!-- ##### SECTION Title ##### -->
GstInfo
<!-- ##### SECTION Short_Description ##### -->
Debugging and logging
<!-- ##### SECTION Long_Description ##### -->
<para>
This file describes the debugging subsystem. The debugging subsystem works
only after GStreamer was initilized - for example by calling #gst_init.
</para>
<para>
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.
</para>
<para>
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.
<informalexample>
<programlisting>
GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
</programlisting>
</informalexample>
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.
</para>
<para>
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 &lt;gst/gst.h&gt;,
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.
</para>
<para>
Please note that there are naming conventions for the names of debugging
categories. These are explained at GST_DEBUG_CATEGORY_INIT().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<link linkend="gstreamer-gstconfig">configuration</link>,
<link linkend="gstreamer-gst">initialization</link> for command line parameters
and environment variables that affect the debugging output.
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### ENUM GstDebugLevel ##### -->
<para>
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.
</para>
@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.
<!-- ##### MACRO GST_LEVEL_DEFAULT ##### -->
<para>
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.
</para>
<!-- ##### ENUM GstDebugColorFlags ##### -->
<para>
These are some terminal-oriented flags you can use when creating your debugging
categories to make them stand out in debugging output.
</para>
@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.
<!-- ##### STRUCT GstDebugCategory ##### -->
<para>
This is the struct that describes the categories. Once initialized with
#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
</para>
<!-- ##### MACRO GST_STR_NULL ##### -->
<para>
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.
</para>
@str: The string to check.
@Returns: A string that is guaranteed to be not NULL.
<!-- ##### MACRO GST_DEBUG_PAD_NAME ##### -->
<para>
Evaluates to 2 strings, that describe the pad. Often used in debugging
statements.
</para>
@pad: The pad to debug.
<!-- ##### MACRO GST_FUNCTION ##### -->
<para>
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.
</para>
<!-- ##### STRUCT GstDebugMessage ##### -->
<para>
</para>
<!-- ##### USER_FUNCTION GstDebugFuncPtr ##### -->
<para>
</para>
<!-- ##### USER_FUNCTION GstLogFunction ##### -->
<para>
</para>
@category:
@level:
@file:
@function:
@line:
@object:
@message:
@data:
<!-- ##### FUNCTION gst_debug_log ##### -->
<para>
</para>
@category:
@level:
@file:
@function:
@line:
@object:
@format:
@Varargs:
<!-- ##### FUNCTION gst_debug_log_valist ##### -->
<para>
</para>
@category:
@level:
@file:
@function:
@line:
@object:
@format:
@args:
<!-- ##### FUNCTION gst_debug_message_get ##### -->
<para>
</para>
@message:
@Returns:
<!-- ##### FUNCTION gst_debug_log_default ##### -->
<para>
</para>
@category:
@level:
@file:
@function:
@line:
@object:
@message:
@unused:
<!-- ##### FUNCTION gst_debug_level_get_name ##### -->
<para>
</para>
@level:
@Returns:
<!-- ##### FUNCTION gst_debug_add_log_function ##### -->
<para>
</para>
@func:
@data:
<!-- ##### FUNCTION gst_debug_remove_log_function ##### -->
<para>
</para>
@func:
@Returns:
<!-- ##### FUNCTION gst_debug_remove_log_function_by_data ##### -->
<para>
</para>
@data:
@Returns:
<!-- ##### FUNCTION gst_debug_set_active ##### -->
<para>
</para>
@active:
<!-- ##### FUNCTION gst_debug_is_active ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_debug_set_colored ##### -->
<para>
</para>
@colored:
<!-- ##### FUNCTION gst_debug_is_colored ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_debug_set_default_threshold ##### -->
<para>
</para>
@level:
<!-- ##### FUNCTION gst_debug_get_default_threshold ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_debug_set_threshold_for_name ##### -->
<para>
</para>
@name:
@level:
<!-- ##### FUNCTION gst_debug_unset_threshold_for_name ##### -->
<para>
</para>
@name:
<!-- ##### MACRO GST_DEBUG_CATEGORY ##### -->
<para>
</para>
@cat:
<!-- ##### MACRO GST_DEBUG_CATEGORY_EXTERN ##### -->
<para>
</para>
@cat:
<!-- ##### MACRO GST_DEBUG_CATEGORY_STATIC ##### -->
<para>
</para>
@cat:
<!-- ##### MACRO GST_DEBUG_CATEGORY_INIT ##### -->
<para>
</para>
@cat:
@name:
@color:
@description:
<!-- ##### FUNCTION gst_debug_category_free ##### -->
<para>
</para>
@category:
<!-- ##### FUNCTION gst_debug_category_set_threshold ##### -->
<para>
</para>
@category:
@level:
<!-- ##### FUNCTION gst_debug_category_reset_threshold ##### -->
<para>
</para>
@category:
<!-- ##### FUNCTION gst_debug_category_get_threshold ##### -->
<para>
</para>
@category:
@Returns:
<!-- ##### FUNCTION gst_debug_category_get_name ##### -->
<para>
</para>
@category:
@Returns:
<!-- ##### FUNCTION gst_debug_category_get_color ##### -->
<para>
</para>
@category:
@Returns:
<!-- ##### FUNCTION gst_debug_category_get_description ##### -->
<para>
</para>
@category:
@Returns:
<!-- ##### FUNCTION gst_debug_get_all_categories ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_debug_construct_term_color ##### -->
<para>
</para>
@colorinfo:
@Returns:
<!-- ##### MACRO GST_CAT_DEFAULT ##### -->
<para>
</para>
<!-- ##### MACRO GST_CAT_LEVEL_LOG ##### -->
<para>
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.
</para>
@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
<!-- ##### MACRO GST_CAT_ERROR_OBJECT ##### -->
<para>
Output an error message belonging to the given object in the given category.
</para>
@cat: category to use
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_WARNING_OBJECT ##### -->
<para>
Output a warning message belonging to the given object in the given category.
</para>
@cat: category to use
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_INFO_OBJECT ##### -->
<para>
Output an informational message belonging to the given object in the given
category.
</para>
@cat: category to use
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_DEBUG_OBJECT ##### -->
<para>
Output an debugging message belonging to the given object in the given category.
</para>
@cat: category to use
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_LOG_OBJECT ##### -->
<para>
Output an logging message belonging to the given object in the given category.
</para>
@cat: category to use
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_ERROR ##### -->
<para>
Output an error message in the given category.
</para>
@cat: category to use
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_WARNING ##### -->
<para>
Output a warning message in the given category.
</para>
@cat: category to use
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_INFO ##### -->
<para>
Output an informational message in the given category.
</para>
@cat: category to use
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_DEBUG ##### -->
<para>
Output a debuggign message in the given category.
</para>
@cat: category to use
@...: printf-style message to output
<!-- ##### MACRO GST_CAT_LOG ##### -->
<para>
Output a logging message in the given category.
</para>
@cat: category to use
@...: printf-style message to output
<!-- ##### MACRO GST_ERROR_OBJECT ##### -->
<para>
Output an error message belonging to the given object in the default category.
</para>
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_WARNING_OBJECT ##### -->
<para>
Output a warning message belonging to the given object in the default category.
</para>
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_INFO_OBJECT ##### -->
<para>
Output an informational message belonging to the given object in the default
category.
</para>
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_DEBUG_OBJECT ##### -->
<para>
Output a debugging message belonging to the given object in the default
category.
</para>
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_LOG_OBJECT ##### -->
<para>
Output a logging message belonging to the given object in the default category.
</para>
@obj: the #GObject the message belongs to
@...: printf-style message to output
<!-- ##### MACRO GST_ERROR ##### -->
<para>
Output an error message in the default category.
</para>
@...: printf-style message to output
<!-- ##### MACRO GST_WARNING ##### -->
<para>
Output a warning message in the default category.
</para>
@...: printf-style message to output
<!-- ##### MACRO GST_INFO ##### -->
<para>
Output an informational message in the default category.
</para>
@...: printf-style message to output
<!-- ##### MACRO GST_DEBUG ##### -->
<para>
Output a debugging message in the default category.
</para>
@...: printf-style message to output
<!-- ##### MACRO GST_LOG ##### -->
<para>
Output a logging message in the default category.
</para>
@...: printf-style message to output
<!-- ##### MACRO GST_DEBUG_FUNCPTR ##### -->
<para>
Register a pointer to a function with its name, so it can later be used by
GST_DEBUG_FUNCPTR_NAME().
</para>
@ptr: The function to register
Returns: The ptr to the function.
<!-- ##### MACRO GST_DEBUG_FUNCPTR_NAME ##### -->
<para>
Retrieves the name of the function, if it was previously registered with
GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer.
<note>
<para>
Make sure you free the string after use.
</para>
</note>
</para>
@ptr: pointer to the function
Returns: The name of the function
<!-- ##### MACRO gst_debug_set_log_function ##### -->
<para>
</para>
@func:
@data:
<!-- ##### MACRO gst_debug_reset_log_function ##### -->
<para>
</para>
@void:
<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
<para>
</para>
<!-- ##### MACRO GST_TIME_FORMAT ##### -->
<para>
</para>
<!-- ##### MACRO GST_TIME_ARGS ##### -->
<para>
</para>
@t:

464
docs/gst/tmpl/gstobject.sgml
View file

@ -1,464 +0,0 @@
<!-- ##### SECTION Title ##### -->
GstObject
<!-- ##### SECTION Short_Description ##### -->
Base class for the GStreamer object hierarchy
<!-- ##### SECTION Long_Description ##### -->
<para>
GstObject provides a root for the object hierarchy tree filed in by the
GST library. It is currently a thin wrapper on top of
<classname>GObject</classname>. It is an abstract class that is not
very usable on its own.
</para>
<para>
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).
</para>
<para>
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).
</para>
<para>
When you add a GstElement to its parent container, the parent container will do
this:
<programlisting>
gst_object_ref (GST_OBJECT (child_element));
gst_object_sink (GST_OBJECT (child_element));
</programlisting>
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.
</para>
<para>
The purpose of the floating reference is to keep the child element alive until
you add it to a parent container:
<programlisting>
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 */
</programlisting>
</para>
<para>
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().
</para>
<para>
gst_object_set_name() and gst_object_get_name() are used to set/get the name of the
object.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GstObject ##### -->
<para>
</para>
@refcount:
@lock:
@name:
@name_prefix:
@parent:
@flags:
<!-- ##### SIGNAL GstObject::deep-notify ##### -->
<para>
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.
</para>
@gstobject: the object which received the signal.
@arg1: the object that originated the signal
@arg2: the property that changed
<!-- ##### SIGNAL GstObject::object-saved ##### -->
<para>
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.
</para>
@gstobject: the object which received the signal.
@arg1: the xmlNodePtr of the parent node
<!-- ##### SIGNAL GstObject::parent-set ##### -->
<para>
Is emitted when the parent of an object is set.
</para>
@gstobject: the object which received the signal.
@arg1: the new parent
<!-- ##### SIGNAL GstObject::parent-unset ##### -->
<para>
Is emitted when the parent of an object is unset.
</para>
@gstobject: the object which received the signal.
@arg1: the old parent
<!-- ##### ARG GstObject:name ##### -->
<para>
The name of the object
</para>
<!-- ##### ENUM GstObjectFlags ##### -->
<para>
Flags for an object
</para>
@GST_OBJECT_DISPOSING:
@GST_OBJECT_FLOATING:
@GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
<!-- ##### MACRO GST_FLAGS ##### -->
<para>
This macro returns the entire set of flags for the object.
</para>
@obj: Object to return flags for.
<!-- ##### MACRO GST_FLAG_IS_SET ##### -->
<para>
This macro checks to see if the given flag is set.
</para>
@obj: GstSrc to check for flag in.
@flag: Flag to check for, must be a single bit in guint32.
<!-- ##### MACRO GST_FLAG_SET ##### -->
<para>
This macro sets the given bits.
</para>
@obj: Object to set flag in.
@flag: Flag to set, can by any number of bits in guint32.
<!-- ##### MACRO GST_FLAG_UNSET ##### -->
<para>
This macro usets the given bits.
</para>
@obj: Object to unset flag in.
@flag: Flag to set, must be a single bit in guint32.
<!-- ##### MACRO GST_OBJECT_NAME ##### -->
<para>
Get the name of this object
</para>
@obj: Object to get the name of.
<!-- ##### MACRO GST_OBJECT_PARENT ##### -->
<para>
Get the parent of this object
</para>
@obj: Object to get the parent of.
<!-- ##### MACRO GST_LOCK ##### -->
<para>
This macro will obtain a lock on the object, making serialization
possible.
</para>
@obj: Object to lock.
<!-- ##### MACRO GST_TRYLOCK ##### -->
<para>
This macro will try to obtain a lock on the object, but will return with
FALSE if it can't get it immediately.
</para>
@obj: Object to try to get a lock on.
<!-- ##### MACRO GST_UNLOCK ##### -->
<para>
This macro releases a lock on the object.
</para>
@obj: Object to unlock.
<!-- ##### MACRO GST_GET_LOCK ##### -->
<para>
Acquire a reference to the mutex of this object.
</para>
@obj: Object to get the mutex of.
<!-- ##### MACRO GST_OBJECT_IS_DISPOSING ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_OBJECT_IS_FLOATING ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_OBJECT_REFCOUNT ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_OBJECT_REFCOUNT_VALUE ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_CLASS_GET_LOCK ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_CLASS_LOCK ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_CLASS_TRYLOCK ##### -->
<para>
</para>
@obj:
<!-- ##### MACRO GST_CLASS_UNLOCK ##### -->
<para>
</para>
@obj:
<!-- ##### FUNCTION gst_object_set_name ##### -->
<para>
</para>
@object:
@name:
@Returns:
<!-- ##### FUNCTION gst_object_get_name ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gst_object_set_parent ##### -->
<para>
</para>
@object:
@parent:
@Returns:
<!-- ##### FUNCTION gst_object_get_parent ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gst_object_unparent ##### -->
<para>
</para>
@object:
<!-- ##### FUNCTION gst_object_get_name_prefix ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gst_object_set_name_prefix ##### -->
<para>
</para>
@object:
@name_prefix:
<!-- ##### FUNCTION gst_object_default_deep_notify ##### -->
<para>
</para>
@object:
@orig:
@pspec:
@excluded_props:
<!-- ##### FUNCTION gst_object_default_error ##### -->
<para>
</para>
@source:
@error:
@debug:
<!-- ##### FUNCTION gst_object_check_uniqueness ##### -->
<para>
</para>
@list:
@name:
@Returns:
<!-- ##### FUNCTION gst_object_save_thyself ##### -->
<para>
</para>
@object:
@parent:
@Returns:
<!-- ##### FUNCTION gst_object_restore_thyself ##### -->
<para>
</para>
@object:
@self:
<!-- ##### FUNCTION gst_object_ref ##### -->
<para>
</para>
@object: the object
@Returns:
<!-- ##### FUNCTION gst_object_unref ##### -->
<para>
</para>
@object: the object
<!-- # Unused Parameters # -->
@Returns:
<!-- ##### FUNCTION gst_object_sink ##### -->
<para>
</para>
@object: the object
<!-- ##### FUNCTION gst_object_replace ##### -->
<para>
</para>
@oldobj:
@newobj:
<!-- ##### FUNCTION gst_object_get_path_string ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gst_class_signal_connect ##### -->
<para>
</para>
@klass:
@name:
@func:
@func_data:
@Returns:
<!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
<para>
</para>
@object:
@name:
@self:

47
gst/gstelement.c
View file

@ -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>

123
gst/gstelement.h
View file

@ -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<<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:
* @obj: A #GstElement to query
*
* 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:
* @obj: A #GstElement to query
*
* Get the parent object of this element.
*/
#define GST_ELEMENT_PARENT(obj) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj)))
/**
* GST_ELEMENT_BUS:
* @obj: A #GstElement to query
*
* Get the message bus of this element.
*/
#define GST_ELEMENT_BUS(obj) (GST_ELEMENT_CAST(obj)->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 */

58
gst/gstinfo.c
View file

@ -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.
* <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.
* <informalexample>
* <programlisting>
* GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
* </programlisting>
* </informalexample>
* 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 &lt;gst/gst.h&gt;,
* 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"

294
gst/gstinfo.h
View file

@ -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)

95
gst/gstobject.c
View file

@ -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:
* <informalexample>
* <programlisting>
* gst_object_ref (GST_OBJECT (child_element));
* gst_object_sink (GST_OBJECT (child_element));
* </programlisting>
* </informalexample>
* 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:
* <informalexample>
* <programlisting>
* 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
* </programlisting>
* </informalexample>
*
* 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 |

98
gst/gstobject.h
View file

@ -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;