GstEvent

GstEvent — Structure describing events that are passed up and down a pipeline

Synopsis


#include <gst/gst.h>


            GstEvent;
enum        GstEventType;
#define     GST_EVENT_TRACE_NAME
#define     GST_EVENT_TYPE                  (event)
#define     GST_EVENT_TIMESTAMP             (event)
#define     GST_EVENT_SRC                   (event)
#define     GST_EVENT_IS_DOWNSTREAM         (ev)
#define     GST_EVENT_IS_SERIALIZED         (ev)
#define     GST_EVENT_IS_UPSTREAM           (ev)
enum        GstSeekType;
enum        GstSeekFlags;
#define     GST_EVENT_MAKE_TYPE             (num,flags)
#define     GST_EVDIR_BOTH
#define     GST_EVDIR_DS
#define     GST_EVDIR_US
#define     gst_event_ref                   (ev)
#define     gst_event_unref                 (ev)
#define     gst_event_copy                  (ev)
GstEvent*   gst_event_new_custom            (GstEventType type,
                                             GstStructure *structure);
const GstStructure* gst_event_get_structure (GstEvent *event);
GstEvent*   gst_event_new_flush_start       (void);
GstEvent*   gst_event_new_flush_stop        (void);
GstEvent*   gst_event_new_eos               (void);
GstEvent*   gst_event_new_newsegment        (gdouble rate,
                                             GstFormat format,
                                             gint64 start_value,
                                             gint64 stop_value,
                                             gint64 base);
void        gst_event_parse_newsegment      (GstEvent *event,
                                             gdouble *rate,
                                             GstFormat *format,
                                             gint64 *start_value,
                                             gint64 *stop_value,
                                             gint64 *base);
GstEvent*   gst_event_new_tag               (GstTagList *taglist);
void        gst_event_parse_tag             (GstEvent *event,
                                             GstTagList **taglist);
GstEvent*   gst_event_new_filler            (void);
GstEvent*   gst_event_new_qos               (gdouble proportion,
                                             GstClockTimeDiff diff,
                                             GstClockTime timestamp);
void        gst_event_parse_qos             (GstEvent *event,
                                             gdouble *proportion,
                                             GstClockTimeDiff *diff,
                                             GstClockTime *timestamp);
GstEvent*   gst_event_new_seek              (gdouble rate,
                                             GstFormat format,
                                             GstSeekFlags flags,
                                             GstSeekType cur_type,
                                             gint64 cur,
                                             GstSeekType stop_type,
                                             gint64 stop);
void        gst_event_parse_seek            (GstEvent *event,
                                             gdouble *rate,
                                             GstFormat *format,
                                             GstSeekFlags *flags,
                                             GstSeekType *cur_type,
                                             gint64 *cur,
                                             GstSeekType *stop_type,
                                             gint64 *stop);
GstEvent*   gst_event_new_navigation        (GstStructure *structure);


Description

The event classes are used to construct and query events.

Events are usually created with gst_event_new() which takes the event type as an argument. Properties specific to the event can be set afterwards with the provided macros. The event should be unreferenced with gst_event_unref().

gst_event_new_seek() is a usually used to create a seek event and it takes the needed parameters for a seek event.

gst_event_new_flush() creates a new flush event.

Details

GstEvent

typedef struct {
  GstMiniObject mini_object;

  GstEventType  type;
  guint64	timestamp;
  GstObject	*src;

  GstStructure	*structure;
} GstEvent;


enum GstEventType

