+2005-12-18 Wim Taymans <wim@fluendo.com>
+
+ * 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 <tim at centricular dot net>
* docs/manual/basics-helloworld.xml:
* 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 <string.h>
* 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
*/
/**
* GstAdapter:
+ * @object: the parent object.
*
* The opaque #GstAdapter data structure.
*/
* @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
* }
* </programlisting>
*
- * 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
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));
/**
* GstBaseSink:
+ * @element: the parent element.
*
* The opaque #GstBaseSink data structure.
*/
*
* 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:
+ *
+ * <programlisting>
+ * 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);
+ * }
+ * </programlisting>
+ *
+ * Last reviewed on 2005-12-18 (0.10.0)
*/
#include <stdlib.h>
/**
* GstBaseSrc:
+ * @element: the parent element.
*
* The opaque #GstBaseSrc data structure.
*/
/**
* GstBaseTransform:
+ * @element: the parent element.
*
* The opaque #GstBaseTransform data structure.
*/
/**
* GstCollectPads:
+ * @object: the #GstObject parent structure.
* @data: #GList of #GstCollectData managed by this #GstCollectPads.
*
* Collectpads object.
* 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
/**
* GstPushSrc:
+ * @parent: the parent base source object.
*
* The opaque #GstPushSrc data structure.
*/
* 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
* 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
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),
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,
/**
* GstNetClientClock:
+ * @clock: the parent clock structure.
*
* Opaque #GstNetClientClock structure.
*/
/**
* GstNetTimeProvider:
+ * @parent: the parent object structure.
*
* Opaque #GstNetTimeProvider structure.
*/
gint active;
} active;
+ /*< private >*/
gpointer _gst_reserved[GST_PADDING - 1];
};
projects / platform / upstream / gstreamer.git / commitdiff