From 588e11ad390666eb38b85a3506214317cfdaa591 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Sun, 18 Dec 2005 16:04:41 +0000 Subject: [PATCH] libs/gst/: Documentation updates. Original commit message from CVS: * libs/gst/base/gstadapter.c: * libs/gst/base/gstadapter.h: * libs/gst/base/gstbasesink.c: (gst_base_sink_class_init), (gst_base_sink_get_position): * libs/gst/base/gstbasesink.h: * libs/gst/base/gstbasesrc.c: (gst_base_src_class_init), (gst_base_src_default_query), (gst_base_src_default_do_seek), (gst_base_src_do_seek), (gst_base_src_perform_seek), (gst_base_src_send_event), (gst_base_src_update_length), (gst_base_src_get_range), (gst_base_src_loop), (gst_base_src_start): * libs/gst/base/gstbasesrc.h: * libs/gst/base/gstbasetransform.h: * libs/gst/base/gstcollectpads.h: * libs/gst/base/gstpushsrc.c: * libs/gst/base/gstpushsrc.h: * libs/gst/dataprotocol/dataprotocol.c: * libs/gst/dataprotocol/dataprotocol.h: * libs/gst/net/gstnetclientclock.h: * libs/gst/net/gstnettimeprovider.h: Documentation updates. --- ChangeLog | 24 ++++++++++++++ libs/gst/base/gstadapter.c | 6 ++-- libs/gst/base/gstadapter.h | 1 + libs/gst/base/gstbasesink.c | 64 ++++++++++++++++++++++++++---------- libs/gst/base/gstbasesink.h | 1 + libs/gst/base/gstbasesrc.c | 23 +++++++++++-- libs/gst/base/gstbasesrc.h | 1 + libs/gst/base/gstbasetransform.h | 1 + libs/gst/base/gstcollectpads.h | 1 + libs/gst/base/gstpushsrc.c | 3 ++ libs/gst/base/gstpushsrc.h | 1 + libs/gst/dataprotocol/dataprotocol.c | 4 +++ libs/gst/dataprotocol/dataprotocol.h | 42 +++++++++++++++++++---- libs/gst/net/gstnetclientclock.h | 1 + libs/gst/net/gstnettimeprovider.h | 2 ++ 15 files changed, 148 insertions(+), 27 deletions(-) diff --git a/ChangeLog b/ChangeLog index 87603ed..4dd0682 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,27 @@ +2005-12-18 Wim Taymans + + * libs/gst/base/gstadapter.c: + * libs/gst/base/gstadapter.h: + * libs/gst/base/gstbasesink.c: (gst_base_sink_class_init), + (gst_base_sink_get_position): + * libs/gst/base/gstbasesink.h: + * libs/gst/base/gstbasesrc.c: (gst_base_src_class_init), + (gst_base_src_default_query), (gst_base_src_default_do_seek), + (gst_base_src_do_seek), (gst_base_src_perform_seek), + (gst_base_src_send_event), (gst_base_src_update_length), + (gst_base_src_get_range), (gst_base_src_loop), + (gst_base_src_start): + * libs/gst/base/gstbasesrc.h: + * libs/gst/base/gstbasetransform.h: + * libs/gst/base/gstcollectpads.h: + * libs/gst/base/gstpushsrc.c: + * libs/gst/base/gstpushsrc.h: + * libs/gst/dataprotocol/dataprotocol.c: + * libs/gst/dataprotocol/dataprotocol.h: + * libs/gst/net/gstnetclientclock.h: + * libs/gst/net/gstnettimeprovider.h: + Documentation updates. + 2005-12-18 Tim-Philipp Müller * docs/manual/basics-helloworld.xml: diff --git a/libs/gst/base/gstadapter.c b/libs/gst/base/gstadapter.c index 6c8720a..e3aa409 100644 --- a/libs/gst/base/gstadapter.c +++ b/libs/gst/base/gstadapter.c @@ -78,7 +78,9 @@ * of GstAdapter is inside one pad's chain function, in which case access is * serialized via the pad's stream lock. * - * Last reviewed on 2005-11-08 (0.9.5). + * Note that gst_adapter_push() takes ownership of the buffer passed. + * + * Last reviewed on 2005-12-18 (0.10.0). */ #include @@ -303,7 +305,7 @@ gst_adapter_flush (GstAdapter * adapter, guint flush) * Returns a freshly allocated buffer containing the first @nbytes bytes of the * @adapter. * - * Caller owns returned value. + * Caller owns returned value. g_free after usage. * * Returns: oven-fresh hot data, or #NULL if @nbytes bytes are not available */ diff --git a/libs/gst/base/gstadapter.h b/libs/gst/base/gstadapter.h index 62565d7..f4d5f2d 100644 --- a/libs/gst/base/gstadapter.h +++ b/libs/gst/base/gstadapter.h @@ -44,6 +44,7 @@ typedef struct _GstAdapterClass GstAdapterClass; /** * GstAdapter: + * @object: the parent object. * * The opaque #GstAdapter data structure. */ diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c index 382a2be..4ea95bf 100644 --- a/libs/gst/base/gstbasesink.c +++ b/libs/gst/base/gstbasesink.c @@ -24,13 +24,13 @@ * @short_description: Base class for sink elements * @see_also: #GstBaseTransform, #GstBaseSource * - * GstBaseSink is the base class for sink elements in GStreamer, such as + * #GstBaseSink is the base class for sink elements in GStreamer, such as * xvimagesink or filesink. It is a layer on top of #GstElement that provides a - * simplified interface to plugin writers. GstBaseSink handles many details for + * simplified interface to plugin writers. #GstBaseSink handles many details for * you, for example preroll, clock synchronization, state changes, activation in * push or pull mode, and queries. In most cases, when writing sink elements, * there is no need to implement class methods from #GstElement or to set - * functions on pads, because the GstBaseSink infrastructure is sufficient. + * functions on pads, because the #GstBaseSink infrastructure is sufficient. * * There is only support in GstBaseSink for one sink pad, which should be named * "sink". A sink implementation (subclass of GstBaseSink) should install a pad @@ -50,26 +50,55 @@ * } * * - * The one method which all subclasses of GstBaseSink must implement is - * GstBaseSink::render. This method will be called... - * - * preroll() - * - * event(): mostly useful for file-like sinks (seeking or flushing) + * #GstBaseSink will handle the prerolling correctly. This means that it will + * return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first buffer + * arrives in this element. The base class will call the GstBaseSink::preroll + * vmethod with this preroll buffer and will then commit the state change to + * PAUSED. * - * get_caps/set_caps/buffer_alloc + * When the element is set to PLAYING, #GstBaseSink will synchronize on the clock + * using the times returned from ::get_times. If this function returns + * #GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done. + * Synchronisation can be disabled entirely by setting the sync property to FALSE. * - * start/stop for resource allocation + * After synchronisation the virtual method #GstBaseSink::render will be called. + * Subclasses should minimally implement this method. * - * unlock if you block on an fd, for example + * Upon receiving the EOS event in th PLAYING state, #GstBaseSink will wait for + * the clock to reach the time indicated by the stop time of the last ::get_times + * call before posting an EOS message. When the element receives EOS in PAUSED, + * the event is queued and an EOS message is posted when going to PLAYING. + * + * #GstBaseSink will internally use the GST_EVENT_NEW_SEGMENT events to schedule + * synchronisation and clipping of buffers. Buffers that fall completely outside + * of the segment are dropped. Buffers that fall partially in the segment are + * rendered (and prerolled), subclasses should do any subbuffer clipping themselves + * when needed. + * + * #GstBaseSink will by default report the current playback position in + * GST_FORMAT_TIME based on the current clock time and segment information. + * If the element is EOS however, the query will be forwarded upstream. * - * get_times i'm sure is for something :P + * The ::set_caps function will be called when the subclass should configure itself + * to precess a specific media type. + * + * The ::start and ::stop virtual methods will be called when resources should be + * allocated. Any ::preroll, ::render and ::set_caps function will be called + * between the ::start and ::stop calls. * - * provide example of textsink + * The ::event virtual method will be called when an event is received by + * #GstBaseSink. Normally this method should only be overriden by very specific + * elements such as file sinks that need to handle the newsegment event specially. + * + * #GstBaseSink provides an overridable ::buffer_alloc function that can be used + * by specific sinks that want to do reverse negotiation or want to provided + * hardware accelerated buffers for downstream elements. * - * admonishment not to try to implement your own sink with prerolling... + * The ::unlock method is called when the elements should unblock any blocking + * operations they perform in the ::render method. This is mostly usefull when + * the ::render method performs a blocking write on a file descripter. * - * extending via subclassing, setting pad functions, gstelement vmethods. + * Last reviewed on 2005-12-18 (0.10.0) */ #ifdef HAVE_CONFIG_H @@ -188,12 +217,13 @@ gst_base_sink_class_init (GstBaseSinkClass * klass) gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_base_sink_get_property); /* FIXME, this next value should be configured using an event from the - * upstream element */ + * upstream element, ie, the BUFFER_SIZE event. */ g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_PREROLL_QUEUE_LEN, g_param_spec_uint ("preroll-queue-len", "preroll-queue-len", "Number of buffers to queue during preroll", 0, G_MAXUINT, 0, G_PARAM_READWRITE | G_PARAM_CONSTRUCT)); + g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_SYNC, g_param_spec_boolean ("sync", "Sync", "Sync on the clock", DEFAULT_SYNC, G_PARAM_READWRITE)); diff --git a/libs/gst/base/gstbasesink.h b/libs/gst/base/gstbasesink.h index 34ba2cf..c0b4ed5 100644 --- a/libs/gst/base/gstbasesink.h +++ b/libs/gst/base/gstbasesink.h @@ -49,6 +49,7 @@ typedef struct _GstBaseSinkClass GstBaseSinkClass; /** * GstBaseSink: + * @element: the parent element. * * The opaque #GstBaseSink data structure. */ diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c index 179a108..020e727 100644 --- a/libs/gst/base/gstbasesrc.c +++ b/libs/gst/base/gstbasesrc.c @@ -82,9 +82,28 @@ * * The #GstBaseSrc::get_times method can be used to implement pseudo-live sources. * The base source will wait for the specified stream time returned in - * #GstBaseSrc::get_times before pushing out the buffer. + * #GstBaseSrc::get_times before pushing out the buffer. It only makes sense to implement + * the ::get_times function if the source is a live source. * - * Last reviewed on 2005-12-10 (0.10.0) + * There is only support in GstBaseSrc for one source pad, which should be named + * "src". A source implementation (subclass of GstBaseSrc) should install a pad + * template in its base_init function, like so: + * + * + * static void + * my_element_base_init (gpointer g_class) + * { + * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class); + * // srctemplate should be a #GstStaticPadTemplate with direction + * // #GST_PAD_SRC and name "src" + * gst_element_class_add_pad_template (gstelement_class, + * gst_static_pad_template_get (&srctemplate)); + * // see #GstElementDetails + * gst_element_class_set_details (gstelement_class, &details); + * } + * + * + * Last reviewed on 2005-12-18 (0.10.0) */ #include diff --git a/libs/gst/base/gstbasesrc.h b/libs/gst/base/gstbasesrc.h index 640ef03..c5b6221 100644 --- a/libs/gst/base/gstbasesrc.h +++ b/libs/gst/base/gstbasesrc.h @@ -63,6 +63,7 @@ typedef struct _GstBaseSrcClass GstBaseSrcClass; /** * GstBaseSrc: + * @element: the parent element. * * The opaque #GstBaseSrc data structure. */ diff --git a/libs/gst/base/gstbasetransform.h b/libs/gst/base/gstbasetransform.h index 0d11b80..63a48c6 100644 --- a/libs/gst/base/gstbasetransform.h +++ b/libs/gst/base/gstbasetransform.h @@ -51,6 +51,7 @@ typedef struct _GstBaseTransformClass GstBaseTransformClass; /** * GstBaseTransform: + * @element: the parent element. * * The opaque #GstBaseTransform data structure. */ diff --git a/libs/gst/base/gstcollectpads.h b/libs/gst/base/gstcollectpads.h index 9bbe831..aa331cb 100644 --- a/libs/gst/base/gstcollectpads.h +++ b/libs/gst/base/gstcollectpads.h @@ -77,6 +77,7 @@ typedef GstFlowReturn (*GstCollectPadsFunction) (GstCollectPads *pads, gpointer /** * GstCollectPads: + * @object: the #GstObject parent structure. * @data: #GList of #GstCollectData managed by this #GstCollectPads. * * Collectpads object. diff --git a/libs/gst/base/gstpushsrc.c b/libs/gst/base/gstpushsrc.c index 59fdcec..224fe8d 100644 --- a/libs/gst/base/gstpushsrc.c +++ b/libs/gst/base/gstpushsrc.c @@ -29,6 +29,9 @@ * random access, or at least very slowly. The source usually * prefers to push out a fixed size buffer. * + * Subclasses usually operate in a format that is different from the + * default GST_FORMAT_BYTES format of #GstBaseSrc. + * * Classes extending this base class will usually be scheduled * in a push based mode. If the peer accepts to operate without * offsets and withing the limits of the allowed block size, this diff --git a/libs/gst/base/gstpushsrc.h b/libs/gst/base/gstpushsrc.h index a7480b4..4563a7e 100644 --- a/libs/gst/base/gstpushsrc.h +++ b/libs/gst/base/gstpushsrc.h @@ -41,6 +41,7 @@ typedef struct _GstPushSrcClass GstPushSrcClass; /** * GstPushSrc: + * @parent: the parent base source object. * * The opaque #GstPushSrc data structure. */ diff --git a/libs/gst/dataprotocol/dataprotocol.c b/libs/gst/dataprotocol/dataprotocol.c index aaf3d3e..1316682 100644 --- a/libs/gst/dataprotocol/dataprotocol.c +++ b/libs/gst/dataprotocol/dataprotocol.c @@ -124,6 +124,8 @@ gst_dp_init (void) * gst_dp_header_payload_length: * @header: the byte header of the packet array * + * Get the length of the payload described by @header. + * * Returns: the length of the payload this header describes. */ guint32 @@ -136,6 +138,8 @@ gst_dp_header_payload_length (const guint8 * header) * gst_dp_header_payload_type: * @header: the byte header of the packet array * + * Get the type of the payload described by @header. + * * Returns: the #GstDPPayloadType the payload this header describes. */ GstDPPayloadType diff --git a/libs/gst/dataprotocol/dataprotocol.h b/libs/gst/dataprotocol/dataprotocol.h index a326a91..912d2c4 100644 --- a/libs/gst/dataprotocol/dataprotocol.h +++ b/libs/gst/dataprotocol/dataprotocol.h @@ -29,14 +29,35 @@ G_BEGIN_DECLS -/* GStreamer Data Protocol Version */ +/** + * GST_DP_VERSION_MAJOR: + * + * The major version number of the GStreamer Data Protocol. + */ #define GST_DP_VERSION_MAJOR 0 +/** + * GST_DP_VERSION_MINOR: + * + * The minor version number of the GStreamer Data Protocol. + */ #define GST_DP_VERSION_MINOR 2 -#define GST_DP_HEADER_LENGTH 62 /* header size in bytes */ - - -/* header flags */ +/** + * GST_DP_HEADER_LENGTH: + * + * The header size in bytes. + */ +#define GST_DP_HEADER_LENGTH 62 + +/** + * GstDPHeaderFlag: + * @GST_DP_HEADER_FLAG_NONE: No flag present. + * @GST_DP_HEADER_FLAG_CRC_HEADER: a header CRC field is present. + * @GST_DP_HEADER_FLAG_CRC_PAYLOAD: a payload CRC field is present. + * @GST_DP_HEADER_FLAG_CRC: a CRC for header and payload is present. + * + * header flags for the dataprotocol. + */ typedef enum { GST_DP_HEADER_FLAG_NONE = 0, GST_DP_HEADER_FLAG_CRC_HEADER = (1 << 0), @@ -44,7 +65,16 @@ typedef enum { GST_DP_HEADER_FLAG_CRC = (1 << 1) | (1 <<0), } GstDPHeaderFlag; -/* payload types */ +/** + * GstDPPayloadType: + * @GST_DP_PAYLOAD_NONE: Invalid payload type. + * @GST_DP_PAYLOAD_BUFFER: #GstBuffer payload packet. + * @GST_DP_PAYLOAD_CAPS: #GstCaps payload packet. + * @GST_DP_PAYLOAD_EVENT_NONE: First value of #GstEvent payload packets. + * + * The GDP payload types. a #GstEvent payload type is encoded with the + * event type number starting from @GST_DP_PAYLOAD_EVENT_NONE. + */ typedef enum { GST_DP_PAYLOAD_NONE = 0, GST_DP_PAYLOAD_BUFFER, diff --git a/libs/gst/net/gstnetclientclock.h b/libs/gst/net/gstnetclientclock.h index 1b7412e..6918770 100644 --- a/libs/gst/net/gstnetclientclock.h +++ b/libs/gst/net/gstnetclientclock.h @@ -57,6 +57,7 @@ typedef struct _GstNetClientClockClass GstNetClientClockClass; /** * GstNetClientClock: + * @clock: the parent clock structure. * * Opaque #GstNetClientClock structure. */ diff --git a/libs/gst/net/gstnettimeprovider.h b/libs/gst/net/gstnettimeprovider.h index f6b3bb7..dadf5c8 100644 --- a/libs/gst/net/gstnettimeprovider.h +++ b/libs/gst/net/gstnettimeprovider.h @@ -51,6 +51,7 @@ typedef struct _GstNetTimeProviderClass GstNetTimeProviderClass; /** * GstNetTimeProvider: + * @parent: the parent object structure. * * Opaque #GstNetTimeProvider structure. */ @@ -74,6 +75,7 @@ struct _GstNetTimeProvider { gint active; } active; + /*< private >*/ gpointer _gst_reserved[GST_PADDING - 1]; }; -- 2.7.4