typedef enum {
  GST_EVENT_UNKNOWN		= GST_EVENT_MAKE_TYPE (0, 0),
  /* bidirectional events */
  GST_EVENT_FLUSH_START		= GST_EVENT_MAKE_TYPE (1, GST_EVDIR_BOTH),
  GST_EVENT_FLUSH_STOP		= GST_EVENT_MAKE_TYPE (2, GST_EVDIR_BOTH),
  /* downstream serialized events */
  GST_EVENT_EOS			= GST_EVENT_MAKE_TYPE (3, GST_EVDIR_DS | GST_EVSER),
  GST_EVENT_NEWSEGMENT		= GST_EVENT_MAKE_TYPE (4, GST_EVDIR_DS | GST_EVSER),
  GST_EVENT_TAG			= GST_EVENT_MAKE_TYPE (5, GST_EVDIR_DS | GST_EVSER),
  GST_EVENT_FILLER		= GST_EVENT_MAKE_TYPE (6, GST_EVDIR_DS | GST_EVSER),
  /* upstream events */
  GST_EVENT_QOS			= GST_EVENT_MAKE_TYPE (7, GST_EVDIR_US),
  GST_EVENT_SEEK		= GST_EVENT_MAKE_TYPE (8, GST_EVDIR_US),
  GST_EVENT_NAVIGATION		= GST_EVENT_MAKE_TYPE (9, GST_EVDIR_US),

  /* custom events start here */
  GST_EVENT_CUSTOM_UP		= GST_EVENT_MAKE_TYPE (32, GST_EVDIR_US),
  GST_EVENT_CUSTOM_DS		= GST_EVENT_MAKE_TYPE (32, GST_EVDIR_DS | GST_EVSER),
  GST_EVENT_CUSTOM_DS_OOB	= GST_EVENT_MAKE_TYPE (32, GST_EVDIR_DS),
  GST_EVENT_CUSTOM_BOTH		= GST_EVENT_MAKE_TYPE (32, GST_EVDIR_BOTH | GST_EVSER),
  GST_EVENT_CUSTOM_BOTH_OOB	= GST_EVENT_MAKE_TYPE (32, GST_EVDIR_BOTH)
} GstEventType;

GstEventType lists the standard event types that can be sent in a pipeline.

The custom event types can be used for private messages between elements that can't be expressed using normal GStreamer buffer passing semantics. Custom events carry an arbitrary GstStructure. Specific custom events are distinguished by the name of the structure.

GST_EVENT_UNKNOWN unknown event.
GST_EVENT_FLUSH_START Start a flush operation
GST_EVENT_FLUSH_STOP Stop a flush operation
GST_EVENT_EOS End-Of-Stream. No more data is to be expected to follow without a NEWSEGMENT event.
GST_EVENT_NEWSEGMENT A new media segment follows in the dataflow.
GST_EVENT_TAG A new set of metadata tags has been found in the stream.
GST_EVENT_FILLER Filler for sparse data streams.
GST_EVENT_QOS A quality message. Used to indicate to upstream elements that the downstream elements are being starved of or flooded with data.
GST_EVENT_SEEK A request for a new playback position and rate.
GST_EVENT_NAVIGATION Navigation events are usually used for communicating user requests, such as mouse or keyboard movements, to upstream elements.
GST_EVENT_CUSTOM_UP Upstream custom event
GST_EVENT_CUSTOM_DS Downstream custom event that travels in the data flow.
GST_EVENT_CUSTOM_DS_OOB Custom out-of-band downstream event.
GST_EVENT_CUSTOM_BOTH Custom upstream or downstream event. In-band when travelling downstream.
GST_EVENT_CUSTOM_BOTH_OOB Custom upstream or downstream out-of-band event.

GST_EVENT_TRACE_NAME

#define GST_EVENT_TRACE_NAME	"GstEvent"

The name used for memory allocation tracing


GST_EVENT_TYPE()

#define GST_EVENT_TYPE(event)		(GST_EVENT(event)->type)

Get the event type.

event : the event to query

GST_EVENT_TIMESTAMP()

#define GST_EVENT_TIMESTAMP(event)	(GST_EVENT(event)->timestamp)

Get the timestamp of the event.

event : the event to query

GST_EVENT_SRC()

#define GST_EVENT_SRC(event)		(GST_EVENT(event)->src)

The source object that generated this event.

event : the event to query

GST_EVENT_IS_DOWNSTREAM()

#define GST_EVENT_IS_DOWNSTREAM(ev)	!!(GST_EVENT_TYPE (ev) & GST_EVDIR_DS)

ev :

GST_EVENT_IS_SERIALIZED()

#define GST_EVENT_IS_SERIALIZED(ev)	!!(GST_EVENT_TYPE (ev) & GST_EVSER)

ev :

GST_EVENT_IS_UPSTREAM()

#define GST_EVENT_IS_UPSTREAM(ev)	!!(GST_EVENT_TYPE (ev) & GST_EVDIR_US)

ev :

enum GstSeekType

typedef enum {
  /* one of these */
  GST_SEEK_TYPE_NONE		= 0,
  GST_SEEK_TYPE_CUR		= 1,
  GST_SEEK_TYPE_SET		= 2,
  GST_SEEK_TYPE_END		= 3
} GstSeekType;

The different types of seek events. When constructing a seek event a format, a seek method and optional flags are OR-ed together. The seek event is then inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().

