Menu
▾
▴
[gst-cvs] ensonic gstreamer: gstreamer/ gstreamer/docs/design/ gstreamer/docs/gst/tmpl/ gstreamer/gst/
|
From: <en...@fr...> - 2005-08-27 10:57:14
|
CVS Root: /cvs/gstreamer
Module: gstreamer
Changes by: ensonic
Date: Sat Aug 27 2005 03:57:13 PDT
Log message:
* 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
Modified files:
. : ChangeLog
docs/design : part-messages.txt
docs/gst/tmpl : .cvsignore
gst : gstbus.c gstcaps.c gstcaps.h gstclock.c
gstclock.h gstmessage.c
Removed files:
docs/gst/tmpl : gstcaps.sgml gstclock.sgml
Links:
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/ChangeLog.diff?r1=1.1418&r2=1.1419
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/design/part-messages.txt.diff?r1=1.2&r2=1.3
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/.cvsignore.diff?r1=1.7&r2=1.8
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstcaps.sgml
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/docs/gst/tmpl/gstclock.sgml
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstbus.c.diff?r1=1.21&r2=1.22
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstcaps.c.diff?r1=1.138&r2=1.139
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstcaps.h.diff?r1=1.91&r2=1.92
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstclock.c.diff?r1=1.55&r2=1.56
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstclock.h.diff?r1=1.38&r2=1.39
http://freedesktop.org/cgi-bin/viewcvs.cgi/gstreamer/gstreamer/gst/gstmessage.c.diff?r1=1.26&r2=1.27
====Begin Diffs====
Index: ChangeLog
===================================================================
RCS file: /cvs/gstreamer/gstreamer/ChangeLog,v
retrieving revision 1.1418
retrieving revision 1.1419
diff -u -d -r1.1418 -r1.1419
--- ChangeLog 26 Aug 2005 22:32:51 -0000 1.1418
+++ ChangeLog 27 Aug 2005 10:56:59 -0000 1.1419
@@ -1,5 +1,21 @@
2005-08-27 Stefan Kost <en...@us...>
+ * 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 <en...@us...>
* gst/gstmessage.c:
* gst/gstmessage.h:
doc fixes
Index: part-messages.txt
RCS file: /cvs/gstreamer/gstreamer/docs/design/part-messages.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- part-messages.txt 21 Apr 2005 09:37:34 -0000 1.2
+++ part-messages.txt 27 Aug 2005 10:57:00 -0000 1.3
@@ -4,7 +4,7 @@
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.
Index: .cvsignore
RCS file: /cvs/gstreamer/gstreamer/docs/gst/tmpl/.cvsignore,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- .cvsignore 25 Aug 2005 23:17:18 -0000 1.7
+++ .cvsignore 27 Aug 2005 10:57:00 -0000 1.8
@@ -8,7 +8,9 @@
gstbin.sgml
gstbuffer.sgml
gstbus.sgml
+gstcaps.sgml
gstcheck.sgml
+gstclock.sgml
gstcollectpads.sgml
gstevent.sgml
gstfakesrc.sgml
--- gstcaps.sgml DELETED ---
--- gstclock.sgml DELETED ---
Index: gstbus.c
RCS file: /cvs/gstreamer/gstreamer/gst/gstbus.c,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -d -r1.21 -r1.22
--- gstbus.c 26 Aug 2005 13:28:01 -0000 1.21
+++ gstbus.c 27 Aug 2005 10:57:00 -0000 1.22
@@ -21,6 +21,38 @@
/**
* 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>
Index: gstcaps.c
RCS file: /cvs/gstreamer/gstreamer/gst/gstcaps.c,v
retrieving revision 1.138
retrieving revision 1.139
diff -u -d -r1.138 -r1.139
--- gstcaps.c 22 Aug 2005 14:35:42 -0000 1.138
+++ gstcaps.c 27 Aug 2005 10:57:00 -0000 1.139
@@ -16,6 +16,12 @@
* 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"
Index: gstcaps.h
RCS file: /cvs/gstreamer/gstreamer/gst/gstcaps.h,v
retrieving revision 1.91
retrieving revision 1.92
diff -u -d -r1.91 -r1.92
--- gstcaps.h 24 Aug 2005 16:09:50 -0000 1.91
+++ gstcaps.h 27 Aug 2005 10:57:00 -0000 1.92
@@ -29,21 +29,81 @@
#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
#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
#define GST_STATIC_CAPS(string) \
{ \
/* caps */ { 0 }, \
Index: gstclock.c
RCS file: /cvs/gstreamer/gstreamer/gst/gstclock.c,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- gstclock.c 20 Aug 2005 12:39:05 -0000 1.55
+++ gstclock.c 27 Aug 2005 10:57:00 -0000 1.56
@@ -20,7 +20,20 @@
-
+ * 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"
Index: gstclock.h
RCS file: /cvs/gstreamer/gstreamer/gst/gstclock.h,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -d -r1.38 -r1.39
--- gstclock.h 24 Aug 2005 11:22:32 -0000 1.38
+++ gstclock.h 27 Aug 2005 10:57:00 -0000 1.39
@@ -35,28 +35,116 @@
#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
#define GST_TIMESPEC_TO_TIME(ts) ((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
+ * GST_TIME_TO_TIMESPEC:
+ * @ts: The target timespec
+ * Convert a GstClockTime to a GstTimeSpec
#define GST_TIME_TO_TIMESPEC(t,ts) \
(ts).tv_sec = (t) / GST_SECOND; \
@@ -71,6 +159,11 @@
(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;
@@ -78,9 +171,31 @@
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,
@@ -92,18 +207,68 @@
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:
+ * Get the type of the clock entry
#define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
+ * GST_CLOCK_ENTRY_TIME:
+ * Get the requested time of this entry
#define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
+ * GST_CLOCK_ENTRY_INTERVAL:
+ * Get the interval of this periodic entry
#define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
+ * GST_CLOCK_ENTRY_STATUS:
+ * 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 >*/
@@ -116,8 +281,17 @@
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),
@@ -125,6 +299,12 @@
GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (1 << 5),
} GstClockFlags;
+ * GST_CLOCK_FLAGS:
+ * Get the clock flags
#define GST_CLOCK_FLAGS(clock) (GST_CLOCK(clock)->flags)
#define GST_CLOCK_COND(clock) (GST_CLOCK_CAST(clock)->entries_changed)
@@ -132,6 +312,11 @@
#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;
Index: gstmessage.c
RCS file: /cvs/gstreamer/gstreamer/gst/gstmessage.c,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- gstmessage.c 26 Aug 2005 22:32:51 -0000 1.26
+++ gstmessage.c 27 Aug 2005 10:57:00 -0000 1.27
@@ -18,6 +18,19 @@
+ * 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 */
|