diff --git a/ChangeLog b/ChangeLog index 8f4bc9a96d..d64678a1db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2006-04-04 Jan Schmidt + + * docs/libs/gstreamer-libs-sections.txt: + * gst/gsttaglist.c: + * libs/gst/base/gstbasesink.c: + * libs/gst/base/gstbasesink.h: + * libs/gst/base/gstbasesrc.c: + * libs/gst/base/gstbasesrc.h: + Documentation updates. Make BaseSink and BaseSrc docs contain the + class structure so that people can actually see the prototypes for + virtual functions they're supposed to be overriding. + 2006-04-04 Tim-Philipp Müller * plugins/elements/gsttypefindelement.c: diff --git a/docs/libs/gstreamer-libs-sections.txt b/docs/libs/gstreamer-libs-sections.txt index 4aa68b6155..762098929a 100644 --- a/docs/libs/gstreamer-libs-sections.txt +++ b/docs/libs/gstreamer-libs-sections.txt @@ -129,6 +129,7 @@ gst_adapter_get_type GstBaseSrc gst/base/gstbasesrc.h GstBaseSrc +GstBaseSrcClass GstBaseSrcFlags gst_base_src_is_live @@ -137,7 +138,6 @@ gst_base_src_set_format GST_BASE_SRC_PAD -GstBaseSrcClass GstBaseSrcPrivate GST_BASE_SRC GST_BASE_SRC_CAST @@ -156,6 +156,7 @@ gst_base_src_get_type GstBaseSink gst/base/gstbasesink.h GstBaseSink +GstBaseSinkClass GST_BASE_SINK_PAD @@ -165,7 +166,6 @@ gst_base_sink_set_max_lateness gst_base_sink_get_max_lateness -GstBaseSinkClass GST_BASE_SINK GST_BASE_SINK_CAST GST_IS_BASE_SINK diff --git a/gst/gsttaglist.c b/gst/gsttaglist.c index a1926bfbfc..2884cbe77d 100644 --- a/gst/gsttaglist.c +++ b/gst/gsttaglist.c @@ -1256,6 +1256,9 @@ TAG_MERGE_FUNCS (pointer, gpointer) * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. + * + * The resulting string in @value should be freed by the caller using g_free + * when no longer needed * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list. @@ -1270,6 +1273,9 @@ TAG_MERGE_FUNCS (pointer, gpointer) * Gets the value that is at the given index for the given tag in the given * list. * + * The resulting string in @value should be freed by the caller using g_free + * when no longer needed + * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list. */ diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c index bc43c357c1..f507216c57 100644 --- a/libs/gst/base/gstbasesink.c +++ b/libs/gst/base/gstbasesink.c @@ -26,15 +26,17 @@ * * #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 - * 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 should be sufficient. + * 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 should be 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 - * template in its base_init function, like so: + * #GstBaseSink provides support for exactly one sink pad, which should be + * named "sink". A sink implementation (subclass of GstBaseSink) should + * install a pad template in its base_init function, like so: * * static void * my_element_base_init (gpointer g_class) @@ -51,75 +53,81 @@ * * * #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 the - * next asynchronously pending state. + * 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 the next asynchronously pending state. * - * When the element is set to PLAYING, #GstBaseSink will synchronize on the clock - * using the times returned from ::get_times. If this function returns + * When the element is set to PLAYING, #GstBaseSink will synchronise 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 object "sync" property - * to FALSE. + * Synchronisation can be disabled entirely by setting the object "sync" + * property to FALSE. * * After synchronisation the virtual method #GstBaseSink::render will be called. * Subclasses should minimally implement this method. * - * Since 0.10.3 subclasses that synchronize on the clock in the ::render method + * Since 0.10.3 subclasses that synchronise on the clock in the ::render method * are supported as well. These classes typically receive a buffer in the render * method and can then potentially block on the clock while rendering. A typical - * example would be an audiosink. + * example is an audiosink. * - * Upon receiving the EOS event in the 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, - * preroll completes, the event is queued and an EOS message is posted when going - * to PLAYING. + * Upon receiving the EOS event in the 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, preroll completes, 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. + * of the current 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 no clock has been set on the element, the query will be forwarded upstream. + * If no clock has been set on the element, the query will be forwarded + * upstream. * - * The ::set_caps function will be called when the subclass should configure itself - * to process a specific media type. + * The ::set_caps function will be called when the subclass should configure + * itself to process 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. + * 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. * * 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. + * elements (such as file sinks) which 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. + * #GstBaseSink provides an overridable ::buffer_alloc function that can be + * used by sinks that want to do reverse negotiation or to provide + * custom buffers (hardware buffers for example) to upstream elements. * * 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. + * operations they perform in the ::render method. This is mostly useful when + * the ::render method performs a blocking write on a file descriptor, for + * example. * - * The max-lateness property defines how the sink deals with buffers that arrive - * too late in the sink. A buffer arrives too late in the sink when the presentation - * time (as a combination of the last segment, buffer timestamp and element - * base_time) plus the duration is before the current time of the clock. - * If the frame is later than max-lateness, the sink will drop the buffer. - * This feature is disabled if sync is disabled, the ::get-times method does not - * return a valid start time or max-lateness is set to -1 (the default). - * Subclasses can use gst_base_sink_set_max_lateness() to configure the max-lateness. + * The max-lateness property affects how the sink deals with buffers that + * arrive too late in the sink. A buffer arrives too late in the sink when + * the presentation time (as a combination of the last segment, buffer + * timestamp and element base_time) plus the duration is before the current + * time of the clock. + * If the frame is later than max-lateness, the sink will drop the buffer + * without calling the render method. + * This feature is disabled if sync is disabled, the ::get-times method does + * not return a valid start time or max-lateness is set to -1 (the default). + * Subclasses can use gst_base_sink_set_max_lateness() to configure the + * max-lateness value. * * The qos property will enable the quality-of-service features of the basesink * which gather statistics about the real-time performance of the clock * synchronisation. For each dropped buffer it will also send a QoS message * upstream. * - * Last reviewed on 2006-03-21 (0.10.5) + * Last reviewed on 2006-03-31 (0.10.5) */ #ifdef HAVE_CONFIG_H diff --git a/libs/gst/base/gstbasesink.h b/libs/gst/base/gstbasesink.h index e00b61b37c..5c6d972ea6 100644 --- a/libs/gst/base/gstbasesink.h +++ b/libs/gst/base/gstbasesink.h @@ -102,6 +102,31 @@ struct _GstBaseSink { GstBaseSinkPrivate *priv; }; +/** + * GstBaseSinkClass: + * @parent_class: Element parent class + * @get_caps: Called to get sink pad caps from the subclass + * @set_caps: Notify subclass of changed caps + * @buffer_alloc: Subclasses can override to perform custom buffer allocations + * @get_times: Called to get the start and end times for synchronising + * the passed buffer to the clock + * @start: Start processing. Ideal for opening resources in the subclass + * @stop: Stop processing. Subclasses should use this to close resources. + * @unlock: Unlock any pending access to the resource. Subclasses should + * unblock any blocked function ASAP + * @event: Override this to handle events arriving on the sink pad + * @preroll: Called to present the preroll buffer if desired + * @render: Called when a buffer should be presented or output, at the + * correct moment if the #GstBaseSink has been set to sync to + * the clock. + * @async_play: Subclasses should override this when they need to perform + * special processing when changing to the PLAYING state asynchronously. + * Called with the OBJECT_LOCK held. + * + * Subclasses can override any of the available virtual methods or not, as + * needed. At the minimum, the render method should be overridden to + * output/present buffers + */ struct _GstBaseSinkClass { GstElementClass parent_class; diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c index bea2d97731..bb2b69666f 100644 --- a/libs/gst/base/gstbasesrc.c +++ b/libs/gst/base/gstbasesrc.c @@ -35,23 +35,25 @@ * * * - * The source can be configured to operate in a any #GstFormat with the - * gst_base_src_set_format(). This format determines the format of the - * internal #GstSegment and the #GST_EVENT_NEW_SEGMENT. The default format for - * #GstBaseSrc is GST_FORMAT_BYTES. + * The source can be configured to operate in any #GstFormat with the + * gst_base_src_set_format() method. The currently set format determines + * the format of the internal #GstSegment and any #GST_EVENT_NEW_SEGMENT + * events. The default format for #GstBaseSrc is #GST_FORMAT_BYTES. * * - * #GstBaseSrc always supports the push mode scheduling. If the following + * #GstBaseSrc always supports push mode scheduling. If the following * conditions are met, it also supports pull mode scheduling: * - * the format is set to GST_FORMAT_BYTES (default). - * #GstBaseSrc::is_seekable returns TRUE. + * The format is set to GST_FORMAT_BYTES (default). + * + * #GstBaseSrc::is_seekable returns TRUE. + * * * * * If all the conditions are met for operating in pull mode, #GstBaseSrc is - * automatically seekable in push mode as well. The following conditions must be - * met to make the element seekable in push mode when the format is not + * automatically seekable in push mode as well. The following conditions must + * be met to make the element seekable in push mode when the format is not * GST_FORMAT_BYTES: * * @@ -67,37 +69,39 @@ * * * - * When the default format is not GST_FORMAT_BYTES, the element should ignore the - * offset and length in the #GstBaseSrc::create method. It is recommended to subclass - * #GstPushSrc instead in this situation. + * When the default format is not GST_FORMAT_BYTES, the subclass should ignore + * the offset and length in the #GstBaseSrc::create method. It is recommended + * to subclass #GstPushSrc instead in this situation. * * - * #GstBaseSrc has support for live sources. Live sources are sources that produce - * data at a fixed rate, such as audio or video capture. A typical live source also - * provides a clock to export the rate at which they produce data. + * #GstBaseSrc has support for live sources. Live sources are sources that + * produce data at a fixed rate, such as audio or video capture devices. A + * typical live source also provides a clock to publish the rate at which + * they produce data. * Use gst_base_src_set_live() to activate the live source mode. * * - * A live source does not produce data in the PAUSED state, this means that the + * A live source does not produce data in the PAUSED state. This means that the * #GstBaseSrc::create method will not be called in PAUSED but only in PLAYING. - * To signal the pipeline that the element will not produce data, its return + * To signal the pipeline that the element will not produce data, the return * value from the READY to PAUSED state will be GST_STATE_CHANGE_NO_PREROLL. * * - * A typical live source will timestamp the buffers they create with the current - * stream time of the pipeline. This is why they can only produce data in PLAYING, - * when the clock is actually distributed and running. + * A typical live source will timestamp the buffers they create with the + * current stream time of the pipeline. This is one reason that they can only + * produce data in PLAYING, when the clock is actually distributed and running. * * - * 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. It only makes sense to implement - * the ::get_times function if the source is a live source. + * 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. + * It only makes sense to implement the ::get_times function if the source is + * a live source. * * - * 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: + * There is only support in GstBaseSrc for exactly 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: * * * @@ -118,7 +122,7 @@ * * Applications that record from a live source may want to stop recording * in a controlled way, so that the recording is stopped, but the data - * already in the pipeline processed to the end (remember that many live + * already in the pipeline is processed to the end (remember that many live * sources would go on recording forever otherwise). For that to happen the * application needs to make the source stop recording and send an EOS * event down the pipeline. The application would then wait for an @@ -150,7 +154,7 @@ * * * - * Last reviewed on 2006-03-07 (0.10.4) + * Last reviewed on 2006-03-31 (0.10.5) * * */ diff --git a/libs/gst/base/gstbasesrc.h b/libs/gst/base/gstbasesrc.h index 9a5ef4d959..0d0e0a2a6f 100644 --- a/libs/gst/base/gstbasesrc.h +++ b/libs/gst/base/gstbasesrc.h @@ -117,8 +117,31 @@ struct _GstBaseSrc { /** * GstBaseSrcClass: - * @create: ask the subclass to create a buffer with offset and size - * @start: start processing + * @parent_class: Element parent class + * @get_caps: Called to get the caps to report + * @set_caps: Notify subclass of changed output caps + * @negotiate: Negotiated the caps with the peer. + * @newsegment: Generate and send a new_segment event. + * @start: Start processing. Subclasses should open resources and prepare + * to produce data. + * @stop: Stop processing. Subclasses should use this to close resources. + * @get_times: Given a buffer, return the start and stop time when it + * should be pushed out. The base class will sync on the clock using + * these times. + * @get_size: Return the total size of the resource, in the configured format. + * @is_seekable: Check if the source can seek + * @unlock: Unlock any pending access to the resource. Subclasses should + * unblock any blocked function ASAP + * @event: Override this to implement custom event handling. + * @create: Ask the subclass to create a buffer with offset and size. + * @do_seek: Perform seeking on the resource to the indicated segment. + * @query: Handle a requested query. + * @check_get_range: Check whether the source would support pull-based + * operation if it were to be opened now. This vfunc is optional, but + * should be implemented if possible to avoid unnecessary start/stop + * cycles. The default implementation will open and close the resource + * to find out whether get_range is supported, and that is usually + * undesirable. */ struct _GstBaseSrcClass { GstElementClass parent_class;