gnomemm r1477 - in gstreamermm/trunk: . gstreamer/src
- From: jaalburqu svn gnome org
- To: svn-commits-list gnome org
- Subject: gnomemm r1477 - in gstreamermm/trunk: . gstreamer/src
- Date: Fri, 25 Apr 2008 04:59:16 +0100 (BST)
Author: jaalburqu
Date: Fri Apr 25 03:59:15 2008
New Revision: 1477
URL: http://svn.gnome.org/viewvc/gnomemm?rev=1477&view=rev
Log:
2008-04-24 Josà Alburquerque <jaalburqu svn gnome org>
* gstreamer/src/bin.hg: Made list of Gst::MessageTypes and
Gst::QueryTypes in class docs appear as an actual list (in html)
* gstreamer/src/clock.hg: Added docs for functions not member of
classes
* gstreamer/src/error.hg: Added class docs for GErrors
* gstreamer/src/event.ccg:
* gstreamer/src/event.hg: Added docs for Event classes and
handwritten class methods; Removed EventCustom because extending
GstEvents would probably be best done in C API for now
* gstreamer/src/format.ccg:
* gstreamer/src/format.hg: Added docs for FormatDefinition structure;
Added function docs for Gst::Format functions
Modified:
gstreamermm/trunk/ChangeLog
gstreamermm/trunk/gstreamer/src/bin.hg
gstreamermm/trunk/gstreamer/src/clock.hg
gstreamermm/trunk/gstreamer/src/error.hg
gstreamermm/trunk/gstreamer/src/event.ccg
gstreamermm/trunk/gstreamer/src/event.hg
gstreamermm/trunk/gstreamer/src/format.ccg
gstreamermm/trunk/gstreamer/src/format.hg
Modified: gstreamermm/trunk/gstreamer/src/bin.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/bin.hg (original)
+++ gstreamermm/trunk/gstreamer/src/bin.hg Fri Apr 25 03:59:15 2008
@@ -62,24 +62,24 @@
* A Gst::Bin internally intercepts every Gst::Message posted by its children
* and implements the following default behaviour for each of them:
*
- * Gst::MESSAGE_EOS - This message is only posted by sinks in the PLAYING
+ * - Gst::MESSAGE_EOS - This message is only posted by sinks in the PLAYING
* state. If all sinks posted the EOS message, this bin will post and EOS
* message upwards.
*
- * Gst::MESSAGE_SEGMENT_START - just collected and never forwarded upwards. The
- * messages are used to decide when all elements have completed playback of
+ * - Gst::MESSAGE_SEGMENT_START - just collected and never forwarded upwards.
+ * The messages are used to decide when all elements have completed playback of
* their segment.
*
- * Gst::MESSAGE_SEGMENT_DONE - Is posted by Gst::Bin when all elements that
+ * - Gst::MESSAGE_SEGMENT_DONE - Is posted by Gst::Bin when all elements that
* posted a SEGMENT_START have posted a SEGMENT_DONE.
*
- * Gst::MESSAGE_DURATION - Is posted by an element that detected a change in
+ * - Gst::MESSAGE_DURATION - Is posted by an element that detected a change in
* the stream duration. The default bin behaviour is to clear any cached
* duration values so that the next duration query will perform a full duration
* recalculation. The duration change is posted to the application so that it
* can refetch the new duration with a duration query.
*
- * Gst::MESSAGE_CLOCK_LOST - This message is posted by an element when it can
+ * - Gst::MESSAGE_CLOCK_LOST - This message is posted by an element when it can
* no longer provide a clock. The default bin behaviour is to check if the lost
* clock was the one provided by the bin. If so and the bin is currently in the
* PLAYING state, the message is forwarded to the bin parent. This message is
@@ -87,30 +87,30 @@
* message is received by the application, it should PAUSE the pipeline and set
* it back to PLAYING to force a new clock distribution.
*
- * Gst::MESSAGE_CLOCK_PROVIDE - This message is generated when an element can
+ * - Gst::MESSAGE_CLOCK_PROVIDE - This message is generated when an element can
* provide a clock. This mostly happens when a new clock provider is added to
* the bin. The default behaviour of the bin is to mark the currently selected
* clock as dirty, which will perform a clock recalculation the next time the
* bin is asked to provide a clock. This message is never sent tot the
* application but is forwarded to the parent of the bin.
*
- * OTHERS - posted upwards.
+ * - OTHERS - posted upwards.
* A Gst::Bin implements the following default behaviour for answering to a
* Gst::Query:
*
- * Gst::QUERY_DURATION - If the query has been asked before with the same
+ * - Gst::QUERY_DURATION - If the query has been asked before with the same
* format and the bin is a toplevel bin (ie. has no parent), use the cached
* previous value. If no previous value was cached, the query is sent to all
* sink elements in the bin and the MAXIMUM of all values is returned. If the
* bin is a toplevel bin the value is cached. If no sinks are available in the
* bin, the query fails.
*
- * Gst::QUERY_POSITION - The query is sent to all sink elements in the bin and
- * the MAXIMUM of all values is returned. If no sinks are available in the bin,
- * the query fails.
+ * - Gst::QUERY_POSITION - The query is sent to all sink elements in the bin
+ * and the MAXIMUM of all values is returned. If no sinks are available in the
+ * bin, the query fails.
*
- * OTHERS - the query is forwarded to all sink elements, the result of the
+ * - OTHERS - the query is forwarded to all sink elements, the result of the
* first sink that answers the query successfully is returned. If no sink is in
* the bin, the query fails.
*
Modified: gstreamermm/trunk/gstreamer/src/clock.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/clock.hg (original)
+++ gstreamermm/trunk/gstreamer/src/clock.hg Fri Apr 25 03:59:15 2008
@@ -69,14 +69,46 @@
_WRAP_METHOD(void unschedule(), gst_clock_id_unschedule)
};
-//Note that ClockTime is an enum. That's why these are not member functions of a class
-
+/** Get hour component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the hour component of the Gst::ClockTime
+ */
guint get_hours(ClockTime time);
+
+/** Get minute component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the minute component of the Gst::ClockTime
+ */
guint get_minutes(ClockTime time);
+
+/** Get seconds component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the seconds component of the Gst::ClockTime
+ */
guint get_seconds(ClockTime time);
+
+/** Get milliseconds component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the milliseconds component of the Gst::ClockTime
+ */
guint get_milliseconds(ClockTime time);
+
+/** Get microseconds component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the microseconds component of the Gst::ClockTime
+ */
guint get_microseconds(ClockTime time);
+
+/** Get nanoseconds component of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the nanoseconds component of the Gst::ClockTime
+ */
guint get_nanoseconds(ClockTime time);
+
+/** Get fractional component (milli, micro and nano seconds) of Gst::ClockTime.
+ * @param time the Gst::ClockTime to parse
+ * @return the fractional component of the Gst::ClockTime
+ */
guint get_fractional_seconds(ClockTime time);
/** Gst::Clock â Abstract class for global clocks.
Modified: gstreamermm/trunk/gstreamer/src/error.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/error.hg (original)
+++ gstreamermm/trunk/gstreamer/src/error.hg Fri Apr 25 03:59:15 2008
@@ -24,10 +24,221 @@
namespace Gst
{
- _WRAP_GERROR(CoreError, GstCoreError, GST_CORE_ERROR, NO_GTYPE)
- _WRAP_GERROR(LibraryError, GstLibraryError, GST_LIBRARY_ERROR, NO_GTYPE)
- _WRAP_GERROR(ResourceError, GstResourceError, GST_RESOURCE_ERROR, NO_GTYPE)
- _WRAP_GERROR(StreamError, GstStreamError, GST_STREAM_ERROR, NO_GTYPE)
+/** GStreamer elements can throw non-fatal warnings and fatal errors.
+ * Higher-level elements and applications can programatically filter the ones
+ * they are interested in or can recover from, and have a default handler
+ * handle the rest of them. Both warnings and fatal errors are treated
+ * similarly.
+ *
+ * Core errors are errors inside the core GStreamer library:
+ *
+ * - FAILED - a general error which doesn't fit in any other category. Make
+ * sure you add a custom message to the error call.
+ * - TOO_LAZY - do not use this except as a placeholder for deciding where to
+ * go while developing code.
+ * - NOT_IMPLEMENTED - use this when you do not want to implement this
+ * functionality yet.
+ * - STATE_CHANGE - used for state change errors.
+ * - PAD - used for pad-related errors.
+ * - THREAD - used for thread-related errors.
+ * - NEGOTIATION - used for negotiation-related errors.
+ * - EVENT - used for event-related errors.
+ * - SEEK - used for seek-related errors.
+ * - CAPS - used for caps-related errors.
+ * - TAG - used for negotiation-related errors.
+ * - MISSING_PLUGIN - used if a plugin is missing.
+ * - CLOCK - used for clock related errors.
+ * - DISABLED - used if functionality has been disabled at compile time (Since:
+ * 0.10.13).
+ * - NUM_ERRORS - the number of core error types.
+ *
+ * Elements do not have the context required to decide what to do with
+ * errors. As such, they should only inform about errors, and stop their
+ * processing. In short, an element doesn't know what it is being used for.
+ *
+ * It is the application or compound element using the given element that has
+ * more context about the use of the element. Errors can be received by
+ * listening to the Gst::Bus of the element/pipeline for Gst::Message objects
+ * with the type Gst::MESSAGE_ERROR or Gst::MESSAGE_WARNING. The thrown
+ * errors should be inspected, and filtered if appropriate.
+ *
+ * An application is expected to, by default, present the user with a dialog
+ * box (or an equivalent) showing the error message. The dialog should also
+ * allow a way to get at the additional debug information, so the user can
+ * provide bug reporting information.
+ *
+ * A compound element is expected to forward errors by default higher up the
+ * hierarchy; this is done by default in the same way as for other types of
+ * Gst::Message.
+ *
+ * When applications or compound elements trigger errors that they can
+ * recover from, they can filter out these errors and take appropriate
+ * action. For example, an application that gets an error from xvimagesink
+ * that indicates all XVideo ports are taken, the application can attempt to
+ * use another sink instead.
+ */
+
+_WRAP_GERROR(CoreError, GstCoreError, GST_CORE_ERROR, NO_GTYPE)
+
+/** GStreamer elements can throw non-fatal warnings and fatal errors.
+ * Higher-level elements and applications can programatically filter the ones
+ * they are interested in or can recover from, and have a default handler
+ * handle the rest of them. Both warnings and fatal errors are treated
+ * similarly.
+ *
+ * Library errors are for errors from the library being used by elements
+ * (initializing, finalizing, settings, ...)
+ *
+ * - FAILED - a general error which doesn't fit in any other category. Make
+ * sure you add a custom message to the error call.
+ * - TOO_LAZY - do not use this except as a placeholder for deciding where to
+ * go while developing code.
+ * - INIT - used when the library could not be opened.
+ * - SHUTDOWN - used when the library could not be closed.
+ * - SETTINGS - used when the library doesn't accept settings.
+ * - ENCODE - used when the library generated an encoding error.
+ * - NUM_ERRORS - the number of library error types.
+ *
+ * Elements do not have the context required to decide what to do with
+ * errors. As such, they should only inform about errors, and stop their
+ * processing. In short, an element doesn't know what it is being used for.
+ *
+ * It is the application or compound element using the given element that has
+ * more context about the use of the element. Errors can be received by
+ * listening to the Gst::Bus of the element/pipeline for Gst::Message objects
+ * with the type Gst::MESSAGE_ERROR or Gst::MESSAGE_WARNING. The thrown
+ * errors should be inspected, and filtered if appropriate.
+ *
+ * An application is expected to, by default, present the user with a dialog
+ * box (or an equivalent) showing the error message. The dialog should also
+ * allow a way to get at the additional debug information, so the user can
+ * provide bug reporting information.
+ *
+ * A compound element is expected to forward errors by default higher up the
+ * hierarchy; this is done by default in the same way as for other types of
+ * Gst::Message.
+ *
+ * When applications or compound elements trigger errors that they can
+ * recover from, they can filter out these errors and take appropriate
+ * action. For example, an application that gets an error from xvimagesink
+ * that indicates all XVideo ports are taken, the application can attempt to
+ * use another sink instead.
+ */
+_WRAP_GERROR(LibraryError, GstLibraryError, GST_LIBRARY_ERROR, NO_GTYPE)
+
+/** GStreamer elements can throw non-fatal warnings and fatal errors.
+ * Higher-level elements and applications can programatically filter the ones
+ * they are interested in or can recover from, and have a default handler
+ * handle the rest of them. Both warnings and fatal errors are treated
+ * similarly.
+ *
+ * Resource errors are for any resource used by an element: memory, files,
+ * network connections, process space, ... They're typically used by source and
+ * sink elements.
+ *
+ * - FAILED - a general error which doesn't fit in any other category. Make
+ * sure you add a custom message to the error call.
+ * - TOO_LAZY - do not use this except as a placeholder for deciding where to
+ * go while developing code.
+ * - NOT_FOUND - used when the resource could not be found.
+ * - BUSY - used when resource is busy.
+ * - OPEN_READ - used when resource fails to open for reading.
+ * - OPEN_WRITE - used when resource fails to open for writing.
+ * - OPEN_READ_WRITE - used when resource cannot be opened for both reading and
+ * writing, or either (but unspecified which).
+ * - CLOSE - used when the resource can't be closed.
+ * - READ - used when the resource can't be read from.
+ * - WRITE - used when the resource can't be written to.
+ * - SEEK - used when a seek on the resource fails.
+ * - SYNC - used when a synchronize on the resource fails.
+ * - SETTINGS - used when settings can't be manipulated on.
+ * - NO_SPACE_LEFT - used when the resource has no space left.
+ * - NUM_ERRORS - the number of resource error types.
+ *
+ * Elements do not have the context required to decide what to do with
+ * errors. As such, they should only inform about errors, and stop their
+ * processing. In short, an element doesn't know what it is being used for.
+ *
+ * It is the application or compound element using the given element that has
+ * more context about the use of the element. Errors can be received by
+ * listening to the Gst::Bus of the element/pipeline for Gst::Message objects
+ * with the type Gst::MESSAGE_ERROR or Gst::MESSAGE_WARNING. The thrown
+ * errors should be inspected, and filtered if appropriate.
+ *
+ * An application is expected to, by default, present the user with a dialog
+ * box (or an equivalent) showing the error message. The dialog should also
+ * allow a way to get at the additional debug information, so the user can
+ * provide bug reporting information.
+ *
+ * A compound element is expected to forward errors by default higher up the
+ * hierarchy; this is done by default in the same way as for other types of
+ * Gst::Message.
+ *
+ * When applications or compound elements trigger errors that they can
+ * recover from, they can filter out these errors and take appropriate
+ * action. For example, an application that gets an error from xvimagesink
+ * that indicates all XVideo ports are taken, the application can attempt to
+ * use another sink instead.
+ */
+_WRAP_GERROR(ResourceError, GstResourceError, GST_RESOURCE_ERROR, NO_GTYPE)
+
+/** GStreamer elements can throw non-fatal warnings and fatal errors.
+ * Higher-level elements and applications can programatically filter the ones
+ * they are interested in or can recover from, and have a default handler
+ * handle the rest of them. Both warnings and fatal errors are treated
+ * similarly.
+ *
+ * Stream errors are for anything related to the stream being processed: format
+ * errors, media type errors, ... They're typically used by decoders, demuxers,
+ * converters, ...
+ *
+ * - FAILED - a general error which doesn't fit in any other category. Make
+ * sure you add a custom message to the error call.
+ * - TOO_LAZY - do not use this except as a placeholder for deciding where to
+ * go while developing code.
+ * - NOT_IMPLEMENTED - use this when you do not want to implement this
+ * functionality yet.
+ * - TYPE_NOT_FOUND - used when the element doesn't know the stream's type.
+ * - WRONG_TYPE - used when the element doesn't handle this type of stream.
+ * - CODEC_NOT_FOUND - used when there's no codec to handle the stream's type.
+ * - DECODE - used when decoding fails.
+ * - ENCODE - used when encoding fails.
+ * - DEMUX - used when demuxing fails.
+ * - MUX - used when muxing fails.
+ * - FORMAT - used when the stream is of the wrong format (for example, wrong
+ * caps).
+ * - DECRYPT - used when the stream is encrypted and can't be decrypted because
+ * this is not supported by the element. (Since: 0.10.20)
+ * - DECRYPT_NOKEY - used when the stream is encrypted and can't be decrypted
+ * because no suitable key is available. (Since: 0.10.20)
+ * - NUM_ERRORS - the number of stream error types.
+ *
+ * Elements do not have the context required to decide what to do with
+ * errors. As such, they should only inform about errors, and stop their
+ * processing. In short, an element doesn't know what it is being used for.
+ *
+ * It is the application or compound element using the given element that has
+ * more context about the use of the element. Errors can be received by
+ * listening to the Gst::Bus of the element/pipeline for Gst::Message objects
+ * with the type Gst::MESSAGE_ERROR or Gst::MESSAGE_WARNING. The thrown
+ * errors should be inspected, and filtered if appropriate.
+ *
+ * An application is expected to, by default, present the user with a dialog
+ * box (or an equivalent) showing the error message. The dialog should also
+ * allow a way to get at the additional debug information, so the user can
+ * provide bug reporting information.
+ *
+ * A compound element is expected to forward errors by default higher up the
+ * hierarchy; this is done by default in the same way as for other types of
+ * Gst::Message.
+ *
+ * When applications or compound elements trigger errors that they can
+ * recover from, they can filter out these errors and take appropriate
+ * action. For example, an application that gets an error from xvimagesink
+ * that indicates all XVideo ports are taken, the application can attempt to
+ * use another sink instead.
+ */
+_WRAP_GERROR(StreamError, GstStreamError, GST_STREAM_ERROR, NO_GTYPE)
} // namespace Gst
Modified: gstreamermm/trunk/gstreamer/src/event.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/event.ccg (original)
+++ gstreamermm/trunk/gstreamer/src/event.ccg Fri Apr 25 03:59:15 2008
@@ -78,17 +78,6 @@
async = result;
}
-EventCustom::EventCustom(GstEvent* castitem) :
-Event(castitem)
-{
-}
-
-Glib::RefPtr<Event> EventCustom::create(EventType type, Structure& structure)
-{
- GstEvent* event = gst_event_new_custom(GstEventType(type), structure.gobj());
- return Gst::Event::wrap(event, false);
-}
-
EventEos::EventEos(GstEvent* castitem) :
Event(castitem)
{
@@ -257,13 +246,6 @@
case GST_EVENT_LATENCY:
result = Glib::RefPtr<Event>( new Gst::EventLatency(event) );
break;
- case GST_EVENT_CUSTOM_UPSTREAM:
- case GST_EVENT_CUSTOM_DOWNSTREAM:
- case GST_EVENT_CUSTOM_DOWNSTREAM_OOB:
- case GST_EVENT_CUSTOM_BOTH:
- case GST_EVENT_CUSTOM_BOTH_OOB:
- result = Glib::RefPtr<Event>( new Gst::EventCustom(event) );
- break;
default:
result = Gst::wrap(event, false);
}
Modified: gstreamermm/trunk/gstreamer/src/event.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/event.hg (original)
+++ gstreamermm/trunk/gstreamer/src/event.hg Fri Apr 25 03:59:15 2008
@@ -98,12 +98,6 @@
_CLASS_GSTMINIOBJECT(Event, GstEvent, GST_EVENT, Gst::MiniObject, GstMiniObject)
public:
- /** Get the structure of an event.
- * @return The Gst::Structure of the event (unmodifiable)
- */
- const Structure* get_structure();
-
-public:
/** Wrap a GstEvent* in a C++ instance, creating an instance of a derived
* Gst::Event. Gst::wrap() would just create a Gst::Event (rather than a
* derived one) because the derived Gst::Event classes do not correspond
@@ -111,101 +105,383 @@
*/
static Glib::RefPtr<Event> wrap(GstEvent* event, bool take_copy=false);
+ /** Get the structure of an event.
+ * @return The Gst::Structure of the event (unmodifiable)
+ */
+ const Structure* get_structure();
+
+ /** Check if an event can travel downstream.
+ */
bool is_downstream() const;
- bool is_upstream() const;
+
+ /** Check if an event is serialized with the data stream.
+ */
bool is_serialized() const;
+ /** Check if an event can travel upstream.
+ */
+ bool is_upstream() const;
+
+ /** Get the Gst::EventType of the event.
+ */
_MEMBER_GET(event_type, type, EventType, GstEventType)
+
+ /** Get the Gst::ClockTime timestamp of the event. This is the time when the
+ * event was created.
+ */
_MEMBER_GET(timestamp, timestamp, ClockTime, guint64)
+
+ /** The source Gst::Object that generated this event.
+ */
_MEMBER_GET_GOBJECT(source, src, Gst::Object, GstObject*)
};
+/** A buffer size event.
+ */
class EventBufferSize : public Event
{
public:
explicit EventBufferSize(GstEvent* event);
+ /** Create a new buffersize event. The event is sent downstream and notifies
+ * elements that they should provide a buffer of the specified dimensions.
+ *
+ * When the async flag is set, a thread boundary is prefered.
+ *
+ * @param format buffer format
+ * @param minsize minimum buffer size
+ * @param maxsize maximum buffer size
+ * @param async thread behavior
+ * @return a new Gst::EventBufferSize
+ */
static Glib::RefPtr<Event> create(Format format, gint64 minsize, gint64 maxsize, bool async);
- void parse(Format& format, gint64& minsize, gint64& maxsize, bool& async);
-};
-
-class EventCustom : public Event
-{
-public:
- explicit EventCustom(GstEvent* event);
- static Glib::RefPtr<Event> create(EventType type, Structure& structure);
+ /** Get the format, minsize, maxsize and async-flag in the buffersize event.
+ *
+ * @param format A pointer to store the format in
+ * @param minsize A pointer to store the minsize in
+ * @param maxsize A pointer to store the maxsize in
+ * @param async A pointer to store the async-flag in
+ */
+ void parse(Format& format, gint64& minsize, gint64& maxsize, bool& async);
};
+/** An end of stream event.
+ */
class EventEos : public Event
{
public:
explicit EventEos(GstEvent* event);
+ /** Create a new EOS event. The eos event can only travel downstream
+ * synchronized with the buffer flow. Elements that receive the EOS event on
+ * a pad can return Gst::FLOW_UNEXPECTED as a Gst::FlowReturn when data after
+ * the EOS event arrives.
+ *
+ * The EOS event will travel down to the sink elements in the pipeline which
+ * will then post the Gst::MESSAGE_EOS on the bus after they have finished
+ * playing any buffered data.
+ *
+ * When all sinks have posted an EOS message, an EOS message is forwarded to
+ * the application.
+ *
+ * @return The new EOS event.
+ */
static Glib::RefPtr<Event> create();
};
+/** A flush start event.
+ */
class EventFlushStart : public Event
{
public:
explicit EventFlushStart(GstEvent* event);
+ /** Allocate a new flush start event. The flush start event can be sent
+ * upstream and downstream and travels out-of-bounds with the dataflow.
+ *
+ * It marks pads as being flushing and will make them return
+ * Gst::FLOW_WRONG_STATE when used for data flow with Gst::Pad::push(),
+ * Gst::Pad::chain(), Gst::Pad::alloc_buffer(), Gst::Pad::get_range() and
+ * Gst::Pad::pull_range(). Any event (except a Gst::EVENT_FLUSH_STOP)
+ * received on a flushing pad will return FALSE immediately.
+ *
+ * Elements should unlock any blocking functions and exit their streaming
+ * functions as fast as possible when this event is received.
+ *
+ * This event is typically generated after a seek to flush out all queued
+ * data in the pipeline so that the new media is played as soon as possible.
+ *
+ * @return A new flush start event.
+ */
static Glib::RefPtr<Event> create();
};
+/** A flush stop event.
+ */
class EventFlushStop : public Event
{
public:
explicit EventFlushStop(GstEvent* event);
+ /** Allocate a new flush stop event. The flush stop event can be sent
+ * upstream and downstream and travels out-of-bounds with the dataflow. It is
+ * typically sent after sending a Gst::EventFlushStart event to make the pads
+ * accept data again.
+ *
+ * Elements can process this event synchronized with the dataflow since the
+ * preceeding Gst::EventFlushStart event stopped the dataflow.
+ *
+ * This event is typically generated to complete a seek and to resume
+ * dataflow.
+ *
+ * @return A new flush stop event.
+ */
static Glib::RefPtr<Event> create();
};
+/** A latency event.
+ */
class EventLatency : public Event
{
public:
explicit EventLatency(GstEvent* event);
- static Glib::RefPtr<Event> create(ClockTime time);
+ /** Create a new latency event. The event is sent upstream from the sinks and
+ * notifies elements that they should add an additional latency to the
+ * timestamps before synchronising against the clock.
+ *
+ * The latency is mostly used in live sinks and is always expressed in the
+ * time format.
+ *
+ * @param latency the new latency value
+ * @return a new Gst::EventLatency
+ *
+ * Since 0.10.12
+ */
+ static Glib::RefPtr<Event> create(ClockTime latency);
+
+ /** Get the latency in the latency event.
+ *
+ * @param latency A pointer to store the latency in.
+ */
void parse(ClockTime& latency);
};
+/** A Navigation event.
+ */
class EventNavigation : public Event
{
public:
explicit EventNavigation(GstEvent* event);
+ /** Create a new navigation event from the given description.
+ *
+ * @param structure description of the event
+ * @return a new Gst::EventNavigation
+ */
static Glib::RefPtr<Event> create(Structure& structure);
};
+/** A new segment event.
+ */
class EventNewSegment : public Event
{
public:
explicit EventNewSegment(GstEvent* event);
+ /** Allocate a new newsegment event with the given format/values tripplets
+ *
+ * The newsegment event marks the range of buffers to be processed. All data
+ * not within the segment range is not to be processed. This can be used
+ * intelligently by plugins to apply more efficient methods of skipping
+ * unneeded data.
+ *
+ * The position value of the segment is used in conjunction with the start
+ * value to convert the buffer timestamps into the stream time. This is
+ * usually done in sinks to report the current stream_time. position
+ * represents the stream_time of a buffer carrying a timestamp of start.
+ * position cannot be -1.
+ *
+ * start cannot be -1, stop can be -1. If there is a valid stop given, it
+ * must be greater or equal the start, including when the indicated playback
+ * rate is < 0.
+ *
+ * The applied_rate value provides information about any rate adjustment that
+ * has already been made to the timestamps and content on the buffers of the
+ * stream. (rate * applied_rate) should always equal the rate that has been
+ * requested for playback. For example, if an element has an input segment
+ * with intended playback rate of 2.0 and applied_rate of 1.0, it can adjust
+ * incoming timestamps and buffer content by half and output a newsegment
+ * event with rate of 1.0 and applied_rate of 2.0
+ *
+ * After a newsegment event, the buffer stream time is calculated with:
+ *
+ * position + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate)
+ *
+ * @param update is this segment an update to a previous one
+ * @param rate a new rate for playback
+ * @param format The format of the segment values
+ * @param start the start value of the segment
+ * @param stop the stop value of the segment
+ * @param position stream position
+ * @param applied_rate The rate factor which has already been applied
+ * @return A new newsegment event.
+ *
+ * Since 0.10.6
+ */
static Glib::RefPtr<Event> create(bool update, double rate, Format format, gint64 strat, gint64 stop, gint64 position, double applied_rate=1.0);
+
+ /** Get the update flag, rate, format, start, stop and position in the
+ * newsegment event.
+ *
+ * @param update A pointer to the update flag of the segment
+ * @param rate A pointer to the rate of the segment
+ * @param format A pointer to the format of the newsegment values
+ * @param start A pointer to store the start value in
+ * @param stop A pointer to store the stop value in
+ * @param position A pointer to store the stream time in
+ */
void parse(bool& update, double& rate, Format& format, gint64& start, gint64& stop, gint64& position);
+
+ /** Get the update, rate, applied_rate, format, start, stop and position in
+ * the newsegment event. See create() for a full description of the
+ * newsegment event.
+ *
+ * @param update A pointer to the update flag of the segment
+ * @param rate A pointer to the rate of the segment
+ * @param format A pointer to the format of the newsegment values
+ * @param start A pointer to store the start value in
+ * @param stop A pointer to store the stop value in
+ * @param position A pointer to store the stream time in
+ * @param applied_rate A pointer to the applied_rate of the segment
+ *
+ * Since 0.10.6
+ */
void parse(bool& update, double& rate, Format& format, gint64& start, gint64& stop, gint64& position, double& applied_rate);
};
+/** A QOS Event.
+ */
class EventQos : public Event
{
public:
explicit EventQos(GstEvent* event);
+ /** Allocate a new qos event with the given values. The QOS event is
+ * generated in an element that wants an upstream element to either reduce or
+ * increase its rate because of high/low CPU load or other resource usage
+ * such as network performance. Typically sinks generate these events for
+ * each buffer they receive.
+ *
+ * proportion indicates the real-time performance of the streaming in the
+ * element that generated the QoS event (usually the sink). The value is
+ * generally computed based on more long term statistics about the streams
+ * timestamps compared to the clock. A value < 1.0 indicates that the
+ * upstream element is producing data faster than real-time. A value > 1.0
+ * indicates that the upstream element is not producing data fast enough. 1.0
+ * is the ideal proportion value. The proportion value can safely be used to
+ * lower or increase the quality of the element.
+ *
+ * diff is the difference against the clock in running time of the last
+ * buffer that caused the element to generate the QOS event. A negative value
+ * means that the buffer with timestamp arrived in time. A positive value
+ * indicates how late the buffer with timestamp was.
+ *
+ * timestamp is the timestamp of the last buffer that cause the element to
+ * generate the QOS event. It is expressed in running time and thus an ever
+ * increasing value.
+ *
+ * The upstream element can use the diff and timestamp values to decide
+ * whether to process more buffers. For possitive diff, all buffers with
+ * timestamp <= timestamp + diff will certainly arrive late in the sink as
+ * well.
+ *
+ * The application can use general event probes to intercept the QoS event
+ * and implement custom application specific QoS handling.
+ *
+ * @param proportion the proportion of the qos message
+ * @param diff The time difference of the last clock sync
+ * @param timestamp The timestamp of the buffer
+ * @return A new QOS event.
+ */
static Glib::RefPtr<Event> create(double proportion, ClockTimeDiff diff, ClockTime timestamp);
+
+ /** Get the proportion, diff and timestamp in the qos event. See create() for
+ * more information about the different QoS values.
+ *
+ * @param proportion A pointer to store the proportion in
+ * @param diff A pointer to store the diff in
+ * @param timestamp A pointer to store the timestamp in
+ */
void parse(double& proportion, ClockTimeDiff& diff, ClockTime& timestamp);
};
+/** A seek event.
+ */
class EventSeek : public Event
{
public:
explicit EventSeek(GstEvent* event);
+ /** Allocate a new seek event with the given parameters.
+ *
+ * The seek event configures playback of the pipeline between start to stop
+ * at the speed given in rate, also called a playback segment. The start and
+ * stop values are expressed in format.
+ *
+ * A rate of 1.0 means normal playback rate, 2.0 means double speed.
+ * Negatives values means backwards playback. A value of 0.0 for the rate is
+ * not allowed and should be accomplished instead by PAUSING the pipeline.
+ *
+ * A pipeline has a default playback segment configured with a start position
+ * of 0, a stop position of -1 and a rate of 1.0. The currently configured
+ * playback segment can be queried with Gst::QUERY_SEGMENT.
+ *
+ * start_type and stop_type specify how to adjust the currently configured
+ * start and stop fields in segment. Adjustments can be made relative or
+ * absolute to the last configured values. A type of Gst::SEEK_TYPE_NONE
+ * means that the position should not be updated.
+ *
+ * When the rate is positive and start has been updated, playback will start
+ * from the newly configured start position.
+ *
+ * For negative rates, playback will start from the newly configured stop
+ * position (if any). If the stop position if updated, it must be different
+ * from -1 for negative rates.
+ *
+ * It is not possible to seek relative to the current playback position, to
+ * do this, PAUSE the pipeline, query the current playback position with
+ * Gst::QUERY_POSITION and update the playback segment current position with
+ * a Gst::SEEK_TYPE_SET to the desired position.
+ *
+ * @param rate The new playback rate
+ * @param format The format of the seek values
+ * @param flags The optional seek flags
+ * @param start_type The type and flags for the new start position
+ * @param start The value of the new start position
+ * @param stop_type The type and flags for the new stop position
+ * @param stop The value of the new stop position
+ * @return A new seek event.
+ */
static Glib::RefPtr<Event> create(double rate, Format format, SeekFlags flags, SeekType start_type, gint64 start, SeekType stop_type, gint64 stop);
+
+ /** Parses a seek event and stores the results in the given result locations.
+ *
+ * @param rate result location for the rate
+ * @param format result location for the stream format
+ * @param flags result location for the Gst::SeekFlags
+ * @param start_type result location for the Gst::SeekType of the start
+ * position
+ * @param start result location for the start postion expressed in format
+ * @param stop_type result location for the Gst::SeekType of the stop position
+ * @param stop result location for the stop postion expressed in format
+ */
void parse(double& rate, Format& format, SeekFlags& flags, SeekType& start_type, gint64& start, SeekType& stop_type, gint64& stop);
};
+/** A tag event.
+ */
class EventTag : public Event
{
public:
Modified: gstreamermm/trunk/gstreamer/src/format.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/format.ccg (original)
+++ gstreamermm/trunk/gstreamer/src/format.ccg Fri Apr 25 03:59:15 2008
@@ -34,6 +34,8 @@
return Glib::QueryQuark(gst_format_to_quark(GstFormat(f)));
}
+//TODO: should gst_format_register() be wrapped? It seems like it would be
+//TODO: extending GStreamer which may be best done with C API directly
Format register_format(const Glib::ustring& nick, const Glib::ustring& description)
{
return Format(gst_format_register(nick.c_str(), description.c_str()));
Modified: gstreamermm/trunk/gstreamer/src/format.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/format.hg (original)
+++ gstreamermm/trunk/gstreamer/src/format.hg Fri Apr 25 03:59:15 2008
@@ -28,25 +28,62 @@
_WRAP_ENUM(Format, GstFormat)
+/** A format definition is used to get details of a Gst::Format by
+ * Gst::get_details().
+ */
struct FormatDefinition
{
- Format value;
+ /// The unique id of this format
+ Gst::Format value;
+ /// A short nick of the format
Glib::ustring nick;
+ /// A longer description of the format
Glib::ustring description;
+ /// A quark for the nick
Glib::QueryQuark quark;
};
+/** Get a printable name for the given format. Do not modify or free.
+ *
+ * @param format a Gst::Format
+ * @return the name of the format or NULL if the format is unknow
+ */
Glib::ustring get_name(Format f);
-Glib::QueryQuark get_quark(Format f);
-//Note that GstFormat is an enum. That's why these are not member functions of a class.
+/** Get the unique quark for the given format.
+ *
+ * @param format a Gst::Format
+ * @return the quark associated with the format or 0 if the format is unknown.
+ */
+Glib::QueryQuark get_quark(Format f);
+/** Create a new Gst::Format based on the nick or return an already registered
+ * format with that nick.
+ *
+ * @param nick The nick of the new format
+ * @param description The description of the new format
+ * @return A new Gst::Format or an already registered format with the same
+ * nick. MT safe.
+ */
Format register_format(const Glib::ustring& nick, const Glib::ustring&description);
+
+/** Return the format registered with the given nick.
+ *
+ * @param nick The nick of the format
+ * @return The format with nick or Gst::FORMAT_UNDEFINED if the format was not
+ * registered.
+ */
Format get_format(const Glib::ustring& nick);
//TODO: first arg is an array of Formats
//TODO: bool formats_contain_format(const Format& formats, Format format);
+/** Get details about the given format.
+ *
+ * @param format The format to get details of
+ * @param The Gst::FormatDefinition in which to store details of format.
+ * @return true if successful, false otherwise. MT safe.
+ */
bool get_details(Format format, FormatDefinition& def);
} //namespace Gst
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
