![]() |
![]() |
![]() |
GStreamer 0.9 Core Reference Manual | ![]() |
---|
GstEventGstEvent — Structure describing events that are passed up and down a pipeline |
#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);
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.
typedef struct { GstMiniObject mini_object; GstEventType type; guint64 timestamp; GstObject *src; GstStructure *structure; } GstEvent;
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. |
#define GST_EVENT_TRACE_NAME "GstEvent"
The name used for memory allocation tracing
#define GST_EVENT_TYPE(event) (GST_EVENT(event)->type)
Get the event type.
event : |
the event to query |
#define GST_EVENT_TIMESTAMP(event) (GST_EVENT(event)->timestamp)
Get the timestamp of the event.
event : |
the event to query |
#define GST_EVENT_SRC(event) (GST_EVENT(event)->src)
The source object that generated this event.
event : |
the event to query |
#define GST_EVENT_IS_DOWNSTREAM(ev) !!(GST_EVENT_TYPE (ev) & GST_EVDIR_DS)
ev : |
#define GST_EVENT_IS_SERIALIZED(ev) !!(GST_EVENT_TYPE (ev) & GST_EVSER)
ev : |
#define GST_EVENT_IS_UPSTREAM(ev) !!(GST_EVENT_TYPE (ev) & GST_EVDIR_US)
ev : |
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 |
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. |
#define GST_EVENT_MAKE_TYPE(num,flags) (((num) << GST_EVSHIFT) | (flags))
num : |
|
flags : |
#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 |
#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 |
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. |
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. |
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. |
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. |
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. |
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. |
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 |
GstEvent* gst_event_new_tag (GstTagList *taglist);
Generates a metadata tag event from the given taglist
.
taglist : |
metadata list |
Returns : | a new GstEvent |
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 |
GstEvent* gst_event_new_filler (void);
Create a new dummy event that should be ignored.
Returns : | a new GstEvent |
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. |
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 |
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. |
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
|
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 |
<< GstGError | GstFilter >> |