GST_SEEK_TYPE_NONE no change in position is required
GST_SEEK_TYPE_CUR change relative to current position
GST_SEEK_TYPE_SET absolute position is requested
GST_SEEK_TYPE_END relative position to duration is requested

enum GstSeekFlags

typedef enum {
  GST_SEEK_FLAG_NONE		= 0,
  GST_SEEK_FLAG_FLUSH		= (1 << 0),
  GST_SEEK_FLAG_ACCURATE	= (1 << 1),
  GST_SEEK_FLAG_KEY_UNIT	= (1 << 2),
  GST_SEEK_FLAG_SEGMENT		= (1 << 3)
} GstSeekFlags;

GST_SEEK_FLAG_NONE no flag
GST_SEEK_FLAG_FLUSH flush pipeline
GST_SEEK_FLAG_ACCURATE accurate position is requested, this might be slower for some formats.
GST_SEEK_FLAG_KEY_UNIT seek to the nearest keyframe. This might be faster but less accurate.
GST_SEEK_FLAG_SEGMENT perform a segment seek. After the playback of the segment completes, no EOS will be emmited but a SEGMENT_DONE message will be posted on the bus.

GST_EVENT_MAKE_TYPE()

#define GST_EVENT_MAKE_TYPE(num,flags) (((num) << GST_EVSHIFT) | (flags))

num :
flags :

GST_EVDIR_BOTH

#define GST_EVDIR_BOTH	GST_EVDIR_US | GST_EVDIR_DS


GST_EVDIR_DS

#define GST_EVDIR_DS	(1 << 1)	


GST_EVDIR_US

#define GST_EVDIR_US	(1 << 0)	


gst_event_ref()

#define         gst_event_ref(ev)		GST_EVENT (gst_mini_object_ref (GST_MINI_OBJECT (ev)))

Decrease the refcount of an event, freeing it if the refcount reaches 0.

ev : The event to refcount

gst_event_unref()

#define         gst_event_unref(ev)		gst_mini_object_unref (GST_MINI_OBJECT (ev))

ev :

gst_event_copy()

#define         gst_event_copy(ev)		GST_EVENT (gst_mini_object_copy (GST_MINI_OBJECT (ev)))

Copy the event using the event specific copy function.

ev : The event to copy

gst_event_new_custom ()

GstEvent*   gst_event_new_custom            (GstEventType type,
                                             GstStructure *structure);

Create a new custom-typed event. This can be used for anything not handled by other event-specific functions to pass an event to another element.

Make sure to allocate an event type with the GST_EVENT_MAKE_TYPE macro, assigning a free number and filling in the correct direction and serialization flags.

New custom events can also be created by subclassing the event type if needed.

type : The type of the new event
structure : The structure for the event. The event will take ownership of the structure.
Returns : The new custom event.

gst_event_get_structure ()

const GstStructure* gst_event_get_structure (GstEvent *event);

Access the structure of the event.

event : The GstEvent.
Returns : The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. MT safe.

gst_event_new_flush_start ()

GstEvent*   gst_event_new_flush_start       (void);

Allocate a new flush start event. The flush start event can be send upstream and downstream and travels out-of-bounds with the dataflow. It marks pads as being in a WRONG_STATE to process more data.

Elements unlock and blocking functions and exit their streaming functions as fast as possible.

This event is typically generated after a seek to minimize the latency after the seek.

Returns : A new flush start event.

gst_event_new_flush_stop ()

GstEvent*   gst_event_new_flush_stop        (void);

Allocate a new flush stop event. The flush start event can be send upstream and downstream and travels out-of-bounds with the dataflow. It is typically send after sending a FLUSH_START event to make the pads accept data again.

Elements can process this event synchronized with the dataflow since the preceeding FLUSH_START event stopped the dataflow.

This event is typically generated to complete a seek and to resume dataflow.

Returns : A new flush stop event.

gst_event_new_eos ()

GstEvent*   gst_event_new_eos               (void);

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 UNEXPECTED as a GstFlowReturn when data after the EOS event arrives.

The EOS event will travel up to the sink elements in the pipeline which will then post the GST_MESSAGE_EOS on the bus.

When all sinks have posted an EOS message, the EOS message is forwarded to the application.

Returns : The new EOS event.

gst_event_new_newsegment ()

GstEvent*   gst_event_new_newsegment        (gdouble rate,
                                             GstFormat format,
                                             gint64 start_value,
                                             gint64 stop_value,
                                             gint64 base);

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 use more efficient methods of skipping unneeded packets.

