2005-08-27 Stefan Kost <ensonic@users.sf.net>
+ * docs/design/part-messages.txt:
+ update info
+ * docs/gst/tmpl/.cvsignore:
+ * docs/gst/tmpl/gstcaps.sgml:
+ * docs/gst/tmpl/gstclock.sgml:
+ * gst/gstbus.c:
+ * gst/gstcaps.c:
+ * gst/gstcaps.h:
+ * gst/gstclock.c:
+ * gst/gstclock.h:
+ * gst/gstmessage.c:
+ added descriptions for bus and message
+ inline caps and clock docs
+
+2005-08-27 Stefan Kost <ensonic@users.sf.net>
+
* gst/gstmessage.c:
* gst/gstmessage.h:
doc fixes
Messages are refcounted lightweight objects to signal the application
of pipeline events.
-Messages are implemented as a subclass of GstData with a generic
+Messages are implemented as a subclass of GstMiniObject with a generic
GstStructure as the content. This allows for writing custom messages without
requiring an API change while allowing a wide range of different types
of messages.
gstbin.sgml
gstbuffer.sgml
gstbus.sgml
+gstcaps.sgml
gstcheck.sgml
+gstclock.sgml
gstcollectpads.sgml
gstevent.sgml
gstfakesrc.sgml
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GstCaps
-
-<!-- ##### SECTION Short_Description ##### -->
-Structure describing sets of media formats
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstCaps ##### -->
-<para>
-
-</para>
-
-@type:
-@refcount:
-@flags:
-@structs:
-
-<!-- ##### STRUCT GstStaticCaps ##### -->
-<para>
-
-</para>
-
-@caps:
-@string:
-
-<!-- ##### MACRO GST_CAPS_FLAGS_ANY ##### -->
-<para>
-Flags that this caps has no specific content, but can contain anything.
-</para>
-
-
-
-<!-- ##### MACRO GST_CAPS_ANY ##### -->
-<para>
-Means that the element/pad can output 'anything'. Useful for elements
-that output unknown media, such as filesrc.
-</para>
-
-
-
-<!-- ##### MACRO GST_CAPS_NONE ##### -->
-<para>
-The opposite of GST_CAPS_ANY: it means that the pad/element outputs an
-undefined media type that can not be detected.
-</para>
-
-
-
-<!-- ##### MACRO GST_CAPS_REFCOUNT ##### -->
-<para>
-
-</para>
-
-@caps:
-
-
-<!-- ##### MACRO GST_CAPS_REFCOUNT_VALUE ##### -->
-<para>
-
-</para>
-
-@caps:
-
-
-<!-- ##### MACRO GST_STATIC_CAPS_ANY ##### -->
-<para>
-Creates a static caps that matches anything. This can be used in pad
-templates.
-</para>
-
-@Returns: a new #GstCaps instance
-
-
-<!-- ##### MACRO GST_STATIC_CAPS_NONE ##### -->
-<para>
-Creates a static caps that matches nothing. This can be used in pad
-templates.
-</para>
-
-@Returns: a new #GstCaps instance
-
-
-<!-- ##### MACRO GST_CAPS_IS_SIMPLE ##### -->
-<para>
-Convinience macro that checks if the number of structures in the gives caps is
-exactly one.
-</para>
-
-@caps: the #GstCaps instance to check
-
-
-<!-- ##### MACRO GST_DEBUG_CAPS ##### -->
-<para>
-Convinience macro for prining out the contents of caps with GST_DEBUG().
-</para>
-
-@string: a string the should be prepend to the caps data.
-@caps: the caps to print
-
-
-<!-- ##### MACRO GST_STATIC_CAPS ##### -->
-<para>
-Creates a static caps from an input string. This can be used in pad
-templates.
-</para>
-
-@string: the string describing the caps.
-@Returns: a new #GstCaps instance
-
-
-<!-- ##### FUNCTION gst_caps_new_empty ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_new_any ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_new_simple ##### -->
-<para>
-
-</para>
-
-@media_type:
-@fieldname:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_new_full ##### -->
-<para>
-
-</para>
-
-@struct1:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_new_full_valist ##### -->
-<para>
-
-</para>
-
-@structure:
-@var_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_copy ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_copy_nth ##### -->
-<para>
-
-</para>
-
-@caps:
-@nth:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_static_caps_get ##### -->
-<para>
-
-</para>
-
-@static_caps:
-@Returns:
-<!-- # Unused Parameters # -->
-@caps:
-
-
-<!-- ##### FUNCTION gst_caps_append ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-
-
-<!-- ##### FUNCTION gst_caps_append_structure ##### -->
-<para>
-
-</para>
-
-@caps:
-@structure:
-<!-- # Unused Parameters # -->
-@caps1:
-
-
-<!-- ##### FUNCTION gst_caps_get_size ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_get_structure ##### -->
-<para>
-
-</para>
-
-@caps:
-@index:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_set_simple ##### -->
-<para>
-
-</para>
-
-@caps:
-@field:
-@Varargs:
-
-
-<!-- ##### FUNCTION gst_caps_set_simple_valist ##### -->
-<para>
-
-</para>
-
-@caps:
-@field:
-@varargs:
-
-
-<!-- ##### FUNCTION gst_caps_is_any ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_empty ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_fixed ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_equal ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_equal_fixed ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_always_compatible ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_is_subset ##### -->
-<para>
-
-</para>
-
-@subset:
-@superset:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_intersect ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_union ##### -->
-<para>
-
-</para>
-
-@caps1:
-@caps2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_normalize ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_do_simplify ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_save_thyself ##### -->
-<para>
-
-</para>
-
-@caps:
-@parent:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_load_thyself ##### -->
-<para>
-
-</para>
-
-@parent:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_replace ##### -->
-<para>
-
-</para>
-
-@caps:
-@newcaps:
-
-
-<!-- ##### FUNCTION gst_caps_to_string ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_from_string ##### -->
-<para>
-
-</para>
-
-@string:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_subtract ##### -->
-<para>
-
-</para>
-
-@minuend:
-@subtrahend:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_make_writable ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_ref ##### -->
-<para>
-
-</para>
-
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_structure_fixate_field_boolean ##### -->
-<para>
-
-</para>
-
-@structure:
-@field_name:
-@target:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_caps_truncate ##### -->
-<para>
-
-</para>
-
-@caps:
-
-
-<!-- ##### FUNCTION gst_caps_unref ##### -->
-<para>
-
-</para>
-
-@caps:
-
-
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GstClock
-
-<!-- ##### SECTION Short_Description ##### -->
-Abstract class for global clocks
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-GStreamer uses a global clock to synchronise the plugins in a pipeline.
-Different clock implementations are possible by implementing this abstract
-base class.
-</para>
-<para>
-The clock time is always measured in nanoseconds and always increases. The
-pipeline uses the clock to calculate the stream time.
-Usually all renderers sync to the global clock so that the clock is always
-a good measure of the current playback time in the pipeline.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GstSystemClock
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstClock ##### -->
-<para>
-
-</para>
-
-@flags:
-
-<!-- ##### ARG GstClock:stats ##### -->
-<para>
-Boolean property to activate stat generation on the clock.
-</para>
-
-<!-- ##### TYPEDEF GstClockTime ##### -->
-<para>
-A datatype to hold a time, measured in nanoseconds.
-</para>
-
-
-<!-- ##### TYPEDEF GstClockTimeDiff ##### -->
-<para>
-A datatype to hold a timedifference, measured in nanoseconds.
-</para>
-
-
-<!-- ##### TYPEDEF GstClockID ##### -->
-<para>
-A detatype to hold the handle to an outstanding async clock callback
-</para>
-
-
-<!-- ##### MACRO GST_CLOCK_TIME_NONE ##### -->
-<para>
-Constant to define an undefined clock time
-</para>
-
-
-
-<!-- ##### MACRO GST_CLOCK_TIME_IS_VALID ##### -->
-<para>
-
-</para>
-
-@time:
-
-
-<!-- ##### MACRO GST_SECOND ##### -->
-<para>
-Constant that defines one GStreamer second
-</para>
-
-
-
-<!-- ##### MACRO GST_MSECOND ##### -->
-<para>
-Constant that defines one GStreamer millisecond
-</para>
-
-
-
-<!-- ##### MACRO GST_USECOND ##### -->
-<para>
-Constant that defines one GStreamer microsecond
-</para>
-
-
-
-<!-- ##### MACRO GST_NSECOND ##### -->
-<para>
-Constant that defines one GStreamer nanosecond
-</para>
-
-
-
-<!-- ##### MACRO GST_CLOCK_DIFF ##### -->
-<para>
-Calculate a difference between to clock times.
-</para>
-
-@s: the first time
-@e: the second time
-
-
-<!-- ##### MACRO GST_TIMEVAL_TO_TIME ##### -->
-<para>
-Convert a GTimeVal to a GstClockTime
-</para>
-
-@tv: the timeval to convert
-
-
-<!-- ##### MACRO GST_TIME_TO_TIMEVAL ##### -->
-<para>
-Convert a GstClockTime to a GTimeVal
-</para>
-
-@t: The GstClockTime to convert
-@tv: The target timeval
-
-
-<!-- ##### MACRO GST_TIMESPEC_TO_TIME ##### -->
-<para>
-
-</para>
-
-@ts:
-
-
-<!-- ##### MACRO GST_TIME_TO_TIMESPEC ##### -->
-<para>
-
-</para>
-
-@t:
-@ts:
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_TRACE_NAME ##### -->
-<para>
-The name used for tracing clock entry allocations.
-</para>
-
-
-
-<!-- ##### STRUCT GstClockEntry ##### -->
-<para>
-All pending timeouts or periodic notifies are converted into
-an entry.
-</para>
-
-@refcount:
-
-<!-- ##### USER_FUNCTION GstClockCallback ##### -->
-<para>
-The function prototype of the callback.
-</para>
-
-@clock: The clock that triggered the callback
-@time: The time it was triggered
-@id: The id that expired
-@user_data: user data passed in the async_wait call
-@Returns: %TRUE or %FALSE (currently unused)
-
-
-<!-- ##### ENUM GstClockEntryType ##### -->
-<para>
-The type of the clock entry
-</para>
-
-@GST_CLOCK_ENTRY_SINGLE: a single shot timeout
-@GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
-
-<!-- ##### MACRO GST_CLOCK_ENTRY ##### -->
-<para>
-Cast to a clock entry
-</para>
-
-@entry: the entry to cast
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_CLOCK ##### -->
-<para>
-Get the owner clock of the entry
-</para>
-
-@entry: the entry to query
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_TYPE ##### -->
-<para>
-Get the type of the clock entry
-</para>
-
-@entry: the entry to query
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_TIME ##### -->
-<para>
-Get the requested time of this entry
-</para>
-
-@entry: the entry to query
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_INTERVAL ##### -->
-<para>
-Get the interval of this periodic entry
-</para>
-
-@entry: the entry to query
-
-
-<!-- ##### MACRO GST_CLOCK_ENTRY_STATUS ##### -->
-<para>
-The status of the entry
-</para>
-
-@entry: the entry to query
-
-
-<!-- ##### ENUM GstClockReturn ##### -->
-<para>
-The return value of a clock operation.
-</para>
-
-@GST_CLOCK_OK: The operation succeded.
-@GST_CLOCK_EARLY: The operation was scheduled too late.
-@GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
-@GST_CLOCK_BUSY: The ClockID is busy
-@GST_CLOCK_BADTIME: A bad time was provided to a function.
-@GST_CLOCK_ERROR: An error occured
-@GST_CLOCK_UNSUPPORTED: Operation is not supported
-
-<!-- ##### ENUM GstClockFlags ##### -->
-<para>
-The capabilities of this clock
-</para>
-
-@GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: This clock can do a single sync timeut request
-@GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: This clock can do a single async timeout request
-@GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: This clock can do sync periodic timeout requests
-@GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: This clock can do async periodic timeout callbacks
-@GST_CLOCK_FLAG_CAN_SET_RESOLUTION: The resolution of this clock can be changed
-
-<!-- ##### MACRO GST_CLOCK_FLAGS ##### -->
-<para>
-Get the clock flags
-</para>
-
-@clock: the clock to query
-
-
-<!-- ##### MACRO GST_CLOCK_BROADCAST ##### -->
-<para>
-
-</para>
-
-@clock:
-
-
-<!-- ##### MACRO GST_CLOCK_CAST ##### -->
-<para>
-
-</para>
-
-@clock:
-
-
-<!-- ##### MACRO GST_CLOCK_COND ##### -->
-<para>
-
-</para>
-
-@clock:
-
-
-<!-- ##### MACRO GST_CLOCK_TIMED_WAIT ##### -->
-<para>
-
-</para>
-
-@clock:
-@tv:
-
-
-<!-- ##### MACRO GST_CLOCK_WAIT ##### -->
-<para>
-
-</para>
-
-@clock:
-
-
-<!-- ##### FUNCTION gst_clock_set_resolution ##### -->
-<para>
-
-</para>
-
-@clock:
-@resolution:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_get_resolution ##### -->
-<para>
-
-</para>
-
-@clock:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_get_time ##### -->
-<para>
-
-</para>
-
-@clock:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_new_single_shot_id ##### -->
-<para>
-
-</para>
-
-@clock:
-@time:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_new_periodic_id ##### -->
-<para>
-
-</para>
-
-@clock:
-@start_time:
-@interval:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_adjust_unlocked ##### -->
-<para>
-
-</para>
-
-@clock:
-@internal:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_set_time_adjust ##### -->
-<para>
-
-</para>
-
-@clock:
-@adjust:
-
-
-<!-- ##### FUNCTION gst_clock_id_get_time ##### -->
-<para>
-
-</para>
-
-@id:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_id_wait ##### -->
-<para>
-
-</para>
-
-@id:
-@jitter:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_id_wait_async ##### -->
-<para>
-
-</para>
-
-@id:
-@func:
-@user_data:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_id_unschedule ##### -->
-<para>
-
-</para>
-
-@id:
-
-
-<!-- ##### FUNCTION gst_clock_id_compare_func ##### -->
-<para>
-
-</para>
-
-@id1:
-@id2:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_id_ref ##### -->
-<para>
-
-</para>
-
-@id:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_clock_id_unref ##### -->
-<para>
-
-</para>
-
-@id:
-
-
/**
* SECTION:gstbus
* @short_description: Asynchronous message bus subsystem
+ * @see_also: #GstMessage, #GstElement
+ *
+ * The #GstBus is an object responsible for delivering #GstMessages in
+ * a first-in first-out way from the streaming threads to the application.
+ *
+ * Since the application typically only wants to deal with delivery of these
+ * messages from one thread, the GstBus will marshall the messages between
+ * different threads. This is important since the actual streaming of media
+ * is done in another thread than the application.
+ *
+ * The GstBus provides support for #GSource based notifications. This makes it
+ * possible to handle the delivery in the glib mainloop.
+ *
+ * A message is posted on the bus with the gst_bus_post() method. With the
+ * gst_bus_peek() and _pop() methods one can look at or retrieve a previously
+ * posted message.
+ *
+ * The bus can be polled with the gst_bus_poll() method. This methods blocks
+ * up to the specified timeout value until one of the specified messages types
+ * is posted on the bus. The application can then _pop() the messages from the
+ * bus to handle them.
+ * Alternatively the application can register an asynchronous bus handler using
+ * gst_bus_add_watch_full() orgst_bus_add_watch(). This handler will receive
+ * messages a short while after they have been posted.
+ *
+ * It is also possible to get messages from the bus without any thread
+ * marshalling with the gst_bus_set_sync_handler() method. This makes it
+ * possible to react to a message in the same thread that posted the
+ * message on the bus. This should only be used if the application is able
+ * to deal with messages from different threads.
+ *
+ * Every #GstElement has its own bus.
*/
#include <errno.h>
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gstcaps
+ * @short_description: Structure describing sets of media formats
+ * @see_also: #GstStructure
+ *
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
#define GST_CAPS(object) ((GstCaps*)object)
#define GST_IS_CAPS(object) ((object) && (GST_CAPS(object)->type == GST_TYPE_CAPS))
+/**
+ * GST_CAPS_FLAGS_ANY:
+ *
+ * Flags that this caps has no specific content, but can contain anything.
+ */
#define GST_CAPS_FLAGS_ANY (1 << 0)
+/**
+ * GST_CAPS_ANY:
+ *
+ * Means that the element/pad can output 'anything'. Useful for elements
+ * that output unknown media, such as filesrc.
+ */
#define GST_CAPS_ANY gst_caps_new_any()
+/**
+ * GST_CAPS_NONE:
+ *
+ * The opposite of %GST_CAPS_ANY: it means that the pad/element outputs an
+ * undefined media type that can not be detected.
+ */
#define GST_CAPS_NONE gst_caps_new_empty()
+/**
+ * GST_STATIC_CAPS_ANY:
+ *
+ * Creates a static caps that matches anything. This can be used in pad
+ * templates.
+ *
+ * Returns: a new #GstCaps instance
+ */
#define GST_STATIC_CAPS_ANY GST_STATIC_CAPS("ANY")
+/**
+ * GST_STATIC_CAPS_NONE:
+ *
+ * Creates a static caps that matches nothing. This can be used in pad
+ * templates.
+ *
+ * Returns: a new #GstCaps instance
+ */
#define GST_STATIC_CAPS_NONE GST_STATIC_CAPS("NONE")
+/**
+ * GST_CAPS_IS_SIMPLE:
+ * @caps: the #GstCaps instance to check
+ *
+ * Convinience macro that checks if the number of structures in the gives caps
+ * is exactly one.
+ *
+ * Returns: %TRUE if caps has exactly one structure
+ */
#define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
#ifndef GST_DISABLE_DEPRECATED
+/**
+ * GST_DEBUG_CAPS:
+ * @string: a string the should be prepend to the caps data.
+ * @caps: the #GstCaps instance to print
+ *
+ * Convinience macro for prining out the contents of caps with GST_DEBUG().
+ *
+ * Deprecated: do not use anymore
+ */
#define GST_DEBUG_CAPS(string, caps) \
GST_DEBUG ( string "%s: " GST_PTR_FORMAT, caps)
#endif
+/**
+ * GST_STATIC_CAPS:
+ * @caps: the string describing the caps.
+ *
+ * Creates a static caps from an input string. This can be used in pad
+ * templates.
+ *
+ * Returns: a new #GstCaps instance
+ */
#define GST_STATIC_CAPS(string) \
{ \
/* caps */ { 0 }, \
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
-
+/**
+ * SECTION:gstclock
+ * @short_description: Abstract class for global clocks
+ * @see_also: #GstSystemClock
+ *
+ * GStreamer uses a global clock to synchronise the plugins in a pipeline.
+ * Different clock implementations are possible by implementing this abstract
+ * base class.
+ *
+ * The clock time is always measured in nanoseconds and always increases. The
+ * pipeline uses the clock to calculate the stream time.
+ * Usually all renderers sync to the global clock so that the clock is always
+ * a good measure of the current playback time in the pipeline.
+ */
#include <time.h>
#include "gst_private.h"
#define GST_IS_CLOCK_CLASS(cclass) (G_TYPE_CHECK_CLASS_TYPE ((cclass), GST_TYPE_CLOCK))
#define GST_CLOCK_GET_CLASS(clock) (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
#define GST_CLOCK_CAST(clock) ((GstClock*)(clock))
-
+
+/**
+ * GstClockTime:
+ *
+ * A datatype to hold a time, measured in nanoseconds.
+ */
typedef guint64 GstClockTime;
+/**
+ * GstClockTimeDiff:
+ *
+ * A datatype to hold a timedifference, measured in nanoseconds.
+ */
typedef gint64 GstClockTimeDiff;
+/**
+ * GstClockID:
+ *
+ * A detatype to hold the handle to an outstanding async clock callback
+ */
typedef gpointer GstClockID;
+/**
+ * GST_CLOCK_TIME_NONE:
+ *
+ * Constant to define an undefined clock time
+ */
#define GST_CLOCK_TIME_NONE ((GstClockTime)-1)
+/**
+ * GST_CLOCK_TIME_IS_VALID:
+ * @time: clock time to validate
+ *
+ * Tests if a clock-time is defined.
+ *
+ * Returns: %TRUE if clocktime is safe to use.
+ */
#define GST_CLOCK_TIME_IS_VALID(time) ((time) != GST_CLOCK_TIME_NONE)
+/**
+ * GST_SECOND:
+ *
+ * Constant that defines one GStreamer second
+ */
#define GST_SECOND (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
+/**
+ * GST_MSECOND:
+ *
+ * Constant that defines one GStreamer millisecond
+ */
#define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
+/**
+ * GST_USECOND:
+ *
+ * Constant that defines one GStreamer microsecond
+ */
#define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
+/**
+ * GST_NSECOND:
+ *
+ * Constant that defines one GStreamer nanosecond
+ */
#define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
+/**
+ * GST_CLOCK_DIFF:
+ * @s: the first time
+ * @e: the second time
+ *
+ * Calculate a difference between two clock times.
+ *
+ * Returns: the difference as #GstClockTimeDiff
+ */
#define GST_CLOCK_DIFF(s, e) (GstClockTimeDiff)((s) - (e))
+
+/**
+ * GST_TIMEVAL_TO_TIME:
+ * @tv: the timeval to convert
+ *
+ * Convert a GTimeVal to a GstClockTime
+ *
+ * Returns: the result as #GstClockTime
+ */
#define GST_TIMEVAL_TO_TIME(tv) ((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
+/**
+ * GST_TIME_TO_TIMEVAL:
+ * @t: The GstClockTime to convert
+ * @tv: The target timeval
+ *
+ * Convert a GstClockTime to a GTimeVal
+ */
#define GST_TIME_TO_TIMEVAL(t,tv) \
G_STMT_START { \
(tv).tv_sec = (t) / GST_SECOND; \
(tv).tv_usec = ((t) - (tv).tv_sec * GST_SECOND) / GST_USECOND; \
} G_STMT_END
+/**
+ * GST_TIMESPEC_TO_TIME:
+ * @ts: the timespec to convert
+ *
+ * Convert a GstTimeSpec to a GstClockTime
+ *
+ * Returns: the result as #GstClockTime
+ */
#define GST_TIMESPEC_TO_TIME(ts) ((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
+/**
+ * GST_TIME_TO_TIMESPEC:
+ * @t: The GstClockTime to convert
+ * @ts: The target timespec
+ *
+ * Convert a GstClockTime to a GstTimeSpec
+ */
#define GST_TIME_TO_TIMESPEC(t,ts) \
G_STMT_START { \
(ts).tv_sec = (t) / GST_SECOND; \
(guint) ((((GstClockTime)(t)) / GST_SECOND) % 60), \
(guint) (((GstClockTime)(t)) % GST_SECOND)
+/**
+ * GST_CLOCK_ENTRY_TRACE_NAME:
+ *
+ * The name used for tracing clock entry allocations.
+ */
#define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"
typedef struct _GstClockEntry GstClockEntry;
typedef struct _GstClockClass GstClockClass;
/* --- prototype for async callbacks --- */
+/**
+ * GstClockCallback:
+ * @clock: The clock that triggered the callback
+ * @time: The time it was triggered
+ * @id: The #GstClockID that expired
+ * @user_data: user data passed in the async_wait call
+ *
+ * The function prototype of the callback.
+ *
+ * Returns: %TRUE or %FALSE (currently unused)
+ */
typedef gboolean (*GstClockCallback) (GstClock *clock, GstClockTime time,
GstClockID id, gpointer user_data);
-
+/**
+ * GstClockReturn:
+ * @GST_CLOCK_OK: The operation succeded.
+ * @GST_CLOCK_EARLY: The operation was scheduled too late.
+ * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
+ * @GST_CLOCK_BUSY: The ClockID is busy
+ * @GST_CLOCK_BADTIME: A bad time was provided to a function.
+ * @GST_CLOCK_ERROR: An error occured
+ * @GST_CLOCK_UNSUPPORTED: Operation is not supported
+ *
+ * The return value of a clock operation.
+ */
typedef enum
{
GST_CLOCK_OK = 0,
GST_CLOCK_UNSUPPORTED = 6,
} GstClockReturn;
+/**
+ * GstClockEntryType:
+ * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
+ * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
+ *
+ * The type of the clock entry
+ */
typedef enum {
GST_CLOCK_ENTRY_SINGLE,
GST_CLOCK_ENTRY_PERIODIC
} GstClockEntryType;
+/**
+ * GST_CLOCK_ENTRY:
+ * @entry: the entry to cast
+ *
+ * Cast to a clock entry
+ */
#define GST_CLOCK_ENTRY(entry) ((GstClockEntry *)(entry))
+/**
+ * GST_CLOCK_ENTRY_CLOCK:
+ * @entry: the entry to query
+ *
+ * Get the owner clock of the entry
+ */
#define GST_CLOCK_ENTRY_CLOCK(entry) ((entry)->clock)
+/**
+ * GST_CLOCK_ENTRY_TYPE:
+ * @entry: the entry to query
+ *
+ * Get the type of the clock entry
+ */
#define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
+/**
+ * GST_CLOCK_ENTRY_TIME:
+ * @entry: the entry to query
+ *
+ * Get the requested time of this entry
+ */
#define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
+/**
+ * GST_CLOCK_ENTRY_INTERVAL:
+ * @entry: the entry to query
+ *
+ * Get the interval of this periodic entry
+ */
#define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
+/**
+ * GST_CLOCK_ENTRY_STATUS:
+ * @entry: the entry to query
+ *
+ * The status of the entry
+ */
#define GST_CLOCK_ENTRY_STATUS(entry) ((entry)->status)
+/**
+ * GstClockEntry:
+ * @refcount: reference counter (read-only)
+ *
+ * All pending timeouts or periodic notifies are converted into
+ * an entry.
+ */
struct _GstClockEntry {
gint refcount;
/*< protected >*/
gpointer user_data;
};
-typedef enum
-{
+/**
+ * GstClockFlags:
+ * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: This clock can do a single sync timeut request
+ * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: This clock can do a single async timeout request
+ * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: This clock can do sync periodic timeout requests
+ * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: This clock can do async periodic timeout callbacks
+ * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: The resolution of this clock can be changed
+ *
+ * The capabilities of this clock
+ */
+typedef enum {
GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC = (1 << 1),
GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC = (1 << 2),
GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC = (1 << 3),
GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (1 << 5),
} GstClockFlags;
+/**
+ * GST_CLOCK_FLAGS:
+ * @entry: the entry to query
+ *
+ * Get the clock flags
+ */
#define GST_CLOCK_FLAGS(clock) (GST_CLOCK(clock)->flags)
#define GST_CLOCK_COND(clock) (GST_CLOCK_CAST(clock)->entries_changed)
#define GST_CLOCK_TIMED_WAIT(clock,tv) g_cond_timed_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock),tv)
#define GST_CLOCK_BROADCAST(clock) g_cond_broadcast(GST_CLOCK_COND(clock))
+/**
+ * GstClock:
+ * @stats: Boolean property to activate stat generation on the clock.
+ *
+ */
struct _GstClock {
GstObject object;
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gstmessage
+ * @short_description: Lightweight objects to signal the application of pipeline events
+ * @see_also: #GstBus,#GstMiniObject
+ *
+ * Messages are implemented as a subclass of #GstMiniObject with a generic
+ * #GstStructure as the content. This allows for writing custom messages without
+ * requiring an API change while allowing a wide range of different types
+ * of messages.
+ *
+ * Messages are posted by objects in the pipeline and are passed to the
+ * application using the #GstBus.
+ */
#include <string.h> /* memcpy */
projects / platform / upstream / gstreamer.git / commitdiff