The base time of the segment is also used to convert the buffer timestamps into the stream time again.

The start_value cannot be -1, the stop_value can be -1. If there is a valid stop_value given, it must be smaller than start_value.

After a newsegment event, the buffer stream time is calculated with:

TIMESTAMP(buf) - start_time + base

rate : a new rate for playback
format : The format of the segment values
start_value : the start value of the segment
stop_value : the stop value of the segment
base : base value for buffer timestamps.
Returns : A new newsegment event.

gst_event_parse_newsegment ()

void        gst_event_parse_newsegment      (GstEvent *event,
                                             gdouble *rate,
                                             GstFormat *format,
                                             gint64 *start_value,
                                             gint64 *stop_value,
                                             gint64 *base);

Get the start, stop and format in the newsegment event.

event : The event to query
rate : A pointer to the rate of the segment
format : A pointer to the format of the newsegment values
start_value : A pointer to store the start value in
stop_value : A pointer to store the stop value in
base : A pointer to store the base time in

gst_event_new_tag ()

GstEvent*   gst_event_new_tag               (GstTagList *taglist);

Generates a metadata tag event from the given taglist.

taglist : metadata list
Returns : a new GstEvent

gst_event_parse_tag ()

void        gst_event_parse_tag             (GstEvent *event,
                                             GstTagList **taglist);

Parses a tag event and stores the results in the given taglist location.

event : a tag event
taglist : pointer to metadata list

gst_event_new_filler ()

GstEvent*   gst_event_new_filler            (void);

Create a new dummy event that should be ignored.

Returns : a new GstEvent

gst_event_new_qos ()

GstEvent*   gst_event_new_qos               (gdouble proportion,
                                             GstClockTimeDiff diff,
                                             GstClockTime timestamp);

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.

proportion is the requested adjustment in datarate, 1.0 is the normal datarate, 0.75 means increase datarate by 75%, 1.5 is 150%. Negative values request a slow down, so -0.75 means a decrease by 75%.

diff is the difference against the clock in stream time of the last buffer that caused the element to generate the QOS event.

timestamp is the timestamp of the last buffer that cause the element to generate the QOS event.

proportion : the proportion of the qos message
diff : The time difference of the last Clock sync
timestamp : The timestamp of the buffer
Returns : A new QOS event.

gst_event_parse_qos ()

void        gst_event_parse_qos             (GstEvent *event,
                                             gdouble *proportion,
                                             GstClockTimeDiff *diff,
                                             GstClockTime *timestamp);

Get the proportion, diff and timestamp in the qos event.

event : The event to query
proportion : A pointer to store the proportion in
diff : A pointer to store the diff in
timestamp : A pointer to store the timestamp in

gst_event_new_seek ()

GstEvent*   gst_event_new_seek              (gdouble rate,
                                             GstFormat format,
                                             GstSeekFlags flags,
                                             GstSeekType cur_type,
                                             gint64 cur,
                                             GstSeekType stop_type,
                                             gint64 stop);

Allocate a new seek event with the given parameters.

The seek event configures playback of the pipeline from cur to stop at the speed given in rate. The cur and stop values are expressed in format 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.

cur_type and stop_type specify how to adjust the current and stop time, relative or absolute. A type of GST_EVENT_TYPE_NONE means that the position should not be updated.

rate : The new playback rate
format : The format of the seek values
flags : The optional seek flags.
cur_type : The type and flags for the new current position
cur : The value of the new current position
stop_type : The type and flags for the new stop position
stop : The value of the new stop position
Returns : A new seek event.

gst_event_parse_seek ()

void        gst_event_parse_seek            (GstEvent *event,
                                             gdouble *rate,
                                             GstFormat *format,
                                             GstSeekFlags *flags,
                                             GstSeekType *cur_type,
                                             gint64 *cur,
                                             GstSeekType *stop_type,
                                             gint64 *stop);

Parses a seek event and stores the results in the given result locations.

event : a seek event
rate : result location for the rate
format : result location for the stream format
flags : result location for the GstSeekFlags
cur_type : result location for the GstSeekType of the current position
cur : result location for the current postion expressed in format
stop_type : result location for the GstSeekType of the stop position
stop : result location for the stop postion expressed in format

gst_event_new_navigation ()

GstEvent*   gst_event_new_navigation        (GstStructure *structure);

Create a new navigation event from the given description.

structure : description of the event
Returns : a new GstEvent

See Also

GstPad, GstElement